docs(ai): add lessons migrated from claude memory

.ai/README.md

@@ -96,7 +96,7 @@ _Generated by `yarn ai:sync` from frontmatter. Do not edit this block by hand._
 - **[`rules/stories-format.md`](./rules/stories-format.md)** (`gen2/packages/swc/components/*/stories/**`, `gen2/packages/swc/patterns/*/*/stories/**`, `gen2/packages/core/controllers/*/stories/**`): Enforces consistent file structure, section separators, meta configuration, story tags, and layout parameters for gen2 Storybook stories files. Story prose lives in per-unit MDX; the stories file is definitions-only.
 - **[`rules/styles.md`](./rules/styles.md)** (`**/*.css`): Rules for consistent styling in component CSS
 - **[`rules/text-formatting.md`](./rules/text-formatting.md)** (`**/*.md`, `**/*.txt`, `**/*.mdx`): Text formatting and capitalization rules for documentation and tickets
-- **[`memory/agnostic-lessons.md`](./memory/agnostic-lessons.md)** (`**`; not used by code-review): Accumulated lessons for agents working in this repository, covering path depths, module format, repository layout, Storybook tag conventions, and documentation style.
+- **[`memory/agnostic-lessons.md`](./memory/agnostic-lessons.md)** (`**`; not used by code-review): Accumulated lessons for agents working in this repository, covering path depths, module format, repository layout, the gen2 styling API prefix, generated build output, Storybook tag conventions, and documentation style.
 - **[`memory/css-styling-lessons.md`](./memory/css-styling-lessons.md)** (`**/*.css`): Accumulated CSS lessons for component styling in this repository, covering selector syntax, custom property consumption, shorthands and fallback chains, variant states, and linter rewrites.
 
 ### Skills

.ai/memory/agnostic-lessons.md

@@ -1,5 +1,5 @@
 ---
-description: Accumulated lessons for agents working in this repository, covering path depths, module format, repository layout, Storybook tag conventions, and documentation style.
+description: Accumulated lessons for agents working in this repository, covering path depths, module format, repository layout, the gen2 styling API prefix, generated build output, Storybook tag conventions, and documentation style.
 paths:
   - '**'
 excludeAgent: code-review
@@ -32,6 +32,19 @@ Accumulated lessons from working sessions on this project. Grouped by category.
 
 ---
 
+## Styling API
+
+- **gen2 components expose `--swc-*` custom properties**: A gen2 component's public styling API, meaning the custom properties it documents with `@cssprop` and that consumers set to override it, uses the `--swc-*` prefix (for example `--swc-badge-height`). `--mod-*` and `--spectrum-*` are 1st-gen and Spectrum CSS conventions. Use them in gen2 docs, examples, and JSDoc only when a 1st-gen to gen2 migration guide compares the two. Stylelint's `custom-property-pattern` doesn't enforce the prefix.
+
+---
+
+## Generated files
+
+- **Keep regenerated build output**: When `yarn build` rewrites a generated file, such as `gen2/packages/swc/stylesheets/global/global-*.css` (built from component CSS by `gen2/packages/tools/vite-global-elements-css`), commit the regenerated file even if the diff looks unrelated, such as reordered properties. The committed copy was stale. Revert it only if the diff contradicts its source.
+
+---
+
 ## Documentation
 
 - **Contributor migration-analysis markdown**: Prefer plain sentences with backticks for roles, elements, and code. Bold is fine sparingly for scanning cues; follow `accessibility-migration-analysis` skill (≈30% cap on bold markup for body prose, single spans for multi-word emphasis).
+- **Don't hard-wrap prose**: `.prettierrc.yaml` sets `printWidth: 80` but leaves `proseWrap` at its default, `preserve`, so Prettier never reflows Markdown prose. Write each paragraph on one line in `.md` and `.mdx` files, and break lines only for structure: list items, headings, tables, and code. Reviewers have flagged hand-wrapped prose as diff noise.