@adobe/data-ai 0.9.84 → 0.9.87

package/.claude/rules/observe.md

@@ -0,0 +1,183 @@
+---
+paths:
+  - '**/services/**/*.ts'
+  - '**/*-plugin.ts'
+  - '**/*-plugin/**/*.ts'
+  - '**/*dependent-state*.ts'
+  - '**/*dependent-state*/**/*.ts'
+---
+
+# Observe pattern
+
+`Observe<T>` from `@adobe/data/observe` — a subscription function: `(notify: (value: T) => void) => Unobserve`. Callback may be invoked
+synchronously or asynchronously, zero or more times. Returns `Unobserve` to stop observing.
+
+**Always use `Observe.*` helpers to create and manipulate observables. Never write raw subscriptions or manual notify wrappers** — the
+standard helpers cover every composition need and keep the code consistent.
+
+---
+
+## Creation helpers
+
+| Helper                               | Usage                                              |
+| ------------------------------------ | -------------------------------------------------- |
+| `Observe.fromConstant(value)`        | `Observe<T>` from a constant value                 |
+| `Observe.fromProperties({ a, b })`   | Combine named observables into `Observe<{ a, b }>` |
+| `Observe.fromArray([obs1, obs2])`    | Combine array of observables into `Observe<T[]>`   |
+| `Observe.fromPromise(() => Promise)` | Lazy; notifies once when promise resolves          |
+| `Observe.createState(initial?)`      | `[Observe<T>, (value: T) => void]` — mutable state |
+
+```ts
+const constant = Observe.fromConstant(42);
+const combined = Observe.fromProperties({ a: db.observe.resources.a, b: db.observe.resources.b });
+const [count, setCount] = Observe.createState(0);
+```
+
+---
+
+## Transformation helpers
+
+| Helper                              | Usage                                                        |
+| ----------------------------------- | ------------------------------------------------------------ |
+| `Observe.withMap(obs, fn)`          | Transform value; map from one type to another                |
+| `Observe.withFilter(obs, fn)`       | Transform or filter; return `undefined` to skip              |
+| `Observe.withDefault(default, obs)` | Use default when value is undefined                          |
+| `Observe.withLazy(() => obs)`       | Defer expensive observable creation until first subscription |
+| `Observe.withUnwrap(obs)`           | Flatten `Observe<Observe<T>>` to `Observe<T>`                |
+
+```ts
+const doubled = Observe.withMap(count, n => n * 2);
+const max = Observe.withFilter(Observe.fromProperties({ a, b }), ({ a, b }) => Math.max(a, b));
+const withFallback = Observe.withDefault('unknown', maybeName);
+```
+
+---
+
+## Conversion helpers
+
+| Helper                   | Usage                               |
+| ------------------------ | ----------------------------------- |
+| `Observe.toPromise(obs)` | Resolve with first value (one-shot) |
+
+`Observe.toPromise` is for services reading a current value — **never use it in UI elements**.
+
+---
+
+## ⛔ Antipattern: synchronous "peek"
+
+**Never read an observable's current value by subscribing and immediately unsubscribing.** The `notify` callback may fire asynchronously
+(auth state, network, derived chains), so the snapshot is stale or `undefined`.
+
+```ts
+// WRONG — only works if the observable happens to emit synchronously on subscribe
+let value: T | undefined;
+const unobserve = someObservable(v => {
+  value = v;
+});
+unobserve();
+// use `value`  ← undefined for any async-resolving observable
+```
+
+```ts
+// CORRECT — resolve the current value explicitly
+const value = await Observe.toPromise(someObservable);
+```
+
+A stored `unobserve` is **only** ever for deferred teardown (returned from an Effect, called on unmount/cleanup) — never to bookend a
+synchronous read. If a sync call site (e.g. a DOM event handler that must call `preventDefault()` before any `await`) needs the value, do
+the synchronous work first, then `void asyncHelper(...)` that awaits `Observe.toPromise`. In a Lit render path, read reactive values through
+`useObservableValues`, not `toPromise`.
+
+---
+
+## ⛔ Antipattern: `undefined` as an Observe data value
+
+`@adobe/data/observe` reserves `undefined` to mean **"no value has been emitted yet"** — it gates the synchronous initial emit in
+`Observe.createState`, `fromProperties`, and friends. A data value flowing through an Observe pipeline must use `null` for the absent case,
+**never** `undefined`.
+
+```ts
+// WRONG — Observe<X | undefined>
+const [projectId, setProjectId] = Observe.createState<ProjectId | undefined>(undefined);
+return Observe.withDefault(undefined, cloudSync.projectName);
+
+// CORRECT — Observe<X | null>
+const [projectId, setProjectId] = Observe.createState<ProjectId | null>(null);
+return Observe.withDefault<string | null>(null, cloudSync.projectName);
+```
+
+Why it bites:
+
+- `createState<T | undefined>(undefined)` does **not** fire on subscribe (the implementation treats `undefined` as "not yet set"), so
+  downstream `useObservableValues` callers wait forever for a value that never arrives.
+- `fromProperties` re-emits when an input flips `undefined → defined`, not when a value changes — using `undefined` as data corrupts the
+  dirty-tracking.
+- `null` JSON-stringifies across the wire; `undefined` silently disappears.
+
+When auditing new code, flag `Observe<… | undefined>`, `createState<… | undefined>`, `withDefault(undefined`, and `fromConstant(undefined)`
+— each should use `null`. (A plain function returning `undefined`, e.g. an early `return` from an async helper, is unrelated and fine.)
+
+---
+
+## ⛔ Antipattern: membership-only subscription for value reads (ECS)
+
+`db.observe.select(archetype.components)` fires **only when entities enter or leave the archetype** — i.e. on set-membership changes. It
+does **not** fire when a component value changes on an entity already in the set. If the callback reads component **values**, this
+subscription is almost always wrong: it emits once on load, then silently stops reacting when the user edits values (opacity slider,
+selection toggle, drag end). The derived state goes stale with no error — the hardest bug to catch.
+
+Pick the subscription by what the callback reads:
+
+| Callback needs                                                          | Use                                                       |
+| ----------------------------------------------------------------------- | --------------------------------------------------------- |
+| Entity **IDs** only ("how many items," "does this track have children") | `db.observe.select(archetype.components)`                 |
+| Component **values** (any `db.get(id, 'field')` in a map/filter)        | `Database.observeSelectDeep(db, [...fields] as const)`    |
+| A single UI element bound to one entity                                 | `db.observe.entity(id)` / `observe.entity(id, archetype)` |
+
+```ts
+// WRONG — reads values but only reacts to add/remove; value edits never re-run this
+Observe.withMap(db.observe.select(archetype.components), ids => ids.filter(id => (db.get(id, 'selectedByUsers') ?? []).includes(userId)));
+
+// CORRECT — value-tracking subscription; list exactly the fields read downstream
+const SELECTED_FIELDS = ['selectedByUsers'] as const; // hoist the tuple above the factory
+const rows$ = Database.observeSelectDeep(db, SELECTED_FIELDS);
+Observe.withMap(rows$, rows => rows.filter(r => r.selectedByUsers?.includes(userId)).map(r => r.id));
+```
+
+`observeSelectDeep` re-emits on **any** change to **any** listed component on **any** matched entity — so list only the fields actually
+read, and when the matched set is large pair it with a structural deduplicate downstream so identical-looking emissions don't propagate
+(`@adobe/data/observe`'s `withDeduplicate` is reference-equality only). `observeSelectDeep` from a UI element is banned — let each element
+observe its own entity (see `.claude/rules/ecs.md` and `.claude/rules/squirrel/ui-data-access.md`).
+
+---
+
+## Common patterns
+
+**Derived observable from service:**
+
+```ts
+export const isDevelopment = memoize((service: Pick<EnvironmentService, 'type'>) =>
+  Observe.withMap(service.type, type => type === 'development')
+);
+```
+
+**Computed from multiple resources:**
+
+```ts
+Observe.withFilter(Observe.fromProperties({ a: db.observe.resources.a, b: db.observe.resources.b }), ({ a, b }) => Math.max(a, b));
+```
+
+**Lazy creation:** `Observe.withLazy(() => expensiveObs)` — defers until first subscription.
+
+---
+
+## Execute
+
+When adding or using Observe:
+
+1. Use `Observe.fromConstant` for static values.
+2. Use `Observe.fromProperties` to combine multiple observables.
+3. Use `Observe.withFilter` when mapping and/or filtering.
+4. Use `Observe.createState` for mutable state with a setter.
+5. Use `Observe.withUnwrap` to flatten `Observe<Observe<T>>`.
+6. Call `unobserve()` when cleaning up (e.g. component unmount).

package/.claude/rules/react.md

@@ -0,0 +1,102 @@
+---
+paths:
+  - '**/*.tsx'
+---
+
+# React component authoring
+
+React components live in the `components/` layer. Consume Observe and void actions from plugins. Use `@adobe/data-react` for `useDatabase`,
+`useObservableValues`, and `DatabaseProvider`.
+
+---
+
+## useDatabase — single context
+
+Binding components **must** call `useDatabase` to obtain the main service context. Do **not** access any other React context. Additional
+contexts create a context waterfall and hurt performance. All other services and state are reachable from the database.
+
+---
+
+## Binding component vs presentation
+
+**Binding component** — the React component that:
+
+- Injects observed values via `useObservableValues`
+- Triggers re-render when those values change
+- Binds action callbacks to the presentation
+
+**Presentation** — a pure function (no hooks) that receives data and action callbacks as props and returns JSX. Keep reactive logic in the
+binding component; presentation stays pure.
+
+---
+
+## Props from parent
+
+**Do not** pass values from parent except when needed to identify which entity in the database to bind to.
+
+```tsx
+// Parent: passes entity so child knows which record to bind to
+{
+  values.sprites.map(entity => <Sprite key={entity} entity={entity} />);
+}
+
+// Child: uses entity prop to observe the right record
+function Sprite({ entity }: { entity: Entity }) {
+  const db = useDatabase();
+  const values = useObservableValues(() => ({ sprite: db.observe.entity(entity, db.archetypes.Sprite) }), [entity]);
+}
+```
+
+---
+
+## useObservableValues
+
+_Most_ binding components use a **single** `useObservableValues` call. Collect all observed values in one object. Use `Observe.withDefault`
+for values that may resolve slowly.
+
+```tsx
+function Counter() {
+  const db = useDatabase(counterPlugin);
+  const values = useObservableValues(() => ({
+    count: db.observe.resources.count,
+  }));
+  if (!values) return null;
+  return presentation.render({ ...values, increment: db.transactions.increment });
+}
+```
+
+---
+
+## Presentation exports
+
+Presentation files ONLY export `render` (and localization bundles where appropriate). Nothing else. If you need render args type externally,
+use `Parameters<typeof render>[0]`.
+
+---
+
+## Action callbacks (not events)
+
+Use **verb** or **verbNoun** names — never `on*` prefix. See `.claude/rules/presentation.md` for full examples.
+
+**Pass function references directly** when the signature matches; wrap in an arrow function only to supply arguments:
+
+```tsx
+increment: db.transactions.increment; // reference — no wrapper needed
+toggleSprite: () => db.transactions.toggleSpriteActive({ entity }); // args required — wrap
+```
+
+---
+
+## Execute
+
+When creating or modifying a React component:
+
+1. Call `useDatabase` for the main service context. Do not use any other React context.
+2. Split into binding component (reactive) and presentation (pure).
+3. Use a single `useObservableValues` in the binding component.
+4. Pass observed values and action callbacks to presentation. Pass function references directly when the signature matches; wrap only when
+   supplying arguments.
+5. Keep presentation pure — no hooks.
+6. Presentation exports only `render` (and localization bundles where appropriate).
+7. Add `*-presentation.test.tsx` for presentation when appropriate; do not unit test binding components.
+8. Never include business logic within binding components. Move into computed values or action handlers.

package/.claude/rules/service.md

@@ -0,0 +1,164 @@
+---
+paths:
+  - '**/services/**/*.ts'
+  - '**/*-service.ts'
+---
+
+# Service authoring
+
+Asynchronous data services. Live in the `services/` layer. Adhere to the namespace rule for type and function organization.
+
+**Data** = readonly JSON values or Blobs.
+
+---
+
+## Front-end vs back-end services
+
+**Front-end services** — called directly from UI components. Support unidirectional control flow.
+
+| Allowed                         | Not allowed                      |
+| ------------------------------- | -------------------------------- |
+| `Observe<Data>`                 | Promise or AsyncGenerator return |
+| Other services (sub-Services)   |                                  |
+| Void-returning action functions |                                  |
+
+**Back-end services** — usually stateless. Functions typically return `Promise<Data>` or `AsyncGenerator<Data>`. Not called directly from
+UI; front-end services call them.
+
+This separation keeps UI components on a strict unidirectional path: data down via void actions, data up via Observe.
+
+---
+
+## Front-end service constraints
+
+`Service` interfaces for UI consumption may only contain:
+
+- **`Observe<Data>`** — observable properties or factories
+- **Sub-Service**s — nested service interfaces
+- **Action functions** — zero or more `Data` arguments, return `void` only
+- **Factory functions** — create observables or sub-Services
+
+Compile-time check: `Assert<AsyncDataService.IsValid<ServiceInterface>>`.
+
+---
+
+## Folder structure and cohesion
+
+**MUST NOT** place implementation files alongside the interface file. The `<name>-service/` folder MUST contain only the interface file and
+`public.ts`.
+
+```
+services/<name>-service/
+  <name>-service.ts          ← interface + contract types; `export * as ServiceName from './public.js'` at bottom
+  public.ts                  ← re-exports factory (and other public exports) from the implementation sub-folder
+  <impl-name>/               ← REQUIRED sub-folder for all implementation files
+    create-<name>-service.ts ← factory function
+    *.ts                     ← helpers, utils, constants (implementation-private)
+    *.test.ts                ← tests live here alongside implementation
+```
+
+**Single-file exception**: a bare factory with no helpers, no utilities, and no constants MAY live as a flat file alongside the interface.
+The moment any additional implementation file is needed, the factory MUST move into a sub-folder.
+
+**Interface file** (`<name>-service.ts`) — interface declaration and types that define the public service contract. MUST NOT import from any
+implementation file or sub-folder. At the bottom of the file, exports the namespace: `export * as ServiceName from './public.js'`. This
+merges the interface type and the factory namespace under one identifier — callers type against the interface and invoke factory functions
+through the same name.
+
+**Separate types file at the interface level** — only permitted if it contains exclusively public-contract types (types that appear in the
+interface's method signatures or `Observe<>` generic arguments). Implementation-detail types — third-party API shapes, `window.*` global
+augmentations, internal utilities — MUST live inside the implementation sub-folder.
+
+**`*.test.ts` files MUST NOT appear at the interface folder level.** Every test file belongs inside the implementation sub-folder next to
+the code it tests; there is nothing at the interface level to test.
+
+**Implementation sub-folder** — all implementation logic including the factory, utilities, constants, helpers, and their tests. MUST NOT
+depend on the interface file's types via the `public.js` re-export; import directly from `<name>-service.js`.
+
+**public.ts** — MUST re-export the factory function and any other public exports from the implementation sub-folder. Does NOT re-export the
+interface — the interface is exported directly from `<name>-service.ts`.
+
+**No classes** — factory function or static plain object only. `this` bindings are brittle and block higher-order composition.
+
+---
+
+## Factory export shape — `singletonFactory` + dual export
+
+Every service factory MUST be wrapped with `singletonFactory` from `factory-functions.js`. This guarantees one instance per argument tuple
+when the same factory is called multiple times, preventing duplicate subscriptions and torn state.
+
+Export **both** the raw `factory` and the singleton-wrapped `create`:
+
+```ts
+// <name>-service/<impl-name>/create-<name>-service.ts
+import { singletonFactory } from 'factory-functions.js';
+
+export const factory = (deps: Deps): NameService => {
+  // implementation
+};
+
+// `factory` — for test injection (bypasses the singleton cache; each test gets a fresh instance)
+// `create`  — for production use (singleton per deps-tuple)
+export const create = singletonFactory(factory);
+```
+
+`public.ts` re-exports both:
+
+```ts
+export { create, factory } from './<impl-name>/create-<name>-service.js';
+```
+
+**Why:** Tests must create fresh instances without sharing a singleton cache. Production callers use `create`; tests that need isolation
+import `factory` directly.
+
+---
+
+## Service interface cleanliness
+
+The `<name>-service.ts` interface MUST NOT reference internal implementation tools, third-party SDK names, or infrastructure system
+identifiers in any method signature, property name, or type parameter.
+
+**Wrong** — leaks an internal infrastructure name into the UI contract:
+
+```ts
+interface SessionService extends Service {
+  readonly dunamis: DunamisSdk; // UI now knows Dunamis exists
+}
+```
+
+**Correct** — surfaces only what UI needs, implementation-tool-agnostic:
+
+```ts
+interface SessionService extends Service {
+  readonly sessionId: Observe<string>;
+}
+```
+
+The interface is the contract between UI and data layers. If the underlying tool is swapped (Dunamis → another SDK, cookies → localStorage),
+the interface must not change. Any leak of an internal tool name into the interface couples the UI to an implementation detail it must not
+know about.
+
+---
+
+## Execute
+
+When creating or modifying a service:
+
+1. Place in `services/<name>-service/`.
+2. Interface in `<name>-service.ts` — types only, extend `Service`, add `Assert<AsyncDataService.IsValid<>>`.
+3. All implementation files go inside a named sub-folder (e.g. `create-<name>-service/`).
+4. At the bottom of `<name>-service.ts`, add `export * as ServiceName from './public.js'`.
+5. In `public.ts`, re-export the factory (and any other public exports) from the implementation sub-folder.
+6. For front-end services: actions return void only; observables observe Data or Service only. For back-end services: functions return
+   `Promise<Data>` or `AsyncGenerator<Data>`.
+
+---
+
+## Verify
+
+When any `src/**/services/**/*.ts` file is in the diff, confirm all three invariants:
+
+1. **Interface/implementation separation** — every `.ts` file added or modified in `<name>-service/` is either `<name>-service.ts`,
+   `public.ts`, or inside a named sub-folder. Any file at the root of the folder that is neither is a violation.
+2. **`public.ts` completeness** — `public.ts` re-exports the factory function (and any other public exports from the sub-folder).
+3. **Interface file purity** — `<name>-service.ts` contains no imports from implementation sub-folders.

package/.claude/rules/type-casts.md

@@ -1,7 +1,7 @@
 ---
 paths:
-  - 'packages/**/*.ts'
-  - 'packages/**/*.tsx'
+  - '**/*.ts'
+  - '**/*.tsx'
 ---
 
 # Type casts — only two valid uses

package/.claude-plugin/plugin.json

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

package/README.md

@@ -18,15 +18,22 @@ It installs two things:
 
 ## Install — Claude Code
 
-Skills load as a marketplace plugin; rules install into the project.
+Skills load as a marketplace plugin; rules install into the project. Run these
+three from a shell (agent-runnable):
 
 ```
-/plugin marketplace add adobe/data
-/plugin install adobe-data-ai@adobe-data-skills
+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
 ```
 
-- Skills → the `adobe-data-ai` plugin. **Update:** `/plugin` → update `adobe-data-ai`.
+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).
+
+- 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`.
 
 ## Install — Cursor (and Codex / other `.agents` agents)
@@ -58,3 +65,16 @@ by name when you want a single phase or a specialized flow: `build-data`,
 `build-ui`, `build-app-entry`; plus `build-game`, `meta-build` (phase-by-phase
 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.
+
+This presumes you are already running the agent within the directory you want to use as your project root.
+
+```
+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>
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/data-ai",
-  "version": "0.9.84",
+  "version": "0.9.87",
   "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.84"
+    "@adobe/data": "0.9.87"
   },
   "devDependencies": {
     "typescript": "^5.8.3",
     "vitest": "^1.6.0",
-    "@adobe/data": "0.9.84"
+    "@adobe/data": "0.9.87"
   },
   "license": "MIT",
   "scripts": {

package/skills/build-actions/SKILL.md

@@ -1,10 +1,12 @@
 ---
 name: build-actions
-description: Build a feature's ecs action-database — async orchestration over services and transactions. If the feature has async flows.
+description: Build a feature's ecs action-database — async orchestration over services and transactions. If the feature has async flows or side effects outside of the main store.
 input: feature
 output: feature
 ---
 
+Skip if this feature doesn't contain or require actions.
+
 Create `ecs/action-database/`: `action-database.ts` (extends `ServiceDatabase`, adds `actions`
 from `./actions/index.js`) plus an `actions/` folder — one async orchestrator per file. An action
 takes `db: ServiceDatabase`, awaits `services/` ports, then commits **exactly one** transaction.

package/skills/build-application/SKILL.md

@@ -5,6 +5,8 @@ input: app
 output: app
 ---
 
-/build-feature (base — features/main)
-|> /build-feature (each peer feature)
-|> /build-app-entry
+/graph-execute
+    /build-feature (base — features/main)
+    for each sub feature
+        /build-feature
+    /build-app-entry

package/skills/build-computed/SKILL.md

@@ -5,6 +5,8 @@ input: feature
 output: feature
 ---
 
+Skip if this feature doesn't contain or require computed values.
+
 Create `ecs/computed-database/`: `computed-database.ts` (extends the previous layer, adds
 `computed` from `./computed/index.js`) plus a `computed/` folder — one `cached` derived value
 per file + barrel. Derivation logic lives in `data/`; a computed only wires a db observable to it.

package/skills/build-data/SKILL.md

@@ -11,6 +11,10 @@ and other `data/` declarations):
 - one namespace folder per data type — `<type>/{<type>.ts, schema.ts, public.ts, <helper>.ts}`;
 - `data/state/` — the `State` aggregate plus its pure transforms/derivations.
 
+**Always create `data/state/`** — even for a shell feature whose only field is a
+boolean or enum. A feature with ECS resources/transactions but no `State` is
+incomplete: the transaction must wrap a pure transform, not invent the logic. In rare circumstances, there may be no real state in a feature in which case the state type = {}
+
 The schema is the single source of truth; the type derives from it (`Schema.ToType`).
 Helpers are pure and unit-tested. Run this first — every other layer imports `data/`.
 

package/skills/build-feature/SKILL.md

@@ -1,21 +1,18 @@
 ---
 name: build-feature
-description: Build a complete feature by piping the per-layer build-* skills bottom-up.
+description: Build a complete feature step by step
 input: feature
 output: feature
 ---
 
-/build-data
-|> /build-services
-|> /build-core-database
-|> /build-indexes
-|> /build-transactions
-|> /build-computed
-|> /build-systems
-|> /build-service-database
-|> /build-actions
-|> /build-ui
-
-Run with /x-execute. Each step is a no-op for a layer the feature doesn't use
-(`build-systems` only for real-time features; `build-services` / `build-service-database` /
-`build-actions` only when the feature has async flows).
+/graph-execute
+    /build-data
+    /build-services
+    /build-core-database
+    /build-indexes
+    /build-transactions
+    /build-computed
+    /build-service-database
+    /build-actions
+    /build-systems
+    /build-ui

package/skills/build-game/SKILL.md

@@ -15,5 +15,7 @@ transactions = moves/spawns, computed = score/status/winner, ui = view + input.
   (see data-lit-tictactoe).
 - **Real-time** adds the `build-systems` phase: a per-frame tick loop (movement,
   collision, lifetime) driven by the scheduler, over many entities in distinct
-  archetypes. This is where components, archetypes, indexes, and systems all
-  carry real weight — see `features/ecs/systems.md`.
+  archetypes. Systems must stay O(1) per touched entity — never project the whole
+  `State` into/out of the store each frame (see `features/ecs/systems.md`).
+  This is where components, archetypes, indexes, and systems all carry real
+  weight.

package/skills/build-indexes/SKILL.md

@@ -5,6 +5,8 @@ input: feature
 output: feature
 ---
 
+Skip if this feature doesn't contain or require indexes.
+
 Create `ecs/index-database/`: `index-database.ts` (extends `CoreDatabase`, adds the `indexes`
 facet from `./indexes/index.js`) plus an `indexes/` folder — one index per file + an `index.ts`
 barrel.

package/skills/build-services/SKILL.md

@@ -5,6 +5,8 @@ input: feature
 output: feature
 ---
 
+Skip if this feature doesn't contain or require services.
+
 Create the feature's `services/` layer: one `<name>-service/` namespace folder per async
 contract — an `interface` (validated with `AsyncDataService.IsValid`), async-only members,
 and `create*` factories.