fix(ai): rules use paths: frontmatter, only task-scoped guidance becomes skills

.ai/rules/component-readme.md

@@ -1,23 +1,25 @@
 ---
 description: Guidelines for component README documentation structure and accessibility compliance
 globs: 1st-gen/packages/*/README.md
+paths:
+  - '1st-gen/packages/*/README.md'
 alwaysApply: false
 ---
 
 # Component README documentation guidelines
 
-Use this rule when editing or creating component README files in `1st-gen/packages/*/README.md`.
+Applies automatically when Claude reads a file matching `1st-gen/packages/*/README.md` (Cursor: via `globs`; Claude Code: via `paths`). Use it explicitly too when asked to work on component README documentation outside that trigger.
 
 ## When to apply
 
-Apply when the user requests any of the following:
-
-- Reorganize or restructure a component README
-- Update component documentation
-- Add accessibility documentation to a component
-- Create documentation for a new component
-- Review README structure for a11y compliance
-- Standardize README format
+- Editing or creating a file matching `1st-gen/packages/*/README.md`
+- The user requests any of the following:
+  - Reorganize or restructure a component README
+  - Update component documentation
+  - Add accessibility documentation to a component
+  - Create documentation for a new component
+  - Review README structure for a11y compliance
+  - Standardize README format
 
 ## Required document structure
 

.ai/rules/contributor-doc-update.md

@@ -1,6 +1,8 @@
 ---
 description: Useful for updating auto-generated navigation and validating links in the contributor docs
 globs: CONTRIBUTOR-DOCS/**
+paths:
+  - 'CONTRIBUTOR-DOCS/**'
 alwaysApply: false
 ---
 

.ai/rules/stories-documentation.md

@@ -1,6 +1,10 @@
 ---
 description: Authoring guide for the per-unit MDX docs page for 2nd-gen components, internal components, patterns, and controllers. Covers section content, accessible examples, and 1st-gen comparison notes. Story prose lives in MDX, not in JSDoc above story exports.
 globs: 2nd-gen/packages/swc/components/*/*.mdx, 2nd-gen/packages/swc/patterns/*/*/*.mdx, 2nd-gen/packages/core/controllers/*/*.mdx
+paths:
+  - '2nd-gen/packages/swc/components/*/*.mdx'
+  - '2nd-gen/packages/swc/patterns/*/*/*.mdx'
+  - '2nd-gen/packages/core/controllers/*/*.mdx'
 alwaysApply: false
 ---
 
@@ -10,6 +14,12 @@ Authoring guide for the per-unit MDX file that powers each Storybook Docs page.
 
 **See also**: `.ai/rules/stories-format.md` for the stories file (`.stories.ts`) structure and conventions.
 
+## When to apply
+
+- Authoring or reviewing a per-unit `<unit>.mdx` docs page for a 2nd-gen component, internal component, pattern, or controller
+- Applies automatically when Claude reads a file matching the globs below (Cursor: via `globs`; Claude Code: via `paths`)
+- Verifying documentation prose against the component's actual implementation to avoid hallucinated attributes, slots, or ARIA claims
+
 ## Scope
 
 Apply to per-unit MDX files in:

.ai/rules/stories-format.md

@@ -1,6 +1,10 @@
 ---
 description: Enforces consistent file structure, section separators, meta configuration, story tags, and layout parameters for 2nd-gen Storybook stories files. Story prose lives in per-unit MDX; the stories file is definitions-only.
 globs: 2nd-gen/packages/swc/components/*/stories/**, 2nd-gen/packages/swc/patterns/*/*/stories/**, 2nd-gen/packages/core/controllers/*/stories/**
+paths:
+  - '2nd-gen/packages/swc/components/*/stories/**'
+  - '2nd-gen/packages/swc/patterns/*/*/stories/**'
+  - '2nd-gen/packages/core/controllers/*/stories/**'
 alwaysApply: false
 ---
 
@@ -10,6 +14,12 @@ Enforce consistent formatting and technical structure for Storybook stories file
 
 **See also**: `.ai/rules/stories-documentation.md` for guidance on WHAT to author in the per-unit MDX (content, patterns, examples).
 
+## When to apply
+
+- Authoring or reviewing a `.stories.ts` file for a 2nd-gen component, pattern, or controller
+- Applies automatically when Claude reads a file matching the globs below (Cursor: via `globs`; Claude Code: via `paths`)
+- Adding a new story (Playground, Options, States, Behaviors, Accessibility, etc.) and needing the right tags, layout parameters, or naming convention
+
 ## Scope
 
 Apply to all `.stories.ts` files in:

.ai/rules/storybook-mdx-conversion.md

@@ -1,16 +1,22 @@
 ---
 description: Converts contributor documentation from Markdown to MDX for Storybook rendering — adds imports, Meta tag, and converts HTML comments to JSX comments without altering any other content.
 globs: '**/*.md,**/*.mdx'
+paths:
+  - '**/*.md'
+  - '**/*.mdx'
 alwaysApply: false
 ---
 
 # Storybook MDX conversion
 
 Converts markdown files to MDX format compatible with Storybook rendering.
 
+> **Relationship to `generate-contributor-docs.mjs`:** the entire `CONTRIBUTOR-DOCS/` tree is already converted to Storybook `.mdx` automatically by `yarn generate:contributor-docs` (`2nd-gen/packages/swc/.storybook/scripts/generate-contributor-docs.mjs`), which also runs before every `yarn storybook` / `yarn storybook:build`. That script's output is regenerated wholesale and not meant to be hand-edited. This rule is for everything that script doesn't cover: converting a standalone `.md` file to `.mdx` by hand (e.g. a one-off doc outside `CONTRIBUTOR-DOCS/`, or manual spot-conversion during authoring) using the same conventions.
+
 ## When to apply
 
-Apply this rule when converting `.md` files to `.mdx` files for display in Storybook, particularly for documentation pages in the 2nd-gen SWC Storybook guides.
+- Converting a standalone `.md` file to `.mdx` by hand, outside the automated `generate-contributor-docs.mjs` pipeline
+- Applies automatically when Claude reads a matching `.md`/`.mdx` file (Cursor: via `globs`; Claude Code: via `paths`); ask explicitly ("convert this doc to MDX") to apply it outside that trigger
 
 ## Conversion steps
 

.ai/rules/styles.md

@@ -1,6 +1,6 @@
 ---
 description: Rules for consistent styling in component CSS
-globs: *.css
+globs: '*.css'
 alwaysApply: true
 ---
 

.ai/rules/text-formatting.md

@@ -1,11 +1,21 @@
 ---
 description: Text formatting and capitalization rules for documentation and tickets
-globs: **/*.md, **/*.txt,**/*.mdx
+globs: '**/*.md, **/*.txt, **/*.mdx'
+paths:
+  - '**/*.md'
+  - '**/*.txt'
+  - '**/*.mdx'
 alwaysApply: false
 ---
 
 # Text formatting conventions
 
+## When to apply
+
+- Writing or editing any `.md`, `.txt`, or `.mdx` content — applies automatically when Claude reads a matching file (Cursor: via `globs`; Claude Code: via `paths`)
+- Drafting prose for PR descriptions, Jira tickets, component docs, or per-unit MDX pages
+- Reviewing existing prose for heading case, em dashes, `<kbd>` formatting, or Jira ticket references
+
 ## Capitalization rules
 
 - Use sentence case for all headings and section titles (capitalize first word only)

.ai/rules/code-conformance.md → .ai/skills/code-conformance/SKILL.md

@@ -1,11 +1,21 @@
 ---
+name: code-conformance
 description: Review 2nd-gen component files against project style guides, run linters, and surface guideline gaps. Apply whenever reviewing or auditing 2nd-gen component code for style conformance.
-alwaysApply: false
 ---
 
 # Code conformance
 
-Use this rule when auditing 2nd-gen component files for alignment with project style guides. It covers four domains: TypeScript, CSS, test files, and Storybook stories. Always run automated linters first, then perform the manual review for each domain.
+## When to use this skill
+
+- Reviewing or auditing 2nd-gen component TypeScript, CSS, test, or Storybook story files for style-guide conformance
+- As part of the `migration-conformance` sub-task, after Phase 6 (testing) and before Phase 7 (documentation) of a component migration
+- Before a consistency pass (see `consistency-pass`), which delegates its code-conformance check to this skill
+
+## How to invoke
+
+- Say "check code conformance", "audit this component's style", "review this against the style guide", or "run conformance checks for [component]"
+
+Use this skill when auditing 2nd-gen component files for alignment with project style guides. It covers four domains: TypeScript, CSS, test files, and Storybook stories. Always run automated linters first, then perform the manual review for each domain.
 
 ## Linting commands
 
@@ -23,24 +33,24 @@ yarn prettier --write "path/to/files"
 
 Resolve every linting error before beginning the manual review. If a lint rule must be disabled, add an inline comment with a clear reason and flag it for reviewer awareness.
 
-Reference: [Linting tools](../../CONTRIBUTOR-DOCS/02_style-guide/03_linting-tools.md)
+Reference: [Linting tools](../../../CONTRIBUTOR-DOCS/02_style-guide/03_linting-tools.md)
 
 ## TypeScript
 
 **Style guide:**
 
-- [File organization](../../CONTRIBUTOR-DOCS/02_style-guide/02_typescript/01_file-organization.md)
-- [Class structure](../../CONTRIBUTOR-DOCS/02_style-guide/02_typescript/02_class-structure.md)
-- [TypeScript modifiers](../../CONTRIBUTOR-DOCS/02_style-guide/02_typescript/03_typescript-modifiers.md)
-- [Lit decorators](../../CONTRIBUTOR-DOCS/02_style-guide/02_typescript/04_lit-decorators.md)
-- [Property patterns](../../CONTRIBUTOR-DOCS/02_style-guide/02_typescript/05_property-patterns.md)
-- [Method patterns](../../CONTRIBUTOR-DOCS/02_style-guide/02_typescript/06_method-patterns.md)
-- [JSDoc standards](../../CONTRIBUTOR-DOCS/02_style-guide/02_typescript/07_jsdoc-standards.md)
-- [Component types](../../CONTRIBUTOR-DOCS/02_style-guide/02_typescript/08_component-types.md)
-- [Rendering patterns](../../CONTRIBUTOR-DOCS/02_style-guide/02_typescript/09_rendering-patterns.md)
-- [Naming conventions](../../CONTRIBUTOR-DOCS/02_style-guide/02_typescript/10_naming-conventions.md)
-- [Base class vs concrete class](../../CONTRIBUTOR-DOCS/02_style-guide/02_typescript/11_base-vs-concrete.md)
-- [Composition patterns](../../CONTRIBUTOR-DOCS/02_style-guide/02_typescript/12_composition-patterns.md) and related composition docs
+- [File organization](../../../CONTRIBUTOR-DOCS/02_style-guide/02_typescript/01_file-organization.md)
+- [Class structure](../../../CONTRIBUTOR-DOCS/02_style-guide/02_typescript/02_class-structure.md)
+- [TypeScript modifiers](../../../CONTRIBUTOR-DOCS/02_style-guide/02_typescript/03_typescript-modifiers.md)
+- [Lit decorators](../../../CONTRIBUTOR-DOCS/02_style-guide/02_typescript/04_lit-decorators.md)
+- [Property patterns](../../../CONTRIBUTOR-DOCS/02_style-guide/02_typescript/05_property-patterns.md)
+- [Method patterns](../../../CONTRIBUTOR-DOCS/02_style-guide/02_typescript/06_method-patterns.md)
+- [JSDoc standards](../../../CONTRIBUTOR-DOCS/02_style-guide/02_typescript/07_jsdoc-standards.md)
+- [Component types](../../../CONTRIBUTOR-DOCS/02_style-guide/02_typescript/08_component-types.md)
+- [Rendering patterns](../../../CONTRIBUTOR-DOCS/02_style-guide/02_typescript/09_rendering-patterns.md)
+- [Naming conventions](../../../CONTRIBUTOR-DOCS/02_style-guide/02_typescript/10_naming-conventions.md)
+- [Base class vs concrete class](../../../CONTRIBUTOR-DOCS/02_style-guide/02_typescript/11_base-vs-concrete.md)
+- [Composition patterns](../../../CONTRIBUTOR-DOCS/02_style-guide/02_typescript/12_composition-patterns.md) and related composition docs
 
 **What to check:**
 
@@ -50,19 +60,19 @@ Reference: [Linting tools](../../CONTRIBUTOR-DOCS/02_style-guide/03_linting-tool
 - Methods follow visibility and naming conventions
 - JSDoc is present and well-formed on public API members
 - No patterns listed as anti-patterns or discouraged in the guide
-- Dev-warning validation (enum values, required/conditionally required properties, mutually exclusive combinations, required slots, allowed children) uses the shared helpers in `@spectrum-web-components/core/utils` (`validateEnum`, `warnIf`, `validateRequiredSlot`, `validateAllowedChildren`), not hand-rolled `includes()` + `window.__swc.warn()` checks. See [Debug and validation](../../CONTRIBUTOR-DOCS/02_style-guide/02_typescript/17_debug-validation.md#reusable-validation-helpers).
+- Dev-warning validation (enum values, required/conditionally required properties, mutually exclusive combinations, required slots, allowed children) uses the shared helpers in `@spectrum-web-components/core/utils` (`validateEnum`, `warnIf`, `validateRequiredSlot`, `validateAllowedChildren`), not hand-rolled `includes()` + `window.__swc.warn()` checks. See [Debug and validation](../../../CONTRIBUTOR-DOCS/02_style-guide/02_typescript/17_debug-validation.md#reusable-validation-helpers).
 
 ## CSS
 
 **Style guide:**
 
-- [Component CSS](../../CONTRIBUTOR-DOCS/02_style-guide/01_css/01_component-css.md)
-- [Custom properties](../../CONTRIBUTOR-DOCS/02_style-guide/01_css/02_custom-properties.md)
-- [Component CSS PR checklist](../../CONTRIBUTOR-DOCS/02_style-guide/01_css/03_component-css-pr-checklist.md)
-- [Spectrum CSS to SWC migration](../../CONTRIBUTOR-DOCS/02_style-guide/01_css/04_spectrum-swc-migration.md)
-- [Styling anti-patterns](../../CONTRIBUTOR-DOCS/02_style-guide/01_css/05_anti-patterns.md)
-- [Property order quick reference](../../CONTRIBUTOR-DOCS/02_style-guide/01_css/06_property-order-quick-reference.md)
-- [Non-component stylesheets](../../CONTRIBUTOR-DOCS/02_style-guide/01_css/07_stylesheets.md) — applies when the changed file is in `swc/stylesheets/` rather than a component package
+- [Component CSS](../../../CONTRIBUTOR-DOCS/02_style-guide/01_css/01_component-css.md)
+- [Custom properties](../../../CONTRIBUTOR-DOCS/02_style-guide/01_css/02_custom-properties.md)
+- [Component CSS PR checklist](../../../CONTRIBUTOR-DOCS/02_style-guide/01_css/03_component-css-pr-checklist.md)
+- [Spectrum CSS to SWC migration](../../../CONTRIBUTOR-DOCS/02_style-guide/01_css/04_spectrum-swc-migration.md)
+- [Styling anti-patterns](../../../CONTRIBUTOR-DOCS/02_style-guide/01_css/05_anti-patterns.md)
+- [Property order quick reference](../../../CONTRIBUTOR-DOCS/02_style-guide/01_css/06_property-order-quick-reference.md)
+- [Non-component stylesheets](../../../CONTRIBUTOR-DOCS/02_style-guide/01_css/07_stylesheets.md) — applies when the changed file is in `swc/stylesheets/` rather than a component package
 
 **What to check:**
 
@@ -73,20 +83,20 @@ Reference: [Linting tools](../../CONTRIBUTOR-DOCS/02_style-guide/03_linting-tool
 - Forced-colors media query is present and correct (if applicable)
 - High-contrast and other media queries are sorted to the bottom of the file
 - No hard-coded values where design tokens are available
-- For files in `swc/stylesheets/`: placement, index registration, generated file conventions, and `_lit-styles/` import patterns match [Non-component stylesheets](../../CONTRIBUTOR-DOCS/02_style-guide/01_css/07_stylesheets.md)
+- For files in `swc/stylesheets/`: placement, index registration, generated file conventions, and `_lit-styles/` import patterns match [Non-component stylesheets](../../../CONTRIBUTOR-DOCS/02_style-guide/01_css/07_stylesheets.md)
 
 ## Test files
 
-**Vitest reference:** see [.ai/references/vitest.md](../references/vitest.md) for the canonical AI-friendly Vitest docs (index + per-page fetch pattern) and project-specific config notes.
+**Vitest reference:** see [.ai/references/vitest.md](../../references/vitest.md) for the canonical AI-friendly Vitest docs (index + per-page fetch pattern) and project-specific config notes.
 
 **Style guide:**
 
-- [Testing overview](../../CONTRIBUTOR-DOCS/02_style-guide/04_testing/01_testing-overview.md)
-- [Storybook testing](../../CONTRIBUTOR-DOCS/02_style-guide/04_testing/02_storybook-testing.md)
-- [Playwright accessibility testing](../../CONTRIBUTOR-DOCS/02_style-guide/04_testing/03_playwright-accessbility-testing.md)
-- [Testing utilities](../../CONTRIBUTOR-DOCS/02_style-guide/04_testing/05_testing-utilities.md)
-- [Avoiding flaky tests](../../CONTRIBUTOR-DOCS/02_style-guide/04_testing/07_avoiding-flaky-tests.md)
-- [PR review checklist](../../CONTRIBUTOR-DOCS/02_style-guide/04_testing/09_pr_review-checklist.md)
+- [Testing overview](../../../CONTRIBUTOR-DOCS/02_style-guide/04_testing/01_testing-overview.md)
+- [Storybook testing](../../../CONTRIBUTOR-DOCS/02_style-guide/04_testing/02_storybook-testing.md)
+- [Playwright accessibility testing](../../../CONTRIBUTOR-DOCS/02_style-guide/04_testing/03_playwright-accessbility-testing.md)
+- [Testing utilities](../../../CONTRIBUTOR-DOCS/02_style-guide/04_testing/05_testing-utilities.md)
+- [Avoiding flaky tests](../../../CONTRIBUTOR-DOCS/02_style-guide/04_testing/07_avoiding-flaky-tests.md)
+- [PR review checklist](../../../CONTRIBUTOR-DOCS/02_style-guide/04_testing/09_pr_review-checklist.md)
 
 **What to check:**