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

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @ethlete/agent-rules
 
+## 0.1.0-next.12
+
+### Patch Changes
+
+- [#3069](https://github.com/ethlete-io/ethdk/pull/3069) [`a258308`](https://github.com/ethlete-io/ethdk/commit/a258308e0753eb65d08b3d7fb9a9f14507229047) Thanks [@github-actions](https://github.com/apps/github-actions)! - Agent rules: make generated guidance safer, reference-aware, example-validated, and cheaper to load.
+
+- [#3069](https://github.com/ethlete-io/ethdk/pull/3069) [`973462e`](https://github.com/ethlete-io/ethdk/commit/973462ebb9ec7c2eef1aca3fc9f01615824d0074) Thanks [@github-actions](https://github.com/apps/github-actions)! - Agent rules: warn about unknown exclusions and apply Codex model-specific long-context pricing limits in the context warning hook.
+
 ## 0.1.0-next.11
 
 ### Patch Changes

package/README.md

@@ -111,7 +111,10 @@ Prettier rewrites them and `check` then reports drift on every run:
   convention and never mentions a `commitlint` run - an agent that goes looking for a
   promised validator and finds nothing reports the discrepancy instead of just
   committing. Setting either one in `vars` overrides the detection.
-- **`exclude`** - content names to skip entirely.
+- **`exclude`** - rule or skill names to skip entirely for every configured agent and
+  developer. For example, `"exclude": ["git-flow", "handoff"]` prevents those skills
+  from being generated; the next `sync` also removes copies generated previously. Unknown
+  names produce a warning so a typo cannot silently leave a skill enabled.
 - **`claudeMdImportsAgentsMd`** - set (usually by `migrate`) when `CLAUDE.md` is an
   `@AGENTS.md` import or symlink; the claude target then skips `.claude/rules/ethlete/`
   so the rules don't load twice. `sync` warns when the flag is set but the import is
@@ -298,9 +301,9 @@ Available hooks:
   context crosses 70% / 85% of the token budget, recommending a handoff. Under Claude the
   budget is capped at the 200k long-context pricing boundary: on 1M-window models every
   request past 200k input tokens bills the whole context at a premium rate, so the
-  warnings fire at ~140k/~170k instead of deep into the expensive range. Codex has no
-  such boundary, so its budget is the model's own reported context window and the
-  warnings are pure occupancy.
+  warnings fire at ~140k/~170k instead of deep into the expensive range. Codex uses
+  the model-specific 272k pricing boundary for GPT-5.6, GPT-5.5 and GPT-5.4, and the
+  rollout's reported context window for models without that pricing rule.
 
   Two things are Claude-only: the separate user-facing line (Codex documents only
   `additionalContext`, so there the warning is folded into the text the model is told to
@@ -397,7 +400,8 @@ differ per developer, without touching any committed file:
 {
   "disableHooks": true,
   "sdkSourcePath": "/absolute/path/to/ethlete-sdk",
-  "apiRepoPaths": { "hub": "../fut-hub-backend" }
+  "apiRepoPaths": { "hub": "../fut-hub-backend", "*": "../shared-backend" },
+  "apiRepoBranches": { "hub": "develop", "*": "main" }
 }
 ```
 
@@ -414,15 +418,18 @@ differ per developer, without touching any committed file:
 - **`apiRepoPaths`** - one checkout per app, keyed by the app's project name
   (`{ "hub": "../fut-hub-backend" }`). The `api-source` skill reads it to confirm a
   response shape, a status code or an enum in the API's own source instead of guessing it
-  from the client. Relative paths resolve from the repo root; a map with a single entry is
-  used for whatever app is in play.
+  from the client. Relative paths resolve from the repo root. Matching is exact; use the
+  explicit `"*"` key only when apps intentionally share a checkout.
+- **`apiRepoBranches`** - the expected backend branch per app. It uses the same exact-key
+  and explicit `"*"` fallback rules. Omit it when branch identity is not part of the
+  environment contract; the source guide then treats the current branch as context.
 
 Everything in this file is read at runtime, never by `sync`: the generated files stay
 identical on every machine and in CI, which is what lets `check` diff them. That is also
 why the file takes nothing beyond these keys - `sync`/`check` warn about unknown keys,
 about an `sdkSourcePath` that is missing or is not an SDK checkout, and about an
-`apiRepoPaths` entry that is not a directory. Add the filename to your repo's
-`.gitignore`.
+`apiRepoPaths` entry that is not a directory, and invalid `apiRepoBranches` values. Add
+the filename to your repo's `.gitignore`.
 
 ## Authoring content
 
@@ -447,7 +454,10 @@ compile: it is a Claude Code output style verbatim, so its frontmatter is Claude
 as it is, apart from a marker line that records where it came from.
 
 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.
+another emitted package guide, and `{% resource:file.mjs %}` links to a bundled file.
+Skill links are required dependencies: after scope, package, variable, and exclusion
+filtering, `sync` and `check` fail with the source and missing target instead of emitting
+a dangling name. Optional guidance must be self-contained when its guide is absent. Use
+the structured marker instead of a plain `` `name` skill`` reference so validation can
+see it. The delimiter is `{% … %}`, not `{{ … }}`, so Angular templates in examples pass
+through untouched. Resource files get variable substitution too, but no links.

package/content/hooks/context-warning.py

@@ -16,11 +16,10 @@ that matter here, all captured in AGENT_PROFILES:
     carry a TokenUsageInfo. Codex's rollout format is explicitly not a stable
     interface, so the parser searches each line for the usage object instead of
     walking a fixed path.
-  * Context budget. Claude's budget is capped at the 200k long-context pricing
-    boundary: on models with a larger window, every request past that point
-    bills the entire context at the premium rate, which costs far more than
-    handing off into a fresh session ever would. Codex has no such boundary, so
-    its budget is just the window.
+  * Context budget. Claude's budget is capped at its 200k long-context pricing
+    boundary. Codex uses the model-specific pricing boundary where OpenAI
+    documents one, and the reported window otherwise. Crossing either boundary
+    costs far more than handing off into a fresh session ever would.
   * How a handoff is invoked. Claude has a slash command and /clear; Codex has
     neither and reads the skill from disk. The skill's own name differs per repo
     (`ethlete-handoff` where the generator installed it, `handoff` where the repo
@@ -63,6 +62,15 @@ CRITICAL_FRACTION = 0.85
 # context at the long-context premium rate — so the budget never exceeds it.
 PREMIUM_BOUNDARY = 200_000
 
+# Codex models whose long-context pricing starts above 272k input tokens. Models
+# without that pricing rule use their reported context window instead.
+CODEX_PREMIUM_BOUNDARIES = (
+    ("gpt-5.6", 272_000),
+    ("gpt-5.5", 272_000),
+    ("gpt-5.4-mini", None),
+    ("gpt-5.4", 272_000),
+)
+
 # Context window (tokens) per model, matched by substring against the model id
 # from the transcript — first match wins. Edit these as model windows change;
 # anything unmatched falls back to DEFAULT_WINDOW.
@@ -83,6 +91,7 @@ DEFAULT_WINDOW = 200_000
 AGENT_PROFILES = {
     "claude": {
         "premium_boundary": PREMIUM_BOUNDARY,
+        "premium_boundaries": (),
         # Claude's transcript reports no window, so it is resolved from the model id.
         "default_window": None,
         "auto_modes": ("auto",),
@@ -101,6 +110,7 @@ AGENT_PROFILES = {
     },
     "codex": {
         "premium_boundary": None,
+        "premium_boundaries": CODEX_PREMIUM_BOUNDARIES,
         # Only reached if a rollout omits model_context_window; the CONTEXT_WINDOWS table
         # holds Claude model ids and would never match a Codex one.
         "default_window": 272_000,
@@ -214,6 +224,15 @@ def window_for(model):
     return DEFAULT_WINDOW
 
 
+def premium_boundary_for(profile, model):
+    """Model-specific pricing boundary, falling back to the agent-wide value."""
+    if model:
+        for needle, boundary in profile["premium_boundaries"]:
+            if needle in model:
+                return boundary
+    return profile["premium_boundary"]
+
+
 def claude_context_state(transcript_path):
     """(tokens, model, window) from the last main-chain assistant message.
 
@@ -376,7 +395,7 @@ def main():
 
     tokens, model, reported_window = CONTEXT_READERS[agent](transcript_path)
     window = reported_window or profile["default_window"] or window_for(model)
-    boundary = profile["premium_boundary"]
+    boundary = premium_boundary_for(profile, model)
     budget = min(window, boundary) if boundary else window
     warn_tokens = int(budget * WARN_FRACTION)
     critical_tokens = int(budget * CRITICAL_FRACTION)

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

@@ -1,6 +1,6 @@
 ---
 name: lint-and-format
-description: Run lint with --fix before fixing anything by hand, and format every edited file.
+description: Run lint with --fix before fixing anything by hand, and format every edited source file Prettier supports.
 kind: rule
 scope: both
 vars: [lintCommand, lintFixCommand, formatCommand]
@@ -16,10 +16,11 @@ so let them do the work before correcting anything by hand:
 {%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%}.
+For judgment calls lint cannot enforce, load the repository's focused guidance for the
+code you are changing.
 
-After editing any file, format it before wrapping up:
+Format every edited Prettier-supported source file before wrapping up. Do not send binary,
+generated, or unsupported files to this command:
 
 ```bash
 {%formatCommand%}

package/content/rules/reactive-state.md

@@ -12,4 +12,4 @@ scope: both
 - **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%}.
+For subscriptions and effects, load the repository's focused reactive-state guidance.

package/content/rules/styling.md

@@ -1,6 +1,6 @@
 ---
 name: styling
-description: Component CSS is plain CSS in @layer components, and every colour comes from a theme token.
+description: Component CSS is plain CSS in @layer components, and hardcoded colours are never primary values.
 kind: rule
 scope: both
 requires: ['@ethlete/core']
@@ -26,10 +26,12 @@ utility can win.
 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%}.
+**Never use a hardcoded colour as the primary value.** Backgrounds, text, borders and
+interaction states resolve from the surface and colour theming tokens
+(`--et-surface-*-solid`, `--et-theme-color-*`). A static fallback inside
+`var(--token, <fallback>)` is permitted, but not required.
 
 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()`).
+the SDK ships none. Never hardcode them as an SDK-defined union or reusable API contract.
+If an app-specific example names one, label it as belonging to that app. Semantic colours
+resolve by theme `type` (e.g. `injectErrorTheme()`).

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

@@ -22,10 +22,10 @@ DOM/`window`, output naming, class-member + decorator-metadata order, no
 
 ```html
 <!-- ❌ runs every CD cycle -->
-<button [disabled]="isDisabled()">
-  <!-- ✅ computed signal -->
-  <button [disabled]="disabled()"></button>
-</button>
+<button [disabled]="isDisabled()"></button>
+
+<!-- ✅ computed signal -->
+<button [disabled]="disabled()"></button>
 ```
 
 ## Lifecycle
@@ -51,8 +51,8 @@ DOM/`window`, output naming, class-member + decorator-metadata order, no
 
 - 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%}.
+- Component CSS is plain CSS wrapped in `@layer components`, with every primary colour
+  value coming from the repository's theme tokens.
 
 ## Reactive state
 

package/content/skills/api-source/SKILL.md

@@ -31,7 +31,12 @@ app to checkout. They are per machine, so the map lives in the gitignored
 ```json
 {
   "apiRepoPaths": {
-    "hub": "../fut-hub-backend"
+    "hub": "../fut-hub-backend",
+    "*": "../shared-backend"
+  },
+  "apiRepoBranches": {
+    "hub": "develop",
+    "*": "main"
   }
 }
 ```
@@ -41,8 +46,8 @@ Read that file before searching anywhere. The rules:
 - **The key is the app** as this repo names it - the workspace project name, which is
   normally also the folder under `apps/`. Match the app you are working in.
 - **A relative path resolves from the repo root**, not from the app folder.
-- **One entry means one API.** If the map holds a single entry, use it whatever it is
-  called.
+- **Require an exact app key.** If several apps intentionally share one API, configure
+  the explicit `"*"` fallback. Never treat an unrelated single entry as a fallback.
 - **No matching entry - stop and ask.** Do not guess a sibling folder and do not clone
   the repository. Say which app you needed the API for and offer the snippet above; the
   file is gitignored, so adding it changes nothing for anyone else.
@@ -51,28 +56,32 @@ Without a checkout, fall back to what the running API tells you: the generated A
 description if the project serves one (`/openapi.json`, `/swagger`, `/api/doc`), and the
 real response body of the call you are debugging.
 
-## 2. Check the branch before you read anything
+## 2. Resolve the relevant files before judging checkout state
 
-A checkout sits on whatever branch its developer left it on, and the code you would
-quote must be the code that serves this app:
+Search by the route, field, or error you already know. Record the contract, serializer,
+handler, and tests that can answer the question. Then inspect checkout state only for
+those paths:
 
 ```bash
-git -C <apiRepoPath> fetch --quiet     # read-only, safe
-git -C <apiRepoPath> status -sb        # branch, ahead/behind, dirty files
+git -C <apiRepoPath> status -sb
+git -C <apiRepoPath> status --short -- <relevant-paths>
+git -C <apiRepoPath> diff -- <relevant-paths>
 ```
 
-**The state to expect is the API's own development branch, up to date with its remote.**
-Anything else, and you are describing a different API than the one the app calls.
+Unrelated dirty files are not evidence about these paths. Continue without blocking on
+them. If a relevant file is dirty, distinguish the worktree implementation from the
+committed or deployed behavior. Ask only when that difference changes the answer or the
+user has to choose which behavior matters.
 
-When it is not in that state, **say so and ask** - never switch, pull, stash or reset it
-yourself:
+`apiRepoBranches` configures the expected branch per exact app key, with `"*"` as the
+only fallback. If no branch is configured, report the current branch as context; do not
+invent a blocking “development branch” requirement. A different or ahead branch matters
+only when the relevant files differ in that commit range.
 
-- **On another branch** - name it and ask. A feature branch may be exactly the endpoint
-  you were sent to look at, but it is not what the app talks to today.
-- **Behind its remote** - report how far. The behaviour you are about to call a bug may
-  already be fixed upstream.
-- **Dirty** - it holds someone's work in progress. Say so rather than quoting it as API
-  behaviour.
+Use existing remote refs first. `git fetch` preserves the worktree but is not read-only:
+it uses the network and mutates remote refs. Fetch only when freshness is material, and
+request any approval the environment requires. Never switch, pull, stash, or reset the
+checkout yourself.
 
 ## 3. The checkout is not the environment the app calls
 
@@ -111,7 +120,7 @@ they name the status code and the body for each case.
 
 It is a different repository with its own branch, review and release process. Never edit
 it while working on a task in this repo, and never change its git state without being
-asked (`fetch` is fine).
+asked. A fetch also needs to meet the freshness and approval conditions above.
 
 When the fix belongs in the API, say so precisely: the endpoint, the field, and the
 behaviour it should have. Then handle the API as it is today - a client workaround for a

package/content/skills/figma-export/SKILL.md

@@ -15,18 +15,15 @@ Three things arrive from Figma, and each answers a different question:
 | **`.css`** (Copy as CSS)  | Named layers, auto-layout properties, typography metrics, design-token names  | Any hierarchy at all — the dump is flat     |
 | **`.png`** (a screenshot) | Figma's own blue measurement overlays, and what the designer chose to frame   | Nothing machine-readable                    |
 
-**Ask for the `.svg` and the `.css` together, and do not start until you have both.** The two
-are complements, not alternatives: the SVG is the only export you can both look at and
-measure, and the CSS is the only one that names layers and records type. A PNG earns its place
-only when it is a _screenshot_ carrying dev-mode annotations — a PNG _render_ of the same frame
-adds nothing the SVG does not. None of the three tells you the colours.
-
-Say what you are missing and what it would settle, in one line — "I have the SVG; the `.css`
-export would give me the font sizes and whether these cards Hug or Fill" — and wait. Every
-number in your diff has to trace back to something in an export or to a token; a plausible
-`17px` you inferred from a 12px outlined glyph is worse than an open question, because it
-survives review as though it had been specified. If the pair genuinely cannot be produced, say
-in the write-up which numbers are therefore guesses.
+**Ask for the `.svg` and the `.css` together.** That pair is the preferred complete input:
+the SVG is the export you can look at and measure, and the CSS names layers and records
+type. A PNG earns its place only when it is a _screenshot_ carrying dev-mode annotations.
+Exports expose rendered color values, but they do not identify the authoritative semantic
+theme token.
+
+If one artifact is missing, inspect the existing code and the artifact you do have. List
+the exact facts that remain unknown and do not invent their measurements. Ask before a
+structural choice or an untraceable numeric value, not before useful read-only inspection.
 
 ## 1. Read the export before touching code
 
@@ -126,8 +123,8 @@ it; the SVG has the tree but no names. The image is what disambiguates:
 - **Authoritative:** geometry and typography metrics — widths, padding, gaps, `flex-grow`,
   border radius, font size / weight / line-height / letter-spacing, and the breakpoints at
   which the layout changes.
-- **Never authoritative: colour.** Backgrounds, text, borders and interaction states resolve
-  from the surface and colour theming tokens — see {%skill:theming%}. A hex in the
+- **Never authoritative: semantic colour choice.** Backgrounds, text, borders and
+  interaction states resolve from the repository's theme tokens. A hex in the
   export is information about the _designer's_ palette, not a value to paste. Where the
   export's colour and the token disagree, keep the token and note the delta for the design
   review; the export can be wrong about contrast in a way the tokens are not. This holds
@@ -181,13 +178,14 @@ Harness gotchas, each of which will cost you an hour:
   ~1px wide of reality, so a label that wraps in the harness may well fit in the app. Check
   before calling a wrap a defect.
 - Playwright is CommonJS and unresolvable from a scratch directory — `createRequire` against
-  the repo root, as the template does. The same applies when driving a story:
-  {%skill:verify-in-storybook%}.
+  the repo root, as the template does. When driving a story, follow the repository's
+  installed Storybook verification guidance if present.
 
 ## 5. Close the loop
 
 Report the measured numbers next to the export's, per width — not "matches the design". Say
 explicitly which parts of the export you deliberately did **not** implement and why (colour
 kept as tokens, a label the product decided never to render, a field the API lacks). Then
-delete the export files once their component is signed off, so the folder always shows only
-what is still outstanding.
+report that the export files are no longer needed. Delete only artifacts this workflow
+created and only when the workflow or user explicitly authorizes cleanup; otherwise let the
+user decide whether supplied exports remain useful records.

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

@@ -27,7 +27,7 @@ npx ethlete-agents git-flow repair <branch>       # rename a non-conforming one,
 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
+credentials. If it reports that the app is not running, ask the
 user to start it. `--subject <text>` names a branch without reading Jira at all.
 
 ## The five shapes
@@ -84,4 +84,4 @@ 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%}.
+issue key** - the branch already has it. Follow the repository's commit-message guidance.

package/content/skills/handoff/SKILL.md

@@ -94,9 +94,9 @@ resume from it.
 3. Verify reality still matches: current branch, `git status`, last commit. If
    they diverge from the handoff (e.g. someone committed in between), say what
    changed and adapt - the repo is the truth, the handoff is the guide.
-4. Read any guides the handoff's work obviously needs (e.g. {%skill:theming%}
-   before CSS work) - same rules as always.
+4. Read any focused repository guidance the handoff's work needs - 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.
+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

@@ -97,23 +97,34 @@ 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.
+For a callback that must start one request and return one correlated result, use a
+manual query with `executeUntilSettled()`. Its frozen snapshot cannot be replaced by a
+later execution, and the observable completes after that one result.
 
 ```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),
-  );
+class ItemSource {
+  private itemsQuery = getItems({ onlyManualExecution: true });
+
+  fetch(query: string) {
+    return defer(() => executeUntilSettled(this.itemsQuery, { args: { queryParams: { q: query } } })).pipe(
+      map((snapshot) => {
+        const response = snapshot.response();
+
+        if (response === null) throw snapshot.error();
+
+        return response.items;
+      }),
+    );
+  }
 }
 ```
 
+Do not set a search signal and immediately return the shared `response` stream: the
+previous response is retained during re-execution and can be the first non-null emission.
+Unsubscribing from the wrapper stops result delivery but does not by itself abort the
+promise-backed execution; use the query's reactive `withArgs` lifecycle when cancellation
+is a requirement rather than a callback contract.
+
 ## Gotchas
 
 - Signals-first: read `query.response()` in templates/computeds; it's **nullable**

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

@@ -34,9 +34,15 @@ 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.
+- **Place lifecycle teardown after higher-order operators** such as `switchMap`, so their
+  inner subscriptions are also covered. Other limiting and finalization operators do not
+  have a universal “last” position; place them where their semantics belong.
 - **Side effects go in `tap()`**, never in the `subscribe()` callback - keep
   `subscribe()` empty.
 - **Don't reach for RxJS inside `effect()`/`computed()`.** Subscribing per run

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

@@ -28,7 +28,7 @@ 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                                                                                                                                                               |
 
@@ -66,13 +66,14 @@ That list is a snapshot. The site itself is machine-readable, so fetch rather th
   `-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%}

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

@@ -44,6 +44,21 @@ If a build stalls trying to reach Nx Cloud, re-run it with `NX_NO_CLOUD=true`.
 
 ## 3. Point this repo at the build
 
+Preflight the manifest and lockfile before changing either:
+
+Use {%resource:sdk-local-baseline.mjs%} to capture their exact bytes:
+
+```bash
+git status --short -- <manifest> yarn.lock
+sdk_local_baseline_dir=$(mktemp -d)
+node <path-to-sdk-local-baseline.mjs> capture <manifest> yarn.lock "$sdk_local_baseline_dir"
+```
+
+If either file already differs and you cannot tell who owns the edit, stop and ask. If
+the user authorizes the experiment, keep the exact baseline above; pre-existing edits
+are part of it and must survive byte-for-byte. If either file changes for another reason
+during the experiment, stop and take a new agreed baseline before cleanup.
+
 Edit the version specifiers in `package.json` (the one declaring the dependency - in a
 workspace that is the workspace package, not necessarily the root):
 
@@ -97,17 +112,20 @@ 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:
+does not exist there. Restore the exact recorded baseline as part of the same task:
 
 ```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
+node <path-to-sdk-local-baseline.mjs> restore <manifest> yarn.lock "$sdk_local_baseline_dir"
+yarn install --immutable
+node <path-to-sdk-local-baseline.mjs> verify <manifest> yarn.lock "$sdk_local_baseline_dir"
 ```
 
-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.
+The verification proves that the local-build delta is gone while preserving any edits
+that existed before it. Do not require either file to be globally clean, and do
+not run whole-file `git checkout` or `git restore`. Report the temporary baseline path;
+it can be removed after verification because this workflow created it. Never commit a
+`file:` specifier or the lockfile it produced. If the verified fix is still unreleased,
+say what has to be published instead of shipping a local path.
 
 ## Related