@adobe/data-ai 0.9.92 → 0.9.93

package/.claude/rules/features/data/index.md

@@ -5,11 +5,17 @@ paths:
 
 # data/ — the data model
 
-The foundation layer: the feature's **data types**. A data type is a
-readonly, JSON-serializable value suitable for persistence and for
-communication over the wire — no functions, no handles, just plain data.
-It depends on nothing but `@adobe/data` and other `data/` declarations, and
-needs no knowledge of anything built on top of it.
+The foundation layer: the feature's **data types** and the pure declarations
+over them. A data type is a readonly, JSON-serializable value suitable for
+persistence and for communication over the wire — no functions, no handles, just
+plain data. A `data/` **type** depends on nothing but `@adobe/data` and other
+`data/` types, and needs no knowledge of anything built on top of it. The
+**transitions** over those types are less restricted: when one injects a service
+it may import freely from `services/` — the service type and any utilities its
+namespace exposes (see `state.md`). What it must **never** touch is `ui/`:
+`data/` never depends on presentation — that isolation is strict and inviolable.
+Only *services themselves* are never authored here; that is what makes this the
+value-type layer.
 
 Each data type is its own namespace folder (see `global/namespace.md`), holding
 its hand-authored type, its (optional, matching) schema, and its pure

package/.claude/rules/features/data/state.md

@@ -5,55 +5,212 @@ paths:
 
 # data/state/ — the State specification
 
-`State` is the whole feature modelled as **one immutable object** — the
-pure, fully-tested source of truth for the feature. Modelling everything as
-a single value keeps each transform a small, trivially-testable function of
-state: collections of entity sub-types plus scalar fields.
+`State` is the whole feature as **one immutable object** — the pure, fully-tested
+source of truth. Each transition is a read→write **patch** over state; each
+derivation a pure selector. Reference: `data-lit-todo`'s `data/state/`.
 
-Every feature that has ECS resources or transactions owns a `State` — including
-a host whose aggregate is a single scalar (`{ playing: boolean }`) or even when there is no state in which case use `{}`. 
 ```ts
-// state.ts — the aggregate, plus the namespace of transforms/derivations.
-export type State = {
-    readonly todos: readonly Todo[];        // a collection of entity sub-types
-    readonly displayCompleted: boolean;     // a scalar field
-};
+// state.ts — the aggregate + the transition/derivation namespace.
+export type State = { readonly todos: readonly Todo[]; readonly displayCompleted: boolean };
 export * as State from "./public.js";
 ```
 
-## Transforms — one per file, `(state, …args) => state`
-
-- **Pure.** No I/O, no framework, no mutation — return a new value.
-- **Narrow in, same shape out.** Write on the smallest slice the transform
-  needs and keep the input generic over that slice so it lifts to
-  full-state-in / full-state-out:
-
-  ```ts
-  export const playMove = <T extends Pick<State, "board" | "firstPlayer">>(
-      state: T,
-      input: PlayMoveArgs,
-  ): T => { /* … return { ...state, board: … } */ };
-  ```
-
-  A whole-`State` transform (`restartGame(state: State): State`) is fine when
-  it genuinely touches everything.
-- Args may be **narrowed or omitted** (`toggleDisplayCompleted(state)`).
-- Guard and **return `state` unchanged** on a no-op / illegal input rather
-  than throwing — this keeps transforms idempotent under repeated application.
-- Each transform has a sibling `*.test.ts`; performance is irrelevant here,
-  correctness is everything. The test file **exports** its cases —
-  `export const cases: ConformanceCase<Args>[]` (the shared `conformance-case.ts`
-  type) — right alongside the `describe`/`it` that exercise them. This is
-  spec-owned truth the matching main-service conformance test imports **from the
-  `<transform>.test.js` file** unchanged (see `services/main-service/conformance.md`).
-  Keeping the cases in the test file rather than a separate `<transform>.cases.ts`
-  removes a file per transform — less folder clutter, same reuse. Author
-  `before`/`after` as full `State` (`{ ...State.create(), …overrides }`); the
-  generic-slice signature lets them flow through. Tolerant full-`State` equality is
-  the shared `expect-state-matches.ts`.
-
-## Derivations — `(state) => value`
-
-Pure selectors (`visibleTodos(state)`). Sub-type math (a winner, a status)
-lives on the relevant `data/<type>` namespace; `state/` only composes over
-the whole aggregate.
+Every feature with ECS resources/transactions owns a `State` (a scalar
+`{ playing: boolean }`, or `{}` when there is none).
+
+**`State` has a standard shape.** Two exports are conventional and drive
+conformance:
+
+- **`create(): State`** (`data/state/create.ts`) — the default state. Every
+  conformance case's `before` is a **delta over `State.create()`**, and both the
+  pure `spec.test.ts` and the ecs `runFeature` seed from it.
+- **`samples: readonly State[]`** (`data/state/samples.ts`) — representative
+  **full** states `runFeature` round-trips through the projection
+  (`toState ∘ fromState ≡ identity`, see `conformance.md`).
+
+Both are re-exported through `public.js`, so `State.create()` / `State.samples`
+are namespace members. (A `cases` literal must still not touch `public.js` at
+load — import `create` from `./create.js` directly there; see below.)
+
+**The discovered transitions are a test-only sibling, NOT on the namespace.**
+`data/state/transitions.ts` exports one `import.meta.glob` of the folder — the
+`{ fn, cases }` modules — imported by *both* `spec.test.ts` and the ecs
+`conformance.test.ts` so the glob is authored once per feature:
+
+```ts
+// data/state/transitions.ts — test-only; both test entry points import it
+export const transitions = import.meta.glob<Record<string, unknown>>(
+  ["./*.ts", "!./*.test.ts", "!./*.type-test.ts", "!./transitions.ts"],
+  { eager: true },
+);
+```
+
+It stays **out of `public.js`** deliberately: unlike `create`/`samples` (plain
+prod-safe values), `transitions` is the test-case graph — hanging it on `State`
+would drag `import.meta.glob` (a Vite-only construct) and every `cases` fixture
+(fake services, matchers, the whole `@adobe/data/testing` module) into every
+production import of `State`, none of which tree-shakes off a live namespace
+re-export. So `create`/`samples` earn a namespace slot; `transitions` is a test
+concern the tests import directly.
+
+## One file per transform: the function **and** its cases
+
+A transform file exports **exactly two things** — the function and its
+`cases` — nothing else (a private helper is fine; a second export is not, and the
+spec aggregator throws if it finds one). The cases are the spec-owned truth every
+conformance runner reuses; co-locating them removes the per-transform `.cases.ts`
+and `.test.ts`.
+
+**Why co-locate `cases` (not a sibling `*.test.ts`)?** They are spec-owned
+fixtures the pure `spec.test.ts` **and** the ecs `runFeature` call both reuse
+(driving transaction / action / computed conformance) — the transform's contract
+expressed as data, not a per-file test — so they belong
+beside the thing they specify, and `Conformance<typeof fn>` binds them to the
+signature so they can't drift. Kept inert (no `describe`; one aggregator runs
+them) they also sidestep the double execution vitest triggers when a single file
+both exports cases and runs its own `describe`. Coverage is then enforced
+centrally by the shared driver's barrel-driven guard rather than by eyeballing
+one test file per transform — and genuine non-transition helpers still keep
+their own `*.test.ts` (see below).
+
+The case types, matchers, and runners all live in the shared
+**`@adobe/data/testing`** module (two namespaces, `Match` and `Conformance`;
+`vitest` is an *optional* peer dependency, already satisfied here). Only one
+tiny per-feature file remains — a ~10-line alias, `conformance-case.ts`, that
+binds `State` once so transform/derivation files can write a one-parameter type:
+
+```ts
+// data/state/conformance-case.ts — the only per-feature conformance declaration
+import { Conformance as ConformanceApi } from "@adobe/data/testing";
+import type { State } from "./state.js";
+export type Conformance<F extends (...args: never[]) => unknown> = ConformanceApi.Cases<State, F>;
+export type Derivation<F extends (...args: never[]) => unknown> = ConformanceApi.DerivationCases<F>;
+export type Effects<Args> = ConformanceApi.Effects<Args>;
+// The entity-reference marker for identity-addressed case args, re-exported so
+// cases import it beside `Conformance`: `args: { id: entity(2) }`.
+export const entity = ConformanceApi.entity;
+```
+
+```ts
+// create-todo.ts
+import { Match } from "@adobe/data/testing";
+import type { Conformance } from "./conformance-case.js"; // the thin per-feature alias above
+export const createTodo = (
+    state: Pick<State, "todos">,
+    { name, complete, analytics }: { name: string; complete?: boolean; analytics: AnalyticsService },
+): Pick<State, "todos"> => {
+    analytics.todoCreated({ name });
+    return { todos: [...state.todos, { name, complete: complete ?? false }] }; // writes patch only
+};
+
+export const cases: Conformance<typeof createTodo> = [
+    { name: "appends the first todo",
+      before: {},                       // empty delta — the default State.create()
+      args: { name: "a", analytics: AnalyticsService.createFake() },
+      after: { todos: [{ id: Match.anyNumber, name: "a", complete: false }] }, // only the changed field
+      effects: { analytics: [["todoCreated", { name: "a" }]] } },
+];
+```
+
+- **Signature** `(state: Pick<State, …reads>, args) => Pick<State, …writes>` — a
+  **read→write patch**. The parameter is the smallest `Pick<State,…>` the
+  transition **reads**; the return is *only the fields it **writes***. **No
+  `<T> => T` generic, no `...state` spread** in the return — return the patch and
+  let the runner merge it. **All non-state inputs go in the single `args` object**
+  (`Conformance<typeof fn>` reads `Parameters[1]`) — bundle a `dt`, an injected
+  service, etc. into it, never as a third positional. A transition that takes
+  **no** args omits `args` from each case entirely (the shared `Case` type makes
+  `args` optional exactly then). **Guard no-ops by returning an empty patch `{}`**
+  (or the unchanged slice), never throw.
+- **A composer merges sub-patches explicitly.** A transition built from smaller
+  ones spreads them — `return { ...s, ...sub(s) }` — so each sub-patch's writes
+  layer in; a transition that merely **delegates** to one sub-transition returns
+  that delegate's patch directly (no spread needed).
+- **Co-located `cases` must not touch the feature's `public.js` barrel at module
+  load** — that barrel re-exports this very file, so calling `State.create()` (or
+  any barrel member) in a top-level `cases` literal dead-locks the import cycle.
+  Import the concrete helper directly (`import { create } from "./create.js"`) or
+  inline full-`State` literals.
+- **`Conformance<typeof fn>`** (the alias above) derives the case `args` type from
+  the function's own signature — author it once, and cases can't drift from what
+  the function accepts. **`before` is a delta over `State.create()`** — list only
+  the fields this case sets differently from the default; **`after` is the writes
+  patch** — only the fields the transition changes. The runner seeds
+  `{ ...State.create(), ...before }` and compares against
+  `{ ...State.create(), ...before, ...after }`, so any field a case doesn't mention
+  is the default and stays unchanged. (A full `before`/`after` still works — it just
+  overrides the default wholesale.)
+- **`after` leaves minted values open** with the shared matchers `Match.anyNumber`
+  / `Match.anyString`, imported from `@adobe/data/testing` — there is **no**
+  per-feature `matchers.ts` anymore. An id the ECS assigns from its own id-space is
+  `id: Match.anyNumber`, so the pure spec and the ECS satisfy the same case — match
+  by content, not by the value you don't control. `Match` is framework-agnostic and
+  honors any asymmetric matcher, so vitest's `expect.stringContaining(...)` interops
+  on the expected side too. When an id must **line up in two places** within one
+  comparison — a `selectedId` that points at a specific todo, say — use
+  `Match.ref(label)`: it asserts id *correspondence* (a bijection up to renaming),
+  not a pinned value, so the two occurrences of the label must resolve to the same
+  actual id and two labels can't collide. `anyNumber`/`anyString` are for an id a
+  case does not pin at all; `ref` for one that must be consistent across the case.
+- **Entity-addressed cases use `entity(specId)`.** A transition that addresses an
+  entity by id writes it as `args: { id: entity(2) }` — `entity` imported from the
+  feature's `conformance-case.ts` (re-exported from `@adobe/data/testing`). It types
+  as the id it stands for (like `Match.anyNumber`), so it slots into the transform's
+  own arg type. `runSpec` unwraps it to the plain data-id for the pure side; the ECS
+  runners resolve it to the seeded entity (see `conformance.md`).
+- No per-transform test. The single **`spec.test.ts`** is one call —
+  `Conformance.runSpec({ state: State, transitions })` importing `transitions`
+  from the test-only `./transitions.js` (above) — that auto-discovers every module
+  exporting `cases`, enforces the two-exports rule, and dispatches on case shape (a
+  `value` case → derivation; otherwise a transition whose declared `effects` are
+  also asserted). Passing `{ state: State }` (the same `state` shape `runFeature`
+  takes) is what makes each case's `before`/`input` a delta over `State.create()`.
+  Add `match` alongside it only when
+  the feature needs float tolerance or unordered collections (see `conformance.md`).
+  There is no per-feature `expect-state-matches.ts`, `record-effects.ts`,
+  `expect-conforms.ts`, or `conformance-case.type-test.ts` — those are gone; the
+  shared driver owns comparison, effect recording, and name-based auto-pairing, and
+  the `Effects` type-test now lives once in `@adobe/data/testing`. A genuine **non-transition helper** in
+  `state/` — a `create()` constructor, a single-field predicate — has no `cases`
+  and isn't a `(state,args)=>state` transform, so `runSpec` skips it: **keep its own
+  sibling `*.test.ts`** rather than deleting it and losing coverage.
+
+## Injected services and side effects
+
+A transform that needs an outside capability receives it as a **named parameter**
+in the args object, keyed by the service name minus its `-service` suffix
+(`AnalyticsService` → `analytics`, `NameGeneratorService` → `nameGenerator`);
+plain data args sit alongside. Import the service straight from `services/` (an
+ordinary import — layers split by kind of type, not dependency). The **same
+services appear on `db.services` for the matching action**, so the transition is
+the complete spec of *both* the state change and the service calls.
+
+- A transition **is deterministic given its dependencies** — inject a fixed
+  double and the output (and its calls) are fixed. An **async** dependency makes
+  the transition `Promise<State>`; keep sync the default.
+- **Side effects are declared in the case's `effects`**, keyed by the service
+  arg, as `[methodName, ...args]` tuples — an `Array` asserts these calls in
+  order, a `Set` in any order. Only listed services are checked (a value-returning
+  read like `generateName` you don't list is ignored). See `conformance.md` for
+  how the recording double captures them.
+- Tests inject **deterministic doubles** (never production) whose published
+  responses the case's `after`/`effects` are authored against — doubles live
+  adjacent to the interface (`features/services/index.md`).
+
+## Derivations — `(state) => value`, cases `{ input, value }`
+
+Pure selectors that **compose the aggregate** — a value drawn from **two or more
+`State` fields** (`visibleTodos` from `todos` + `displayCompleted`;
+`currentPlayer` from `board` + `firstPlayer`). A value computed from a **single**
+`State` field is that field's own type math and lives on its `data/<type>`
+namespace (`winner`/`status` from `board` → `data/board-state`), tested there —
+**not** in `state/`. A feature may therefore have zero `state/` derivations.
+
+A `state/` derivation co-locates cases shaped `{ input, value }`, typed
+`Derivation<typeof fn>` (input + value read from the signature). Take the **full
+`State`** as the parameter (not a `Pick` slice like a transform) — so the case
+`input` type is the full `State` and computed conformance can seed it via
+`fromState`; `value` may use matchers. The same `spec.test.ts` runs them (dispatching on case shape),
+and each ECS computed backing one is conformance-tested from the same cases
+(`conformance.md`). Sub-type math (a winner, a status) lives on the
+relevant `data/<type>` namespace; `state/` only composes over the aggregate.

package/.claude/rules/features/index.md

@@ -26,9 +26,25 @@ derive a fast one that provably behaves the same.
 
 ## The layers
 
-`ui → services → data` — higher imports lower, never the reverse. `data/`
-depends on nothing but `@adobe/data` and other `data/` declarations. A feature
-creates only the layers it uses.
+**The layers organize by the *kind of type* each folder holds, not by a strict
+dependency wall.** `data/` holds **value types** (pure, serializable data) and
+the pure declarations over them; `services/` holds **service types** (interfaces
+**and** implementations); `ui/` holds presentation. The rule is about *what
+lives where*: a service is never authored under `data/`, a value type is never
+authored under `services/`.
+
+**`ui/` isolation is strict and inviolable.** `ui/` sits at the top: neither
+`data/` nor `services/` may ever import from `ui/`, no exceptions. Presentation
+depends on the model; the model never depends on presentation.
+
+Beneath that hard line, `data/` and `services/` are **not** strictly ordered.
+Value types are fundamental — a `data/` **type** depends on nothing but
+`@adobe/data` and other `data/` types. But the **transition functions** over
+them may depend on `services/` **without restriction**: they import whatever they
+need — service interfaces they inject, and any associated utilities the service
+namespace exposes — as ordinary imports, not type-only. So the strict wall is
+`ui/` above `data/` + `services/`; the `data/ ↔ services/` boundary is the loose
+one. A feature creates only the layers it uses.
 
 | Layer | Role |
 |-------|------|
@@ -85,13 +101,16 @@ The tie between `data/` (spec) and `main-service` (implementation) is
 **conformance**, one property —
 `toState(apply(fromState(before), args)) ≡ transform(before, args)`: each
 main-service mutation, seeded and read back through a test-only store↔`State`
-projection, equals the pure `data/` transform it stands for. The projection and
-its runner live in `services/main-service/conformance/` (see
-`services/main-service/conformance.md`); the shared `{ before, args, after }`
-cases are spec-owned (exported from `data/state/<transform>.test.ts`), so conforming the
-implementation is "substitute the implementation, reuse the expectations." This
-lets `main-service` be largely mechanical and agent-generated, with the spec as
-oracle. *How* to author each layer lives in the per-folder rules below.
+projection, equals the pure `data/` transform it stands for. The per-feature
+projection lives in `services/main-service/conformance/`, and a **single
+`Conformance.runFeature({...})` call** replays the shared cases against the ecs —
+pairing each ECS op to its same-named transition automatically and round-tripping
+the projection (see `services/main-service/conformance.md`);
+the shared `{ before, args, after }` cases are spec-owned — co-located in each
+`data/state/<transform>.ts`, which exports its function plus `cases` — so
+conforming the implementation is "substitute the implementation, reuse the
+expectations." This lets `main-service` be largely mechanical and agent-generated,
+with the spec as oracle. *How* to author each layer lives in the per-folder rules below.
 
 ## Reference implementations
 

package/.claude/rules/features/services/index.md

@@ -33,6 +33,25 @@ portability and lazy loading (`AsyncDataService.createLazy`).
 - Members are async only: `void | Promise<T> | AsyncGenerator<T> | Observe<T>`.
 - Provide `create*` factories.
 
+## Deterministic test doubles, adjacent to the contract
+
+A service is the seam consumers swap out under test — `data/` transitions that
+take it as an injected dependency (`data/state.md`), actions, systems. Ship a
+**deterministic test double** alongside the interface, in the same namespace
+folder and under the same `global/namespace.md` standard: `create-fake.ts` is a
+**single export**, `createFake`, re-exported through `public.ts` so callers reach
+it as `MyService.createFake` (mirroring the `create` / `factory` pair).
+
+Because tests assert on exact `after` values, the double must be **deterministic
+and its responses caller-controlled**: `createFake` takes the exact response — the
+fixed value, or the ordered sequence each method returns — as a parameter, with a
+small inline default. A conformance case then **injects the responses it needs**
+(`createFake(["random task"])`, `createFake([4])`) and authors its `after` /
+`effects` against those values it supplied — nothing is read from a shared
+published constant (that would be a second export, and it makes the assertion
+guess at a value it doesn't own). The injected schedule is exactly what makes the
+double a dependable oracle: the test controls both the input and the expectation.
+
 ## Where the I/O types live
 
 Most input/output types belong to a single service — declare them **on that

package/.claude/rules/features/services/main-service/actions.md

@@ -10,6 +10,20 @@ argument and pure `data/` args. Actions orchestrate anything *outside* a
 single transaction — awaiting a `services/` port, sequencing calls, deriving
 timing — and then commit the result through a transaction.
 
+**Every *app-facing, transaction-backed* transition has a corresponding
+same-named action** — the async realization the UI drives. It reads the same
+services the transition injects from `db.services`, so it reproduces both the
+transition's state change (through a transaction) and its side effects. It may
+reuse another transition's transaction (`createRandomTodo` reuses `createTodo`) —
+there need not be a same-named transaction; transactions are the looser layer.
+
+**Per-frame / system transitions are exempt.** In a real-time feature the `step*`
+/ physics / collision transitions are realized by the **systems** tick loop, not
+by an action, and are conformed by the tick-loop test (`systems.md`), not the
+action surface of `runFeature`. Give an action only to transitions a user/UI invokes directly
+(and skip it too when the realization needs more than one transaction — e.g. a
+`newGame` that both sets bounds and resets is conformed via its transaction).
+
 ```ts
 import type { ServiceDatabase } from "../../service-database/service-database.js";
 
@@ -29,4 +43,24 @@ export const addRandomTodo = async (service: ServiceDatabase) => {
   awaited-internally, never surfaced to the caller.
 - Do the outside-world work here: await/sequence `services/` calls, and if a
   slow call needs timing, compute it here around the call.
+- **Read current state synchronously from the store** (`db.resources` / `db.read`
+  / `db.select`, then a pure `data/` helper) — never from a cached `computed`.
+  Reactive computeds refresh only on a committed transaction, so an imperative
+  read of one can hand back a stale shared cache (and it's the UI's layer, not
+  the action's). This also keeps the action correct under the conformance seed.
+- **Conformance** is the action surface of the feature's single
+  `conformance/conformance.test.ts` `Conformance.runFeature({...})` call. It pulls
+  actions off **`plugin.actions`** and pairs each to the **same-named** `data/state`
+  transition. **The action is the primary seam** — it reads injected services from
+  `db.services`, so the case's service args become recording overrides (the runner
+  builds `Database.toSystemDatabase(Database.create(plugin, { services }))`); it
+  splits the case `args` into services and plain input, runs the action, then
+  `Match.assert`s `toState ≡ after` **and** checks the recorded calls against the
+  case's `effects`. There is no `define`/`conforms` and no coverage guard. A thin
+  **same-named** action gives a transaction-only or renamed transition something to
+  pair with (todo's `reorderTodo`). A streaming/capability action with no transition
+  is skipped. **A per-transition action kept out of the facet** (to bound the
+  plugin's type) is discovered via `runFeature`'s `ops.actions` glob —
+  `ops: { actions: import.meta.glob([".../actions/*.ts", "!.../actions/index.ts"], { eager: true }) }`
+  (p2p negotiation). That is the *only* reason to pass `ops` (see `conformance.md`).
 - An `index.ts` barrel feeds the `actions` plugin facet.

package/.claude/rules/features/services/main-service/computed.md

@@ -10,6 +10,27 @@ returns an `Observe` of state projected through pure `data/` helpers.
 Derivation logic itself lives in `data/`; a computed only wires a service
 observable to it.
 
+**Reuse tested pure logic; let performance pick the wiring.** Prefer wiring the
+pure **`data/<type>` helper** (or composing indexes) directly — the tictactoe
+computeds delegate their observable straight to
+`BoardState.deriveStatus`/`getWinner`/`currentPlayer` — because a helper reads
+exactly the resource/entities it needs, and both the computed and the matching
+`state/` derivation call it, so they agree by construction.
+
+You **may** also import a pure `state/` derivation `(state) => value` into a
+computed where performance is adequate: a small-N or resource/scalar composition,
+not a hot per-entity or large-N path. Reusing a tested derivation is good — the
+only cost is that it takes the **whole `State`**, so the computed must observe the
+full-state projection and re-runs on *any* field change (fine for a small feature,
+wasteful on a large or hot one, where you hand-wire the minimal resource/index
+reads instead). A derivation takes **no services**, so its co-located `cases` are
+inert `{ input, value }` data (no test-doubles) that tree-shake out of the app
+build (they reference the `@adobe/data/testing` matchers only, and that module is
+`sideEffects: false`) — the one hazard is a `cases` literal touching the
+`public.js` barrel at load, which `state.md` already forbids. **Performance is the
+first-class constraint**: reuse freely where it doesn't matter, hand-wire minimal
+reads where it does.
+
 ```ts
 import { cached } from "@adobe/data/cache";
 import { Observe } from "@adobe/data/observe";
@@ -24,3 +45,33 @@ export const status = cached((service: IndexDatabase) =>
 Type the parameter on the lowest database layer that exposes what it
 reads. An `index.ts` barrel re-exports every computed; `computed-database.ts`
 registers it under the `computed` facet.
+
+**Conform a computed to its `data/state` derivation** whenever one exists. The
+derivation co-locates `{ input, value }` cases (`Derivation<typeof fn>`), and the
+feature's single `conformance/conformance.test.ts` `Conformance.runFeature({...})`
+call conforms computeds: it pulls them off **`computedPlugin.computed`**, pairs each
+to its **same-named** derivation, seeds the store from `input`, reads the computed's
+synchronous emission, and `Match.assert`s it against `value` (see `conformance.md`).
+There is no `define`/`conforms` wiring. **`computedPlugin` is the `ComputedDatabase`
+layer** — the runner builds computed conformance from that layer, not the assembled
+`MainService`, so a `withCache` above can't hand back a stale pre-seed value (a
+direct `fromState` seed emits no transaction to invalidate it). Comparison is
+identity by default; a computed that emits an **entity-id list** names itself in
+`hydrate: [...]` (todo's `visibleTodos`) so the runner projects each id through
+`toData`. A computed with **no `state/` derivation is skipped** —
+single-`data/<type>` math is covered by that helper's own test. A feature with no
+`state/` derivation omits `computedPlugin` entirely.
+
+**What needs conformance is proportional to wiring logic.** A computed that
+composes/branches over the aggregate *is* a `state/` derivation (composes ≥2
+fields) and is conformed here. A computed that **trivially applies one
+`data/<type>` helper to one field** (`winner` ← `BoardState.getWinner(board)`) is
+already covered by its parts — the field by `toState` conformance, the math by
+that helper's unit test — so an added conformance would just re-invoke the same
+helper on both sides (tautological); the helper's unit test is sufficient. Two
+exceptions: (1) to pin a particular non-obvious wiring, promote it to a thin
+`state/` derivation `(state) => Type.helper(state.field)` and the runner conforms
+it — no new mechanism; (2) if a computed folds **entities into a value with no
+intermediate `State` field**, that projection *is* unconformed — promote the
+intermediate to a `State` field so `toState` covers it, making it a normal
+`state/` derivation.

package/.claude/rules/features/services/main-service/conformance.md

@@ -3,70 +3,216 @@ paths:
   - '**/features/*/services/main-service/**/conformance/**/*.ts'
 ---
 
-# services/main-service/conformance/ — spec↔implementation projection (test-only)
-
-The bridge that keeps the ecs implementation honest against the `data/` spec.
-**Test-only**: imported solely by `*.test.ts` and in no facet barrel, so it never
-enters the runtime bundle (test-support may import the test framework — it is not
-a runtime declaration). **Never call `fromState` / `toState` (or a shared
-clear-all + reinsert helper used only for that projection) from systems,
-transactions, or UI** — that is a full-store rewrite, not an O(1) ECS update.
-**Feature-level**: one projection per feature, reused by every transaction test
-and the system tick-loop test — don't nest it under `transaction-database/`.
-
-The property, per `{ before, args, after }` case:
-`toState(apply(fromState(before), args)) ≡ spec(before, args)`.
-
-Conformance test-support splits by concern along the layer boundary:
-
-- **Store-side, here in `services/main-service/conformance/`:**
-  - `from-state.ts` → `fromState(store: CoreDatabase.Store, state: State): void`
-    seeds the store (clear tail→head → insert entities → set resources) to a `State`.
-  - `to-state.ts` → `toState(store): State` reads the store back — each kind via
-    its full named-archetype component set, so the shapes never alias.
-  - `expect-conforms.ts` → **one export, `expectConforms({ cases, spec, apply })`**.
-    Per case it asserts `spec(before, args) ≡ after` (keeps the case honest), then
-    `fromState(before)` → `apply(store, args)` → `toState ≡ after`.
-- **Spec-side, in `data/state/`** (State values, no store — so both the `data/`
-  transform tests and this runner import them without a layer violation):
-  `conformance-case.ts` (`ConformanceCase<Args>`), the cases **exported from each
-  `<transform>.test.ts`** (`import { cases } from "…/<transform>.test.js"` — no
-  separate `.cases.ts` file), and `expect-state-matches.ts` (State equality).
-
-## No cast — build on `Store.create`, not a `Database`
-
-A **transaction is `(store, args) => void`**, so transaction conformance needs no
-`Database`: `Store.create(<schema-layer>.plugin)` returns a cast-free writable
-`CoreDatabase.Store` — pass the plugin directly, `Store.create` reads its schema
-facets. Source it from the **lowest layer that declares all the schema** —
-`IndexDatabase`, or `CoreDatabase` if the feature has no indexes — **not**
-`MainService`: the store needs only schema, and the behaviour layers
-(transactions / computed / systems) add none.
-`fromState`/`toState`/`apply` all operate on it, and `apply` calls the **raw
-transaction function** directly:
+# services/main-service/conformance/ — keeping the ECS honest against the spec
+
+Test-only (imported only by `*.test.ts`, in no facet barrel). The `data/state`
+cases are the shared truth; the shared **`@adobe/data/testing`** runner replays
+them against the ECS. This folder holds only the *feature-specific projection*
+(`projection.ts`) plus one `conformance.test.ts` that makes a **single**
+`Conformance.runFeature({...})` call. Reference: `data-lit-tictactoe`'s
+`conformance/` (the zero-config example) and `data-lit-todo` (entity markers +
+`hydrate`); `data-lit-space-rock-game` for the entity-bag / real-time variant.
+
+**The projection helpers — `fromState`, `toState`, and the
+`toData(store, entity)` reader — are strictly for conformance tests and MUST
+NEVER run in production code, ever.** `fromState`/`toState` rewrite the whole
+store out-of-band; runtime code reads through observables/indexes and writes
+through transactions. (This conformance `toData(store, entity)` reader is
+unrelated to the library's `db.toData()` store-serialization method, which *is*
+a normal runtime API — the collision is only in the name.) Likewise
+`Match.matches` / `Match.assert` are comparison helpers for `*.test.ts` only —
+never a runtime branch.
+
+## What `@adobe/data/testing` gives you
+
+Two namespaces, imported only from `*.test.ts` (the module is
+`sideEffects: false`, and `vitest` is an optional peer dependency, satisfied
+here):
+
+- **`Match`** — the tolerant, matcher-aware value comparison: `matches(actual,
+  expected, options?)` and its throwing wrapper `assert(...)`, plus the matchers
+  `Match.anyNumber` / `Match.anyString` / `Match.ref(label)`. Options are
+  `{ unordered?: ReadonlySet<string>; tolerance?: number }` — arrays compare **in
+  order** (default) unless a key is named in `unordered`, and numbers snap to
+  `tolerance` (default `0.01`) to absorb F32↔f64 / trig noise. Framework-agnostic:
+  it honors any asymmetric matcher, so vitest's `expect.any(...)` interops.
+- **`Conformance`** — the case types (`Case`, `Cases`, `DerivationCase`,
+  `DerivationCases`, `Effects`, `ServiceCall`), the `entity(specId)` identity
+  marker, the id `resolver(map)`, the whole-feature driver **`runFeature`**, the
+  pure-spec driver **`runSpec`**, and the lower-level per-surface drivers
+  `runTransactions` / `runActions` / `runComputeds` (internals of `runFeature`,
+  exported for the escape hatch below). Auto-pairing (transition ⇄ op by name),
+  effect recording, and id resolution are built **into** the drivers — no
+  per-feature helper writes them. The `Effects` type-test also lives here (once),
+  so there is no per-feature `conformance-case.type-test.ts` to author.
+
+## Projection (store ⇄ State) — the one per-feature piece
+
+`projection.ts` is the only feature-specific file, and it is a **single
+aggregated export** — the three test-only helpers in one file, one `export`:
+
+```ts
+// conformance/projection.ts
+export const projection = { fromState, toState, toData };
+```
+
+- `fromState(store, state)` seeds a store to a `State` (clear tail→head, insert
+  entities, set resources). It **returns the `id → entity` map**
+  (`ReadonlyMap<Id, Entity>`) it built while seeding — the ECS assigns ids from
+  its own id-space, so the runner turns this map into a `resolve` via
+  `Conformance.resolver`; **no feature writes id resolution by hand**. A feature
+  whose transactions are index-addressed or singleton returns `void`, and any id
+  then resolves to `Entity.none`.
+- `toState(store)` reads the whole store back, built on `toData`.
+- `toData(store, entity)` reads one entity as its `data/` value — the single
+  place the ECS↔data mapping lives; the runner reuses it to hydrate id-list
+  computed outputs. **Present only when the feature has entities** (omit for a
+  scalar / resource-only feature).
+
+This replaces the old separate `create-store.ts` / `from-state.ts` /
+`to-state.ts` / `to-data.ts`. **`create-store` is gone** — `runFeature` builds
+every store/db itself with `Store.create(plugin)` / `Database.create(plugin)`.
+
+## ECS conformance is ONE call — `Conformance.runFeature`
+
+`conformance/conformance.test.ts` is a single call that conforms the whole
+feature — transaction + action + computed conformance **plus** the projection
+round-trip. No per-surface test file, no `define` callback, no `conforms(...)`
+adapters, no coverage guard.
+
+```ts
+import { State } from "../../../data/state/state.js";
+import { transitions } from "../../../data/state/transitions.js";
+
+Conformance.runFeature({
+  state: State,
+  transitions,
+  plugin: MainService.plugin,
+  computedPlugin: ComputedDatabase.plugin,   // omit if no state/ derivations
+  projection,
+  hydrate: ["visibleTodos"],                 // entity-id-list computeds; omit if none
+  match: { unordered: new Set(["bullets", "asteroids"]) }, // entity bags / tolerance; omit if none
+  ops: { actions: import.meta.glob([...]) }, // ONLY when ops aren't in the plugin facet
+});
+```
+
+- **`state`** is the `State` namespace itself — the runner calls `State.create()`
+  for the default each case's `before` deltas over, and round-trips `State.samples`
+  through the projection.
+- **`transitions`** is imported from the feature's test-only
+  `data/state/transitions.ts` (the single `import.meta.glob` of the `{ fn, cases }`
+  source, shared with `spec.test.ts` — see `data/state.md`). Never re-glob it here.
+- **Ops come off the plugin facets.** The runner reads
+  `plugin.transactions` / `plugin.actions` / `computedPlugin.computed` and builds
+  the stores/dbs itself (`Store.create(plugin)` for transactions,
+  `Database.create(plugin)` for actions, `Database.create(computedPlugin)` for
+  computeds). Each op pairs to its **same-named** transition/derivation; auto-pairing
+  can't forget an item, so there is **no coverage guard** — an op with **no
+  same-named transition** is infrastructure or system-dispatched and is simply
+  **skipped** (a streaming action with no transition is skipped too).
+- **`ops`** overrides the facet-discovered ops per surface — use it **only** when
+  an op isn't registered in the plugin facet: a per-transition action kept out of
+  the facet (to bound the plugin's type) is discovered via an
+  `ops.actions: import.meta.glob([".../actions/*.ts", "!.../actions/index.ts"], { eager: true })`
+  glob (p2p negotiation). Ordinary features omit `ops` entirely.
+- **`computedPlugin`** is the `ComputedDatabase` **layer** plugin — build computed
+  conformance from this layer, **not** the assembled `MainService`: a behaviour
+  layer above may `withCache` a pre-seed value that a direct `fromState` seed emits
+  no transaction to invalidate; the computed layer keeps the seed authoritative.
+  Omit it when the feature has no `state/` derivations (a computed with no
+  derivation is skipped anyway, and single-`data/<type>` math is covered by that
+  helper's own test).
+- **`hydrate`** names the computeds that emit an **entity-id list** (todo's
+  `visibleTodos`) so the runner maps each id through `toData` into the value shape
+  the derivation yields. Comparison is identity otherwise. Omit if none.
+- **`match`** threads `MatchOptions` through every comparison (see below). Omit if
+  none.
+- **Projection round-trip.** When `State.samples` is non-empty, the runner adds a
+  `toState ∘ fromState ≡ identity` test per sample — proving the pair round-trips
+  faithfully so a symmetric bug in `fromState`/`toState` can't cancel out and mask
+  a real ECS defect. No separate `projection.test.ts`.
+
+`data-lit-tictactoe` is the zero-config call (no `computedPlugin`, no `hydrate`,
+no `match`, no `ops` — moves are board-index addressed, so no `entity()`
+markers). `data-lit-todo` adds `hydrate: ["visibleTodos"]` and `entity()` markers.
+`data-lit-space-rock-game` adds `match: { unordered: … }` for its entity bags
+(its per-frame transitions are conformed by the systems tick loop, not here — see
+`systems.md`).
+
+## The pure spec — `data/state/spec.test.ts`
+
+Lives in `data/state/`, not here. One call, importing the same `transitions`:
 
 ```ts
-expectConforms({ cases, spec: State.hitTarget, apply: (store, args) => hitTarget(store, args) });
+import { State } from "./state.js";
+import { transitions } from "./transitions.js";
+
+Conformance.runSpec({ state: State, transitions });
 ```
 
-A mutation addressed by **entity id** resolves its entities from the seeded store
-inside `apply` (the shared cases stay spec-shaped). Reads never need a cast —
-`Database extends ReadonlyStore`.
-
-**Systems** are the one exception: they run via `db.system.functions` and reach
-the store through the db. Get that writable view with the library lens —
-`Database.toSystemDatabase(Database.create(plugin))` (the widening twin of
-`UIService.restrict`, cast-free) — then `fromState(db.store, before)` → drive one
-frame → `toState(db.store)`. Test **selection/detection** logic (which entities
-interact) separately, with seeded edge-case geometries.
-
-## State equality — ordering vs precision, kept separate
-
-`expect-state-matches.ts` compares with **`equalsUnordered`** from `@adobe/data`
-(arrays as multisets — archetype hole-fill reorders rows — objects key-order
-independent). Absorb float noise — F32↔f64 storage rounding **and** trig epsilon
-(a quadrant `cos`/`sin` yields ~3e-15 where a case authors `0`) — by quantizing
-every number on both sides onto a small grid (`Math.round(Math.fround(n)*k)/k`)
-before comparing. Ordering and precision stay separate concerns. **Guard the
-projection itself** with one `fromState → toState` identity test on
-representative states.
+It discovers every file exporting `cases`, enforces the two-exports rule, and
+dispatches on case shape (transition → state + effects, derivation →
+`fn(input) ≡ value`), seeding each case's `before`/`input` as a delta over
+`State.create()`. Unwraps any `entity(specId)` arg marker to its plain data-id for
+the pure side.
+
+## The exception — a per-surface `userId`, via the lower-level runners
+
+A feature that needs **ambient per-case context differing per surface** — a
+user-scoped `userId` that must be seeded before the raw transaction *and*
+independently before the action dispatch (**p2p presence**) — does **not** use
+`runFeature`. It calls `Conformance.runTransactions` / `runActions` (still
+exported) directly, each with its own `seedContext` (and any per-surface
+concurrency), because the seam differs between the transaction store and the
+action db. `runFeature` has no place to thread two different `seedContext`s, so
+this feature drops to the lower level. This is the escape hatch — ordinary
+features never touch these drivers directly.
+
+## Identity — the `entity(specId)` marker
+
+An entity-addressed transition writes its addressed id as `args: { id: entity(2) }`
+— import `entity`, re-exported from the feature's `data/state/conformance-case.ts`.
+`runSpec` unwraps it to the plain data-id; the ECS runner resolves it to the
+**seeded entity** via the id→entity map `fromState` returns (turned into a `resolve`
+by `Conformance.resolver` — no feature writes `resolve` by hand). Two conventions
+make the wiring vanish: the ECS op takes the entity **under the transition's own arg
+key** (`{ id }`, same-shape args, no reshape), and `fromState` returns the
+`ReadonlyMap<Id, Entity>` id→entity map (or `void` for an index-addressed / singleton
+feature, whose ids then resolve to `Entity.none`). `data-lit-todo` is the reference.
+
+## Name-parity — add a same-named op, never a per-item adapter
+
+Every app transition is realized by a **same-named** transaction and/or action. When
+the real UI op is richer or renamed — todo's `dragTodo`, space-rock's `newGame` — that
+op is infra, and a thin **same-named** op (todo's `reorderTodo` action, space-rock's
+`createInitial` transaction) gives the transition something to pair with. Do **not**
+reintroduce a per-item adapter to bridge a name mismatch — add the same-named op.
+
+## Ordering, tolerance, `ref` — all via `match`
+
+`runFeature` threads `match?: MatchOptions` through to every comparison, so
+per-feature tuning is data, not code:
+
+- **Ordered by default.** `toState` reads a display-ordered collection in order —
+  that is what verifies a reorder — and positional tuples (a `Vec2`) must stay in
+  order.
+- **Entity bags compare as multisets.** A collection the ECS materialises with no
+  display order (bullets, asteroids) is named in
+  `match: { unordered: new Set(["bullets", "asteroids"]) }` so just those fields
+  compare order-independently — never blanket-unordered (it would conflate
+  `[100,180]` with `[180,100]`).
+- **Float noise** is absorbed by the default `tolerance` (`0.01`); raise it only
+  when a case genuinely needs a looser grid.
+- **`Match.ref(label)`** on the expected side asserts id correspondence for a
+  referential feature (an id that must line up in two places); `Match.anyNumber` /
+  `anyString` leave an id a case doesn't pin fully open.
+
+## Recording side effects — built in, no Proxy
+
+Effect recording lives in the drivers: they enumerate a plain-object service's own
+methods and closure-wrap each to record `[method, ...args]` calls, then delegate
+(no `Proxy`, per the repo rule). `runSpec` records the case's injected service
+`args`; the action surface records the `db.services` overrides. A case's `effects`
+asserts each **declared** service's calls exactly (`Array` = ordered, `Set` = any
+order); undeclared services (value-returning reads like `generateName`) are
+ignored.

package/.claude/rules/features/services/main-service/transactions.md

@@ -30,12 +30,21 @@ export const playMove = (t: CoreDatabase.Store, { index }: PlayMoveArgs) => {
   than throwing.
 - Decisions come from pure `data/` helpers; the transaction only applies the
   result — read the touched slice, call the `data/` transform, write the diff.
-- **Conform every transaction to its `data/` transform** in its sibling
-  `*.test.ts`, via `expectConforms` over the spec's shared cases (see
-  `services/main-service/conformance.md`): seed `fromState(before)`, dispatch, assert `toState ≡
-  after`, covering every branch and edge case. A transaction taking **entity
-  ids** resolves them from the seeded store in the `apply` closure; one with no
-  `data/` analogue (`setBounds`, `setInput`) gets a direct resource assertion.
+- Keep transaction files **single-export** (the `transactions/` barrel is
+  `export *`-ed into the plugin facet, so a second export would pollute it).
+- **Conformance is wired once, centrally, and auto-paired** — not per-file. The
+  feature's single `conformance/conformance.test.ts` `Conformance.runFeature({...})`
+  call conforms transactions: it pulls them off **`plugin.transactions`** (the
+  registered facet), pairs each to the **same-named** `data/state` transition, and
+  conforms it — seed `fromState(before)`, apply, `Match.assert` `toState ≡ after`
+  (state only; service effects are asserted through the action). There is **no**
+  `define`/`conforms` adapter and **no** `covers` guard. A transaction taking
+  **entity ids** takes them under the transition's own arg key (`{ id }`); the runner
+  resolves each `entity(specId)` marker via the id→entity map `fromState` returns. A
+  transaction with **no same-named transition** is infrastructure (`setInput`,
+  `setBounds`) or the drag UI op (`dragTodo`) or system-dispatched — it is simply
+  **skipped**, no guard needed. Don't add a per-item adapter for a renamed op; add a
+  thin same-named transaction instead (see `conformance.md`).
 - An `index.ts` barrel feeds the `transactions` plugin facet — so it must
   re-export **only** the mutations. A read/query helper shared by several
   transactions (`readShip`, `readBoard` — a `(t) => value` function) may live

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "adobe-data-ai",
-  "version": "0.9.92",
+  "version": "0.9.93",
   "description": "Architecture skills for @adobe/data — data-oriented modelling, archetype iteration, hot-path performance, and related conventions.",
   "author": {
     "name": "Adobe"

package/README.md

@@ -11,46 +11,95 @@ It installs two things:
 - **skills** — `build-*` commands that scaffold features and applications.
 - **rules** — the path-scoped conventions those skills follow while building.
 
-> **For the installing agent:** find the block below that matches your host
-> (Claude Code or Cursor/other), run its commands, and stop. Each install owns a
-> namespaced folder and is a clean wipe-and-recopy, so re-running is also how you
-> **update** — it never touches files you authored.
+The **rules** are the part that evolves often, so `install` pins the package and
+re-copies them automatically on every install: bump the version and they refresh —
+no manual step, no committed diff, no hand-editing.
 
-## Install — Claude Code
+## Quick start
 
-Skills load as a marketplace plugin; rules install into the project. Run these
-three from a shell (agent-runnable):
+From your project folder root:
+
+**1. Install** — one command:
 
 ```
-claude plugin marketplace add adobe/data --scope project
-claude plugin install adobe-data-ai@adobe-data-skills --scope project
 npx @adobe/data-ai@latest install
 ```
 
-In an interactive Claude session you can instead use the slash-command form of
-the first two — `/plugin marketplace add adobe/data` then
-`/plugin install adobe-data-ai@adobe-data-skills` — but an agent driving a shell
-should use the `claude plugin …` commands above (slash commands aren't
-shell-runnable).
+*(Claude Code only:* also add the skills plugin once — see
+[Claude Code](#claude-code--add-the-skills-plugin-one-time). Cursor/Codex need
+nothing extra; `install` copies their skills.*)*
+
+**2. Restart your AI agent** so it loads the newly installed skills and rules.
+
+**3. Create an application** — ask your agent:
+
+```
+/build-application <a description of the app you want>
+```
+
+That's the whole flow. Everything below explains what `install` does and the
+other build skills available.
+
+## What `install` does
+
+`install` does two things: it **copies the bundle now** (rules →
+`.claude/rules/adobe-data-ai/`, and for Cursor/Codex skills →
+`.agents/skills/adobe-data-ai/`), and it **wires the repo so future installs
+self-update**, editing your `package.json` and `.gitignore` to:
 
-- Skills → the `adobe-data-ai` plugin. **Update:** `claude plugin update adobe-data-ai`.
-- Rules → `.claude/rules/adobe-data-ai/`. **Update:** re-run `npx @adobe/data-ai@latest install`.
+1. pin `@adobe/data-ai` in `devDependencies` at the **exact version it just
+   resolved** (never a range, so a later install can't silently pull an
+   unreviewed release);
+2. add `data-ai install` to **your own** `postinstall` script (chaining if one
+   exists) — it must be *your* script: pnpm does not run a dependency's lifecycle
+   scripts, so a `postinstall` shipped inside the package would silently not fire;
+3. gitignore the managed bundle folders.
 
-## Install — Cursor (and Codex / other `.agents` agents)
+The copied files are regenerated artifacts — never committed, never edited in
+place. The wiring is idempotent, so re-running is harmless; with `--global` or in a
+directory with no `package.json`, `install` just copies (no wiring).
 
-One command installs both:
+After that first run, sync your lockfile with a normal install (`pnpm install`) so
+the pinned dev-dependency is recorded; from then on every install refreshes the
+bundle via the postinstall.
+
+**Why `@latest` for the first command but a pinned version afterward?** The one
+command you type is a one-time, human-initiated bootstrap, so `@latest` is fine
+(the same posture as `npm create …@latest`). The part that *repeats* — every
+teammate's and CI's install — runs from the **exact version `install` pinned into
+your `devDependencies`**, never a moving tag, so no unreviewed release ever
+auto-executes. Pinning happens where it matters, automatically.
+
+**Update:** bump the `@adobe/data-ai` version in `package.json` and install again.
+That's it.
+
+### Claude Code — add the skills plugin (one time)
+
+Claude Code loads skills from a marketplace plugin, not from `.claude/skills/`, so
+its skills are a separate one-time install (the `install` step above already
+handles the rules for Claude Code):
 
 ```
-npx @adobe/data-ai@latest install
+claude plugin marketplace add adobe/data --scope project
+claude plugin install adobe-data-ai@adobe-data-skills --scope project
 ```
 
-- Skills → `.agents/skills/adobe-data-ai/`.
-- Rules → `.claude/rules/adobe-data-ai/`.
-- **Update:** re-run the same command.
+(Interactive sessions can use `/plugin marketplace add adobe/data` then
+`/plugin install adobe-data-ai@adobe-data-skills`.) **Update the skills:**
+`claude plugin update adobe-data-ai`. Cursor/Codex need no plugin — `install`
+copies their skills too.
+
+### Just the files, no managed dependency
 
-## Use
+If you don't want the auto-update wiring — a throwaway scaffold, a non-Node repo,
+or you'd rather commit the bundle and update it on your own schedule — run
+`install` where it can't wire (no `package.json`, or pass `--global`), or simply
+delete the `postinstall`/dev-dependency lines it added. Re-running `install` is
+always a clean wipe-and-recopy; you then update by re-running it yourself.
 
-Ask your agent to run a build command — skills are available by name:
+## Build skills
+
+Step 3 above uses `build-application`; the skills are available by name:
 
 - **`build-application`** — build a whole app: a base feature that hosts
   lazily-loaded peer features.
@@ -66,15 +115,16 @@ by name when you want a single phase or a specialized flow: `build-data`,
 in subagents), `review` (audit output against the rules), and `structure`
 (reason about layout).
 
-## One-liner: install + build an app
-
-Paste one of these into a shell, replacing the quoted text with your own app
-description. It installs the bundle, then runs `build-application` headlessly on
-your prompt.
+## One-liner: install + build an app (headless)
 
-This presumes you are already running the agent within the directory you want to use as your project root.
+Paste this into an agent already running in your project root, replacing the
+quoted text with your own app description. It installs the bundle, then runs
+`build-application` on your prompt:
 
 ```
-Find the @adobe/data-ai package on npmjs and then install it in the current directory.
-Next use it's /build-application skill to build <prompt here>
+Set up @adobe/data-ai in the current directory: run
+`npx @adobe/data-ai@latest install` (this copies the bundle and pins the exact
+version so rules auto-update on every install). On Claude Code also add the
+skills plugin per the package README. Then use its /build-application skill to
+build <prompt here>
 ```

package/bin/cli.mjs

@@ -157,6 +157,78 @@ version on every install. Package: <https://www.npmjs.com/package/${PKG_NAME}>
     return file;
 }
 
+// Wire the consumer repo for auto-updating installs (part of `install`, not a
+// separate step). Idempotently:
+//   1. pins `@adobe/data-ai` in devDependencies (exact version — never a range,
+//      so an install can't silently pull an unreviewed release),
+//   2. adds `data-ai install` to the consumer's OWN `postinstall` (a dependency's
+//      lifecycle script does NOT run under pnpm, so it must live here), and
+//   3. gitignores the managed, regenerated bundle folders.
+// After this, bumping the pinned version and re-installing recopies the bundle —
+// no manual step, no committed diff. Skips gracefully with a note when there is
+// no package.json (the bundle is still copied; the repo just isn't auto-wired).
+const MANAGED_GITIGNORE = [
+    `# ${PKG_NAME} — managed, regenerated on install; do not edit or commit`,
+    ".claude/rules/adobe-data-ai/",
+    ".claude/rules/adobe-data-ai-bootstrap.md",
+    ".agents/skills/adobe-data-ai/",
+];
+
+function wireManagedUpdates(base) {
+    const pkgPath = join(base, "package.json");
+    if (!existsSync(pkgPath)) {
+        process.stdout.write(
+            `  (no package.json in ${base} — auto-update not wired; the bundle was still copied.\n` +
+                `   Add one, re-run install to wire it, or re-run manually to update.)\n`,
+        );
+        return;
+    }
+    const consumer = JSON.parse(readFileSync(pkgPath, "utf8"));
+    const changes = [];
+
+    // 1. pinned devDependency
+    consumer.devDependencies ??= {};
+    let pinnedDep = false;
+    if (consumer.devDependencies[PKG_NAME] !== VERSION) {
+        consumer.devDependencies[PKG_NAME] = VERSION;
+        changes.push(`devDependencies["${PKG_NAME}"] = "${VERSION}" (exact)`);
+        pinnedDep = true;
+    }
+
+    // 2. own postinstall runs the installer (chain if one already exists)
+    consumer.scripts ??= {};
+    const INSTALL = "data-ai install";
+    const post = consumer.scripts.postinstall;
+    if (!post) {
+        consumer.scripts.postinstall = INSTALL;
+        changes.push(`scripts.postinstall = "${INSTALL}"`);
+    } else if (!post.includes(INSTALL)) {
+        consumer.scripts.postinstall = `${post} && ${INSTALL}`;
+        changes.push(`scripts.postinstall += " && ${INSTALL}"`);
+    }
+    if (changes.length) writeFileSync(pkgPath, JSON.stringify(consumer, null, 2) + "\n");
+
+    // 3. gitignore the managed bundle folders
+    const giPath = join(base, ".gitignore");
+    const gi = existsSync(giPath) ? readFileSync(giPath, "utf8") : "";
+    if (!gi.includes(MANAGED_GITIGNORE[0])) {
+        const sep = gi === "" ? "" : gi.endsWith("\n") ? "\n" : "\n\n";
+        writeFileSync(giPath, gi + sep + MANAGED_GITIGNORE.join("\n") + "\n");
+        changes.push(".gitignore += managed bundle paths");
+    }
+
+    for (const c of changes) process.stdout.write(`  wired: ${c}\n`);
+    if (!changes.length) process.stdout.write("  auto-update already wired\n");
+    // Adding/repinning the dev-dependency leaves the lockfile out of sync until a
+    // normal install records it (and CI with a frozen lockfile would fail until then).
+    if (pinnedDep) {
+        process.stdout.write(
+            "\nNext: run your package manager's install to sync the lockfile\n" +
+                "  pnpm install    # or npm install / yarn\n",
+        );
+    }
+}
+
 function parseArgs(argv) {
     const positional = [];
     const flags = new Set();
@@ -177,11 +249,17 @@ Install the architecture skills + rules for Cursor, Codex, and other agents.
 same way for every agent — see README.)
 
 Usage:
-  npx ${PKG_NAME}@latest install [options]
+  npx ${PKG_NAME}@latest install   # copy the bundle AND wire auto-updates (default)
   npx ${PKG_NAME}@latest list
 
 Commands:
-  install   Skills → .agents/skills/${BUNDLE}/, rules → .claude/rules/${BUNDLE}/ (default).
+  install   Copy the bundle (skills → .agents/skills/${BUNDLE}/, rules →
+            .claude/rules/${BUNDLE}/) AND wire this repo for auto-updating installs:
+            pin ${PKG_NAME} in devDependencies (exact), add \`data-ai install\` to the
+            repo's own postinstall, and gitignore the managed bundle folders. Run once;
+            thereafter a plain install refreshes the bundle and bumping the pinned
+            version updates it. Skips the wiring (copies only) with \`--global\` or when
+            there's no package.json.
   list      Print the skills bundled in this package.
 
 Options:
@@ -229,6 +307,10 @@ function main() {
     process.stdout.write(`  ${skills.length} skills → ${skillsDir}\n`);
     process.stdout.write(`  ${ruleCount} rules  → ${rulesDir}\n`);
     process.stdout.write(`  bootstrap → ${bootstrapFile}\n`);
+
+    // A project install also wires the repo for auto-updating installs (idempotent).
+    // A global install has no consumer package.json to wire, so it only copies.
+    if (!flags.has("global")) wireManagedUpdates(base);
 }
 
 main();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/data-ai",
-  "version": "0.9.92",
+  "version": "0.9.93",
   "description": "Cross-agent architecture skills for @adobe/data — installable as a Claude Code plugin or copied into any Agent-Skills-compatible agent (Cursor, Codex).",
   "type": "module",
   "private": false,
@@ -29,12 +29,12 @@
     "skills"
   ],
   "peerDependencies": {
-    "@adobe/data": "0.9.92"
+    "@adobe/data": "0.9.93"
   },
   "devDependencies": {
     "typescript": "^5.8.3",
     "vitest": "^1.6.0",
-    "@adobe/data": "0.9.92"
+    "@adobe/data": "0.9.93"
   },
   "license": "MIT",
   "scripts": {