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

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # @ethlete/agent-rules
 
+## 0.1.0-next.2
+
+### Minor Changes
+
+- [#3043](https://github.com/ethlete-io/ethdk/pull/3043) [`a311f80`](https://github.com/ethlete-io/ethdk/commit/a311f80455bc9cc9a925fe8f72ac945a1b057315) Thanks [@github-actions](https://github.com/apps/github-actions)! - New `sdk-source` and `sdk-local-build` skills let an agent read the SDK's own sources and test an unreleased build via `file:`, from the checkout named by the local config's new `sdkSourcePath`.
+
+### Patch Changes
+
+- [#3043](https://github.com/ethlete-io/ethdk/pull/3043) [`9627646`](https://github.com/ethlete-io/ethdk/commit/96276462e1c2ecde5394b8b1eafcebbb9f56a973) Thanks [@github-actions](https://github.com/apps/github-actions)! - Styleguide: changeset notes are now capped at one to two sentences, with mechanism and API inventories
+  explicitly sent to the docs instead.
+
+## 0.1.0-next.1
+
+### Minor Changes
+
+- [#3042](https://github.com/ethlete-io/ethdk/pull/3042) [`28a58eb`](https://github.com/ethlete-io/ethdk/commit/28a58ebc56420b7e067d8c56108b39601d7b367e) Thanks [@github-actions](https://github.com/apps/github-actions)! - - Skills now compile to the cross-tool `.agents/skills/ethlete-*/SKILL.md` format, discovered natively by Codex, Cursor and Copilot; the `.agents/ethlete/` pointer tree is pruned on sync.
+  - New `ethlete-agents migrate` converts a repo to the `AGENTS.md`-canonical layout: `CLAUDE.md` becomes an `@AGENTS.md` import and hand-written skills move to `.agents/skills` with symlinks.
+  - New opt-in `hooks` config: `context-warning` warns (and instructs Claude) before the context crosses the 200k long-context pricing boundary, recommending `/handoff`.
+  - A gitignored `ethlete-agents.config.local.json` (`"disableHooks": true` or a list of hook names) disables generated hooks per machine at runtime — committed files never change, and `sync`/`check` warn about unsupported keys or unknown hook names in it.
+
 ## 0.1.0-next.0
 
 ### Minor Changes

package/README.md

@@ -23,17 +23,44 @@ 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.
+Skills are compiled once into `.agents/skills/ethlete-*/SKILL.md` - the cross-tool
+[Agent Skills](https://agentskills.io) format that Codex, Cursor, Copilot and VS Code
+discover natively (each skill's body loads on demand from its `description`
+frontmatter). Claude Code only scans `.claude/skills/`, so the claude target writes its
+own copies there. Rules are always-loaded and go into each tool's native mechanism:
+
+|                     | 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 skills    | `.claude/skills/ethlete-*/SKILL.md` | `.agents/skills/ethlete-*/SKILL.md`                 | `.agents/skills/ethlete-*/SKILL.md`            | `.agents/skills/ethlete-*/SKILL.md` |
+
+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.
+
+## Migrating a repo to the AGENTS.md layout
+
+`AGENTS.md` is the cross-tool standard, and Claude Code officially supports reading it
+through a one-line `CLAUDE.md` import. To restructure a whole repo around that:
+
+```bash
+npx ethlete-agents migrate --dry-run   # prints the plan
+npx ethlete-agents migrate
+```
+
+- `CLAUDE.md` content moves to the top of `AGENTS.md`; `CLAUDE.md` becomes `@AGENTS.md`.
+- Hand-written `.claude/skills/<name>` directories move to `.agents/skills/<name>`, with
+  a symlink left behind so Claude Code still finds them. (Symlinks need Developer Mode
+  on Windows checkouts.)
+- A short layout note is added to `AGENTS.md` so agents know the symlinked skills are
+  the same files, not duplicates - skipped if your `AGENTS.md` already explains it.
+- The config gains the `codex` target and `claudeMdImportsAgentsMd: true`, which stops
+  the claude target from writing `.claude/rules/ethlete/` - the rules already reach
+  Claude through the `AGENTS.md` marker block, and a second copy would load twice.
+- A `sync` runs, which also prunes output from older layouts (`.agents/ethlete/`,
+  `.github/instructions/ethlete-*`).
+
+The command is idempotent - every step detects the migrated state and skips itself.
 
 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
@@ -47,7 +74,6 @@ Prettier rewrites them and `check` then reports drift on every run:
 /.claude
 /.agents
 /.cursor/rules/ethlete-*
-/.github/instructions/ethlete-*
 ```
 
 ## Configuration
@@ -69,8 +95,9 @@ Prettier rewrites them and `check` then reports drift on every run:
 }
 ```
 
-- **`targets`** - `"auto"` (default) emits for every agent whose directory already
-  exists, or list a subset of `claude`, `codex`, `cursor`, `copilot`.
+- **`targets`** - `"auto"` (default) always emits `codex` (`AGENTS.md` plus
+  `.agents/skills/` is the cross-tool baseline) and adds `claude`, `cursor` or `copilot`
+  when their directory exists; or list an explicit subset.
 - **`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.
@@ -78,10 +105,65 @@ Prettier rewrites them and `check` then reports drift on every run:
   `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.
+- **`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
+  missing.
 
 Content that declares `requires` is only emitted when those packages are installed, so
 a repo without `@ethlete/query` never sees the query guide.
 
+## Hooks (opt-in)
+
+Claude Code hooks run commands on the developer's machine, so none are emitted by
+default - opt in per hook in the config:
+
+```json
+{
+  "hooks": ["context-warning"]
+}
+```
+
+`sync` writes the script to `.claude/hooks/ethlete/` and registers it in
+`.claude/settings.json` (your own entries are left untouched); removing the name from
+`hooks` unregisters and deletes it again.
+
+Available hooks:
+
+- **`context-warning`** - warns once per tier (and instructs Claude) when the session
+  context crosses 70% / 85% of the token budget, recommending `/handoff`. 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.
+
+Hooks can be turned off per machine - see the local config below.
+
+## Per-machine local config
+
+A gitignored `ethlete-agents.config.local.json` at the repo root holds the values that
+differ per developer, without touching any committed file:
+
+```json
+{
+  "disableHooks": true,
+  "sdkSourcePath": "/absolute/path/to/ethlete-sdk"
+}
+```
+
+- **`disableHooks`** - `true` disables every generated hook; an array
+  (`["context-warning"]`) just the named ones. The hook scripts read the file at
+  runtime, so toggling takes effect on the next prompt - no `sync` needed.
+- **`sdkSourcePath`** - a local `ethlete-sdk` checkout. The `sdk-source` and
+  `sdk-local-build` skills read it when the agent needs the SDK's own sources, or has to
+  build the SDK and install it here through a `file:` dependency. A relative path is
+  resolved from the repo root.
+
+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,
+and about an `sdkSourcePath` that is missing or is not an SDK checkout. Add the filename
+to your repo's `.gitignore`.
+
 ## Authoring content
 
 `content/rules/<name>.md` for short, always-loaded rules; `content/skills/<name>/SKILL.md`
@@ -94,7 +176,7 @@ 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`
+paths: ['**/*.css'] # optional; becomes Claude `paths` and Cursor `globs` on rules
 vars: [docsBaseUrl] # optional
 ---
 ```

package/content/hooks/context-warning.py

@@ -0,0 +1,215 @@
+#!/usr/bin/env python3
+"""UserPromptSubmit hook: warn when the context window is getting large.
+
+Reads the hook input JSON from stdin, estimates the current context size from
+the last main-chain assistant message in the session transcript, and emits a
+warning (visible to both the user and Claude) when it crosses a threshold.
+Recommends the /handoff skill so work can continue in a fresh session.
+
+The thresholds are fractions of a token budget, and the 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.
+
+Warns once per tier per session (state kept in a temp file); re-arms itself
+if the context shrinks again (e.g. after /compact).
+
+Can be disabled per machine via a gitignored ethlete-agents.config.local.json
+at the repo root: {"disableHooks": true} or {"disableHooks": ["context-warning"]}.
+
+Fail-safe: any error exits 0 with no output — the hook must never block a prompt.
+"""
+
+import json
+import os
+import sys
+import tempfile
+
+HOOK_NAME = "context-warning"
+LOCAL_CONFIG_FILE = "ethlete-agents.config.local.json"
+
+# Warn / critical fire at these fractions of the token budget.
+WARN_FRACTION = 0.70
+CRITICAL_FRACTION = 0.85
+
+# On models with a window larger than this, tokens beyond it bill the whole
+# context at the long-context premium rate — so the budget never exceeds it.
+PREMIUM_BOUNDARY = 200_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.
+CONTEXT_WINDOWS = (
+    ("opus-5", 1_000_000),
+    ("opus-4-8", 1_000_000),
+    ("sonnet-4-5", 1_000_000),
+    ("sonnet-5", 1_000_000),
+    ("fable-5", 1_000_000),
+    # Generic fallbacks — keep these last: the first substring match wins, so a bare
+    # "opus"/"sonnet" entry placed above would shadow every versioned entry below it.
+    ("opus", 200_000),
+    ("sonnet", 200_000),
+    ("haiku", 200_000),
+)
+DEFAULT_WINDOW = 200_000
+
+
+def disabled_locally():
+    """True when the local config disables this hook (or all hooks) on this machine."""
+    root = os.environ.get("CLAUDE_PROJECT_DIR")
+    if not root:
+        return False
+    try:
+        with open(os.path.join(root, LOCAL_CONFIG_FILE), encoding="utf-8") as f:
+            disabled = json.load(f).get("disableHooks")
+    except (OSError, ValueError, AttributeError):
+        return False
+    return disabled is True or (isinstance(disabled, list) and HOOK_NAME in disabled)
+
+
+def window_for(model):
+    """Context window for a model id, by first substring match; DEFAULT_WINDOW otherwise."""
+    if model:
+        for needle, window in CONTEXT_WINDOWS:
+            if needle in model:
+                return window
+    return DEFAULT_WINDOW
+
+
+def context_state(transcript_path):
+    """(tokens, model) from the last main-chain assistant message.
+
+    tokens ≈ its total input tokens (fresh + cache read + cache creation).
+    """
+    last_usage = None
+    last_model = None
+    with open(transcript_path, encoding="utf-8") as f:
+        for line in f:
+            try:
+                obj = json.loads(line)
+            except json.JSONDecodeError:
+                continue
+            if obj.get("type") != "assistant" or obj.get("isSidechain"):
+                continue
+            message = obj.get("message") or {}
+            usage = message.get("usage")
+            if usage:
+                last_usage = usage
+                last_model = message.get("model") or last_model
+    if not last_usage:
+        return 0, last_model
+    tokens = (
+        last_usage.get("input_tokens", 0)
+        + last_usage.get("cache_read_input_tokens", 0)
+        + last_usage.get("cache_creation_input_tokens", 0)
+    )
+    return tokens, last_model
+
+
+def messages(tier, tokens, budget, priced):
+    """(systemMessage, additionalContext) for a tier.
+
+    priced: the budget is the pricing boundary, not the window — the reason to
+    hand off is cost, not an imminent auto-compact.
+    """
+    k = f"~{tokens // 1000}k"
+    pct = round(tokens / budget * 100)
+    budget_k = f"{budget // 1000}k"
+    if tier == 2 and priced:
+        return (
+            f"🔴 Context is at {k} tokens — about to cross the {budget_k} long-context "
+            f"pricing boundary, after which every request bills the whole context at the "
+            f"premium rate. Run /handoff now and continue in a fresh session.",
+            f"[context-warning hook] The context is at {k} tokens — {pct}% of the "
+            f"{budget_k} long-context pricing boundary. Past it every request is billed at "
+            "the premium rate. Finish only the immediate step, then recommend the user run "
+            "/handoff to save state and start a fresh session. Do not start new sub-tasks.",
+        )
+    if tier == 2:
+        return (
+            f"🔴 Context is at {k} tokens ({pct}% of the {budget_k} window) — "
+            f"auto-compact is imminent. Run /handoff now and continue in a fresh session.",
+            f"[context-warning hook] The context window is at {k} tokens — {pct}% of "
+            f"this model's {budget_k} window (critical, ≥{int(CRITICAL_FRACTION * 100)}%). "
+            "Finish only the immediate step, then recommend the user run /handoff to "
+            "save state and start a fresh session. Do not start new sub-tasks.",
+        )
+    if priced:
+        return (
+            f"🟡 Context is at {k} tokens, approaching the {budget_k} long-context "
+            f"pricing boundary. At the next natural stopping point, consider /handoff "
+            f"to continue in a fresh session.",
+            f"[context-warning hook] The context is at {k} tokens — {pct}% of the "
+            f"{budget_k} long-context pricing boundary, past which every request is "
+            "billed at the premium rate. When the current task reaches a natural "
+            "stopping point, suggest the user run /handoff to save state and start a "
+            "fresh session. Keep working normally until then.",
+        )
+    return (
+        f"🟡 Context is at {k} tokens ({pct}% of the {budget_k} window). At the next "
+        f"natural stopping point, consider /handoff to continue in a fresh session.",
+        f"[context-warning hook] The context window is at {k} tokens — {pct}% of "
+        f"this model's {budget_k} window (≥{int(WARN_FRACTION * 100)}%). When the "
+        "current task reaches a natural stopping point, suggest the user run "
+        "/handoff to save state and start a fresh session. Keep working normally until then.",
+    )
+
+
+def main():
+    if disabled_locally():
+        return
+    data = json.load(sys.stdin)
+    transcript_path = data.get("transcript_path")
+    session_id = data.get("session_id", "unknown")
+    if not transcript_path or not os.path.isfile(transcript_path):
+        return
+
+    tokens, model = context_state(transcript_path)
+    window = window_for(model)
+    budget = min(window, PREMIUM_BOUNDARY)
+    warn_tokens = int(budget * WARN_FRACTION)
+    critical_tokens = int(budget * CRITICAL_FRACTION)
+    tier = 2 if tokens >= critical_tokens else 1 if tokens >= warn_tokens else 0
+
+    state_file = os.path.join(
+        tempfile.gettempdir(), f"claude-context-warning-{session_id}"
+    )
+    prev_tier = 0
+    try:
+        with open(state_file, encoding="utf-8") as f:
+            prev_tier = int(f.read().strip() or 0)
+    except (OSError, ValueError):
+        pass
+
+    if tier != prev_tier:
+        try:
+            with open(state_file, "w", encoding="utf-8") as f:
+                f.write(str(tier))
+        except OSError:
+            pass
+
+    if tier <= prev_tier:
+        return  # already warned at this tier (or context shrank — state re-armed above)
+
+    system_message, additional_context = messages(tier, tokens, budget, budget < window)
+
+    print(
+        json.dumps(
+            {
+                "systemMessage": system_message,
+                "suppressOutput": True,
+                "hookSpecificOutput": {
+                    "hookEventName": "UserPromptSubmit",
+                    "additionalContext": additional_context,
+                },
+            }
+        )
+    )
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except Exception:
+        pass
+    sys.exit(0)

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

@@ -68,3 +68,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

@@ -0,0 +1,113 @@
+---
+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).
+- Note which branch it is on. Building `main` when your app runs `-next` prereleases
+  swaps in a completely different API surface.
+
+## 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

@@ -0,0 +1,108 @@
+---
+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 checkout matches what is installed
+
+A checkout sits on whatever branch the developer left it on, so it can be months of
+work ahead of the installed package - or behind it. Compare before you trust it:
+
+```bash
+grep '"@ethlete/' package.json                          # what this repo runs
+grep -m1 '"version"' <sdkSourcePath>/libs/<lib>/package.json   # what the checkout is at
+git -C <sdkSourcePath> status -sb                       # branch, and whether it is dirty
+```
+
+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.
+- A dirty checkout may contain someone's work in progress. Say so rather than quoting
+  it as SDK behaviour.
+
+## 3. 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/playground/`                  | 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.
+
+## 4. 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.
+
+## 5. 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, and never copy its internals into
+consumer code - 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

@@ -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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ethlete/agent-rules",
-  "version": "0.1.0-next.0",
+  "version": "0.1.0-next.2",
   "license": "MIT",
   "type": "commonjs",
   "main": "./src/index.js",