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

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

@@ -20,6 +20,13 @@ Two sources, both authoritative for different things:
 | **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 |
 
+## First: app setup
+
+Before the first component, work through `{%docsBaseUrl%}/components/setup` - the 62.5% root
+font size, Tailwind 4 theme generation, a `type: 'error'` color theme, and the providers
+(`provideOverlay`, `provideDateLocale`, label tokens, …). Missing any of them fails at runtime,
+not at compile time.
+
 ## Finding the right page
 
 Page URLs follow `{%docsBaseUrl%}/<lib>/<topic>`. The library sections:
@@ -28,23 +35,51 @@ 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                                                                                                                                                               |
 
 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`
+`accordion` `avatar` `badge` `banner` `bracket` `bracket-prediction` `bracket-rounds-list`
+`breadcrumb` `button` `calendar` `card` `carousel` `cascader` `chart` `chip`
+`choice-inputs` `command-palette` `copy-button` `date-time-inputs` `description-list`
+`divider` `dropzone` `empty-state` `error-codes` `filter-overlay` `floating-action`
+`focus-ring` `forms` `grid` `icon` `kbd` `line-chart` `loader` `localization` `masonry`
+`match` `menu` `mixed-state` `notification` `overlay-openers` `overlays` `paged-query-trigger`
+`pagination` `picture` `pie-chart` `progress-steps` `query-error` `rich-text-editor` `sankey-chart`
+`scheduler` `scrollable` `scrollbar` `select` `setup` `skeleton` `slider` `sport-recipes` `stat-tile`
+`standings` `standings-pick` `stream` `table` `tabs` `testing` `text-inputs` `time-picker`
+`timeline` `toggletip` `toolbar` `tooltip` `tree`
+
+**Check this list before you build any UI by hand.** Some needs hide behind a name you
+would not guess:
+
+| You need                                   | Read                                      |
+| ------------------------------------------ | ----------------------------------------- |
+| Bar or stacked bar chart, series legend    | `chart`                                   |
+| Line, pie, flow chart                      | `line-chart`, `pie-chart`, `sankey-chart` |
+| Progress bar, spinner                      | `loader`                                  |
+| Initials or user picture in a circle       | `avatar`                                  |
+| "No results" or empty table state          | `empty-state`                             |
+| Failed request with a retry button         | `query-error`                             |
+| Status pill, count                         | `badge`                                   |
+| Tab strip that switches a view or a filter | `tabs` (nav tabs)                         |
+| Dialog, bottom sheet, side panel           | `overlays`, `overlay-openers`             |
+| Label and value pairs                      | `description-list`                        |
+| Stepper, wizard progress                   | `progress-steps`                          |
+| Providers and styles a new app needs       | `setup`                                   |
 
 So the table guide is `{%docsBaseUrl%}/components/table`, the menu guide
-`{%docsBaseUrl%}/components/menu`, and so on. When a name isn't in that list, start at
-`{%docsBaseUrl%}/components/` and follow the sidebar rather than guessing a URL.
+`{%docsBaseUrl%}/components/menu`, and so on.
+
+That list is a snapshot. The site itself is machine-readable, so fetch rather than guess:
+
+- `{%docsBaseUrl%}/llms.txt` - every page's title and path as of the last deploy. Use it
+  when a name isn't in the list above, or to check the list hasn't drifted.
+- Append `.md` to any page URL - `{%docsBaseUrl%}/components/button.md` - to get raw
+  markdown instead of the rendered page. Prefer this over `/llms-full.txt`, which is the
+  entire site in one ~1 MB file.
 
 ## How to use them
 
@@ -59,13 +94,14 @@ So the table guide is `{%docsBaseUrl%}/components/table`, the menu guide
   `-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

@@ -17,12 +17,14 @@ published yet, or when you are iterating on it.
 
 ## 1. Prerequisites
 
-- The checkout path comes from `sdkSourcePath` in `ethlete-agents.config.local.json`;
+- The checkout path comes from `sdkSourcePath` in `ethlete.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.
+- Check which branch it is on before building - unless the user said otherwise, that
+  should be `next`, up to date with `origin/next`. Building `main` when your app runs
+  `-next` prereleases swaps in a completely different API surface, and building a stale
+  `next` rebuilds a bug that is already fixed upstream. Ask before changing its branch.
 
 ## 2. Build the libraries you changed
 
@@ -42,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):
 
@@ -95,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
 

package/content/skills/sdk-local-build/sdk-local-baseline.mjs

@@ -0,0 +1,64 @@
+import { copyFileSync, existsSync, mkdirSync, readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { join, resolve } from 'node:path';
+
+const baselinePaths = (baselineDir) => ({
+  manifest: join(baselineDir, 'package.json.baseline'),
+  lockfile: join(baselineDir, 'yarn.lock.baseline'),
+});
+
+export const captureBaseline = (manifestPath, lockfilePath, baselineDir) => {
+  const baseline = baselinePaths(baselineDir);
+
+  mkdirSync(baselineDir, { recursive: true });
+
+  if (existsSync(baseline.manifest) || existsSync(baseline.lockfile)) {
+    throw new Error(`Baseline already exists in ${baselineDir}.`);
+  }
+
+  copyFileSync(manifestPath, baseline.manifest);
+  copyFileSync(lockfilePath, baseline.lockfile);
+};
+
+export const restoreBaseline = (manifestPath, lockfilePath, baselineDir) => {
+  const baseline = baselinePaths(baselineDir);
+
+  copyFileSync(baseline.manifest, manifestPath);
+  copyFileSync(baseline.lockfile, lockfilePath);
+};
+
+export const verifyBaseline = (manifestPath, lockfilePath, baselineDir) => {
+  const baseline = baselinePaths(baselineDir);
+
+  for (const [current, recorded] of [
+    [manifestPath, baseline.manifest],
+    [lockfilePath, baseline.lockfile],
+  ]) {
+    if (!readFileSync(current).equals(readFileSync(recorded))) {
+      throw new Error(`${current} does not match its recorded baseline.`);
+    }
+  }
+};
+
+const run = () => {
+  const [mode, manifestPath, lockfilePath, baselineDir] = process.argv.slice(2);
+
+  if (!mode || !manifestPath || !lockfilePath || !baselineDir) {
+    throw new Error('Usage: sdk-local-baseline.mjs <capture|restore|verify> <manifest> <lockfile> <baseline-dir>');
+  }
+
+  const actions = {
+    capture: captureBaseline,
+    restore: restoreBaseline,
+    verify: verifyBaseline,
+  };
+  const action = actions[mode];
+
+  if (!action) throw new Error(`Unknown mode "${mode}".`);
+
+  action(manifestPath, lockfilePath, baselineDir);
+};
+
+if (process.argv[1] && fileURLToPath(import.meta.url) === resolve(process.argv[1])) {
+  run();
+}

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

@@ -21,7 +21,7 @@ first. Reach for the source when the docs genuinely cannot answer the question:
 
 ## 1. Resolve the checkout
 
-The path is per machine, so it lives in the gitignored `ethlete-agents.config.local.json`
+The path is per machine, so it lives in the gitignored `ethlete.config.local.json`
 at the repo root:
 
 ```json
@@ -30,6 +30,9 @@ at the repo root:
 }
 ```
 
+Older checkouts still keep this key in `ethlete-agents.config.local.json`. Read that file as a
+fallback when `ethlete.config.local.json` is absent.
+
 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
@@ -38,27 +41,50 @@ 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
+## 2. Match evidence to the installed package
+
+Start with this routing:
+
+- Installed `.d.ts` files are authoritative for the public type surface available to
+  this consumer.
+- Source matching the installed build is authoritative for runtime implementation
+  details.
+- Docs explain intended usage and defaults, but can drift from a prerelease.
+- A dirty or ahead `next` checkout is not automatically source for the installed build.
+
+Compare the installed package version with the checkout version before attributing
+runtime behavior to the checkout:
+
+```bash
+grep '"@ethlete/' package.json
+grep -m1 '"version"' <sdkSourcePath>/libs/<lib>/package.json
+```
+
+Matching version strings are necessary but not sufficient when the checkout is ahead of
+the published commit. Never write consumer code against source that the installed types
+do not expose.
+
+## 3. Check only the paths that answer the question
 
-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:
+Resolve the implementation, public barrel, specs, and docs relevant to the question.
+Then inspect state for those paths:
 
 ```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
+git -C <sdkSourcePath> status -sb
+git -C <sdkSourcePath> status --short -- <relevant-paths>
+git -C <sdkSourcePath> diff -- <relevant-paths>
 ```
 
-Rules when they differ:
+Unrelated dirty files, another branch, or unrelated ahead commits do not block a source
+lookup. If relevant paths are dirty or differ in the relevant commit range, label the
+worktree behavior separately from published behavior. Ask only when that distinction
+changes the answer.
 
-- **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.
+Use existing remote refs first. `git fetch` preserves worktree files but 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. Where things live
+## 4. Where things live
 
 Paths are relative to the checkout root:
 
@@ -71,7 +97,7 @@ Paths are relative to the checkout root:
 | `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                |
+| `apps/storybook/`                   | The Storybook app - stories also live next to each component                |
 
 Inside a component domain: `<name>.component.ts` with its `.css` next to it,
 `<name>.imports.ts` (the imports array to spread into a consumer component),
@@ -79,7 +105,7 @@ Inside a component domain: `<name>.component.ts` with its `.css` next to it,
 `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
+## 5. Search it, don't read it whole
 
 ```bash
 rg -n "etButton" <sdkSourcePath>/libs/components/src --glob '!*.spec.ts'   # a selector
@@ -91,12 +117,14 @@ Specs are the cheapest description of intended behaviour - `<name>.component.spe
 next to a component usually answers "is this supposed to happen?" faster than the
 implementation does.
 
-## 5. The checkout is read-only from here
+## 6. The checkout is read-only from here
 
 It is a different repository with its own branch, lint, docs and changeset workflow.
-Never edit it while working on a task in this repo, 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).
+Never edit it while working on a task in this repo - that covers its git state too, so
+no `checkout`, `pull`, `stash` or `reset` without the user asking for it. Never copy its
+internals into consumer code either - a private helper is not a
+supported API and disappears without a major version (the same goes for anything under
+a `subtle` namespace).
 
 When the fix belongs in the SDK, say so and describe it precisely: file, symbol, and
 the behaviour it should have. If the user wants that fix verified against this app

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

@@ -0,0 +1,96 @@
+---
+name: sdk-update
+description: Update the @ethlete/* packages in this repo with `et update`, and work the migration tasks it leaves behind - the codemods it runs itself, the recommendations a human must decide, and the tasks written as a prompt for you. Read whenever this repo moves to a newer @ethlete version, when a task list under .ethlete/update is present, or when the user asks you to apply an SDK migration.
+kind: skill
+scope: consumer
+requires: ['@ethlete/cli']
+vars: [docsBaseUrl, lintCommand]
+---
+
+# Updating the @ethlete SDK
+
+`et update` moves this repo's `@ethlete/*` dependencies to a newer version and runs the migrations
+those versions ship. Never bump an `@ethlete/*` range by hand: the version that lands is what selects
+the migrations, so a hand-written bump skips every one of them silently.
+
+## 1. See what is pending
+
+```bash
+{%packageRunner%} et update --check
+```
+
+It prints one line per package, `installed → target`, and exits 1 while an update is pending. It
+writes nothing. The target follows the dist tag the installed version is on: a repo on a `-next`
+prerelease stays on `next`.
+
+Name a package to limit the run, short or in full:
+
+```bash
+{%packageRunner%} et update core            # only @ethlete/core
+{%packageRunner%} et update core --to 5.0.0-next.55
+{%packageRunner%} et update --tag latest    # leave the prerelease line
+```
+
+## 2. Run it
+
+The working tree must be clean - the codemods rewrite files, and you need a diff you can read.
+Commit or stash first, then:
+
+```bash
+{%packageRunner%} et update
+```
+
+In order, it writes the new ranges into every `package.json` in the repo that declares the package -
+an Nx library manifest included, not only the root one - runs the install, reads the migrations out of
+the freshly installed packages, runs every codemod, regenerates the agent rules and skills with
+`ethlete-agents sync` when `@ethlete/agent-rules` moved, and writes what is left to `.ethlete/update`.
+
+An older `@ethlete/cli` skips the sync. If the run moved `@ethlete/agent-rules` and printed no
+`ethlete-agents sync` line, run `{%packageRunner%} ethlete-agents sync` yourself before the first task: the
+tasks assume the guidance of the new version.
+
+If the install or a codemod fails, the run stops and leaves `.ethlete/update/pending.json` behind.
+Fix the cause, then continue - do not start over, or the migrations of the versions already installed
+are skipped:
+
+```bash
+{%packageRunner%} et update --continue
+```
+
+## 3. Work the task list
+
+Two files describe what is left. Read the JSON one when you work through the list yourself:
+
+| File                              | What it holds                                                         |
+| --------------------------------- | --------------------------------------------------------------------- |
+| `.ethlete/update/tasks.md`        | The report for a human: what moved, what applied, what is left        |
+| `.ethlete/update/tasks.json`      | The same tasks as data: `kind`, `instructionsFile`, `docsUrl`         |
+| `.ethlete/update/<pkg>-<name>.md` | One task in full: what moved, plus the instructions the package ships |
+
+Every task carries a `kind`, and the kind decides who acts:
+
+- **`assisted`** - written for you. The task file states one bounded change to apply across this repo.
+  Read the whole file before the first edit, then work it until its `Done when` list holds. These are
+  the changes no codemod can make, so expect a decision per call site rather than one pattern. What the
+  file leaves for later stays for later: report it, do not do it. A view you cannot open in the browser
+  (a login fails, no API) goes into your report as unchecked; it does not block the task.
+- **`manual`** - a recommendation for the developer. It needs a product or design decision, or a
+  command with answers only they have. Do not guess the answer. Report the task and what it needs.
+- **`unsupported`** - a codemod that could not run here, because this repo has no Nx. The task carries
+  the exact command. Ask before running it: it rewrites files.
+
+## 4. Finish
+
+1. Run the type check and `{%lintCommand%}` for every project you changed.
+2. Run the tests that cover what you touched.
+3. Delete the task files you finished under `.ethlete/update`, and leave the ones you could not decide.
+4. Tell the user, per task: what you changed, and what still needs their decision.
+
+## Rules
+
+- **Never invent a migration.** Only the tasks in `.ethlete/update` and the guides they link are real.
+  A rewrite you reasoned out from a version number is a guess.
+- **Never edit the generated report to make it look done.** Deleting a finished task file is right;
+  deleting an entry you did not work is not.
+- **One task at a time.** Each has its own diff, so a failure stays readable.
+- The version notes and every guide a task links live at {%docsBaseUrl%}.

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

@@ -12,9 +12,10 @@ vars: [themeStylesheet]
 
 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%}.
+1. **A library component's source is plain CSS, never Tailwind.** The `.css` next
+   to a component a library ships, wrapped in `@layer components`, using
+   surface/color tokens - see {%skill:theming%}. Application components are the
+   opposite: they use Tailwind utilities in their templates.
 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.
@@ -33,11 +34,11 @@ error and no warning, the element just renders unstyled. A theme that does this:
 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%}`:
+**Read the theme before reaching for an unfamiliar utility.** This project's lives in
+`{%themeStylesheet%}` (a file, or a folder of theme files):
 
 ```bash
-grep -nE -- '--(color|text|font|spacing)-' {%themeStylesheet%}
+grep -rnE -- '--(color|text|font|spacing)-' {%themeStylesheet%}
 ```
 
 If `@theme` doesn't define the token, the class doesn't exist. Check rather than
@@ -62,7 +63,7 @@ paints must come from those tokens - the same rule as component CSS
 
 - 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
+- An accent: scope it with `[etProvideColor]="storyAccentTheme"` 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
@@ -80,4 +81,5 @@ paints must come from those tokens - the same rule as component CSS
 - 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%}.
+- Then verify it actually renders with the repository's installed Storybook verification
+  workflow, or inspect the story directly when no such guide was emitted.

package/content/skills/styleguide/SKILL.md

@@ -14,18 +14,23 @@ 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, …)
+{%lintFixCommand%}   # auto-fixes first (case, ordering, metadata, …); rename to the $ suffix by hand
 {%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%}.
+Load only the reference needed for the current question:
 
-## Focused guides
+- {%resource:lint-rule-lookup.md%} when a lint fix or diagnostic needs explanation.
+- {%resource:file-structure.md%} when placing routes, views, reusable components,
+  providers, or local utilities.
+- {%resource:assets.md%} when deciding where build, serve, shared, or Storybook assets
+  belong.
+- {%resource:storybook-structure.md%} when placing a story file or its private helpers.
+- {%resource:changesets.md%} when deciding whether an application or library change
+  needs a release note and no repository-specific release skill exists.
 
-- {%skill:rxjs-signals%} - synchronous state vs async, subscriptions, effects.
-- {%skill:angular-patterns%} - components, directives, services, pipes, templates,
-  lifecycle.
+For reactive state or Angular building blocks, load the corresponding focused repository
+guide if one was emitted. This entry point does not duplicate those guides.
 
 The rest of this guide is the cross-cutting judgment that doesn't belong to one
 of those.

package/content/skills/styleguide/assets.md

@@ -0,0 +1,54 @@
+# Assets
+
+Read this file when deciding whether an asset belongs to production, local serve, a
+specific app, Storybook, or shared output.
+
+Keep assets in the workspace assets library and separate them by consumer and purpose:
+
+```plaintext
+assets/
+├── my-app/
+│   ├── build/
+│   ├── serve/
+│   └── storybook/
+├── other-app/
+│   ├── build/
+│   ├── serve/
+│   └── storybook/
+└── shared/
+    ├── build/
+    ├── serve/
+    └── storybook/
+```
+
+- `build/` contains production assets.
+- `serve/` contains development-only placeholders or fixtures.
+- `storybook/` contains assets used only by stories.
+- `shared/` contains assets genuinely used by more than one app.
+- Preserve the intended public URL through the project's `assets` configuration. Do not
+  expose a `build` directory segment in the final URL.
+
+```json
+{
+  "assets": [
+    {
+      "input": "libs/assets/src/my-app/build",
+      "glob": "**/*",
+      "output": "assets"
+    },
+    {
+      "input": "libs/assets/src/my-app/serve",
+      "glob": "**/*",
+      "output": "assets/serve"
+    },
+    {
+      "input": "libs/assets/src/shared/build",
+      "glob": "**/*",
+      "output": "assets/shared"
+    }
+  ]
+}
+```
+
+Add only build assets to a production configuration. Add serve and Storybook assets
+only to the configurations that need them.

package/content/skills/styleguide/changesets.md

@@ -0,0 +1,17 @@
+# Changesets
+
+Read this fallback only when the repository has no more specific release workflow.
+
+- Add a changeset for a consumer-visible change to a published package.
+- Do not add one for formatting, comments, tests, or an internal refactor with no
+  consumer-visible effect.
+- Use `patch` for fixes, `minor` for backward-compatible API additions, and `major` for
+  breaking API or behavior changes.
+- Keep one logical release note focused. Split unrelated changes.
+- Write the note for the package consumer: state what they now get, not how the change
+  was implemented.
+- Keep the note to one sentence, two at most, under 40 words.
+- Do not run an interactive changeset command in a non-interactive agent environment;
+  write the repository's changeset file format directly.
+
+When a repository supplies its own release skill or policy, that local guidance wins.