docs(ai): rewrite .ai readme around a generated catalog

[caseyisonit]

Layers 1–3 (#6785, #6786, #6787) are merged, so this PR now targets main and is the bottom of the remaining stack.

Description

Replaces the hand-maintained .ai/README.md catalog with one that yarn ai:sync generates from frontmatter.

• Rewrites .ai/README.md (37.6 KB → 21.6 KB) as a short guide:
  • How each source maps to each tool
  • How to choose between a rule, a skill, and AGENTS.md
  • How to author and validate each kind of file
  • Tool setup, including a Windows fallback when symlinks aren't available (copilot skill add <repo>/.ai/skills)
  • Optional personal MCP and tool-permission setup
• Generates the catalog. The list of rules, lessons, and skills is generated between <!-- ai:catalog:start --> and <!-- ai:catalog:end -->. It's rendered as lists rather than tables so Prettier doesn't pad it. yarn lint:ai fails if the catalog drifts from frontmatter. The old hand-written catalog had already drifted, for example with a dead cursor_prompt.md path and wrong glob summaries.
• Adds the catalog generator to sync.js. renderCatalog() and the README write moved here from feat(ai): generate copilot and cursor instructions from .ai rules #6785 after review, because this is the layer that adds the markers.
• Keeps the git hooks in step with the catalog. The catalog reads skill frontmatter, so pre-commit also skips the sync when .ai/skills/ or .ai/README.md has unstaged changes, and re-stages the README after syncing. Pre-push treats the README as a generated file and blocks the push if the catalog is out of date.
• Checks only git-tracked files in yarn lint:ai. The .ai/ validators and yarn ai:sync --check now read files from git ls-files (staged new files count) instead of walking the file system. Untracked or ignored local files, such as a Cursor .cursor/rules/manifest.json cache or .ai/handoffs/ notes, no longer fail the lint. A hand-authored file staged in a generated folder still fails. This came from review feedback on this PR.
• Aligns the branch and commit guidance in the contributor docs. 04_making-a-pull-request.md now documents <username>/<type>-<description>[-swc-<issue>] and the full commitlint type list, and links to the branch-naming and conventional-commit skills. The PR template's commit-type comment listed 7 types and pointed to a PULL_REQUESTS.md that doesn't exist. It now cites commitlint.

Motivation and context

The README duplicated every skill's frontmatter by hand and had already drifted. Generating the catalog makes drift a lint failure instead of a silent inconsistency. The contributor docs, the PR template, the skills, and commitlint disagreed on branch and commit conventions (plan conflicts C-1 and C-2). Now there's one convention everywhere.

Related issue(s)

• Follows feat(ai): generate copilot and cursor instructions from .ai rules #6785, feat(ai): split stories rules and load memory as instructions #6786, and refactor(ai): normalize skills and retire .ai/config.json #6787 (merged). This is part of the AI configuration migration plan.

Screenshots (if appropriate)

N/A

Author's checklist

• I have read the CONTRIBUTING and PULL_REQUESTS documents.
• I have reviewed at the Accessibility Practices for this feature, see: Aria Practices. No rendered UI changes.
• I have added automated tests to cover my changes. yarn lint:ai checks catalog drift.
• I have included a well-written changeset if my change needs to be published. It doesn't: no published package changes.
• I have included updated documentation if my change required it.

Reviewer's checklist

• Includes a Github Issue with appropriate flag or Jira ticket number without a link
• Includes thoughtfully written changeset if changes suggested include patch, minor, or major features
• Automated tests cover all use cases and follow best practices for writing
• Validated on all supported browsers
• All VRTs are approved before the author can update Golden Hash

Manual review test cases

• The catalog is generated and up to date

  1. Run yarn ai:sync --check, then yarn lint:ai.
  2. Expect both to pass. Change a skill's description without running the sync, and expect yarn lint:ai to fail on .ai/README.md.
  3. Change the "Do not edit this block by hand" text in .ai/scripts/sync.js, then run git push --dry-run. Expect ✖ yarn ai:sync updated generated files listing .ai/README.md. Revert with git checkout -- .ai/scripts/sync.js .ai/README.md.

• yarn lint:ai ignores untracked files

  1. Run echo '{}' > .cursor/rules/manifest.json, then yarn lint:ai. Expect it to pass.
  2. Run git add .cursor/rules/manifest.json, then yarn lint:ai. Expect ✖ .cursor/rules/manifest.json: hand-authored file in a generated folder.
  3. Clean up with git rm -q --cached .cursor/rules/manifest.json && rm .cursor/rules/manifest.json.

• Contributor docs render

  1. Run yarn storybook and open Contributor Docs › Making a pull request.
  2. Expect the updated branch naming and conventional commits sections.

Verified by the author: yarn lint:ai and Prettier pass. After rebasing onto main, yarn ai:sync --check reports 21 generated files up to date, the pre-push hook blocked a simulated stale catalog, and yarn lint:ai passed with an untracked .cursor/rules/manifest.json and failed once it was staged. The contributor docs nav script reports no new broken links. The 25 it reports are pre-existing, all in 03_project-planning/. Pending host verification: the Storybook render of the contributor docs page.

Device review

• Did it pass in Desktop?
• Did it pass in (emulated) Mobile?
• Did it pass in (emulated) iPad?

Accessibility testing checklist

N/A. This PR changes documentation, scripts, and git hooks only. It adds and changes no rendered UI or components.

[changeset-bot]

⚠️ No Changeset found

Latest commit: 98cd20d

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[github-actions]

📚 Branch Preview Links

• Storybook (Gen2, dev mode)
• Storybook (Gen2, prod mode)
• Documentation Site (Gen1)
• Storybook (Gen1)

🔍 Gen1 Visual Regression Test Results

When a visual regression test fails (or has previously failed while working on this branch), its results can be found in the following URLs:

• Spectrum | Light | Medium | LTR
• Spectrum | Dark | Large | RTL
• Express | Light | Medium | LTR
• Express | Dark | Large | RTL
• Spectrum-two | Light | Medium | LTR
• Spectrum-two | Dark | Large | RTL
• High Contrast Mode | Medium | LTR

Deployed to Azure Blob Storage: pr-6788

If the changes are expected, update the current_golden_images_cache hash in the circleci config to accept the new images. Instructions are included in that file.
If the changes are unexpected, you can investigate the cause of the differences and update the code accordingly.

yarn lint:ai is still failing

[blunteshwar]

`yarn lint:ai` is failing with the following error

[caseyisonit]

@blunteshwar the error comes from .cursor/rules/manifest.json. That file isn't tracked in the repo, so a local tool probably created it, and lint:ai treats any file without the generated header in .cursor/rules/ as hand-authored. Remove just that file:

rm .cursor/rules/manifest.json
yarn lint:ai

Please don't delete the whole .cursor/ directory. It holds tracked generated rules, the skills symlink, and your personal mcp.json.

The link warnings for .ai/handoffs/ are local, gitignored files and don't fail the check. As of 98cd20d, lint:ai only checks tracked files, so after pulling, a stray local manifest.json no longer fails it either.

[blunteshwar]

@blunteshwar the error comes from .cursor/rules/manifest.json. That file isn't tracked in the repo, so a local tool probably created it, and lint:ai treats any file without the generated header in .cursor/rules/ as hand-authored. Remove just that file:

rm .cursor/rules/manifest.json
yarn lint:ai

Please don't delete the whole .cursor/ directory. It holds tracked generated rules, the skills symlink, and your personal mcp.json.

The link warnings for .ai/handoffs/ are local, gitignored files and don't fail the check. As of 98cd20d, lint:ai only checks tracked files, so after pulling, a stray local manifest.json no longer fails it either.

Checked locally. It works fine after removing the .cursor/rules/manifest.json