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

package/content/skills/handoff/SKILL.md

@@ -15,11 +15,92 @@ 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.
 
+Text after the slug or the name is an instruction from the user, in both modes. In save mode it is
+for the session that resumes, so it must reach that session word for word. In resume mode it wins
+over the Next steps of the file where the two conflict.
+
+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.
+
+Then give a prompt the user can copy into the fresh session, in a code block: the next task, the
+plan file or finding it lives in, and any rule of this session that the repo does not record. Keep
+it to a few lines.
+
+An open item counts as the next task: a known gap, an open finding, or an unbuilt step in the plan,
+in the task, or in your own report of this session. "Everything waits for the user" is true only
+when every open item needs a decision of the user. Then name each decision; do not stop silently.
+In a `tmux` session, restart yourself with the next task as the prompt (see the next section) instead
+of handing the prompt to the user.
+
 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.
@@ -81,18 +162,57 @@ map, not a transcript.
 After writing, tell the user where it landed and that a fresh session should
 resume from it.
 
+## Clear and resume on your own
+
+Run inside a `tmux` session started with the agent-sessions `run` command or the shell functions from `shell-install` (`echo $TMUX` is not empty and
+the agent-sessions script `restart` finds the session)? Then you may clear and
+resume yourself after the save, instead of asking the user to. You decide. Do it only if every line
+is true:
+
+- No sub-agent, workflow or background command still runs. A background command from the old
+  session reports back into the new one, and a sub-agent answer has no reader after the clear.
+- No answer you wait for is open: a peer session, a mailbox reply, a CI run.
+- The tree is committed, or the handoff file names every uncommitted change.
+- The handoff file is saved and its Next steps are concrete.
+
+If one line is false, finish or collect that first. If you cannot, hand the prompt to the user as
+before. Then run, with the slug of the file you saved:
+
+```bash
+node <sessions-skill-dir>/agent-sessions.mjs restart <name> '<resume command> <slug> [<text after the slug>]'
+```
+
+If the user wrote text after the slug of the save command, append it to the prompt word for word.
+Escape each `'` in it as `'\''`. The restart drops anything you leave out, and the fresh session has
+no other way to see it.
+
+`<resume command>` is your own resume form from the top of this guide, with the name this repo
+installed the skill under: `/ethlete-handoff resume` under Claude Code, `ethlete-handoff resume`
+under Codex. A repo that ships its own copy can name it `handoff`, so check the skill directory
+name. A wrong name runs no skill, and the fresh session starts without the file.
+
+`<name>` is the sender name of your own session. Read it first with `tmux display-message -p -t "$TMUX_PANE" '#{session_name}'` and drop the `@<repo>` part: `claude-2@ethlete-sdk` gives `claude-2`. Never take the name from an example: a second Claude session is `claude-2`, not `claude`. The command refuses a session you do not run in. It returns at once. It
+types `/clear` (`/new` for a `codex` name) and the prompt into your pane a few seconds later, so
+end your turn after you run it and do not start another tool call. The `/clear` wipes the pane, so
+the user never sees text you write after the command. Before you run it, put the reason as the
+first line of the handoff file: `Restarted because: <one line>`. End the turn with no text.
+
 ## Resume mode
 
 1. List `{%handoffDir%}/`. Pick the file matching the given name, or the most
    recently modified one if no name was given. If the directory is empty, say so
    and stop.
-2. Read the file fully.
+2. Read the file fully. If its first line starts with `Restarted because:`, show that line to the
+   user first, then delete it from the file.
 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,18 @@ 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.
+  Completion-only operators (`finalize`, `defaultIfEmpty`, `toArray`, …) may follow it, and
+  chained `.pipe(...).pipe(...)` calls count as one pipe.
+  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 +65,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()`,

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

@@ -20,6 +20,13 @@ Two sources, both authoritative for different things:
 | **Docs site** | {%docsBaseUrl%}     | Prose guides: what a thing is for, options, defaults, behaviour, migration notes                 |
 | **Storybook** | {%sdkStorybookUrl%} | The live component: every variant rendered, the real controls, and the exact markup a story uses |
 
+## First: app setup
+
+Before the first component, work through `{%docsBaseUrl%}/components/setup` - the 62.5% root
+font size, Tailwind 4 theme generation, a `type: 'error'` color theme, and the providers
+(`provideOverlay`, `provideDateLocale`, label tokens, …). Missing any of them fails at runtime,
+not at compile time.
+
 ## Finding the right page
 
 Page URLs follow `{%docsBaseUrl%}/<lib>/<topic>`. The library sections:
@@ -28,23 +35,51 @@ Page URLs follow `{%docsBaseUrl%}/<lib>/<topic>`. The library sections:
 | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | `/components/`                                 | The active UI library - one guide per domain (see the list below)                                                                                                                    |
 | `/core/`                                       | Framework primitives: `theming`, `overlay-runtime`, `signal-utils`, `element-signals`, `animations`, `scrolling`, `drag-resize`, `directives-pipes`, `providers`, `seo`, `utilities` |
-| `/query/`                                      | Data fetching - see the dedicated {%skill:query%} guide first                                                                                                                        |
+| `/query/`                                      | Data fetching; load the dedicated query guide first when this package emitted one                                                                                                    |
 | `/cdk/`                                        | The predecessor UI toolkit, maintenance mode. Only for code that still uses it                                                                                                       |
 | `/contentful/`, `/cli/`, `/eslint/`, `/types/` | The remaining packages                                                                                                                                                               |
 
 Component domains under `/components/`:
 
-`accordion` `bracket` `bracket-rounds-list` `breadcrumb` `button` `calendar` `carousel`
-`cascader` `chip` `choice-inputs` `date-time-inputs` `dropzone` `error-codes`
-`filter-overlay` `floating-action` `focus-ring` `forms` `grid` `icon` `loader`
-`localization` `masonry` `match` `menu` `mixed-state` `notification` `overlay-openers`
-`overlays` `pagination` `picture` `query-devtools` `query-error` `rich-text-editor`
-`scrollable` `select` `skeleton` `slider` `sport-recipes` `standings` `stream` `table`
-`tabs` `text-inputs` `time-picker` `toggletip` `tooltip`
+`accordion` `avatar` `badge` `banner` `bracket` `bracket-prediction` `bracket-rounds-list`
+`breadcrumb` `button` `calendar` `card` `carousel` `cascader` `chart` `chip`
+`choice-inputs` `command-palette` `copy-button` `date-time-inputs` `description-list`
+`divider` `dropzone` `empty-state` `error-codes` `filter-overlay` `floating-action`
+`focus-ring` `forms` `grid` `icon` `kbd` `line-chart` `loader` `localization` `masonry`
+`match` `menu` `mixed-state` `notification` `overlay-openers` `overlays` `paged-query-trigger`
+`pagination` `picture` `pie-chart` `progress-steps` `query-error` `rich-text-editor` `sankey-chart`
+`scheduler` `scrollable` `scrollbar` `select` `setup` `skeleton` `slider` `sport-recipes` `stat-tile`
+`standings` `standings-pick` `stream` `table` `tabs` `testing` `text-inputs` `time-picker`
+`timeline` `toggletip` `toolbar` `tooltip` `tree`
+
+**Check this list before you build any UI by hand.** Some needs hide behind a name you
+would not guess:
+
+| You need                                   | Read                                      |
+| ------------------------------------------ | ----------------------------------------- |
+| Bar or stacked bar chart, series legend    | `chart`                                   |
+| Line, pie, flow chart                      | `line-chart`, `pie-chart`, `sankey-chart` |
+| Progress bar, spinner                      | `loader`                                  |
+| Initials or user picture in a circle       | `avatar`                                  |
+| "No results" or empty table state          | `empty-state`                             |
+| Failed request with a retry button         | `query-error`                             |
+| Status pill, count                         | `badge`                                   |
+| Tab strip that switches a view or a filter | `tabs` (nav tabs)                         |
+| Dialog, bottom sheet, side panel           | `overlays`, `overlay-openers`             |
+| Label and value pairs                      | `description-list`                        |
+| Stepper, wizard progress                   | `progress-steps`                          |
+| Providers and styles a new app needs       | `setup`                                   |
 
 So the table guide is `{%docsBaseUrl%}/components/table`, the menu guide
-`{%docsBaseUrl%}/components/menu`, and so on. When a name isn't in that list, start at
-`{%docsBaseUrl%}/components/` and follow the sidebar rather than guessing a URL.
+`{%docsBaseUrl%}/components/menu`, and so on.
+
+That list is a snapshot. The site itself is machine-readable, so fetch rather than guess:
+
+- `{%docsBaseUrl%}/llms.txt` - every page's title and path as of the last deploy. Use it
+  when a name isn't in the list above, or to check the list hasn't drifted.
+- Append `.md` to any page URL - `{%docsBaseUrl%}/components/button.md` - to get raw
+  markdown instead of the rendered page. Prefer this over `/llms-full.txt`, which is the
+  entire site in one ~1 MB file.
 
 ## How to use them
 
@@ -59,13 +94,14 @@ So the table guide is `{%docsBaseUrl%}/components/table`, the menu guide
   `-next` prereleases should read `{%docsBaseUrl%}` and `{%sdkStorybookUrl%}` only if
   they are the matching prerelease deployments, otherwise expect drift and verify
   against the installed `.d.ts` in `node_modules/@ethlete/<lib>`.
-- **`node_modules` is the tiebreaker.** If the docs and the installed package disagree,
-  the installed type definitions win - report the drift rather than working around it.
+- **Use the SDK skills instead of searching `node_modules` ad hoc.** The installed `.d.ts`
+  files are authoritative for the public type surface this consumer can compile against.
+  Source matching that installed build is authoritative for runtime implementation details.
+  A dirty or ahead `next` checkout is not automatically source for the installed package.
+  If docs and installed types disagree, report the drift.
 - **Never treat a `subtle` namespace as public API.** Anything exposed under `subtle` is
   an unsupported escape hatch that can change without a major version.
 
 ## Related
 
-- Data fetching has its own guide: {%skill:query%}
-- Theming tokens and how to register themes: {%skill:theming%}
 - When the docs cannot answer it, read the SDK source: {%skill:sdk-source%}