@ethlete/agent-rules 0.1.0-next.2 → 0.1.0-next.21

package/content/skills/git-flow/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: git-flow
+description: How to name and base a branch in this repo, and what its merge request must target - feature, sub-feature, release, release fix and hotfix. Read BEFORE creating a branch, opening a merge request, or choosing what to branch from (e.g. the user says "start work on FIP-2177" or "open an MR").
+kind: skill
+scope: both
+vars: [gitFlowDevelopmentBranch, gitFlowProductionBranch, gitFlowTypes, gitFlowEnforcement, gitFlowSubPrefix]
+---
+
+# Git flow
+
+Work is organised in two levels: a **main feature branch** per Jira Story, into which
+**sub-feature branches** (one per Task) are merged after review. The main feature branch is
+what gets deployed to a test environment and, once accepted, merged into
+`{%gitFlowDevelopmentBranch%}`.
+
+**Never name a branch by hand - `start` does it from the grammar:**
+
+```bash
+{%packageRunner%} ethlete-agents git-flow start FIP-2178        # reads the issue, names it, branches off the right base
+{%packageRunner%} ethlete-agents git-flow check                 # is the current branch conforming?
+{%packageRunner%} ethlete-agents git-flow explain <branch>      # what the parser sees, and what it expects
+{%packageRunner%} ethlete-agents git-flow repair <branch>       # rename a non-conforming one, retarget its MRs
+```
+
+`start` prints its plan (branch, base, MR target) and asks before writing anything; add
+`--dry-run` to see the plan alone. It refuses on a dirty working tree, and a Task nests under
+its parent Story's branch, so that branch has to exist first.
+
+It reads the issue through the running Timetrack app, which holds this machine's only Jira
+credentials. If it reports that the app is not running, ask the
+user to start it. `--subject <text>` names a branch without reading Jira at all.
+
+## The five shapes
+
+| Shape                                                                             | Issue | Branch from                    | MR targets                                                       |
+| --------------------------------------------------------------------------------- | ----- | ------------------------------ | ---------------------------------------------------------------- |
+| `feat/FIP-2177-user-management`                                                   | Story | `{%gitFlowDevelopmentBranch%}` | `{%gitFlowDevelopmentBranch%}`                                   |
+| `{%gitFlowSubPrefix%}/feat/FIP-2177-user-management/FIP-2178-user-password-reset` | Task  | the main feature branch        | the main feature branch                                          |
+| `release/2026.04.28`                                                              | -     | `{%gitFlowDevelopmentBranch%}` | `{%gitFlowDevelopmentBranch%}` and `{%gitFlowProductionBranch%}` |
+| `{%gitFlowSubPrefix%}/release/2026.04.28/FIP-2222-button-not-visible`             | Bug   | the release branch             | the release branch                                               |
+| `hotfix/FIP-2799-password-recovery-broken`                                        | Bug   | `{%gitFlowProductionBranch%}`  | `{%gitFlowProductionBranch%}`                                    |
+
+- The **type** is one of {%gitFlowTypes%}, and a nested branch carries its parent's **full**
+  name - that path is what makes the parent machine-readable.
+- The **key** is the Jira issue, uppercase, immediately after the type. The **subject** is the
+  Story's subject meta field in kebab-case, not a paraphrase of the summary.
+- A branch with no key still works, but nothing can attribute it to an issue. Add the key.
+
+### Why a nested branch starts with `{%gitFlowSubPrefix%}/`
+
+Git refuses a ref that is both a branch and a directory of branches. So
+`feat/FIP-2177-user-management/FIP-2178-user-password-reset` **cannot exist** while
+`feat/FIP-2177-user-management` does - git rejects it locally and the push comes back as
+`refname conflict`. The prefix moves the nested tree out of the way and keeps the parent's
+full path inside the child's name, so the MR target is still readable off the name.
+
+Do not "fix" a name by dropping the prefix; the branch it produces cannot be created.
+
+## Rules that are not about naming
+
+- **Never rebase a shared branch.** A main feature branch is published and other people's
+  sub-features are based on it - bring it up to date by **merging**
+  `{%gitFlowDevelopmentBranch%}` into it. Rebase only a local branch you have not pushed.
+- **A sub-feature merges into its parent, never straight into
+  `{%gitFlowDevelopmentBranch%}`** - that is the whole point of the two levels, since the
+  parent is what gets tested as a unit.
+- **Delete the source branch on merge** (the checkbox in the merge request) for sub-features,
+  release fixes and merged main features.
+- **A hotfix branches off `{%gitFlowProductionBranch%}`** and, after rollout, that branch is
+  merged back into `{%gitFlowDevelopmentBranch%}` so the two do not drift.
+- **Never push directly to `{%gitFlowDevelopmentBranch%}` or
+  `{%gitFlowProductionBranch%}`.** Open a merge request; it needs another developer's review.
+
+## Enforcement is `{%gitFlowEnforcement%}`
+
+In `advisory` mode every rule reports and nothing blocks - the older naming shapes (`feature/`
+instead of `feat/`, a lowercase key, no key at all, a `dev-*` integration branch) are accepted
+on purpose while the team adapts. Report the suggestion, do not "fix" someone's existing
+branch unasked - `repair` is how a rename happens, and only when asked for.
+
+`dev-*` is the **old spelling of a main feature branch**, not a stray name: sub-features
+legitimately target it. Leave a live one alone.
+
+## Commit messages are a separate thing
+
+Commits stay conventional (`feat(platform): Prefer a player's common name`) and carry **no
+issue key** - the branch already has it. Follow the repository's commit-message guidance.

package/content/skills/grill-with-docs/SKILL.md

@@ -0,0 +1,13 @@
+---
+name: grill-with-docs
+description: A relentless interview to sharpen a plan or design, which also creates docs (ADR's and glossary) as we go.
+kind: skill
+scope: both
+modelInvocation: false
+---
+
+Call the Skill tool twice, for {%skill:grilling%} and {%skill:domain-modeling%}.
+
+---
+
+Vendored from [mattpocock/skills](https://github.com/mattpocock/skills) at `3cca18b`, MIT (Copyright (c) 2026 Matt Pocock).

package/content/skills/grilling/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: grilling
+description: Grill the user relentlessly about a plan, decision, or idea. Use when the user wants to stress-test their thinking, or uses any 'grill' trigger phrases.
+kind: skill
+scope: both
+---
+
+Interview the user relentlessly until you reach a shared understanding. Map this as a **design tree**: every decision branches into the decisions that hang off it.
+
+Work the tree in **rounds**. The **frontier** is every decision whose prerequisites are already settled: the questions you can ask _now_ without guessing at answers you haven't heard yet. Ask the whole frontier in one round: number each question and give your recommended answer. Then wait for the user's answers before the next round.
+
+Format a round like so:
+
+```
+❓ **Q1** - **<question title>**: <question body, might be multiple paragraphs, including multiple choices>
+
+➡️ <your recommended answer>
+
+---
+
+❓ **Q2** - **<question title>**: <question body, might be multiple paragraphs, including multiple choices>
+
+➡️ <your recommended answer>
+```
+
+Each round the user answers reshapes the tree: settled decisions push the frontier outward and unblock questions that depended on them. Recompute the frontier and ask the next round. A question whose answer depends on another question still open in this round belongs to a _later_ round, not this one.
+
+Finding _facts_ is your job, never the user's. When a frontier question needs a fact from the environment (filesystem, tools, etc.), dispatch a sub-agent to find it; don't ask the user for anything you could look up yourself. Don't block on it: a running exploration is an unsettled prerequisite, so only the questions downstream of it wait for the sub-agent to report; ask the rest of the frontier now. The _decisions_ are the user's: put each to them and wait.
+
+The session is done when the frontier is empty: every branch of the design tree visited, nothing left silently assumed. Do not act on it until the user confirms you have reached a shared understanding.
+
+---
+
+Vendored from [mattpocock/skills](https://github.com/mattpocock/skills) at `3cca18b`, MIT (Copyright (c) 2026 Matt Pocock).

package/content/skills/handoff/SKILL.md

@@ -15,11 +15,78 @@ continue in a fresh session. Two modes:
 - **save** ("handoff", "wrap up") - write a handoff file.
 - **resume** ("continue from the handoff") - read one and continue the work.
 
+Name one invocation form to the user - your own - and never both. The skill is
+installed as `ethlete-handoff`, so under Claude Code the commands are
+`/ethlete-handoff` and `/ethlete-handoff resume [name]`; there is no `/handoff`.
+Codex has no slash commands, so there the same two are plain prompts without the
+leading `/`.
+
 Handoff files live in `{%handoffDir%}/` (gitignored - they are personal,
 ephemeral working state, not team docs).
 
+## Handoff mode
+
+Where this repo installs the `context-warning` hook, it names the budget at session start,
+turns handoff mode on at 70% of it, and repeats a short note with the remaining budget on
+every prompt after that. It reaches you at three points, not only when the user types: at
+the start of the session, after a batch of your own tool calls, and as a turn ends. So a
+long autonomous run learns its token count while it works.
+
+Handoff mode is not an order to stop. It is the signal to change how you work, so that
+either ending - you finish, or a fresh session takes over - stays cheap:
+
+- Work in slices that each end in a committable state. Never leave two half-finished edits
+  in the tree.
+- Send bulky reads, searches and test runs to a sub-agent. Its output stays out of your
+  context; its answer does not.
+- Write down each decision and dead end as you reach it, in the commit message or in the
+  handoff file. Do not save them for a final summary you may have no room for.
+- Start nothing you cannot finish or hand off inside the remaining budget.
+
+At the critical tier (85%) the hook asks you to choose one of two, and to tell the user
+which you chose:
+
+1. **Finish the task.** Only when you can name every step that is left, and they plainly
+   fit the remaining budget. Finish it, commit, then apply the save test below - the answer
+   is then usually that no file is needed at all.
+2. **Hand off.** Everything else. Finish the in-flight atomic edit, nothing new, then save.
+
+"Nearly done" means you can name the last steps now. It does not mean the end feels close.
+At the last tier (95%) the hook takes option 1 away, because a budget that small covers no
+task.
+
+### Ending a turn over the budget
+
+From 85% on, the hook also fires as you try to end the turn, and the turn then continues so
+you can act. It adds a third option to the two above:
+
+3. **Cross the boundary on purpose.** Some sessions are worth the premium rate: the task is
+   one step from done, or this session holds reasoning that no handoff file survives. Take
+   it only for a reason you can name in one sentence right now. Say the reason, say what it
+   costs, and keep working.
+
+Option 3 is a judgment call, not a way out of the other two. Naming a reason you cannot
+state plainly is the same as taking option 2 late and expensively. The hook asks once per
+tier, so it will not block the end of a turn twice for the same budget. It stays quiet while a
+handoff is being saved, until the user's next prompt.
+
 ## Save mode
 
+**Decide first whether a handoff is needed at all.** One exists so work can resume, so
+write one only when at least one of these holds:
+
+- Uncommitted work from this session sits in the tree.
+- A step the user asked for is unfinished, blocked, or waiting on a result.
+- A decision, dead end, or user constraint from this session is written down nowhere else -
+  not in a commit message, a changeset, a docs page, or a plan file.
+
+Check it, never assume it: `git status`, `git log`, and the task as the user stated it. A
+context warning is a token count, not evidence that work is left.
+
+If none of them holds, write no file. Tell the user in two or three lines what landed, name
+the commits, and say a fresh session needs nothing from this one. A handoff nobody resumes is
+noise, and it costs the next session the tokens to read it.
+
 Write `{%handoffDir%}/<slug>.md` where `<slug>` is a short kebab-case name for
 the task (use the user-provided slug if they gave one). If the file exists,
 overwrite it - a handoff always describes the _current_ state.
@@ -90,9 +157,12 @@ resume from it.
 3. Verify reality still matches: current branch, `git status`, last commit. If
    they diverge from the handoff (e.g. someone committed in between), say what
    changed and adapt - the repo is the truth, the handoff is the guide.
-4. Read any guides the handoff's work obviously needs (e.g. {%skill:theming%}
-   before CSS work) - same rules as always.
+4. **Read only what you are about to change.** The handoff already carries the decisions,
+   the constraints and the dead ends, so do not re-read the plan files it summarises, and do
+   not survey the directory. Open a source file when you are going to edit it, and load a
+   focused guidance file only when the work needs one.
 5. Continue with the **Next steps** section. Don't redo work listed under
    _Done_; don't re-open questions under _Decisions_.
-6. When every next step is complete (including changeset/docs follow-ups),
-   delete the handoff file so the directory only contains live handoffs.
+6. When every next step is complete, decide whether the handoff can be removed. Delete it
+   only if this workflow created it and the save workflow or user authorized cleanup.
+   Otherwise report that it is no longer needed and let the user decide.

package/content/skills/query/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: query
-description: The signals-first @ethlete/query data-fetching system - the query client, typed query creators, reactive args, and reading results as signals or observables. Read BEFORE writing or reviewing code that fetches data, wires search/autocomplete to an API, adds auth/polling/pagination, or bridges a query into UI or RxJS.
+description: The signals-first @ethlete/query data-fetching system - the query client, typed query creators, reactive args, and reading results as signals or observables. Read BEFORE writing or reviewing code that fetches data, builds a list with filters/search/sort/paging bound to URL query params (defineQueryForm), wires search/autocomplete to an API, adds auth, route guards or polling, or bridges a query into UI or RxJS.
 kind: skill
 scope: consumer
 requires: ['@ethlete/query']
@@ -13,38 +13,109 @@ Signals-first, typesafe data fetching for Angular: request dedup, caching, polli
 paged queries, bearer auth, GraphQL, and a socket.io realtime client.
 
 **The written docs are the source of truth - read the relevant page before
-non-trivial query work.** This guide is the index plus the load-bearing facts, so you
-don't re-derive them from source.
-
-| Page                                                                   | Covers                                                                              |
-| ---------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
-| {%docsBaseUrl%}/query/                                                 | Overview + the two-generations note                                                 |
-| {%docsBaseUrl%}/query/queries                                          | **Start here** - client, creators, the query object's signals, auto-execution       |
-| {%docsBaseUrl%}/query/features                                         | `withArgs`, `withPolling`, `withAutoRefresh`, side-effect handlers                  |
-| {%docsBaseUrl%}/query/http                                             | REST creators, typing requests, response transforms, upload progress                |
-| {%docsBaseUrl%}/query/auth                                             | Bearer auth: login/refresh, auto token refresh, multi-tab sync                      |
-| {%docsBaseUrl%}/query/caching · `/stacks` · `/errors` · `/gql` · `/ws` | Caching/dedup, pagination, error/retry, GraphQL, WebSockets                         |
-| {%docsBaseUrl%}/query/multi-tab                                        | Opt-in cross-tab sync: shared responses, per-key polling election, mutation fan-out |
-| {%docsBaseUrl%}/query/query-forms                                      | Router-synced filter/search forms                                                   |
-| {%docsBaseUrl%}/query/legacy                                           | The maintenance-mode `V2QueryClient`                                                |
+non-trivial query work.** This guide maps every need to its API and page, plus the
+load-bearing facts, so you don't re-derive them from source or hand-build what ships.
+
+| Page                                              | Covers                                                                                  |
+| ------------------------------------------------- | --------------------------------------------------------------------------------------- |
+| {%docsBaseUrl%}/query/                            | Overview, the two generations, what else the package ships                              |
+| {%docsBaseUrl%}/query/queries                     | **Start here** - client, creators, the query object's signals, auto-execution           |
+| {%docsBaseUrl%}/query/features                    | `withArgs`, polling, auto-refresh, side-effect handlers, custom features                |
+| {%docsBaseUrl%}/query/http                        | REST creators, typing requests, response transforms, upload progress                    |
+| {%docsBaseUrl%}/query/auth                        | Bearer auth provider, guards, token refresh, auth features                              |
+| {%docsBaseUrl%}/query/caching                     | Cache keys, dedup, `keepUnusedFor`, freshness, refresh and invalidation                 |
+| {%docsBaseUrl%}/query/multi-tab                   | Cross-tab response sharing, one poller per key, mutation fan-out                        |
+| {%docsBaseUrl%}/query/persistence                 | Successful reads kept in IndexedDB for reloads and offline cold starts                  |
+| {%docsBaseUrl%}/query/stacks                      | Many queries of one creator, infinite lists, paged data                                 |
+| {%docsBaseUrl%}/query/dependent-queries           | GET → GET dependencies and ordered mutation chains                                      |
+| {%docsBaseUrl%}/query/groups                      | Several queries behind one state: loading, error and retry follow the one that ran last |
+| {%docsBaseUrl%}/query/batching                    | Bulk writes with bounded concurrency, per-item results, retry                           |
+| {%docsBaseUrl%}/query/errors                      | Error object, opt-in parsers, form submission, violations, retries                      |
+| {%docsBaseUrl%}/query/testing                     | Specs: answering requests, `@ethlete/query/testing` helpers and fakes                   |
+| {%docsBaseUrl%}/query/query-forms                 | **Any filtered, searched, sorted or paged list** - `defineQueryForm`                    |
+| {%docsBaseUrl%}/query/gql                         | GraphQL creators over GET/POST                                                          |
+| {%docsBaseUrl%}/query/ws                          | socket.io rooms and live-updating responses                                             |
+| {%docsBaseUrl%}/query/legacy                      | The maintenance-mode `V2QueryClient` and its replacements                               |
+| {%docsBaseUrl%}/query/migrating-from-v2           | Codemods and the screen-by-screen move off the legacy client                            |
+| {%docsBaseUrl%}/query/migrating-from-ngrx-toolkit | The generator and interop that move a store off `@tomtomb/ngrx-toolkit`                 |
+| {%docsBaseUrl%}/query-devtools/                   | The devtools panel and `provideQueryDevtools()`                                         |
+
+## You need → use → read
+
+Before writing a helper, find your need here. Pages are under `{%docsBaseUrl%}/query/`.
+
+| You need                                                                       | Use                                                                                                                                                                                                                                    | Read                |
+| ------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- |
+| One client per API                                                             | `createQueryClient`, `injectApi()`                                                                                                                                                                                                     | `queries`           |
+| REST reads (auto-executing)                                                    | `createGetQuery`, `createHeadQuery`, `createOptionsQuery`                                                                                                                                                                              | `http`              |
+| REST writes (manual)                                                           | `createPostQuery`, `createPutQuery`, `createPatchQuery`, `createDeleteQuery`                                                                                                                                                           | `http`              |
+| The same behind a bearer token                                                 | `createSecureGetQuery`, `createSecureHeadQuery`, `createSecureOptionsQuery`, `createSecurePostQuery`, `createSecurePutQuery`, `createSecurePatchQuery`, `createSecureDeleteQuery`                                                      | `http`, `auth`      |
+| Upload/download progress bar                                                   | creator option `reportProgress: true`, then `loading().progress`                                                                                                                                                                       | `http`              |
+| Args that follow signals (route params, inputs, filters)                       | `withArgs`                                                                                                                                                                                                                             | `features`          |
+| A filtered / searched / sorted / paged list synced to the URL                  | `defineQueryForm`, `queryField`, `searchQueryField`, `sortQueryField`                                                                                                                                                                  | `query-forms`       |
+| Refetch on an interval                                                         | `withPolling`                                                                                                                                                                                                                          | `features`          |
+| Next request once the previous settled, with a cursor from it                  | `withLongPolling`                                                                                                                                                                                                                      | `features`          |
+| Refetch when some other signal changes                                         | `withAutoRefresh`                                                                                                                                                                                                                      | `features`          |
+| Toast / log / react on success or failure                                      | `withSuccessHandling`, `withErrorHandling`, `withLogging`                                                                                                                                                                              | `features`          |
+| Patch a loaded response in place (e.g. from a socket message)                  | `withResponseUpdate`                                                                                                                                                                                                                   | `features`, `ws`    |
+| Page falls out of range after a filter shrinks the results                     | `withPageResetOnError`, `isPageOutOfRangeError`                                                                                                                                                                                        | `features`          |
+| Package your own reusable query behavior                                       | `createQueryFeature`                                                                                                                                                                                                                   | `features`          |
+| Refresh reads after a mutation (here and in other tabs)                        | `injectApi().invalidateQueries({ url })`                                                                                                                                                                                               | `caching`           |
+| Show a mutation's result in cached reads before the server answers             | `withOptimisticUpdate`                                                                                                                                                                                                                 | `caching`           |
+| One loading, error and retry state for whichever of several mutations ran last | `createQueryGroup`                                                                                                                                                                                                                     | `groups`            |
+| Refetch everything after a client-wide header changed                          | `injectApi().refreshQueriesInUse()`                                                                                                                                                                                                    | `caching`           |
+| Show the previous data instantly on back navigation                            | `keepUnusedFor` + `executionState().cachedResponse`                                                                                                                                                                                    | `caching`           |
+| Last known data after a reload or offline                                      | `withQueryPersistence`, `createIndexedDbQueryPersistenceAdapter`, `createNoopQueryPersistenceAdapter`                                                                                                                                  | `persistence`       |
+| Tabs share responses, poll once, see each other's mutations                    | `withMultiTabSync`                                                                                                                                                                                                                     | `multi-tab`         |
+| Parallel detail requests for a list of ids                                     | `createQueryStack`, `transformArrayResponse`                                                                                                                                                                                           | `stacks`            |
+| Load more / infinite scroll / classic paging                                   | `createPagedQueryStack`, `ethletePaginationAdapter` (and other adapters)                                                                                                                                                               | `stacks`            |
+| A GET whose args come from another GET's response                              | `withArgs` reading the first query's `response()`                                                                                                                                                                                      | `dependent-queries` |
+| Run mutations in order, each using the previous result                         | `querySequence`                                                                                                                                                                                                                        | `dependent-queries` |
+| Many edits with progress, time remaining and retry of failures                 | `createQueryBatch`                                                                                                                                                                                                                     | `batching`          |
+| Submit a signal form through a mutation, violations on fields                  | `createQuerySubmission`                                                                                                                                                                                                                | `errors`            |
+| Own submit handler, or server-side validation while typing                     | `executeUntilSettled`, `executeUntilSettled$`, `mapViolationsToFormErrors`, `validateWithQuery`                                                                                                                                        | `errors`            |
+| Understand the error shapes your API returns                                   | `withEthleteApiErrors` (all), `withSymfonyErrors`, `withHtmlErrorParsing`                                                                                                                                                              | `errors`            |
+| Error text for display, or an error built by hand (tests)                      | `queryErrorMessage`, `queryErrorMessages`, `createQueryErrorResponse`, `<et-query-error>`                                                                                                                                              | `errors`            |
+| Retry failed requests                                                          | `withDefaultRetry`, `createDefaultRetryFn`                                                                                                                                                                                             | `errors`            |
+| Login / refresh / logout with bearer tokens                                    | `createBearerAuthProvider`, `withAuthenticationQuery`, `withRefreshQuery`                                                                                                                                                              | `auth`              |
+| Protect routes, check roles or permissions                                     | `createAuthGuard`, `canMatchWith`                                                                                                                                                                                                      | `auth`              |
+| "Remember me" auto-login                                                       | `withPersistentAuth`                                                                                                                                                                                                                   | `auth`              |
+| Log out idle users                                                             | `withInactivityLogout`                                                                                                                                                                                                                 | `auth`              |
+| Warn before the session expires                                                | `withTokenExpirationWarning`                                                                                                                                                                                                           | `auth`              |
+| Revoke the token on logout                                                     | `withTokenRevocation`                                                                                                                                                                                                                  | `auth`              |
+| Share login/logout across tabs                                                 | `withBearerAuthMultiTabSync`                                                                                                                                                                                                           | `auth`              |
+| Auth telemetry events                                                          | `withTracking`                                                                                                                                                                                                                         | `auth`              |
+| Tokens from SSO or a native shell                                              | `provider.setTokens(access, refresh)`                                                                                                                                                                                                  | `auth`              |
+| Which of several queries is busy (v2 query collections)                        | each query's `executionState()` in a `computed`; auth: `provider.executionState()`                                                                                                                                                     | `migrating-from-v2` |
+| GraphQL                                                                        | `createGqlQueryViaGet`, `createGqlQueryViaPost`, `createGqlMutationViaGet`, `createGqlMutationViaPost`, `createSecureGqlQueryViaGet`, `createSecureGqlQueryViaPost`, `createSecureGqlMutationViaGet`, `createSecureGqlMutationViaPost` | `gql`               |
+| Realtime rooms over socket.io                                                  | `createWebSocketClient`                                                                                                                                                                                                                | `ws`                |
+| Inspect queries, stacks, auth and cache at runtime                             | `provideQueryDevtools()` + `@ethlete/query-devtools`                                                                                                                                                                                   | `/query-devtools/`  |
 
 ## Two generations - use the current one
 
-- **Current (use this):** signals-first, provider-based. `createQueryClient`,
-  `createGetQuery`/`createPostQuery`/…, `withArgs`. Everything imports from the
-  single entry `@ethlete/query`.
-- **Legacy (maintenance mode):** class-based `V2QueryClient`, `.prepare().execute()`,
-  `queryComputed`. Don't write new code against it.
+Write new code against the signals-first system (`createQueryClient`, `createGetQuery`, …,
+`withArgs`), all from the single entry `@ethlete/query`. The class-based `V2QueryClient`
+(`.prepare().execute()`, `queryComputed`) is in maintenance mode.
 
 ## Core usage
 
-One client per API, one creator per endpoint, one live query per component instance:
+One client per API, one bound creator per method, one query per endpoint, one live query
+per component instance:
 
 ```ts
 import { createQueryClient, createGetQuery, withArgs } from '@ethlete/query';
 
+// api.ts
 export const apiClient = createQueryClient({ name: 'api', baseUrl: API_URL });
-export const getPost = createGetQuery(apiClient)<GetPostArgs>((p) => `/posts/${p.pathParams.postId}`);
+export const getQuery = createGetQuery(apiClient);
+
+// posts.queries.ts
+export type GetPostQueryArgs = {
+  response: Post;
+  pathParams: { postId: string };
+};
+
+export const getPost = getQuery<GetPostQueryArgs>((p) => `/posts/${p.postId}`);
 
 // in a component (injection context):
 postId = input.required<string>();
@@ -54,61 +125,91 @@ 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; call `.execute({ args })`. A function route (`pathParams`)
-  requires `withArgs` (dev-mode error otherwise).
+  never auto-execute; declare their args with `withArgs` too and call `.execute()`. A function route (`pathParams`)
+  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)`.
 - Queries live in a child injector tied to the creating component; destroyed with it.
 
-## The query object
+## Lists with filters, search, sort or paging: `defineQueryForm`
 
-Every state member is an **`ObservableSignal`** - a `Signal` that also has
-`.asObservable()`. So each is both a signal (call it) and a stream:
+Never wire list controls to the URL by hand (`injectQueryParams` + `router.navigate` +
+drafts + effects). `defineQueryForm` does URL sync, debounce, defaults and page resets:
 
-- `response()` → `TResponse | null` (kept while re-executing; cleared on a failed re-exec).
-- `loading()`, `error()` (normalized `QueryErrorResponse`), `args()`,
-  `executionState()` (`{ type: 'loading' | 'success' | 'failure', … } | null`, great for `@switch`).
-- Methods: `execute({ args?, options? })`, `reset()`, `createSnapshot()`, `asReadonly()`.
-
-`query.response.asObservable()` binds to the query's own injector, so callers get
-an `Observable<T | null>` **without** needing their own injection context (unlike
-raw `toObservable`). It emits `null` first - `pipe(filter(r => r !== null))`.
+```ts
+qf = defineQueryForm({
+  fields: {
+    search: searchQueryField(),
+    sort: sortQueryField(),
+    page: queryField<number>({ defaultValue: 1, isResetBy: ['search', 'sort'] }),
+  },
+}).observe();
+
+users = getUsers(
+  withArgs(() => {
+    const { search, sort, page } = this.qf.value();
+
+    return { queryParams: { query: search, sortBy: sort?.active, sortOrder: sort?.direction, page } };
+  }),
+);
+```
 
-## Reactive args & features
+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"`; 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`.
 
-- **`withArgs(() => ({ pathParams, queryParams, body }))`** - runs like a `computed`;
-  re-runs when a signal it reads changes and re-executes the query. This is how you
-  drive **search-as-you-type**: back it with a search signal
-  (`withArgs(() => ({ queryParams: { search: this.search() } }))`). Return
-  `CLEAR_QUERY_ARGS` to reset args to `null` (pauses polling/auto-refresh).
-- `withPolling({ interval })`, `withAutoRefresh({ onSignalChanges: [...] })`.
-- Side-effects: `withSuccessHandling`, `withErrorHandling`, `withLogging`.
+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' })`.
 
-There is no built-in debounce operator - dedup/caching handles repeated identical
-requests; debounce at the input if you need it.
+## The query object
 
-## Bridging a query into RxJS / other APIs
+Every state member is an **`ObservableSignal`** - call it, or `.asObservable()` it without an
+injection context of your own (it emits `null` first).
 
-To hand a query's results to something that wants an `Observable<T[]>` (e.g. a
-`(query) => Observable<...>` source): drive the query by a search signal and return
-its response stream.
+- `response()` → `TResponse | null` (kept while re-executing; cleared on a failed re-exec).
+  To keep showing the last good data after a failure, read `cachedResponse` from the
+  `loading` or `failure` variant of `executionState()` - do not copy responses into a signal.
+- `loading()`, `error()` (normalized `QueryErrorResponse`), `args()`,
+  `executionState()` (`{ type: 'loading' | 'success' | 'failure', … } | null`, great for `@switch`).
+- Methods: `execute({ args?, options? })`, `reset()`, `createSnapshot()`, `asReadonly()`.
 
-```ts
-private search = signal('');
-private q = getItems(withArgs(() => ({ queryParams: { q: this.search() } })));
-
-fetch(query: string) {
-  this.search.set(query);
-  return this.q.response.asObservable().pipe(
-    filter((r): r is ItemsRes => r !== null),
-    map((r) => r.items),
-  );
-}
-```
+## Reactive args
+
+- **`withArgs(() => ({ pathParams, queryParams, body }))`** runs like a `computed` and
+  re-executes on change. Return `null` to park the query (pauses polling/auto-refresh).
+  Calling `.execute()` on a parked query is ignored and warns in dev mode
+  (`queryExecutedWhileParkedMessage`); pass `execute({ args })` or let the source return args.
+- **Prefer `withArgs` over `execute({ args })`.** Declared args keep a `GET` re-executing and
+  polling/auto-refresh restarting off the same signal; a function route throws without it. A
+  mutation with `withArgs` is just `.execute()`. Reserve `execute({ args })` for a one-off
+  payload no signal holds.
+- Search-as-you-type: read a debounced value (`searchQueryField()` debounces 300ms; every
+  query field takes `debounce`) - a raw input signal sends one request per keystroke.
+- `withLongPolling` and `withPolling` throw when combined.
+
+## Bridging into RxJS or callbacks
+
+For a callback that must return one correlated result, run a manual query
+(`{ onlyManualExecution: true }`) through `executeUntilSettled$(query, { args })` - cold, its
+snapshot is frozen to that execution, and unsubscribing aborts the request. Keep the Promise
+`executeUntilSettled` for an `async` signal-forms `submit()`. Never set a signal and return the shared `response`
+stream: the retained previous response can be the first non-null emission. See
+{%docsBaseUrl%}/query/queries#the-query-object.
 
 ## Gotchas
 
-- Signals-first: read `query.response()` in templates/computeds; it's **nullable**
-  (`?? []` / `filter(Boolean)` as needed).
-- Don't reach for the legacy client for new code.
+- `query.response()` is **nullable** (`?? []` / `filter(Boolean)` as needed).
 - `.execute()` defaults `args` to the current `args()` when omitted.
 - Anything under a query's `subtle` namespace is an unsupported escape hatch - never
   treat it as public API.
+- Use `withArgs` for mutations too. Never reach for `execute({ args })` plus
+  `silenceMissingWithArgsFeatureError` unless the args really exist only at call time - the
+  flag is an escape hatch, not the mutation pattern.

package/content/skills/rxjs-signals/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: rxjs-signals
-description: How to choose between signals and RxJS, and use each correctly - synchronous state vs asynchronous work, unsubscribing, and avoiding RxJS inside effects/computeds. Read when adding reactive state, wiring up an observable, or deciding whether something should be a signal or a stream. Part of the Ethlete styleguide (judgment beyond what lint enforces).
+description: How to choose between signals and RxJS, and use each correctly - synchronous state vs asynchronous work, unsubscribing, and avoiding RxJS inside effects/computeds. Read when adding reactive state, wiring up an observable, or deciding whether something should be a signal or a stream.
 kind: skill
 scope: both
 requires: ['@ethlete/core']
@@ -34,9 +34,16 @@ const data = toSignal(obs$);
 
 ## Using RxJS correctly
 
-- **Always unsubscribe.** Prefer `takeUntilDestroyed()` (needs an injection
-  context); otherwise `take` / `takeUntil` / `takeWhile`, or store and call
-  `.unsubscribe()`. Place the limiting operator **last** in the pipe.
+- **Tear down long-lived or manual subscriptions.** Finite streams that complete on their
+  own need no artificial lifecycle operator. For Angular lifecycle cleanup, prefer
+  `takeUntilDestroyed()` (it needs an injection context) or explicitly unsubscribe.
+  Do not use `takeWhile` as destruction cleanup: without another emission it stays
+  subscribed. Use `take(1)` or `first()` only when one emission is the operation's
+  intended semantics.
+- **`takeUntilDestroyed()` goes last in its pipe** (`ethlete/take-until-destroyed-last`), so
+  higher-order operators such as `switchMap` and their inner subscriptions are covered.
+  Other limiting and finalization operators do not have a universal “last” position;
+  place them where their semantics belong.
 - **Side effects go in `tap()`**, never in the `subscribe()` callback - keep
   `subscribe()` empty.
 - **Don't reach for RxJS inside `effect()`/`computed()`.** Subscribing per run
@@ -56,6 +63,26 @@ toObservable(page)
   .subscribe();
 ```
 
+## An effect that only writes a signal is a derivation
+
+If an `effect()` does nothing but `.set()` a signal, even behind an `if`, the value is derived
+state: use `computed()` when it is read-only, `linkedSignal()` when the user can still
+overwrite it. `ethlete/prefer-linked-signal` flags the plain cases. Keep `effect()` for work
+that leaves the signal graph: DOM, storage, logging, third-party APIs.
+
+```ts
+// ❌
+effect(() => {
+  if (this.items().length) this.selected.set(this.items()[0]);
+});
+
+// ✅ the previous value stays when the list is empty
+selected = linkedSignal<Item[], Item | null>({
+  source: this.items,
+  computation: (items, previous) => items[0] ?? previous?.value ?? null,
+});
+```
+
 ## Prefer `@ethlete/core` helpers
 
 Lint nudges these, but reach for them by default: `injectViewportSize()`,