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

package/CHANGELOG.md

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

package/README.md

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

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

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

package/content/rules/app-styling.md

@@ -18,6 +18,10 @@ component a host class (`host: { class: 'app-player-card' }`) and scope every se
 the way SDK components scope theirs under their `et-` classes. Never write a bare element or
 unprefixed class selector in a component stylesheet.
 
+In an existing repo, apply this to the component you are editing, not to the rest of the app. A
+legacy component that relies on emulated encapsulation keeps it until its CSS is scoped under a
+host class: without that scope, `ViewEncapsulation.None` leaks its CSS into every view.
+
 Write CSS only for what utilities cannot express. Keep that CSS **unlayered** or in
 `@layer utilities` — never in `@layer components`, and that includes the global stylesheet. SDK component styles are injected into
 `@layer components` at runtime, after your stylesheet, so an app rule in the same layer
@@ -34,7 +38,8 @@ The SDK sizes everything in `rem` on a **10px root**: the app's global styleshee
 The 10px root also shrinks every rem-based Tailwind scale to 62.5% of its nominal size (1.6×
 smaller): `p-4` is 10px instead of 16px, and `max-w-3xl` is 480px instead of 768px. Set
 `--spacing: 0.4rem` in the app's `@theme` so the spacing scale keeps its 4px step, as the SDK's
-own Storybook does. Redefine any other rem scale the app uses (`--text-*`, `--container-*`,
+own Storybook does. In an app that already uses utilities without it, setting it rescales every
+view: tell the user rather than set it. Redefine any other rem scale the app uses (`--text-*`, `--container-*`,
 `--radius-*`) the same way, or use px where a size matters. Breakpoints are not affected: a
 media query's `rem` ignores the root font size.
 

package/content/rules/subagent-models.md

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

package/content/skills/design-exploration/SKILL.md

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

package/content/skills/query/SKILL.md

@@ -123,7 +123,7 @@ post = computed(() => this.postQuery.response());
 - `GET`/`HEAD`/`OPTIONS` **auto-execute** - immediately when static/argless, or
   whenever `withArgs` produces new args. Mutations (`POST`/`PUT`/`PATCH`/`DELETE`)
   never auto-execute; declare their args with `withArgs` too and call `.execute()`. A function route (`pathParams`)
-  requires `withArgs` (dev-mode error otherwise).
+  requires `withArgs` (a type error, and a dev-mode error).
 - A route function receives the path params themselves: `(p) => \`/posts/${p.postId}\``.
 - With bearer auth, bind the secure creators the same way:
   `const secureGetQuery = createSecureGetQuery(apiClient, authProviderRef)`.
@@ -154,10 +154,18 @@ users = getUsers(
 
 Bind form controls with `[formField]="qf.fields.search"`. `et-pagination` and
 `et-page-size-select` are not form controls: bind their `model` to the field's value signal,
-`[(page)]="qf.fields.page().value"`. `qf.value()` is the committed, debounced value. Each
+`[(page)]="qf.fields.page().value"`; an `et-table` sort binds the same way to a
+`tableSortQueryField()`, `[(sort)]="qf.fields.sort().value"`, with no mapping. `qf.value()` is the committed, debounced value. Each
 change pushes a history entry; pass `observe({ replaceUrl: true })` to replace it instead. See {%docsBaseUrl%}/query/query-forms for the other field creators,
 filter overlays and `activeFilterCount`.
 
+When you move a list that syncs its params by hand, keep the param names the URL already uses, so
+saved links keep working (`queryParamPrefix` when two lists share a route). Keep each old default as
+the field's `defaultValue`. A URL with sort and direction in two params (`?sort=name&dir=asc`)
+keeps two `queryField`s, `dir` with `skipInFilterCount: true`; `sortQueryField()` writes one
+`name:asc` param, so it breaks old links. A date field bound to `et-date-input`,
+`et-date-time-input` or `et-time-input` needs `dateQueryField({ as: 'string' })`.
+
 ## The query object
 
 Every state member is an **`ObservableSignal`** - call it, or `.asObservable()` it without an

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

@@ -69,9 +69,11 @@ Two files describe what is left. Read the JSON one when you work through the lis
 
 Every task carries a `kind`, and the kind decides who acts:
 
-- **`assisted`** - written for you. The task file states one change to apply across this repo. Read the
-  whole file before the first edit, then apply it. These are the changes no codemod can make, so expect
-  a decision per call site rather than one pattern.
+- **`assisted`** - written for you. The task file states one bounded change to apply across this repo.
+  Read the whole file before the first edit, then work it until its `Done when` list holds. These are
+  the changes no codemod can make, so expect a decision per call site rather than one pattern. What the
+  file leaves for later stays for later: report it, do not do it. A view you cannot open in the browser
+  (a login fails, no API) goes into your report as unchecked; it does not block the task.
 - **`manual`** - a recommendation for the developer. It needs a product or design decision, or a
   command with answers only they have. Do not guess the answer. Report the task and what it needs.
 - **`unsupported`** - a codemod that could not run here, because this repo has no Nx. The task carries

package/content/skills/timetrack/SKILL.md

@@ -21,6 +21,20 @@ in this machine's keychain, and every repository asks it:
 
 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,25 +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    |
-| `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     |
+| 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.
@@ -87,9 +105,10 @@ timeline, with the id every edit names a row by, the day's totals and its warnin
 {%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.
@@ -166,7 +185,7 @@ days. `--split` re-cuts it into one record per directory, and moves each day ont
 
 ```bash
 {%packageRunner%} ethlete-agents timetrack standins --split <id>              # the plan, writes nothing
-{%packageRunner%} ethlete-agents timetrack standins --split <id> --force      # carry it out
+{%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,
@@ -234,7 +253,7 @@ read-only, and the app keeps the Tempo token:
 ```
 
 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
+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.
 
@@ -255,21 +274,72 @@ counted. `--json` answers each entry with `calendarId`, `day`, `startMs`, `endMs
 `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
 {%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/migrations/app-styling-utilities.md

@@ -1,114 +1,63 @@
-# Style app components with Tailwind utilities
+# Move app CSS out of `@layer components`
 
-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.
+The `app-styling` rule now says how app components are styled: Tailwind utilities in the
+template, CSS only for what a utility cannot express, and never an app rule in
+`@layer components`. SDK styles are injected into that layer at runtime, after the app's
+stylesheet, so an app rule there ties on layer and loses on source order. That is a bug today,
+and this task fixes it. The rest of the rule applies when a component is next edited.
 
 ## 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'
-```
+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`), then
+read the rule. If the repo's own styling rules (a styleguide, `CONTRIBUTING.md`, the parts of
+`AGENTS.md` outside the generated block) forbid a change below, follow them and report the
+conflict.
 
 ## 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:
+1. Find the app stylesheets with a `@layer components` block, global stylesheets included:
 
    ```bash
-   grep -rnE '(^|[ ,>+~])\.et-[a-z0-9-]+' apps libs --include='*.css' --include='*.scss'
+   grep -rlE '@layer components' apps libs --include='*.css' --include='*.scss' --include='*.sass' --include='*.less'
    ```
 
-   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.
+2. In each, move the rules out of the block into `@layer utilities`, and delete the empty
+   block. In `@layer utilities` a rule still beats the SDK, and does not beat every utility the
+   way unlayered CSS would.
+3. The move lets these rules win over SDK styles they used to lose to. Check the views that use
+   them. Where a view now looks wrong because the old rule was never meant to apply, delete the
+   rule instead.
 
 ## 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.
+- `--spacing` and the other rem scales in `@theme`. If the app has not set `--spacing: 0.4rem`,
+  setting it now rescales every utility already in use: report it and leave it.
+- `html { font-size: 62.5%; }`: if it is missing, report it and leave it. Adding it rescales
+  every `rem` the app uses.
+
+## On touch, not in this task
+
+Rewriting BEM classes and component stylesheets to utilities, replacing hardcoded colours with
+theme tokens, and adding `ViewEncapsulation.None` to a component that relies on emulated CSS
+(its CSS would leak) happen when someone edits that component. Count what is left for the
+final message:
+
+```bash
+grep -rlE 'styleUrls?:' apps libs --include='*.ts' | wc -l
+grep -rlE 'class="[^"]*\b[a-z0-9-]+__[a-z0-9-]+' apps libs --include='*.html' --include='*.ts' | wc -l
+grep -rlE '@Component\(' apps libs --include='*.ts' | xargs grep -LE 'ViewEncapsulation\.None' | wc -l
+```
 
-## When you are done
+## Done when
 
-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 grep in step 1 finds no app stylesheet, apart from the ones under "Leave these alone".
+- The type check, lint and build pass for every project you changed.
+- Each view that uses a moved rule is checked in the browser. A view you cannot open (the login
+  fails, no API) is listed as unchecked in your final message; that does not block the task.
+- Your final message gives the three counts above, and whether `--spacing` and the 62.5% root
+  are set.
 
-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.
+Then delete this task file.