@danieljvdm/dev-kit 0.5.0 → 0.6.0

package/README.md

@@ -73,18 +73,33 @@ bun x dev-kit plan
 bun x dev-kit apply
 ```
 
-Commit the generated `dev-kit.lock.json`, then use locked mode in your package
-lifecycle:
+Commit the generated `dev-kit.lock.json`, then let the package lifecycle
+converge owned outputs automatically when installed packages change:
 
 ```jsonc
 {
   "scripts": {
-    "postinstall": "dev-kit apply --locked"
+    "postinstall": "dev-kit apply"
   }
 }
 ```
 
-That single postinstall applies every task enabled in `dev-kit.jsonc`.
+That single postinstall applies every task enabled in `dev-kit.jsonc` and
+regenerates `dev-kit.lock.json` when an intentional package upgrade changes a
+bundled or package-provided skill. Ownership and conflict checks still prevent
+unreviewed overwrites.
+
+Keep strict verification in CI. Either install with lifecycle scripts disabled
+before running locked mode:
+
+```bash
+bun install --ignore-scripts
+bun x dev-kit apply --locked
+```
+
+Or allow the normal postinstall and fail CI when it leaves tracked changes.
+Do not run an unlocked apply before a locked verification because that would
+regenerate the drift being checked.
 
 This repository dogfoods the same flow with its committed `dev-kit.jsonc` and
 `dev-kit.lock.json`. From this source checkout, invoke the local CLI with:
@@ -166,6 +181,7 @@ tool versions. A project-local process lock also prevents concurrent applies.
   ],
   "exclude": ["animation-vocabulary"],
   "setup": {
+    "agentInstructions": { "enabled": true },
     "claudeInstructions": { "enabled": true }
   },
   "targets": {
@@ -177,7 +193,8 @@ tool versions. A project-local process lock also prevents concurrent applies.
 ```
 
 - `dev-kit` installs guidance for operating the toolkit itself.
-- `effect` expands to the consolidated `effect-ts` skill.
+- `effect` expands to `effect-ts` plus focused Effect Atom HTTP data-fetching
+  guidance.
 - 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.
@@ -191,24 +208,33 @@ Dev Kit reserves `.repos/<source-id>` for project-local source checkouts. Run
 The patch is idempotent, preserves existing lines, and refuses symlinked
 `.gitignore` files.
 
-## Claude instructions
+## Agent instructions
 
-Enable a portable Claude Code instruction bridge in the manifest:
+Enable a managed project-root instruction wrapper and a portable Claude Code
+bridge in the manifest:
 
 ```jsonc
 {
-  "include": [],
+  "include": ["dev-kit"],
   "setup": {
+    "agentInstructions": { "enabled": true },
     "claudeInstructions": { "enabled": true }
   }
 }
 ```
 
-`dev-kit apply` requires a project-root `AGENTS.md`, then manages
-`CLAUDE.md` as the relative symlink `CLAUDE.md → AGENTS.md`. The link is
-recorded in the lockfile and local ownership state. Dev Kit refuses to replace
-an unowned `CLAUDE.md` and removes the link when the task is disabled only if
-the owned link is unchanged.
+`setup.agentInstructions` manages `AGENTS.md` as a generated wrapper with a
+short description of dev-kit and a pointer to the installed `dev-kit` skill.
+When the root `package.json` declares `vite-plus` directly, the wrapper also
+includes Vite+'s installed `node_modules/vite-plus/AGENTS.md` instructions.
+Transitive installations do not opt a project in.
+
+`setup.claudeInstructions` manages `CLAUDE.md` as the relative symlink
+`CLAUDE.md → AGENTS.md`. It can link to the generated wrapper in the same apply,
+or retain the older behavior of linking to an existing regular `AGENTS.md` when
+the wrapper task is disabled. Both outputs are recorded independently in the
+lockfile and local ownership state. Dev Kit refuses to replace unowned files
+and removes only unchanged owned outputs.
 
 ## Effect source checkout
 

package/dev-kit.example.jsonc

@@ -2,6 +2,7 @@
   "$schema": "./schema/dev-kit.schema.json",
   "include": ["dev-kit", "effect"],
   "setup": {
+    "agentInstructions": { "enabled": true },
     "claudeInstructions": { "enabled": true },
     "effectSource": { "enabled": true },
     "effectTsgo": { "enabled": true }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danieljvdm/dev-kit",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "private": false,
   "type": "module",
   "description": "Declarative project development toolkit with portable agent skills.",
@@ -40,7 +40,8 @@
     "skills/",
     "skill-sources.jsonc",
     "skill-sources.lock.json",
-    "src/"
+    "src/",
+    "templates/"
   ],
   "scripts": {
     "prepare": "./bin/dev-kit.mjs apply --locked",

package/schema/dev-kit.schema.json

@@ -34,6 +34,9 @@
       "type": "object",
       "additionalProperties": false,
       "properties": {
+        "agentInstructions": {
+          "$ref": "#/$defs/agentInstructionsSetup"
+        },
         "claudeInstructions": {
           "$ref": "#/$defs/claudeInstructionsSetup"
         },
@@ -61,6 +64,17 @@
   },
   "required": ["include"],
   "$defs": {
+    "agentInstructionsSetup": {
+      "description": "Manage a project-root AGENTS.md wrapper with dev-kit guidance and conditional tool instructions.",
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "enabled": {
+          "type": "boolean",
+          "default": false
+        }
+      }
+    },
     "claudeInstructionsSetup": {
       "description": "Manage CLAUDE.md as a relative symlink to the project-root AGENTS.md file.",
       "type": "object",

package/skills/dev-kit/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: dev-kit
-description: Dev-kit operations for projects that configure dev-kit.jsonc, sync portable skills, run plan/apply or locked postinstalls, maintain dev-kit.lock.json, resolve ownership conflicts, patch managed ignores, or enable Effect TypeScript-Go.
+description: Dev-kit operations for projects that configure dev-kit.jsonc, sync portable skills, run plan/apply or automatic postinstalls, perform locked CI checks, maintain dev-kit.lock.json, resolve ownership conflicts, patch managed ignores, or enable Effect TypeScript-Go.
 ---
 
 # Dev Kit
@@ -51,8 +51,12 @@ stores explicit skill names and exact commit/content digests.
 6. Resolve conflicts, then run `dev-kit apply`. Commit the manifest and
    regenerated `dev-kit.lock.json`; keep `.dev-kit/` local. Finish when a second
    plan reports only unchanged resources and setup tasks.
-7. Use `dev-kit apply --locked` in CI and the package lifecycle. Finish when a
-   clean install converges from the committed manifest and lock.
+7. Use `dev-kit apply` in the package lifecycle so intentional dependency
+   upgrades regenerate owned outputs and `dev-kit.lock.json`. For strict CI,
+   either disable lifecycle scripts before `dev-kit apply --locked`, or run the
+   normal lifecycle and require the tracked working tree to remain clean. Never
+   run an unlocked apply before locked verification. Finish when a clean install
+   converges from the committed manifest and lock.
 
 ## Manifest
 
@@ -68,6 +72,7 @@ skill as `dev-kit` when project agents should carry the toolkit procedure.
   "include": ["dev-kit", "effect"],
   "exclude": [],
   "setup": {
+    "agentInstructions": { "enabled": true },
     "claudeInstructions": { "enabled": true }
   },
   "targets": {
@@ -83,11 +88,14 @@ use symlinks for additional harness discovery paths. Keep every target path
 project-relative and separate from the manifest, lock, state, and process-lock
 paths.
 
+Enable `setup.agentInstructions` to manage a project-root `AGENTS.md` wrapper
+that points agents back to this skill. When `vite-plus` is a declared direct
+dependency, dev-kit includes its installed agent instructions in the wrapper.
 Enable `setup.claudeInstructions` when Claude Code should consume the same
-project-root instructions as Codex. It manages `CLAUDE.md` as a relative
-symlink to an existing `AGENTS.md`. Preserve any conflicting `CLAUDE.md`; when
-disabled, dev-kit removes only an unchanged link recorded in local ownership
-state.
+project-root instructions; it manages `CLAUDE.md` as a relative symlink to the
+wrapper or to an existing regular `AGENTS.md`. Preserve conflicting paths;
+when disabled, dev-kit removes only unchanged outputs recorded in local
+ownership state.
 
 ## Ownership and conflicts
 
@@ -118,11 +126,17 @@ For one lifecycle entry point, configure:
 ```jsonc
 {
   "scripts": {
-    "postinstall": "dev-kit apply --locked"
+    "postinstall": "dev-kit apply"
   }
 }
 ```
 
+This intentionally refreshes the committed lock and owned outputs when the
+package manager installs a new Dev Kit or selected package-skill version.
+Review and commit those changes with the dependency update. Keep
+`dev-kit apply --locked` as a verification command, not the normal local
+lifecycle; in CI, run it only before any unlocked apply.
+
 ## Effect source checkout
 
 Enable the source task when agents should have canonical source matching the
@@ -204,7 +218,8 @@ in the consuming project.
 
 ## Current boundary
 
-Manage skill outputs, the `setup.claudeInstructions` link, the
+Manage skill outputs, the `setup.agentInstructions` wrapper, the
+`setup.claudeInstructions` link, the
 `setup.effectSource` checkout, and the explicit `setup.effectTsgo` task. Edit
 shared `package.json` and `tsconfig.json`
 contributions deliberately. The Oxlint and Oxfmt configurations are composable

package/skills/effect-atom-data-fetching/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: effect-atom-data-fetching
+description: Design, implement, debug, or review HTTP data fetching with Effect Atom in React applications. Use for AtomHttpApi.Service queries and mutations, parameterized Atom.family caches, RegistryProvider and runtime placement, TTL/SWR/polling behavior, reactivity-key invalidation, framework-appropriate SSR and focus handling, AsyncResult aggregation resets, and deterministic cache lifecycle tests.
+---
+
+# Effect Atom Data Fetching
+
+Model server data as stable atoms owned outside React renders. Give the application one intentional registry boundary and one compatible runtime factory; then choose cache retention, freshness, polling, and invalidation independently.
+
+## Workflow
+
+1. Inspect the installed `effect` and `@effect/atom-react` versions and their source before copying signatures. These APIs live under `effect/unstable/reactivity` and may move.
+2. Locate every `RegistryProvider`, runtime factory, query atom, mutation atom, and route-level `AsyncResult.all`. Draw the ownership boundary before changing behavior.
+3. Keep one `RegistryProvider` for the intended client application lifetime. Define the shared runtime factory, API service, query families, and mutation atoms at module scope rather than in components.
+4. Choose each lifecycle control for its actual job:
+   - idle `timeToLive`: retain an unused registry value before disposal;
+   - `Atom.swr({ staleTime })`: decide when mount/focus revalidation is needed;
+   - `Atom.withRefresh`: force periodic refresh while mounted.
+5. Give queries stable identities and matching reactivity keys. Let successful mutations invalidate those keys rather than manually coordinating every consumer.
+6. Keep browser-only signals behind an SSR-safe boundary. Decide explicitly whether initial data is client-only or hydrated from a request-scoped server registry.
+7. Verify lifecycle behavior with fake time and request counters, not sleeps.
+
+## Ownership rules
+
+- Treat a query as shared read state: export one atom or `Atom.family` and let components subscribe.
+- Treat an action as an event owned by the initiating UI or workflow: export the mutation atom, invoke it with `useAtomSet`, and observe its result only where useful.
+- Never allocate a query atom in render. For parameterized queries, use a stable scalar or Effect `Hash`/`Equal` value as the family argument.
+- Ensure every input to a route-level `AsyncResult.all` has stable atom identity and compatible retention. One newly allocated or immediately evicted input returns to `Initial` and makes the whole aggregate appear reset even when the other inputs remain cached.
+- Do not describe manual refresh or polling as freshness caching. Refresh is forceful; `staleTime` only gates SWR's automatic mount/focus decisions.
+
+## References
+
+- Read `./references/cache-lifecycle.md` for registry scope, runtime memoization, families, TTL, SWR, polling, and the aggregation trap.
+- Read `./references/http-and-invalidation.md` for `AtomHttpApi.Service`, query/mutation ownership, reactivity-key vocabulary, and invalidation.
+- Read `./references/tanstack-start.md` only for its framework-specific provider placement, SSR isolation, hydration, and focus guidance.
+- Read `./references/testing.md` when adding or diagnosing lifecycle tests.
+
+## Completion check
+
+Confirm one registry boundary, stable atom identity, deliberate TTL/staleness/polling values, matching query and mutation keys, SSR-safe browser access, and tests for every lifecycle behavior changed.

package/skills/effect-atom-data-fetching/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Effect Atom Data Fetching"
+  short_description: "Cache HTTP data safely with Effect Atom"
+  default_prompt: "Use $effect-atom-data-fetching to design or debug Effect Atom HTTP queries, caching, polling, invalidation, and SSR integration in a React app."

package/skills/effect-atom-data-fetching/references/cache-lifecycle.md

@@ -0,0 +1,72 @@
+# 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.
+
+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-atom-data-fetching/references/http-and-invalidation.md

@@ -0,0 +1,93 @@
+# 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.
+
+## 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.

package/skills/effect-atom-data-fetching/references/tanstack-start.md

@@ -0,0 +1,69 @@
+# TanStack Start integration
+
+TanStack Start code is isomorphic by default, including route loaders. Treat every module used by a route as server-capable unless an explicit boundary says otherwise.
+
+## Choose an SSR strategy
+
+Use one of these models deliberately:
+
+### Client-only atom data
+
+- Put one `RegistryProvider` in the app/root component so client navigations share a registry.
+- Render atom consumers that touch browser-only APIs inside `ClientOnly` from `@tanstack/react-router`.
+- Accept that the fallback is the server-rendered state and fetching begins on the client.
+- Keep the client runtime and API service as module singletons.
+
+```tsx
+import { RegistryProvider } from "@effect/atom-react";
+import { ClientOnly } from "@tanstack/react-router";
+
+export function AppShell() {
+  return (
+    <RegistryProvider defaultIdleTTL={30_000}>
+      <ClientOnly fallback={<DashboardSkeleton />}>
+        <Dashboard />
+      </ClientOnly>
+    </RegistryProvider>
+  );
+}
+```
+
+### SSR plus hydration
+
+- Create the registry and any request-specific runtime/layers per request; never share user/auth state through a process-global registry or memo map.
+- Give decoded query atoms deterministic `serializationKey` values.
+- Mount/run the required serializable atoms on the server, dehydrate only the intended values, and pass them through the document safely.
+- Create the client registry once, then hydrate matching atom identities before descendants consume them. Use `HydrationBoundary` where the installed React adapter supports it.
+- Verify that server and client construct the same API service, family arguments, and serialization keys.
+
+Prefer framework loaders/server functions when they already own SSR data. Do not build a second atom SSR cache merely to mirror loader data; seed atoms from the loader or keep atom fetching client-only.
+
+## Focus is browser-only
+
+`Atom.windowFocusSignal` reads `window` and `document.visibilityState` when mounted. Do not mount it during SSR. Put focus-enabled consumers behind `ClientOnly`, or inject a no-op server signal and the browser signal on the client.
+
+```ts
+const project = projectAtom(projectId).pipe(
+  Atom.swr({
+    staleTime: "30 seconds",
+    revalidateOnFocus: true,
+    focusSignal: Atom.windowFocusSignal,
+  }),
+);
+```
+
+`revalidateOnFocus: true` respects `staleTime`; `"always"` forces a request on every focus signal.
+
+## In-memory limits
+
+Effect Atom's registry cache is in memory and scoped to that registry:
+
+- a new tab, hard reload, server process, or newly created provider starts another cache;
+- idle TTL evicts only unused atoms and is not a maximum-entry or byte-size bound;
+- `keepAlive` and infinite TTL can grow memory with unbounded family keys;
+- browser memory is not durable or shared across users/devices;
+- hydration transfers a snapshot, not a persistent distributed cache.
+
+For large or unbounded parameter spaces, use finite TTLs and avoid `keepAlive`. Put durable/shared caching at the HTTP, server, CDN, or database layer.
+
+Primary TanStack references: [execution model](https://tanstack.com/start/latest/docs/framework/react/guide/execution-model) and [`ClientOnly`](https://tanstack.com/router/latest/docs/api/router/clientOnlyComponent).

package/skills/effect-atom-data-fetching/references/testing.md

@@ -0,0 +1,63 @@
+# Deterministic lifecycle testing
+
+Test cache policy below React first with `AtomRegistry.make()`. Add a React integration test only for provider placement, hook behavior, a browser-only SSR boundary, or hydration.
+
+Use fake timers, a request counter, controllable Effects, and explicit mounts:
+
+```ts
+const registry = AtomRegistry.make({ defaultIdleTTL: 1_000 });
+const unmount = registry.mount(queryAtom);
+const first = registry.get(queryAtom);
+
+// Advance the Effect scheduler/microtasks as required by the installed version.
+// Assert with AsyncResult predicates and request counts.
+
+unmount();
+```
+
+Avoid wall-clock sleeps. Flush Effect work with the repository's established `Effect.yieldNow`/test-clock pattern and advance the test runner's fake timers.
+
+Prefer the installed test APIs over invented helpers or matchers. The upstream Effect tests use `assert(AsyncResult.isSuccess(result))`, `Effect.runPromise(Effect.yieldNow)`, `vitest.advanceTimersByTimeAsync(...)`, and the cleanup returned by `registry.mount(atom)`.
+
+## Required scenarios
+
+### Remount reuse
+
+1. Mount and resolve the query; assert request count `1`.
+2. Unmount, advance less than idle TTL, remount the same atom identity.
+3. Assert the cached success is immediately available and no request occurs while still fresh.
+
+### Stale refresh
+
+1. Resolve once through an SWR wrapper.
+2. Advance past `staleTime` but not idle TTL.
+3. Remount or emit the injected focus signal.
+4. Assert the previous success stays available with `waiting: true`, then a second success arrives and request count becomes `2`.
+5. Also prove a fresh mount/focus does not request.
+
+### TTL eviction
+
+1. Resolve and unmount.
+2. Advance to just before TTL; assert reuse.
+3. Advance to/after TTL and flush disposal; remount.
+4. Assert `Initial`/waiting behavior and a new request.
+
+### Polling cleanup
+
+1. Mount the `Atom.withRefresh` wrapper and resolve once.
+2. Advance one interval; assert one forced refresh.
+3. Unmount and advance several intervals.
+4. Assert the counter does not change. This catches leaked timers or accidental `keepAlive`.
+
+### Mutation invalidation
+
+1. Mount list and detail queries with explicit keys.
+2. Run a successful mutation with matching keys; assert only the intended queries refresh.
+3. Run a failed mutation; assert no invalidation.
+4. Assert cleanup removes invalidation handlers after query disposal.
+
+### Aggregate stability
+
+Mount a route atom that uses `AsyncResult.all`, resolve every input, unmount, and remount inside the retention window. Assert the aggregate never returns to `Initial`. Then let one input expire and prove the aggregate reset is caused by that input, not the retained queries.
+
+For runtime/layer tests, seed `runtime.layer` through `RegistryProvider initialValues` with a deterministic test layer. This replaces network services without changing the production atom graph.

package/src/catalog.ts

@@ -167,7 +167,7 @@ export const loadSkillCatalog = Effect.fn("loadSkillCatalog")(function* (
     });
   }
   const families: Readonly<Record<string, ReadonlyArray<string>>> = {
-    effect: ["effect-ts"],
+    effect: ["effect-ts", "effect-atom-data-fetching"],
     ...Object.fromEntries(externalFamilies),
   };
   return {

package/src/index.ts

@@ -1,4 +1,6 @@
 export {
+  type AgentInstructionsSetup,
+  AgentInstructionsSetupSchema,
   type ClaudeInstructionsSetup,
   ClaudeInstructionsSetupSchema,
   type DevKitManifest,
@@ -64,6 +66,8 @@ export {
   DevKitLockSchema,
   EffectSourceLockSchema,
   EffectTsgoLockSchema,
+  ManagedAgentInstructionsOutputSchema,
+  ManagedClaudeInstructionsOutputSchema,
   ManagedInstructionOutputSchema,
   ManagedOutputSchema,
   ManagedSkillOutputSchema,
@@ -73,6 +77,8 @@ export {
   type DevKitLock,
   type EffectSourceLock,
   type EffectTsgoLock,
+  type ManagedAgentInstructionsOutput,
+  type ManagedClaudeInstructionsOutput,
   type ManagedInstructionOutput,
   type ManagedOutput,
   type ManagedSkillOutput,

package/src/manifest.ts

@@ -37,6 +37,12 @@ export const EffectSourceSetupSchema = Schema.Struct({
 
 export type EffectSourceSetup = typeof EffectSourceSetupSchema.Type;
 
+export const AgentInstructionsSetupSchema = Schema.Struct({
+  enabled: Schema.optional(Schema.Boolean),
+});
+
+export type AgentInstructionsSetup = typeof AgentInstructionsSetupSchema.Type;
+
 export const ClaudeInstructionsSetupSchema = Schema.Struct({
   enabled: Schema.optional(Schema.Boolean),
 });
@@ -49,6 +55,7 @@ export const DevKitManifestSchema = Schema.Struct({
   exclude: Schema.optional(Schema.Array(Schema.String.check(Schema.isPattern(SKILL_SELECTOR_PATTERN)))),
   setup: Schema.optional(
     Schema.Struct({
+      agentInstructions: Schema.optional(AgentInstructionsSetupSchema),
       claudeInstructions: Schema.optional(ClaudeInstructionsSetupSchema),
       effectSource: Schema.optional(EffectSourceSetupSchema),
       effectTsgo: Schema.optional(EffectTsgoSetupSchema),
@@ -75,6 +82,9 @@ export type NormalizedManifest = {
   readonly include: ReadonlyArray<string>;
   readonly exclude: ReadonlyArray<string>;
   readonly setup: {
+    readonly agentInstructions: {
+      readonly enabled: boolean;
+    };
     readonly claudeInstructions: {
       readonly enabled: boolean;
     };
@@ -125,6 +135,9 @@ export const normalizeManifest = (manifest: DevKitManifest): NormalizedManifest
     exclude: manifest.exclude ?? [],
     include: manifest.include,
     setup: {
+      agentInstructions: {
+        enabled: manifest.setup?.agentInstructions?.enabled ?? false,
+      },
       claudeInstructions: {
         enabled: manifest.setup?.claudeInstructions?.enabled ?? false,
       },

package/src/package-skill-source.ts

@@ -1,6 +1,7 @@
 import { Effect, FileSystem, Path, Result, Schema } from "effect";
 
 import { observeSymbolicLink } from "./node-symbolic-link.ts";
+import { readDirectDependencyNames } from "./project-package.ts";
 import { isSkillName, parseSkillSelector } from "./skill-selector.ts";
 import { isTypeScriptPackageName } from "./typescript-package-name.ts";
 
@@ -24,13 +25,6 @@ export type DiscoveredPackageSkill = {
   readonly linkPath: string;
 };
 
-const ProjectPackageSchema = Schema.fromJsonString(Schema.Struct({
-  dependencies: Schema.optional(Schema.Record(Schema.String, Schema.String)),
-  devDependencies: Schema.optional(Schema.Record(Schema.String, Schema.String)),
-  optionalDependencies: Schema.optional(Schema.Record(Schema.String, Schema.String)),
-  peerDependencies: Schema.optional(Schema.Record(Schema.String, Schema.String)),
-}));
-
 const PackageMetadataSchema = Schema.fromJsonString(Schema.Struct({
   name: Schema.String,
   version: Schema.String,
@@ -114,22 +108,6 @@ const rejectNestedSymlinks = Effect.fn("rejectPackageSkillSymlinks")(function* (
   }
 });
 
-const readDirectDependencyNames = Effect.fn("readDirectPackageSkillDependencyNames")(function* (projectDir: string) {
-  const fs = yield* FileSystem.FileSystem;
-  const path = yield* Path.Path;
-  const manifestPath = path.join(projectDir, "package.json");
-  const manifest = yield* fs.readFileString(manifestPath).pipe(
-    Effect.flatMap(Schema.decodeUnknownEffect(ProjectPackageSchema)),
-    Effect.mapError(() => new PackageSkillSourceError({ message: `invalid project package.json: ${manifestPath}` })),
-  );
-  return [...new Set([
-    ...Object.keys(manifest.dependencies ?? {}),
-    ...Object.keys(manifest.devDependencies ?? {}),
-    ...Object.keys(manifest.optionalDependencies ?? {}),
-    ...Object.keys(manifest.peerDependencies ?? {}),
-  ])].sort();
-});
-
 type InstalledPackageSkills = {
   readonly package: string;
   readonly version: string;

package/src/path-digest.ts

@@ -135,6 +135,13 @@ export const digestText = Effect.fn("digestText")(function* (value: string) {
   return yield* digestFrames(["text-v1", value]);
 });
 
+export const digestFileContent = Effect.fn("digestFileContent")(function* (
+  value: string,
+  mode = 0o644,
+) {
+  return yield* digestFrames(["file-v1", String(mode), value]);
+});
+
 export const digestSymlinkTarget = Effect.fn("digestSymlinkTarget")(function* (target: string) {
   return yield* digestFrames(["symlink-v1", target]);
 });

package/src/project-package.ts

@@ -0,0 +1,34 @@
+import { Effect, FileSystem, Path, Schema } from "effect";
+
+export class ProjectPackageError extends Schema.TaggedErrorClass<ProjectPackageError>()(
+  "ProjectPackageError",
+  { message: Schema.String },
+) {}
+
+const ProjectPackageSchema = Schema.fromJsonString(Schema.Struct({
+  dependencies: Schema.optional(Schema.Record(Schema.String, Schema.String)),
+  devDependencies: Schema.optional(Schema.Record(Schema.String, Schema.String)),
+  optionalDependencies: Schema.optional(Schema.Record(Schema.String, Schema.String)),
+  peerDependencies: Schema.optional(Schema.Record(Schema.String, Schema.String)),
+}));
+
+export const readDirectDependencyNames = Effect.fn("readDirectDependencyNames")(function* (
+  projectDir: string,
+) {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const manifestPath = path.join(projectDir, "package.json");
+  if (!(yield* fs.exists(manifestPath))) return [];
+  const manifest = yield* fs.readFileString(manifestPath).pipe(
+    Effect.flatMap(Schema.decodeUnknownEffect(ProjectPackageSchema)),
+    Effect.mapError(() => new ProjectPackageError({
+      message: `invalid project package.json: ${manifestPath}`,
+    })),
+  );
+  return [...new Set([
+    ...Object.keys(manifest.dependencies ?? {}),
+    ...Object.keys(manifest.devDependencies ?? {}),
+    ...Object.keys(manifest.optionalDependencies ?? {}),
+    ...Object.keys(manifest.peerDependencies ?? {}),
+  ])].sort();
+});

package/src/project-state.ts

@@ -29,7 +29,17 @@ export const ManagedSkillOutputSchema = Schema.Struct({
 });
 export type ManagedSkillOutput = typeof ManagedSkillOutputSchema.Type;
 
-export const ManagedInstructionOutputSchema = Schema.Struct({
+export const ManagedAgentInstructionsOutputSchema = Schema.Struct({
+  resourceId: Schema.Literal("setup:agent-instructions"),
+  path: Schema.String,
+  sourcePath: Schema.String,
+  mode: Schema.Literal("copy"),
+  kind: Schema.Literal("file"),
+  digest: DigestSchema,
+});
+export type ManagedAgentInstructionsOutput = typeof ManagedAgentInstructionsOutputSchema.Type;
+
+export const ManagedClaudeInstructionsOutputSchema = Schema.Struct({
   resourceId: Schema.Literal("setup:claude-instructions"),
   path: Schema.String,
   sourcePath: Schema.String,
@@ -37,6 +47,12 @@ export const ManagedInstructionOutputSchema = Schema.Struct({
   kind: Schema.Literal("symlink"),
   digest: DigestSchema,
 });
+export type ManagedClaudeInstructionsOutput = typeof ManagedClaudeInstructionsOutputSchema.Type;
+
+export const ManagedInstructionOutputSchema = Schema.Union([
+  ManagedAgentInstructionsOutputSchema,
+  ManagedClaudeInstructionsOutputSchema,
+]);
 export type ManagedInstructionOutput = typeof ManagedInstructionOutputSchema.Type;
 
 export const ManagedOutputSchema = Schema.Union([
@@ -79,7 +95,7 @@ export const OwnershipReceiptSchema = Schema.Struct({
   resourceId: Schema.String,
   path: Schema.String,
   mode: Schema.Literals(["copy", "symlink"]),
-  kind: Schema.Literals(["directory", "symlink"]),
+  kind: Schema.Literals(["file", "directory", "symlink"]),
   digest: DigestSchema,
 });
 export type OwnershipReceipt = typeof OwnershipReceiptSchema.Type;

package/src/sync.ts

@@ -21,19 +21,22 @@ import {
   type EffectTsgoPatchPlan,
 } from "./effect-tsgo.ts";
 import {
+  digestFileContent,
   digestSymlinkTarget,
   digestText,
   observePath,
   type ObservedPath,
 } from "./path-digest.ts";
 import { resolvePackageSkillSelector } from "./package-skill-source.ts";
+import { readDirectDependencyNames } from "./project-package.ts";
 import { parseSkillSelector } from "./skill-selector.ts";
 import {
   AppliedStateSchema,
   DevKitLockSchema,
   type AppliedState,
   type DevKitLock,
-  type ManagedInstructionOutput,
+  type ManagedAgentInstructionsOutput,
+  type ManagedClaudeInstructionsOutput,
   type ManagedOutput,
   type ManagedSkillOutput,
   type OwnershipReceipt,
@@ -76,12 +79,20 @@ type DesiredSkillOutput =
       readonly linkTarget: string;
     });
 
-type DesiredInstructionOutput = ManagedInstructionOutput & {
+type DesiredAgentInstructionsOutput = ManagedAgentInstructionsOutput & {
+  readonly content: string;
+  readonly destination: string;
+};
+
+type DesiredClaudeInstructionsOutput = ManagedClaudeInstructionsOutput & {
   readonly destination: string;
   readonly linkTarget: string;
 };
 
-type DesiredOutput = DesiredSkillOutput | DesiredInstructionOutput;
+type DesiredOutput =
+  | DesiredSkillOutput
+  | DesiredAgentInstructionsOutput
+  | DesiredClaudeInstructionsOutput;
 
 type SkillPlanAction =
   | {
@@ -196,10 +207,14 @@ class ApplyRaceError extends Schema.TaggedErrorClass<ApplyRaceError>()("ApplyRac
   }
 }
 
-const SKILL_FAMILIES: SkillCatalog = { effect: ["effect-ts"] };
+const SKILL_FAMILIES: SkillCatalog = {
+  effect: ["effect-ts", "effect-atom-data-fetching"],
+};
 export const DEFAULT_MANIFEST = "dev-kit.jsonc";
 const DEFAULT_LOCKFILE = "dev-kit.lock.json";
 const DEFAULT_STATE = ".dev-kit/state.json";
+const AGENT_INSTRUCTIONS_TEMPLATE = "templates/AGENTS.md";
+const DEV_KIT_SKILL_PATH_PLACEHOLDER = "{{DEV_KIT_SKILL_PATH}}";
 
 const resolvePackageRoot = Effect.fn("resolvePackageRoot")(function* () {
   const path = yield* Path.Path;
@@ -421,7 +436,51 @@ const validateCrossInventoryPaths = Effect.fn("validateCrossInventoryPaths")(fun
   }
 });
 
+const renderAgentInstructions = Effect.fn("renderAgentInstructions")(function* (
+  packageRoot: string,
+  projectDir: string,
+  sourceBySkill: ReadonlyMap<string, ResolvedSkillSource>,
+) {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const templatePath = path.join(packageRoot, AGENT_INSTRUCTIONS_TEMPLATE);
+  if ((yield* observePath(templatePath)).kind !== "file") {
+    return yield* new InvalidProjectStateError({
+      message: `dev-kit agent instructions template is not a regular file: ${AGENT_INSTRUCTIONS_TEMPLATE}`,
+    });
+  }
+  const template = yield* fs.readFileString(templatePath);
+  if (!template.includes(DEV_KIT_SKILL_PATH_PLACEHOLDER)) {
+    return yield* new InvalidProjectStateError({
+      message: `dev-kit agent instructions template is missing ${DEV_KIT_SKILL_PATH_PLACEHOLDER}`,
+    });
+  }
+
+  const devKitSkill = sourceBySkill.get("dev-kit");
+  const devKitSkillPath = devKitSkill === undefined
+    ? "node_modules/@danieljvdm/dev-kit/skills/dev-kit/SKILL.md"
+    : portablePath(
+        path,
+        path.relative(
+          projectDir,
+          path.join(devKitSkill.linkPath ?? devKitSkill.path, "SKILL.md"),
+        ),
+      );
+  const sections = [template.replaceAll(DEV_KIT_SKILL_PATH_PLACEHOLDER, devKitSkillPath).trimEnd()];
+  if ((yield* readDirectDependencyNames(projectDir)).includes("vite-plus")) {
+    const vitePlusTemplate = path.join(projectDir, "node_modules", "vite-plus", "AGENTS.md");
+    if ((yield* observePath(vitePlusTemplate)).kind !== "file") {
+      return yield* new InvalidProjectStateError({
+        message: "Vite+ is a direct dependency but its agent instructions are not a regular file: node_modules/vite-plus/AGENTS.md",
+      });
+    }
+    sections.push((yield* fs.readFileString(vitePlusTemplate)).trim());
+  }
+  return `${sections.join("\n\n")}\n`;
+});
+
 const buildDesiredOutputs = Effect.fn("buildDesiredSkillOutputs")(function* (
+  packageRoot: string,
   projectDir: string,
   sourceBySkill: ReadonlyMap<string, ResolvedSkillSource>,
   skills: ReadonlyArray<CatalogSkill>,
@@ -430,10 +489,26 @@ const buildDesiredOutputs = Effect.fn("buildDesiredSkillOutputs")(function* (
 ) {
   const path = yield* Path.Path;
   const outputs: Array<DesiredOutput> = [];
+  if (setup.agentInstructions.enabled) {
+    const managed = yield* resolveManagedPath(projectDir, "AGENTS.md");
+    const content = yield* renderAgentInstructions(packageRoot, projectDir, sourceBySkill);
+    outputs.push({
+      resourceId: "setup:agent-instructions",
+      path: managed.relative,
+      sourcePath: AGENT_INSTRUCTIONS_TEMPLATE,
+      mode: "copy",
+      kind: "file",
+      digest: yield* digestFileContent(content),
+      destination: managed.absolute,
+      content,
+    });
+  }
   if (setup.claudeInstructions.enabled) {
     const source = yield* resolveManagedPath(projectDir, "AGENTS.md");
-    const sourceObservation = yield* observePath(source.absolute);
-    if (sourceObservation.kind !== "file") {
+    const sourceObservation = setup.agentInstructions.enabled
+      ? undefined
+      : yield* observePath(source.absolute);
+    if (!setup.agentInstructions.enabled && sourceObservation?.kind !== "file") {
       return yield* new InvalidProjectStateError({
         message: "Claude instructions source is not a regular file: AGENTS.md",
       });
@@ -673,6 +748,7 @@ export const planProjectSkills = Effect.fn("planProjectSkills")(function* (optio
     selectedSkills.push(catalogSkill);
   }
   const desired = yield* buildDesiredOutputs(
+    packageRoot,
     projectDir,
     sourceBySkill,
     selectedSkills,
@@ -705,27 +781,38 @@ export const planProjectSkills = Effect.fn("planProjectSkills")(function* (optio
             },
           }),
     },
-    outputs: desired.map((output): ManagedOutput =>
-      "skill" in output
-        ? {
-            resourceId: output.resourceId,
-            path: output.path,
-            skill: output.skill,
-            target: output.target,
-            mode: output.mode,
-            kind: output.kind,
-            digest: output.digest,
-            ...(output.catalog ? { catalog: output.catalog } : {}),
-          }
-        : {
-            resourceId: output.resourceId,
-            path: output.path,
-            sourcePath: output.sourcePath,
-            mode: output.mode,
-            kind: output.kind,
-            digest: output.digest,
-          },
-    ),
+    outputs: desired.map((output): ManagedOutput => {
+      if ("skill" in output) {
+        return {
+          resourceId: output.resourceId,
+          path: output.path,
+          skill: output.skill,
+          target: output.target,
+          mode: output.mode,
+          kind: output.kind,
+          digest: output.digest,
+          ...(output.catalog ? { catalog: output.catalog } : {}),
+        };
+      }
+      if (output.resourceId === "setup:agent-instructions") {
+        return {
+          resourceId: output.resourceId,
+          path: output.path,
+          sourcePath: output.sourcePath,
+          mode: output.mode,
+          kind: output.kind,
+          digest: output.digest,
+        };
+      }
+      return {
+        resourceId: output.resourceId,
+        path: output.path,
+        sourcePath: output.sourcePath,
+        mode: output.mode,
+        kind: output.kind,
+        digest: output.digest,
+      };
+    }),
   };
   const reservedPaths = [
     { label: "manifest", path: manifestManaged.relative },
@@ -739,6 +826,17 @@ export const planProjectSkills = Effect.fn("planProjectSkills")(function* (optio
   yield* validateReservedPaths(projectDir, reservedPaths, desired);
   const currentLock = yield* readOptionalStructuredFile(lockManaged.absolute, DevKitLockSchema);
   const currentState = yield* readOptionalStructuredFile(stateManaged.absolute, AppliedStateSchema);
+  if (
+    manifest.setup.claudeInstructions.enabled &&
+    !manifest.setup.agentInstructions.enabled &&
+    currentState?.outputs.some(
+      (output) => output.resourceId === "setup:agent-instructions",
+    )
+  ) {
+    return yield* new InvalidProjectStateError({
+      message: "cannot disable agentInstructions while claudeInstructions still links to its AGENTS.md wrapper",
+    });
+  }
   yield* validateReservedPaths(
     projectDir,
     reservedPaths,
@@ -898,12 +996,16 @@ const applyPlannedSkillChanges = Effect.fn("applyPlannedSkillChanges")(function*
     const staged = path.join(stageDir, String(stageIndex++));
     yield* fs.makeDirectory(path.dirname(staged), { recursive: true });
     if (action.desired.mode === "copy") {
-      yield* fs.copy(action.desired.source, staged, { overwrite: true });
-      const symbolicLink = yield* findNestedSymbolicLink(staged);
-      if (symbolicLink !== undefined) {
-        return yield* new InvalidProjectStateError({
-          message: `staged skill contains a symlink: ${action.desired.path}`,
-        });
+      if (action.desired.kind === "file") {
+        yield* fs.writeFileString(staged, action.desired.content, { mode: 0o644 });
+      } else {
+        yield* fs.copy(action.desired.source, staged, { overwrite: true });
+        const symbolicLink = yield* findNestedSymbolicLink(staged);
+        if (symbolicLink !== undefined) {
+          return yield* new InvalidProjectStateError({
+            message: `staged skill contains a symlink: ${action.desired.path}`,
+          });
+        }
       }
     } else {
       yield* fs.symlink(action.desired.linkTarget, staged);

package/templates/AGENTS.md

@@ -0,0 +1,9 @@
+<!-- DEV KIT START -->
+
+# Dev Kit
+
+This project uses `@danieljvdm/dev-kit` to manage portable agent skills and reproducible setup from `dev-kit.jsonc` and `dev-kit.lock.json`.
+
+For dev-kit operations, use the `dev-kit` skill and read `{{DEV_KIT_SKILL_PATH}}` before changing managed outputs.
+
+<!-- DEV KIT END -->