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

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,16 +11,30 @@ 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.
 
+**Every write waits for the user's approval in the app.** `create`, `log`, `edit`, `standins
+--remove | --rename | --merge | --split --force`, `sync --write`, `worklog --delete` and `resync` answer at
+once with an approval id and write nothing yet. The user approves or rejects the request in
+Timetrack; `approval <id>` reads the outcome:
+
+```bash
+{%packageRunner%} ethlete-agents timetrack approval <id>          # queued, approved (with the result), rejected or expired
+```
+
+Tell the user a request waits in Timetrack, then read `approval` once they say they decided -
+do not poll in a loop. A request that is still waiting at the end of the day it was asked on
+expires; ask again rather than assuming it landed. Set `TIMETRACK_CLIENT` to name yourself in the
+queue (Claude Code is named without it).
+
 **Never ask the user for a Jira token, and never write one into a file.** If a command reports
 that the app is not running, say so and ask the user to start it. That is the whole fix -
 there is no per-repo fallback, by design: a secret copied into every checkout is a secret
@@ -28,23 +42,29 @@ nobody can rotate.
 
 ## What each command is for
 
-| Command                                | Use it when                                                               |
-| -------------------------------------- | ------------------------------------------------------------------------- |
-| `status`                               | Before anything else, when a Jira command failed and you need the cause   |
-| `instance`                             | A setup step needs the instance's levels or its branch-subject field      |
-| `issue <KEY>`                          | The user names a key and you need its summary, type or parent             |
-| `search [text]`                        | The user describes work but names no key                                  |
-| `project [path]`                       | You need the project a repository files into                              |
-| `create --summary "…"`                 | The work has no ticket and the user asked for one                         |
-| `log --issue <KEY> --minutes <n>`      | The user asks to record time that nothing observed                        |
-| `day [YYYY-MM-DD]`                     | You need the evidence a day holds, not a screenshot of it                 |
-| `rows [YYYY-MM-DD]`                    | You need the rows the day drew, and the ids an edit names them by         |
-| `edit <row-id> …`                      | The user asks you to correct one row of a day                             |
-| `rules`                                | You need to know why a band was named, or why it was not                  |
-| `standins`                             | You need to know which work still waits for a ticket, and for how long    |
-| `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    |
+| Command                                    | Use it when                                                                 |
+| ------------------------------------------ | --------------------------------------------------------------------------- |
+| `status`                                   | Before anything else, when a Jira command failed and you need the cause     |
+| `instance`                                 | A setup step needs the instance's levels or its branch-subject field        |
+| `issue <KEY>`                              | The user names a key and you need its summary, type or parent               |
+| `search [text]`                            | The user describes work but names no key                                    |
+| `project [path]`                           | You need the project a repository files into                                |
+| `create --summary "…"`                     | The work has no ticket and the user asked for one                           |
+| `log --issue <KEY> --minutes <n>`          | The user asks to record time that nothing observed                          |
+| `day [YYYY-MM-DD]`                         | You need the evidence a day holds, not a screenshot of it                   |
+| `rows [YYYY-MM-DD]`                        | You need the rows the day drew, and the ids an edit names them by           |
+| `edit <row-id> …`                          | The user asks you to correct one row of a day                               |
+| `rules`                                    | You need to know why a band was named, or why it was not                    |
+| `standins`                                 | You need to know which work still waits for a ticket, and for how long      |
+| `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   |
+| `standins --merge <id> --into <id>`        | Two placeholders are one piece of work, and the user asked you to join them |
+| `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       |
+| `sync <YYYY-MM-DD>`                        | The user asks what a Tempo sync of a day would write, or asks to sync it    |
+| `worklog --delete <id> --day <YYYY-MM-DD>` | The user asked you to delete one of their own Tempo worklogs                |
+| `approval <id>`                            | A write you queued: whether the user approved it, and what it answered      |
 
 `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 +74,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,22 +92,23 @@ 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
-changed. `applied` says how many edits found their row: a running day is re-cut on every collector
-tick, so read `rows` again rather than reusing an id from minutes ago.
+`rows` moves the app's own review to that day, so the user sees what you read. An edit is queued
+like every write; once approved, its result's `applied` says how many edits found their row. A
+running day is re-cut on every collector tick, so read `rows` again rather than reusing an id from
+minutes ago.
 
 An edit may correct a row's times, its name, its note and whether it syncs. It may not split, merge
 or delete one - restructuring a day is the user's own decision, made on the screen.
@@ -99,8 +120,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 +134,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 +171,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 +184,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      # queue it for approval
 ```
 
 Without `--force` it prints every directory the commits name, with its commit count and its days,
@@ -191,7 +212,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 +232,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,21 +241,105 @@ 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` as `HH:MM`, `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.
+
+## Syncing a day to Tempo
+
+`sync` plans a day exactly as the app's Sync page does, and writes nothing:
+
+```bash
+{%packageRunner%} ethlete-agents timetrack sync 2026-09-07
+{%packageRunner%} ethlete-agents timetrack sync 2026-09-07 --json
+```
+
+It prints every create, update and delete with its issue, local time, minutes, description and
+reason; the rows it holds back (Tempo refuses an empty description); how many are unchanged or still
+awaiting review; keys Jira does not know; and the foreign worklogs it never touches. The first line
+carries a short **plan hash** over the write set.
+
+Writing is a Tempo write, so it follows one rule without exception: **show the user the rows, and
+write only after they confirmed those rows in this conversation.** Then pass the hash the read
+printed:
+
+```bash
+{%packageRunner%} ethlete-agents timetrack sync 2026-09-07 --write --plan 1a2b3c4d
+```
+
+The write is queued, and the user approves it in the app as well - "Approve all" never includes
+it. On approval the app plans the day again and refuses, writing nothing, when the hash differs -
+the day changed since the user saw it, so read it again and ask again. `--write` without `--plan`
+is refused at once. Once approved, `approval <id>` prints each row as `written`, `blocked`,
+`skipped` or `failed`, with the worklog id or the error, and exits non-zero while a row did not
+land. Never re-run the write to retry: a plan read
+straight after a write can miss what Tempo just took and log it twice. The Sync page shows the run
+and retries from its own plan. A "written, but not recorded" line means Tempo holds worklogs the
+app no longer owns; tell the user to delete them in Tempo before this day is written again.
+
+Both reads and writes move the app's Day screen to that day, as `rows` and `edit` do.
+
+## Deleting a Tempo worklog
+
+`worklog --delete` deletes one of the user's own Tempo worklogs. Both flags are required; read the
+id and its day off `worklogs --json`:
+
+```bash
+{%packageRunner%} ethlete-agents timetrack worklog --delete 98765 --day 2026-09-07
+```
+
+It is a Tempo write, so the same rule holds: **name the worklog to the user, and delete only after
+they confirmed that one in this conversation.** The app refuses, deleting nothing, an id that is not
+among the account's own worklogs on that day. The delete is queued for the user's approval like
+`sync --write`; once approved, `approval <id>` answers what went, and the app drops its own record
+of the worklog, so the next `sync` of the day plans from what Tempo holds.
+
 ## Writes
 
-Two commands write, so both need the user to have asked for them in this conversation:
+Four commands write to Jira or Tempo, so all need the user to have asked for them in this
+conversation - `sync --write` and `worklog --delete` are described above. Each is queued for the
+user's approval in the app:
 
 ```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
+- **`create`** files the issue, once approved, with the instance's own ticket settings - its type, its parent
   rule and its subject field all come from the app, so the ticket is shaped like every other.
   `--project` is needed unless the app holds exactly one picked project.
 - **`log`** adds a row to the day in Timetrack. It is **not** a Tempo entry: the user reviews
   the day and syncs it, which is what keeps an agent's row from double-booking against the
-  hours the day already observed. `--at <date>` places it; without one it starts now.
+  hours the day already observed. `--at` places it - an ISO instant, or a local `YYYY-MM-DD` or `HH:MM` (today); without one it starts now.
 
 ## What the app decides, not you
 

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.