@ethlete/agent-rules 0.1.0-next.3 → 0.1.0-next.30

package/content/skills/styleguide/storybook-structure.md

@@ -0,0 +1,25 @@
+# Storybook structure
+
+Read this file when placing a `*.stories.ts` file or code used only to render stories.
+
+- Keep the `*.stories.ts` file beside the component it documents.
+- Put private host components, dummy data, and story-only helpers in `storybook/`.
+- Never export Storybook-only code from the component's public barrel.
+- A private `storybook/index.ts` may simplify imports into the adjacent story, but no
+  production source may import it.
+
+```plaintext
+settings-form/
+├── storybook/
+│   ├── settings-form-storybook.component.ts
+│   ├── settings-form-storybook.component.html
+│   ├── settings-form-dummy-data.ts
+│   └── index.ts
+├── settings-form.component.ts
+├── settings-form.component.html
+├── settings-form.component.stories.ts
+└── index.ts
+```
+
+The story file stays at the component root; only its private support code goes into
+`storybook/`.

package/content/skills/theming/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: theming
-description: The two runtime theming systems in @ethlete/core - surface theming (elevation-aware neutrals) and color theming (semantic accent palettes) - how to register them in an app and how components must consume them. Read BEFORE writing or reviewing CSS that involves any color, background, border, or interaction state, and when wiring theme context across overlay/portal boundaries.
+description: The two runtime theming systems in @ethlete/core - surface theming (elevation-aware neutrals) and color theming (semantic accent palettes). Read BEFORE writing or reviewing CSS involving color, background, border, or interaction state, and when wiring theme context across overlay/portal boundaries.
 kind: skill
 scope: consumer
 requires: ['@ethlete/core']
@@ -37,16 +37,16 @@ The generated CSS defines the raw vars on `.et-surface--<name>` / `.et-color--<n
 classes (plus `:root` defaults) and derives the public tokens below on `:root` **and**
 every scope class - so the tokens are always resolvable and components just read them.
 
-**Theme names are yours.** `brand`, `danger`, `neutral`, `dark-elevated` are only
-examples. Never hardcode a theme-name union in a component type, a doc or an example.
-The portable handle is the theme **`type`**: `injectErrorTheme()` finds whichever theme
-the app registered with `type: 'error'`.
+**Theme names are yours.** Never hardcode them as an SDK-defined union or reusable API
+contract. App-specific docs may name their own themes when they label them as app values.
+The portable handle is the theme **`type`**: `injectSemanticColorTheme('error')` finds
+whichever theme the app registered with `type: 'error'`.
 
 ## Tokens components may consume
 
 Use these **derived** tokens - never the raw `--et-surface-background` /
-`--et-color-primary` channel triplets, and never a hardcoded color (a static fallback
-_after_ the token is fine).
+`--et-color-primary` channel triplets. Never use a hardcoded color as the primary value.
+A static fallback inside `var(--token, <fallback>)` is permitted, but not required.
 
 Surface (each exists as `-solid` = usable color, `-rgb` = `R G B` channels):
 
@@ -61,22 +61,26 @@ Surface (each exists as `-solid` = usable color, `-rgb` = `R G B` channels):
 
 Color (from the nearest `[etProvideColor]` scope):
 
-| Token                            | Use for                                                                                                                                |
-| -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
-| `--et-theme-color-primary`       | filled backgrounds; **opacity-aware** - set `--et-theme-color-primary-opacity: 0.16` etc. per state to tint without changing the color |
-| `--et-theme-color-primary-solid` | accents at full strength: focus borders, selected marks, spinners                                                                      |
-| `--et-theme-color-on-primary`    | text/icons on a primary-filled background                                                                                              |
-| `--et-theme-color-ink-solid`     | primary-tinted text/border on transparent/tonal fills                                                                                  |
+| Token                            | Use for                                                                                                                                                                                                                                                                                                                                                             |
+| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--et-theme-color-primary`       | filled backgrounds on an element you do **not** tint. To tint per state, set `--et-theme-color-primary-opacity: 0.16` and compose the color yourself: `rgb(var(--et-theme-color-primary-rgb) / var(--et-theme-color-primary-opacity))`. The alias is substituted at the `et-color--*` scope, so an inherited value carries the scope's opacity, never the element's |
+| `--et-theme-color-primary-solid` | accents at full strength: focus borders, selected marks, spinners                                                                                                                                                                                                                                                                                                   |
+| `--et-theme-color-on-primary`    | text/icons on a primary-filled background                                                                                                                                                                                                                                                                                                                           |
+| `--et-theme-color-ink-solid`     | primary-tinted text/border on transparent/tonal fills                                                                                                                                                                                                                                                                                                               |
 
 Interaction-state variants (`--et-surface-interaction-{hover,focus,active,disabled}-solid`)
 resolve automatically per CSS state when the element has `[etSurfaceInteractive]`;
 similarly `[etColorInteractive]` re-resolves the color tokens per state. Put either on
 the interactive element itself, never on a wrapper.
 
+**Never use `hover:bg-et-surface-interaction-hover` for a hover row.** The token is a
+full-strength neutral tint, so in dark mode it gives a light row with near-white text. Use
+`[etSurfaceInteractive]` on the row for hover feedback.
+
 ## Providing context
 
-- `[etProvideSurface]="'dark-elevated'"` / `[etAutoSurface]` (auto-picks the next
-  elevation) set the surface scope; `[etProvideColor]="'brand'"` sets the color scope.
+- `[etProvideSurface]="surfaceThemeName"` / `[etAutoSurface]` (auto-picks the next
+  elevation) set the surface scope; `[etProvideColor]="colorThemeName"` sets the color scope.
   A component that owns a themed region usually adds `ProvideColorDirective` /
   `ProvideSurfaceDirective` as `hostDirectives`.
 - **Detached overlay panes (menu, dialog, tooltip…) do not inherit DOM context.**
@@ -85,10 +89,22 @@ the interactive element itself, never on a wrapper.
   color and `resolveSurfaceByElevation(themes, type, elevation + 1)` for the surface.
 - **Semantic colors come through DI, not CSS.** There is no global "error color"
   variable - error/warning/success are just color themes. To render something in the
-  error color, `injectErrorTheme()` (it throws if the app registered no `type: 'error'`
-  theme) and either bind it (`[etProvideColor]="errorColorTheme"`) or force it
-  programmatically (`provideColor.forceColor(theme)` / `clearForcedColor()`). Inside
-  that scope, `--et-theme-color-primary-*` _is_ the error color.
+  error color, `injectSemanticColorTheme('error')` (reading it throws if the app
+  registered no `type: 'error'` theme) and either bind it
+  (`[etProvideColor]="errorColorTheme()"`) or force it programmatically
+  (`provideColor.forceColor(theme)` / `clearForcedColor()`). Inside that scope,
+  `--et-theme-color-primary-*` _is_ the error color.
+- **A surface swaps a chosen accent; it never picks one.** The chosen accent is the
+  nearest `[etProvideColor]`, else the `isDefault` theme, or for
+  `injectSemanticColorTheme(type)` the theme of that `type`. The nearest surface's
+  `SurfaceTheme.colorThemeVariants` (e.g. `{ brand: 'brand-on-light', success: 'success-on-light' }`,
+  variants registered without a `type`) swaps it; an accent without an entry stays the
+  same on every surface. With no surface above, the root surface swaps, and
+  `provideColorScheme()` paints its swap of the default accent on `<html>`. A neutral that follows the surface is `color="surface"`
+  (`interactionColor`), not a variant. `colorTheme` and `semanticColorThemes` are
+  deprecated. Never add per-surface logic to a color theme or new CSS vars for it.
+  `injectErrorTheme()`, `injectWarningTheme()` and `injectSuccessTheme()` are
+  deprecated: they ignore the surface.
 
 ## Pitfalls
 
@@ -96,15 +112,21 @@ the interactive element itself, never on a wrapper.
   declared via `@property` can never default to a theme token. If the default should
   come from the theme, don't declare an `@property` - consume the theme token directly
   (optionally behind a `--_et-*` indirection var).
+- `@property` `initial-value` also cannot use a **font-relative or container unit**
+  (`em`, `rem`, `ex`, `ch`, `lh`, `cap`, `ic`, `cq*`). The value must be computationally
+  independent, so the browser drops the whole rule and leaves the token unregistered -
+  with no error. Percentages and viewport units (`vh`, `vw`, `dvh`) are fine. When the
+  default has to be relative, use `syntax: '*'` with no `initial-value` and put the
+  default in a fallback at each use site: `var(--et-skeleton-size, 1em)`.
 - `--et-theme-color-primary-*` always resolves to the **nearest color scope**. A
   hardcoded semantic color in CSS can't be replaced by it unless the right theme is
   provided on that element.
-- Keep a static fallback (`var(--et-surface-border-solid, rgb(255 255 255 / 0.1))`) so
-  components degrade in theme-less setups. `injectErrorTheme()` is the exception: it is
-  a hard requirement wherever it is used.
-- **Cascade layers, not `:where()`, are what let a Tailwind utility override component
-  CSS.** Wrap every component CSS file in `@layer components { … }`; `:where()` only
-  flattens a component's own modifiers to single-class weight. See the `styling` rule.
-
-Styling a **story** file rather than a component? The colour rule is the same, but the
-Tailwind side has its own traps - {%skill:story-styling%}.
+- A static fallback (`var(--et-surface-border-solid, rgb(255 255 255 / 0.1))`) is
+  permitted for theme-less setups, but themes make it unnecessary. `injectSemanticColorTheme()`
+  is a hard requirement wherever it is read.
+- **Cascade layers, not `:where()`, decide who wins against SDK component CSS.** SDK
+  styles live in `@layer components`, so a utility or unlayered app CSS overrides them.
+  An app rule inside `@layer components` loses. See the `app-styling` rule.
+
+Styling a **story** file rather than a component? The colour rule is the same. Check the
+repository's Storybook guidance before assuming a Tailwind utility exists.

package/content/skills/timetrack/SKILL.md

@@ -0,0 +1,397 @@
+---
+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 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
+---
+
+# Reaching Jira through Timetrack
+
+**No repository holds a Jira token.** The Timetrack desktop app holds one set of credentials
+in this machine's keychain, and every repository asks it:
+
+```bash
+{%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 | --resolve | --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
+{%packageRunner%} ethlete-agents timetrack approvals              # every write that waits now: id, asker, op, asked at, what it writes
+{%packageRunner%} ethlete-agents timetrack approval <id> --reject # reject one that waits, as the app's Reject button does
+```
+
+A reject answers at once and writes nothing to Jira or Tempo; an item that no longer waits is
+refused and stays as it is. Reject only what the user asked you to, or a write you queued by
+mistake. **There is no approve command and never will be: only the user approves, in the app.**
+
+`ask` does what the app's "Ask auto mode again" does, on any day, without moving the day on
+screen. It answers at once with what it queued; the model runs on the user's machine, and its new
+answer replaces the stored one. It writes nothing to Jira or Tempo itself: a ticket or a name the
+answer proposes waits for the user's approval as auto mode's own does.
+
+```bash
+{%packageRunner%} ethlete-agents timetrack ask --stand-in <id> [--day YYYY-MM-DD]       # an open stand-in, ids from `standins`
+{%packageRunner%} ethlete-agents timetrack ask --context <context-id> [--day YYYY-MM-DD] # an unnamed band, ids from `rows`
+```
+
+A subject the app does not offer the press on is refused: an unknown or resolved stand-in, one
+the day holds no time of, a context a rule names or the user named by hand.
+
+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
+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   |
+| `standins --merge <id> --into <id>`        | Two placeholders are one piece of work, and the user asked you to join them |
+| `standins --resolve <id> --issue <KEY>`    | The user named the issue a placeholder is, or the one a resolved one is now |
+| `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      |
+| `approvals`                                | You need what waits in the queue, from every caller                         |
+| `approval <id> --reject`                   | The user asked you to drop a waiting write, or you queued one by mistake    |
+| `ask --stand-in <id>` / `--context <id>`   | The user asks auto mode to look at a stand-in or an unnamed band again      |
+
+`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.
+
+## Reading a day
+
+The app's store is encrypted, so no shell reads a day off disk. `day` is the only way in:
+
+```bash
+{%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
+`--out`, then read that file from a test or a script. Without `--out` the command reports
+only the counts, which is what tells you whether a day holds the source you are looking for.
+
+`--out` writes a new file, readable by its owner alone. A destination that already exists is
+refused until you pass `--overwrite`, and a symlink is never written through. The file holds the
+day as it was observed - window titles, paths and messages - so delete it when you are done.
+
+`transcript` prints what the app transcribed of the user's own microphone during the day's calls,
+one 30-second chunk per line. It exists only where the user turned call transcription on, and the
+app deletes a chunk after seven days. Read it only when the task needs what was said.
+
+```bash
+npx ethlete-agents timetrack transcript [YYYY-MM-DD]
+```
+
+## Reading and correcting the rows a day drew
+
+`day` answers what the collectors saw. `rows` answers what the app made of it - the bands on the
+timeline, with the id every edit names a row by, the day's totals and its warnings.
+
+```bash
+{%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
+{%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
+{%packageRunner%} ethlete-agents timetrack edit '<row-id>' --issue ABC-2
+{%packageRunner%} ethlete-agents timetrack edit '<row-id>' --state rejected
+```
+
+`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.
+
+## Why a band carries the name it does
+
+`rules` reads the settings that name a day's work - the attribution rules, the project links,
+the background projects and the applications the user has ruled in or out. It holds no host, no
+account and no token, so it is safe to quote back to the user.
+
+```bash
+{%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
+carries no issue key, and a project in `backgroundProjects` keeps only the minutes no other
+band claims.
+
+## Work with no ticket yet
+
+A **stand-in** is a name the user gave work that Jira does not hold yet. It takes bands across
+days and across checkouts, and it books nothing. `standins` lists them:
+
+```bash
+{%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
+app is the only place they give it. If the user asks for a ticket, use `create` and tell them
+to resolve the stand-in in Timetrack.
+
+A placeholder is drawn per branch, and per directory where the branch names no piece of work.
+A base branch, or no branch at all, says nothing about what was worked on, so the directory the
+commits touched answers instead. That directory is the project the repository declares - the one
+carrying the `project.json` or `package.json` above the changed files. A repository that declares
+none lets its own commits pick the grain between them. A directory named with a leading dot is
+the checkout's own tooling, so it never answers: a commit in `.changeset` or `.github` is
+bookkeeping for another piece of work.
+
+Where the directories cannot answer either, the branch the checkout was next cut onto does. A
+branch is very often cut once the work on it has started, so the minutes before the cut sit on
+the base branch although they are that branch's work.
+
+One placeholder written before any of that was true covers a whole checkout, and it blocks a
+per-branch placeholder for every branch of it. The list says so:
+
+```
+Competition journey spec frontend in FIFAGG  3d old, 3 day(s) of work
+  covers all of /home/tom/dev/fifagg/specs, so no branch of it gets one of its own
+```
+
+Two separate things cause that, and either alone is enough: the record names no branch, or the
+rule naming it names no branch. The line above reports both, so take it at its word rather than
+reading `--json` yourself.
+
+### Give one another name
+
+The name is only wrong, and the work behind it is right:
+
+```bash
+{%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
+lose. Rename one only when the user asks. The name is their own word for their work, so a name you
+find unclear is not a fault to correct.
+
+### Resolve one to its issue
+
+The user told you which Jira issue a placeholder is:
+
+```bash
+{%packageRunner%} ethlete-agents timetrack standins --resolve <id> --issue <KEY>
+```
+
+It resolves the placeholder as the user's own pick in the app does, so every band on every day it
+held takes the key. One that is resolved already moves to the new key, as the app's Undo and a new
+pick would. It writes nothing to Tempo, so a day of it already booked keeps the old key there. The
+app reads the issue from Jira before it queues anything, so an unknown key or placeholder answers an
+error and nothing waits. A done issue is fine. The approval card shows the name, the old key and the
+new one with its summary.
+
+### Re-cut one that named two pieces of work
+
+A record covering a whole checkout is repaired rather than deleted, because a delete strands its
+days. `--split` re-cuts it into one record per directory, and moves each day onto the right one:
+
+```bash
+{%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,
+then says which of them it would write. A directory under three commits is an edit made in
+passing rather than a piece of work, so it is listed but not written. Pass
+`--paths <dir>,<dir>` to pick the pieces yourself.
+
+The commits are read across every branch, and only the ones the checkout's own `user.email`
+authored. That is the history the collector that opened the record read, so work left on an
+unmerged branch still counts and a colleague's commits never shape a piece. `--author <email>`
+overrides the address.
+
+A day the record covers that holds no commit of yours goes back to unnamed, and the split names
+it. That is the honest answer: nothing says which directory it was. The day review is where it
+gets named, and `--claim <dir>` gives every such day to one directory instead.
+
+The record and its checkout-wide rule always go, even when a day is left unnamed. Both are read
+as covering every branch of the checkout, so keeping either would block any later branch from
+getting a record of its own — which is the fault the repair exists to cure.
+
+The record must name the checkout it was opened for. One the user opened by hand names none, and
+the split refuses it.
+
+You may delete one, because that takes a name away rather than putting one on the day:
+
+```bash
+{%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:
+
+- The record names a branch. The delete refuses that branch, and no second one opens for it.
+- It names none. The delete refuses nothing, so the next pass opens one per branch instead.
+
+**Deleting one strands every day but today.** Only the day the app next reviews gets a new
+placeholder; every earlier day the record covered then reads as unnamed, with nothing left to
+say what it was. The command refuses such a delete and lists the days, and `--force` makes it
+anyway. Ask the user before you use `--force`, and tell them which days they will lose.
+
+## Why a checkout was never offered a name
+
+The day screen offers a whole checkout one issue when the user's own record already answers it. The
+card is either drawn or it is not, and every step that can stop it is invisible from the screen.
+`naming` names the step:
+
+```bash
+{%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
+checkout the day saw either the offer or the reason there is none - `already-named`,
+`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
+
+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
+{%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, 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` 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
+
+- **The projects.** The user picked them in Timetrack. `search` is scoped to them, and
+  `--project <KEY>` is how you look outside.
+- **The branch subject.** `issue` returns `subject` when the instance's subject field is set on
+  that issue. Prefer it over the summary; the summary is a paraphrase.
+- **The instance.** Its host, its issue types and its hierarchy are settings in the app. Do not
+  hardcode any of them in this repo.

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.