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

package/content/skills/query/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: query
-description: The signals-first @ethlete/query data-fetching system - the query client, typed query creators, reactive args, and reading results as signals or observables. Read BEFORE writing or reviewing code that fetches data, wires search/autocomplete to an API, adds auth/polling/pagination, or bridges a query into UI or RxJS.
+description: The signals-first @ethlete/query data-fetching system - the query client, typed query creators, reactive args, and reading results as signals or observables. Read BEFORE writing or reviewing code that fetches data, builds a list with filters/search/sort/paging bound to URL query params (defineQueryForm), wires search/autocomplete to an API, adds auth, route guards or polling, or bridges a query into UI or RxJS.
 kind: skill
 scope: consumer
 requires: ['@ethlete/query']
@@ -13,38 +13,106 @@ Signals-first, typesafe data fetching for Angular: request dedup, caching, polli
 paged queries, bearer auth, GraphQL, and a socket.io realtime client.
 
 **The written docs are the source of truth - read the relevant page before
-non-trivial query work.** This guide is the index plus the load-bearing facts, so you
-don't re-derive them from source.
-
-| Page                                                                   | Covers                                                                                |
-| ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
-| {%docsBaseUrl%}/query/                                                 | Overview + the two-generations note                                                   |
-| {%docsBaseUrl%}/query/queries                                          | **Start here** - client, creators, the query object's signals, auto-execution         |
-| {%docsBaseUrl%}/query/features                                         | `withArgs`, `withPolling`, `withLongPolling`, `withAutoRefresh`, side-effect handlers |
-| {%docsBaseUrl%}/query/http                                             | REST creators, typing requests, response transforms, upload progress                  |
-| {%docsBaseUrl%}/query/auth                                             | Bearer auth: login/refresh, auto token refresh, multi-tab sync                        |
-| {%docsBaseUrl%}/query/caching · `/stacks` · `/errors` · `/gql` · `/ws` | Caching/dedup, pagination, error/retry, GraphQL, WebSockets                           |
-| {%docsBaseUrl%}/query/multi-tab                                        | Opt-in cross-tab sync: shared responses, per-key polling election, mutation fan-out   |
-| {%docsBaseUrl%}/query/query-forms                                      | Router-synced filter/search forms                                                     |
-| {%docsBaseUrl%}/query/legacy                                           | The maintenance-mode `V2QueryClient`                                                  |
+non-trivial query work.** This guide maps every need to its API and page, plus the
+load-bearing facts, so you don't re-derive them from source or hand-build what ships.
+
+| Page                                              | Covers                                                                        |
+| ------------------------------------------------- | ----------------------------------------------------------------------------- |
+| {%docsBaseUrl%}/query/                            | Overview, the two generations, what else the package ships                    |
+| {%docsBaseUrl%}/query/queries                     | **Start here** - client, creators, the query object's signals, auto-execution |
+| {%docsBaseUrl%}/query/features                    | `withArgs`, polling, auto-refresh, side-effect handlers, custom features      |
+| {%docsBaseUrl%}/query/http                        | REST creators, typing requests, response transforms, upload progress          |
+| {%docsBaseUrl%}/query/auth                        | Bearer auth provider, guards, token refresh, auth features                    |
+| {%docsBaseUrl%}/query/caching                     | Cache keys, dedup, `keepUnusedFor`, freshness, refresh and invalidation       |
+| {%docsBaseUrl%}/query/multi-tab                   | Cross-tab response sharing, one poller per key, mutation fan-out              |
+| {%docsBaseUrl%}/query/persistence                 | Successful reads kept in IndexedDB for reloads and offline cold starts        |
+| {%docsBaseUrl%}/query/stacks                      | Many queries of one creator, infinite lists, paged data                       |
+| {%docsBaseUrl%}/query/dependent-queries           | GET → GET dependencies and ordered mutation chains                            |
+| {%docsBaseUrl%}/query/batching                    | Bulk writes with bounded concurrency, per-item results, retry                 |
+| {%docsBaseUrl%}/query/errors                      | Error object, opt-in parsers, form submission, violations, retries            |
+| {%docsBaseUrl%}/query/testing                     | Specs: answering requests, `@ethlete/query/testing` helpers and fakes         |
+| {%docsBaseUrl%}/query/query-forms                 | **Any filtered, searched, sorted or paged list** - `defineQueryForm`          |
+| {%docsBaseUrl%}/query/gql                         | GraphQL creators over GET/POST                                                |
+| {%docsBaseUrl%}/query/ws                          | socket.io rooms and live-updating responses                                   |
+| {%docsBaseUrl%}/query/legacy                      | The maintenance-mode `V2QueryClient` and its replacements                     |
+| {%docsBaseUrl%}/query/migrating-from-v2           | Codemods and the screen-by-screen move off the legacy client                  |
+| {%docsBaseUrl%}/query/migrating-from-ngrx-toolkit | The generator and interop that move a store off `@tomtomb/ngrx-toolkit`       |
+| {%docsBaseUrl%}/query-devtools/                   | The devtools panel and `provideQueryDevtools()`                               |
+
+## You need → use → read
+
+Before writing a helper, find your need here. Pages are under `{%docsBaseUrl%}/query/`.
+
+| You need                                                       | Use                                                                                                                                                                                                                                    | Read                |
+| -------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- |
+| One client per API                                             | `createQueryClient`, `injectApi()`                                                                                                                                                                                                     | `queries`           |
+| REST reads (auto-executing)                                    | `createGetQuery`, `createHeadQuery`, `createOptionsQuery`                                                                                                                                                                              | `http`              |
+| REST writes (manual)                                           | `createPostQuery`, `createPutQuery`, `createPatchQuery`, `createDeleteQuery`                                                                                                                                                           | `http`              |
+| The same behind a bearer token                                 | `createSecureGetQuery`, `createSecureHeadQuery`, `createSecureOptionsQuery`, `createSecurePostQuery`, `createSecurePutQuery`, `createSecurePatchQuery`, `createSecureDeleteQuery`                                                      | `http`, `auth`      |
+| Upload/download progress bar                                   | creator option `reportProgress: true`, then `loading().progress`                                                                                                                                                                       | `http`              |
+| Args that follow signals (route params, inputs, filters)       | `withArgs`                                                                                                                                                                                                                             | `features`          |
+| A filtered / searched / sorted / paged list synced to the URL  | `defineQueryForm`, `queryField`, `searchQueryField`, `sortQueryField`                                                                                                                                                                  | `query-forms`       |
+| Refetch on an interval                                         | `withPolling`                                                                                                                                                                                                                          | `features`          |
+| Next request once the previous settled, with a cursor from it  | `withLongPolling`                                                                                                                                                                                                                      | `features`          |
+| Refetch when some other signal changes                         | `withAutoRefresh`                                                                                                                                                                                                                      | `features`          |
+| Toast / log / react on success or failure                      | `withSuccessHandling`, `withErrorHandling`, `withLogging`                                                                                                                                                                              | `features`          |
+| Patch a loaded response in place (e.g. from a socket message)  | `withResponseUpdate`                                                                                                                                                                                                                   | `features`, `ws`    |
+| Page falls out of range after a filter shrinks the results     | `withPageResetOnError`, `isPageOutOfRangeError`                                                                                                                                                                                        | `features`          |
+| Package your own reusable query behavior                       | `createQueryFeature`                                                                                                                                                                                                                   | `features`          |
+| Refresh reads after a mutation (here and in other tabs)        | `injectApi().invalidateQueries({ url })`                                                                                                                                                                                               | `caching`           |
+| Refetch everything after a client-wide header changed          | `injectApi().refreshQueriesInUse()`                                                                                                                                                                                                    | `caching`           |
+| Show the previous data instantly on back navigation            | `keepUnusedFor` + `executionState().cachedResponse`                                                                                                                                                                                    | `caching`           |
+| Last known data after a reload or offline                      | `withQueryPersistence`, `createIndexedDbQueryPersistenceAdapter`, `createNoopQueryPersistenceAdapter`                                                                                                                                  | `persistence`       |
+| Tabs share responses, poll once, see each other's mutations    | `withMultiTabSync`                                                                                                                                                                                                                     | `multi-tab`         |
+| Parallel detail requests for a list of ids                     | `createQueryStack`, `transformArrayResponse`                                                                                                                                                                                           | `stacks`            |
+| Load more / infinite scroll / classic paging                   | `createPagedQueryStack`, `ethletePaginationAdapter` (and other adapters)                                                                                                                                                               | `stacks`            |
+| A GET whose args come from another GET's response              | `withArgs` reading the first query's `response()`                                                                                                                                                                                      | `dependent-queries` |
+| Run mutations in order, each using the previous result         | `querySequence`                                                                                                                                                                                                                        | `dependent-queries` |
+| Many edits with progress, time remaining and retry of failures | `createQueryBatch`                                                                                                                                                                                                                     | `batching`          |
+| Submit a signal form through a mutation, violations on fields  | `createQuerySubmission`                                                                                                                                                                                                                | `errors`            |
+| Own submit handler, or server-side validation while typing     | `executeUntilSettled`, `executeUntilSettled$`, `mapViolationsToFormErrors`, `validateWithQuery`                                                                                                                                        | `errors`            |
+| Understand the error shapes your API returns                   | `withEthleteApiErrors` (all), `withSymfonyErrors`, `withHtmlErrorParsing`                                                                                                                                                              | `errors`            |
+| Error text for display, or an error built by hand (tests)      | `queryErrorMessage`, `queryErrorMessages`, `createQueryErrorResponse`, `<et-query-error>`                                                                                                                                              | `errors`            |
+| Retry failed requests                                          | `withDefaultRetry`, `createDefaultRetryFn`                                                                                                                                                                                             | `errors`            |
+| Login / refresh / logout with bearer tokens                    | `createBearerAuthProvider`, `withAuthenticationQuery`, `withRefreshQuery`                                                                                                                                                              | `auth`              |
+| Protect routes, check roles or permissions                     | `createAuthGuard`, `canMatchWith`                                                                                                                                                                                                      | `auth`              |
+| "Remember me" auto-login                                       | `withPersistentAuth`                                                                                                                                                                                                                   | `auth`              |
+| Log out idle users                                             | `withInactivityLogout`                                                                                                                                                                                                                 | `auth`              |
+| Warn before the session expires                                | `withTokenExpirationWarning`                                                                                                                                                                                                           | `auth`              |
+| Revoke the token on logout                                     | `withTokenRevocation`                                                                                                                                                                                                                  | `auth`              |
+| Share login/logout across tabs                                 | `withBearerAuthMultiTabSync`                                                                                                                                                                                                           | `auth`              |
+| Auth telemetry events                                          | `withTracking`                                                                                                                                                                                                                         | `auth`              |
+| Tokens from SSO or a native shell                              | `provider.setTokens(access, refresh)`                                                                                                                                                                                                  | `auth`              |
+| Which of several queries is busy (v2 query collections)        | each query's `executionState()` in a `computed`; auth: `provider.executionState()`                                                                                                                                                     | `migrating-from-v2` |
+| GraphQL                                                        | `createGqlQueryViaGet`, `createGqlQueryViaPost`, `createGqlMutationViaGet`, `createGqlMutationViaPost`, `createSecureGqlQueryViaGet`, `createSecureGqlQueryViaPost`, `createSecureGqlMutationViaGet`, `createSecureGqlMutationViaPost` | `gql`               |
+| Realtime rooms over socket.io                                  | `createWebSocketClient`                                                                                                                                                                                                                | `ws`                |
+| Inspect queries, stacks, auth and cache at runtime             | `provideQueryDevtools()` + `@ethlete/query-devtools`                                                                                                                                                                                   | `/query-devtools/`  |
 
 ## Two generations - use the current one
 
-- **Current (use this):** signals-first, provider-based. `createQueryClient`,
-  `createGetQuery`/`createPostQuery`/…, `withArgs`. Everything imports from the
-  single entry `@ethlete/query`.
-- **Legacy (maintenance mode):** class-based `V2QueryClient`, `.prepare().execute()`,
-  `queryComputed`. Don't write new code against it.
+Write new code against the signals-first system (`createQueryClient`, `createGetQuery`, …,
+`withArgs`), all from the single entry `@ethlete/query`. The class-based `V2QueryClient`
+(`.prepare().execute()`, `queryComputed`) is in maintenance mode.
 
 ## Core usage
 
-One client per API, one creator per endpoint, one live query per component instance:
+One client per API, one bound creator per method, one query per endpoint, one live query
+per component instance:
 
 ```ts
 import { createQueryClient, createGetQuery, withArgs } from '@ethlete/query';
 
+// api.ts
 export const apiClient = createQueryClient({ name: 'api', baseUrl: API_URL });
-export const getPost = createGetQuery(apiClient)<GetPostArgs>((p) => `/posts/${p.pathParams.postId}`);
+export const getQuery = createGetQuery(apiClient);
+
+// posts.queries.ts
+export type GetPostQueryArgs = {
+  response: Post;
+  pathParams: { postId: string };
+};
+
+export const getPost = getQuery<GetPostQueryArgs>((p) => `/posts/${p.postId}`);
 
 // in a component (injection context):
 postId = input.required<string>();
@@ -54,82 +122,81 @@ post = computed(() => this.postQuery.response());
 
 - `GET`/`HEAD`/`OPTIONS` **auto-execute** - immediately when static/argless, or
   whenever `withArgs` produces new args. Mutations (`POST`/`PUT`/`PATCH`/`DELETE`)
-  never auto-execute; call `.execute({ args })`. A function route (`pathParams`)
+  never auto-execute; declare their args with `withArgs` too and call `.execute()`. A function route (`pathParams`)
   requires `withArgs` (dev-mode error otherwise).
+- A route function receives the path params themselves: `(p) => \`/posts/${p.postId}\``.
+- With bearer auth, bind the secure creators the same way:
+  `const secureGetQuery = createSecureGetQuery(apiClient, authProviderRef)`.
 - Queries live in a child injector tied to the creating component; destroyed with it.
 
+## Lists with filters, search, sort or paging: `defineQueryForm`
+
+Never wire list controls to the URL by hand (`injectQueryParams` + `router.navigate` +
+drafts + effects). `defineQueryForm` does URL sync, debounce, defaults and page resets:
+
+```ts
+qf = defineQueryForm({
+  fields: {
+    search: searchQueryField(),
+    sort: sortQueryField(),
+    page: queryField<number>({ defaultValue: 1, isResetBy: ['search', 'sort'] }),
+  },
+}).observe();
+
+users = getUsers(
+  withArgs(() => {
+    const { search, sort, page } = this.qf.value();
+
+    return { queryParams: { query: search, sortBy: sort?.active, sortOrder: sort?.direction, page } };
+  }),
+);
+```
+
+Bind form controls with `[formField]="qf.fields.search"`. `et-pagination` and
+`et-page-size-select` are not form controls: bind their `model` to the field's value signal,
+`[(page)]="qf.fields.page().value"`. `qf.value()` is the committed, debounced value. Each
+change pushes a history entry; pass `observe({ replaceUrl: true })` to replace it instead. See {%docsBaseUrl%}/query/query-forms for the other field creators,
+filter overlays and `activeFilterCount`.
+
 ## The query object
 
-Every state member is an **`ObservableSignal`** - a `Signal` that also has
-`.asObservable()`. So each is both a signal (call it) and a stream:
+Every state member is an **`ObservableSignal`** - call it, or `.asObservable()` it without an
+injection context of your own (it emits `null` first).
 
 - `response()` → `TResponse | null` (kept while re-executing; cleared on a failed re-exec).
+  To keep showing the last good data after a failure, read `cachedResponse` from the
+  `loading` or `failure` variant of `executionState()` - do not copy responses into a signal.
 - `loading()`, `error()` (normalized `QueryErrorResponse`), `args()`,
   `executionState()` (`{ type: 'loading' | 'success' | 'failure', … } | null`, great for `@switch`).
 - Methods: `execute({ args?, options? })`, `reset()`, `createSnapshot()`, `asReadonly()`.
 
-`query.response.asObservable()` binds to the query's own injector, so callers get
-an `Observable<T | null>` **without** needing their own injection context (unlike
-raw `toObservable`). It emits `null` first - `pipe(filter(r => r !== null))`.
-
-## Reactive args & features
-
-- **`withArgs(() => ({ pathParams, queryParams, body }))`** - runs like a `computed`;
-  re-runs when a signal it reads changes and re-executes the query. This is how you
-  drive **search-as-you-type**: back it with a search signal
-  (`withArgs(() => ({ queryParams: { search: this.search() } }))`). Return `null`
-  to park the query - args reset to `null`, pausing polling/auto-refresh.
-- **Prefer `withArgs` over passing `args` to `execute()`.** Args declared on the query
-  stay reactive: a `GET` re-executes itself when they change, and `withPolling` /
-  `withAutoRefresh` restart off the same signal - none of which happens for args handed
-  to `execute()`. A function route additionally throws without it. With `withArgs` in
-  place a mutation is just `.execute()`, which reuses the current `args()`. Reserve
-  `execute({ args })` for a one-off payload no signal holds (a form submit).
-- `withPolling({ interval })`, `withAutoRefresh({ onSignalChanges: [...] })`.
-- **`withLongPolling({ nextArgs })`** for a completion-driven chain instead of an interval: each
-  round starts once the previous settled, with args (a cursor) derived from its response. `nextArgs`
-  returning `null` ends the chain. Not `withPolling` with a small interval - and the two throw when
-  combined.
-- Side-effects: `withSuccessHandling`, `withErrorHandling`, `withLogging`.
-
-There is no built-in debounce operator - dedup/caching handles repeated identical
-requests; debounce at the input if you need it.
-
-## Bridging a query into RxJS / other APIs
-
-For a callback that must start one request and return one correlated result, use a
-manual query with `executeUntilSettled()`. Its frozen snapshot cannot be replaced by a
-later execution, and the observable completes after that one result.
-
-```ts
-class ItemSource {
-  private itemsQuery = getItems({ onlyManualExecution: true });
-
-  fetch(query: string) {
-    return defer(() => executeUntilSettled(this.itemsQuery, { args: { queryParams: { q: query } } })).pipe(
-      map((snapshot) => {
-        const response = snapshot.response();
+## Reactive args
 
-        if (response === null) throw snapshot.error();
+- **`withArgs(() => ({ pathParams, queryParams, body }))`** runs like a `computed` and
+  re-executes on change. Return `null` to park the query (pauses polling/auto-refresh).
+- **Prefer `withArgs` over `execute({ args })`.** Declared args keep a `GET` re-executing and
+  polling/auto-refresh restarting off the same signal; a function route throws without it. A
+  mutation with `withArgs` is just `.execute()`. Reserve `execute({ args })` for a one-off
+  payload no signal holds.
+- Search-as-you-type: read a debounced value (`searchQueryField()` debounces 300ms; every
+  query field takes `debounce`) - a raw input signal sends one request per keystroke.
+- `withLongPolling` and `withPolling` throw when combined.
 
-        return response.items;
-      }),
-    );
-  }
-}
-```
+## Bridging into RxJS or callbacks
 
-Do not set a search signal and immediately return the shared `response` stream: the
-previous response is retained during re-execution and can be the first non-null emission.
-Unsubscribing from the wrapper stops result delivery but does not by itself abort the
-promise-backed execution; use the query's reactive `withArgs` lifecycle when cancellation
-is a requirement rather than a callback contract.
+For a callback that must return one correlated result, run a manual query
+(`{ onlyManualExecution: true }`) through `executeUntilSettled$(query, { args })` - cold, its
+snapshot is frozen to that execution, and unsubscribing aborts the request. Keep the Promise
+`executeUntilSettled` for an `async` signal-forms `submit()`. Never set a signal and return the shared `response`
+stream: the retained previous response can be the first non-null emission. See
+{%docsBaseUrl%}/query/queries#the-query-object.
 
 ## Gotchas
 
-- Signals-first: read `query.response()` in templates/computeds; it's **nullable**
-  (`?? []` / `filter(Boolean)` as needed).
-- Don't reach for the legacy client for new code.
+- `query.response()` is **nullable** (`?? []` / `filter(Boolean)` as needed).
 - `.execute()` defaults `args` to the current `args()` when omitted.
 - Anything under a query's `subtle` namespace is an unsupported escape hatch - never
   treat it as public API.
+- Use `withArgs` for mutations too. Never reach for `execute({ args })` plus
+  `silenceMissingWithArgsFeatureError` unless the args really exist only at call time - the
+  flag is an escape hatch, not the mutation pattern.

package/content/skills/rxjs-signals/SKILL.md

@@ -63,6 +63,26 @@ toObservable(page)
   .subscribe();
 ```
 
+## An effect that only writes a signal is a derivation
+
+If an `effect()` does nothing but `.set()` a signal, even behind an `if`, the value is derived
+state: use `computed()` when it is read-only, `linkedSignal()` when the user can still
+overwrite it. `ethlete/prefer-linked-signal` flags the plain cases. Keep `effect()` for work
+that leaves the signal graph: DOM, storage, logging, third-party APIs.
+
+```ts
+// ❌
+effect(() => {
+  if (this.items().length) this.selected.set(this.items()[0]);
+});
+
+// ✅ the previous value stays when the list is empty
+selected = linkedSignal<Item[], Item | null>({
+  source: this.items,
+  computation: (items, previous) => items[0] ?? previous?.value ?? null,
+});
+```
+
 ## Prefer `@ethlete/core` helpers
 
 Lint nudges these, but reach for them by default: `injectViewportSize()`,

package/content/skills/sdk-docs/SKILL.md

@@ -20,6 +20,13 @@ Two sources, both authoritative for different things:
 | **Docs site** | {%docsBaseUrl%}     | Prose guides: what a thing is for, options, defaults, behaviour, migration notes                 |
 | **Storybook** | {%sdkStorybookUrl%} | The live component: every variant rendered, the real controls, and the exact markup a story uses |
 
+## First: app setup
+
+Before the first component, work through `{%docsBaseUrl%}/components/setup` - the 62.5% root
+font size, Tailwind 4 theme generation, a `type: 'error'` color theme, and the providers
+(`provideOverlay`, `provideDateLocale`, label tokens, …). Missing any of them fails at runtime,
+not at compile time.
+
 ## Finding the right page
 
 Page URLs follow `{%docsBaseUrl%}/<lib>/<topic>`. The library sections:
@@ -34,13 +41,34 @@ Page URLs follow `{%docsBaseUrl%}/<lib>/<topic>`. The library sections:
 
 Component domains under `/components/`:
 
-`accordion` `bracket` `bracket-rounds-list` `breadcrumb` `button` `calendar` `carousel`
-`cascader` `chip` `choice-inputs` `date-time-inputs` `dropzone` `error-codes`
-`filter-overlay` `floating-action` `focus-ring` `forms` `grid` `icon` `loader`
-`localization` `masonry` `match` `menu` `mixed-state` `notification` `overlay-openers`
-`overlays` `pagination` `picture` `query-devtools` `query-error` `rich-text-editor`
-`scrollable` `select` `skeleton` `slider` `sport-recipes` `standings` `stream` `table`
-`tabs` `text-inputs` `time-picker` `toggletip` `tooltip`
+`accordion` `avatar` `badge` `banner` `bracket` `bracket-prediction` `bracket-rounds-list`
+`breadcrumb` `button` `calendar` `card` `carousel` `cascader` `chart` `chip`
+`choice-inputs` `command-palette` `copy-button` `date-time-inputs` `description-list`
+`divider` `dropzone` `empty-state` `error-codes` `filter-overlay` `floating-action`
+`focus-ring` `forms` `grid` `icon` `kbd` `line-chart` `loader` `localization` `masonry`
+`match` `menu` `mixed-state` `notification` `overlay-openers` `overlays` `pagination`
+`picture` `pie-chart` `progress-steps` `query-error` `rich-text-editor` `sankey-chart`
+`scheduler` `scrollable` `scrollbar` `select` `setup` `skeleton` `slider` `sport-recipes`
+`standings` `standings-pick` `stream` `table` `tabs` `text-inputs` `time-picker`
+`timeline` `toggletip` `toolbar` `tooltip` `tree`
+
+**Check this list before you build any UI by hand.** Some needs hide behind a name you
+would not guess:
+
+| You need                                   | Read                                      |
+| ------------------------------------------ | ----------------------------------------- |
+| Bar or stacked bar chart, series legend    | `chart`                                   |
+| Line, pie, flow chart                      | `line-chart`, `pie-chart`, `sankey-chart` |
+| Progress bar, spinner                      | `loader`                                  |
+| Initials or user picture in a circle       | `avatar`                                  |
+| "No results" or empty table state          | `empty-state`                             |
+| Failed request with a retry button         | `query-error`                             |
+| Status pill, count                         | `badge`                                   |
+| Tab strip that switches a view or a filter | `tabs` (nav tabs)                         |
+| Dialog, bottom sheet, side panel           | `overlays`, `overlay-openers`             |
+| Label and value pairs                      | `description-list`                        |
+| Stepper, wizard progress                   | `progress-steps`                          |
+| Providers and styles a new app needs       | `setup`                                   |
 
 So the table guide is `{%docsBaseUrl%}/components/table`, the menu guide
 `{%docsBaseUrl%}/components/menu`, and so on.

package/content/skills/sdk-update/SKILL.md

@@ -16,7 +16,7 @@ the migrations, so a hand-written bump skips every one of them silently.
 ## 1. See what is pending
 
 ```bash
-yarn et update --check
+{%packageRunner%} et update --check
 ```
 
 It prints one line per package, `installed → target`, and exits 1 while an update is pending. It
@@ -26,9 +26,9 @@ prerelease stays on `next`.
 Name a package to limit the run, short or in full:
 
 ```bash
-yarn et update core            # only @ethlete/core
-yarn et update core --to 5.0.0-next.55
-yarn et update --tag latest    # leave the prerelease line
+{%packageRunner%} et update core            # only @ethlete/core
+{%packageRunner%} et update core --to 5.0.0-next.55
+{%packageRunner%} et update --tag latest    # leave the prerelease line
 ```
 
 ## 2. Run it
@@ -37,19 +37,24 @@ The working tree must be clean - the codemods rewrite files, and you need a diff
 Commit or stash first, then:
 
 ```bash
-yarn et update
+{%packageRunner%} et update
 ```
 
 In order, it writes the new ranges into every `package.json` in the repo that declares the package -
 an Nx library manifest included, not only the root one - runs the install, reads the migrations out of
-the freshly installed packages, runs every codemod, and writes what is left to `.ethlete/update`.
+the freshly installed packages, runs every codemod, regenerates the agent rules and skills with
+`ethlete-agents sync` when `@ethlete/agent-rules` moved, and writes what is left to `.ethlete/update`.
+
+An older `@ethlete/cli` skips the sync. If the run moved `@ethlete/agent-rules` and printed no
+`ethlete-agents sync` line, run `{%packageRunner%} ethlete-agents sync` yourself before the first task: the
+tasks assume the guidance of the new version.
 
 If the install or a codemod fails, the run stops and leaves `.ethlete/update/pending.json` behind.
 Fix the cause, then continue - do not start over, or the migrations of the versions already installed
 are skipped:
 
 ```bash
-yarn et update --continue
+{%packageRunner%} et update --continue
 ```
 
 ## 3. Work the task list

package/content/skills/story-styling/SKILL.md

@@ -12,9 +12,10 @@ vars: [themeStylesheet]
 
 Two separate rules, often confused:
 
-1. **Component source is plain CSS, never Tailwind.** The `.css` next to a
-   component, wrapped in `@layer components`, using surface/color tokens - see
-   {%skill:theming%}.
+1. **A library component's source is plain CSS, never Tailwind.** The `.css` next
+   to a component a library ships, wrapped in `@layer components`, using
+   surface/color tokens - see {%skill:theming%}. Application components are the
+   opposite: they use Tailwind utilities in their templates.
 2. **Story files may use Tailwind** (`*.stories.ts`, anything under a `stories/`
    folder) for demo layout only - the frame around the component, not the
    component's own look.
@@ -33,11 +34,11 @@ error and no warning, the element just renders unstyled. A theme that does this:
 leaves `bg-blue-500`, `text-gray-700` and `text-sm` as dead strings, even though
 they are "real" Tailwind classes.
 
-**Read the theme before reaching for an unfamiliar utility.** This project's is
-`{%themeStylesheet%}`:
+**Read the theme before reaching for an unfamiliar utility.** This project's lives in
+`{%themeStylesheet%}` (a file, or a folder of theme files):
 
 ```bash
-grep -nE -- '--(color|text|font|spacing)-' {%themeStylesheet%}
+grep -rnE -- '--(color|text|font|spacing)-' {%themeStylesheet%}
 ```
 
 If `@theme` doesn't define the token, the class doesn't exist. Check rather than

package/content/skills/styleguide/lint-rule-lookup.md

@@ -7,7 +7,7 @@ convention. Run lint with `--fix`; do not hand-check this table before linting.
 | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | No `any` / `$any()`; narrow `unknown`                                | `@typescript-eslint/no-explicit-any`, `@angular-eslint/template/no-any`                                                                                                                                             |
 | Static strings and booleans use attributes                           | `@angular-eslint/template/prefer-static-string-properties`, `ethlete/prefer-static-boolean-properties`                                                                                                              |
-| `type`, not `interface`                                              | `@typescript-eslint/consistent-type-definitions`                                                                                                                                                                    |
+| `type`, not `interface` (module augmentations stay interfaces)       | `ethlete/consistent-type-definitions`                                                                                                                                                                               |
 | No `enum` or `const enum`                                            | `ethlete/no-enum`                                                                                                                                                                                                   |
 | `const` by default; one declaration per statement                    | `no-var`, `prefer-const`, `one-var`                                                                                                                                                                                 |
 | Strict equality                                                      | `eqeqeq`                                                                                                                                                                                                            |

package/content/skills/theming/SKILL.md

@@ -102,16 +102,15 @@ the interactive element itself, never on a wrapper.
   with no error. Percentages and viewport units (`vh`, `vw`, `dvh`) are fine. When the
   default has to be relative, use `syntax: '*'` with no `initial-value` and put the
   default in a fallback at each use site: `var(--et-skeleton-size, 1em)`.
-  `yarn lint:css-properties` checks this, and pre-commit runs it on staged files.
 - `--et-theme-color-primary-*` always resolves to the **nearest color scope**. A
   hardcoded semantic color in CSS can't be replaced by it unless the right theme is
   provided on that element.
 - A static fallback (`var(--et-surface-border-solid, rgb(255 255 255 / 0.1))`) is
   permitted for theme-less setups, but themes make it unnecessary. `injectErrorTheme()`
   is a hard requirement wherever it is used.
-- **Cascade layers, not `:where()`, are what let a Tailwind utility override component
-  CSS.** Wrap every component CSS file in `@layer components { … }`; `:where()` only
-  flattens a component's own modifiers to single-class weight. See the `styling` rule.
+- **Cascade layers, not `:where()`, decide who wins against SDK component CSS.** SDK
+  styles live in `@layer components`, so a utility or unlayered app CSS overrides them.
+  An app rule inside `@layer components` loses. See the `app-styling` rule.
 
 Styling a **story** file rather than a component? The colour rule is the same. Check the
 repository's Storybook guidance before assuming a Tailwind utility exists.