npm - @ethlete/agent-rules - Versions diffs - 0.1.0-next.1 → 0.1.0-next.11 - Mend

@ethlete/agent-rules 0.1.0-next.1 → 0.1.0-next.11

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (121) hide show

package/CHANGELOG.md +101 -0
package/README.md +296 -21
package/content/git-hooks/post-checkout.sh +10 -0
package/content/git-hooks/pre-push.sh +5 -0
package/content/hooks/context-warning.py +284 -69
package/content/output-styles/ste-clarity.md +131 -0
package/content/rules/comments.md +50 -20
package/content/skills/angular-patterns/SKILL.md +1 -1
package/content/skills/api-source/SKILL.md +118 -0
package/content/skills/figma-export/SKILL.md +193 -0
package/content/skills/figma-export/dump-figma-layers.py +83 -0
package/content/skills/figma-export/dump-figma-svg.py +235 -0
package/content/skills/figma-export/measure-template.mjs +87 -0
package/content/skills/git-commit/SKILL.md +6 -7
package/content/skills/git-flow/SKILL.md +87 -0
package/content/skills/handoff/SKILL.md +4 -0
package/content/skills/query/SKILL.md +23 -13
package/content/skills/rxjs-signals/SKILL.md +1 -1
package/content/skills/sdk-docs/SKILL.md +10 -2
package/content/skills/sdk-local-build/SKILL.md +115 -0
package/content/skills/sdk-source/SKILL.md +133 -0
package/content/skills/styleguide/STYLEGUIDE.md +2 -2
package/content/skills/theming/SKILL.md +14 -7
package/content/skills/timetrack/SKILL.md +66 -0
package/package.json +12 -1
package/src/index.js +23 -10
package/src/index.js.map +1 -1
package/src/lib/commitlint.d.ts +10 -0
package/src/lib/commitlint.js +51 -0
package/src/lib/commitlint.js.map +1 -0
package/src/lib/config.d.ts +35 -6
package/src/lib/config.js +26 -3
package/src/lib/config.js.map +1 -1
package/src/lib/git-flow/build.d.ts +35 -0
package/src/lib/git-flow/build.js +24 -0
package/src/lib/git-flow/build.js.map +1 -0
package/src/lib/git-flow/config.d.ts +59 -0
package/src/lib/git-flow/config.js +50 -0
package/src/lib/git-flow/config.js.map +1 -0
package/src/lib/git-flow/index.d.ts +6 -0
package/src/lib/git-flow/index.js +10 -0
package/src/lib/git-flow/index.js.map +1 -0
package/src/lib/git-flow/parse.d.ts +49 -0
package/src/lib/git-flow/parse.js +274 -0
package/src/lib/git-flow/parse.js.map +1 -0
package/src/lib/git-flow/rename.d.ts +24 -0
package/src/lib/git-flow/rename.js +70 -0
package/src/lib/git-flow/rename.js.map +1 -0
package/src/lib/git-flow/start.d.ts +49 -0
package/src/lib/git-flow/start.js +57 -0
package/src/lib/git-flow/start.js.map +1 -0
package/src/lib/git-flow/validate.d.ts +34 -0
package/src/lib/git-flow/validate.js +72 -0
package/src/lib/git-flow/validate.js.map +1 -0
package/src/lib/git-flow-command.d.ts +4 -0
package/src/lib/git-flow-command.js +157 -0
package/src/lib/git-flow-command.js.map +1 -0
package/src/lib/git-flow-repair.d.ts +17 -0
package/src/lib/git-flow-repair.js +146 -0
package/src/lib/git-flow-repair.js.map +1 -0
package/src/lib/git-flow-start.d.ts +20 -0
package/src/lib/git-flow-start.js +132 -0
package/src/lib/git-flow-start.js.map +1 -0
package/src/lib/git.d.ts +27 -0
package/src/lib/git.js +49 -0
package/src/lib/git.js.map +1 -0
package/src/lib/gitlab.d.ts +35 -0
package/src/lib/gitlab.js +98 -0
package/src/lib/gitlab.js.map +1 -0
package/src/lib/index.d.ts +1 -0
package/src/lib/index.js +1 -0
package/src/lib/index.js.map +1 -1
package/src/lib/output-style-command.d.ts +3 -0
package/src/lib/output-style-command.js +69 -0
package/src/lib/output-style-command.js.map +1 -0
package/src/lib/output-style.d.ts +38 -0
package/src/lib/output-style.js +126 -0
package/src/lib/output-style.js.map +1 -0
package/src/lib/owned-paths.js +19 -1
package/src/lib/owned-paths.js.map +1 -1
package/src/lib/plan.d.ts +0 -1
package/src/lib/plan.js +83 -9
package/src/lib/plan.js.map +1 -1
package/src/lib/prompt.d.ts +8 -0
package/src/lib/prompt.js +27 -0
package/src/lib/prompt.js.map +1 -0
package/src/lib/render.d.ts +20 -2
package/src/lib/render.js +31 -8
package/src/lib/render.js.map +1 -1
package/src/lib/sync.d.ts +0 -1
package/src/lib/sync.js +2 -2
package/src/lib/sync.js.map +1 -1
package/src/lib/targets/claude-hooks.d.ts +1 -23
package/src/lib/targets/claude-hooks.js +15 -84
package/src/lib/targets/claude-hooks.js.map +1 -1
package/src/lib/targets/claude.js +1 -1
package/src/lib/targets/claude.js.map +1 -1
package/src/lib/targets/codex-hooks.d.ts +12 -0
package/src/lib/targets/codex-hooks.js +33 -0
package/src/lib/targets/codex-hooks.js.map +1 -0
package/src/lib/targets/codex.js +1 -1
package/src/lib/targets/codex.js.map +1 -1
package/src/lib/targets/copilot.js +1 -1
package/src/lib/targets/copilot.js.map +1 -1
package/src/lib/targets/cursor.js +1 -1
package/src/lib/targets/cursor.js.map +1 -1
package/src/lib/targets/git-hooks.d.ts +24 -0
package/src/lib/targets/git-hooks.js +70 -0
package/src/lib/targets/git-hooks.js.map +1 -0
package/src/lib/targets/hooks-shared.d.ts +37 -0
package/src/lib/targets/hooks-shared.js +95 -0
package/src/lib/targets/hooks-shared.js.map +1 -0
package/src/lib/targets/shared.d.ts +0 -1
package/src/lib/targets/shared.js +1 -1
package/src/lib/targets/shared.js.map +1 -1
package/src/lib/timetrack-command.d.ts +11 -0
package/src/lib/timetrack-command.js +199 -0
package/src/lib/timetrack-command.js.map +1 -0
package/src/lib/timetrack.d.ts +86 -0
package/src/lib/timetrack.js +112 -0
package/src/lib/timetrack.js.map +1 -0

package/content/skills/figma-export/measure-template.mjs ADDED Viewed

@@ -0,0 +1,87 @@
+/**
+ * Measure real rendered geometry against the numbers in a Figma export.
+ *
+ * Copy into a scratch directory next to a `styles.css` copied out of a production build,
+ * replace MARKUP / WIDTHS / DESIGN / probe(), then `node measure-template.mjs`.
+ */
+import { createRequire } from 'node:module';
+import { writeFileSync } from 'node:fs';
+// This runs from a scratch directory, so Playwright cannot be resolved by name — point
+// createRequire at the repo root. Playwright is CommonJS; a named import fails.
+const REPO_ROOT = '/absolute/path/to/repo'; // <-- change me
+const { chromium } = createRequire(`${REPO_ROOT}/`)('playwright');
+/** One instance of the thing under test. Keep the real component classes verbatim. */
+const MARKUP = (id) => `
+  <div id="${id}-card" class="…">
+    <h4 id="${id}-title" class="…">Some realistically long label</h4>
+  </div>`;
+/** Container widths to probe, taken from the export's frames — not from viewport breakpoints. */
+const WIDTHS = [956, 640];
+/** What the export says each width should produce. */
+const DESIGN = {
+  956: { cols: 4, cardW: 219, cardH: 60 },
+  640: { cols: 3, cardW: 192, cardH: 60 },
+};
+// Column, never row: in a flex row the harness items shrink, and container queries then
+// report results for a width the component would never actually see.
+const page = (blocks) => `<!doctype html><html class="et-surface--dark"><head><meta charset="utf-8">
+<link rel="stylesheet" href="./styles.css"></head>
+<body class="et-surface--dark" style="margin:0;padding:24px;display:flex;flex-direction:column;gap:24px;align-items:flex-start">
+${blocks}
+</body></html>`;
+const block = (width) => `<div id="w${width}" class="@container" style="width:${width}px">
+  <div class="…">${MARKUP(`w${width}`)}</div>
+</div>`;
+// page.setContent() renders on about:blank, which blocks file:// subresources — the
+// stylesheet would silently never load. Write a real file and navigate to it.
+writeFileSync('harness.html', page(WIDTHS.map(block).join('\n')));
+const browser = await chromium.launch();
+const tab = await browser.newPage({ viewport: { width: 1200, height: 900 }, deviceScaleFactor: 2 });
+await tab.goto(`file://${process.cwd()}/harness.html`);
+await tab.waitForTimeout(300);
+const measured = await tab.evaluate((widths) => {
+  const round = (value) => Math.round(value * 100) / 100;
+  const box = (id) => document.getElementById(id).getBoundingClientRect();
+  const font = (id) => getComputedStyle(document.getElementById(id));
+  return widths.map((width) => {
+    const card = box(`w${width}-card`);
+    const title = font(`w${width}-title`);
+    return {
+      width,
+      cardW: round(card.width),
+      cardH: round(card.height),
+      titleInset: round(box(`w${width}-title`).left - card.left),
+      fontSize: title.fontSize,
+      lineHeight: title.lineHeight,
+      letterSpacing: title.letterSpacing,
+    };
+  });
+}, WIDTHS);
+let failures = 0;
+for (const row of measured) {
+  const want = DESIGN[row.width];
+  const ok = Math.abs(row.cardW - want.cardW) < 1 && Math.abs(row.cardH - want.cardH) < 0.5;
+  if (!ok) failures++;
+  console.log(`${String(row.width).padStart(4)}px | ${ok ? 'OK ' : 'BAD'} |`, row);
+}
+console.log(failures === 0 ? '\nALL GEOMETRY MATCHES' : `\n${failures} MISMATCHES`);
+await tab.screenshot({ path: 'verify.png', fullPage: true });
+await browser.close();

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

@@ -1,23 +1,22 @@
 ---
 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").
+description: How to write git commits in this repo - conventional 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]
+vars: [commitScopes, commitRuleSource, commitValidation]
 ---
 # Git commits
-Commits are **lean** and follow the **commitlint rules** in `commitlint.config.js`
-(conventional commits with a required scope):
+Commits are **lean** and follow {%commitRuleSource%}:
-- **Format: `type(scope): Subject`** - one line. All three parts are enforced:
+- **Format: `type(scope): Subject`** - one line, all three parts required:
   - `type` ∈ `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`,
     `build`, `ci`, `chore`, `revert`
-  - `scope` is **required**, ∈ {%commitScopes%}
+  - `scope` ∈ {%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`.
+- {%commitValidation%}
 - 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

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

@@ -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
+npx ethlete-agents git-flow start FIP-2178        # reads the issue, names it, branches off the right base
+npx ethlete-agents git-flow check                 # is the current branch conforming?
+npx ethlete-agents git-flow explain <branch>      # what the parser sees, and what it expects
+npx 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 - see the `timetrack` skill. 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. See {%skill:git-commit%}.

package/content/skills/handoff/SKILL.md CHANGED Viewed

@@ -15,6 +15,10 @@ 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.
+This skill is installed as `ethlete-handoff`, so under Claude Code the commands
+are `/ethlete-handoff` and `/ethlete-handoff resume [name]` - there is no
+`/handoff`. Name them that way whenever you tell the user what to run.
 Handoff files live in `{%handoffDir%}/` (gitignored - they are personal,
 ephemeral working state, not team docs).

package/content/skills/query/SKILL.md CHANGED Viewed

@@ -16,17 +16,17 @@ paged queries, bearer auth, GraphQL, and a socket.io realtime client.
 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`                                                |
+| 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`, `withLongPolling`, `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
@@ -77,9 +77,19 @@ raw `toObservable`). It emits `null` first - `pipe(filter(r => r !== null))`.
 - **`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).
+  (`withArgs(() => ({ queryParams: { search: this.search() } }))`). Return `null`
+  to park the query - args reset to `null`, pausing polling/auto-refresh.
+- **Prefer `withArgs` over passing `args` to `execute()`.** Args declared on the query
+  stay reactive: a `GET` re-executes itself when they change, and `withPolling` /
+  `withAutoRefresh` restart off the same signal - none of which happens for args handed
+  to `execute()`. A function route additionally throws without it. With `withArgs` in
+  place a mutation is just `.execute()`, which reuses the current `args()`. Reserve
+  `execute({ args })` for a one-off payload no signal holds (a form submit).
 - `withPolling({ interval })`, `withAutoRefresh({ onSignalChanges: [...] })`.
+- **`withLongPolling({ nextArgs })`** for a completion-driven chain instead of an interval: each
+  round starts once the previous settled, with args (a cursor) derived from its response. `nextArgs`
+  returning `null` ends the chain. Not `withPolling` with a small interval - and the two throw when
+  combined.
 - Side-effects: `withSuccessHandling`, `withErrorHandling`, `withLogging`.
 There is no built-in debounce operator - dedup/caching handles repeated identical

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

@@ -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']

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

@@ -43,8 +43,15 @@ Component domains under `/components/`:
 `tabs` `text-inputs` `time-picker` `toggletip` `tooltip`
 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
@@ -68,3 +75,4 @@ So the table guide is `{%docsBaseUrl%}/components/table`, the menu guide
 - 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%}

package/content/skills/sdk-local-build/SKILL.md ADDED Viewed

@@ -0,0 +1,115 @@
+---
+name: sdk-local-build
+description: Build the @ethlete SDK from a local ethlete-sdk checkout and install it into this repo through a `file:` dependency, so an unreleased SDK change can be tested against this app before it is published - and reverted cleanly afterwards. Read whenever an SDK-side fix needs verifying here, or when package.json already points at a local build.
+kind: skill
+scope: consumer
+---
+# Testing an unreleased SDK build in this repo
+Swapping an `@ethlete/*` dependency for a locally built one lets you verify an SDK
+change against this app before it ships. It is a **temporary, local-only** state: the
+`file:` specifier and the lockfile entry it produces must never be committed.
+Prefer a published prerelease when one exists - installing `@ethlete/components@next`
+is faster and reproducible for the whole team. Use a local build when the change is not
+published yet, or when you are iterating on it.
+## 1. Prerequisites
+- The checkout path comes from `sdkSourcePath` in `ethlete-agents.config.local.json`;
+  {%skill:sdk-source%} covers resolving it and what to check before trusting it.
+- The checkout has its dependencies installed (`yarn install` in the checkout root - the
+  SDK repo is a Yarn 4 workspace).
+- Check which branch it is on before building - unless the user said otherwise, that
+  should be `next`, up to date with `origin/next`. Building `main` when your app runs
+  `-next` prereleases swaps in a completely different API surface, and building a stale
+  `next` rebuilds a bug that is already fixed upstream. Ask before changing its branch.
+## 2. Build the libraries you changed
+From the **checkout root**, one build per `@ethlete/*` package whose source you touched:
+```bash
+npx nx build components   # writes dist/libs/components
+npx nx build query        # writes dist/libs/query
+```
+Each build also builds the libs it depends on (`types` → `core` → `query` →
+`components`), so a single command is enough to produce a consistent set. Only the
+packages you actually changed need to be installed here; leave the rest on their
+published versions.
+If a build stalls trying to reach Nx Cloud, re-run it with `NX_NO_CLOUD=true`.
+## 3. Point this repo at the build
+Edit the version specifiers in `package.json` (the one declaring the dependency - in a
+workspace that is the workspace package, not necessarily the root):
+```json
+{
+  "dependencies": {
+    "@ethlete/components": "file:../ethlete-sdk/dist/libs/components"
+  }
+}
+```
+The path is resolved relative to that `package.json`; an absolute path works too. Then
+install:
+```bash
+yarn install
+```
+Expect peer-dependency warnings - the built package pins peers to the SDK's own Angular
+version. They are warnings, not failures; a real version conflict shows up as a build
+error, and means the checkout is on the wrong branch.
+## 4. Confirm the local build is really what got installed
+`yarn install` is the only thing that copies the build into `node_modules`, so verifying
+is not optional - a stale package looks exactly like a change that did not work:
+```bash
+grep -m1 '"version"' node_modules/@ethlete/components/package.json
+rg -n "<a symbol from your change>" node_modules/@ethlete/components/fesm2022/
+```
+Then **restart the dev server**. Bundlers pre-bundle dependencies and will keep serving
+the old copy; if the change still does not show up, delete `.angular/cache` (and
+`node_modules/.vite` if present) and start it again.
+## 5. Iterating
+Every SDK edit needs the full loop - there is no watch mode across the boundary:
+1. rebuild in the checkout (`npx nx build <lib>`)
+2. `yarn install` here
+3. restart the dev server
+Yarn 4 re-copies a `file:` dependency whenever its contents change, so step 2 does pick
+up the rebuild. It also rewrites that package's `resolution` hash in `yarn.lock` on
+every rebuild - which is one more reason the lockfile must not be committed in this
+state. (With npm, `file:` symlinks instead of copying, so a rebuild is picked up without
+reinstalling; the restart in step 3 is still required.)
+## 6. Clean up when you are done
+Leaving a `file:` dependency behind breaks every other checkout and CI, because the path
+does not exist there. Restore it as part of the same task, not later:
+```bash
+git checkout package.json   # or hand-restore the original version specifier
+yarn install
+git status --short          # package.json and yarn.lock must both be clean
+```
+Never commit a `file:` specifier or the lockfile it produced. If the verified fix is
+still unreleased, say what has to be published (which lib, which version) instead of
+shipping a local path.
+## Related
+- Finding and reading the checkout: {%skill:sdk-source%}
+- What the published packages document: {%skill:sdk-docs%}

package/content/skills/sdk-source/SKILL.md ADDED Viewed

@@ -0,0 +1,133 @@
+---
+name: sdk-source
+description: How to read the @ethlete SDK's own source from a local ethlete-sdk checkout when the docs and the installed types are not enough. Read when you need an implementation detail, the exact behaviour behind a bug, or an API the docs do not cover - and never edit that checkout as part of work in this repo.
+kind: skill
+scope: consumer
+vars: [docsBaseUrl]
+---
+# Reading the @ethlete SDK source
+The SDK is developed in a separate repository (`ethlete-sdk`). Most questions are
+answered faster and more reliably by the documentation - read {%skill:sdk-docs%}
+first. Reach for the source when the docs genuinely cannot answer the question:
+- a behaviour looks like an SDK bug and you need to see what the code actually does
+- you need an implementation detail the guides omit (event order, internal defaults,
+  which host directive writes which attribute)
+- the installed version is ahead of - or behind - the published docs and you have to
+  confirm what the code in _this_ version does
+- you are about to report or fix something in the SDK itself
+## 1. Resolve the checkout
+The path is per machine, so it lives in the gitignored `ethlete-agents.config.local.json`
+at the repo root:
+```json
+{
+  "sdkSourcePath": "/absolute/path/to/ethlete-sdk"
+}
+```
+Read that file before searching anywhere. A relative path is resolved from the repo root.
+If the file or the key is missing, **do not guess a path** and do not clone the
+repository. Fall back to the installed package - `node_modules/@ethlete/<lib>/types/`
+holds the full `.d.ts` surface of exactly the version this repo runs - and to
+{%docsBaseUrl%}. Then tell the user a local checkout would help, and offer the snippet
+above (the file is gitignored, so adding it changes nothing for anyone else).
+## 2. Check the branch before you read anything
+A checkout sits on whatever branch the developer left it on, so the first command you
+run against it is the one that tells you what you are looking at:
+```bash
+git -C <sdkSourcePath> fetch --quiet          # read-only, safe
+git -C <sdkSourcePath> status -sb             # branch, ahead/behind, dirty files
+```
+**Unless the user says otherwise, the expected state is `next`, up to date with
+`origin/next`.** That is the branch the SDK develops on, and the one the `-next`
+prereleases are cut from. Anything else and you are reading a different SDK than the
+one you are about to describe.
+When it is not in that state, **say so and ask** - never switch, pull, stash or reset
+it yourself. It is someone's working tree, and the read-only rule below applies:
+- **On another branch** - name it and ask whether to read it as-is or whether they want
+  `next`. A feature branch may be exactly what you were sent to look at.
+- **Behind `origin/next`** - report how far. The code you would quote may already be
+  fixed upstream, so read the missing commits before calling anything a bug:
+  `git -C <sdkSourcePath> log --oneline HEAD..origin/next`.
+- **Dirty** - it may contain someone's work in progress. Say so rather than quoting it
+  as SDK behaviour.
+## 3. Check the checkout matches what is installed
+Even on a clean `next`, the checkout can be months of work ahead of the installed
+package - or behind it:
+```bash
+grep '"@ethlete/' package.json                                 # what this repo runs
+grep -m1 '"version"' <sdkSourcePath>/libs/<lib>/package.json   # what the checkout is at
+```
+Rules when they differ:
+- **The installed package wins** for anything about how this repo behaves today. The
+  `.d.ts` in `node_modules` is the truth about the API you are calling.
+- Source that is ahead describes an **unreleased** API. Never write consumer code
+  against it, and never assume it is available - say what release it needs.
+## 4. Where things live
+Paths are relative to the checkout root:
+| Path                                | What is in it                                                               |
+| ----------------------------------- | --------------------------------------------------------------------------- |
+| `libs/components/src/lib/<domain>/` | The active UI library, one folder per domain (`button`, `menu`, `table`, …) |
+| `libs/core/src/lib/`                | Framework primitives: directives, signal utils, overlay runtime, theming    |
+| `libs/query/src/lib/`               | Data fetching: `http`, `gql`, `ws`, auth, query-form                        |
+| `libs/types/src/lib/`               | Shared types                                                                |
+| `libs/cdk/`                         | The predecessor UI toolkit, maintenance mode - only for code still on it    |
+| `libs/eslint-plugin/src/`           | The lint rules, including the message text explaining each one              |
+| `apps/docs/`                        | The markdown behind {%docsBaseUrl%}                                         |
+| `apps/storybook/`                   | The Storybook app - stories also live next to each component                |
+Inside a component domain: `<name>.component.ts` with its `.css` next to it,
+`<name>.imports.ts` (the imports array to spread into a consumer component),
+`headless/` for the unstyled directives, `stories/` for the Storybook stories, and
+`index.ts` as the barrel. The lib's public surface is `libs/<lib>/src/index.ts` -
+anything not re-exported from there is internal, whatever it looks like.
+## 5. Search it, don't read it whole
+```bash
+rg -n "etButton" <sdkSourcePath>/libs/components/src --glob '!*.spec.ts'   # a selector
+rg -n "export const OVERLAY" <sdkSourcePath>/libs/core/src                 # an export
+rg -n "menu" <sdkSourcePath>/apps/docs/components                          # the guide source
+```
+Specs are the cheapest description of intended behaviour - `<name>.component.spec.ts`
+next to a component usually answers "is this supposed to happen?" faster than the
+implementation does.
+## 6. The checkout is read-only from here
+It is a different repository with its own branch, lint, docs and changeset workflow.
+Never edit it while working on a task in this repo - that covers its git state too, so
+no `checkout`, `pull`, `stash` or `reset` without the user asking for it (`fetch` is
+fine). Never copy its internals into consumer code either - a private helper is not a
+supported API and disappears without a major version (the same goes for anything under
+a `subtle` namespace).
+When the fix belongs in the SDK, say so and describe it precisely: file, symbol, and
+the behaviour it should have. If the user wants that fix verified against this app
+before it ships, that is {%skill:sdk-local-build%}.
+## Related
+- Docs and Storybook, which come first: {%skill:sdk-docs%}
+- Testing an unreleased SDK build here: {%skill:sdk-local-build%}

package/content/skills/styleguide/STYLEGUIDE.md CHANGED Viewed

@@ -37,7 +37,7 @@ Run your lint task with `--fix` - the rules below are enforced (and mostly auto-
 | Max two function parameters                                                                                                       | `max-params`                                                                                                                                                                                                        |
 | No `import type` / inline `type` specifiers                                                                                       | `ethlete/no-type-only-import`                                                                                                                                                                                       |
 | Generic params `T`-prefixed (`TValue`), never bare `T`                                                                            | `@typescript-eslint/naming-convention`                                                                                                                                                                              |
-| No `async`/`await` - use RxJS                                                                                                     | `no-restricted-syntax`                                                                                                                                                                                              |
+| No `async`/`await` - use RxJS                                                                                                     | `ethlete/no-async-await`                                                                                                                                                                                            |
 | Arrow fns standalone; methods in classes; no arrow-fn class props; no `function` keyword                                          | `no-restricted-syntax`                                                                                                                                                                                              |
 | Blank line before `return` in multi-line guard clauses                                                                            | `ethlete/guard-return-newline`                                                                                                                                                                                      |
 | No trivially-inferable explicit return types                                                                                      | `ethlete/no-trivial-return-type`                                                                                                                                                                                    |
@@ -463,7 +463,7 @@ settings-form/
 - **Do not** create a changeset for irrelevant changes (e.g., formatting, comments, internal refactoring).
 - **Do not** create a changeset for fixes to features that have not yet been released.
 - **Do not** include multiple changes in a single changeset. Each changeset should contain only one change.
-- **Always** start a changeset with at least one sentence describing the change. Optional follow-up markdown can be added after the initial sentence.
+- **A changeset note is a TL;DR: one sentence, two at most, under 40 words.** Never a second paragraph, no matter how much work the change took. It is the line a consumer skims to decide whether the release affects them - not a summary of your work. Mechanism, API inventories, caveats and rationale belong in the docs or the commit body, never here.
 - Create changesets for dependency updates if they are relevant to the project (e.g., major version updates).
 - Write changesets in the imperative mood. For example:
   - Add button component

package/content/skills/theming/SKILL.md CHANGED Viewed

@@ -1,6 +1,6 @@
 ---
 name: theming
-description: The two runtime theming systems in @ethlete/core - surface theming (elevation-aware neutrals) and color theming (semantic accent palettes) - how to register them in an app and how components must consume them. Read BEFORE writing or reviewing CSS that involves any color, background, border, or interaction state, and when wiring theme context across overlay/portal boundaries.
+description: The two runtime theming systems in @ethlete/core - surface theming (elevation-aware neutrals) and color theming (semantic accent palettes). Read BEFORE writing or reviewing CSS involving color, background, border, or interaction state, and when wiring theme context across overlay/portal boundaries.
 kind: skill
 scope: consumer
 requires: ['@ethlete/core']
@@ -61,12 +61,12 @@ Surface (each exists as `-solid` = usable color, `-rgb` = `R G B` channels):
 Color (from the nearest `[etProvideColor]` scope):
-| Token                            | Use for                                                                                                                                |
-| -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
-| `--et-theme-color-primary`       | filled backgrounds; **opacity-aware** - set `--et-theme-color-primary-opacity: 0.16` etc. per state to tint without changing the color |
-| `--et-theme-color-primary-solid` | accents at full strength: focus borders, selected marks, spinners                                                                      |
-| `--et-theme-color-on-primary`    | text/icons on a primary-filled background                                                                                              |
-| `--et-theme-color-ink-solid`     | primary-tinted text/border on transparent/tonal fills                                                                                  |
+| Token                            | Use for                                                                                                                                                                                                                                                                                                                                                             |
+| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--et-theme-color-primary`       | filled backgrounds on an element you do **not** tint. To tint per state, set `--et-theme-color-primary-opacity: 0.16` and compose the color yourself: `rgb(var(--et-theme-color-primary-rgb) / var(--et-theme-color-primary-opacity))`. The alias is substituted at the `et-color--*` scope, so an inherited value carries the scope's opacity, never the element's |
+| `--et-theme-color-primary-solid` | accents at full strength: focus borders, selected marks, spinners                                                                                                                                                                                                                                                                                                   |
+| `--et-theme-color-on-primary`    | text/icons on a primary-filled background                                                                                                                                                                                                                                                                                                                           |
+| `--et-theme-color-ink-solid`     | primary-tinted text/border on transparent/tonal fills                                                                                                                                                                                                                                                                                                               |
 Interaction-state variants (`--et-surface-interaction-{hover,focus,active,disabled}-solid`)
 resolve automatically per CSS state when the element has `[etSurfaceInteractive]`;
@@ -96,6 +96,13 @@ the interactive element itself, never on a wrapper.
   declared via `@property` can never default to a theme token. If the default should
   come from the theme, don't declare an `@property` - consume the theme token directly
   (optionally behind a `--_et-*` indirection var).
+- `@property` `initial-value` also cannot use a **font-relative or container unit**
+  (`em`, `rem`, `ex`, `ch`, `lh`, `cap`, `ic`, `cq*`). The value must be computationally
+  independent, so the browser drops the whole rule and leaves the token unregistered -
+  with no error. Percentages and viewport units (`vh`, `vw`, `dvh`) are fine. When the
+  default has to be relative, use `syntax: '*'` with no `initial-value` and put the
+  default in a fallback at each use site: `var(--et-skeleton-size, 1em)`.
+  `yarn lint:css-properties` checks this, and pre-commit runs it on staged files.
 - `--et-theme-color-primary-*` always resolves to the **nearest color scope**. A
   hardcoded semantic color in CSS can't be replaced by it unless the right theme is
   provided on that element.