@danieljvdm/dev-kit 0.4.0 → 0.6.0

package/README.md

@@ -20,7 +20,8 @@ Install the published Dev Kit package:
 bun add -d @danieljvdm/dev-kit
 ```
 
-Initialize the project, browse the approved catalog, and add skills:
+Initialize the project, browse available built-in, approved Git, and installed
+package skills, then add the ones you want:
 
 ```bash
 bun x dev-kit init
@@ -72,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:
@@ -107,7 +123,7 @@ the root package itself.
 | `dev-kit remove <skill...>` | Deselect and uninstall skills safely. |
 | `dev-kit list [--all]` | List selected skills or browse the catalog. |
 | `dev-kit search <words...>` | Search names and descriptions. |
-| `dev-kit info <skill>` | Show description, source, and approved commit. |
+| `dev-kit info <skill>` | Show description and Git or installed-package provenance. |
 | `dev-kit status` | Check whether the project matches its selection. |
 | `dev-kit sync` | Apply the current manifest. |
 | `dev-kit plan` | Preview project changes without writing files. |
@@ -149,7 +165,8 @@ tool versions. A project-local process lock also prevents concurrent applies.
 
 ## Manifest
 
-`include` accepts individual skill names and skill families:
+`include` accepts static skill names, skill families, and explicit
+`<package>#<skill>` selectors:
 
 ```jsonc
 {
@@ -159,9 +176,14 @@ tool versions. A project-local process lock also prevents concurrent applies.
     "effect",
     "workers-best-practices",
     "wrangler",
-    "serve-sim"
+    "serve-sim",
+    "@tanstack/ai#ai-core"
   ],
   "exclude": ["animation-vocabulary"],
+  "setup": {
+    "agentInstructions": { "enabled": true },
+    "claudeInstructions": { "enabled": true }
+  },
   "targets": {
     "agents": { "enabled": true, "mode": "copy" },
     "claude": { "enabled": true, "mode": "symlink" },
@@ -171,10 +193,13 @@ 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.
+- `@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.
 
@@ -183,6 +208,34 @@ Dev Kit reserves `.repos/<source-id>` for project-local source checkouts. Run
 The patch is idempotent, preserves existing lines, and refuses symlinked
 `.gitignore` files.
 
+## Agent instructions
+
+Enable a managed project-root instruction wrapper and a portable Claude Code
+bridge in the manifest:
+
+```jsonc
+{
+  "include": ["dev-kit"],
+  "setup": {
+    "agentInstructions": { "enabled": true },
+    "claudeInstructions": { "enabled": true }
+  }
+}
+```
+
+`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
 
 Enable a local checkout of the exact installed Effect release in the manifest:
@@ -248,10 +301,65 @@ troubleshooting the task directly.
 Package and tsconfig edits remain explicit until Dev Kit can safely own parts
 of shared JSONC files.
 
-## Approved external skills
+## Installed package skills
 
-This repository is an opinionated catalog, not a mirror of every upstream skill
-tree. `skill-sources.jsonc` declares sources Dan has approved:
+Dev Kit generically discovers agent skills bundled by the project's installed
+JavaScript packages. It reads the project's direct dependencies, checks the
+package's Intent v1 discovery metadata (or Intent's repository-metadata
+fallback), then looks for the layout
+`node_modules/<package>/skills/<skill>/SKILL.md`.
+TanStack is one publisher of this layout; no TanStack package names or skill
+paths are hard-coded into Dev Kit.
+
+Discovery is browse-only. These commands show an installed package skill but do
+not select, copy, symlink, lock, or otherwise install it:
+
+```bash
+bun x dev-kit list --all
+bun x dev-kit search tanstack
+bun x dev-kit info @tanstack/ai#ai-core
+```
+
+Selection is explicit and package-qualified:
+
+```bash
+bun x dev-kit add @tanstack/ai#ai-core
+```
+
+That writes `@tanstack/ai#ai-core` to `dev-kit.jsonc` and, unless
+`--no-apply` is passed, installs it through the normal ownership-safe sync
+path. The qualifier prevents ambiguity when two dependencies publish the same
+skill name. Two selected skills that would both write the same destination are
+rejected before any output is changed.
+
+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.
+
+The project `dev-kit.lock.json` records the selected package name, installed
+version, skill name, and content digest. `apply --locked` therefore rejects
+package-version or skill-content drift. Dev Kit never downloads a missing
+package or substitutes a registry version.
+
+See TanStack's
+[Agent Skills documentation](https://tanstack.com/ai/latest/docs/getting-started/agent-skills)
+for a real package suite that uses this convention.
+
+## Approved external Git skills
+
+This repository remains an opinionated catalog for Git-hosted skills.
+`skill-sources.jsonc` contains only reviewed Git sources:
 
 ```jsonc
 {
@@ -276,38 +384,25 @@ bun run catalog:refresh
 bun run catalog:check
 ```
 
-Adding a source does not require editing JSONC:
+Adding a Git source does not require editing JSONC:
 
 ```bash
-# Opens a skill picker in a terminal
 dev-kit catalog add https://github.com/owner/repository
-
-# Explicit and automation-friendly
 dev-kit catalog add https://github.com/owner/repository \
   --skill one --skill two
 dev-kit catalog add https://github.com/owner/repository --all
 ```
 
-GitHub tree URLs are accepted, so a URL such as
-`https://github.com/owner/repository/tree/main/skills` supplies the repository,
-ref, and skills path together. `--all` expands to the skills discovered at that
+GitHub tree URLs are accepted. `--all` expands to the skills found at that
 exact snapshot; it never writes a wildcard that could silently approve a future
-upstream addition.
-
-The current catalog includes approved snapshots from Emil Kowalski,
-Cloudflare, and Evan Bacon. Inspect them with `dev-kit catalog list` and
-`dev-kit catalog info <source>`.
-
-The refresh resolves refs to exact commits, validates names and paths, rejects
-symlinks and collisions, extracts short descriptions, and updates
-`skill-sources.lock.json`. It does not copy upstream skill trees into this
-repository.
-
-When a consuming project selects an external skill, Dev Kit fetches that exact
-approved commit into the ignored `.dev-kit/cache`, applies declared compatibility
-transforms, and installs the result through the ownership-safe sync path. Normal
-installs never float to a newer upstream commit; only a reviewed catalog refresh
-changes what is approved.
+upstream addition. Catalog refresh resolves refs to exact commits, validates
+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.
 
 ## Oxlint and Oxfmt configurations
 

package/dev-kit.example.jsonc

@@ -2,6 +2,8 @@
   "$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.4.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

@@ -10,21 +10,21 @@
       "type": "string"
     },
     "include": {
-      "description": "Skill names or family names to sync. Prefer individually relevant external skills; an external source id selects every approved skill from that source.",
+      "description": "Static skill names, family names, or exact <package>#<skill> selectors to sync. Installed package skills are discovered for browsing but selected only when explicitly included.",
       "type": "array",
       "items": {
         "type": "string",
-        "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$"
+        "pattern": "^(?:[a-z0-9]+(?:-[a-z0-9]+)*|(?:[a-z0-9][a-z0-9._-]*|@[a-z0-9][a-z0-9._-]*/[a-z0-9][a-z0-9._-]*)#[a-z0-9]+(?:-[a-z0-9]+)*)$"
       },
       "uniqueItems": true,
       "minItems": 0
     },
     "exclude": {
-      "description": "Skill names or family names to remove from the selected set after expanding includes.",
+      "description": "Static skill names, family names, or exact <package>#<skill> selectors to remove after expanding includes.",
       "type": "array",
       "items": {
         "type": "string",
-        "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$"
+        "pattern": "^(?:[a-z0-9]+(?:-[a-z0-9]+)*|(?:[a-z0-9][a-z0-9._-]*|@[a-z0-9][a-z0-9._-]*/[a-z0-9][a-z0-9._-]*)#[a-z0-9]+(?:-[a-z0-9]+)*)$"
       },
       "uniqueItems": true,
       "default": []
@@ -34,6 +34,12 @@
       "type": "object",
       "additionalProperties": false,
       "properties": {
+        "agentInstructions": {
+          "$ref": "#/$defs/agentInstructionsSetup"
+        },
+        "claudeInstructions": {
+          "$ref": "#/$defs/claudeInstructionsSetup"
+        },
         "effectSource": {
           "$ref": "#/$defs/effectSourceSetup"
         },
@@ -58,6 +64,28 @@
   },
   "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",
+      "additionalProperties": false,
+      "properties": {
+        "enabled": {
+          "type": "boolean",
+          "default": false
+        }
+      }
+    },
     "effectSourceSetup": {
       "type": "object",
       "additionalProperties": false,

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
 
@@ -67,6 +71,10 @@ skill as `dev-kit` when project agents should carry the toolkit procedure.
   "$schema": "./node_modules/@danieljvdm/dev-kit/schema/dev-kit.schema.json",
   "include": ["dev-kit", "effect"],
   "exclude": [],
+  "setup": {
+    "agentInstructions": { "enabled": true },
+    "claudeInstructions": { "enabled": true }
+  },
   "targets": {
     "agents": { "enabled": true, "mode": "copy" },
     "claude": { "enabled": true, "mode": "symlink" },
@@ -80,6 +88,15 @@ 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; 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
 
 Dev-kit adopts an existing destination only when its digest exactly matches a
@@ -109,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
@@ -195,8 +218,10 @@ in the consuming project.
 
 ## Current boundary
 
-Manage skill outputs, the `setup.effectSource` checkout, and the explicit
-`setup.effectTsgo` task. Edit shared `package.json` and `tsconfig.json`
+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 exports, not manifest-managed outputs. Treat broader setup tasks as
 future manifest capabilities until the installed CLI exposes them.

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.