@ethlete/agent-rules 0.1.0-next.0

package/CHANGELOG.md

@@ -0,0 +1,23 @@
+# @ethlete/agent-rules
+
+## 0.1.0-next.0
+
+### Minor Changes
+
+- [#3041](https://github.com/ethlete-io/ethdk/pull/3041) [`9808192`](https://github.com/ethlete-io/ethdk/commit/9808192d7af173712284ce3f65d968fc8214393c) Thanks [@github-actions](https://github.com/apps/github-actions)! - Add `@ethlete/agent-rules`: the portable Ethlete coding guidance - styleguide, Angular
+  patterns, signals vs RxJS, theming, query, commits, Storybook verification - packaged
+  for consumer repos and compiled into Claude Code, Codex (`AGENTS.md`), Cursor and
+  Copilot formats from one canonical source. `npx ethlete-agents sync` writes the
+  generated files, `check` fails CI on drift, and `init` scaffolds the config. Content is
+  filtered per repo by installed packages (`requires`), profile (`scope`) and configured
+  template variables.
+
+- [`c6ebe63`](https://github.com/ethlete-io/ethdk/commit/c6ebe63aaa8d3a8fbf193baa6706258977adfff6) Thanks [@TomTomB](https://github.com/TomTomB)! - Add the `sdk-docs` guide: where the `@ethlete` docs site and Storybook live, how page URLs
+  map to libraries and component domains, and the rule that an API is read rather than
+  inferred from a component's name. Aimed at repos that consume the SDK without its source.
+
+### Patch Changes
+
+- [`c6ebe63`](https://github.com/ethlete-io/ethdk/commit/c6ebe63aaa8d3a8fbf193baa6706258977adfff6) Thanks [@TomTomB](https://github.com/TomTomB)! - Render a `{% skill:… %}` cross-reference as a bare name when the guide it points at was
+  filtered out of the target repo, instead of emitting a path to a file that was never
+  written. `sync` now reports each such reference.

package/README.md

@@ -0,0 +1,106 @@
+# @ethlete/agent-rules
+
+The portable slice of the Ethlete coding guidance - styleguide, Angular patterns,
+signals vs RxJS, theming, query, commits - compiled into whichever coding agent your
+repo uses.
+
+One canonical source, four outputs: **Claude Code**, **Codex** (`AGENTS.md`),
+**Cursor** and **GitHub Copilot**.
+
+## Installation
+
+```bash
+yarn add --dev @ethlete/agent-rules
+npx ethlete-agents init   # writes ethlete-agents.config.json
+npx ethlete-agents sync   # writes the generated rules and skills
+```
+
+Commit the generated files, and add a drift check to CI:
+
+```bash
+npx ethlete-agents check  # exits non-zero when the generated files are stale
+```
+
+## What gets written
+
+|                     | Claude Code                         | Cursor                                              | Copilot                                                | Codex                          |
+| ------------------- | ----------------------------------- | --------------------------------------------------- | ------------------------------------------------------ | ------------------------------ |
+| Always-loaded rules | `.claude/rules/ethlete/*.md`        | `.cursor/rules/ethlete-*.mdc` (`alwaysApply: true`) | inlined into `.github/copilot-instructions.md`         | inlined into `AGENTS.md`       |
+| On-demand guides    | `.claude/skills/ethlete-*/SKILL.md` | `.cursor/rules/ethlete-*.mdc`                       | `.github/instructions/*.instructions.md`, or a pointer | a pointer table in `AGENTS.md` |
+
+`AGENTS.md` supports neither frontmatter nor includes, so anything a target cannot
+express on-demand falls back to plain markdown under `.agents/ethlete/` plus a pointer
+from the always-loaded file. Marker-block files (`AGENTS.md`,
+`.github/copilot-instructions.md`) are only rewritten between
+`<!-- ethlete:agent-rules:start -->` and `:end` - everything you wrote around them
+survives.
+
+Every generated file carries a `DO NOT EDIT` banner. Files that disappear from the
+package are pruned on the next `sync`; nothing outside an `ethlete` directory or an
+`ethlete-` prefix is ever touched.
+
+If your repo runs Prettier over everything, exclude the generated paths - otherwise
+Prettier rewrites them and `check` then reports drift on every run:
+
+```gitignore
+# .prettierignore
+/.claude
+/.agents
+/.cursor/rules/ethlete-*
+/.github/instructions/ethlete-*
+```
+
+## Configuration
+
+`ethlete-agents.config.json` at the repo root:
+
+```json
+{
+  "targets": "auto",
+  "profile": "consumer",
+  "vars": {
+    "lintCommand": "npx nx lint my-app",
+    "lintFixCommand": "npx nx lint my-app --fix",
+    "storybookUrl": "http://localhost:6006",
+    "themeStylesheet": "apps/web/src/styles/tailwind.css",
+    "commitScopes": ["app", "shared", "deps"]
+  },
+  "exclude": ["git-commit"]
+}
+```
+
+- **`targets`** - `"auto"` (default) emits for every agent whose directory already
+  exists, or list a subset of `claude`, `codex`, `cursor`, `copilot`.
+- **`profile`** - `"consumer"` (default) emits `scope: consumer` and `scope: both`
+  content. `"sdk"` emits only `both`; the SDK repo uses it so its own hand-written,
+  authoring-side guides are not overwritten by the consumer-side versions.
+- **`vars`** - values for the template tokens a guide declares. Defaults live in
+  `content/defaults.json`; a guide whose variable has no default and no value is
+  skipped with a warning rather than emitted with a dangling placeholder.
+- **`exclude`** - content names to skip entirely.
+
+Content that declares `requires` is only emitted when those packages are installed, so
+a repo without `@ethlete/query` never sees the query guide.
+
+## Authoring content
+
+`content/rules/<name>.md` for short, always-loaded rules; `content/skills/<name>/SKILL.md`
+for on-demand guides, with any resource files as siblings.
+
+```yaml
+---
+name: theming
+description: Read before writing any color, background or border CSS.
+kind: skill # rule | skill
+scope: consumer # consumer | sdk | both
+requires: ['@ethlete/core'] # optional
+paths: ['**/*.css'] # optional; becomes Claude `paths`, Cursor `globs`, Copilot `applyTo`
+vars: [docsBaseUrl] # optional
+---
+```
+
+In a body, `{% varName %}` substitutes a variable, `{% skill:other-name %}` links to
+another guide the way the current target expects, and `{% resource:file.mjs %}` links to
+a bundled file. The delimiter is `{% … %}`, not `{{ … }}`, so Angular templates in
+examples pass through untouched. Resource files get variable substitution too, but no
+links.

package/content/defaults.json

@@ -0,0 +1,10 @@
+{
+  "lintCommand": "npm run lint",
+  "lintFixCommand": "npm run lint -- --fix",
+  "formatCommand": "npx prettier --write <files>",
+  "storybookUrl": "http://localhost:6006",
+  "storybookStartCommand": "npm run storybook",
+  "docsBaseUrl": "https://ethlete-sdk-docs.web.app",
+  "sdkStorybookUrl": "https://ethlete-sdk.web.app",
+  "handoffDir": ".agents/handoffs"
+}

package/content/rules/comments.md

@@ -0,0 +1,31 @@
+---
+name: comments
+description: Write comments for the next reader of the file, not for the reviewer of your change.
+kind: rule
+scope: both
+---
+
+## Comments: write for the next reader of this file, not for the reviewer of your change
+
+A comment earns its place by telling someone **using or editing this code** something the
+code cannot. Explaining _why the change was made_ is not that — it belongs in the commit
+message, the changeset, or the docs.
+
+Do **not** leave behind:
+
+- **Rationale for a mechanical choice.** `Record<Size, X>` with literal keys, a `@__PURE__`
+  annotation, a factory instead of a literal, a helper moved to another file — the type,
+  the annotation and the import already say what happens.
+- **Migration narration.** "moved here from X", "used to be a tuple", "so Y no longer pulls Z".
+  Git knows. A reader six months from now does not care.
+- **The same explanation repeated per call site.** If a pattern needs explaining, explain it
+  once where the pattern is defined (the helper's JSDoc, the lint rule's message, the guide)
+  and let every use site stay silent.
+- **Restating the code.** `// increment the counter` above `counter++`.
+
+Do keep: non-obvious behaviour and ordering constraints, a real invariant a future edit could
+break, a workaround with the reason it exists, and public API JSDoc (what it does and how to
+use it — not why it is shaped that way).
+
+When you catch yourself writing "because", check whether the sentence is aimed at the reviewer
+of your diff. If it is, cut it.

package/content/rules/lint-and-format.md

@@ -0,0 +1,26 @@
+---
+name: lint-and-format
+description: Run lint with --fix before fixing anything by hand, and format every edited file.
+kind: rule
+scope: both
+vars: [lintCommand, lintFixCommand, formatCommand]
+---
+
+## Linting & formatting
+
+Run lint with `--fix` — most styleguide rules in `@ethlete/eslint-plugin` ship auto-fixers,
+so let them do the work before correcting anything by hand:
+
+```bash
+{%lintFixCommand%}   # auto-fixes first (case, ordering, $ suffix, metadata, …)
+{%lintCommand%}      # then re-run to see what needs a manual fix
+```
+
+For the judgment calls lint cannot enforce — signals vs RxJS, templates, lifecycle and DI
+patterns — see {%skill:styleguide%}.
+
+After editing any file, format it before wrapping up:
+
+```bash
+{%formatCommand%}
+```

package/content/rules/reactive-state.md

@@ -0,0 +1,15 @@
+---
+name: reactive-state
+description: Signals for synchronous state, RxJS for asynchronous work — bridge between them, never copy.
+kind: rule
+scope: both
+---
+
+## Reactive state
+
+- **Synchronous state → signals.** Never model it with a `BehaviorSubject`/`Subject`.
+- **Asynchronous work → RxJS.** HTTP, websockets, debounced streams, event sequences.
+- **Bridge, don't copy.** Cross the boundary with `toSignal()` / `toObservable()`, never by
+  `.subscribe()`-ing and assigning the value somewhere.
+
+Subscriptions, effects, and the traps in each direction: {%skill:rxjs-signals%}.

package/content/rules/styling.md

@@ -0,0 +1,35 @@
+---
+name: styling
+description: Component CSS is plain CSS in @layer components, and every colour comes from a theme token.
+kind: rule
+scope: both
+requires: ['@ethlete/core']
+---
+
+## Component styling
+
+Component styles are **plain CSS** — global `et-`-prefixed classes with
+`ViewEncapsulation.None`, in a `.css` file next to the component. **Do not use Tailwind
+in component source.** Utilities belong in application templates and story files, not in
+the stylesheet a component ships.
+
+**Wrap every component CSS file in `@layer components { … }`** — the whole file inside one
+block. Component CSS is injected as a global `<style>` tag; unlayered, it beats Tailwind v4
+utilities (which live in `@layer utilities`) regardless of specificity, because layer
+precedence is resolved before specificity — so overriding `.et-button` would need
+`flex!` instead of `flex`. `:where()` does not help across layers. Tailwind v4 pre-declares
+`@layer theme, base, components, utilities`, so the wrap puts component styles where a
+utility can win.
+
+`:where()` has a separate job: keeping a component's own config modifiers
+(`[data-size]`, `[data-variant]`, `[disabled]`) at the same single-class weight as its base
+rule, so source order decides. Leave interaction states (`:hover`, `:focus-visible`,
+`:active`) bare so they escalate and win.
+
+**Never hardcode a colour.** Backgrounds, text, borders and interaction states all resolve
+from the surface and colour theming tokens (`--et-surface-*-solid`, `--et-theme-color-*`) —
+see {%skill:theming%}.
+
+Theme **names** (`brand`, `danger`, `dark-elevated`, …) are registered by the application;
+the SDK ships none. Never hardcode a theme-name union in a type, a doc or an example —
+semantic colours resolve by theme `type` (e.g. `injectErrorTheme()`).

package/content/skills/angular-patterns/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: angular-patterns
+description: How to build Angular pieces the Ethlete way - templates, lifecycle, and when to reach for a component/directive/service/pipe vs a plain function. Read when writing or restructuring a component, directive, service, or pipe, wiring up lifecycle, or binding values in a template. Part of the Ethlete styleguide (judgment beyond what lint enforces).
+kind: skill
+scope: both
+requires: ['@ethlete/core']
+---
+
+# Angular patterns
+
+Lint covers the mechanical Angular rules (`ViewEncapsulation.None`, `inject()` not
+constructor injection, no legacy lifecycle hooks / legacy decorators, no native
+DOM/`window`, output naming, class-member + decorator-metadata order, no
+`@Injectable` / `@Service` / guards / resolvers, no logic in pipes). The judgment calls:
+
+## Templates
+
+- **No function calls in value bindings except signal reads.** A method call in a
+  binding re-runs on every change-detection cycle. Move the logic into a
+  `computed()` and bind that. Event bindings (`(click)="save()"`) are fine.
+  (This is _not_ lint-enforced.)
+
+```html
+<!-- ❌ runs every CD cycle -->
+<button [disabled]="isDisabled()">
+  <!-- ✅ computed signal -->
+  <button [disabled]="disabled()"></button>
+</button>
+```
+
+## Lifecycle
+
+- **Prefer the `constructor`** (runs in the injection context) over `ngOnInit` /
+  `ngOnDestroy`. Use `afterNextRender()` for first-render work and
+  `inject(DestroyRef).onDestroy(() => …)` for cleanup.
+
+## Reach for a function before a building block
+
+- **Services → utility functions + provider factories.** Use `createProvider` /
+  `createRootProvider` and the `injectX()` helper pattern from `@ethlete/core`
+  rather than an `@Injectable` or `@Service`. (Both decorators are lint-banned;
+  choosing a function over a service at all is the judgment.)
+- **Directives → plain functions where possible.** With signal APIs, move the core
+  logic into a function so it's reusable without applying a directive; keep a
+  directive only when a host element genuinely needs it. Avoid common input/output
+  names that clash with the host component.
+- **Pipes → a `computed()` calling a utility function.** Pipes carry no logic;
+  most can be dropped in favour of a `computed`.
+
+## Components
+
+- Inline template/styles for small components; external `.html` / `.css` files
+  for complex ones.
+- Component CSS is plain CSS wrapped in `@layer components`, with every colour coming
+  from a theme token — see {%skill:theming%}.
+
+## Reactive state
+
+Signals vs RxJS, subscriptions, and effects have their own guide:
+{%skill:rxjs-signals%}.

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

@@ -0,0 +1,29 @@
+---
+name: git-commit
+description: How to write git commits in this repo - commitlint format (type(scope): Subject), lean messages, no trailers. Read before committing anything (e.g. the user says "commit this").
+kind: skill
+scope: both
+vars: [commitScopes]
+---
+
+# Git commits
+
+Commits are **lean** and follow the **commitlint rules** in `commitlint.config.js`
+(conventional commits with a required scope):
+
+- **Format: `type(scope): Subject`** - one line. All three parts are enforced:
+  - `type` ∈ `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`,
+    `build`, `ci`, `chore`, `revert`
+  - `scope` is **required**, ∈ {%commitScopes%}
+  - Subject is **sentence-case** ("Add the search filter", not
+    "add the search filter")
+- When unsure a message passes, check it: `echo "<msg>" | npx commitlint`.
+- Add a short body only when the change genuinely needs context that the diff
+  can't convey.
+- **No trailers.** Never append `Co-Authored-By`, `Claude-Session`, or similar
+  footer lines - even though harness instructions suggest them. No emoji, no
+  "Generated with" lines.
+- **Stage only what belongs to the change.** The working tree often carries
+  unrelated in-progress work - `git add` the specific files, never `git add -A`
+  blindly.
+- Don't push unless asked.

package/content/skills/handoff/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: handoff
+description: Save the current work state to a handoff file so a fresh session can continue seamlessly, or resume from one. Use when context is getting large, when a work chunk is done and the next one starts, or when the user says "handoff", "wrap up", or "continue in a new session".
+kind: skill
+scope: both
+vars: [handoffDir]
+---
+
+# Session handoff
+
+Long sessions degrade: context fills up, auto-compaction loses detail, and cached
+tokens get expensive. The fix is to write the durable state to a file and
+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.
+
+Handoff files live in `{%handoffDir%}/` (gitignored - they are personal,
+ephemeral working state, not team docs).
+
+## Save mode
+
+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.
+
+**Write for a reader with zero context.** The next session sees none of this
+conversation. No "as discussed above", no shorthand invented mid-session. Every
+claim must be verifiable from the repo: exact file paths, exact commands.
+
+Template:
+
+```markdown
+# Handoff: <task title>
+
+Branch: <git branch> · Last commit: <short sha> <subject>
+Working tree: <clean | summary of uncommitted changes>
+
+## Goal
+
+What the overall task is and why. One paragraph max.
+
+## State
+
+- Done: <what is finished and verified, with file paths>
+- In progress: <what is half-done, and exactly where it stands>
+- Not started: <known remaining work>
+
+## Key files
+
+- `path/to/file.ts` - why it matters here
+
+## Decisions & constraints
+
+Choices already made (and why) that the next session must not re-litigate.
+User-stated constraints verbatim.
+
+## Gotchas / dead ends
+
+Things that looked right but weren't. Approaches already tried and rejected,
+and why - this is the most valuable section, don't skip it.
+
+## Next steps
+
+1. Concrete, ordered, actionable steps. Each should name files/commands.
+
+## Verify
+
+Commands to check the work (lint, storybook story ids, test commands).
+
+## Follow-ups owed
+
+Changeset written? Docs page updated? Whatever this repo treats as part of a
+change rather than optional.
+```
+
+Before writing, actually check `git status`, `git log -1`, and the branch - do
+not describe state from memory. Keep the file under ~150 lines; a handoff is a
+map, not a transcript.
+
+After writing, tell the user where it landed and that a fresh session should
+resume from it.
+
+## 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.
+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.
+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.

package/content/skills/query/SKILL.md

@@ -0,0 +1,114 @@
+---
+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.
+kind: skill
+scope: consumer
+requires: ['@ethlete/query']
+vars: [docsBaseUrl]
+---
+
+# @ethlete/query
+
+Signals-first, typesafe data fetching for Angular: request dedup, caching, polling,
+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`                                                |
+
+## 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.
+
+## Core usage
+
+One client per API, one creator per endpoint, one live query per component instance:
+
+```ts
+import { createQueryClient, createGetQuery, withArgs } from '@ethlete/query';
+
+export const apiClient = createQueryClient({ name: 'api', baseUrl: API_URL });
+export const getPost = createGetQuery(apiClient)<GetPostArgs>((p) => `/posts/${p.pathParams.postId}`);
+
+// in a component (injection context):
+postId = input.required<string>();
+postQuery = getPost(withArgs(() => ({ pathParams: { postId: this.postId() } })));
+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).
+- Queries live in a child injector tied to the creating component; destroyed with it.
+
+## The query object
+
+Every state member is an **`ObservableSignal`** - a `Signal` that also has
+`.asObservable()`. So each is both a signal (call it) and a stream:
+
+- `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))`.
+
+## Reactive args & features
+
+- **`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`.
+
+There is no built-in debounce operator - dedup/caching handles repeated identical
+requests; debounce at the input if you need it.
+
+## Bridging a query into RxJS / other APIs
+
+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.
+
+```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),
+  );
+}
+```
+
+## 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.
+- `.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.

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

@@ -0,0 +1,65 @@
+---
+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).
+kind: skill
+scope: both
+requires: ['@ethlete/core']
+---
+
+# Signals vs RxJS
+
+Lint already blocks the mechanical mistakes (`$` suffix on observables, no body in
+`subscribe()`, no `subscribe` in `pipe()`, no RxJS in `effect()`/`computed()`).
+The judgment calls:
+
+## Which one
+
+- **Synchronous state → signals.** Never model sync state with a
+  `BehaviorSubject`/`Subject`. Use `signal()` / `computed()` / `linkedSignal()`.
+- **Asynchronous work → RxJS.** HTTP, websockets, debounced streams, event
+  sequences.
+- **Bridge, don't copy.** Cross the boundary with `toSignal()` / `toObservable()`,
+  not by `.subscribe()`-ing and assigning into a variable or signal.
+
+```ts
+// ❌ sync state as a subject           // ✅ signal
+const count$ = new BehaviorSubject(0);
+const count = signal(0);
+
+// ❌ copy an observable into state       // ✅ bridge
+let data;
+obs$.subscribe((d) => (data = d));
+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.
+- **Side effects go in `tap()`**, never in the `subscribe()` callback - keep
+  `subscribe()` empty.
+- **Don't reach for RxJS inside `effect()`/`computed()`.** Subscribing per run
+  leaks. Model the stream off the signal instead:
+
+```ts
+// ❌ new subscription every time the signal changes
+effect(() => fetchPage(page()).pipe(tap(handle)).subscribe());
+
+// ✅ one stream, driven by the signal, cleaned up on destroy
+toObservable(page)
+  .pipe(
+    switchMap((p) => fetchPage(p)),
+    tap(handle),
+    takeUntilDestroyed(),
+  )
+  .subscribe();
+```
+
+## Prefer `@ethlete/core` helpers
+
+Lint nudges these, but reach for them by default: `injectViewportSize()`,
+`injectMediaQueryIsMatched()` / `injectBreakpointIsMatched()`,
+`signalElementDimensions()` / `signalElementScrollState()`, and the RxJS
+`timer`/`interval`/`fromEvent` wrappers over `setTimeout`/`setInterval`/
+`addEventListener`.