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

package/CHANGELOG.md

@@ -1,5 +1,55 @@
 # @ethlete/agent-rules
 
+## 0.1.0-next.18
+
+### Minor Changes
+
+- Timetrack: every write command now queues for the user's approval in the app and prints an approval id; `timetrack approval <id>` reads the outcome, and the agent contract moves to version 3.
+- Timetrack: add `timetrack sync <day>` to plan a day's Tempo sync, and `--write --plan <hash>` to write the confirmed plan; `worklogs --json` now reports a midnight `startTime`.
+- Timetrack: add `timetrack worklog --delete <id> --day <YYYY-MM-DD>` to delete one of the account's own Tempo worklogs; the app refuses any other id.
+- Timetrack: add `timetrack standins --merge <id> --into <id>` and the `standIn.merge` agent op, which waits for the user's approval. `standIn.list` now reports `hiddenOn` and `mergedIds`.
+
+### Patch Changes
+
+- `parseBranch` now reads a leading issue key from a deprecated spelling such as `dev-FIP-2721-subject`, so it returns the key and a rename suggestion that carries it.
+- The design exploration skill now tells an agent in the ethlete SDK that the user reads calls in Ethlete Studio (`yarn studio`), so the agent does not start `yarn design` next to it.
+- Git-flow matches a project key prefix as a whole word, keeps the subject with a grouped `keyPattern`, drops the `CI_JOB_TOKEN` fallback, and prints an undo hint when the push after a repair rename fails.
+- `git-flow repair` sends `GITLAB_TOKEN` only to the hosts in `GITLAB_HOST` or `CI_SERVER_HOST`, and no longer follows redirects.
+- `git-flow repair` and `start` no longer mistake a remote branch that only ends with the name, such as `team/feat/x` for `feat/x`, for the branch.
+- `sync` writes only changed files, survives dangling symlinks, warns about an unparseable hook settings file, and rejects duplicate frontmatter keys; `output-style --remove` works for a style no longer shipped.
+- `timetrack` rejects a flag whose value is another flag, a malformed `naming` day and a non-positive `--limit`; `day --out` honours `--json` and resolves against the root.
+- `timetrack` reads a date-only `--at`, `--from` or `--to` as local midnight and accepts a local `HH:MM`, and `timetrack project` resolves a relative path.
+- `sync` refuses a file whose ethlete marker block has lost a marker, instead of deleting the text after it on the next run.
+- Git flow: a lowercase `<word>-<number>` branch subject such as `step-2-rework` is no longer read as an issue key when no key prefixes are configured.
+- `tableSortQueryField()` holds the `et-table` sort and keeps it in the URL, so `[(sort)]="qf.fields.sort().value"` binds it with no mapping.
+- Recommend `sonnet` for scoped subagent work and keep `opus` for hard work, in the subagent-models rule and the subagent-model-policy hook.
+
+## 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

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
@@ -223,7 +224,8 @@ sets no subject falls back to its summary, and the printed plan says which of th
 `git-flow repair [ref]` derives the conforming name (`--key FIP-2900` when the old name
 carries no issue key, `--to <branch>` to override), renames the branch locally and on the
 remote, and retargets the open merge requests aimed at it through the GitLab API.
-`GITLAB_TOKEN` needs the `api` scope.
+`GITLAB_TOKEN` needs the `api` scope, and is sent only to the hosts named in `GITLAB_HOST`
+(comma-separated) or, in a GitLab CI job, `CI_SERVER_HOST`.
 
 Everything is checked before the first mutation, and it refuses rather than half-finishing:
 
@@ -231,7 +233,7 @@ Everything is checked before the first mutation, and it refuses rather than half
   move a merge request to another source branch, and closing it would lose its discussion -
   merge or close it first.
 - A branch that is pushed but whose merge requests cannot be listed (no token, or a remote
-  that is not GitLab) blocks too. `--no-mr-check` asserts that none point at it.
+  that is not a configured GitLab host) blocks too. `--no-mr-check` asserts that none point at it.
 - If a retarget fails halfway, the old branch is still there and the recovery commands are
   printed.
 
@@ -247,10 +249,16 @@ npx ethlete-agents timetrack search "password"     # open issues of the picked p
 npx ethlete-agents timetrack project               # which project does this repo log into?
 npx ethlete-agents timetrack create --summary "…"  # file a ticket with the instance's settings
 npx ethlete-agents timetrack log --issue FIP-2177 --minutes 45
+npx ethlete-agents timetrack approval <id>         # where a queued write stands
 ```
 
 `--json` prints the raw answer instead of lines. `git-flow start` uses the same channel.
 
+**Every write waits for the user.** `create`, `log` and every other write answer at once with an
+approval id and write nothing; the user approves or rejects the request in the app, and
+`approval <id>` reads the outcome. A request still waiting at the end of its day expires.
+`TIMETRACK_CLIENT` names the caller in the queue.
+
 **How it connects.** The app binds a loopback socket and writes its port and a fresh token
 into `agent.json` in its own data directory (`~/.local/share/io.ethlete.timetrack/` on Linux,
 `~/Library/Application Support/…` on macOS, `%APPDATA%\…` on Windows), readable by its owner

package/content/hooks/subagent-model-policy.py

@@ -43,8 +43,10 @@ would run on the model leading this session - which is how one expensive model e
 Call the tool again with `model` set:
 
 - `haiku` - mechanical lookups: grep, find, read a file, run a command and report what it said.
-- `opus` - the default for real work: code changes, tests, debugging, reviewing a diff.
-- `sonnet` - a middle ground where opus is more than the task needs.
+- `sonnet` - scoped work with a clear target: a fix in a named file, a spec, a docs page, a lint cleanup, \
+research that needs reasoning. Sonnet 5.5 is close to opus here and costs less.
+- `opus` - hard work: a bug with no known cause, a change across many files, a review of a diff, and any task \
+sonnet did not finish.
 - `fable` - judgment-heavy work: planning, design, cross-cutting review, leading other subagents. The most \
 expensive of the four, so choosing it asks the user first.
 
@@ -54,7 +56,7 @@ effort, so a call that names one needs no `model` of its own."""
 
 FABLE_REASON = """This subagent would run on fable, the most expensive model. Approve it where the task is \
 judgment-heavy - planning, design, cross-cutting review, or leading other subagents. Deny it for implementation \
-(`model: "opus"`) or for a mechanical lookup (`model: "haiku"`), then repeat the call with that model."""
+(`model: "sonnet"` or `"opus"`) or for a mechanical lookup (`model: "haiku"`), then repeat the call with that model."""
 
 
 def agent_name(argv):

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/rules/subagent-models.md

@@ -1,6 +1,6 @@
 ---
 name: subagent-models
-description: A subagent's model is an explicit choice on every call - haiku for lookups, opus for work, fable for judgment.
+description: A subagent's model is an explicit choice on every call - haiku for lookups, sonnet for scoped work, opus for hard work, fable for judgment.
 kind: rule
 scope: both
 ---
@@ -11,12 +11,12 @@ A subagent spawned without a `model` runs on the model leading the session, so a
 model ends up doing every small job it delegates. **Set `model` on every call**, matched to the
 task:
 
-| Model    | The work it fits                                                                                                                                         |
-| -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `haiku`  | Mechanical lookups: grep, find, read a file, run a command and report what it said.                                                                      |
-| `sonnet` | A middle ground where opus is more than the task needs.                                                                                                  |
-| `opus`   | The default for real work: code changes, tests, debugging, reviewing a diff.                                                                             |
-| `fable`  | Judgment-heavy work: planning, design, cross-cutting review, leading other subagents. The most expensive of the four, so ask the user before picking it. |
+| Model    | The work it fits                                                                                                                                                             |
+| -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `haiku`  | Mechanical lookups: grep, find, read a file, run a command and report what it said.                                                                                          |
+| `sonnet` | Scoped work with a clear target: a fix in a named file, a spec, a docs page, a lint cleanup, research that needs reasoning. Sonnet 5.5 is close to opus here and costs less. |
+| `opus`   | Hard work: a bug with no known cause, a change across many files, a review of a diff, and any task sonnet did not finish.                                                    |
+| `fable`  | Judgment-heavy work: planning, design, cross-cutting review, leading other subagents. The most expensive of the four, so ask the user before picking it.                     |
 
 Effort follows the prompt, not a parameter: scope the prompt to one question, name what "done"
 means, and say "keep it brief" for a lookup. Two calls need no `model` of their own - a named

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

@@ -67,7 +67,9 @@ drawings. A project the config names not draws bare.
 Start the page with `et design [checkout]`, which serves the port `config.json` names. The
 checkout defaults to the working directory, and `DE_PORT` overrules the config, so two
 checkouts can be drawn at once. A repository that builds the tool rather than installing it
-wraps this in a script - in the ethlete SDK, `yarn design` and `yarn design:check`.
+wraps this in a script - in the ethlete SDK, `yarn design:check`. There, the user reads the
+calls in Ethlete Studio, started with `yarn studio`, and Studio serves the page itself. Do not
+start `yarn design` next to it.
 
 Ethlete Studio carries its own copy of the tool, so it draws a checkout that installs nothing.
 The machine still needs Node, and the render stage still needs `playwright` where the copy in

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