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

package/content/skills/timetrack/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: timetrack
-description: How to reach Jira from any repo through the running Timetrack app - look up an issue, search for one, ask which project a repo logs into, file a ticket, add a worklog row, read the evidence a day holds, or list the work that still waits for a ticket. Read whenever a task needs Jira data, a Jira write, or the day's own events, and never put a Jira token in a repo.
+description: How to reach Jira from any repo through the running Timetrack app - look up an issue, search for one, ask which project a repo logs into, file a ticket, add a worklog row, read the user's own Tempo worklogs, read their Google Calendar, read the evidence a day holds, or list the work that still waits for a ticket. Read whenever a task needs Jira data, a Jira write, or the day's own events, and never put a Jira token in a repo.
 kind: skill
 scope: both
 ---
@@ -11,12 +11,12 @@ scope: both
 in this machine's keychain, and every repository asks it:
 
 ```bash
-npx ethlete-agents timetrack status                 # is the app reachable, and what does it hold?
-npx ethlete-agents timetrack issue FIP-2177         # one issue: summary, type, parent, subject
-npx ethlete-agents timetrack search "password"      # open issues of the picked projects
-npx ethlete-agents timetrack project                # which project does this repo log into?
-npx ethlete-agents timetrack instance               # the instance's own levels and custom fields
-npx ethlete-agents timetrack standins               # work the user named that Jira does not hold yet
+{%packageRunner%} ethlete-agents timetrack status                 # is the app reachable, and what does it hold?
+{%packageRunner%} ethlete-agents timetrack issue FIP-2177         # one issue: summary, type, parent, subject
+{%packageRunner%} ethlete-agents timetrack search "password"      # open issues of the picked projects
+{%packageRunner%} ethlete-agents timetrack project                # which project does this repo log into?
+{%packageRunner%} ethlete-agents timetrack instance               # the instance's own levels and custom fields
+{%packageRunner%} ethlete-agents timetrack standins               # work the user named that Jira does not hold yet
 ```
 
 Add `--json` to any of them when you need to read a field rather than a line.
@@ -45,6 +45,8 @@ nobody can rotate.
 | `standins --remove <id>`               | A placeholder is wrong or too wide, and the user asked you to delete it   |
 | `standins --rename <id> --name <text>` | The name a placeholder carries is wrong, and the user asked you to fix it |
 | `naming [YYYY-MM-DD]`                  | A checkout was never offered a name and you need the step that stopped    |
+| `worklogs [from] [to]`                 | You need what the user already booked in Tempo over a span of days        |
+| `calendar [from] [to]`                 | You need the user's meetings and calendar entries over a span of days     |
 
 `git-flow start` uses the same channel, so a branch is named from the real issue rather than
 from a key you typed. Follow the repository's branch workflow when creating a branch.
@@ -54,8 +56,8 @@ from a key you typed. Follow the repository's branch workflow when creating a br
 The app's store is encrypted, so no shell reads a day off disk. `day` is the only way in:
 
 ```bash
-npx ethlete-agents timetrack day                       # today: how many events, and of which kind
-npx ethlete-agents timetrack day 2026-09-10 --out /tmp/day.json
+{%packageRunner%} ethlete-agents timetrack day                       # today: how many events, and of which kind
+{%packageRunner%} ethlete-agents timetrack day 2026-09-10 --out /tmp/day.json
 ```
 
 A real day holds thousands of events, so **never print them**. Write them to a file with
@@ -72,17 +74,17 @@ day as it was observed - window titles, paths and messages - so delete it when y
 timeline, with the id every edit names a row by, the day's totals and its warnings.
 
 ```bash
-npx ethlete-agents timetrack rows                      # today
-npx ethlete-agents timetrack rows 2026-09-10 --json
+{%packageRunner%} ethlete-agents timetrack rows                      # today
+{%packageRunner%} ethlete-agents timetrack rows 2026-09-10 --json
 ```
 
 `edit` changes one row. Pass exactly one change per call:
 
 ```bash
-npx ethlete-agents timetrack edit 'ABC-1@2026-09-10T11:00:00.000Z' --day 2026-09-10 \
+{%packageRunner%} ethlete-agents timetrack edit 'ABC-1@2026-09-10T11:00:00.000Z' --day 2026-09-10 \
   --from 2026-09-10T13:15:00Z --to 2026-09-10T17:00:00Z
-npx ethlete-agents timetrack edit '<row-id>' --issue ABC-2
-npx ethlete-agents timetrack edit '<row-id>' --state rejected
+{%packageRunner%} ethlete-agents timetrack edit '<row-id>' --issue ABC-2
+{%packageRunner%} ethlete-agents timetrack edit '<row-id>' --state rejected
 ```
 
 Both commands move the app's own review to that day, so the user sees what you read and what you
@@ -99,8 +101,8 @@ the background projects and the applications the user has ruled in or out. It ho
 account and no token, so it is safe to quote back to the user.
 
 ```bash
-npx ethlete-agents timetrack rules            # a summary of the rules
-npx ethlete-agents timetrack rules --json     # the whole answer
+{%packageRunner%} ethlete-agents timetrack rules            # a summary of the rules
+{%packageRunner%} ethlete-agents timetrack rules --json     # the whole answer
 ```
 
 Read it before claiming a band should have been named something: a rule that donates its time
@@ -113,8 +115,8 @@ A **stand-in** is a name the user gave work that Jira does not hold yet. It take
 days and across checkouts, and it books nothing. `standins` lists them:
 
 ```bash
-npx ethlete-agents timetrack standins         # the open ones, oldest first
-npx ethlete-agents timetrack standins --json  # the whole answer, resolved ones included
+{%packageRunner%} ethlete-agents timetrack standins         # the open ones, oldest first
+{%packageRunner%} ethlete-agents timetrack standins --json  # the whole answer, resolved ones included
 ```
 
 **Never open or resolve a stand-in.** The name is the user's own word for their work, and the
@@ -150,7 +152,7 @@ reading `--json` yourself.
 The name is only wrong, and the work behind it is right:
 
 ```bash
-npx ethlete-agents timetrack standins --rename <id> --name '20260921 competition navigation rework'
+{%packageRunner%} ethlete-agents timetrack standins --rename <id> --name '20260921 competition navigation rework'
 ```
 
 The days it holds and the rules that name it stay, which is what a delete and a fresh record would
@@ -163,8 +165,8 @@ A record covering a whole checkout is repaired rather than deleted, because a de
 days. `--split` re-cuts it into one record per directory, and moves each day onto the right one:
 
 ```bash
-npx ethlete-agents timetrack standins --split <id>              # the plan, writes nothing
-npx ethlete-agents timetrack standins --split <id> --force      # carry it out
+{%packageRunner%} ethlete-agents timetrack standins --split <id>              # the plan, writes nothing
+{%packageRunner%} ethlete-agents timetrack standins --split <id> --force      # carry it out
 ```
 
 Without `--force` it prints every directory the commits name, with its commit count and its days,
@@ -191,7 +193,7 @@ the split refuses it.
 You may delete one, because that takes a name away rather than putting one on the day:
 
 ```bash
-npx ethlete-agents timetrack standins --remove <id>
+{%packageRunner%} ethlete-agents timetrack standins --remove <id>
 ```
 
 The rule that named it goes with it, and what happens next is worth knowing before you ask:
@@ -211,8 +213,8 @@ card is either drawn or it is not, and every step that can stop it is invisible
 `naming` names the step:
 
 ```bash
-npx ethlete-agents timetrack naming              # today
-npx ethlete-agents timetrack naming 2026-09-14
+{%packageRunner%} ethlete-agents timetrack naming              # today
+{%packageRunner%} ethlete-agents timetrack naming 2026-09-14
 ```
 
 It reports whether a Tempo token is stored, how far the read of the worklog history got, and for each
@@ -220,13 +222,46 @@ checkout the day saw either the offer or the reason there is none - `already-nam
 `no-project-link`, `no-history`, `project-too-small`, `too-few-days` or `share-too-low`. A `history`
 of `failed` or `no-token` explains every checkout at once, so read that line first.
 
+## What Tempo already holds
+
+`worklogs` reads the user's own Tempo worklogs straight from Tempo, whoever wrote them. It is
+read-only, and the app keeps the Tempo token:
+
+```bash
+{%packageRunner%} ethlete-agents timetrack worklogs                          # the last 7 days
+{%packageRunner%} ethlete-agents timetrack worklogs 2026-09-01 2026-09-24    # both days included
+{%packageRunner%} ethlete-agents timetrack worklogs 2026-09-01 2026-09-24 --json
+```
+
+Without `--json` it prints one line per booked day: the total, then minutes per issue. `--json`
+answers each worklog with its day, `startTime` where Tempo holds one, `durationMs`, `issueKey` and
+description. A span is at most 92 days. The descriptions are the user's own words, so quote them
+only when the task needs them.
+
+## What the calendar holds
+
+`calendar` reads the Google calendars the app watches, straight from Google and read-only. The app
+keeps the Google token:
+
+```bash
+{%packageRunner%} ethlete-agents timetrack calendar                          # the last 7 days
+{%packageRunner%} ethlete-agents timetrack calendar 2026-09-01 2026-09-24    # both days included
+{%packageRunner%} ethlete-agents timetrack calendar 2026-09-01 2026-09-24 --json
+```
+
+Without `--json` it prints each day with its meeting hours, then one line per entry: start, minutes,
+title, and the user's answer where it is not a yes. All-day and declined entries are listed but not
+counted. `--json` answers each entry with `calendarId`, `day`, `startMs`, `endMs`, `allDay`, `title`,
+`attendeeCount` and `response`. A span is at most 92 days. Titles come from whoever sent the
+invitation, so quote them only when the task needs them.
+
 ## Writes
 
 Two commands write, so both need the user to have asked for them in this conversation:
 
 ```bash
-npx ethlete-agents timetrack create --summary "Reset password mail is not sent" --project FIP
-npx ethlete-agents timetrack log --issue FIP-2177 --minutes 45 --description "pairing call"
+{%packageRunner%} ethlete-agents timetrack create --summary "Reset password mail is not sent" --project FIP
+{%packageRunner%} ethlete-agents timetrack log --issue FIP-2177 --minutes 45 --description "pairing call"
 ```
 
 - **`create`** files the issue with the instance's own ticket settings - its type, its parent

package/content/skills/verify-in-app/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: verify-in-app
+description: Verify a UI change in the running app by driving it headlessly with Playwright - screenshots, computed styles, pointer and cursor state - and prove a fix with a test that fails without it. Use whenever you change a view, a component or its styles and need to confirm what renders, not just that it compiles.
+kind: skill
+scope: consumer
+---
+
+# Verify a UI change in the running app
+
+A build that passes says nothing about what the user sees. Serve the app, drive the real page in
+a headless browser, and assert on the rendered DOM and computed styles.
+
+## 1. Serve the app
+
+It may already be running. Check before starting a second instance - the dev server prompts for
+another port and hangs:
+
+```bash
+curl -s -o /dev/null -w "%{http_code}" http://localhost:4200/
+```
+
+- `200` → it is up.
+- anything else → start it in the background and poll the curl above until it answers (a cold
+  build can take a minute):
+
+  ```bash
+  npx nx serve <app>
+  ```
+
+The port and any proxy config live in the app's `project.json` `serve` target. A view behind a
+login needs a session: log in once through the form in the script, or seed the token storage the
+app reads before `page.goto`.
+
+## 2. Drive it with Playwright
+
+Use the `playwright` package from the repo's `node_modules`. Write the script in a scratch
+directory outside the repo and run it with `node`:
+
+```js
+import { createRequire } from 'node:module';
+
+const require = createRequire(`${process.cwd()}/`);
+const { chromium } = require('playwright');
+
+const browser = await chromium.launch();
+const page = await browser.newPage({ viewport: { width: 1280, height: 900 } });
+
+await page.goto('http://localhost:4200/players?search=mul', { waitUntil: 'domcontentloaded' });
+await page.waitForSelector('.players-table', { state: 'attached' });
+
+const state = await page.$eval('.players-table', (el) => {
+  const cs = getComputedStyle(el);
+  return { display: cs.display, color: cs.color, rows: el.querySelectorAll('tr').length };
+});
+console.log(JSON.stringify(state));
+
+await page.screenshot({ path: '/tmp/players.png', fullPage: true });
+await browser.close();
+```
+
+Then read the screenshot back and look at it.
+
+- **`playwright` is CommonJS** - resolve it with `createRequire`; a named ESM import fails.
+- **`waitUntil: 'domcontentloaded'`, never `networkidle`** - the dev server's live-reload socket
+  and any polling query keep the network busy forever.
+- **`waitForSelector` waits for visible by default.** Pass `{ state: 'attached' }` for anything
+  correctly hidden (`opacity: 0`, collapsed, `inert`).
+- **Overlays render at the end of `<body>`,** not inside the view that opened them. Query them from
+  `page`, not from the view's element.
+- After a click that starts a transition, wait out its duration before reading final styles.
+
+## 3. Pointer and cursor state
+
+`getComputedStyle(el).cursor` reports what the stylesheet says, not what the pointer gets - an
+overlay, a backdrop or `pointer-events: none` in between changes the answer. Ask the page which
+element is under the point instead:
+
+```js
+const hit = await page.evaluate(
+  ([x, y]) => {
+    const el = document.elementFromPoint(x, y);
+    return el && { tag: el.tagName, class: el.className, cursor: getComputedStyle(el).cursor };
+  },
+  [640, 300],
+);
+```
+
+`elementFromPoint` returns `null` outside the viewport, so use a viewport tall enough for the
+point, or scroll the target into view first. Hover with `page.mouse.move(x, y)` before reading
+`:hover` styles.
+
+## 4. Prove a fix with a test that bites
+
+A screenshot shows the fix once; a test keeps it. For a bug fix, write the spec (a unit spec for
+logic, or a Playwright e2e spec where the app has one), then:
+
+1. run it against the fix - it passes;
+2. revert the fix (stash it, or comment the one line out) and run it again - it **must fail**;
+3. restore the fix.
+
+A test that passes both ways asserts on the wrong thing. Fix the test before you call the change
+done.
+
+## 5. Report
+
+Say what you drove (URL, clicks, viewport) and what you observed, with the numbers you read. Keep
+the script and screenshots in the scratch directory, not the repo.

package/migrations/app-styling-utilities.md

@@ -0,0 +1,114 @@
+# Style app components with Tailwind utilities
+
+The earlier guidance left app styling open, so app components were often styled with a BEM class
+system or a `.css` file per component. The `app-styling` rule now says: every app component is laid
+out and styled with Tailwind utility classes in its template, and CSS is written only for what a
+utility cannot express.
+
+## Before you start
+
+`et update` regenerates the agent rules when it moves `@ethlete/agent-rules`. If this repo has no
+`app-styling` rule yet (in `AGENTS.md`, or under `.claude/rules/ethlete/`), run
+`ethlete-agents sync` with this repo's package manager (`yarn`, `pnpm exec` or `npx`) first, then read the rule.
+
+Then read this repo's own styling rules: a styleguide under `docs/`, a `CONTRIBUTING.md`, lint
+config for CSS, and the parts of `AGENTS.md` outside the generated block. Where they conflict with
+this task, such as shared app classes listed as the building blocks to use, or a ban on `rem` in own
+CSS while step 1 sets a rem-based `--spacing`, stop and ask the user which one wins. Do not override
+the repo's rules silently, and do not edit them without that answer.
+
+## Find the call sites
+
+The components with a stylesheet, whatever their file suffix:
+
+```bash
+grep -rlE 'styleUrls?:' apps libs --include='*.ts'
+```
+
+The stylesheets those components reference. This leaves out the global stylesheets (the `styles`
+of a build target, and the files they `@import`) and generated theme files:
+
+```bash
+grep -rlE 'styleUrls?:' apps libs --include='*.ts' | while read -r file; do
+  grep -oE "['\"][^'\"]+\.(css|scss|sass|less)['\"]" "$file" | tr -d "'\"" |
+    while read -r sheet; do realpath -m --relative-to=. "$(dirname "$file")/$sheet"; done
+done | sort -u
+```
+
+BEM classes in templates, class bindings, `routerLinkActive` and host classes, app rules in
+`@layer components` (global stylesheets included), and the components that do not set
+`ViewEncapsulation.None` yet:
+
+```bash
+grep -rnE 'class="[^"]*\b[a-z0-9-]+__[a-z0-9-]+' apps libs --include='*.html' --include='*.ts'
+grep -rnE '\[class\.[a-z0-9_-]+\]|\[ngClass\]|\[class\]=' apps libs --include='*.html' --include='*.ts'
+grep -rnE 'routerLinkActive="[^"]+"' apps libs --include='*.html' --include='*.ts'
+grep -rnE "(host: \{|'\[class(\.[a-z0-9_-]+)?\]'|class: ')" apps libs --include='*.ts'
+grep -rlE '@layer components' apps libs --include='*.css' --include='*.scss'
+grep -rlE '@Component\(' apps libs --include='*.ts' | xargs grep -LE 'ViewEncapsulation\.None'
+```
+
+## What to change
+
+1. Check the root font size and the spacing scale first. On the 10px root the SDK needs, Tailwind's
+   rem scales are 1.6× smaller than their nominal size. Set `--spacing: 0.4rem` in the app's
+   `@theme` so that `p-4` is 16px again, and redefine any other rem scale the templates use
+   (`--text-*`, `--container-*`, `--radius-*`). This rescales the utilities the app already uses,
+   so check the views that have them.
+2. Replace each class that sets layout, spacing, sizing or typography with the utilities in the
+   template, and delete the rule from the stylesheet.
+3. Replace a hardcoded colour with a theme utility or a `var(--et-…)` token. The surface utilities
+   are `bg-et-surface-bg`, `text-et-surface`, `text-et-surface-muted`, `text-et-surface-subtle` and
+   `border-et-surface-border`. The colour utilities resolve against the nearest `[etProvideColor]`
+   scope: `bg-et-theme`, `text-et-on-theme` for text on that fill, and `text-et-theme-ink` or
+   `border-et-theme-ink` on a transparent background. Each has `-hover`, `-focus`, `-active` and
+   `-disabled` variants. A utility with a theme name in it (`bg-et-<name>`) pins one theme and
+   ignores the scope, so prefer the scoped ones.
+4. Keep what utilities cannot express (a keyframe, a complex selector) as CSS, unlayered or in
+   `@layer utilities`. Move any app rule out of `@layer components`: SDK styles land in that layer
+   after yours, so the app rule loses. This applies to the `@layer components` blocks in the global
+   stylesheet too: shared app classes there are app components, and move to utilities in the
+   templates that use them.
+5. Find the app's unlayered overrides of SDK classes (`.et-button`, `.et-badge`, …) in the global
+   stylesheet and in component sheets:
+
+   ```bash
+   grep -rnE '(^|[ ,>+~])\.et-[a-z0-9-]+' apps libs --include='*.css' --include='*.scss'
+   ```
+
+   Unlayered CSS beats every layer, so such a rule beats the utilities you add on the same element.
+   Replace it with the component's `--et-*` tokens or a utility on the element. A rule that has to
+   stay goes into `@layer utilities`, like the CSS in step 4: it then still beats the SDK's
+   `@layer components`, and no longer beats every utility.
+
+6. To restyle an SDK component, set its `--et-*` tokens first, then a utility on the element.
+7. Delete a stylesheet that ends up empty, and its `styleUrl`.
+8. Keep `encapsulation: ViewEncapsulation.None` on every app component, and add it where it is
+   missing: the `require-view-encapsulation-none` lint rule requires it. The CSS that is left is then
+   global, so give the component a host class (`host: { class: 'app-…' }`) and scope every selector
+   under it, the way the SDK scopes its CSS under `et-` classes.
+
+## Watch the initial bundle
+
+A component stylesheet ships with its component, so a lazy route's CSS loads with that route. The
+utilities go into the global stylesheet, which is part of the initial bundle. Moving many lazy
+components to utilities can push the initial bundle over its budget. Check the build's initial
+total against the budget after each batch. Keep the stylesheet of a lazy component whose CSS is
+large and used nowhere else, and report the trade-off rather than raising the budget on your own.
+
+## Leave these alone
+
+- A library that ships its own CSS to other repos. The rule is about app components.
+- In the global stylesheet: the Tailwind and theme imports, `@theme`, `html { font-size: 62.5%; }`
+  and the `@layer base` rules for elements (`html`, `body`, `a`).
+- Generated theme files, such as the surface and colour themes `@ethlete/core` writes.
+- CSS that no utility expresses.
+
+## When you are done
+
+Run the type check, the lint task and the build of every project you changed, and look at each
+changed view in the browser: a missed class renders unstyled, not as an error.
+
+The page the `Docs` line at the top of this file links (`/components/setup` on the SDK docs site)
+summarises the rule under "Styles". Overriding SDK styles is under "Overriding component styles" on
+`/components/`, on the same site.

package/migrations/list-state-query-form.md

@@ -0,0 +1,103 @@
+# Move URL-bound list state to `defineQueryForm`
+
+The earlier query guidance did not name `defineQueryForm`, so list pages wired their filters,
+search, sort and paging to the URL by hand: `injectQueryParams()` to read, `router.navigate` to write,
+and a draft signal plus an effect in between. `defineQueryForm` does the URL sync, the debounce, the
+defaults and the page reset, and the `ethlete-query` skill now says to use it for every filtered,
+searched, sorted or paged list.
+
+## Before you start
+
+`et update` regenerates the skills when it moves `@ethlete/agent-rules`. If
+`.agents/skills/ethlete-query/SKILL.md` does not mention `defineQueryForm`, run
+`ethlete-agents sync` with this repo's package manager (`yarn`, `pnpm exec` or `npx`) first. Read
+the skill, then the guide the `Docs` line at the top of this file links (`/query/query-forms` on the
+SDK docs site).
+
+## Find the call sites
+
+The reads, with comment lines filtered out:
+
+```bash
+grep -rnE 'injectQueryParams?\(|inject\(ActivatedRoute\)|:\s*ActivatedRoute\b|queryParamMap|snapshot\.queryParams|\.queryParams\.(pipe|subscribe)\(' \
+  apps libs --include='*.ts' | grep -vE '^[^:]+:[0-9]+:\s*(//|/?\*)'
+```
+
+The writes. A navigation spreads its options over several lines, so this prints the `queryParams`
+line up to three lines below each call:
+
+```bash
+grep -rnE -A3 '\.navigate(ByUrl)?\(|createUrlTree\(|\.(go|replaceState|pushState)\(' apps libs --include='*.ts' \
+  | grep -E '\bqueryParams(Handling)?\b|\?[a-zA-Z_-]+='
+```
+
+A call site is in scope when the params it reads or writes are the arguments of a list query:
+search text, filters, sort, page or page size.
+
+## What to change
+
+1. Declare one `defineQueryForm({ fields })` per list, with a field creator per param
+   (`searchQueryField`, `sortQueryField`, `queryField<number>({ defaultValue: 1 })` for the page, and
+   the typed array and date creators for filters), and call `.observe()` on it. Give a `queryField`
+   a `defaultValue` wherever the old code had one: the field is then typed without `null`, so reads
+   need no `?? DEFAULT`. A `queryField<T>()` without a default reads the URL as a string, so any
+   other `T` needs a `queryParamToValue` such as `transformToNumber`. A date field bound to an
+   `et-date-input`, `et-date-time-input` or `et-time-input` needs `dateQueryField({ as: 'string' })`,
+   because those controls hold a string.
+2. Give the page field `isResetBy` for the fields that must send the list back to page 1.
+3. Feed the query from `withArgs(() => … this.qf.value() …)`.
+4. Bind each form control with `[formField]="qf.fields.<name>"`. `et-pagination` and
+   `et-page-size-select` are not form controls; bind their two-way `model` to the field's value
+   signal instead: `[(page)]="qf.fields.page().value"`, `[(pageSize)]="qf.fields.limit().value"`.
+   A table sort needs a mapping both ways; see "Sort from a table" below.
+5. Delete the hand-written reads, writes, draft signals and effects the form replaces.
+6. Keep the param names the URL already uses, so saved links keep working. Each field is one param,
+   named by its key. Use `queryParamPrefix` when two lists share a route.
+7. If the old code navigated with `replaceUrl: true`, so filtering did not add history entries, pass
+   `observe({ replaceUrl: true })`. Without it every commit pushes an entry.
+
+### Sort and direction in two params
+
+`sortQueryField()` writes one param as `active:direction` (`?sort=name:asc`). No field maps two
+params, so a URL with separate params such as `?sort=name&dir=asc` needs a decision:
+
+- **Keep the URL** (the default). Declare two fields, `sort: queryField<SortKey>(…)` and
+  `dir: queryField<'asc' | 'desc'>(…)`, each with a `defaultValue` and a `queryParamToValue` that
+  maps an unknown value to the default. Give `dir` `skipInFilterCount: true`: only `sort` is on the
+  list of names `activeFilterCount` ignores. Put both in the page field's `isResetBy`.
+- **Move to `sortQueryField()`** when you are free to change the URL. Old links with a `dir` param
+  lose their direction. Say so in the commit message.
+
+### Sort from a table
+
+`et-table` holds its sort as `TableSort[]` (`{ key, direction }`); `sortQueryField()` holds one
+`Sort` (`{ active, direction }`). Nothing converts between them and the table does not write the
+URL, so map both ways in the component:
+
+```ts
+tableSort = computed<TableSort[]>(() => {
+  const sort = this.qf.value().sort;
+
+  return sort?.direction ? [{ key: sort.active, direction: sort.direction }] : [];
+});
+
+onSortChange([first]: TableSort[]) {
+  this.qf.patchValue({ sort: first ? { active: first.key, direction: first.direction } : null });
+}
+```
+
+Bind `[sort]="tableSort()"` and `(sortChange)="onSortChange($event)"`.
+
+## Leave these alone
+
+- A param that is not list state, such as a `returnUrl`, a tab id or an opened-detail id. Reading it
+  with `injectQueryParam` is correct.
+- A one-off `router.navigate` to another page.
+
+## When you are done
+
+No list may read and write its params by hand any more. Run the type check, the lint task and the tests
+of every project you changed, and check in the browser that reload, back and forward restore the list.
+
+The guide in the `Docs` line at the top of this file has every field creator, the URL rules and
+filter overlays.

package/migrations/nx-layout.md

@@ -0,0 +1,23 @@
+# Compare the workspace with the Nx layout rule
+
+`@ethlete/agent-rules` now ships an `nx-layout` rule for Nx workspaces: thin apps, feature code in
+`libs/domain/<app>/<feature>`, shared `queries`, `types`, `uikit`, `theme` and `env` libs, aliases that
+mirror the path, and one `scope:*` tag per project. New code follows it.
+
+This is a recommendation, not a rewrite. Moving projects changes import paths, project names, tags
+and CI caches across the whole repo, and the rule itself says not to restructure an existing
+workspace unless the team asks for it.
+
+## What to decide
+
+1. Read the rule (in `AGENTS.md`, or under `.claude/rules/ethlete/`). If it is missing, run
+   `ethlete-agents sync` with this repo's package manager (`yarn`, `pnpm exec` or `npx`).
+2. List where the workspace deviates: feature code inside `apps/`, queries or themes inside an app,
+   `feature/ui/data-access/util` folders, aliases that do not mirror the path, missing `scope:*` tags.
+3. Decide per deviation: move it now, move it when that area is next touched, or keep it.
+4. Keep what you decided where an agent reads it, so it stops flagging it: in `AGENTS.md` above the
+   `<!-- ethlete:agent-rules:start -->` line or below `<!-- ethlete:agent-rules:end -->`, or in the
+   repo's `CONTEXT.md` or an ADR. Never between the two markers: `ethlete-agents sync` rewrites that
+   block and drops the edit. If `AGENTS.md` holds nothing but the block, add the decisions above it.
+
+An agent may prepare the list in step 2. It must not move a project without that decision.

package/migrations/sdk-components-over-hand-built-ui.md

@@ -0,0 +1,69 @@
+# Use the SDK component where one exists
+
+The earlier `ethlete-sdk-docs` skill listed only part of the component domains, and named some by a
+word an agent would not search for. So apps built their own bar charts, avatars and progress bars,
+although `@ethlete/components` ships all three. The skill now lists every domain and maps the common
+needs to them.
+
+## Before you start
+
+`et update` regenerates the skills when it moves `@ethlete/agent-rules`. If
+`.agents/skills/ethlete-sdk-docs/SKILL.md` has no "Check this list before you build any UI by hand"
+table, run `ethlete-agents sync` with this repo's package manager (`yarn`, `pnpm exec` or `npx`) first. Read that table: it covers more than the three below.
+
+## Find the call sites
+
+```bash
+grep -rnE 'chart|bar-?graph|<rect ' apps libs --include='*.html' --include='*.ts'
+grep -rnE 'avatar|initials' apps libs --include='*.html' --include='*.ts' --include='*.css'
+grep -rnE '\b[A-Z0-9_]*(INITIALS|AVATAR|ABBR)[A-Z0-9_]*\b' apps libs --include='*.ts'
+grep -rnE '\.(charAt\(0\)|at\(0\)|\[0\])[^;]*\.toUpperCase\(\)|split\(.*\)\.map\(.*\[0\]' apps libs --include='*.ts' --include='*.html'
+grep -rnE 'progress' apps libs --include='*.html' --include='*.ts' --include='*.css'
+```
+
+The third and fourth catch initials built by hand: a constant map from a name or key to its letters, and
+first letters taken and upper-cased. Skip every hit that already uses an `et-` element.
+
+## The replacement for each
+
+| Hand-built                                | SDK component                  | Guide                |
+| ----------------------------------------- | ------------------------------ | -------------------- |
+| Bar or stacked bar chart, a series legend | `et-bar-chart`                 | `/components/chart`  |
+| Initials or a user picture in a circle    | `et-avatar`, `et-avatar-group` | `/components/avatar` |
+| Progress bar                              | `et-progress-bar`              | `/components/loader` |
+
+## What to change
+
+1. Read the guide of the component, and map the data the hand-built one received onto its inputs.
+2. Replace the markup, and delete the component, the CSS and the helpers only it used.
+3. Style it through its `--et-*` tokens, not by overriding its internals.
+
+## When the SDK component cannot cover it
+
+Check every feature of the hand-built one against the component's inputs, slots and `--et-*`
+tokens before you replace it. Known gaps:
+
+- `et-bar-chart` renders every category label and only truncates it, so a long axis cannot be
+  thinned. It has no slot for a title, a note or an empty state.
+- `et-avatar` derives initials from `name` only, so explicit initials (a constant map, a team
+  abbreviation) cannot be passed. Its fill and text colour come from a colour theme only; there is
+  no `--et-avatar-*` colour token.
+
+When a feature has no counterpart, keep the hand-built one and record the gap for the user: which
+view, which feature, which component. Do not drop the feature to make the component fit, and do not
+register or invent a colour theme to reach a colour the component has no token for.
+
+## Leave these alone
+
+- A visual the SDK component cannot express, such as a chart type it does not have. Report it
+  instead of forcing a fit.
+- A component another repo imports from this one: replacing it is a change to that repo's contract,
+  so report it.
+
+## When you are done
+
+Run the type check, the lint task and the tests of every project you changed, and compare each
+replaced view in the browser with how it looked before.
+
+The page the `Docs` line at the top of this file links (`/components/` on the SDK docs site) lists
+every component domain.

package/migrations/search-query-field.md

@@ -0,0 +1,45 @@
+# Replace a hand-debounced search with `searchQueryField`
+
+The earlier query guidance said there was no built-in debounce and to debounce at the input. So a
+search box that feeds a query was debounced by hand: `debounceTime` on a stream, a `setTimeout`, or a
+debounced copy of the input signal. `searchQueryField()` debounces by itself (300ms), and applies a
+cleared input at once.
+
+## Before you start
+
+`et update` regenerates the skills when it moves `@ethlete/agent-rules`. If
+`.agents/skills/ethlete-query/SKILL.md` does not mention `searchQueryField`, run
+`ethlete-agents sync` with this repo's package manager (`yarn`, `pnpm exec` or `npx`) first.
+
+## Find the call sites
+
+```bash
+grep -rnE 'debounceTime\(|debounce\(' apps libs --include='*.ts'
+grep -rnE 'setTimeout\(' apps libs --include='*.ts'
+```
+
+A call site is in scope when the debounced value ends up in the args of a query.
+
+## What to change
+
+1. Add a `search: searchQueryField()` field to the list's `defineQueryForm`, or declare a form with
+   that one field.
+2. Call `.observe()` on it. Pass `{ writeToQueryParams: false }` when the search must not reach the
+   URL, for example a search inside a dialog.
+3. Read `this.qf.value().search` in `withArgs`, and bind the input with `[formField]="qf.fields.search"`.
+4. Delete the debounce, the subject or timer, and the intermediate signal.
+5. Pass `debounce` to the field when the old delay was deliberately different from 300ms.
+
+If the `list-state-query-form` task already moved this list to a query form, the search is done.
+
+## Leave these alone
+
+- A debounce whose value never reaches a query: resize and scroll handlers, autosave, analytics.
+- An SDK control that takes a search input of its own.
+
+## When you are done
+
+Run the type check, the lint task and the tests of every project you changed.
+
+The guide the `Docs` line at the top of this file links (`/query/query-forms` on the SDK docs site)
+has the field creators and their options.