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

package/content/skills/styleguide/file-structure.md

@@ -0,0 +1,73 @@
+# File structure
+
+Read this file when placing routes, views, components, providers, or local utilities.
+
+Mirror the route tree in folders and suffix routing components with `-view`:
+
+```ts
+import { Routes } from '@angular/router';
+
+export const SHOP_ROUTES: Routes = [
+  {
+    path: 'items',
+    loadComponent: () =>
+      import('./items-list-view/items-list-view.component').then((module) => module.ItemsListViewComponent),
+  },
+  {
+    path: 'items/:id',
+    loadComponent: () =>
+      import('./item-detail-host-view/item-detail-host-view.component').then(
+        (module) => module.ItemDetailHostViewComponent,
+      ),
+    children: [
+      {
+        path: '',
+        loadComponent: () =>
+          import('./item-detail-host-view/item-detail-view/item-detail-view.component').then(
+            (module) => module.ItemDetailViewComponent,
+          ),
+      },
+      {
+        path: 'reviews',
+        loadComponent: () =>
+          import('./item-detail-host-view/item-reviews-view/item-reviews-view.component').then(
+            (module) => module.ItemReviewsViewComponent,
+          ),
+      },
+    ],
+  },
+];
+```
+
+Use these placement rules:
+
+- Put reusable view-level pieces in `components/`.
+- Put children used only by one parent in that parent's `partials/`.
+- Put generic presentation-only pieces in `uikit/`.
+- Put application-shell pieces in `shell/`.
+- Keep a directive, pipe, provider, form configuration, or utility beside its narrowest
+  consumer. Move it upward only when more consumers appear.
+- Use simple utility names such as `items-list-filter-form.ts`, not `.utils.ts`.
+- Give exportable folders an `index.ts`, but import source files directly. Do not import
+  a parent barrel from its subdirectory.
+- Keep application projects thin; move shared or domain logic into buildable libraries
+  with clear import paths.
+
+```plaintext
+shop/
+├── items-list-view/
+│   ├── components/
+│   │   └── item-card/
+│   │       ├── partials/
+│   │       │   ├── item-image/
+│   │       │   └── item-price/
+│   │       ├── item-card.component.ts
+│   │       └── item-card.component.html
+│   ├── items-list-filter-form.ts
+│   └── items-list-view.component.ts
+└── item-detail-host-view/
+    ├── item-detail-view/
+    ├── item-reviews-view/
+    ├── item-detail.provider.ts
+    └── item-detail-host-view.component.ts
+```

package/content/skills/styleguide/lint-rule-lookup.md

@@ -0,0 +1,51 @@
+# Lint rule lookup
+
+Read this file only to explain a lint result or identify which rule owns a mechanical
+convention. Run lint with `--fix`; do not hand-check this table before linting.
+
+| Convention                                                           | Rule                                                                                                                                                                                                                |
+| -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| No `any` / `$any()`; narrow `unknown`                                | `@typescript-eslint/no-explicit-any`, `@angular-eslint/template/no-any`                                                                                                                                             |
+| Static strings and booleans use attributes                           | `@angular-eslint/template/prefer-static-string-properties`, `ethlete/prefer-static-boolean-properties`                                                                                                              |
+| `type`, not `interface` (module augmentations stay interfaces)       | `ethlete/consistent-type-definitions`                                                                                                                                                                               |
+| No `enum` or `const enum`                                            | `ethlete/no-enum`                                                                                                                                                                                                   |
+| `const` by default; one declaration per statement                    | `no-var`, `prefer-const`, `one-var`                                                                                                                                                                                 |
+| Strict equality                                                      | `eqeqeq`                                                                                                                                                                                                            |
+| Maximum two positional parameters                                    | `max-params`                                                                                                                                                                                                        |
+| No type-only imports                                                 | `ethlete/no-type-only-import`                                                                                                                                                                                       |
+| Descriptive `T`-prefixed generic names                               | `@typescript-eslint/naming-convention`                                                                                                                                                                              |
+| No `async` / `await`                                                 | `ethlete/no-async-await`                                                                                                                                                                                            |
+| Arrow functions standalone; methods in classes                       | `no-restricted-syntax`                                                                                                                                                                                              |
+| Blank line before a multiline guard return                           | `ethlete/guard-return-newline`                                                                                                                                                                                      |
+| No trivially inferable return type                                   | `ethlete/no-trivial-return-type`                                                                                                                                                                                    |
+| Member and local naming conventions                                  | `@typescript-eslint/naming-convention`, `ethlete/no-leading-underscore-class-member`, `ethlete/no-screaming-case-local`                                                                                             |
+| Class constants are `readonly` and upper case                        | `ethlete/class-constant-property`                                                                                                                                                                                   |
+| No `readonly` on reactive members                                    | `ethlete/no-readonly-signal`                                                                                                                                                                                        |
+| Injected and template-visible member accessibility                   | `ethlete/inject-member-accessibility`, `ethlete/template-member-accessibility`                                                                                                                                      |
+| No inject chains, pure aliases, or trivial wrappers                  | `ethlete/no-inject-chain`, `ethlete/no-member-alias`, `ethlete/no-trivial-wrapper-method`                                                                                                                           |
+| No unused private or protected members                               | `ethlete/no-unused-class-member`                                                                                                                                                                                    |
+| Pure module-scope provider calls                                     | `ethlete/no-impure-top-level-provider`                                                                                                                                                                              |
+| No redundant `@internal`                                             | `ethlete/no-redundant-internal`                                                                                                                                                                                     |
+| Observable names end in `$`                                          | `ethlete/require-dollar-suffix`                                                                                                                                                                                     |
+| No subscribe body, subscribe in pipe, or RxJS in signal derivations  | `ethlete/no-subscribe-with-body`, `ethlete/no-subscribe-in-pipe`, `ethlete/no-rxjs-in-effect`                                                                                                                       |
+| `takeUntilDestroyed()` is the last operator in its pipe              | `ethlete/take-until-destroyed-last`                                                                                                                                                                                 |
+| Effect teardown uses `onCleanup` or `DestroyRef`                     | `ethlete/no-effect-cleanup-return`                                                                                                                                                                                  |
+| Prefer `linkedSignal` for writable derived state                     | `ethlete/prefer-linked-signal`                                                                                                                                                                                      |
+| Global component CSS encapsulation                                   | `ethlete/require-view-encapsulation-none`                                                                                                                                                                           |
+| Angular-version-correct change detection metadata                    | `ethlete/require-on-push-change-detection`, `ethlete/no-redundant-on-push-change-detection`                                                                                                                         |
+| No redundant standalone flag or empty metadata arrays                | `ethlete/no-standalone-flag`, `ethlete/no-empty-angular-metadata-arrays`                                                                                                                                            |
+| No legacy lifecycle hooks or decorators                              | `no-restricted-syntax`, `ethlete/no-legacy-angular-decorators`                                                                                                                                                      |
+| No injectable services, guards, or resolvers                         | `no-restricted-syntax`                                                                                                                                                                                              |
+| Output naming                                                        | `@angular-eslint/no-output-on-prefix`, `@angular-eslint/no-output-native`, `ethlete/prefer-present-tense-output`                                                                                                    |
+| Inputs do not collide with global HTML attributes                    | `ethlete/no-native-html-input-name`                                                                                                                                                                                 |
+| No pipe logic                                                        | `ethlete/no-pipe-logic`                                                                                                                                                                                             |
+| Class members and decorator metadata stay ordered                    | `ethlete/class-member-order`, `ethlete/angular-decorator-property-order`                                                                                                                                            |
+| Routing views use `-view` / `ViewComponent`                          | `ethlete/enforce-routing-view-naming`                                                                                                                                                                               |
+| No direct browser globals, DOM queries, native observers, or cookies | `no-restricted-globals`, `ethlete/no-direct-dom-manipulation`, `ethlete/no-dom-query`, `ethlete/no-native-observers`, `ethlete/no-document-cookie`                                                                  |
+| No barrel imports                                                    | `no-restricted-syntax`                                                                                                                                                                                              |
+| Prefer the SDK wrappers for platform utilities                       | `ethlete/prefer-clone-equal`, `ethlete/prefer-rxjs-timer`, `ethlete/prefer-match-media`, `ethlete/prefer-viewport-size`, `ethlete/no-angular-seo-services`, `ethlete/no-locale-id`, `ethlete/no-angular-router-api` |
+
+Judgment still belongs outside lint: name things after their behavior, use an object
+parameter after two positional parameters, expose injected members directly instead of
+aliasing them, and use `/** @internal */` only on technically public library API that
+must be stripped from declarations.

package/content/skills/styleguide/storybook-structure.md

@@ -0,0 +1,25 @@
+# Storybook structure
+
+Read this file when placing a `*.stories.ts` file or code used only to render stories.
+
+- Keep the `*.stories.ts` file beside the component it documents.
+- Put private host components, dummy data, and story-only helpers in `storybook/`.
+- Never export Storybook-only code from the component's public barrel.
+- A private `storybook/index.ts` may simplify imports into the adjacent story, but no
+  production source may import it.
+
+```plaintext
+settings-form/
+├── storybook/
+│   ├── settings-form-storybook.component.ts
+│   ├── settings-form-storybook.component.html
+│   ├── settings-form-dummy-data.ts
+│   └── index.ts
+├── settings-form.component.ts
+├── settings-form.component.html
+├── settings-form.component.stories.ts
+└── index.ts
+```
+
+The story file stays at the component root; only its private support code goes into
+`storybook/`.

package/content/skills/theming/SKILL.md

@@ -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']
@@ -37,16 +37,16 @@ The generated CSS defines the raw vars on `.et-surface--<name>` / `.et-color--<n
 classes (plus `:root` defaults) and derives the public tokens below on `:root` **and**
 every scope class - so the tokens are always resolvable and components just read them.
 
-**Theme names are yours.** `brand`, `danger`, `neutral`, `dark-elevated` are only
-examples. Never hardcode a theme-name union in a component type, a doc or an example.
-The portable handle is the theme **`type`**: `injectErrorTheme()` finds whichever theme
-the app registered with `type: 'error'`.
+**Theme names are yours.** Never hardcode them as an SDK-defined union or reusable API
+contract. App-specific docs may name their own themes when they label them as app values.
+The portable handle is the theme **`type`**: `injectSemanticColorTheme('error')` finds
+whichever theme the app registered with `type: 'error'`.
 
 ## Tokens components may consume
 
 Use these **derived** tokens - never the raw `--et-surface-background` /
-`--et-color-primary` channel triplets, and never a hardcoded color (a static fallback
-_after_ the token is fine).
+`--et-color-primary` channel triplets. Never use a hardcoded color as the primary value.
+A static fallback inside `var(--token, <fallback>)` is permitted, but not required.
 
 Surface (each exists as `-solid` = usable color, `-rgb` = `R G B` channels):
 
@@ -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]`;
@@ -75,8 +75,8 @@ the interactive element itself, never on a wrapper.
 
 ## Providing context
 
-- `[etProvideSurface]="'dark-elevated'"` / `[etAutoSurface]` (auto-picks the next
-  elevation) set the surface scope; `[etProvideColor]="'brand'"` sets the color scope.
+- `[etProvideSurface]="surfaceThemeName"` / `[etAutoSurface]` (auto-picks the next
+  elevation) set the surface scope; `[etProvideColor]="colorThemeName"` sets the color scope.
   A component that owns a themed region usually adds `ProvideColorDirective` /
   `ProvideSurfaceDirective` as `hostDirectives`.
 - **Detached overlay panes (menu, dialog, tooltip…) do not inherit DOM context.**
@@ -85,10 +85,17 @@ the interactive element itself, never on a wrapper.
   color and `resolveSurfaceByElevation(themes, type, elevation + 1)` for the surface.
 - **Semantic colors come through DI, not CSS.** There is no global "error color"
   variable - error/warning/success are just color themes. To render something in the
-  error color, `injectErrorTheme()` (it throws if the app registered no `type: 'error'`
-  theme) and either bind it (`[etProvideColor]="errorColorTheme"`) or force it
-  programmatically (`provideColor.forceColor(theme)` / `clearForcedColor()`). Inside
-  that scope, `--et-theme-color-primary-*` _is_ the error color.
+  error color, `injectSemanticColorTheme('error')` (reading it throws if the app
+  registered no `type: 'error'` theme) and either bind it
+  (`[etProvideColor]="errorColorTheme()"`) or force it programmatically
+  (`provideColor.forceColor(theme)` / `clearForcedColor()`). Inside that scope,
+  `--et-theme-color-primary-*` _is_ the error color.
+- **`injectSemanticColorTheme(type)` follows the surface**: it is a signal of the theme
+  the nearest surface names in `SurfaceTheme.semanticColorThemes` (e.g.
+  `{ success: 'success-on-light' }`, an extra theme registered without a `type`), else
+  the theme of that `type`. Never add per-surface logic to a color theme or new CSS vars
+  for it. `injectErrorTheme()`, `injectWarningTheme()` and `injectSuccessTheme()` are
+  deprecated: they ignore the surface.
 
 ## Pitfalls
 
@@ -96,15 +103,21 @@ 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)`.
 - `--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.
-- Keep a static fallback (`var(--et-surface-border-solid, rgb(255 255 255 / 0.1))`) so
-  components degrade in theme-less setups. `injectErrorTheme()` is the exception: it is
-  a hard requirement wherever it is used.
-- **Cascade layers, not `:where()`, are what let a Tailwind utility override component
-  CSS.** Wrap every component CSS file in `@layer components { … }`; `:where()` only
-  flattens a component's own modifiers to single-class weight. See the `styling` rule.
-
-Styling a **story** file rather than a component? The colour rule is the same, but the
-Tailwind side has its own traps - {%skill:story-styling%}.
+- A static fallback (`var(--et-surface-border-solid, rgb(255 255 255 / 0.1))`) is
+  permitted for theme-less setups, but themes make it unnecessary. `injectSemanticColorTheme()`
+  is a hard requirement wherever it is read.
+- **Cascade layers, not `:where()`, decide who wins against SDK component CSS.** SDK
+  styles live in `@layer components`, so a utility or unlayered app CSS overrides them.
+  An app rule inside `@layer components` loses. See the `app-styling` rule.
+
+Styling a **story** file rather than a component? The colour rule is the same. Check the
+repository's Storybook guidance before assuming a Tailwind utility exists.