@aurorajs.dev/catalyst-cli 1.0.0

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

@@ -0,0 +1,76 @@
+# Spartan MCP Server
+
+The MCP server lets AI assistants discover, browse, install, and verify Spartan Angular UI components.
+
+---
+
+## Tools
+
+> **Tip:** MCP tools handle discovery and source code. For project config, use `spartan_project_info`. For installation, use `spartan_install_command` which generates ready-to-run CLI commands.
+
+### Discovery
+
+- **`spartan_list`** — List all components and blocks. Filter by type (`components`, `blocks`) or block category.
+- **`spartan_search`** — Fuzzy search across components, blocks, and docs. Scope to `components`, `blocks`, `docs`, or `all`.
+- **`spartan_view`** — View detailed component API: Brain directives, Helm components, inputs/outputs, signal models, code examples, install snippets. Sections: `api`, `examples`, `install`, `all`.
+- **`spartan_dependencies`** — Show component dependency graph: direct deps, transitive deps (configurable depth), and reverse dependents.
+
+### Source Code
+
+- **`spartan_source`** — Fetch Brain/Helm TypeScript source from GitHub. Specify `brain`, `helm`, or `both`.
+- **`spartan_block_source`** — Fetch block source code + shared utilities + extracted imports.
+
+### Documentation
+
+- **`spartan_docs`** — Fetch documentation topics: `installation`, `cli`, `theming`, `dark-mode`, `typography`, `figma`, `changelog`.
+
+### Installation
+
+- **`spartan_install_command`** — Generate `nx generate` or `npm install` commands for one or more components. Auto-detects package manager.
+- **`spartan_audit`** — Post-installation verification: Angular project, Tailwind config, Spartan preset, Brain/Helm pairing, OnPush reminder.
+
+### Project Context
+
+- **`spartan_project_info`** — Detect Angular/Nx project: Angular version, Nx workspace, Tailwind version, installed Spartan packages, package manager, zoneless mode.
+- **`spartan_project_components`** — List installed Brain/Helm packages with missing pair detection.
+
+### Cache & Registry
+
+- **`spartan_cache`** — Check cache status, clear, or trigger rebuild. Shows memory + file stats and GitHub rate limit.
+- **`spartan_registry_refresh`** — Refresh component registry from live Analog API. Reports added/updated/removed components.
+
+---
+
+## Workflow
+
+1. Use `spartan_project_info` to understand the project
+2. Use `spartan_search` to find components
+3. Use `spartan_view` to get API details and examples
+4. Use `spartan_dependencies` to check what else is needed
+5. Use `spartan_install_command` to generate install commands
+6. Run the install command
+7. Use `spartan_audit` to verify installation
+
+---
+
+## Resources (spartan:// URIs)
+
+| URI | Description |
+|-----|-------------|
+| `spartan://components/list` | All components with Brain/Helm availability |
+| `spartan://blocks/list` | All blocks by category |
+| `spartan://project/info` | Registry metadata |
+| `spartan://component/{name}/api` | Brain & Helm API for a component |
+| `spartan://component/{name}/examples` | Code examples for a component |
+
+---
+
+## Prompts
+
+| Prompt | Purpose |
+|--------|---------|
+| `spartan-get-started` | Installation + API overview + basic usage for a component |
+| `spartan-compare-layers` | Side-by-side Brain vs Helm comparison |
+| `spartan-implement` | Step-by-step feature implementation guide |
+| `spartan-use-block` | Block integration guide with source fetching |
+| `spartan-migrate` | Version migration guide with generators |

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

@@ -0,0 +1,114 @@
+# Brain vs Helm
+
+## Contents
+
+- When to use Brain vs Helm
+- Never mix layers on the same element
+- hostDirectives composition
+- Selector conventions
+- CDK-based components (no Brain)
+
+---
+
+## When to use Brain vs Helm
+
+| Scenario | Use |
+|----------|-----|
+| Standard styled component | **Helm** — comes with Tailwind styling and CVA variants |
+| Custom-styled component | **Brain** — headless, apply your own styles |
+| Building a component library | **Brain** — consumers apply their own styling |
+| Quick prototyping | **Helm** — ready-to-use, zero configuration |
+| Accessibility-only behavior | **Brain** — gets ARIA, keyboard, focus management |
+
+---
+
+## Never mix Brain and Helm selectors on the same element
+
+**Incorrect:**
+
+```html
+<!-- Don't apply Brain directive on a Helm component -->
+<button hlmBtn brnButton>Click me</button>
+```
+
+**Correct:**
+
+```html
+<!-- Helm already wraps Brain internally via hostDirectives -->
+<button hlmBtn>Click me</button>
+```
+
+---
+
+## hostDirectives composition
+
+Helm components use Angular's `hostDirectives` to compose Brain directives internally:
+
+```typescript
+// How HlmButton works internally (you don't write this — Spartan does)
+@Directive({
+  selector: 'button[hlmBtn], a[hlmBtn]',
+  hostDirectives: [
+    { directive: BrnButton, inputs: ['disabled'] }
+  ],
+})
+export class HlmButtonDirective { /* adds CVA variant styling */ }
+```
+
+**Using Helm in your template — just use Helm:**
+
+```html
+<button hlmBtn variant="outline" size="sm">Click me</button>
+```
+
+Some Helm components use **class inheritance** instead of hostDirectives:
+
+```typescript
+// HlmDialog extends BrnDialog (not hostDirectives)
+export class HlmDialog extends BrnDialog { }
+```
+
+---
+
+## Selector conventions
+
+Both layers use **mixed selector patterns**. Do not assume a single pattern.
+
+| Layer | Prefix | Selector Patterns | Examples |
+|-------|--------|-------------------|---------|
+| Brain | `brn` | Mostly attribute, some element, some both | `[brnDialogTrigger]`, `brn-avatar`, `[brnDialog],brn-dialog` |
+| Helm | `hlm` | Attribute, element, or both | `[hlmBtn]`, `hlm-dialog-content`, `[hlmCard],hlm-card` |
+
+**Common patterns:**
+
+- Directives that attach to existing elements → attribute selectors: `[hlmBtn]` on `<button>`
+- Self-contained UI elements → element selectors: `hlm-dialog-content`, `hlm-spinner`
+- Flexible components → both: `[hlmCard],hlm-card` — use either
+- Restricted selectors → `button[brnDialogTrigger]` (attribute only on `<button>` elements)
+
+---
+
+## CDK-based components (no Brain layer)
+
+Some Helm components wrap `@angular/cdk` directly instead of Brain:
+
+| Component | Helm wraps | Note |
+|-----------|-----------|------|
+| DropdownMenu | `@angular/cdk/menu` (`CdkMenu`) | No `BrnDropdownMenu` exists |
+| ContextMenu | `@angular/cdk/menu` (`CdkContextMenuTrigger`) | No `BrnContextMenu` exists |
+| Menubar | `@angular/cdk/menu` (`CdkMenuBar`) | No `BrnMenubar` exists |
+
+For these components, only import from `@spartan-ng/helm/*`. There is no Brain package to install.
+
+**Incorrect:**
+
+```typescript
+// This doesn't exist
+import { BrnDropdownMenu } from '@spartan-ng/brain/dropdown-menu';
+```
+
+**Correct:**
+
+```typescript
+import { HlmDropdownMenuComponent } from '@spartan-ng/helm/dropdown-menu';
+```

package/dist/templates/frontend/application/.claude/skills/spartan/rules/composition.md

@@ -0,0 +1,151 @@
+# Component Composition
+
+## Contents
+
+- Dialog always needs a Title
+- Full Card composition
+- TabsTrigger inside TabsList
+- Avatar needs AvatarFallback
+- Overlay selection guide
+- Use components, not custom markup
+
+---
+
+## Dialog always needs a Title
+
+`hlmDialogTitle` is required for accessibility. Use `class="sr-only"` if visually hidden.
+
+**Incorrect:**
+
+```html
+<brn-dialog>
+  <button brnDialogTrigger hlmBtn>Open</button>
+  <hlm-dialog-content *brnDialogContent>
+    <p>Content without a title</p>
+  </hlm-dialog-content>
+</brn-dialog>
+```
+
+**Correct:**
+
+```html
+<brn-dialog>
+  <button brnDialogTrigger hlmBtn>Open</button>
+  <hlm-dialog-content *brnDialogContent>
+    <hlm-dialog-header>
+      <h3 hlmDialogTitle>Edit Profile</h3>
+      <p hlmDialogDescription>Update your details.</p>
+    </hlm-dialog-header>
+    <!-- content here -->
+    <hlm-dialog-footer>
+      <button hlmBtn hlmDialogClose>Close</button>
+    </hlm-dialog-footer>
+  </hlm-dialog-content>
+</brn-dialog>
+```
+
+**Key patterns:**
+
+- `brnDialogTrigger` is an attribute on `<button>` (not an element component)
+- `hlm-dialog-content` is an element component with `*brnDialogContent` structural directive
+- `hlmDialogClose` is Helm — don't mix with `brnDialogClose` on the same element
+- Same pattern applies to **Sheet** (`hlmSheetTitle`) and **AlertDialog** (`hlmAlertDialogTitle`)
+
+---
+
+## Full Card composition
+
+Don't dump everything into a single element.
+
+**Incorrect:**
+
+```html
+<section hlmCard>
+  <h2>Title</h2>
+  <p>Everything dumped together</p>
+</section>
+```
+
+**Correct:**
+
+```html
+<section hlmCard>
+  <div hlmCardHeader>
+    <h3 hlmCardTitle>Team Members</h3>
+    <p hlmCardDescription>Manage your team.</p>
+  </div>
+  <div hlmCardContent>
+    <!-- content -->
+  </div>
+  <div hlmCardFooter>
+    <button hlmBtn>Invite</button>
+  </div>
+</section>
+```
+
+---
+
+## TabsTrigger inside TabsList
+
+Never render triggers directly in Tabs.
+
+**Incorrect:**
+
+```html
+<brn-tabs value="account">
+  <button brnTabsTrigger="account">Account</button>
+  <button brnTabsTrigger="password">Password</button>
+  <div brnTabsContent="account">...</div>
+</brn-tabs>
+```
+
+**Correct:**
+
+```html
+<brn-tabs value="account">
+  <brn-tabs-list hlmTabsList>
+    <button brnTabsTrigger="account" hlmTabsTrigger>Account</button>
+    <button brnTabsTrigger="password" hlmTabsTrigger>Password</button>
+  </brn-tabs-list>
+  <div brnTabsContent="account" hlmTabsContent>...</div>
+</brn-tabs>
+```
+
+---
+
+## Avatar always needs AvatarFallback
+
+**Correct:**
+
+```html
+<brn-avatar hlmAvatar>
+  <brn-avatar-image hlmAvatarImage src="/avatar.png" alt="User" />
+  <brn-avatar-fallback hlmAvatarFallback>JD</brn-avatar-fallback>
+</brn-avatar>
+```
+
+---
+
+## Overlay selection guide
+
+| Use case | Component |
+|----------|-----------|
+| Focused task that requires input | `BrnDialog` + `HlmDialog*` |
+| Destructive action confirmation | `BrnAlertDialog` + `HlmAlertDialog*` |
+| Side panel with details or filters | `BrnSheet` + `HlmSheet*` |
+| Quick info on hover | `BrnHoverCard` + `HlmHoverCard*` |
+| Contextual content on click | `BrnPopover` + `HlmPopover*` |
+| Command palette | `BrnCommand` inside `BrnDialog` |
+
+---
+
+## Use components, not custom markup
+
+| Instead of | Use |
+|------------|-----|
+| `<hr>` or `<div class="border-t">` | `<brn-separator hlmSeparator />` |
+| `<div class="animate-pulse">` with styled divs | `<hlm-skeleton class="h-4 w-3/4" />` |
+| `<span class="rounded-full bg-green-100 ...">` | `<span hlmBadge variant="secondary">` |
+| Custom styled callout div | `<div hlmAlert>` with `hlmAlertTitle` + `hlmAlertDescription` |
+| Custom empty state markup | `<hlm-empty>` with title, description, action |
+| Custom toast implementation | `<hlm-toaster />` + `toast()` from `@spartan-ng/brain/sonner` |

package/dist/templates/frontend/application/.claude/skills/spartan/rules/directives.md

@@ -0,0 +1,173 @@
+# Angular Directive Patterns
+
+## Contents
+
+- Signals for reactive state
+- Standalone is default (Angular 19+)
+- New control flow syntax
+- `inject()` for dependency injection
+- Import organization
+- OnPush change detection
+
+---
+
+## Use signals for reactive state
+
+**Incorrect:**
+
+```typescript
+@Component({...})
+export class MyComponent {
+  @Input() name: string = '';
+  @Output() nameChange = new EventEmitter<string>();
+  isOpen = false;
+}
+```
+
+**Correct:**
+
+```typescript
+@Component({...})
+export class MyComponent {
+  name = input<string>('');
+  nameChange = output<string>();
+  isOpen = signal(false);
+
+  displayName = computed(() => this.name().toUpperCase());
+}
+```
+
+Also available: `linkedSignal()` for writable derived signals, and `model()` for two-way binding signals.
+
+---
+
+## Standalone is default (Angular 19+)
+
+Do not write `standalone: true` — it's the default.
+
+**Incorrect:**
+
+```typescript
+@NgModule({
+  declarations: [MyComponent],
+  imports: [HlmButtonModule],
+})
+export class MyModule {}
+
+// Also incorrect — redundant
+@Component({ standalone: true, ... })
+```
+
+**Correct:**
+
+```typescript
+@Component({
+  imports: [HlmButtonDirective, BrnDialogComponent],
+  template: `...`,
+})
+export class MyComponent {}
+```
+
+---
+
+## Use new control flow syntax
+
+**Incorrect:**
+
+```html
+<div *ngIf="isOpen">Content</div>
+<div *ngFor="let item of items">{{ item.name }}</div>
+<div [ngSwitch]="status">
+  <span *ngSwitchCase="'active'">Active</span>
+</div>
+```
+
+**Correct:**
+
+```html
+@if (isOpen()) {
+  <div>Content</div>
+}
+
+@for (item of items(); track item.id) {
+  <div>{{ item.name }}</div>
+} @empty {
+  <hlm-empty>
+    <p>No items found.</p>
+  </hlm-empty>
+}
+
+@switch (status()) {
+  @case ('active') { <span hlmBadge>Active</span> }
+  @case ('inactive') { <span hlmBadge variant="secondary">Inactive</span> }
+}
+```
+
+---
+
+## Use `inject()` for dependency injection
+
+**Incorrect:**
+
+```typescript
+export class MyComponent {
+  constructor(
+    private fb: FormBuilder,
+    private router: Router,
+    private destroyRef: DestroyRef,
+  ) {}
+}
+```
+
+**Correct:**
+
+```typescript
+export class MyComponent {
+  private readonly _fb = inject(FormBuilder);
+  private readonly _router = inject(Router);
+  private readonly _destroyRef = inject(DestroyRef);
+}
+```
+
+---
+
+## Import organization
+
+```typescript
+// 1. Angular core
+import { Component, inject, signal, computed, input, ChangeDetectionStrategy } from '@angular/core';
+import { FormBuilder, ReactiveFormsModule, Validators } from '@angular/forms';
+
+// 2. Spartan Brain
+import { BrnDialogComponent, BrnDialogTriggerDirective } from '@spartan-ng/brain/dialog';
+import { BrnSelectComponent } from '@spartan-ng/brain/select';
+
+// 3. Spartan Helm
+import { HlmDialogContentComponent, HlmDialogHeaderComponent } from '@spartan-ng/helm/dialog';
+import { HlmButtonDirective } from '@spartan-ng/helm/button';
+
+// 4. Spartan utils
+import { hlm, classes } from '@spartan-ng/helm/utils';
+
+// 5. Icons
+import { HlmIconImports } from '@spartan-ng/helm/icon';
+import { provideIcons } from '@ng-icons/core';
+import { lucideCheck, lucideSearch } from '@ng-icons/lucide';
+```
+
+---
+
+## OnPush change detection
+
+All Spartan components use OnPush. Your components should too.
+
+```typescript
+@Component({
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  imports: [HlmButtonDirective],
+  template: `<button hlmBtn>Click</button>`,
+})
+export class MyComponent {}
+```
+
+This works seamlessly with signals — `input()`, `signal()`, `computed()` all trigger OnPush change detection automatically.

package/dist/templates/frontend/application/.claude/skills/spartan/rules/forms.md

@@ -0,0 +1,104 @@
+# Forms
+
+## Contents
+
+- HlmField system for form layout
+- Angular Reactive Forms with Spartan
+- Form control selection guide
+- Validation states
+- FieldSet for grouping related fields
+
+---
+
+## HlmField system for form layout
+
+Spartan provides a complete form field system. Always use it instead of raw divs.
+
+**Incorrect:**
+
+```html
+<label hlmLabel for="name">Name</label>
+<input hlmInput id="name" formControlName="name" />
+@if (form.controls.name.invalid && form.controls.name.touched) {
+  <p class="text-destructive text-sm">Name is required.</p>
+}
+```
+
+**Correct:**
+
+```html
+<div hlmField>
+  <label hlmFieldLabel>Name</label>
+  <input hlmInput formControlName="name" />
+  <hlm-field-error validator="required">Name is required.</hlm-field-error>
+</div>
+```
+
+### Full form example
+
+```typescript
+@Component({
+  template: `
+    <form [formGroup]="form" (ngSubmit)="onSubmit()">
+      <div hlmFieldGroup>
+        <div hlmField>
+          <label hlmFieldLabel>Name</label>
+          <input hlmInput formControlName="name" />
+          <hlm-field-error validator="required">Name is required.</hlm-field-error>
+        </div>
+        <div hlmField>
+          <label hlmFieldLabel>Email</label>
+          <input hlmInput formControlName="email" type="email" />
+          <hlm-field-error validator="required">Email is required.</hlm-field-error>
+          <hlm-field-error validator="email">Invalid email.</hlm-field-error>
+        </div>
+      </div>
+      <button hlmBtn type="submit">Submit</button>
+    </form>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class MyFormComponent {
+  private readonly _fb = inject(FormBuilder);
+  form = this._fb.group({
+    name: ['', Validators.required],
+    email: ['', [Validators.required, Validators.email]],
+  });
+}
+```
+
+---
+
+## Form control selection guide
+
+| Need | Component |
+|------|-----------|
+| Text input | `hlmInput` on `<input>` |
+| Multi-line text | `hlmTextarea` on `<textarea>` (**NOT** `hlmInput`) |
+| Simple dropdown (no JS) | `hlmNativeSelect` on `<select>` |
+| Rich dropdown | `brn-select` + `hlm-select-*` directives |
+| Searchable dropdown | `brn-combobox` + `hlm-combobox-*` |
+| Boolean toggle | `brn-switch` / `hlm-switch` (settings) or `brn-checkbox` (forms) |
+| Single choice | `brn-radio-group` / `hlm-radio-group` |
+| Range value | `brn-slider` / `hlm-slider` |
+| Date | `brn-calendar` + `brn-popover` |
+| OTP/verification | `brn-input-otp` / `hlm-input-otp` |
+
+---
+
+## FieldSet for grouping related fields
+
+Use `HlmFieldSet` + `HlmFieldLegend` for related checkboxes, radios, or switches.
+
+```html
+<fieldset hlmFieldSet>
+  <legend hlmFieldLegend>Preferences</legend>
+  <p hlmFieldDescription>Select all that apply.</p>
+  <div hlmFieldGroup class="gap-3">
+    <div hlmField class="flex-row items-center gap-2">
+      <brn-checkbox hlmCheckbox id="dark" formControlName="darkMode" />
+      <label hlmFieldLabel for="dark" class="font-normal">Dark mode</label>
+    </div>
+  </div>
+</fieldset>
+```

package/dist/templates/frontend/application/.claude/skills/spartan/rules/icons.md

@@ -0,0 +1,93 @@
+# Icons
+
+**Always use the project's configured icon library.** Check `@ng-icons/*` packages in the project's `package.json`. Common: `@ng-icons/lucide`, `@ng-icons/heroicons`, `@ng-icons/tabler-icons`.
+
+---
+
+## Use ng-icon with hlm directive
+
+**Incorrect:**
+
+```html
+<!-- Don't use raw SVG or icon fonts -->
+<svg viewBox="0 0 24 24"><path d="M12..."/></svg>
+<i class="fa fa-check"></i>
+```
+
+**Correct:**
+
+```html
+<ng-icon hlm name="lucideCheck" size="sm" />
+```
+
+Import using the convenience array:
+
+```typescript
+import { HlmIconImports } from '@spartan-ng/helm/icon';
+import { provideIcons } from '@ng-icons/core';
+import { lucideCheck, lucideSearch } from '@ng-icons/lucide';
+
+@Component({
+  imports: [...HlmIconImports],
+  providers: [provideIcons({ lucideCheck, lucideSearch })],
+})
+```
+
+---
+
+## No manual sizing on icons inside Spartan components
+
+Spartan components handle icon sizing via CSS.
+
+**Incorrect:**
+
+```html
+<button hlmBtn>
+  <ng-icon hlm name="lucideSearch" class="w-4 h-4 mr-2" />
+  Search
+</button>
+```
+
+**Correct:**
+
+```html
+<button hlmBtn>
+  <ng-icon hlm name="lucideSearch" size="sm" />
+  Search
+</button>
+```
+
+The `size` input on `hlm` directive handles sizing: `xs`, `sm`, `base`, `lg`, `xl`.
+
+---
+
+## Pass icons as component references, not strings
+
+When building reusable components that accept icons:
+
+**Incorrect:**
+
+```typescript
+// String-based lookup
+@Component({...})
+export class StatusBadge {
+  icon = input<string>('');
+}
+```
+
+**Correct:**
+
+```typescript
+// Type-safe icon component
+@Component({
+  template: `
+    <span hlmBadge>
+      <ng-icon hlm [name]="icon()" size="sm" />
+      <ng-content />
+    </span>
+  `
+})
+export class StatusBadge {
+  icon = input.required<string>();
+}
+```