@danieljvdm/dev-kit 0.14.0 → 0.16.0

package/README.md

@@ -137,6 +137,7 @@ the root package itself.
 | `dev-kit gitignore`                        | Add `.repos/` and `.dev-kit/` to `.gitignore`.            |
 | `dev-kit effect sync`                      | Sync `.repos/effect` to the installed Effect version.     |
 | `dev-kit tsgo patch`                       | Validate and patch Effect TypeScript-Go directly.         |
+| `dev-kit cache prune`                      | Evict stale machine-global cache content (`--all` wipes). |
 | `dev-kit catalog refresh`                  | Maintainer command to approve current upstream refs.      |
 | `dev-kit catalog add <repository>`         | Inspect a repository and approve selected skills.         |
 | `dev-kit catalog remove <source-or-skill>` | Revoke an approval (`--yes` outside a terminal).          |
@@ -199,21 +200,15 @@ tool versions. A project-local process lock also prevents concurrent applies.
 ```
 
 - `dev-kit` installs guidance for operating the toolkit itself.
-- `open-pull-request` provides a conventional, context-complete PR workflow
-  with terse English descriptions and verified proof of work.
-- `effect` expands to the package-guidance `effect-ts` bootstrap, the
-  opinionated `effect-architecture-audit`, `build-effect-apis` for shared HTTP
-  contracts and clients, and `build-effect-clis` for typed command-line
-  applications, one-off scripts, and CI/deploy/build automation. The focused
-  references cover Effect Atom, TanStack Start, Cloudflare Workers, child
-  processes, runtime entrypoints, and script/CLI testing.
-- 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.
+- `effect` is a built-in family: the `effect-ts` bootstrap,
+  `effect-architecture-audit`, `build-effect-apis`, `effect-atom-state`, and
+  `build-effect-clis`.
+- External Git skills (`workers-best-practices`, `serve-sim`, …) are selected
+  individually after scanning the project for relevant technologies. An
+  approved source ID selects every skill from that source; use it only when
+  the scan confirms that every member applies.
 - `@tanstack/ai#ai-core` explicitly selects a skill discovered in that direct
   project dependency; discovery alone never selects it.
-- An approved source ID is broad shorthand that selects every skill from that
-  source. Use it only when the scan confirms that every member applies.
 
 Dev Kit reserves `.repos/<source-id>` for project-local source checkouts. Run
 `dev-kit gitignore` to add `.repos/` and `.dev-kit/` to the project ignore file.
@@ -239,18 +234,17 @@ bridge in the manifest:
 `AGENTS.md`, preserving handwritten project guidance around them. The Dev Kit
 section contains a short description and a pointer to the installed `dev-kit`
 skill. When the root `package.json` declares `vite-plus` directly, Dev Kit
-renders its own repository-specific Vite+ guidance, including the unified
-toolchain overview, help and documentation entry points, and `vp env doctor`
-troubleshooting. It does not import Vite+'s generic `AGENTS.md`, which can
-conflict with the repository's exact commands; transitive installations do not
-opt a project in. Previously managed Vite+ sections are removed during a safe
-owned update. Ambiguous or malformed managed markers fail closed.
+renders its own repository-specific Vite+ guidance — toolchain overview, help
+and documentation entry points, `vp env doctor` troubleshooting — rather than
+importing Vite+'s generic `AGENTS.md`, which can contradict the repository's
+exact commands; transitive installations do not opt a project in. Ambiguous or
+malformed managed markers fail closed.
 
 The Dev Kit section also renders an opinionated project command policy. A
 direct Vite+ dependency makes `vp` the only supported front door: built-in
 format, lint, and test commands use `vp`, while repository tasks and package
-scripts use `vp run`. When Dev Kit manages the quality config, the canonical
-full validation and typecheck commands are `vp run check` and
+scripts use `vp run`. When the manifest enables the Vite+ workflow scaffold,
+the canonical full validation and typecheck commands are `vp run check` and
 `vp run typecheck`; `vp check` alone is only the Vite+ static-check command.
 Without Vite+, Bun is the required package-script runner and Dev Kit lists only
 quality scripts the root package actually declares. The package manager named
@@ -291,7 +285,7 @@ worktree converges its own copy during install while the project-owned
 ## Vite+ quality setup
 
 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
+from that project-owned config, then opt into the scaffolded GitHub Actions
 workflow independently:
 
 ```ts
@@ -321,13 +315,6 @@ 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.
 
-Vite+ 0.2.6 forwards JavaScript-plugin declarations into its effective lint
-config but its bundled native Oxlint path does not register or execute those
-rules. Native Oxlint rules and Oxfmt settings remain active; run standalone
-Oxlint when enforcement of Dev Kit's `effect/*` or
-`stylistic/padding-line-between-statements` rules is required. This limitation
-can be removed once a supported Vite+ release executes configured JS plugins.
-
 ```jsonc
 {
   "include": ["dev-kit", "effect"],
@@ -335,19 +322,24 @@ can be removed once a supported Vite+ release executes configured JS plugins.
     "effectTsgo": { "enabled": true },
     "vitePlus": {
       "hooks": { "enabled": true },
-      "quality": {
-        "workflow": { "enabled": true },
-      },
+      "workflow": { "enabled": true },
     },
   },
 }
 ```
 
-`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.
+`setup.vitePlus.workflow` scaffolds `.github/workflows/check.yml` and never
+reads, rewrites, adopts, or removes `vite.config.ts`. Scaffolds are
+create-only: the file is written only when missing, never recorded in
+`dev-kit.lock.json`, and never touched again — the repository owns it from
+creation, and disabling the task leaves it in place. Edit the YAML directly
+for repository-specific preparation steps or a custom typecheck command; when
+the shipped template improves, compare against the installed copy under
+`node_modules/@danieljvdm/dev-kit/templates/` and merge what fits.
+Scaffolding requires direct `@danieljvdm/dev-kit`, `vite-plus`, `effect`,
+`@effect/tsgo`, and native TypeScript dependencies with
+`setup.effectTsgo.enabled`, and the installed Vite+ must satisfy Dev Kit's
+peer range.
 
 Workspaces select bounded, dependency-ordered typechecking in their config:
 
@@ -363,44 +355,98 @@ export default defineConfig(
 );
 ```
 
-Each listed package must expose a pure `typecheck` script. Repositories can
-also declare workflow-specific preparation and typecheck commands:
+Each listed package must expose a pure `typecheck` script.
+
+The scaffolded workflow performs one frozen, script-suppressed install, runs
+`dev-kit apply --locked`, and only then runs formatting, linting, tests, and
+`vp run typecheck`. 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
+templates.
+
+### Absolute (path-alias) imports
+
+Opt into enforcing path-alias imports for selected app sources. The factory
+appends an Oxlint override that errors on `../` imports inside the given
+globs, so those files import through tsconfig path aliases such as `@/*`:
+
+```ts
+export default defineConfig(
+  createRecommendedVitePlusConfig({
+    absoluteImports: {
+      files: ["apps/app/src/**/*.{ts,tsx}", "apps/mobile/src/**/*.{ts,tsx}"],
+    },
+  }),
+);
+```
+
+The lint rule only forbids relative parent imports; each covered app must map
+the alias itself. Add the `paths` entry to the app's `tsconfig.json`:
 
 ```jsonc
 {
+  "compilerOptions": {
+    "paths": { "@/*": ["./src/*"] },
+  },
+}
+```
+
+Vite-built apps also resolve the alias from the same tsconfig by setting
+`resolve: { tsconfigPaths: true }` in the app's Vite config. Expo apps need no
+Metro configuration: Expo SDK 49+ resolves tsconfig `paths` by default.
+
+Standalone Oxlint projects compose the same override directly:
+
+```ts
+// oxlint.config.ts
+import {
+  createAbsoluteImportsOxlintOverride,
+  recommendedOxlintConfig,
+} from "@danieljvdm/dev-kit/oxlint";
+import { defineConfig } from "oxlint";
+
+export default defineConfig({
+  extends: [recommendedOxlintConfig],
+  overrides: [createAbsoluteImportsOxlintOverride({ files: ["src/**/*.{ts,tsx}"] })],
+});
+```
+
+## Worktrunk project config
+
+Enable a scaffolded default [Worktrunk](https://worktrunk.dev) project config
+in the manifest:
+
+```jsonc
+{
+  "include": ["dev-kit"],
   "setup": {
-    "effectTsgo": { "enabled": true },
-    "vitePlus": {
-      "quality": {
-        "workflow": {
-          "enabled": true,
-          "beforeChecks": [
-            {
-              "name": "Install media tools",
-              "run": ["sudo apt-get update", "sudo apt-get install --yes ffmpeg"],
-            },
-          ],
-          "typecheck": [
-            "vp run -F './apps/*' -F './packages/*' check",
-            "vp exec tsc --noEmit -p scripts/tsconfig.json",
-          ],
-        },
-      },
-    },
+    "worktrunk": { "config": { "enabled": true } },
   },
 }
 ```
 
-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
-templates.
+`setup.worktrunk.config` scaffolds `.config/wt.toml` with the portable hooks an
+app repository wants in every worktree: a `pre-start` pipeline that copies
+gitignored files matched by `.worktreeinclude` (a no-op without that file) and
+then installs dependencies, plus a `pre-merge` full-validation hook. Hook
+commands render for the repository's command runner: a direct `vite-plus`
+dependency selects `vp install` and `vp run check`; otherwise Dev Kit requires
+a declared root `check` package script, runs it through `bun run check`, and
+takes the install command from the detected package manager. Repositories with
+neither fail the plan instead of shipping a broken hook.
+
+The config follows the same create-only scaffold semantics as the check
+workflow above: created once, never locked or touched again, owned by the
+repository. Edit hooks freely after creation.
+
+The config intentionally carries no worktree-path template or other user
+preferences—those belong in each user's `~/.config/worktrunk/config.toml`. A
+commented `post-start` block shows how to run a per-worktree dev server on a
+stable branch-derived port (`{{ branch | hash_port }}`) under `wt step tether`;
+point it at the repository's dev entrypoint and uncomment to opt in. Worktrunk
+never runs project hooks until each user approves them with
+`wt config approvals add`.
 
 ## Effect source checkout
 
@@ -416,9 +462,12 @@ Enable a local checkout of the exact installed Effect release in the manifest:
 ```
 
 `dev-kit apply` reads `node_modules/effect/package.json`, then shallow-clones or
-updates `.repos/effect` to the detached `effect@<version>` tag. It skips the
-checkout in CI, leaves the repository in place when the task is disabled, and
-refuses to switch a checkout with local changes or an unexpected origin.
+updates `.repos/effect` to the detached `effect@<version>` tag. Tag fetches go
+through a shared clone in the machine-global cache, so a new worktree or
+project reuses tags already cached on the machine and only contacts the
+network for a tag the cache has never seen. It skips the checkout in CI,
+leaves the repository in place when the task is disabled, and refuses to
+switch a checkout with local changes or an unexpected origin.
 
 The path, package name, and repository URL may be overridden for compatible
 Effect package layouts. Use `dev-kit effect sync --dry-run` to inspect this
@@ -522,31 +571,20 @@ 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, 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:
-
-- only packages named in the root project's `dependencies`,
-  `devDependencies`, `optionalDependencies`, or `peerDependencies` are
-  scanned;
-- package code is never imported or executed;
-- npm-style and pnpm/workspace symlinks under `node_modules` are supported;
-- Yarn Plug'n'Play and transitive dependency traversal are not scanned; and
-- immediate `skills/<name>/SKILL.md` roots are listed. Nested topic skills and
-  references remain part of that root and are copied with it.
-
-The last rule adapts Intent's routed, nested skill trees to the immediate folder
-and frontmatter-name invariants expected by Agent Skills targets. Dev Kit does
-not rewrite nested names or ask Intent to manage agent configuration.
+skill name, and the installed output carries it: the copied directory flattens
+the package name and appends the skill name (`@tanstack/ai#ai-core` →
+`tanstack-ai-ai-core`), and the copied `SKILL.md` frontmatter `name:` is
+rewritten to match because harnesses identify a skill by its directory name.
+Symlink-mode targets link straight into `node_modules`, so only the link
+carries the qualified name. Two selections that would write the same
+destination are rejected before any output changes.
+
+The compatibility boundary is intentionally small and deterministic: only the
+root project's direct dependencies are scanned, package code is never imported
+or executed, npm-style and pnpm/workspace symlinks are supported (Yarn
+Plug'n'Play and transitive traversal are not), and only immediate
+`skills/<name>/SKILL.md` roots are listed — nested topic skills and references
+are copied as part of their root.
 
 The project `dev-kit.lock.json` records the selected package name, installed
 version, original bare skill name, and the `node_modules` content digest.
@@ -601,9 +639,23 @@ names and paths, rejects symlinks and collisions, extracts descriptions, and
 updates `skill-sources.lock.json`.
 
 When a project selects one of these Git-backed skills, Dev Kit fetches the
-approved commit into the ignored `.dev-kit/cache` and installs it through the
-same ownership-safe sync path. Only a reviewed catalog refresh changes the
-approved Git content.
+approved commit into a machine-global cache and installs it through the same
+ownership-safe sync path. Cache entries are keyed by resolved commit SHA, so
+every project and git worktree on the machine shares one download; a warm
+`dev-kit plan` or `dev-kit apply` performs no network operations. The cache
+lives in `$XDG_CACHE_HOME/dev-kit` (falling back to `~/Library/Caches/dev-kit`
+on macOS and `~/.cache/dev-kit` elsewhere) and may be overridden with
+`DEV_KIT_CACHE_DIR`; it is safe to delete at any time. Populating this
+immutable commit-keyed cache is not project state, so planning and `--locked`
+verification use it too. Only a reviewed catalog refresh changes the approved
+Git content.
+
+The cache does not grow without bounds: every use refreshes a recency stamp,
+and `dev-kit apply` sweeps content unused for 30 days at most once a day.
+Shared Effect repositories drop unused tags individually and are removed whole
+once empty. Run `dev-kit cache prune` to sweep on demand (`--max-age-days` to
+tune the threshold, `--all` to clear the cache entirely); an evicted entry is
+simply fetched again the next time a project needs it.
 
 ## Oxlint and Oxfmt configurations
 
@@ -652,7 +704,11 @@ export default defineConfig({
 The Oxlint preset enables `stylistic/padding-line-between-statements`: adjacent
 variable declarations remain grouped, while the next logical statement and
 all `return` statements require a separating blank line. The rule is fixable,
-so `vp lint --fix` repairs missing spacing automatically.
+so `vp lint --fix` repairs missing spacing automatically. Vite+ 0.2.6 forwards
+the preset's JavaScript-plugin declarations but its native Oxlint path does not
+execute their rules — run standalone Oxlint when `effect/*` or the padding rule
+must be enforced, until a supported Vite+ release executes configured JS
+plugins.
 
 The preset also registers the shared `effect` JavaScript plugin. Effect
 projects opt into its rules in path-specific overrides, for example

package/dev-kit.example.jsonc

@@ -8,9 +8,10 @@
     "effectTsgo": { "enabled": true },
     "vitePlus": {
       "hooks": { "enabled": true },
-      "quality": {
-        "workflow": { "enabled": true },
-      },
+      "workflow": { "enabled": true },
+    },
+    "worktrunk": {
+      "config": { "enabled": true },
     },
   },
   "targets": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danieljvdm/dev-kit",
-  "version": "0.14.0",
+  "version": "0.16.0",
   "private": false,
   "description": "Declarative project development toolkit with portable agent skills.",
   "license": "MIT",

package/schema/dev-kit.schema.json

@@ -48,6 +48,9 @@
         },
         "vitePlus": {
           "$ref": "#/$defs/vitePlusSetup"
+        },
+        "worktrunk": {
+          "$ref": "#/$defs/worktrunkSetup"
         }
       },
       "default": {}
@@ -144,8 +147,8 @@
         "hooks": {
           "$ref": "#/$defs/vitePlusHooksSetup"
         },
-        "quality": {
-          "$ref": "#/$defs/vitePlusQualitySetup"
+        "workflow": {
+          "$ref": "#/$defs/vitePlusWorkflowSetup"
         }
       }
     },
@@ -160,61 +163,35 @@
         }
       }
     },
-    "vitePlusQualitySetup": {
-      "description": "Manage the Vite+ quality workflow while the repository owns and extends vite.config.ts.",
+    "vitePlusWorkflowSetup": {
+      "description": "Scaffold the canonical GitHub Actions check workflow (.github/workflows/check.yml); the repository owns the file after creation.",
       "type": "object",
       "additionalProperties": false,
       "properties": {
-        "workflow": {
-          "$ref": "#/$defs/vitePlusQualityWorkflowSetup"
+        "enabled": {
+          "type": "boolean",
+          "default": false
         }
       }
     },
-    "vitePlusQualityWorkflowSetup": {
-      "description": "Manage the canonical GitHub Actions check workflow without requiring Dev Kit to own the Vite config.",
+    "worktrunkSetup": {
+      "description": "Manage project-local Worktrunk setup tasks.",
       "type": "object",
       "additionalProperties": false,
       "properties": {
-        "enabled": {
-          "type": "boolean",
-          "default": false
-        },
-        "beforeChecks": {
-          "description": "Repository-specific preparation steps inserted after locked setup verification and before quality checks.",
-          "type": "array",
-          "items": {
-            "$ref": "#/$defs/vitePlusQualityWorkflowStep"
-          },
-          "default": []
-        },
-        "typecheck": {
-          "description": "Shell commands for the workflow's pure typecheck step.",
-          "type": "array",
-          "minItems": 1,
-          "items": {
-            "type": "string",
-            "minLength": 1
-          },
-          "default": ["vp run typecheck"]
+        "config": {
+          "$ref": "#/$defs/worktrunkConfigSetup"
         }
       }
     },
-    "vitePlusQualityWorkflowStep": {
+    "worktrunkConfigSetup": {
+      "description": "Scaffold the default Worktrunk project config (.config/wt.toml) with portable pre-start and pre-merge hooks rendered for the repository's command runner; the repository owns the file after creation.",
       "type": "object",
       "additionalProperties": false,
-      "required": ["name", "run"],
       "properties": {
-        "name": {
-          "type": "string",
-          "minLength": 1
-        },
-        "run": {
-          "type": "array",
-          "minItems": 1,
-          "items": {
-            "type": "string",
-            "minLength": 1
-          }
+        "enabled": {
+          "type": "boolean",
+          "default": false
         }
       }
     },

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

@@ -1,6 +1,6 @@
 ---
 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.
+description: Build contract-first Effect HTTP APIs. Use when defining shared HttpApiEndpoint/HttpApiGroup contracts, implementing HttpApiBuilder or HttpApiServer handlers and middleware, assembling server runtimes and OpenAPI docs, or serving on Cloudflare Workers/effect-cf. For consuming an API from client state, use $effect-atom-state.
 ---
 
 # Build Effect APIs
@@ -9,12 +9,11 @@ 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.
+Effect HTTP 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
 
@@ -31,35 +30,21 @@ from another version.
    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.
-
+4. Route consumer changes through the `$effect-atom-state` skill: deriving
+   `AtomHttpApi` or direct `HttpApiClient` clients, query and mutation atoms,
+   reactivity keys, and React integration all live there. 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.
+   round-trip, middleware failures use declared error channels, and server and
+   client agree on every request shape.
 
 ## 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.
@@ -94,6 +79,3 @@ but the boundary and type reasoning remain the source of truth.
 - 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/references/verification.md

@@ -48,9 +48,9 @@ decoding are skipped.
   `HttpApiMiddleware.layerClient` and assert that it transforms the request.
 - Assert params, query, headers, payload, and expected errors at least once for
   every changed request shape.
-- For Atom clients, complete every applicable scenario routed through
-  `effect-atom-testing.md`; use a deterministic HTTP layer so request encoding,
-  invalidation, and lifecycle remain observable.
+- For Atom clients, complete every applicable scenario in the
+  `$effect-atom-state` skill's testing reference; use a deterministic HTTP
+  layer so request encoding, invalidation, and lifecycle remain observable.
 
 ## Completion matrix