@adobe/data-ai 0.10.21 → 0.10.23

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

@@ -1,13 +1,18 @@
 ---
 paths:
   - '**/features/*/ui/**/*.ts'
+  - '**/features/*/ui/**/*.tsx'
 ---
 
 # ui/ — user interface
 
-The top layer: UI that binds the `services/main-service/` database to what the user sees. It
-owns no business logic — it subscribes to state, hands it to a pure
-presentation, and wires actions back to transactions.
+The top layer: UI that binds the feature's `MainService` database (`ecs/main-service.ts`)
+to what the user sees. It owns no business logic — it subscribes to state, hands it to
+a pure presentation, and wires user input to `service.actions.*`.
+
+Each feature has one base element (Lit: `ui/<feature>-element.ts`, a
+`DatabaseElement` typed on its `MainService.plugin`; React: a `use-main-service.ts`
+hook) that every element of the feature builds on.
 
 The folder name is framework-neutral; its contents are framework-specific
 (Lit elements, React components, …). Each UI unit is its own folder, named

package/.claude/rules/features/ui/lazy-wrapper.md

@@ -1,7 +1,7 @@
 ---
 paths:
-  - 'src/**/elements/**/*.ts'
-  - 'src/**/ui/**/*.ts'
+  - '**/src/**/elements/**/*.ts'
+  - '**/src/**/ui/**/*.ts'
 ---
 
 # Lazy Wrapper

package/.claude/rules/features/ui/presentation-test.md

@@ -1,6 +1,7 @@
 ---
 paths:
   - '**/*presentation.test.ts'
+  - '**/*presentation.test.tsx'
 ---
 
 ## Testing

package/.claude/rules/features/ui/presentation.md

@@ -1,6 +1,7 @@
 ---
 paths:
   - '**/*presentation.ts'
+  - '**/*presentation.tsx'
 ---
 
 # Presentation authoring

package/.claude/rules/global/function-references.md

@@ -11,12 +11,12 @@ When a value is already a function with the signature the callee wants, pass it
 
 ```ts
 // ❌ identity wrappers — the arrow adds nothing
-expectConforms({ spec: (s, dt) => State.resolveBulletHits(s, dt), apply: (store, a) => hitAsteroid(store, a) });
+cached((db) => Observe.withFilter(db.observe.resources.board, (b) => BoardState.deriveStatus(b)));
 onClick={() => save()}
 todos.map((t) => render(t))
 
 // ✅ pass the function itself
-expectConforms({ spec: State.resolveBulletHits, apply: hitAsteroid });
+cached((db) => Observe.withFilter(db.observe.resources.board, BoardState.deriveStatus));
 onClick={save}
 todos.map(render)
 ```

package/.claude/rules/global/namespace.md

@@ -6,7 +6,8 @@ paths:
 # Type namespace pattern
 
 Single import surface per type: `<type-name>/<type-name>.ts`. Schema in `-schema.ts`, namespace re-export from `public.js`. Types live in
-the `types/` layer.
+the `types/` layer. **In a feature**, Data types live in `features/<name>/data/values/<type>/` with the schema in `schema.ts`
+(`features/data/values.md`).
 
 ## Authority
 
@@ -161,5 +162,4 @@ Example — a type merged with one value export and any number of type-only memb
     }
 
 The canonical use is a feature's `core-database.ts` / layered `*-database.ts` (a
-`plugin` value plus `Store` / `Index` / `Component` / `Archetype` types) — see
-`features/services/main-service/core-database.md`.
+`plugin` value plus `Store` / `Index` types) — see `features/ecs/core.md`.

package/.claude/rules/global/react.md

@@ -5,7 +5,7 @@ paths:
 
 # React component authoring
 
-React components live in the `components/` layer. Consume Observe and void actions from plugins. Use `@adobe/data-react` for `useDatabase`,
+React components live in the `ui/` layer (`features/ui/`). Consume Observe and void actions from plugins. Use `@adobe/data-react` for `useDatabase`,
 `useObservableValues`, and `DatabaseProvider`.
 
 ---
@@ -61,7 +61,7 @@ function Counter() {
     count: db.observe.resources.count,
   }));
   if (!values) return null;
-  return presentation.render({ ...values, increment: db.transactions.increment });
+  return presentation.render({ ...values, increment: db.actions.increment });
 }
 ```
 
@@ -81,8 +81,8 @@ Use **verb** or **verbNoun** names — never `on*` prefix. See `features/ui/pres
 **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
+increment: db.actions.increment; // reference — no wrapper needed
+toggleSprite: () => db.actions.toggleSpriteActive({ entity }); // args required — wrap
 ```
 
 ---

package/.claude/rules/lit.md

@@ -7,7 +7,7 @@ paths:
 
 # Lit element authoring
 
-Lit elements live in the `components/` layer per the structure rule. Consume Observe and void actions from plugins per the service rule.
+Lit elements live in the `ui/` layer (`features/ui/`). Consume Observe and void actions from plugins per the service rule.
 
 ---
 
@@ -58,7 +58,7 @@ render() {
     userProfile: this.service.services.authentication.userProfile,
   }));
   if (!values) return;
-  return presentation.render({ ...values, toggleView: () => this.service.transactions.setViewVisible({ name, visible: true }) });
+  return presentation.render({ ...values, toggleView: () => this.service.actions.setViewVisible({ name, visible: true }) });
 }
 ```
 

package/.claude/rules/plugin-modelling.md

@@ -31,6 +31,8 @@ authoring abstraction.
 
 ## File naming
 
+Outside `features/`. Inside a feature, the `features/ecs/` naming applies (`<layer>-database.ts`).
+
 Each file whose primary export is a `Database.Plugin` (created or
 combined) ends in `-plugin.ts` — e.g. `node-plugin.ts`, `model-plugin.ts`,
 `pbr-core-plugin.ts`. The suffix is for discovery: cursor rules,

package/.claude/rules/service.md

@@ -6,6 +6,8 @@ paths:
 
 # Service authoring
 
+> Inside a feature, `features/services/index.md` governs the folder layout: a small service keeps `create.ts` and `create-fake.ts` flat beside the interface (the single-file exception below); one with helpers moves its implementation into a sub-folder. Database-bound factories in `ecs/services/` follow `features/ecs/services.md`.
+
 Asynchronous data services. Live in the `services/` layer. Adhere to the namespace rule for type and function organization.
 
 **Data** = readonly JSON values, `ReadonlySet`, `ReadonlyMap`, or Blobs.

package/.claude/rules/versioning.md

@@ -12,6 +12,9 @@ persisted document can be upgraded to the current schema on load. You (human or
 agent) should almost never have to reason about this by hand: **change the schema,
 run the tests, and the failing test prints the exact fix to apply.**
 
+The history lives in the app root, `src/app/versioning/` (`app.md`), because the
+persisted data covers every feature's schema in the database.
+
 ## The pieces (all from `@adobe/data/ecs`)
 
 - **`versions.ts`** — `export const versions: readonly VersionEntry[]`. `entries[i]`
@@ -59,7 +62,7 @@ run the tests, and the failing test prints the exact fix to apply.**
    writes to SEVERAL components (a cross-component move, deriving a new component from
    others, splitting one into many) must be hand-written to your upgrade algorithm:
    query the input components, compute, and write the outputs directly on the store.
-   Add a test case either way (rule 6).
+   Add a test case either way (the guard test below).
 5. **Removing a component drops its data.** If the data still matters, migrate it in a
    handler BEFORE the removal entry.
 6. **Versioned schemas must be REAL** — declare a `type` (or `enum`/`const`), and the
@@ -83,7 +86,7 @@ history. Its message is a literal recipe. To fix it:
    and the `changes` block the error printed verbatim. `db.version` follows the history
    automatically (`= versions.length - 1`) — there is no resource default to update.
 2. If the error marks a change **BREAKING — needs a handler**, add a `handler` to that
-   entry AND add a matching test case under `testUpgradeHandlers` (rule 6). The error
+   entry AND add a matching test case under `testUpgradeHandlers` (the guard test below). The error
    may point at `Store.remapComponent(...)` for an isolated single-component change, but
    that is only a suggestion — write whatever upgrade code the change actually needs.
 
@@ -97,17 +100,17 @@ schema (schema coverage) AND every entry with a `handler` has a passing test cas
 
 ```ts
 import { Database, assertVersioning, createVersionUpgrader } from "@adobe/data/ecs";
-import { MainService } from "../main-service.js";
+import { AppSchema } from "../schema.js";
 import { versions } from "./versions.js";
 
 describe("database schema versions", () => {
   it("the version history is consistent (schema folds + every handler tested)", () =>
     assertVersioning({
       // the version-configured db, so db.version = the history's current version
-      database: Database.create(MainService.plugin, { versioning: createVersionUpgrader(versions) }),
+      database: Database.create(AppSchema.plugin, { versioning: createVersionUpgrader(versions) }),
       entries: versions,
       handlers: {
-        // Append a case per version that adds a `handler` (rule 6):
+        // Append a case per version that adds a `handler` (the guard test below):
         // <version>: { setup: (store) => <populate the version-(v-1) store, return entities>,
         //              expect: (store, setup) => <assert the version-v result> },
       },
@@ -116,7 +119,6 @@ describe("database schema versions", () => {
 ```
 
 (`assertVersionsMatchSchema` and `testUpgradeHandlers` remain exported for bespoke use.)
-```
 
 ## Example: a breaking change (number → object) at version 1
 

package/.claude-plugin/plugin.json

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

package/README.md

@@ -55,6 +55,14 @@ self-update**, editing your `package.json` and `.gitignore` to:
    scripts, so a `postinstall` shipped inside the package would silently not fire;
 3. gitignore the managed bundle folders.
 
+Each managed folder also gets a short "externally managed — do not edit" notice so
+an agent that opens it is warned before touching the regenerated files. The notice
+follows your repo's instruction convention: it is written as `AGENTS.md` by default
+(the cross-agent standard, which Claude Code also reads) and only as `CLAUDE.md` for a
+repo that is still CLAUDE.md-only. `install` never drops a `CLAUDE.md` into a repo that
+uses `AGENTS.md` — a stray `CLAUDE.md` anywhere makes Claude Code ignore every
+`AGENTS.md` project-wide.
+
 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).

package/bin/cli.mjs

@@ -41,10 +41,13 @@ const { name: PKG_NAME, version: VERSION } = pkg;
 // each agent root.
 const BUNDLE = "adobe-data-ai";
 
-// A do-not-edit notice dropped at each bundle root. Claude Code loads nested
-// CLAUDE.md files when working in a subtree, so an agent that opens one of these
-// folders sees the notice before touching anything. `extra` adds a pointer to
-// the companion bundle.
+// A do-not-edit notice dropped at each bundle root so an agent that opens one of
+// these managed folders sees it before touching anything. The file is named for the
+// project's instruction convention (see `noticeFilename`) — never unconditionally
+// `CLAUDE.md`: Claude Code treats any CLAUDE.md in the tree as switching the whole
+// project into CLAUDE.md mode and then ignores every AGENTS.md project-wide (observed
+// on Claude Code 2.1.286), which would silently blank out instructions in an
+// AGENTS.md-based repo. `extra` adds a pointer to the companion bundle.
 function notice(extra) {
     return `# Externally managed — do not edit
 
@@ -58,11 +61,23 @@ version, then reinstall — do not modify these files in place.
 ${extra ? `\n${extra}\n` : ""}`;
 }
 
-function writeMeta(bundleDir, noticeBody, extraMeta) {
-    writeFileSync(join(bundleDir, "CLAUDE.md"), noticeBody);
+// Choose the managed notice's filename from the project's instruction convention.
+// Preference is AGENTS.md (the cross-agent standard, which Claude Code also reads); we
+// fall back to CLAUDE.md only for a repo still on the CLAUDE.md convention (a root
+// CLAUDE.md and no AGENTS.md), so the notice keeps auto-loading there. An AGENTS.md
+// repo (and a greenfield one) therefore never receives a data-ai CLAUDE.md — a stray
+// CLAUDE.md anywhere flips Claude Code out of AGENTS.md mode for the whole project.
+function noticeFilename(base) {
+    const hasClaude = existsSync(join(base, "CLAUDE.md"));
+    const hasAgents = existsSync(join(base, "AGENTS.md"));
+    return hasClaude && !hasAgents ? "CLAUDE.md" : "AGENTS.md";
+}
+
+function writeMeta(bundleDir, noticeBody, extraMeta, noticeFile) {
+    writeFileSync(join(bundleDir, noticeFile), noticeBody);
     writeFileSync(
         join(bundleDir, ".data-ai.json"),
-        JSON.stringify({ package: PKG_NAME, version: VERSION, ...extraMeta }, null, 2) + "\n",
+        JSON.stringify({ package: PKG_NAME, version: VERSION, notice: noticeFile, ...extraMeta }, null, 2) + "\n",
     );
 }
 
@@ -107,6 +122,7 @@ function installSkills(base, skills) {
         bundleDir,
         notice("The architecture rules these skills follow are installed at\n`.claude/rules/adobe-data-ai/` (referenced by name from each SKILL.md)."),
         { skills },
+        noticeFilename(base),
     );
     return bundleDir;
 }
@@ -118,7 +134,7 @@ function installRules(base) {
     // Copy the whole rules tree, minus the top-level README.md meta doc.
     const readme = join(rulesSrc, "README.md");
     cpSync(rulesSrc, bundleDir, { recursive: true, filter: (src) => src !== readme });
-    writeMeta(bundleDir, notice(), { rules: countRules(rulesSrc) });
+    writeMeta(bundleDir, notice(), { rules: countRules(rulesSrc) }, noticeFilename(base));
     return bundleDir;
 }
 

package/package.json

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

package/skills/build-actions/SKILL.md

@@ -1,16 +1,15 @@
 ---
 name: build-actions
-description: Build a feature's action-database — async orchestration over services and transactions. If the feature has async flows or side effects outside of the main store.
+description: Build a feature's ecs/actions layer — the operations the app performs.
 input: feature
 output: feature
 ---
 
-Skip if this feature doesn't contain or require actions.
+Create `ecs/actions/`: `action-database.ts` (extends the previous layer, adds `actions`
+from `./index.js`), one action per file, and a barrel. Every spec action has a
+same-named action. It awaits services and commits through at most one transaction
+(add any transaction `build-transactions` missed). Point `ecs/main-service.ts` at the top layer.
 
-Create `services/main-service/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.
+Gate: `checkFeature` passes for each op as it is added.
 
-The top main-service layer; comes after `service-database`.
-
-The how is in the auto-loading `features/services/main-service/actions.md` rule.
+The how is in the auto-loading `features/ecs/actions.md` rule.

package/skills/build-app-entry/SKILL.md

@@ -1,15 +1,19 @@
 ---
 name: build-app-entry
-description: Wire built features into a running application — import peer schemas, lazy-load peers, and mount the root UI.
+description: Build an application's src/app/ composition root.
 input: app
 output: app
 ---
 
-- The base (`features/main`) core-database `imports` each peer feature's core-database
-  plugin, so all schemas coexist, persist, and sync while the base type stays decoupled.
-- The base reaches a peer only through a lazy element wrapper (dynamic import), so peers
-  load on demand.
-- The entry point creates the live database from `MainService.plugin` (the base
-  feature's assembled database — see `features/services/main-service/index.md`) and mounts the root UI.
+Create `src/app/`:
 
-See `features/index.md` (one-app-many-features) for the wiring rules.
+- `schema.ts` — the composed plugin: the base feature's `MainService.plugin`, `imports`
+  of the core schema of each feature that loads lazily (single-feature apps skip this).
+- `versioning/` — `versions.ts` + `versions.test.ts` over the composed schema, when
+  the app persists.
+- `persistence.test.ts` — a save/load round-trip, when the app persists.
+- `main.ts` — creates the database, injects every service whose `create` throws, and
+  mounts the root UI. Point `index.html` at it.
+
+The how is in the auto-loading `app.md` and `versioning.md` rules, and
+`features/index.md` (one app, many features).

package/skills/build-computed/SKILL.md

@@ -1,16 +1,17 @@
 ---
 name: build-computed
-description: Build a feature's computed-database — derived observable values.
+description: Build a feature's ecs/computed layer. Optional.
 input: feature
 output: feature
 ---
 
-Skip if this feature doesn't contain or require computed values.
+Skip if the spec has no derivations and the UI needs no derived values.
 
-Create `services/main-service/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.
+Create `ecs/computed/`: `computed-database.ts` (extends the previous layer, adds
+`computed` from `./index.js`), one `cached` derived value per file, and a barrel. Wire
+`data/values/` helpers to the minimal observables. Name each entity-id-list computed in
+the implementation's `hydrate`, and pass `computedPlugin: ComputedDatabase.plugin`.
 
-Comes after `transaction-database`.
+Gate: each derivation's computed conforms.
 
-The how is in the auto-loading `features/services/main-service/computed.md` rule.
+The how is in the auto-loading `features/ecs/computed.md` rule.

package/skills/build-core-database/SKILL.md

@@ -1,24 +1,27 @@
 ---
 name: build-core-database
-description: Build a feature's schema — the core-database (components, resources, archetypes). The first main-service layer.
+description: Build a feature's ECS schema (ecs/core) and its conformance wiring. The first ecs layer.
 input: feature
 output: feature
 ---
 
-Create `services/main-service/core-database/` — `core-database.ts` plus one single-export file per facet
-the feature actually uses (`components`, `resources`, `archetypes` are each optional on
-`Database.Plugin.create`). Create only the facet files you need; omit the rest rather than
-shipping empty `Database.components({})` boilerplate. A feature with **no entities** (a
-singleton whose whole state is resources) is just `resources.ts` + `core-database.ts`.
+Create:
 
-- `components.ts` → `Database.components({ document, settings, presence, session })` (scopes optional) — only if the feature has entities.
-- `resources.ts` → `Database.resources({ … })` (every entry needs a `default`) — for singleton / global state.
-- `archetypes.ts` → `Database.archetypes(components, { … })` — only alongside components.
-- `core-database.ts` → `Database.Plugin.create({ imports?, components?, resources?, archetypes? })`, exporting the `CoreDatabase` namespace.
+- `ecs/core/archetypes.ts` — `Database.archetypes(components, { … })`, spreading each
+  `data/entities` tuple and adding implementation-only columns (never a
+  `nonPersistent` column without a real default).
+- `ecs/core/core-database.ts` — `Database.Plugin.create({ extends?, components?,
+  resources?, archetypes? })` from the `data/` barrels, exporting the `CoreDatabase`
+  namespace. A feature built on another extends that feature's core.
+- `ecs/main-service.ts` — `export { CoreDatabase as MainService }`, moved up as layers
+  are added.
+- `ecs/conformance/` — `projection.ts`, `implementation.ts`
+  (`Conformance.implementation(spec, …)`) and `conformance.test.ts`
+  (`Conformance.checkFeature`).
 
-The schema root; comes after `data/` (and `services/`). Bind each schema from its `data/`
-type — don't author shapes here. Components use JSON schemas; resources use the
-`{ default }` convention (a schemaless aggregate binds via `{ default: State.create() }`).
+Gate: the samples round-trip through the projection. Until the later layers exist,
+`checkFeature` lists each spec op without an implementation by name; that list is
+the work remaining.
 
-The how is in the auto-loading `features/services/main-service/index.md` + `components.md` / `resources.md` /
-`archetypes.md` rules.
+The how is in the auto-loading `features/ecs/index.md`, `core.md` and `conformance.md`
+rules.

package/skills/build-data/SKILL.md

@@ -1,22 +1,23 @@
 ---
 name: build-data
-description: Build a feature's data/ layer — data-type namespaces and the State spec. The first, foundational feature phase.
+description: Build a feature's data/ layer — values, components, resources, entities. The first, foundational phase.
 input: feature
 output: feature
 ---
 
-Create the feature's `data/` layer (pure spec; depends on nothing but `@adobe/data`
-and other `data/` declarations):
+Create the feature's `data/` layer: pure Data declarations, depending only on
+`@adobe/data` and the `data/` of features this one builds on.
 
-- one namespace folder per data type — `<type>/{<type>.ts, public.ts, <helper>.ts}` (+ `schema.ts` only when a runtime boundary needs it);
-- `data/state/` — the `State` aggregate plus its pure transforms/derivations.
+- `values/<type>/` — one namespace per Data type: a hand-written type, a schema pinned
+  to it (`type _Pin = Assert<Equal<Schema.ToType<typeof schema>, <Type>>>`) when
+  something needs one, and pure helpers, each with a test.
+- `components/<name>.ts` — one schema per file, scope spread from `Scope`, plus an
+  `index.ts` barrel. Include implementation-only columns (tags, drag offsets).
+- `resources/<name>.ts` — one schema per file, `satisfies ResourceSchema`, plus a barrel.
+- `entities/<entity>.ts` — the spec-visible entity as a component-name tuple, with its
+  type derived by `Database.EntityType`, plus a barrel.
 
-**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 = {}
+Create only the folders the feature needs. Gate: it compiles and the helper tests
+pass.
 
-The hand-authored type in `<type>.ts` is the source of truth. The schema is optional up front — add `schema.ts` only when a runtime boundary (persistence, wire, or an ECS component/resource) needs one, write it to match the type, and pin it with `type _Pin = Assert<Equal<Schema.ToType<typeof schema>, <Type>>>` so it cannot drift. `Schema.ToType` is used only in that assertion, never as the exported type.
-Helpers are pure and unit-tested. Run this first — every other layer imports `data/`.
-
-The how is in the auto-loading rules: `features/data/index.md`, `features/data/state.md`, and
-`global/namespace.md`.
+The how is in the auto-loading `features/data/` rules and `global/namespace.md`.

package/skills/build-feature/SKILL.md

@@ -8,11 +8,12 @@ output: feature
 /graph-execute
     /build-data
     /build-services
+    /build-spec
     /build-core-database
     /build-indexes
     /build-transactions
-    /build-computed
     /build-service-database
+    /build-computed
     /build-actions
     /build-systems
     /build-ui

package/skills/build-game/SKILL.md

@@ -7,15 +7,17 @@ output: game
 
 /build-application — a game is an application.
 
-Map game concepts to feature layers: data/ = state + rules (+ per-tick step math),
-components/archetypes = entity kinds, indexes = spatial/lookup queries,
-transactions = moves/spawns, computed = score/status/winner, ui = view + input.
+Map game concepts to feature layers: data/ = value types, rules math, components,
+resources (the board, the player, the score) and entities (the pieces); spec/ = the
+game state + moves (+ one pure function per system); indexes = spatial/lookup queries;
+transactions + actions = moves/spawns; computed = score/status/winner; ui = view + input.
 
 - **Turn-based** uses the reactive transaction → computed → ui loop, no systems
   (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. Systems must stay O(1) per touched entity — never project the whole
-  `State` into/out of the store each frame (see `features/services/main-service/systems.md`).
+  `State` into/out of the store each frame, and never turn per-row work into per-entity
+  transactions. Each system conforms alone and as a frame (see `features/ecs/systems.md`).
   This is where components, archetypes, indexes, and systems all carry real
   weight.

package/skills/build-indexes/SKILL.md

@@ -1,16 +1,15 @@
 ---
 name: build-indexes
-description: Build a feature's index-database — component/archetype indexes for O(1) lookup. As needed.
+description: Build a feature's ecs/indexes layer. Optional.
 input: feature
 output: feature
 ---
 
-Skip if this feature doesn't contain or require indexes.
+Skip if the feature needs no indexed lookups.
 
-Create `services/main-service/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.
+Create `ecs/indexes/`: `index-database.ts` (extends `CoreDatabase`, adds `indexes` from
+`./index.js`), one index per file, and an `index.ts` barrel.
 
-Only if the feature needs indexed lookups. Comes after `core-database`.
+Gate: conformance unchanged, plus index tests where an index has logic.
 
-The how is in the auto-loading `features/services/main-service/indexes.md` rule.
+The how is in the auto-loading `features/ecs/indexes.md` rule.

package/skills/build-service-database/SKILL.md

@@ -1,16 +1,16 @@
 ---
 name: build-service-database
-description: Build a feature's service-database — db-bound service factories. If the feature exposes services.
+description: Build a feature's ecs/services layer — registering services on the database. Optional.
 input: feature
 output: feature
 ---
 
-Create `services/main-service/service-database/`: `service-database.ts` (extends the previous layer, registers the
-`services` facet). Two forms:
+Skip if the feature has no services.
 
-- db-bound factories `create<Name>Service(db, …)` in `service-database/services/` (one per file + barrel), for services that read `db.observe.*` / call `db.transactions.*`; or
-- plain async ports registered straight from the feature's `services/` contracts.
+Create `ecs/services/service-database.ts` (extends the previous layer), registering
+each `services/` service's `create` under its `Services` key, plus any database-bound
+factories (one per file + barrel) for services that read observables or call
+transactions. Pin with `Assert<Equal<ServiceDatabase["services"], Services>>`. Give
+the implementation base fakes for services whose `create` throws.
 
-Comes after `computed-database`.
-
-The how is in the auto-loading `features/services/main-service/services.md` rule.
+The how is in the auto-loading `features/ecs/services.md` rule.

package/skills/build-services/SKILL.md

@@ -1,16 +1,18 @@
 ---
 name: build-services
-description: Build a feature's services/ layer — async capability contracts (ports to the outside world). Optional.
+description: Build a feature's services/ layer — async data services (interface, create, createFake). Optional.
 input: feature
 output: feature
 ---
 
-Skip if this feature doesn't contain or require services.
+Skip if the feature talks to nothing outside itself.
 
-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.
+Create one `services/<name>-service/` namespace per service: the interface (an async
+data service, validated with `AsyncDataService.IsValid`), `create` (the
+implementation, or a factory that throws when the app must inject it),
+`createFake`, and `public.ts`. Add `services/services.ts` with the `Services` map when
+spec actions inject services.
 
-Only if the feature talks to the outside world. Comes after `data/`, before `services/main-service/`.
+Depends only on `data/`. Gate: per-service unit tests.
 
-The how is in the auto-loading `features/services/index.md` rule (and `global/namespace.md`).
+The how is in the auto-loading `features/services/index.md` rule.