@ethlete/agent-rules 0.1.0-next.0

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

@@ -0,0 +1,70 @@
+---
+name: sdk-docs
+description: Where the @ethlete SDK is documented and how to find the right page. Read BEFORE using any @ethlete component, directive or API you have not already used in this repo - the docs site and Storybook are the source of truth, and inputs/outputs must never be guessed from a component's name.
+kind: skill
+scope: consumer
+vars: [docsBaseUrl, sdkStorybookUrl]
+---
+
+# Finding the @ethlete SDK docs
+
+The SDK lives in another repository. Its source is **not** in this project, so the only
+reliable way to learn a component's inputs, outputs, defaults or required directives is
+to read its documentation - never infer an API from the name, and never copy a shape
+from an unrelated component.
+
+Two sources, both authoritative for different things:
+
+| Source        | URL                 | Use it for                                                                                       |
+| ------------- | ------------------- | ------------------------------------------------------------------------------------------------ |
+| **Docs site** | {%docsBaseUrl%}     | Prose guides: what a thing is for, options, defaults, behaviour, migration notes                 |
+| **Storybook** | {%sdkStorybookUrl%} | The live component: every variant rendered, the real controls, and the exact markup a story uses |
+
+## Finding the right page
+
+Page URLs follow `{%docsBaseUrl%}/<lib>/<topic>`. The library sections:
+
+| Section                                        | Covers                                                                                                                                                                               |
+| ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `/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                                                                                                                        |
+| `/cdk/`                                        | The predecessor UI toolkit, maintenance mode. Only for code that still uses it                                                                                                       |
+| `/contentful/`, `/cli/`, `/eslint/`, `/types/` | The remaining packages                                                                                                                                                               |
+
+Component domains under `/components/`:
+
+`accordion` `bracket` `bracket-rounds-list` `breadcrumb` `button` `calendar` `carousel`
+`cascader` `chip` `choice-inputs` `date-time-inputs` `dropzone` `error-codes`
+`filter-overlay` `floating-action` `focus-ring` `forms` `grid` `icon` `loader`
+`localization` `masonry` `match` `menu` `mixed-state` `notification` `overlay-openers`
+`overlays` `pagination` `picture` `query-devtools` `query-error` `rich-text-editor`
+`scrollable` `select` `skeleton` `slider` `sport-recipes` `standings` `stream` `table`
+`tabs` `text-inputs` `time-picker` `toggletip` `tooltip`
+
+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.
+
+## How to use them
+
+- **Read before writing.** Fetch the guide for the domain you are about to touch. A
+  component's required host directives, its two-way models, and which imports array to
+  pull in (`MENU_IMPORTS`, `TABLE_IMPORTS`, …) are all things the docs state and the
+  name does not imply.
+- **Storybook shows the real thing.** When the prose is ambiguous about markup or a
+  variant's look, open the story - the source panel is the exact template that renders it.
+- **Match the docs to your installed version.** Check the `@ethlete/*` versions in
+  `package.json`. The main docs and Storybook track the released line; a repo on
+  `-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.
+- **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%}

package/content/skills/story-styling/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: story-styling
+description: How to style Storybook story files - where Tailwind is (and isn't) allowed, and how to check which utilities actually exist in your trimmed Tailwind theme before reaching for one. Read BEFORE writing or editing any `*.stories.ts` / `stories/` component, or when a class in a story renders with no visible effect.
+kind: skill
+scope: consumer
+requires: ['@ethlete/core']
+paths: ['**/*.stories.ts', '**/stories/**']
+vars: [themeStylesheet]
+---
+
+# Styling story files
+
+Two separate rules, often confused:
+
+1. **Component source is plain CSS, never Tailwind.** The `.css` next to a
+   component, wrapped in `@layer components`, using surface/color tokens - see
+   {%skill:theming%}.
+2. **Story files may use Tailwind** (`*.stories.ts`, anything under a `stories/`
+   folder) for demo layout only - the frame around the component, not the
+   component's own look.
+
+## The trap: an unknown utility fails silently
+
+A Tailwind v4 `@theme` that resets a token group deletes every utility built from
+it. Tailwind then emits **no class at all** for the name you typed - there is no
+error and no warning, the element just renders unstyled. A theme that does this:
+
+```css
+--color-*: initial; /* the entire default palette is GONE */
+--text-*: initial; /* the entire default type scale is GONE */
+```
+
+leaves `bg-blue-500`, `text-gray-700` and `text-sm` as dead strings, even though
+they are "real" Tailwind classes.
+
+**Read the theme before reaching for an unfamiliar utility.** This project's is
+`{%themeStylesheet%}`:
+
+```bash
+grep -nE -- '--(color|text|font|spacing)-' {%themeStylesheet%}
+```
+
+If `@theme` doesn't define the token, the class doesn't exist. Check rather than
+guess, and prefer utilities from groups the theme leaves untouched (layout, flex,
+grid, radius, opacity, borders) over ones it redefines.
+
+Watch the root font size too: a theme that sets `html { font-size: 62.5% }` makes
+`1rem` = 10px, so every rem-based utility is 62.5% of its nominal value. That mostly
+reads fine when `--spacing` is scaled to match, but it bites on the container scale -
+`max-w-3xl` becomes 480px, not 768px, and silently truncates a demo you sized by eye.
+When a width or height actually matters, bind px:
+
+```html
+<div [style.max-inline-size.px]="768" class="p-8">…</div>
+```
+
+## Colours in a story come from theming, not utilities
+
+A story renders inside a **surface theme** and a **colour theme**, so any colour it
+paints must come from those tokens - the same rule as component CSS
+({%skill:theming%} is the reference for the token names).
+
+- A tinted panel: put `etAutoSurface` on it (next elevation up) and read the token:
+  `style="background: var(--et-surface-background-solid)"`.
+- An accent: scope it with `[etProvideColor]="'brand'"` and read
+  `--et-theme-color-primary-solid` / `--et-theme-color-ink-solid`. Theme names are
+  whatever **your app** registers - fine to name in a story, never in library code.
+- Better still: don't hand-paint. Compose the component that already does it
+  (`<et-chip>` for a badge, `<et-button>` for an action) - that's also what a real
+  consumer would write.
+- **Never `dark:`.** It resolves to `prefers-color-scheme`, which knows nothing about
+  the surface theme the story is rendered on: a story on a dark surface would keep its
+  light styling on an OS in light mode. Elevation and light/dark come from
+  `[etProvideSurface]` / `etAutoSurface`.
+
+## Checklist for a story you just wrote
+
+- Utilities only for layout/spacing/typography; the component's own look comes from the component.
+- Every colour is a theme token, or a utility built on a token the theme still defines.
+- Text sizes from your theme's scale, not Tailwind's default `text-sm`/`text-xs`.
+- No `dark:` variants.
+- Width/height that matters is px, not the rem container scale.
+- Then verify it actually renders - {%skill:verify-in-storybook%}.

package/content/skills/styleguide/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: styleguide
+description: Entry point for the Ethlete coding styleguide. Read when writing or reviewing TypeScript/Angular code. The mechanical rules are enforced by `@ethlete/eslint-plugin` (run lint with `--fix`); this covers the cross-cutting judgment calls (accessibility modifiers, `@internal`, naming intent, file/folder structure).
+kind: skill
+scope: consumer
+requires: ['@ethlete/eslint-plugin']
+vars: [lintCommand, lintFixCommand]
+---
+
+# Styleguide - the parts lint can't check
+
+Most of the styleguide is enforced automatically by **`@ethlete/eslint-plugin`**.
+Don't hand-check or hand-fix those - **run lint with `--fix` first**; many rules
+ship auto-fixers, so most violations are corrected for you:
+
+```bash
+{%lintFixCommand%}   # auto-fixes first (case, ordering, $ suffix, metadata, …)
+{%lintCommand%}      # then re-run to see what needs a manual fix
+```
+
+Full prose reference, including the rule → lint-rule table and the worked
+file-structure example: {%resource:STYLEGUIDE.md%}.
+
+## Focused guides
+
+- {%skill:rxjs-signals%} - synchronous state vs async, subscriptions, effects.
+- {%skill:angular-patterns%} - components, directives, services, pipes, templates,
+  lifecycle.
+
+The rest of this guide is the cross-cutting judgment that doesn't belong to one
+of those.
+
+## Accessibility & visibility
+
+Lint auto-fixes injected providers to `private` and flags template/host-visible
+members, but the _intent_ is yours:
+
+- Injected provider → `private` by default; `protected` **only** when referenced
+  from the HTML template or a `host:` binding; **drop the modifier entirely** if
+  keeping it `private` would force a member alias (a property whose sole purpose
+  is re-exposing a nested member - expose the injected symbol directly instead).
+- Never add a member that only **aliases** another member's nested property
+  (`foo = this.thing.foo`) - widen the source member's visibility and use it.
+- For a member that must stay technically public purely for cross-class/DI use
+  (e.g. a self-registration method called by a sub-directive), keep it `public`
+  and tag `/** @internal */` so build tooling strips it from the published
+  `.d.ts`. Never put `@internal` on `private`/`protected` members.
+
+## Naming with intent
+
+- Name things after **what they do**, not the mechanism: an `onChange` that posts
+  a form → `sendFormValueToApi`. (Lint catches `on`-prefixed _outputs_; plain
+  functions/methods are on you.)
+- More than two params → a single **object parameter** with a named `type`.
+- Descriptive generics (`TValue`, `TResult`) and descriptive const/var names.
+
+## File & folder structure
+
+- Mirror routes in the folder tree; routing components end in `-view`.
+- Reusable pieces → `components/`; a component's private children → `partials/`
+  (used only by that parent); Storybook helpers → `storybook/` (never exported
+  from the component's public surface); generic dumb components → `uikit/`;
+  app-shell pieces → `shell/`.
+- Each exportable folder has an `index.ts` barrel - but **import from the source
+  file, not the barrel** (barrel imports are lint-banned; they break lazy loading).
+- Don't import from a parent directory in a subdirectory (circular-dep risk).