@ethlete/agent-rules 0.1.0-next.15 → 0.1.0-next.17

package/CHANGELOG.md

@@ -1,5 +1,38 @@
 # @ethlete/agent-rules
 
+## 0.1.0-next.17
+
+### Minor Changes
+
+- `et update` now leaves tasks to fix code written under the earlier guidance: app styling, URL-bound list state, hand-debounced search, hand-built charts, avatars and progress bars, and the Nx layout.
+- `timetrack resync --replace` re-reads a checkout's agent logs and replaces the samples the store already holds for those sessions, so a parser fix reaches stored days.
+
+### Patch Changes
+
+- The Angular and signals skills cover shared `injectX()` logic, per-row formatting, writing query params and effects that only write a signal; the comment rule says app code rarely has public API.
+- Add the consumer skills `verify-in-app` (drive the served app headlessly with Playwright) and `app-testing` (specs for query, router and overlay code), and link the new query testing docs page from the query skill.
+- The `app-styling` rule and its migration now keep `ViewEncapsulation.None` on app components, as the `require-view-encapsulation-none` lint rule requires, and scope the remaining CSS under the component's host class.
+- Consumer repos get an `app-styling` rule (Tailwind in app templates, 10px rem root) instead of the SDK's component styling rule, and the `query` and `sdk-docs` skills now point to `defineQueryForm` and every component domain.
+- Query skill: bridge a correlated result into RxJS with `executeUntilSettled$`, keeping the Promise form for signal-forms `submit()`.
+- The `list-state-query-form` task binds pagination, page size and a table sort the way that works, and keeps `replaceUrl: true`. The query skill names `observe({ replaceUrl: true })`.
+- The guidance migrations find the call sites they missed in a real app, and generated commands use the repo's package manager.
+- The `app-styling-utilities`, `sdk-components-over-hand-built-ui` and `nx-layout` migration tasks name the real theme utilities, find more call sites, and stop before overriding a repo's own rules or the generated `AGENTS.md` block.
+- Consumer Nx workspaces get an `nx-layout` rule: thin apps, feature code in `libs/domain`, and shared `queries`, `types`, `uikit`, `theme` and `env` libs with `scope:*` tags.
+- The consumer query skill now maps every @ethlete/query capability to its docs page, so agents find APIs like `defineQueryForm` instead of hand-building them.
+- `ethlete-agents` commands run from a subdirectory now use the nearest directory holding `ethlete-agents.config.json` as the repo root, so `check` no longer reports false drift there.
+- The `sdk-docs` skill points consumer agents at the new App setup docs page first: root font size, theme generation and the providers an app needs.
+- `sync` and `check` now name every skill or rule skipped for an unmet `requires` or missing var, and warn when a path var like `themeStylesheet` points at a missing file.
+- `vars.themeStylesheet` may now name a folder of theme files. The `story-styling` skill searches it recursively.
+- `recommendedTs` now uses `ethlete/consistent-type-definitions` instead of `@typescript-eslint/consistent-type-definitions`, so `--fix` no longer turns an interface inside `declare module` or `declare global` (such as the theme-name registry the `@ethlete/core` generators emit) into a type alias that merges into nothing.
+- The `ET100` error now says mutations need `withArgs` too and calls `silenceMissingWithArgsFeatureError` an escape hatch; the query skill recommends `withArgs` for mutations.
+
+## 0.1.0-next.16
+
+### Patch Changes
+
+- Name the `take-until-destroyed-last` lint rule in the styleguide lint lookup and the RxJS skill.
+- A design call now lists its drawings as `variants` in `variant-<key>.ts` files, and `et design check` takes `--variant`; the old `options` key and `--option` flag are gone.
+
 ## 0.1.0-next.15
 
 ### Minor Changes

package/README.md

@@ -99,18 +99,19 @@ Prettier rewrites them and `check` then reports drift on every run:
   `.agents/skills/` is the cross-tool baseline) and adds `claude`, `cursor` or `copilot`
   when their directory exists; or list an explicit subset.
 - **`profile`** - `"consumer"` (default) emits `scope: consumer` and `scope: both`
-  content. `"sdk"` emits only `both`; the SDK repo uses it so its own hand-written,
-  authoring-side guides are not overwritten by the consumer-side versions.
+  content. `"sdk"` emits `scope: sdk` and `scope: both`; the SDK repo uses it so its own
+  hand-written, authoring-side guides are not overwritten by the consumer-side versions.
 - **`vars`** - values for the template tokens a guide declares. Defaults live in
   `content/defaults.json`; a guide whose variable has no default and no value is
   skipped with a warning rather than emitted with a dangling placeholder. Some are
   derived from the repo instead of defaulted - the `gitFlow*` ones from the `gitFlow`
-  block, and `commitRuleSource` / `commitValidation` from whether a commitlint config
+  block, `packageRunner` (`yarn`, `pnpm exec`, `bunx` or `npx`) from the root
+  `package.json`'s `packageManager` or the lockfile, and `commitRuleSource` / `commitValidation` from whether a commitlint config
   exists (`commitlint.config.*`, `.commitlintrc*`, or a `commitlint` key in
   `package.json`). Without one, the git-commit guide presents the format as the repo's
   convention and never mentions a `commitlint` run - an agent that goes looking for a
   promised validator and finds nothing reports the discrepancy instead of just
-  committing. Setting either one in `vars` overrides the detection.
+  committing. Setting any derived var in `vars` overrides the detection.
 - **`exclude`** - rule or skill names to skip entirely for every configured agent and
   developer. For example, `"exclude": ["git-flow", "handoff"]` prevents those skills
   from being generated; the next `sync` also removes copies generated previously. Unknown

package/content/rules/app-styling.md

@@ -0,0 +1,47 @@
+---
+name: app-styling
+description: App components are styled with Tailwind utilities in their templates; app CSS stays out of @layer components; the SDK needs a 10px rem root; hardcoded colours are never primary values.
+kind: rule
+scope: consumer
+requires: ['@ethlete/core']
+---
+
+## Styling
+
+Every component in this workspace (views, pages, shells, shared UI in `libs/`) is laid out
+and styled with **Tailwind utility classes in its template**, including the generated
+theme utilities (`bg-et-surface-bg`, `border-et-surface-border`, `text-et-<theme>`). Do not
+invent a BEM class system, and do not write a `.css` file for layout, spacing or
+typography a utility expresses. Every app component sets `encapsulation: ViewEncapsulation.None`,
+as the `require-view-encapsulation-none` lint rule requires. Its CSS is then global, so give the
+component a host class (`host: { class: 'app-player-card' }`) and scope every selector under it,
+the way SDK components scope theirs under their `et-` classes. Never write a bare element or
+unprefixed class selector in a component stylesheet.
+
+Write CSS only for what utilities cannot express. Keep that CSS **unlayered** or in
+`@layer utilities` — never in `@layer components`, and that includes the global stylesheet. SDK component styles are injected into
+`@layer components` at runtime, after your stylesheet, so an app rule in the same layer
+ties on layer and loses on source order.
+
+To change an SDK component's look, set its `--et-*` tokens first (documented per
+component), then use a utility class or unlayered CSS on the element — see "Overriding
+component styles" in the docs site's components overview.
+
+The SDK sizes everything in `rem` on a **10px root**: the app's global stylesheet must set
+`html { font-size: 62.5%; }`. Without it every SDK control renders 1.6× too large. With it,
+`1rem` is `10px`, so the app's own `rem` values stay easy to read.
+
+The 10px root also shrinks every rem-based Tailwind scale to 62.5% of its nominal size (1.6×
+smaller): `p-4` is 10px instead of 16px, and `max-w-3xl` is 480px instead of 768px. Set
+`--spacing: 0.4rem` in the app's `@theme` so the spacing scale keeps its 4px step, as the SDK's
+own Storybook does. Redefine any other rem scale the app uses (`--text-*`, `--container-*`,
+`--radius-*`) the same way, or use px where a size matters. Breakpoints are not affected: a
+media query's `rem` ignores the root font size.
+
+**Never use a hardcoded colour as the primary value.** Backgrounds, text, borders and
+interaction states resolve from the surface and colour theming tokens
+(`--et-surface-*-solid`, `--et-theme-color-*`) or their generated utilities. A static
+fallback inside `var(--token, <fallback>)` is permitted, but not required.
+
+Theme **names** (`brand`, `danger`, `dark-elevated`, …) are registered by this app; the SDK
+ships none. Semantic colours resolve by theme `type` (e.g. `injectErrorTheme()`).

package/content/rules/comments.md

@@ -20,6 +20,8 @@ smaller function, or a type; fix that instead of narrating it.
    limitation) and linking it where a link exists, so the next reader can tell when it may go.
 4. **Public API JSDoc** — what it does and how to call it, on something a lib actually
    exports. One or two sentences. Not internals, not history, not why it is shaped that way.
+   In an application nothing is public API unless it lives in a shared lib other projects
+   import, so this case rarely applies to app code.
 
 Nothing else qualifies. Not "this is subtle", not "worth noting", not a heading over a group
 of members, not a summary of the function underneath it.
@@ -43,7 +45,8 @@ years.
   annotation, a factory instead of a literal, a helper moved into its own file. The type, the
   annotation and the import already say what happens.
 - **Migration narration** — "moved here from X", "used to be a tuple", "so Y no longer pulls
-  Z", "renamed for clarity". Git knows; the next reader does not care.
+  Z", "renamed for clarity", "see ADR-0012". Git and the ADR index know; the next reader does
+  not care.
 - **The same explanation at every call site.** Explain a pattern once where it is defined (the
   helper's JSDoc, the lint rule's message, the guide) and let every use site stay silent.
 - **Commented-out code.**

package/content/rules/nx-layout.md

@@ -0,0 +1,47 @@
+---
+name: nx-layout
+description: Nx workspace layout - thin apps, feature code in libs grouped by kind, path-mirroring aliases, scope tags.
+kind: rule
+scope: consumer
+requires: ['nx']
+---
+
+## Nx workspace layout
+
+Apps are thin shells. All feature code lives in libs, grouped by kind, not by Nx type:
+
+```text
+apps/<app>/src/app/        app.component.ts, app.config.ts, app.routes.ts only
+libs/
+  domain/<app>/<feature>/  views, components, services, <feature>.routes.ts
+  domain/<app>/shared/     code shared by one app's features (optional)
+  queries/                 query clients and creators, one folder per backend
+  types/                   API models and shared types
+  uikit/                   app-agnostic presentational components
+  theme/                   surface and colour themes
+  env/                     environment.ts, environment.production.ts
+  assets/                  fonts, icons, images
+```
+
+- `app.routes.ts` only lazy-loads domain libs:
+  `loadChildren: () => import('@acme/domain/admin/users').then((m) => m.USERS_ROUTES)`.
+  Each feature lib exports its own `<FEATURE>_ROUTES`.
+- A small app may use one lib per app (`libs/domain/<app>`) with a folder per feature.
+  Never put features, queries, shared UI or theme in the app project.
+- Do not add Nx `feature/ui/data-access/util` folders or `type:*` tags.
+- Every lib has `src/index.ts` and explicit `build` (`@nx/angular:ng-packagr-lite`), `lint`
+  and `test` targets in `project.json`. Keep `plugins: []` in `nx.json`.
+- Alias = path with slashes: `@acme/domain/admin/users`, `@acme/queries`, `@acme/types`,
+  `@acme/uikit`, `@acme/env`. Project name = path with dashes (`domain-admin-users`).
+  Component `prefix` = the repo abbreviation.
+- Tag every project with one `scope:*`: `scope:<app>` for an app and its domain libs,
+  `scope:core` for env and types, plus `scope:queries`, `scope:uikit`, `scope:theme`.
+  `@nx/enforce-module-boundaries` with `enforceBuildableLibDependency: true` lets
+  `scope:<app>` depend on itself and the shared scopes, never on another app.
+- A backend in the same workspace is an app in `apps/` with its libs in
+  `libs/domain/<name>-api`. Ban `@angular/*` in backend scopes and `@nestjs/*` in frontend
+  scopes with `bannedExternalImports`.
+- Environment config lives only in `libs/env`, never hardcoded in a query client.
+
+This is the layout for new workspaces and new code. Do not restructure an existing
+workspace that deviates from it unless the user asks.

package/content/rules/styling.md

@@ -2,7 +2,7 @@
 name: styling
 description: Component CSS is plain CSS in @layer components, and hardcoded colours are never primary values.
 kind: rule
-scope: both
+scope: sdk
 requires: ['@ethlete/core']
 ---
 

package/content/skills/angular-patterns/SKILL.md

@@ -28,6 +28,16 @@ DOM/`window`, output naming, class-member + decorator-metadata order, no
 <button [disabled]="disabled()"></button>
 ```
 
+- **Per-row formatting belongs in the data, not in a method per row.** Map the rows once
+  in a `computed()` and bind the prepared fields. A pure, module-level formatting function
+  is acceptable too; a component method called for each row in `@for` is not.
+
+```ts
+// ❌ <td>{{ formatDate(row.createdAt) }}</td> - re-runs for every row, every CD cycle
+// ✅
+rows = computed(() => this.items().map((item) => ({ ...item, createdAtLabel: formatDate(item.createdAt) })));
+```
+
 ## Lifecycle
 
 - **Prefer the `constructor`** (runs in the injection context) over `ngOnInit` /
@@ -40,6 +50,10 @@ DOM/`window`, output naming, class-member + decorator-metadata order, no
   `createRootProvider` and the `injectX()` helper pattern from `@ethlete/core`
   rather than an `@Injectable` or `@Service`. (Both decorators are lint-banned;
   choosing a function over a service at all is the judgment.)
+- **Repeated component logic → one `injectX()` function.** When two components carry the
+  same signals, effects or subscriptions, extract them into an `injectX()` that runs in the
+  injection context and returns what the components bind. Do not copy the block, and do not
+  reach for a base class.
 - **Directives → plain functions where possible.** With signal APIs, move the core
   logic into a function so it's reusable without applying a directive; keep a
   directive only when a host element genuinely needs it. Avoid common input/output
@@ -47,6 +61,15 @@ DOM/`window`, output naming, class-member + decorator-metadata order, no
 - **Pipes → a `computed()` calling a utility function.** Pipes carry no logic;
   most can be dropped in favour of a `computed`.
 
+## Query params
+
+- **Read** them with the `@ethlete/core` signals: `injectQueryParam(key)`,
+  `injectQueryParams()`. `ActivatedRoute` and `router.url` are lint-banned.
+- **Write** them with `inject(Router).navigate([], { queryParams, queryParamsHandling: 'merge' })`.
+  `merge` keeps the params you do not set; `null` removes a param.
+- **Filter, sort and page state bound to the URL** is a query form: with `@ethlete/query`,
+  use `defineQueryForm` instead of writing the params by hand.
+
 ## Components
 
 - Inline template/styles for small components; external `.html` / `.css` files

package/content/skills/app-testing/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: app-testing
+description: How to unit-test an app built on the Ethlete SDK - views that fetch through @ethlete/query (HttpTestingController and the @ethlete/query/testing helpers), components that open overlays, and views that read the URL with injectQueryParam under provideRouter. Read before writing or fixing a spec for a component, view or service that uses @ethlete/query, @ethlete/core router signals or @ethlete/components overlays.
+kind: skill
+scope: consumer
+requires: ['@ethlete/core']
+vars: [docsBaseUrl]
+---
+
+# Testing an Ethlete app
+
+Specs run in jsdom under `TestBed`. Test through the public API the view uses - mount the
+component, answer its requests, move the URL - and assert on what it renders or exposes. The full
+reference for the query helpers is {%docsBaseUrl%}/query/testing.
+
+## Views that fetch
+
+A client made with `createQueryClient` is provided in root, so a spec provides nothing for it. It
+needs Angular's HTTP testing backend, and answers each request by hand:
+
+```ts
+import { provideHttpClient } from '@angular/common/http';
+import { HttpTestingController, provideHttpClientTesting } from '@angular/common/http/testing';
+import { TestBed } from '@angular/core/testing';
+
+beforeEach(() => {
+  TestBed.configureTestingModule({ providers: [provideHttpClient(), provideHttpClientTesting()] });
+});
+
+afterEach(() => TestBed.inject(HttpTestingController).verify());
+
+it('renders the players', async () => {
+  const http = TestBed.inject(HttpTestingController);
+  const fixture = TestBed.createComponent(PlayersComponent);
+  fixture.detectChanges();
+  TestBed.tick();
+
+  http.expectOne((req) => req.url.includes('/players')).flush({ items: ['Müller'] });
+  await fixture.whenStable();
+
+  expect(fixture.nativeElement.textContent).toContain('Müller');
+});
+```
+
+- A GET query executes once its args resolve, which happens on change detection -
+  `TestBed.tick()` before `expectOne`, and again after `flush` before reading the query's
+  `response()`, `loading()` or `error()`.
+- `req.url` carries the query string, so `expectOne('https://api.example.com/players?search=mul')`
+  matches the full URL. Match with a predicate, as above, when the params are not the point.
+- Fail a request with `flush(body, { status: 422, statusText: 'Unprocessable Entity' })`.
+- Mutations (`POST`, `PUT`, `PATCH`, `DELETE`) never auto-execute - call `.execute({ args })`,
+  then expect the request.
+
+From `@ethlete/query/testing`:
+
+| Export                                                                        | Use                                                                                                                                 |
+| ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| `expectAndFlush(http, url, body, status?)`                                    | `expectOne(url).flush(body)` in one call.                                                                                           |
+| `expectFlushAndWait(http, url, body, status?)`                                | The same, then `TestBed.tick()`.                                                                                                    |
+| `setupQueryTest(config?)`                                                     | A scratch client, `HttpTestingController`, `createGet` … `createDelete` creators - for testing code that takes a creator or client. |
+| `setupAuthTest({ querySetup })`                                               | A bearer auth provider on that scratch client, with `login()` / `refresh()` helpers that answer the requests.                       |
+| `createFakeQueryPersistenceStore()`                                           | In-memory persistence adapter - jsdom has no IndexedDB.                                                                             |
+| `installFakeBroadcastChannel()`, `installFakeWebLocks()`, `flushMultiTabSync` | Two clients in one spec behave as two tabs.                                                                                         |
+| `createWebSocketTestDouble()`                                                 | A scripted socket.io `io` for `createWebSocketClient({ io })`.                                                                      |
+
+`setupQueryTest` calls `TestBed.configureTestingModule` itself and replaces `ErrorHandler` with a
+no-op (`mockErrorHandler: false` keeps the real one). Call it inside `beforeEach`, and call
+`restoreConsole()` in `afterEach` if the file spies on `console`.
+
+## Views that read the URL
+
+`injectQueryParam`, `injectQueryParams`, `injectPathParam` and the other router signals from
+`@ethlete/core` read the router, so the spec provides one and navigates it:
+
+```ts
+import { provideRouter, Router } from '@angular/router';
+
+TestBed.configureTestingModule({
+  providers: [provideHttpClient(), provideHttpClientTesting(), provideRouter([])],
+});
+
+await TestBed.inject(Router).navigateByUrl('/?search=mul');
+const fixture = TestBed.createComponent(PlayersComponent);
+fixture.detectChanges();
+TestBed.tick();
+
+http.expectOne((req) => req.urlWithParams.includes('search=mul')).flush({ items: [] });
+
+await TestBed.inject(Router).navigateByUrl('/?search=x');
+TestBed.tick();
+http.expectOne((req) => req.urlWithParams.includes('search=x')).flush({ items: [] });
+```
+
+Navigate to change a param - never set the signal or mock the inject function. A view that also
+reads path params needs the real route in the config (`provideRouter([{ path: 'players/:id',
+component: PlayersComponent }])`) and `RouterTestingHarness` from `@angular/router/testing` to
+render it.
+
+## Components that open overlays
+
+An overlay mounts at the end of `document.body`, not in the fixture, and it opens and closes over
+animation frames. Query the document, wait two frames, and close what is left after each test:
+
+```ts
+import { injectOverlayManager } from '@ethlete/components';
+
+const flushFrames = () =>
+  new Promise<void>((resolve) => requestAnimationFrame(() => requestAnimationFrame(() => resolve())));
+
+afterEach(async () => {
+  TestBed.runInInjectionContext(() => injectOverlayManager())
+    .openOverlays()
+    .forEach((ref) => ref.forceClose());
+  await flushFrames();
+});
+
+it('opens the edit dialog', async () => {
+  const fixture = TestBed.createComponent(PlayerListComponent);
+  fixture.detectChanges();
+
+  fixture.nativeElement.querySelector('button.edit').click();
+  await flushFrames();
+
+  expect(document.querySelector('.player-edit-dialog')).not.toBeNull();
+});
+```
+
+- Count open overlays with `injectOverlayManager().openOverlays().length` (inside
+  `TestBed.runInInjectionContext`).
+- The `OverlayRef` that `createOverlayOpener(...).open()` returns has `componentInstance()`,
+  `close(result)` and `afterClosed()` - enough to test what the opener does with the result.
+- A query-param overlay (`defineQueryParamOverlay`) opens from the URL: provide the router and
+  navigate with the param set, as above.
+- jsdom has no `ResizeObserver`, `IntersectionObserver`, `matchMedia` or `Element.animate`. If a
+  spec throws on one of them, stub it once in the test setup file with an inert class or function,
+  not per spec.
+
+## Before you call it done
+
+A spec for a bug fix must fail without the fix - revert it, run the spec, see it fail, restore it.
+To check the same change in the running app, read {%skill:verify-in-app%}.

package/content/skills/design-exploration/SKILL.md

@@ -12,12 +12,12 @@ A design exploration is a dialog. **The user is the designer. You find and frame
 chooses.** A finding is not a licence to pick the fix.
 
 The unit of work is a **call**: one open question, with every answer drawn side by side at
-the same geometry. An option wins or loses only against the other options of its call.
+the same geometry. A variant wins or loses only against the other variants of its call.
 
 ## The rules
 
-1. **One open call at a time.** Take one question. Draw its options. Stop.
-2. **Put the options in the call, then name your pick.** Two to four options, drawn for
+1. **One open call at a time.** Take one question. Draw its variants. Stop.
+2. **Put the variants in the call, then name your pick.** Two to four variants, drawn for
    real, side by side, labelled, with what each one costs. Your pick is a proposal.
 3. **Commit only when the user says commit.**
 4. **A clear rejection starts the next call.** Settle and record the rejected call, then draw
@@ -33,31 +33,31 @@ finished while the user is still talking about it.
 
 - The question, in one sentence.
 - The call slug to look at.
-- The options, labelled A, B, C, one line each.
+- The variants, labelled A, B, C, one line each.
 - Your pick, one line on why.
 - Nothing else. No next step, no second finding.
 
 **Do not send a screenshot.** The user keeps the page open. Screenshot only for your own
-check that an option renders.
+check that a variant renders.
 
 If a second defect appears, add it to the open list and give it one line. Do not draw it.
 
-## Where the options are drawn
+## Where the variants are drawn
 
 The exploration's plan file names the tool. Two shapes exist.
 
-**A repository with a `.ethlete/design` folder** draws a call per page, each option in its own
+**A repository with a `.ethlete/design` folder** draws a call per page, each variant in its own
 iframe. The tool is `et design`, from `@ethlete/cli`, so the repository itself needs no design
 tooling. A call argues in the repository it is about:
 
 ```
 .ethlete/design/
-  config.json    the port, the default call, and one entry per project
+  config.json     the port, the default call, and one entry per project
   calls/<project>/<group>/<slug>/
-    call.ts      the eyebrow, the headline, the intro, frameWidth, the options and the round prose
-    fixture.ts   the data every option shares
-    option-a.ts  one default-exported drawing per option
-    option-b.ts
+    call.ts       the eyebrow, the headline, the intro, frameWidth, the variants and the round prose
+    fixture.ts    the data every variant shares
+    variant-a.ts  one default-exported drawing per variant
+    variant-b.ts
 ```
 
 The first segment of a slug is the **project**. `config.json` gives each project its own
@@ -73,16 +73,16 @@ Ethlete Studio carries its own copy of the tool, so it draws a checkout that ins
 The machine still needs Node, and the render stage still needs `playwright` where the copy in
 use can reach it.
 
-`call.ts` calls `defineCall` from `@design-explore`. Each option carries a `key`, a `name`,
+`call.ts` calls `defineCall` from `@design-explore`. Each variant carries a `key`, a `name`,
 a `claim`, a `cost`, an optional `verdict` of `chosen` or `rejected`, and a `load` that
-imports its own module. The host greys a rejected option and shows it on hover.
+imports its own module. The host greys a rejected variant and shows it on hover.
 
-In a call that runs past about a dozen options, every option names the pass that drew it with
+In a call that runs past about a dozen variants, every variant names the pass that drew it with
 `round: 'r3'`. **That tag is the only thing that makes a round exist.** The host reads the
-options, draws one band per round in the order the options introduce them, and lists those
-same bands in the sidebar, so a new option can never leave the menu stale. A round whose
-options all carry a verdict is **settled**: the page folds it down to its winner plus one row
-per rejected option, and a link opens it again.
+variants, draws one band per round in the order the variants introduce them, and lists those
+same bands in the sidebar, so a new variant can never leave the menu stale. A round whose
+variants all carry a verdict is **settled**: the page folds it down to its winner plus one row
+per rejected variant, and a link opens it again.
 
 A call whose rounds have all ruled is **resolved**. Its winners usually form a chain, each one
 the last plus a change, so the page stops drawing them: it leads with a **Result** band holding
@@ -92,36 +92,36 @@ rows. A key in the chain opens the round that drew it.
 `rounds` is prose only. Each entry gives a `key`, a `title` and a `note` saying what came out
 of that pass, which is how the intro stays short and each pass reads as a reply to the one
 before. An untagged round still draws and still gets a menu row - it says the bare key until
-somebody writes the entry. A `rounds` entry that no option names is stale prose, and the host
+somebody writes the entry. A `rounds` entry that no variant names is stale prose, and the host
 and the check both report it. Write the note in the same pass that sets the verdicts, never
 before the user rules.
 
-A call with one option and no `claim` is a **view**: one reference picture, drawn full
+A call with one variant and no `claim` is a **view**: one reference picture, drawn full
 width with no verdict tag. Use it for a picture that answers no question.
 
 Two views, and a way to compare:
 
 - **rounds** is the default. Round headings, the result band, and the folding above.
-- **all N** is a contact sheet: every option in the call at about a third size, in one grid, so
-  a call of two dozen fits on a screen or two. Use it to find the options worth a close look.
-- Clicking an option's name anywhere - a heading, a folded row, a thumbnail - puts it in the
+- **all N** is a contact sheet: every variant in the call at about a third size, in one grid, so
+  a call of two dozen fits on a screen or two. Use it to find the variants worth a close look.
+- Clicking a variant's name anywhere - a heading, a folded row, a thumbnail - puts it in the
   **compare overlay** at the top of the page. Two drawings that differ by a few pixels can only
   be told apart in one place, so the overlay stacks every pick in one box at full size and the
   reader switches between them: click the box or press space to blink, and with two picks the
   arrow keys wipe a seam across. Nothing is scaled and nothing moves. The picks live in the URL
   under `pick`, so a comparison is a link you can send.
 
-Three constraints the tool puts on an option file:
+Three constraints the tool puts on a variant file:
 
 - **Never import a package barrel.** The libraries resolve to source, so one barrel makes
   the browser request every module in the library, and the requests fail with
   `ERR_INSUFFICIENT_RESOURCES`. Import the one file you need.
-- **The fixture is shared, and an option may not change it.** Options drawn at three
+- **The fixture is shared, and a variant may not change it.** Variants drawn at three
   geometries cannot be compared.
-- **One file per option**, so several agents can draw at once, and a broken option breaks
+- **One file per variant**, so several agents can draw at once, and a broken variant breaks
   its own frame only.
 
-**A repository with a sketch Storybook** draws every option in the **same** story, side by
+**A repository with a sketch Storybook** draws every variant in the **same** story, side by
 side, under the real geometry the thing ships in. The default Storybook is
 {%storybookUrl%}; an app with its own sketch Storybook names its port in the plan file.
 
@@ -130,7 +130,7 @@ Either way:
 - Sketches take inputs only and stay out of the application's build.
 - Prototype, never refactor. Do not touch the shipped component until the treatment is
   settled.
-- Keep the rejected options drawn, marked as rejected.
+- Keep the rejected variants drawn, marked as rejected.
 
 ## Check before you look
 
@@ -159,30 +159,30 @@ transpile without type checking, so the render reports `ok` on a file that does
 compile. Open it only when the check passes and the drawing still does not appear:
 
 ```bash
-et design check --call <slug>            # every option of the call
-et design check --call <slug> --option b # one of them
+et design check --call <slug>             # every variant of the call
+et design check --call <slug> --variant b # one of them
 node check-story.mjs --tsconfig <path> --story <story-id>
 ```
 
 ## Delegating a call
 
-A call has one job per option, so it fans out. Every brief names `model: opus`.
+A call has one job per variant, so it fans out. Every brief names `model: opus`.
 
-1. **One agent per option.** Give it the call folder, the option key, the fixture it must
+1. **One agent per variant.** Give it the call folder, the variant key, the fixture it must
    not change, and the one claim its drawing has to support. Tell it to write its own
-   option file and nothing else, so two agents never touch one file.
+   variant file and nothing else, so two agents never touch one file.
 2. **One check-and-fix agent, after the drawing agents return.** Give it the changed files
    and the call slug. It runs the check above, fixes what it reports, and repeats until the
-   check says `ok`. It may not change what an option draws, only what stops it rendering.
+   check says `ok`. It may not change what a variant draws, only what stops it rendering.
 3. **One write-up agent, once the user settles the call.** Give it the verdict in the
    user's own words and the plan file. It records what won, what lost and why, it sets each
-   option's `verdict` in `call.ts`, and it writes that round's `note`. It runs while you open
+   variant's `verdict` in `call.ts`, and it writes that round's `note`. It runs while you open
    the next call.
 
 ## Screenshots
 
 **Off by default.** The user has the page open and sends you a picture when something looks
-wrong. Take one only when the code cannot tell you whether two options really differ, and
+wrong. Take one only when the code cannot tell you whether two variants really differ, and
 never to put in front of the user. Copy {%resource:shoot-template.mjs%} to the repository
 root.
 
@@ -198,6 +198,6 @@ node shoot.mjs <story-id> 1100 760 out.png
 ## Writing it down
 
 Every settled call goes in the exploration's plan file: what won, what lost, and why. Keep
-an **Open** list for the calls not yet made. A rejected option written down stops the next
+an **Open** list for the calls not yet made. A rejected variant written down stops the next
 session from drawing it again. After a clear rejection, use that record to frame and draw the
 next call; do not wait for the user to type “continue”.

package/content/skills/git-flow/SKILL.md

@@ -16,10 +16,10 @@ what gets deployed to a test environment and, once accepted, merged into
 **Never name a branch by hand - `start` does it from the grammar:**
 
 ```bash
-npx ethlete-agents git-flow start FIP-2178        # reads the issue, names it, branches off the right base
-npx ethlete-agents git-flow check                 # is the current branch conforming?
-npx ethlete-agents git-flow explain <branch>      # what the parser sees, and what it expects
-npx ethlete-agents git-flow repair <branch>       # rename a non-conforming one, retarget its MRs
+{%packageRunner%} ethlete-agents git-flow start FIP-2178        # reads the issue, names it, branches off the right base
+{%packageRunner%} ethlete-agents git-flow check                 # is the current branch conforming?
+{%packageRunner%} ethlete-agents git-flow explain <branch>      # what the parser sees, and what it expects
+{%packageRunner%} ethlete-agents git-flow repair <branch>       # rename a non-conforming one, retarget its MRs
 ```
 
 `start` prints its plan (branch, base, MR target) and asks before writing anything; add