@aurorajs.dev/catalyst-cli 1.0.0

package/dist/templates/codegen/partials/relationships/multiple-select.eta

@@ -0,0 +1,42 @@
+<%_
+  // Multi-select dropdown (Spartan-ng) for many-to-many FK relations. Uses
+  // <hlm-select-multiple> (the dedicated component) — NOT <hlm-select multiple>,
+  // which does not exist in the Spartan-ng API and silently degrades to single.
+  //
+  // The bound FormControl carries `string[]` (FK ids). The selected items are
+  // displayed via <ng-template hlmSelectValues> as a count summary; the
+  // <hlm-select-placeholder> shows when nothing is selected.
+  //
+  // [value]="option.id" keeps the FormControl as string[] (Aurora contract).
+  // [itemToString] converts a single id to its label for accessibility hints.
+  const relSingular = it.fmt.toCamelCase(it.mappers.getRelationshipSingularName(it.property));
+  const optionsName = relSingular + 'Options';
+  const isRequired = it.property.nullable === false && it.property.type !== 'boolean';
+_%>
+<hlm-field class="<%= it.colSpan %>">
+  <%~ include('/partials/form/field-label', it) %>
+  <hlm-select-multiple
+    formControlName="<%= it.propCamel %>"
+    [itemToString]="<%= relSingular %>ItemToString"
+  >
+    <hlm-select-trigger buttonId="<%= it.propCamel %>"<% if (isRequired) { %> aria-required="true"<% } %>>
+      <hlm-select-placeholder>{{ t('Select') }}</hlm-select-placeholder>
+      <ng-template hlmSelectValues let-values>
+        <hlm-select-values-content>
+          {{ <%= relSingular %>ItemToString(values[0]) }}
+          @if (values.length > 1) {
+            (+{{ values.length - 1 }})
+          }
+        </hlm-select-values-content>
+      </ng-template>
+    </hlm-select-trigger>
+    <hlm-select-content *hlmSelectPortal>
+      @for (option of <%= optionsName %>(); track option.id) {
+        <hlm-select-item [value]="option.id">{{ option.name }}</hlm-select-item>
+      }
+    </hlm-select-content>
+  </hlm-select-multiple>
+  <hlm-field-error>
+    {{ signalForm.get('<%= it.propCamel %>')?.errors | validationMessage }}
+  </hlm-field-error>
+</hlm-field>

package/dist/templates/codegen/partials/relationships/search-select.eta

@@ -0,0 +1,41 @@
+<%_
+  // Synchronous, searchable single-select for many-to-one FK with a medium
+  // catalog (20–500). All options preloaded by the route resolver — Spartan's
+  // default client-side filter handles type-to-filter UX without a server
+  // roundtrip. Uses `<au-search-select>`. Pure dumb component: bind via
+  // [value]/(valueChange) and mark form dirty manually.
+  //
+  // The component takes Option[], but the form receives the raw aggregate
+  // T[]. The T -> Option adaptation lives at the binding site via the
+  // centralized ToOptionsPipe in @aurora, parameterized with the target
+  // aggregate front.displayField (identifier wrapped as {id} or template
+  // shape {code} - {name}).
+  //
+  // Wrapped in <hlm-field> with the centralized label partial. The
+  // [inputId] binding connects <label for=...> to the internal Spartan
+  // <hlm-combobox-input id=...>, so click-on-label focuses the combobox
+  // input (depends on the companion `aurora-catalyst` PR exposing `inputId`
+  // on the wrapper).
+  const relSingular = it.fmt.toCamelCase(it.mappers.getRelationshipSingularName(it.property));
+  const optionsName = relSingular + 'Options';
+  const displayFieldTemplate = it.crossSchema.getTargetDisplayFieldTemplate(it.property.relationship.modulePath);
+  const isRequired = it.property.nullable === false && it.property.type !== 'boolean';
+_%>
+<hlm-field class="<%= it.colSpan %>">
+  <%~ include('/partials/form/field-label', it) %>
+  <au-search-select
+    [inputId]="'<%= it.propCamel %>'"
+    [value]="signalForm.controls['<%= it.propCamel %>'].value"
+    [options]="<%= optionsName %>() | toOptions:'<%= displayFieldTemplate %>'"
+    [placeholder]="t('Select')"
+    [emptyMessage]="t('NoResults')"
+<% if (isRequired) { -%>
+    aria-required="true"
+<% } -%>
+    (valueChange)="signalForm.controls['<%= it.propCamel %>'].setValue($event); signalForm.markAsDirty()"
+    (touched)="signalForm.controls['<%= it.propCamel %>'].markAsTouched()"
+  />
+  <hlm-field-error>
+    {{ signalForm.get('<%= it.propCamel %>')?.errors | validationMessage }}
+  </hlm-field-error>
+</hlm-field>

package/dist/templates/codegen/partials/relationships/select.eta

@@ -0,0 +1,27 @@
+<%_
+  // Single-select dropdown (Spartan-ng) for many-to-one FK relations.
+  // Bind via `formControlName`. Options come from the form's per-relation
+  // input signal `<relSingularName>Options` (target aggregate array).
+  const relSingular = it.fmt.toCamelCase(it.mappers.getRelationshipSingularName(it.property));
+  const optionsName = relSingular + 'Options';
+  const isRequired = it.property.nullable === false && it.property.type !== 'boolean';
+_%>
+<hlm-field class="<%= it.colSpan %>">
+  <%~ include('/partials/form/field-label', it) %>
+  <hlm-select
+    formControlName="<%= it.propCamel %>"
+    [itemToString]="<%= relSingular %>ItemToString"
+  >
+    <hlm-select-trigger buttonId="<%= it.propCamel %>"<% if (isRequired) { %> aria-required="true"<% } %>>
+      <hlm-select-value placeholder="{{ t('Select') }}" />
+    </hlm-select-trigger>
+    <hlm-select-content *hlmSelectPortal>
+      @for (option of <%= optionsName %>(); track option.id) {
+        <hlm-select-item [value]="option.id">{{ option.name }}</hlm-select-item>
+      }
+    </hlm-select-content>
+  </hlm-select>
+  <hlm-field-error>
+    {{ signalForm.get('<%= it.propCamel %>')?.errors | validationMessage }}
+  </hlm-field-error>
+</hlm-field>

package/dist/templates/frontend/application/.agents/skills/spartan/SKILL.md

@@ -0,0 +1,176 @@
+---
+name: spartan
+description: >-
+  Manages spartan/ui, the Angular UI library - adding, composing, fixing, debugging, and styling UI
+  with the Brain (headless primitives) and Helm (styled) layers. Provides project context, component
+  APIs, and usage examples. Applies when working with spartan/ui, @spartan-ng/brain, @spartan-ng/helm,
+  the @spartan-ng/cli generators, or any Angular project with a components.json file. Also triggers
+  for "spartan init", "add a spartan component", or "set up spartan/ui".
+user-invocable: false
+allowed-tools:
+  - Bash(npx nx g @spartan-ng/cli:*)
+  - Bash(pnpm nx g @spartan-ng/cli:*)
+  - Bash(ng g @spartan-ng/cli:*)
+---
+
+# spartan/ui
+
+spartan/ui is an Angular UI library. It uses a **two-layer architecture**:
+
+- **Brain (`@spartan-ng/brain`)** - accessible, unstyled primitives (Angular directives/components),
+  installed from npm. This is the behavior and accessibility layer.
+- **Helm (`@spartan-ng/helm`)** - the styled layer (Tailwind + class-variance-authority). Helm code
+  is **copied into the user's project** by the CLI so they own and can customize it.
+
+You compose Helm directives/components onto host elements; Helm wires up the matching Brain
+primitive under the hood. Always prefer existing components over hand-written markup.
+
+All CLI commands run through the workspace's runner. Detect it from the project:
+
+- **Nx workspace** (has `nx.json`): `npx nx g @spartan-ng/cli:<generator>` (or `pnpm nx g ...`).
+- **Angular CLI workspace** (has `angular.json`, no `nx.json`): `ng g @spartan-ng/cli:<generator>`.
+
+## Current project context
+
+Before generating any code, gather the project context:
+
+```bash
+npx nx g @spartan-ng/cli:info --json     # Nx
+ng g @spartan-ng/cli:info --json         # Angular CLI
+```
+
+This is read-only and prints JSON with:
+
+- `workspaceType` - `nx` | `angular-cli` (decides which runner to use above).
+- `config.componentsPath` - where Helm components are copied (e.g. `libs/ui`).
+- `config.importAlias` - the import prefix for Helm, default `@spartan-ng/helm`.
+- `config.generateAs` - `library` | `entrypoint` (Nx layout choice).
+- `versions` - Angular, Angular CDK, Tailwind, `@spartan-ng/brain`, `@spartan-ng/cli`.
+- `iconLibrary` - `@ng-icons` when present.
+- `tailwindCssFile` - the global stylesheet that imports the preset.
+- `installedComponents` - components already present (do not re-add these).
+- `availableComponents` - everything the CLI can generate.
+
+If `components.json` does not exist, the project is not set up yet - run `@spartan-ng/cli:init`
+first (it installs dependencies and the theme). `components.json` itself is created when you add the
+first component with `ui` (see `cli.md`).
+
+## Principles
+
+1. **Use existing components first.** Check `installedComponents`, then `availableComponents`. Find
+   docs via the MCP server (`spartan_components_list` / `spartan_components_get`) or the live docs at
+   `https://www.spartan.ng/components/<name>`. See `mcp.md`.
+2. **Compose, do not reinvent.** Build dashboards, forms, and dialogs from existing Helm + Brain
+   pieces rather than custom markup.
+3. **Use built-in variants before custom styles.** Buttons, badges, alerts, etc. ship `variant` and
+   `size` inputs - use them instead of overriding classes.
+4. **Use semantic colors, never raw values.** `bg-primary text-primary-foreground`, not
+   `bg-blue-500`. See `rules/styling.md`.
+
+## Critical rules
+
+Read the rule file before doing the related work:
+
+- **`rules/styling.md`** - the `hlm()` util, semantic color tokens, layout-only classes,
+  `gap-*` over `space-*`, `size-*`, dark mode, no manual z-index on overlays.
+- **`rules/forms.md`** - compose forms with `hlmField` (label, control, error, description) and
+  `hlmFieldSet` / `hlmFieldLegend` on native `<fieldset>`/`<legend>`; option sets (2-7 choices) use
+  `hlm-toggle-group`.
+- **`rules/composition.md`** - items belong inside their group; dialogs/sheets need a title;
+  full Card composition; tabs triggers inside `hlm-tabs-list`; avatar always has a fallback;
+  use `Alert`/`Empty`/`Skeleton`/`Badge`/`Separator`/`Spinner` instead of custom markup.
+- **`rules/icons.md`** - icons are `<ng-icon hlm name="lucide...">`; register with `provideIcons`;
+  no manual sizing classes inside components - use the `size` input.
+- **`rules/brain-vs-helm.md`** - the two-layer model (one headless library, Brain, plus the styled
+  Helm layer); when to reach for Brain directly vs Helm, and how composition works via directives.
+- **`cli.md`** - every generator (`init`, `ui`, `ui-theme`, `healthcheck`, `info`, `migrate-*`),
+  with Nx and Angular CLI invocations.
+- **`registry.md`** - the Brain-npm + Helm-copy-in distribution model, `components.json`, and the
+  fixed component catalog (the shipped CLI uses no remote or custom registry).
+- **`customization.md`** - theming via the `hlm-tailwind-preset.css`, CSS variables, the `ui-theme`
+  generator, and extending copied Helm components.
+- **`mcp.md`** - using the `@spartan-ng/mcp` tools, resources, and prompts for discovery.
+
+## Key patterns
+
+```html
+<!-- Buttons: use variant/size inputs, not custom classes -->
+<button hlmBtn variant="destructive" size="lg">Delete</button>
+
+<!-- Icon in a button: ng-icon + hlm, no sizing classes -->
+<button hlmBtn size="icon" variant="ghost">
+	<ng-icon hlm name="lucideTrash" size="sm" />
+</button>
+
+<!-- Loading state: compose a spinner, there is no isLoading input -->
+<button hlmBtn [disabled]="loading()">
+	@if (loading()) {
+	<hlm-spinner />
+	} Save
+</button>
+
+<!-- Layout: gap, not space-* ; size-* when width == height -->
+<div class="flex items-center gap-2">
+	<span hlmBadge variant="secondary">beta</span>
+</div>
+```
+
+## Component selection
+
+| Need                   | Component(s)                                                                                |
+| ---------------------- | ------------------------------------------------------------------------------------------- |
+| Action / button        | `button` (`hlmBtn`), `button-group`                                                         |
+| Text/number input      | `input`, `textarea`, `input-otp`, `input-group`, `native-select`                            |
+| Choice input           | `select`, `combobox`, `autocomplete`, `radio-group`, `checkbox`, `switch`, `slider`         |
+| Toggle 2-7 options     | `toggle-group`                                                                              |
+| Form layout/validation | `field`, `label`                                                                            |
+| Data display           | `table`, `card`, `badge`, `avatar`, `kbd`, `item`                                           |
+| Navigation             | `sidebar`, `navigation-menu`, `breadcrumb`, `tabs`, `pagination`                            |
+| Overlays               | `dialog`, `sheet`, `alert-dialog`, `popover`, `hover-card`, `tooltip`                       |
+| Menus                  | `dropdown-menu`, `context-menu`, `menubar`, `command`                                       |
+| Feedback               | `sonner` (toasts), `alert`, `progress`, `skeleton`, `spinner`                               |
+| Layout/containers      | `card`, `separator`, `resizable`, `scroll-area`, `accordion`, `collapsible`, `aspect-ratio` |
+| Empty states           | `empty`                                                                                     |
+| Dates                  | `calendar`, `date-picker`                                                                   |
+| Icons                  | `icon` (`@ng-icons`)                                                                        |
+| Typography             | `typography`                                                                                |
+
+## Workflow
+
+1. **Get context.** Run `@spartan-ng/cli:info --json`. If the project is not set up, run `:init`,
+   then add components with `:ui` (the first `:ui` run creates `components.json`).
+2. **Check what is installed.** Do not re-add anything in `installedComponents`.
+3. **Find the component.** Use the MCP tools or `https://www.spartan.ng/components/<name>` for the
+   API and examples (`mcp.md`). Never guess selectors - confirm them.
+4. **Add it.** `npx nx g @spartan-ng/cli:ui --name=<component>` (Nx) or
+   `ng g @spartan-ng/cli:ui --name=<component>` (Angular CLI). This installs the Brain dependency and
+   copies the Helm code. Omit `--name` to get an interactive multiselect.
+5. **Compose correctly.** Import the `*Imports` const (e.g. `HlmDialogImports`) or the individual
+   classes from the import alias, add them to the standalone component's `imports`, and follow the
+   composition rules.
+6. **Register icons.** Any `<ng-icon>` you use must be passed to `provideIcons(...)` (see
+   `rules/icons.md`).
+7. **Verify.** After bigger changes or upgrades, run `@spartan-ng/cli:healthcheck` to catch
+   deprecated patterns and fix imports.
+8. **Theme/customize.** Edit the copied Helm files and the CSS variables; do not fork Brain.
+
+## Quick reference
+
+```bash
+# Initialize (creates components.json, wires Tailwind + preset)
+npx nx g @spartan-ng/cli:init
+ng g @spartan-ng/cli:init
+
+# Project context as JSON
+npx nx g @spartan-ng/cli:info --json
+
+# Add components (interactive, or pass --name)
+npx nx g @spartan-ng/cli:ui
+npx nx g @spartan-ng/cli:ui --name=dialog
+
+# Generate theme variables
+npx nx g @spartan-ng/cli:ui-theme
+
+# Scan + auto-fix deprecated APIs/imports after an upgrade
+npx nx g @spartan-ng/cli:healthcheck --autoFix
+```

package/dist/templates/frontend/application/.agents/skills/spartan/cli.md

@@ -0,0 +1,92 @@
+# CLI reference (`@spartan-ng/cli`)
+
+The CLI is an Nx plugin that also runs as Angular CLI schematics. Pick the invocation that matches
+the workspace (`info --json` reports `workspaceType`):
+
+- **Nx** (`nx.json` present): `npx nx g @spartan-ng/cli:<generator>` (or `pnpm nx g ...`).
+- **Angular CLI** (`angular.json`, no `nx.json`): `ng g @spartan-ng/cli:<generator>`.
+
+Install the plugin first: `npm i -D @spartan-ng/cli`.
+
+## Core generators
+
+### `init`
+
+One-time setup. Installs the required dependencies and runs the theme generator (Tailwind + the
+spartan preset and CSS variables).
+
+```bash
+npx nx g @spartan-ng/cli:init
+ng g @spartan-ng/cli:init
+```
+
+`components.json` is not written by `init`; it is created on the first `ui` run, which prompts for
+the components path (e.g. `libs/ui`), the import alias (default `@spartan-ng/helm`), and on Nx
+whether libraries are buildable and the `generateAs` strategy.
+
+### `ui`
+
+Adds components. Installs the Brain dependency from npm and copies the Helm code into
+`componentsPath`. Run with no name for an interactive multiselect, or target one component:
+
+```bash
+npx nx g @spartan-ng/cli:ui                 # interactive multiselect (choose 'all' or specific)
+npx nx g @spartan-ng/cli:ui --name=dialog   # add a single component
+ng g @spartan-ng/cli:ui --name=button
+```
+
+Dependent components are pulled in automatically.
+
+### `ui-theme`
+
+Generates the CSS theme variables (light + dark) into your stylesheet.
+
+```bash
+npx nx g @spartan-ng/cli:ui-theme
+ng g @spartan-ng/cli:ui-theme
+```
+
+### `info`
+
+Read-only. Prints project context. Add `--json` for machine-readable output (use this for agents).
+
+```bash
+npx nx g @spartan-ng/cli:info --json
+ng g @spartan-ng/cli:info --json
+```
+
+Fields: `workspaceType`, `config` (`componentsPath`, `importAlias`, `buildable`, `generateAs`),
+`versions`, `iconLibrary`, `tailwindCssFile`, `installedComponents`, `availableComponents`.
+
+### `healthcheck`
+
+Scans the workspace for deprecated APIs, outdated imports, and breaking changes; can auto-fix.
+
+```bash
+npx nx g @spartan-ng/cli:healthcheck            # report only
+npx nx g @spartan-ng/cli:healthcheck --autoFix  # apply fixes
+ng g @spartan-ng/cli:healthcheck --autoFix
+```
+
+Run it after upgrading `@spartan-ng` packages.
+
+## Migration generators
+
+The `migrate-*` family upgrades specific components/APIs (e.g. `migrate-brain-imports`,
+`migrate-helm-imports`, `migrate-module-imports`, `migrate-naming-conventions`, `migrate-select`,
+`migrate-icon`, and more - see `generators.json` for the full list). In normal use you do not invoke
+these directly - run `healthcheck`, which scans for the same problems and applies the fixes
+automatically. Invoke a single migration only when targeting a specific upgrade:
+
+```bash
+npx nx g @spartan-ng/cli:migrate-helm-imports
+```
+
+## Typical sequence
+
+```bash
+npm i -D @spartan-ng/cli
+npx nx g @spartan-ng/cli:init
+npx nx g @spartan-ng/cli:ui-theme
+npx nx g @spartan-ng/cli:ui --name=button
+```

package/dist/templates/frontend/application/.agents/skills/spartan/customization.md

@@ -0,0 +1,88 @@
+# Theming and customization
+
+## Setup
+
+spartan/ui requires Tailwind CSS (v4 recommended; v3 is not guaranteed). The global stylesheet needs
+the Tailwind layers and the spartan preset.
+
+```css
+/* src/styles.css */
+@layer theme, base, components, utilities;
+@import 'tailwindcss/theme.css' layer(theme);
+@import 'tailwindcss/preflight.css' layer(base);
+@import 'tailwindcss/utilities.css';
+```
+
+```css
+/* src/styles.css - add the spartan preset (bundles tw-animate-css + the CDK overlay styles) */
+@import '@spartan-ng/brain/hlm-tailwind-preset.css';
+```
+
+## Theme variables
+
+Colors are driven by CSS variables (OKLCH) in `:root` (light) and `.dark` (dark). Generate them with
+the CLI:
+
+```bash
+npx nx g @spartan-ng/cli:ui-theme
+ng g @spartan-ng/cli:ui-theme
+```
+
+Or add them manually. The semantic tokens are: `background`, `foreground`, `card`/`card-foreground`,
+`popover`/`popover-foreground`, `primary`/`primary-foreground`, `secondary`/`secondary-foreground`,
+`muted`/`muted-foreground`, `accent`/`accent-foreground`, `destructive`, `border`, `input`, `ring`,
+plus `--radius` and the `sidebar*` family. Reference them in templates via the matching Tailwind
+classes (`bg-primary`, `text-muted-foreground`, `border-border`, ...). See `rules/styling.md`.
+
+```css
+:root {
+	color-scheme: light;
+	--radius: 0.625rem;
+	--background: oklch(1 0 0);
+	--foreground: oklch(0.145 0 0);
+	--primary: oklch(0.205 0 0);
+	--primary-foreground: oklch(0.985 0 0);
+	/* ...rest of the tokens... */
+}
+
+.dark {
+	color-scheme: dark;
+	--background: oklch(0.145 0 0);
+	--foreground: oklch(0.985 0 0);
+	/* ...dark overrides... */
+}
+```
+
+## Adding a custom color
+
+Define the variable in both `:root` and `.dark`, then expose it to Tailwind with `@theme inline` so
+`bg-warning` / `text-warning-foreground` work:
+
+```css
+:root {
+	--warning: oklch(0.84 0.16 84);
+	--warning-foreground: oklch(0.28 0.07 46);
+}
+.dark {
+	--warning: oklch(0.41 0.11 46);
+	--warning-foreground: oklch(0.99 0.02 95);
+}
+
+@theme inline {
+	--color-warning: var(--warning);
+	--color-warning-foreground: var(--warning-foreground);
+}
+```
+
+## Dark mode
+
+Dark mode is class-based: toggle the `dark` class on the `<html>` (or root) element and the
+variables switch automatically. No component changes are needed. Typically a small service persists
+the choice to `localStorage` and respects the system color scheme.
+
+## Customizing components
+
+Because Helm code is copied into your project, customize by editing those files directly - adjust the
+`class-variance-authority` variants, change classes, or add inputs. Do not fork or edit the Brain
+packages. After spartan upgrades, run `@spartan-ng/cli:healthcheck --autoFix` to reconcile
+deprecated APIs.

package/dist/templates/frontend/application/.agents/skills/spartan/mcp.md

@@ -0,0 +1,76 @@
+# Using the spartan MCP server
+
+`@spartan-ng/mcp` is a Model Context Protocol server that exposes spartan's component docs, APIs,
+examples, blocks, and accessibility info (sourced from `https://www.spartan.ng` with a local cache).
+When it is connected, use it for discovery instead of guessing selectors or fetching pages by hand.
+
+## Configuration
+
+No install (recommended):
+
+```json
+{
+	"mcpServers": {
+		"spartan-ui": { "command": "npx", "args": ["-y", "@spartan-ng/mcp"] }
+	}
+}
+```
+
+Global install:
+
+```bash
+npm install -g @spartan-ng/mcp
+```
+
+```json
+{
+	"mcpServers": { "spartan-ui": { "command": "spartan-mcp" } }
+}
+```
+
+## Tools
+
+Components and analysis:
+
+- `spartan_components_list` - all components with their docs URLs.
+- `spartan_components_get` - fetch a component page; `extract: "code" | "api"`.
+- `spartan_components_dependencies` - npm/CDK/peer-component dependencies for a component.
+- `spartan_accessibility_check` - ARIA/keyboard/WCAG notes for a component.
+
+Blocks (prebuilt multi-component layouts - `sidebar`, `login`, `signup`, `calendar`):
+
+- `spartan_blocks_list`, `spartan_blocks_get` (`format: "html" | "text"`), `spartan_blocks_dependencies`.
+
+Docs and meta:
+
+- `spartan_docs_get` - a docs topic (installation, cli, theming, dark-mode, ...);
+  `extract: "none" | "code" | "headings" | "links"`.
+- `spartan_meta` - topics/components/blocks index for autocomplete.
+
+Health and cache:
+
+- `spartan_health_check`, `spartan_health_instructions`, `spartan_health_command`.
+- `spartan_cache_status`, `spartan_cache_clear`, `spartan_cache_rebuild`,
+  `spartan_cache_switch_version`, `spartan_cache_list_versions`.
+
+## Resources
+
+- `spartan://components/list`
+- `spartan://component/{name}/api`
+- `spartan://component/{name}/examples`
+- `spartan://component/{name}/full`
+
+## Prompts
+
+`spartan-get-started`, `spartan-compare-apis`, `spartan-implement-feature`, `spartan-troubleshoot`,
+`spartan-list-components`.
+
+## Recommended flow
+
+1. `spartan_components_get` with `extract: "api"` to confirm selectors and inputs.
+2. `spartan_components_get` with `extract: "code"` for a working example.
+3. `spartan_components_dependencies` if you need to know what else gets installed.
+4. Then add via the CLI (`@spartan-ng/cli:ui --name=<component>`).
+
+If the MCP server is not connected, fall back to `https://www.spartan.ng/components/<name>` and the
+`@spartan-ng/cli:info --json` output.

package/dist/templates/frontend/application/.agents/skills/spartan/registry.md

@@ -0,0 +1,51 @@
+# Distribution and registry
+
+## The spartan model
+
+spartan/ui is **not** a single installed UI library. It uses a two-layer model:
+
+- **Brain** primitives are real npm packages (`@spartan-ng/brain/<name>`), installed into
+  `node_modules`. You do not edit them.
+- **Helm** styled components are **copied into your project** (under `componentsPath`) by the CLI.
+  You own this code and customize it freely.
+
+This is why there is no "upgrade my installed components" button: Brain updates via npm + the
+`healthcheck` migrations, while Helm code is yours to edit and re-generate.
+
+## `components.json`
+
+`components.json` is written at the project root on the first `ui` run (not by `init`). It is the
+project marker the skill triggers on and the source of paths/aliases.
+
+```json
+{
+	"componentsPath": "libs/ui",
+	"importAlias": "@spartan-ng/helm",
+	"buildable": true,
+	"generateAs": "library"
+}
+```
+
+- `componentsPath` - where Helm code is copied.
+- `importAlias` - the import prefix for the copied Helm components (default `@spartan-ng/helm`).
+- `buildable` - Nx only: whether generated libraries are buildable.
+- `generateAs` - Nx only: `library` (one Nx library per component) or `entrypoint` (secondary
+  entrypoints under a single library).
+
+The Angular CLI variant only uses `componentsPath` and `importAlias`.
+
+Read these values via `@spartan-ng/cli:info --json` rather than parsing the file yourself - the
+`info` command applies defaults and reports `installedComponents`.
+
+## Available components
+
+The CLI ships a fixed catalog of components (the `availableComponents` in `info --json`). Add any of
+them with `ui --name=<component>`. The shipped CLI does not wire up any remote or custom registry;
+components come only from this bundled catalog.
+
+## Custom usage
+
+When generating into a non-default layout, pass `--directory` to `ui`, or set `componentsPath` /
+`importAlias` in `components.json` before running. Do not invent registry URLs or remote sources -
+if a user asks for a component that is not in `availableComponents`, tell them it is not in the
+catalog rather than guessing.

package/dist/templates/frontend/application/.agents/skills/spartan/rules/brain-vs-helm.md

@@ -0,0 +1,59 @@
+# Brain vs Helm
+
+spartan has a single headless library, **Brain**. There is no choice between competing primitive
+libraries and no per-variant API switch - every component has one API. Each spartan component is
+built from **two layers**:
+
+| Layer     | Package                    | Role                                                                           | Distribution                                              |
+| --------- | -------------------------- | ------------------------------------------------------------------------------ | --------------------------------------------------------- |
+| **Brain** | `@spartan-ng/brain/<name>` | Headless behavior + accessibility (Angular directives/components). No styling. | Installed from npm.                                       |
+| **Helm**  | `@spartan-ng/helm/<name>`  | Tailwind styling layered on top of Brain.                                      | Copied into your project by the CLI; you own and edit it. |
+
+## Which one do I use?
+
+- **Use Helm by default.** It is the styled component. When you "add a dialog," you use
+  `HlmDialogImports`, which already composes the Brain dialog internally.
+- **Use Brain directly** only when you need fully custom styling and want the behavior/accessibility
+  without spartan's look - i.e. you are building your own styled layer. Then import from
+  `@spartan-ng/brain/<name>` and apply your own classes.
+- **Never edit Brain.** It is an npm dependency. Customize by editing the copied Helm files or the
+  theme variables.
+
+## Composition uses directives
+
+Composition is done with **directives applied to host elements** and **structural directives** for
+portals/content - there is no wrapper prop that swaps the rendered element.
+
+- Triggers are directives you put on your own element: `<button hlmDialogTrigger hlmBtn>` makes a
+  styled button act as the dialog trigger.
+- Content is projected into structural directives: `<hlm-dialog-content *hlmDialogPortal>`,
+  `<hlm-select-content *hlmSelectPortal>`, `<hlm-sheet-content *hlmSheetPortal>`.
+- To restyle a trigger or item, you change the classes/variant on your host element directly - no
+  wrapper prop needed.
+
+## Imports
+
+Each component publishes an `*Imports` barrel (e.g. `HlmDialogImports`, `HlmSelectImports`,
+`HlmCardImports`) plus the individual classes. Add the barrel to a standalone component's `imports`
+array:
+
+```ts
+import { HlmDialogImports } from '@spartan-ng/helm/dialog';
+
+@Component({
+  imports: [HlmDialogImports],
+  // ...
+})
+```
+
+The entrypoint name matches the component name in kebab-case (e.g. `@spartan-ng/helm/alert-dialog`,
+`@spartan-ng/brain/toggle-group`). When unsure, confirm the exact path from the component docs or
+MCP rather than guessing.
+
+## Per-component notes
+
+- **select / toggle-group / radio-group / accordion / tabs**: the Brain layer owns
+  keyboard/selection behavior; you compose Helm items inside the Helm group as shown in
+  `rules/composition.md`.
+- **dialog / sheet / popover / tooltip / menus**: rely on the Angular CDK overlay (a peer
+  dependency). Do not manage z-index yourself (see `rules/styling.md`).