From ca012cb12bc9b5e486621a36e359e166d385d107 Mon Sep 17 00:00:00 2001
From: Dmytro Kirpa <dmytrokirpa@microsoft.com>
Date: Wed, 4 Mar 2026 15:43:16 +0100
Subject: [PATCH 1/6] docs: cover more component migrations in
 fluent-migrate-v8-to-v9

---
 skills/fluentui-migrate-v8-to-v9/SKILL.md     | 331 +++++++++++++-----
 .../references/breadcrumb.md                  |  92 +++++
 .../references/button.md                      |  32 ++
 .../references/card.md                        |  79 +++++
 .../references/charts.md                      |  49 +++
 .../references/colorpicker.md                 |  59 ++++
 .../references/image.md                       |  67 ++++
 .../references/keytips.md                     |  76 ++++
 .../references/label.md                       |  41 +++
 .../references/link.md                        |  81 +++++
 .../references/list.md                        |  92 +++++
 .../references/nav.md                         | 112 ++++++
 .../references/overflow.md                    | 117 +++++++
 .../references/persona.md                     |  81 +++++
 .../references/rating.md                      |  88 +++++
 .../references/searchbox.md                   |  68 ++++
 .../references/separator.md                   |  44 +++
 .../references/skeleton.md                    |  76 ++++
 .../references/swatchpicker.md                | 101 ++++++
 .../references/switch.md                      |  49 +++
 .../references/tagpicker.md                   | 107 ++++++
 .../references/teachingpopover.md             | 117 +++++++
 .../references/text.md                        |  82 +++++
 .../references/textarea.md                    |  55 +++
 .../references/theme.md                       |  29 +-
 .../references/toolbar.md                     |  25 ++
 .../references/tree.md                        | 101 ++++++
 27 files changed, 2169 insertions(+), 82 deletions(-)
 create mode 100644 skills/fluentui-migrate-v8-to-v9/references/breadcrumb.md
 create mode 100644 skills/fluentui-migrate-v8-to-v9/references/card.md
 create mode 100644 skills/fluentui-migrate-v8-to-v9/references/charts.md
 create mode 100644 skills/fluentui-migrate-v8-to-v9/references/colorpicker.md
 create mode 100644 skills/fluentui-migrate-v8-to-v9/references/image.md
 create mode 100644 skills/fluentui-migrate-v8-to-v9/references/keytips.md
 create mode 100644 skills/fluentui-migrate-v8-to-v9/references/label.md
 create mode 100644 skills/fluentui-migrate-v8-to-v9/references/link.md
 create mode 100644 skills/fluentui-migrate-v8-to-v9/references/list.md
 create mode 100644 skills/fluentui-migrate-v8-to-v9/references/nav.md
 create mode 100644 skills/fluentui-migrate-v8-to-v9/references/overflow.md
 create mode 100644 skills/fluentui-migrate-v8-to-v9/references/persona.md
 create mode 100644 skills/fluentui-migrate-v8-to-v9/references/rating.md
 create mode 100644 skills/fluentui-migrate-v8-to-v9/references/searchbox.md
 create mode 100644 skills/fluentui-migrate-v8-to-v9/references/separator.md
 create mode 100644 skills/fluentui-migrate-v8-to-v9/references/skeleton.md
 create mode 100644 skills/fluentui-migrate-v8-to-v9/references/swatchpicker.md
 create mode 100644 skills/fluentui-migrate-v8-to-v9/references/switch.md
 create mode 100644 skills/fluentui-migrate-v8-to-v9/references/tagpicker.md
 create mode 100644 skills/fluentui-migrate-v8-to-v9/references/teachingpopover.md
 create mode 100644 skills/fluentui-migrate-v8-to-v9/references/text.md
 create mode 100644 skills/fluentui-migrate-v8-to-v9/references/textarea.md
 create mode 100644 skills/fluentui-migrate-v8-to-v9/references/tree.md

diff --git a/skills/fluentui-migrate-v8-to-v9/SKILL.md b/skills/fluentui-migrate-v8-to-v9/SKILL.md
index c7bd906ac4bdea..da037730bafbd9 100644
--- a/skills/fluentui-migrate-v8-to-v9/SKILL.md
+++ b/skills/fluentui-migrate-v8-to-v9/SKILL.md
@@ -5,23 +5,89 @@ description: 'Guides migration from Fluent UI React v8 (@fluentui/react) to v9 (
 
 # Fluent UI v8 → v9 Migration
 
+## Agent Output Template
+
+After completing a migration session, report using this structure:
+
+```
+### Migration Report
+
+**Scope:** <files changed> files, <components migrated> component types migrated
+**Assumptions logged:** <count> (see inline `// MIGRATION ASSUMPTION:` comments)
+**Unresolved deltas:** <list or "none">
+**Shims still in place:** <list ShimComponent → target file — or "none">
+**Shim removal plan:** <for each shim: target v9 component when ready to replace — or "n/a">
+**Reference precedence used:** <component: decision made — or "none">
+**Validation evidence:**
+  - TypeScript check (<command used>): ✅ / ❌ <error count> (baseline was <baseline count>)
+  - lint: ✅ / ❌ / ⏭️ skipped (no linter found)
+  - tests: ✅ / ❌ / ⏭️ skipped (no test command found)
+  - No remaining @fluentui/react imports: ✅ / ❌ <count remaining>
+**Final status:** ✅ Complete / ⚠️ Partial (see unresolved deltas) / ❌ Blocked (<reason>)
+```
+
+---
+
 ## Migration Workflow
 
 ### Step 1 — Assess
 
-Find all files using v8:
+**Determine source root first:**
+
+1. Check `tsconfig.json` for `include` or `rootDir` to identify the source root (e.g., `src/`, `app/`, `lib/`)
+2. In a monorepo or if multiple `tsconfig.json` files exist, ask the user: _"Which directory or package should I migrate? (e.g., `packages/my-app/src`)"_
+3. If no tsconfig exists, default to searching from the repo root (`.`) and adjust from there
+
+Replace `<SOURCE_ROOT>` in the commands below with the path you identified:
 
 ```sh
-# All files importing from @fluentui/react
-grep -rl "@fluentui/react" src/ --include="*.tsx" --include="*.ts"
+# All files importing from @fluentui/react — adjust path to your repo layout
+grep -rl "@fluentui/react" <SOURCE_ROOT> --include="*.tsx" --include="*.ts"
 
 # Tally component usage to prioritize
-grep -rh "from '@fluentui/react'" src/ | sort | uniq -c | sort -rn
+grep -rh "from '@fluentui/react'" <SOURCE_ROOT> --include="*.tsx" --include="*.ts" | sort | uniq -c | sort -rn
 ```
 
 Identify which components are used and how many times. Migrate high-count simple components first.
 
-### Step 2 — Setup
+Skip files that import **only** from `@fluentui/react-components` — they are already migrated.
+
+### Setup Boundary
+
+**Agents do not run installs.** Read `package.json` and report what's missing; the user installs.
+
+Ready-to-proceed conditions (verify before starting Step 3):
+
+- `@fluentui/react-components` is present in `package.json` dependencies
+- A `FluentProvider` wrapper exists somewhere in the codebase (or the user has confirmed they will add one)
+
+If either condition is unmet, report what's needed and stop until the user confirms setup is complete.
+
+### Agent Execution Contract
+
+**Phase order:** assess (+ tsc baseline) → plan → mechanical pass → semantic pass → validate → report (Output Template above)
+
+**Baseline TypeScript check before starting:** run the repo's TypeScript check command (`tsc --noEmit` or the equivalent in `package.json` scripts) before any changes and record the error count. In the Validation step, report TypeScript as ✅ if post-migration error count ≤ baseline — do not block on pre-existing errors.
+
+**Behavior-preserving default:** when uncertain, preserve existing behavior. Never silently drop functionality.
+
+**Confidence threshold:** if you are less than ~80% confident in a mapping, add an inline comment and flag it — do not skip it silently:
+
+```tsx
+// MIGRATION ASSUMPTION: GroupedList mapped to Tree (expand/collapse usage detected). Verify if tabular layout was intended.
+```
+
+**Stop and escalate when:**
+
+- TypeScript errors remain after mechanical pass that you cannot resolve
+- A component has no known v9 equivalent and no clear workaround
+- More than 2 unresolved 1→many mappings in the same file (see Ambiguity Resolution below)
+
+In those cases: commit what's done, fill in the Output Template with status ⚠️ or ❌, list the blockers, and wait for user input.
+
+### Step 2 — User Setup (reference only)
+
+> **Agent note:** do not execute these commands. Report which packages are missing from `package.json` and wait for the user to confirm installation is complete before proceeding to Step 3.
 
 ```sh
 npm install @fluentui/react-components @fluentui/react-icons
@@ -51,8 +117,10 @@ import { PortalCompatProvider } from '@fluentui/react-portal-compat';
 
 **Recommended order within a file:**
 
+#### Pass 1 — Mechanical (safe to automate)
+
 1. Update import statements (`@fluentui/react` → `@fluentui/react-components`)
-2. Rename components per the mapping table below
+2. Rename components per the mapping table below (1→1 renames only; defer 1→many to Pass 2)
 3. Apply universal prop renames (applies to every component):
    - `componentRef` → `ref`
    - `ariaLabel` → `aria-label`
@@ -63,6 +131,9 @@ import { PortalCompatProvider } from '@fluentui/react-portal-compat';
    - Combine class names with `mergeClasses(s.a, s.b, extra)` (replaces `cx` / `mergeStyles` for className composition)
    - Remove `theme` prop → handled by `FluentProvider`
 4. Apply component-specific prop changes (see reference files below)
+
+#### Pass 2 — Semantic (requires judgment)
+
 5. Replace v8-only utility imports (no v9 equivalent — remove the import and use the native alternative):
    - `useBoolean` → `React.useState<boolean>(false)` (`const [open, setOpen] = React.useState(false)`)
    - `KeyCodes.enter` / `KeyCodes.escape` → `event.key === 'Enter'` / `event.key === 'Escape'`
@@ -81,6 +152,7 @@ import { PortalCompatProvider } from '@fluentui/react-portal-compat';
      ```
    - **Alternative (manual):** separate `<Label htmlFor={id}>` + `useId` from `@fluentui/react-components`
 7. Migrate `iconProps={{ iconName: 'X' }}` → `icon={<XRegular />}` (see [icons.md](references/icons.md))
+8. Resolve 1→many mappings and architectural changes (ContextualMenu→Menu JSX, Stack→makeStyles, etc.) — see Ambiguity Resolution below
 
 **Recommended migration order across files:**
 
@@ -89,22 +161,65 @@ import { PortalCompatProvider } from '@fluentui/react-portal-compat';
 3. Components requiring label extraction (SpinButton, ChoiceGroup→RadioGroup, Slider)
 4. Architectural changes (ContextualMenu→Menu JSX children, Stack→makeStyles, ThemeProvider→FluentProvider)
 
-### Step 4 — Verify
+### Codemod Guidance
 
-```sh
-# After each file or batch — catch type errors early:
-npx tsc --noEmit
+**Safe to automate (Pass 1):**
 
-# Confirm no v8 imports remain:
-grep -r "from '@fluentui/react'" src/ --include="*.tsx" --include="*.ts"
-# Should only show @fluentui/react-components imports
-```
+- Import path: `@fluentui/react` → `@fluentui/react-components`
+- Universal prop renames (`componentRef→ref`, `ariaLabel→aria-label`, etc.)
+- 1→1 component renames: Separator→Divider, Toggle→Switch, Shimmer→Skeleton, Label→Label, Icon→SVG import, Fabric→FluentProvider, Layer→Portal, Overlay→Portal
+- Shim swaps: `import { XShim as X } from '@fluentui/react-migration-v8-v9'`
+
+**Manual only (Pass 2 — requires understanding intent):**
+
+- 1→many mappings: GroupedList, DetailsList, Popup (see Ambiguity Resolution below)
+- `styles` prop → `makeStyles` (must understand what styles were doing)
+- `Stack`/`StackItem` → flexbox via `makeStyles` (layout intent must be preserved)
+- `ContextualMenu` / `CommandBar` data-driven → JSX (tree structure must be reconstructed)
+- Icon name string → SVG component import (names don't always match 1:1; use the icons reference)
+- Any `onRender*` callback → slot (render logic must be understood)
+
+### Ambiguity Resolution Rules
+
+For **1→many mappings**, resolve in this order:
+
+1. Check the component's reference file — it usually identifies the right target based on usage pattern
+2. Use surrounding code context:
+   - Tabular data with columns → `DataGrid` (selection/sort) or `Table` (read-only)
+   - Nested items with expand/collapse → `Tree`
+   - Flat scrollable list → `List`
+   - Non-modal overlay → `Popover`; modal/blocking → `Dialog`
+3. If still ambiguous after steps 1–2, log an assumption comment:
+   ```tsx
+   // MIGRATION ASSUMPTION: GroupedList mapped to Tree (expand/collapse pattern detected). Verify intent.
+   ```
+
+**Escalation trigger:** more than 2 unresolved 1→many mappings in the same file → stop, report status ⚠️, and ask the user before continuing.
 
-**Visual / runtime checks (open the app after each batch):**
+### Step 4 — Validate
 
-- **Unstyled components** (raw HTML with no Fluent design) → `FluentProvider` is missing or the component is rendered outside it
+Run the host repo's own commands. Do not assume `npx tsc` or `npm test` — check `package.json` scripts first.
+
+**Checklist (all must pass before reporting ✅ Complete):**
+
+- [ ] **TypeScript** — TypeScript check command from `package.json` scripts (or `tsc --noEmit` if none) exits with error count ≤ baseline
+- [ ] **Lint** — repo linter (eslint/biome/etc.) exits 0; if no linter found, mark ⏭️ skipped
+- [ ] **Tests** — repo test command passes; if no test command found, mark ⏭️ skipped
+- [ ] **No remaining v8 imports** — `grep -r "from '@fluentui/react'" <SOURCE_ROOT> --include="*.tsx" --include="*.ts"` returns nothing (only `@fluentui/react-components` imports remain)
+- [ ] **Shims tracked** — every `*Shim` import still in the codebase is listed in the Output Template
+- [ ] **Accessibility parity** — icon-only buttons have `aria-label`; all form controls have labels via `<Field>` or `<Label>`
+- [ ] **No `styles` prop remaining** — `grep -r "styles={" <SOURCE_ROOT> --include="*.tsx"` returns nothing Fluent-related
+
+**Go / No-go:**
+
+- All ✅ → fill Output Template with status ✅ Complete
+- Any ❌ → fill Output Template with status ❌ Blocked, list each failure
+
+**Visual / runtime checks (open the app after migration):**
+
+- **Unstyled components** → `FluentProvider` is missing or the component is rendered outside it
 - **v9 components inside a v8 Callout / Panel / Modal have no styles** → add `PortalCompatProvider` (see Troubleshooting)
-- **Icon-only buttons have no accessible name** → add `aria-label` to every button that has only an `icon` slot and no visible text
+- **Icon-only buttons have no accessible name** → add `aria-label`
 - **Form controls have no visible label** → label extraction step was missed; wrap with `<Field label="...">`
 - **Console warnings about unknown props** → a v8 prop (e.g. `text`, `iconProps`, `componentRef`) was not removed
 
@@ -177,71 +292,74 @@ Rule of thumb: add `disableButtonEnhancement` when the trigger child is a Fluent
 
 ## Component Mapping
 
-| v8                                | v9                                | Notes                                                                                                                    |
-| --------------------------------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
-| `ActionButton`                    | `Button`                          | `appearance="transparent"`                                                                                               |
-| `Breadcrumb`                      | `Breadcrumb`                      | New package                                                                                                              |
-| `Calendar`                        | `CalendarCompat`                  | `@fluentui/react-calendar-compat`                                                                                        |
-| `Callout`                         | `Popover`                         | Composable trigger/surface; `target` ref → `PopoverTrigger` — see [callout.md](references/callout.md)                    |
-| `Checkbox`                        | `Checkbox`                        | API mostly same                                                                                                          |
-| `ChoiceGroup`                     | `RadioGroup`                      | Renamed; options array → `Radio` children                                                                                |
-| `Coachmark`                       | `TeachingPopover`                 |                                                                                                                          |
-| `CommandBar` / `CommandBarButton` | `Toolbar`                         | Data-driven → JSX children — see [toolbar.md](references/toolbar.md)                                                     |
-| `CommandButton`                   | `MenuButton`                      |                                                                                                                          |
-| `CompoundButton`                  | `CompoundButton`                  | New package                                                                                                              |
-| `ComboBox`                        | `Combobox`                        | options array → `Option` children — see [dropdown.md](references/dropdown.md)                                            |
-| `ContextualMenu`                  | `Menu`                            | Data-driven → JSX children — see [menu.md](references/menu.md)                                                           |
-| `DatePicker`                      | `DatePickerCompat`                | `@fluentui/react-datepicker-compat`                                                                                      |
-| `DefaultButton`                   | `Button`                          |                                                                                                                          |
-| `DetailsList`                     | `DataGrid`                        | columns/selection/sort API restructured — see [datagrid.md](references/datagrid.md)                                      |
-| `Dialog`                          | `Dialog`                          | Composable children; `hidden` → `open` (inverted) — see [dialog.md](references/dialog.md)                                |
-| `DocumentCard`                    | `Card`                            |                                                                                                                          |
-| `Dropdown`                        | `Dropdown`                        | options array → `Option` children — see [dropdown.md](references/dropdown.md)                                            |
-| `Fabric`                          | `FluentProvider`                  |                                                                                                                          |
-| `Facepile`                        | `AvatarGroup`                     | personas array → children                                                                                                |
-| `FocusTrapZone` / `FocusZone`     | Tabster                           | https://tabster.io                                                                                                       |
-| `GroupedList`                     | `Tree`                            |                                                                                                                          |
-| `Icon`                            | `@fluentui/react-icons`           | SVG components                                                                                                           |
-| `IconButton`                      | `Button`                          | Use `icon` slot only, no text                                                                                            |
-| `Image`                           | `Image`                           | New package                                                                                                              |
-| `Label`                           | `Label`                           | New package                                                                                                              |
-| `Layer`                           | `Portal`                          |                                                                                                                          |
-| `Link`                            | `Link`                            | Better accessibility                                                                                                     |
-| `List`                            | `List`                            | Performance improvements                                                                                                 |
-| `MessageBar`                      | `MessageBar`                      | Composable children; `messageBarType` → `intent` — see [messagebar.md](references/messagebar.md)                         |
-| `Modal`                           | `Dialog`                          | `isOpen` → `open`; `isBlocking` → `modalType` — see [dialog.md](references/dialog.md)                                    |
-| `Nav`                             | `Nav`                             | New package                                                                                                              |
-| `OverflowSet`                     | `Overflow`                        |                                                                                                                          |
-| `Overlay`                         | `Portal`                          |                                                                                                                          |
-| `Panel`                           | `OverlayDrawer`                   | `isOpen`/`type`/`onRenderFooterContent` restructured — see [drawer.md](references/drawer.md)                             |
-| `PeoplePicker`                    | `TagPicker`                       |                                                                                                                          |
-| `Persona`                         | `Persona`                         | New package                                                                                                              |
-| `Pivot` / `PivotItem`             | `TabList` / `Tab`                 | Content moves outside TabList — see [tabs.md](references/tabs.md)                                                        |
-| `PrimaryButton`                   | `Button`                          | `appearance="primary"`                                                                                                   |
-| `ProgressIndicator`               | `ProgressBar`                     | `percentComplete` → `value`; label → `<Field>` — see [progressbar.md](references/progressbar.md)                         |
-| `Rating`                          | `Rating`                          |                                                                                                                          |
-| `SearchBox`                       | `SearchBox`                       | New package                                                                                                              |
-| `Separator`                       | `Divider`                         |                                                                                                                          |
-| `Shimmer`                         | `Skeleton`                        |                                                                                                                          |
-| `Slider`                          | `Slider`                          | New package; label extraction, `onChange` type change — see [slider.md](references/slider.md)                            |
-| `SpinButton`                      | `SpinButton`                      | New package; label extraction, `onChange` type change — see [spinbutton.md](references/spinbutton.md)                    |
-| `Spinner`                         | `Spinner`                         | `SpinnerSize` enum → string `size`; `labelPosition` renamed — see [spinner.md](references/spinner.md)                    |
-| `SplitButton`                     | `SplitButton` with `Menu` trigger |                                                                                                                          |
-| `Stack` / `StackItem`             | `makeStyles` + flexbox            | No v9 equivalent — see [stack.md](references/stack.md)                                                                   |
-| `SwatchColorPicker`               | `SwatchPicker`                    |                                                                                                                          |
-| `TagPicker`                       | `TagPicker`                       | New package                                                                                                              |
-| `TeachingBubble`                  | `TeachingPopover`                 |                                                                                                                          |
-| `Text`                            | `Text`                            | New package                                                                                                              |
-| `TextField`                       | `Input` / `Textarea`              | multiline → Textarea — see [input.md](references/input.md)                                                               |
-| `ThemeProvider`                   | `FluentProvider`                  | see [theme.md](references/theme.md)                                                                                      |
-| `TimePicker`                      | `TimePickerCompat`                | `@fluentui/react-timepicker-compat`                                                                                      |
-| `Toggle`                          | `Switch`                          |                                                                                                                          |
-| `ToggleButton`                    | `ToggleButton`                    | New package                                                                                                              |
-| `Tooltip`                         | `Tooltip`                         | Children = trigger; `directionalHint` → `positioning`; `relationship` required — see [tooltip.md](references/tooltip.md) |
+| v8                                | v9                                                         | Notes                                                                                                                                             |
+| --------------------------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ActionButton`                    | `Button`                                                   | `appearance="transparent"`                                                                                                                        |
+| `Breadcrumb`                      | `Breadcrumb`                                               | `items` array → declarative `BreadcrumbItem`/`BreadcrumbButton`/`BreadcrumbLink` children — see [breadcrumb.md](references/breadcrumb.md)         |
+| `Calendar`                        | `CalendarCompat`                                           | `@fluentui/react-calendar-compat`                                                                                                                 |
+| `Callout`                         | `Popover`                                                  | Composable trigger/surface; `target` ref → `PopoverTrigger` — see [callout.md](references/callout.md)                                             |
+| `Checkbox`                        | `Checkbox`                                                 | API mostly same                                                                                                                                   |
+| `ChoiceGroup`                     | `RadioGroup`                                               | Renamed; options array → `Radio` children                                                                                                         |
+| `Coachmark`                       | `TeachingPopover`                                          | Composable trigger/surface/header/body/footer — see [teachingpopover.md](references/teachingpopover.md)                                           |
+| `CommandBar` / `CommandBarButton` | `Toolbar`                                                  | Data-driven → JSX children — see [toolbar.md](references/toolbar.md)                                                                              |
+| `CommandButton`                   | `MenuButton`                                               |                                                                                                                                                   |
+| `CompoundButton`                  | `CompoundButton`                                           | New package                                                                                                                                       |
+| `ColorPicker`                     | `ColorPicker`                                              | New v9 API; `IColor` → `HSV`, `onChange` → `onColorChange` — see [colorpicker.md](references/colorpicker.md)                                      |
+| `ComboBox`                        | `Combobox`                                                 | options array → `Option` children — see [dropdown.md](references/dropdown.md)                                                                     |
+| `ContextualMenu`                  | `Menu`                                                     | Data-driven → JSX children — see [menu.md](references/menu.md)                                                                                    |
+| `DatePicker`                      | `DatePickerCompat`                                         | `@fluentui/react-datepicker-compat`                                                                                                               |
+| `DefaultButton`                   | `Button`                                                   |                                                                                                                                                   |
+| `DetailsList`                     | `DataGrid` / `Table`                                       | Read-only/simple tabular → `Table`+`TableHeader`+`TableRow`+`TableCell`; selection+sort → `DataGrid` — see [datagrid.md](references/datagrid.md)  |
+| `Dialog`                          | `Dialog`                                                   | Composable children; `hidden` → `open` (inverted) — see [dialog.md](references/dialog.md)                                                         |
+| `DocumentCard`                    | `Card`                                                     | `DocumentCard*` → `Card`/`CardHeader`/`CardFooter`/`CardPreview` — see [card.md](references/card.md)                                              |
+| `Dropdown`                        | `Dropdown`                                                 | options array → `Option` children — see [dropdown.md](references/dropdown.md)                                                                     |
+| `Fabric`                          | `FluentProvider`                                           |                                                                                                                                                   |
+| `Facepile`                        | `AvatarGroup`                                              | personas array → children                                                                                                                         |
+| `FocusTrapZone`                   | `Dialog` / `Popover trapFocus` / `@fluentui/react-tabster` | Built-in v9 components handle trapping; for custom traps: `import { useFocusFinders } from '@fluentui/react-tabster'`                             |
+| `FocusZone`                       | `@fluentui/react-tabster`                                  | Arrow-key navigation: `useMergedTabsterAttributes_unstable` or use components that handle it natively (TabList, Menu, etc.)                       |
+| `GroupedList`                     | `Tree` / `List` / `DataGrid`                               | Depends on usage (expand/collapse → Tree; flat list → List; tabular → DataGrid) — see [tree.md](references/tree.md)                               |
+| `Icon`                            | `@fluentui/react-icons`                                    | SVG components                                                                                                                                    |
+| `IconButton`                      | `Button`                                                   | Use `icon` slot only, no text                                                                                                                     |
+| `Image`                           | `Image`                                                    | `imageFit` → `fit`; no wrapper div; `shouldFadeIn` removed — see [image.md](references/image.md)                                                  |
+| `Label`                           | `Label`                                                    | Custom required indicator; prefer `<Field>` for form controls — see [label.md](references/label.md)                                               |
+| `Layer`                           | `Portal`                                                   |                                                                                                                                                   |
+| `Link`                            | `Link`                                                     | `inline` prop for prose context; `appearance="subtle"`; `disabledFocusable` — see [link.md](references/link.md)                                   |
+| `List`                            | `List`                                                     | `items`+`onRenderCell` → `<ListItem>` children; `navigationMode`/`selectionMode` added — see [list.md](references/list.md)                        |
+| `MessageBar`                      | `MessageBar`                                               | Composable children; `messageBarType` → `intent` — see [messagebar.md](references/messagebar.md)                                                  |
+| `Modal`                           | `Dialog`                                                   | `isOpen` → `open`; `isBlocking` → `modalType` — see [dialog.md](references/dialog.md)                                                             |
+| `Nav`                             | `Nav`                                                      | `groups` array → declarative `NavItem`/`NavCategory` children; `NavDrawer` for side panels — see [nav.md](references/nav.md)                      |
+| `OverflowSet`                     | `Overflow`                                                 | Hook-based; `onRenderItem`/`onRenderOverflowButton` → `OverflowItem` + `useOverflowMenu` — see [overflow.md](references/overflow.md)              |
+| `Overlay`                         | `Portal`                                                   |                                                                                                                                                   |
+| `Panel`                           | `OverlayDrawer`                                            | `isOpen`/`type`/`onRenderFooterContent` restructured — see [drawer.md](references/drawer.md)                                                      |
+| `Popup`                           | `Popover` / `Dialog`                                       | Non-modal overlay → `Popover`; blocking/modal behavior → `Dialog`                                                                                 |
+| `PeoplePicker`                    | `TagPicker`                                                | `onResolveSuggestions` → filter `<TagPickerOption>` children; composable structure — see [tagpicker.md](references/tagpicker.md)                  |
+| `Persona`                         | `Persona`                                                  | Slot-based; flat image/initials props → `avatar` slot; `PersonaPresence` enum → string status — see [persona.md](references/persona.md)           |
+| `Pivot` / `PivotItem`             | `TabList` / `Tab`                                          | Content moves outside TabList — see [tabs.md](references/tabs.md)                                                                                 |
+| `PrimaryButton`                   | `Button`                                                   | `appearance="primary"`                                                                                                                            |
+| `ProgressIndicator`               | `ProgressBar`                                              | `percentComplete` → `value`; label → `<Field>` — see [progressbar.md](references/progressbar.md)                                                  |
+| `Rating`                          | `Rating`                                                   | `rating` → `value`; `readOnly` → `RatingDisplay`; `icon` string → `iconFilled`/`iconOutline` components — see [rating.md](references/rating.md)   |
+| `SearchBox`                       | `SearchBox`                                                | `onSearch` → `onKeyDown`; `onClear` → `onChange` with `''`; `underlined` → `appearance="underline"` — see [searchbox.md](references/searchbox.md) |
+| `Separator`                       | `Divider`                                                  | Simple rename; new `appearance`/`inset` props — see [separator.md](references/separator.md)                                                       |
+| `Shimmer`                         | `Skeleton`                                                 | `isDataLoaded` removed; `shimmerElements` → `<SkeletonItem>` children — see [skeleton.md](references/skeleton.md)                                 |
+| `Slider`                          | `Slider`                                                   | New package; label extraction, `onChange` type change — see [slider.md](references/slider.md)                                                     |
+| `SpinButton`                      | `SpinButton`                                               | New package; label extraction, `onChange` type change — see [spinbutton.md](references/spinbutton.md)                                             |
+| `Spinner`                         | `Spinner`                                                  | `SpinnerSize` enum → string `size`; `labelPosition` renamed — see [spinner.md](references/spinner.md)                                             |
+| `SplitButton`                     | `SplitButton` with `Menu` trigger                          |                                                                                                                                                   |
+| `Stack` / `StackItem`             | `makeStyles` + flexbox                                     | No v9 equivalent — see [stack.md](references/stack.md)                                                                                            |
+| `SwatchColorPicker`               | `SwatchPicker`                                             | `colorCells` array → `<ColorSwatch>` children; `onChange` → `onSelectionChange` — see [swatchpicker.md](references/swatchpicker.md)               |
+| `TagPicker`                       | `TagPicker`                                                | `onResolveSuggestions` → filter `<TagPickerOption>` children — see [tagpicker.md](references/tagpicker.md)                                        |
+| `TeachingBubble`                  | `TeachingPopover`                                          | Composable trigger/surface/header/body/footer — see [teachingpopover.md](references/teachingpopover.md)                                           |
+| `Text`                            | `Text`                                                     | `variant` → `size`+`weight`; `nowrap` → `wrap={false}`; use presets (`Body1`, `Title2`, etc.) — see [text.md](references/text.md)                 |
+| `TextField`                       | `Input` / `Textarea`                                       | multiline → Textarea — see [input.md](references/input.md)                                                                                        |
+| `ThemeProvider`                   | `FluentProvider`                                           | see [theme.md](references/theme.md)                                                                                                               |
+| `TimePicker`                      | `TimePickerCompat`                                         | `@fluentui/react-timepicker-compat`                                                                                                               |
+| `Toggle`                          | `Switch`                                                   | `onText`/`offText` removed; `onChange` type changed; `inlineLabel` → `labelPosition` — see [switch.md](references/switch.md)                      |
+| `ToggleButton`                    | `ToggleButton`                                             | New package                                                                                                                                       |
+| `Tooltip`                         | `Tooltip`                                                  | Children = trigger; `directionalHint` → `positioning`; `relationship` required — see [tooltip.md](references/tooltip.md)                          |
 
 ### New in v9 (no v8 equivalent)
 
-`Accordion`, `Avatar`, `AvatarGroup`, `Badge` / `CounterBadge` / `PresenceBadge`, `Carousel`, `Drawer`, `InfoLabel`, `Popover`, `ProgressBar`, `Skeleton`, `Switch`, `SwatchPicker`, `Toast` / `Toaster`, `TeachingPopover`, `TabList`
+`Accordion`, `Avatar`, `AvatarGroup`, `Badge` / `CounterBadge` / `PresenceBadge`, `Carousel`, `Drawer`, `InfoLabel`, `Popover`, `Toast` / `Toaster`, `TabList`
 
 #### Toast / Toaster (quick start)
 
@@ -267,9 +385,37 @@ dispatchToast(
 
 `intent` values: `"info"` (default) | `"success"` | `"warning"` | `"error"`.
 
+#### InfoLabel (quick start)
+
+`InfoLabel` combines a `Label` with an info icon that shows a `Tooltip`. Use it to replace the v8 pattern of `TooltipHost` wrapping an info icon placed beside a `Label`:
+
+```tsx
+// v8 — manual pattern: label + TooltipHost + info icon
+import { Label, TooltipHost } from '@fluentui/react';
+<TooltipHost content="This field is required for billing.">
+  <Label htmlFor="field">
+    Invoice number <Icon iconName="Info" />
+  </Label>
+</TooltipHost>;
+
+// v9 — InfoLabel (built-in)
+import { InfoLabel } from '@fluentui/react-components';
+<InfoLabel info="This field is required for billing." htmlFor="field">
+  Invoice number
+</InfoLabel>;
+```
+
 ### Deprecated with no v9 equivalent
 
-`ActivityItem`, `Announced`, `HoverCard`, `MarqueeSelection`, `Pickers`, `ResizeGroup`, `ScrollablePane`
+| v8                 | Recommended alternative                                                                                          |
+| ------------------ | ---------------------------------------------------------------------------------------------------------------- |
+| `ActivityItem`     | Build with `Avatar` + `Text` + `makeStyles` flexbox layout                                                       |
+| `Announced`        | Use a visually-hidden live region: `<div role="status" aria-live="polite" aria-atomic="true">...</div>`          |
+| `HoverCard`        | Use `<Popover>` with `onMouseEnter`/`onMouseLeave` on the trigger (or `openOnHover` prop if available)           |
+| `MarqueeSelection` | Use browser selection APIs or a custom `onPointerDown`/`onPointerMove` drag-select implementation                |
+| `Pickers`          | Use `TagPicker` (multi-select) or `Combobox`/`Dropdown` (single/multi-select) — see tagpicker.md and dropdown.md |
+| `ResizeGroup`      | Use the `Overflow` component (`<Overflow>` + `<OverflowItem>`) — see [overflow.md](references/overflow.md)       |
+| `ScrollablePane`   | Use `overflow: auto` on a CSS container + `position: sticky` for sticky headers; no FluentUI wrapper needed      |
 
 ---
 
@@ -383,6 +529,8 @@ const brandVariants = createBrandVariants(myV8Palette);
 
 ## Per-Component Detail References
 
+> **Reference Precedence Rule:** per-component files in `references/` are more specific than this file. When they conflict, trust the reference file.
+
 Load the relevant file when doing detailed migration work on a specific component:
 
 - **Icons** (`iconProps` → `@fluentui/react-icons`, name mapping) → [references/icons.md](references/icons.md)
@@ -407,3 +555,26 @@ Load the relevant file when doing detailed migration work on a specific componen
 - **ProgressIndicator → ProgressBar** (`percentComplete` → `value`, label → `<Field>`) → [references/progressbar.md](references/progressbar.md)
 - **Callout → Popover** (composable trigger/surface, `directionalHint` → `positioning`, `trapFocus`) → [references/callout.md](references/callout.md)
 - **CommandBar → Toolbar** (data-driven → JSX children, overflow with `Overflow`/`OverflowItem`) → [references/toolbar.md](references/toolbar.md)
+- **ColorPicker** (`IColor` → `HSV`, `onChange` → `onColorChange`, sub-component renames) → [references/colorpicker.md](references/colorpicker.md)
+- **Keytips** (now in `@fluentui/react-keytips` contrib, `KeytipLayer` → `Keytips`, `useKeytipRef` changes) → [references/keytips.md](references/keytips.md)
+- **Card / CardHeader / CardFooter / CardPreview** → [references/card.md](references/card.md)
+- **Image** → [references/image.md](references/image.md)
+- **Label** → [references/label.md](references/label.md)
+- **Textarea** (`TextField multiline` → `Textarea`) → [references/textarea.md](references/textarea.md)
+- **Separator → Divider** → [references/separator.md](references/separator.md)
+- **Charts** (`@fluentui/react-charting` → `@fluentui/react-charts`, native v9 + FluentProvider) → [references/charts.md](references/charts.md)
+- **Link** (`inline` prop for prose, `appearance="subtle"`, `disabledFocusable`) → [references/link.md](references/link.md)
+- **SearchBox** (`onSearch` → `onKeyDown`, `onClear` → `onChange` with `''`, `underlined` → `appearance`) → [references/searchbox.md](references/searchbox.md)
+- **Persona** (slot-based; `imageUrl`/`imageInitials`/`presence` → slots; size/presence enum → string) → [references/persona.md](references/persona.md)
+- **Nav** (`groups` array → `NavItem`/`NavCategory` JSX; `NavDrawer` for side panels) → [references/nav.md](references/nav.md)
+- **OverflowSet → Overflow** (hook-based; `onRenderItem` → `OverflowItem`; `useOverflowMenu`) → [references/overflow.md](references/overflow.md)
+- **GroupedList → Tree / List / DataGrid** (choose target by usage; `items`+`groups` → declarative `TreeItem` children) → [references/tree.md](references/tree.md)
+- **TagPicker / PeoplePicker** (`onResolveSuggestions` → filter `TagPickerOption` children; composable structure) → [references/tagpicker.md](references/tagpicker.md)
+- **Toggle → Switch** (`onText`/`offText` removed; `onChange` type changed; `inlineLabel` → `labelPosition`) → [references/switch.md](references/switch.md)
+- **Shimmer → Skeleton** (`isDataLoaded` removed; `shimmerElements` → `<SkeletonItem>` JSX) → [references/skeleton.md](references/skeleton.md)
+- **TeachingBubble / Coachmark → TeachingPopover** (composable; multi-step carousel support) → [references/teachingpopover.md](references/teachingpopover.md)
+- **Rating** (`rating` → `value`; `readOnly` → `RatingDisplay`; `icon` string → component type; half-star `step`) → [references/rating.md](references/rating.md)
+- **Breadcrumb** (`items` array → `BreadcrumbItem`/`BreadcrumbButton`/`BreadcrumbLink` JSX; overflow via `Overflow`) → [references/breadcrumb.md](references/breadcrumb.md)
+- **Text** (`variant` → `size`+`weight`; `nowrap` → `wrap={false}`; use presets `Body1`, `Title2`, etc.) → [references/text.md](references/text.md)
+- **List** (`items`+`onRenderCell` → `<ListItem>` children; `navigationMode`; `selectionMode`; `onAction`) → [references/list.md](references/list.md)
+- **SwatchColorPicker → SwatchPicker** (`colorCells` → `<ColorSwatch>` children; `onChange` → `onSelectionChange`; `ImageSwatch`/`EmptySwatch`) → [references/swatchpicker.md](references/swatchpicker.md)
diff --git a/skills/fluentui-migrate-v8-to-v9/references/breadcrumb.md b/skills/fluentui-migrate-v8-to-v9/references/breadcrumb.md
new file mode 100644
index 00000000000000..3d0e59440f7ecc
--- /dev/null
+++ b/skills/fluentui-migrate-v8-to-v9/references/breadcrumb.md
@@ -0,0 +1,92 @@
+# Breadcrumb Migration
+
+v9 `Breadcrumb` uses composable JSX children (`BreadcrumbItem`, `BreadcrumbButton`, `BreadcrumbLink`, `BreadcrumbDivider`) instead of an `items` array.
+
+## Architecture Shift
+
+| v8                                     | v9                                                                   |
+| -------------------------------------- | -------------------------------------------------------------------- |
+| `items` array prop                     | Declarative JSX children                                             |
+| `IBreadcrumbItem.text`                 | `<BreadcrumbButton>` children                                        |
+| `IBreadcrumbItem.href`                 | `<BreadcrumbLink href="...">`                                        |
+| `IBreadcrumbItem.onClick`              | `onClick` on `<BreadcrumbButton>`                                    |
+| `IBreadcrumbItem.isCurrentItem`        | `current` on `<BreadcrumbButton>`                                    |
+| `maxDisplayedItems` + `overflowIndex`  | Use `<Overflow>` + `<OverflowItem>` — see [overflow.md](overflow.md) |
+| `onRenderItem` / `onRenderItemContent` | Render `<BreadcrumbItem>` directly                                   |
+| `dividerAs`                            | `<BreadcrumbDivider>` (place manually between items)                 |
+
+## Component Tree
+
+```tsx
+import {
+  Breadcrumb,
+  BreadcrumbItem,
+  BreadcrumbButton,
+  BreadcrumbLink,
+  BreadcrumbDivider,
+} from '@fluentui/react-components';
+```
+
+| v9 Component        | Purpose                                                                         |
+| ------------------- | ------------------------------------------------------------------------------- |
+| `Breadcrumb`        | Container (`<nav>` element)                                                     |
+| `BreadcrumbItem`    | `<li>` wrapper — use around every item                                          |
+| `BreadcrumbLink`    | An `<a>` tag — use for navigable crumbs                                         |
+| `BreadcrumbDivider` | Separator between items (must be placed manually between each `BreadcrumbItem`) |
+| `BreadcrumbButton`  | A `<button>` — use for the current/last crumb or click handlers                 |
+
+## Prop Mapping
+
+| v8 `IBreadcrumbProps` | v9 equivalent                      | Notes                                   |
+| --------------------- | ---------------------------------- | --------------------------------------- |
+| `items`               | JSX children                       |                                         |
+| `maxDisplayedItems`   | `<Overflow>` wrapper               | See overflow.md                         |
+| `overflowIndex`       | `<OverflowItem>` with `priority`   | See overflow.md                         |
+| `onReduceData`        | `useOverflowMenu` hook             | See overflow.md                         |
+| `dividerAs`           | `<BreadcrumbDivider>`              | Place between `BreadcrumbItem` wrappers |
+| `onRenderItem`        | Render `<BreadcrumbItem>` directly |                                         |
+| `focusMode`           | `focusMode` on `<Breadcrumb>`      | `"tab"` (default) \| `"arrow"`          |
+| `size`                | `size` on `<Breadcrumb>`           | `"small"` \| `"medium"` \| `"large"`    |
+| `styles`              | `className` + `makeStyles`         |                                         |
+| `theme`               | —                                  | Use `FluentProvider`                    |
+
+## Before / After
+
+```tsx
+// v8 — data-driven
+import { Breadcrumb } from '@fluentui/react';
+<Breadcrumb
+  items={[
+    { text: 'Home', key: 'home', href: '/' },
+    { text: 'Docs', key: 'docs', href: '/docs' },
+    { text: 'Components', key: 'components', isCurrentItem: true },
+  ]}
+/>;
+
+// v9 — declarative
+import {
+  Breadcrumb,
+  BreadcrumbItem,
+  BreadcrumbButton,
+  BreadcrumbLink,
+  BreadcrumbDivider,
+} from '@fluentui/react-components';
+
+<Breadcrumb aria-label="Breadcrumb">
+  <BreadcrumbItem>
+    <BreadcrumbLink href="/">Home</BreadcrumbLink>
+  </BreadcrumbItem>
+  <BreadcrumbDivider />
+  <BreadcrumbItem>
+    <BreadcrumbLink href="/docs">Docs</BreadcrumbLink>
+  </BreadcrumbItem>
+  <BreadcrumbDivider />
+  <BreadcrumbItem>
+    <BreadcrumbButton current>Components</BreadcrumbButton>
+  </BreadcrumbItem>
+</Breadcrumb>;
+```
+
+## Overflow (maxDisplayedItems equivalent)
+
+Combine with `<Overflow>` and `useOverflowMenu` to collapse items when the container is too narrow — see [overflow.md](overflow.md) for the full pattern.
diff --git a/skills/fluentui-migrate-v8-to-v9/references/button.md b/skills/fluentui-migrate-v8-to-v9/references/button.md
index 6468df87a8d488..f22605e91cbc9c 100644
--- a/skills/fluentui-migrate-v8-to-v9/references/button.md
+++ b/skills/fluentui-migrate-v8-to-v9/references/button.md
@@ -84,6 +84,38 @@ import { Button } from '@fluentui/react-components';
 supports `href`, `target`, `rel`). Use `Link` for inline prose links; use `Button as="a"` when the
 design needs a button shape that navigates.
 
+### Button with dropdown menu (`menuProps`)
+
+```tsx
+// v8 — button that opens a dropdown via menuProps
+import { DefaultButton } from '@fluentui/react';
+<DefaultButton
+  text="Options"
+  menuProps={{
+    items: [
+      { key: 'edit', text: 'Edit', onClick: handleEdit },
+      { key: 'delete', text: 'Delete', onClick: handleDelete },
+    ],
+  }}
+/>;
+
+// v9 — MenuButton inside Menu
+import { Menu, MenuTrigger, MenuPopover, MenuList, MenuItem, MenuButton } from '@fluentui/react-components';
+<Menu>
+  <MenuTrigger disableButtonEnhancement>
+    <MenuButton>Options</MenuButton>
+  </MenuTrigger>
+  <MenuPopover>
+    <MenuList>
+      <MenuItem onClick={handleEdit}>Edit</MenuItem>
+      <MenuItem onClick={handleDelete}>Delete</MenuItem>
+    </MenuList>
+  </MenuPopover>
+</Menu>;
+```
+
+For a primary-styled dropdown button: `<MenuButton appearance="primary">`.
+
 ### SplitButton
 
 ```tsx
diff --git a/skills/fluentui-migrate-v8-to-v9/references/card.md b/skills/fluentui-migrate-v8-to-v9/references/card.md
new file mode 100644
index 00000000000000..f9adcfecb42046
--- /dev/null
+++ b/skills/fluentui-migrate-v8-to-v9/references/card.md
@@ -0,0 +1,79 @@
+# Card Migration
+
+v8 `DocumentCard` and its variants map to v9's composable `Card` family in `@fluentui/react-components`.
+
+## Component Renames
+
+| v8                                     | v9            | Notes                                             |
+| -------------------------------------- | ------------- | ------------------------------------------------- |
+| `DocumentCard`                         | `Card`        | More generic, less opinionated                    |
+| `DocumentCardDetails`                  | `CardHeader`  |                                                   |
+| `DocumentCardTitle`                    | —             | Use `Text` component                              |
+| `DocumentCardActivity` (activity prop) | `CardHeader`  | Use `description` prop                            |
+| `DocumentCardActivity` (people prop)   | `CardHeader`  | Use `image` + `header` props                      |
+| `DocumentCardActions`                  | `CardFooter`  |                                                   |
+| `DocumentCardPreview`                  | `CardPreview` | No `previewImages` array — pass children directly |
+
+## Prop Mapping — DocumentCard → Card
+
+| v8              | v9          | Notes                                                |
+| --------------- | ----------- | ---------------------------------------------------- |
+| `className`     | `className` |                                                      |
+| `componentRef`  | `ref`       |                                                      |
+| `onClick`       | `onClick`   |                                                      |
+| `onClickHref`   | —           | Implement via `onClick`                              |
+| `onClickTarget` | —           | Implement via `onClick`                              |
+| `role`          | `role`      |                                                      |
+| `styles`        | `className` |                                                      |
+| `theme`         | —           | Use `FluentProvider`                                 |
+| `type`          | —           | Use `orientation="horizontal"` for horizontal layout |
+
+## Prop Mapping — DocumentCardActions → CardFooter
+
+| v8             | v9          | Notes                                                 |
+| -------------- | ----------- | ----------------------------------------------------- |
+| `className`    | `className` |                                                       |
+| `componentRef` | `ref`       |                                                       |
+| `views`        | —           | Create a view-count element and pass to `action` prop |
+| `role`         | `role`      |                                                       |
+| `styles`       | `className` |                                                       |
+| `theme`        | —           | Use `FluentProvider`                                  |
+
+## Prop Mapping — DocumentCardPreview → CardPreview
+
+| v8                             | v9          | Notes                                            |
+| ------------------------------ | ----------- | ------------------------------------------------ |
+| `className`                    | `className` |                                                  |
+| `componentRef`                 | `ref`       |                                                  |
+| `previewImages`                | `children`  | Pass `<img>` or any element as children directly |
+| `maxDisplayCount`              | —           | Implement custom overflow via `Card` composition |
+| `getOverflowDocumentCountText` | —           | Implement custom overflow via `Card` composition |
+| `styles`                       | `className` |                                                  |
+| `theme`                        | —           | Use `FluentProvider`                             |
+
+## Before / After
+
+```tsx
+// v8
+import { DocumentCard, DocumentCardPreview, DocumentCardTitle, DocumentCardActivity } from '@fluentui/react';
+
+<DocumentCard onClick={handleClick}>
+  <DocumentCardPreview previewImages={[{ previewImageSrc: imgSrc }]} />
+  <DocumentCardTitle title="Report.pdf" />
+  <DocumentCardActivity activity="Modified Jan 1" people={[{ name: 'Alice', profileImageSrc: avatarSrc }]} />
+</DocumentCard>;
+
+// v9
+import { Card, CardHeader, CardPreview } from '@fluentui/react-components';
+
+<Card onClick={handleClick}>
+  <CardPreview>
+    <img src={imgSrc} alt="Report preview" />
+  </CardPreview>
+  <CardHeader
+    image={<img src={avatarSrc} alt="Alice" />}
+    header={<Text weight="semibold">Report.pdf</Text>}
+    description="Modified Jan 1 · Alice"
+  />
+</Card>;
+```
diff --git a/skills/fluentui-migrate-v8-to-v9/references/charts.md b/skills/fluentui-migrate-v8-to-v9/references/charts.md
new file mode 100644
index 00000000000000..52c6ba902a05c0
--- /dev/null
+++ b/skills/fluentui-migrate-v8-to-v9/references/charts.md
@@ -0,0 +1,49 @@
+# Charts Migration
+
+v9 charts are available in **`@fluentui/react-charts`** (v9). Migrate away from `@fluentui/react-charting` (v8).
+
+```sh
+npm install @fluentui/react-charts
+```
+
+## Package Rename
+
+| v8                         | v9                       |
+| -------------------------- | ------------------------ |
+| `@fluentui/react-charting` | `@fluentui/react-charts` |
+
+The v9 package is built on Griffel (`makeStyles`) and integrates natively with `FluentProvider` — no theme shim required.
+
+## Setup
+
+Wrap your app (or the chart subtree) with `FluentProvider` as you would for any v9 component:
+
+```tsx
+import { FluentProvider, webLightTheme } from '@fluentui/react-components';
+import { DonutChart } from '@fluentui/react-charts';
+
+<FluentProvider theme={webLightTheme}>
+  <DonutChart data={chartData} />
+</FluentProvider>;
+```
+
+## Using v9 Design Tokens in Chart Data
+
+Pass token values directly to chart color properties for consistent theming:
+
+```tsx
+import { tokens } from '@fluentui/react-components';
+
+const chartData = {
+  chartTitle: 'Usage',
+  chartData: [
+    { legend: 'Active', data: 40, color: tokens.colorBrandBackground },
+    { legend: 'Inactive', data: 60, color: tokens.colorNeutralBackground3 },
+  ],
+};
+```
+
+## Resources
+
+- [Fluent Charting docs](https://aka.ms/fluentCharting)
+- Reach out to the charting team: tag `@microsoft/charting-team` in GitHub Discussions
diff --git a/skills/fluentui-migrate-v8-to-v9/references/colorpicker.md b/skills/fluentui-migrate-v8-to-v9/references/colorpicker.md
new file mode 100644
index 00000000000000..83a175c42ce6b3
--- /dev/null
+++ b/skills/fluentui-migrate-v8-to-v9/references/colorpicker.md
@@ -0,0 +1,59 @@
+# ColorPicker Migration
+
+v9 ships a new `ColorPicker` in `@fluentui/react-components` with a revised API. The core type changes from `IColor` to `HSV`, and the event callback is renamed.
+
+## Sub-Component Renames
+
+| v8                  | v9             | Notes                                                       |
+| ------------------- | -------------- | ----------------------------------------------------------- |
+| `ColorPicker`       | `ColorPicker`  | New package                                                 |
+| `ColorRectangle`    | `ColorArea`    | Renamed                                                     |
+| `ColorSlider`       | `ColorSlider`  | `type`/`isAlpha` → `channel`; add `AlphaSlider` for alpha   |
+| `SwatchColorPicker` | `SwatchPicker` | Separate component — see [swatchpicker.md](swatchpicker.md) |
+
+## Prop Mapping — ColorPicker
+
+| v8                             | v9              | Notes                                    |
+| ------------------------------ | --------------- | ---------------------------------------- |
+| `color`                        | `color`         | Type changed: `IColor \| string` → `HSV` |
+| `onChange`                     | `onColorChange` | Renamed; type changed to `EventHandler`  |
+| `alphaType`                    | —               | Use `AlphaSlider` component separately   |
+| `alphaSliderHidden`            | —               | Use `AlphaSlider` component separately   |
+| `showPreview`                  | —               | Use `ColorSwatch` instead                |
+| `hexLabel` / `redLabel` / etc. | —               | Not supported                            |
+| `styles`                       | `className`     |                                          |
+| `theme`                        | —               | Use `FluentProvider`                     |
+| `tooltipProps`                 | —               | Use `Tooltip` component                  |
+
+## Prop Mapping — ColorArea (was ColorRectangle)
+
+| v8         | v9              | Notes                                   |
+| ---------- | --------------- | --------------------------------------- |
+| `color`    | `color`         | Type changed: `IColor` → `HSV`          |
+| `onChange` | `onColorChange` | Renamed; type changed to `EventHandler` |
+| `minSize`  | —               | Not supported                           |
+| —          | `defaultColor`  | New: default color for uncontrolled use |
+| —          | `shape`         | New prop                                |
+
+## Prop Mapping — ColorSlider
+
+| v8         | v9             | Notes                                                                            |
+| ---------- | -------------- | -------------------------------------------------------------------------------- |
+| `type`     | `channel`      | Values: `"hue"` \| `"saturation"` \| `"brightness"`; for alpha use `AlphaSlider` |
+| `color`    | `color`        | Type changed: `IColor` → `HSV`                                                   |
+| `isAlpha`  | —              | Use `AlphaSlider` component                                                      |
+| `minValue` | —              | Use native `min` prop                                                            |
+| `maxValue` | —              | Use native `max` prop                                                            |
+| —          | `defaultColor` | New: default color for uncontrolled use                                          |
+
+## Before / After
+
+```tsx
+// v8
+import { ColorPicker } from '@fluentui/react';
+<ColorPicker color={color} onChange={(_, c) => setColor(c)} />;
+
+// v9
+import { ColorPicker } from '@fluentui/react-components';
+<ColorPicker color={hsv} onColorChange={(_, data) => setHsv(data.color)} />;
+```
diff --git a/skills/fluentui-migrate-v8-to-v9/references/image.md b/skills/fluentui-migrate-v8-to-v9/references/image.md
new file mode 100644
index 00000000000000..142f3dbf702b43
--- /dev/null
+++ b/skills/fluentui-migrate-v8-to-v9/references/image.md
@@ -0,0 +1,67 @@
+# Image Migration
+
+v9 `Image` renders a plain `<img>` element (no wrapper `<div>`). The fit API is renamed and simplified.
+
+## Key Changes
+
+- **No wrapper div**: v8 wrapped `<img>` in a styled `<div>`; v9 applies styles directly to `<img>`. This may affect existing layouts.
+- **`imageFit` → `fit`**: maps directly to CSS `object-fit` / `object-position`
+- **`shouldFadeIn` / `shouldStartVisible` / `onLoadingStateChange` removed**: use native `onLoad` / `onError` events
+
+## Fit Mapping
+
+| v8 `imageFit`                   | v9 `fit`                | CSS equivalent                                 |
+| ------------------------------- | ----------------------- | ---------------------------------------------- |
+| `ImageFit.contain`              | `"contain"`             | `object-fit: contain; object-position: center` |
+| `ImageFit.cover`                | `"cover"`               | `object-fit: cover; object-position: center`   |
+| `ImageFit.center`               | `"center"`              | `object-fit: none; object-position: center`    |
+| `ImageFit.none`                 | `"none"`                | `object-fit: none; object-position: left top`  |
+| `centerContain` / `centerCover` | use `contain` / `cover` | Centering is the default in v9                 |
+
+> **Note**: `fit="none"` and `fit="center"` are **not** exact drop-ins for v8 equivalents. v8 used absolute positioning + transform; v9 uses `object-fit`. With `shape="circular"`, use `fit="cover"` to ensure the image fills the box.
+
+## Prop Mapping
+
+| v8                     | v9            | Notes                                           |
+| ---------------------- | ------------- | ----------------------------------------------- |
+| `height`               | `height`      |                                                 |
+| `width`                | `width`       |                                                 |
+| `className`            | `className`   |                                                 |
+| `imageFit`             | `fit`         | See fit mapping above                           |
+| `coverStyle`           | `fit="cover"` |                                                 |
+| `maximizeFrame`        | `block`       | Renamed                                         |
+| `styles`               | `className`   | Use `makeStyles`                                |
+| `shouldFadeIn`         | —             | Implement via `makeStyles` + `onLoad` animation |
+| `shouldStartVisible`   | —             | Use `onLoad` / `onError` events                 |
+| `loading`              | —             | Use `onLoad` / `onError` events                 |
+| `onLoadingStateChange` | —             | Use `onLoad` / `onError` events                 |
+| `theme`                | —             | Use `FluentProvider`                            |
+
+The boolean style props from v8 (`isCenter`, `isCoverContain`, `isLandscape`, `isError`, `isLoaded`, etc.) are removed — use `className` with `makeStyles` instead.
+
+## Before / After
+
+```tsx
+// v8
+import { Image, ImageFit } from '@fluentui/react';
+<Image src={imgSrc} imageFit={ImageFit.cover} width={200} height={150} shouldFadeIn />;
+
+// v9
+import { Image, makeStyles } from '@fluentui/react-components';
+
+const useStyles = makeStyles({
+  img: {
+    // Griffel: pass keyframe stops directly to animationName (no @keyframes key)
+    animationName: {
+      from: { opacity: 0 },
+      to: { opacity: 1 },
+    },
+    animationDuration: '300ms',
+  },
+});
+
+function MyImage() {
+  const s = useStyles();
+  return <Image src={imgSrc} fit="cover" width={200} height={150} className={s.img} />;
+}
+```
diff --git a/skills/fluentui-migrate-v8-to-v9/references/keytips.md b/skills/fluentui-migrate-v8-to-v9/references/keytips.md
new file mode 100644
index 00000000000000..60fcb626ebf44e
--- /dev/null
+++ b/skills/fluentui-migrate-v8-to-v9/references/keytips.md
@@ -0,0 +1,76 @@
+# Keytips Migration
+
+v9 Keytips are in **`@fluentui/react-keytips`** (Fluent UI contrib), not the main `@fluentui/react-components` package.
+
+```sh
+npm install @fluentui/react-keytips
+```
+
+v9 components do **not** have a `keytipProps` prop — keytips are attached via the `useKeytipRef` hook.
+
+## Component Renames
+
+| v8              | v9        | Notes                    |
+| --------------- | --------- | ------------------------ |
+| `KeytipLayer`   | `Keytips` | Mount once near the root |
+| `useKeytipData` | —         | No equivalent            |
+| `KeytipData`    | —         | No equivalent            |
+
+## Prop Mapping — KeytipLayer → Keytips
+
+| v8                     | v9                   | Notes                                                                |
+| ---------------------- | -------------------- | -------------------------------------------------------------------- |
+| `keytipStartSequence`  | `startSequence`      | Type changed: `IKeytipTransitionKey[]` → `string` (e.g. `"alt+f10"`) |
+| `keytipExitSequence`   | `exitSequence`       | Same type change                                                     |
+| `keytipReturnSequence` | `returnSequence`     | Same type change                                                     |
+| `onEnterKeytipMode`    | `onEnterKeytipsMode` | Renamed; type changed to `EventHandler`                              |
+| `onExitKeytipMode`     | `onExitKeytipsMode`  | Renamed; type changed to `EventHandler`                              |
+| `content`              | `content`            | Unchanged                                                            |
+| `styles`               | —                    | Component is logic-only, no styles                                   |
+| —                      | `invokeEvent`        | New: event that triggers keytips                                     |
+| —                      | `startDelay`         | New: delay before entering keytip mode                               |
+
+## Prop Mapping — IKeytipProps → KeytipProps
+
+| v8                    | v9                 | Notes                                                  |
+| --------------------- | ------------------ | ------------------------------------------------------ |
+| `content`             | `content`          | Unchanged                                              |
+| `keySequences`        | `keySequences`     | Unchanged                                              |
+| `hasMenu`             | `hasMenu`          | Unchanged                                              |
+| `visible`             | `visible`          | Unchanged                                              |
+| `hasDynamicChildren`  | `dynamic`          | Renamed                                                |
+| `hasOverflowSubMenu`  | —                  | Use `hasMenu` instead                                  |
+| `overflowSetSequence` | `overflowSequence` | Renamed                                                |
+| `callOutProps`        | `positioning`      | Type changed to `PositioningProps`                     |
+| `disabled`            | —                  | Not supported; keytips don't show on disabled elements |
+| `onExecute`           | `onExecute`        | Type changed to `ExecuteKeytipEventHandler`            |
+| `onReturn`            | `onReturn`         | Type changed to `ReturnKeytipEventHandler`             |
+| `styles`              | —                  | Not supported                                          |
+| `theme`               | —                  | Not supported                                          |
+
+## useKeytipRef Changes
+
+| v8 (useKeytipRef) | v9  | Notes                        |
+| ----------------- | --- | ---------------------------- |
+| `keytipProps`     | —   | Use individual props instead |
+| `ariaDescribedBy` | —   | Not supported                |
+| `disabled`        | —   | Not supported                |
+
+## Before / After
+
+```tsx
+// v8 — keytipProps on the component
+import { DefaultButton } from '@fluentui/react';
+<DefaultButton keytipProps={{ content: 'B', keySequences: ['b'] }}>Action</DefaultButton>;
+
+// v9 — useKeytipRef hook
+import { Button } from '@fluentui/react-components';
+import { Keytips, useKeytipRef } from '@fluentui/react-keytips';
+
+// Mount once near root:
+<Keytips startSequence="alt+f10" />;
+
+// Attach to any component:
+const keytipRef = useKeytipRef({ keySequences: ['b'], content: 'B' });
+<Button ref={keytipRef}>Action</Button>;
+```
diff --git a/skills/fluentui-migrate-v8-to-v9/references/label.md b/skills/fluentui-migrate-v8-to-v9/references/label.md
new file mode 100644
index 00000000000000..ff573193feaae9
--- /dev/null
+++ b/skills/fluentui-migrate-v8-to-v9/references/label.md
@@ -0,0 +1,41 @@
+# Label Migration
+
+v9 `Label` is a near drop-in replacement. The main addition is support for a **custom required indicator** (pass a custom element to `required` instead of just `true`).
+
+## Prop Mapping
+
+| v8             | v9          | Notes                                              |
+| -------------- | ----------- | -------------------------------------------------- |
+| `componentRef` | `ref`       |                                                    |
+| `disabled`     | `disabled`  |                                                    |
+| `required`     | `required`  | v9 also accepts a ReactNode for a custom indicator |
+| `styles`       | `className` |                                                    |
+| `theme`        | —           | Use `FluentProvider`                               |
+| `as`           | —           | Not supported in v9                                |
+
+## Before / After
+
+```tsx
+// v8
+import { Label } from '@fluentui/react';
+<Label required>Email</Label>;
+
+// v9
+import { Label } from '@fluentui/react-components';
+<Label required>Email</Label>;
+// Custom required indicator:
+<Label required={<span aria-hidden> *</span>}>Email</Label>;
+```
+
+## Usage with Form Controls
+
+In v9, prefer wrapping form controls with `<Field>` rather than using a standalone `<Label>`:
+
+```tsx
+import { Field, Input } from '@fluentui/react-components';
+<Field label="Email" required validationState="error" validationMessage="Required">
+  <Input />
+</Field>;
+```
+
+`Field` wires up `htmlFor` / `aria-describedby` automatically. Use a standalone `Label` only when you need fine-grained control over placement.
diff --git a/skills/fluentui-migrate-v8-to-v9/references/link.md b/skills/fluentui-migrate-v8-to-v9/references/link.md
new file mode 100644
index 00000000000000..f664ab366536e8
--- /dev/null
+++ b/skills/fluentui-migrate-v8-to-v9/references/link.md
@@ -0,0 +1,81 @@
+# Link Migration
+
+v9 `Link` is a near drop-in replacement with improved accessibility and an `inline` prop for use alongside body text.
+
+## Key Differences
+
+- Renders as `<a>` when `href` is provided, as `<button>` otherwise (same as v8)
+- New `appearance="subtle"` removes the brand color for a neutral look
+- New `inline` prop adds an underline and adjusts spacing for use inside prose text
+- `disabledFocusable` keeps the link in the tab order while disabled (accessibility improvement)
+- No `styles` prop — use `className` + `makeStyles`
+
+## Prop Mapping
+
+| v8 `ILinkProps` | v9 `LinkProps`      | Notes                                             |
+| --------------- | ------------------- | ------------------------------------------------- |
+| `href`          | `href`              |                                                   |
+| `target`        | `target`            |                                                   |
+| `rel`           | `rel`               |                                                   |
+| `onClick`       | `onClick`           |                                                   |
+| `disabled`      | `disabled`          |                                                   |
+| `componentRef`  | `ref`               |                                                   |
+| `styles`        | `className`         | Use `makeStyles`                                  |
+| `theme`         | —                   | Use `FluentProvider`                              |
+| —               | `appearance`        | New: `"default"` \| `"subtle"`                    |
+| —               | `inline`            | New: underlined, inline-text variant              |
+| —               | `disabledFocusable` | New: focusable while disabled (for accessibility) |
+| —               | `as`                | New: `"a"` \| `"button"` \| `"span"`              |
+
+## Before / After
+
+```tsx
+// v8
+import { Link } from '@fluentui/react';
+<Link href="/docs">Read the docs</Link>;
+<Link onClick={handleClick}>Click me</Link>;
+
+// v9
+import { Link } from '@fluentui/react-components';
+<Link href="/docs">Read the docs</Link>;
+<Link onClick={handleClick}>Click me</Link>;
+```
+
+## Inline Text Link
+
+When a link appears inside a sentence, add `inline` to get proper underline and spacing:
+
+```tsx
+// v9
+<p>
+  See the{' '}
+  <Link href="/docs" inline>
+    documentation
+  </Link>{' '}
+  for details.
+</p>
+```
+
+Without `inline`, the link uses no underline by default — only appropriate in visually discrete nav areas.
+
+## Subtle Appearance
+
+```tsx
+<Link href="/help" appearance="subtle">
+  Help
+</Link>
+```
+
+## Render as `<span>`
+
+Renders as `<span role="button">` — wraps correctly in multiline text unlike `<button>`:
+
+```tsx
+<Link as="span" inline onClick={handleClick}>
+  Terms of service
+</Link>
+```
+
+## Accessibility Notes
+
+Links **must** have an underline (use `inline`) unless they are in a visually discrete region containing only links or interactive controls, or all links have an icon indicating interactivity.
diff --git a/skills/fluentui-migrate-v8-to-v9/references/list.md b/skills/fluentui-migrate-v8-to-v9/references/list.md
new file mode 100644
index 00000000000000..41021ad02133c6
--- /dev/null
+++ b/skills/fluentui-migrate-v8-to-v9/references/list.md
@@ -0,0 +1,92 @@
+# List Migration
+
+v9 `List` + `ListItem` replaces v8 `List`. The v9 component adds first-class keyboard navigation, selection, and multi-action support.
+
+## Key Differences
+
+- v8 `List` used `items` array + `onRenderCell` callback; v9 uses declarative `<ListItem>` children
+- v9 has explicit `navigationMode` and `selectionMode` props
+- `onAction` replaces `onClick` on items for consistent keyboard + mouse handling
+
+## Prop Mapping — List
+
+| v8 `IListProps`        | v9 `ListProps`               | Notes                                    |
+| ---------------------- | ---------------------------- | ---------------------------------------- |
+| `items`                | `<ListItem>` children        |                                          |
+| `onRenderCell`         | Render `<ListItem>` directly |                                          |
+| `onShouldVirtualize`   | —                            | v9 does not have built-in virtualization |
+| `renderedWindowsAhead` | —                            | Removed                                  |
+| `styles`               | `className`                  | Use `makeStyles`                         |
+| `theme`                | —                            | Use `FluentProvider`                     |
+
+## New v9 Props
+
+| Prop                   | Values / Notes                                                                                   |
+| ---------------------- | ------------------------------------------------------------------------------------------------ |
+| `navigationMode`       | `"items"` (single action, arrow navigation) \| `"composite"` (multiple actions, grid navigation) |
+| `selectionMode`        | `"single"` \| `"multiselect"`                                                                    |
+| `selectedItems`        | Controlled selected set (`Iterable<string>`)                                                     |
+| `defaultSelectedItems` | Uncontrolled initial selection                                                                   |
+| `onSelectionChange`    | `(_, data: { selectedItems: Set<string> }) => void`                                              |
+
+## ListItem Props
+
+| Prop        | Notes                                                                               |
+| ----------- | ----------------------------------------------------------------------------------- |
+| `value`     | Unique identifier for selection                                                     |
+| `onAction`  | Called on click, Enter, or Space (when selection not active). Prefer over `onClick` |
+| `checkmark` | Slot for the selection checkmark                                                    |
+
+## Before / After
+
+```tsx
+// v8 — data-driven
+import { List } from '@fluentui/react';
+<List items={contacts} onRenderCell={item => <div onClick={() => openContact(item)}>{item?.name}</div>} />;
+
+// v9 — declarative + keyboard-accessible
+import { List, ListItem } from '@fluentui/react-components';
+<List navigationMode="items">
+  {contacts.map(contact => (
+    <ListItem key={contact.id} value={contact.id} onAction={() => openContact(contact)}>
+      {contact.name}
+    </ListItem>
+  ))}
+</List>;
+```
+
+## Selectable List
+
+```tsx
+const [selected, setSelected] = React.useState(new Set<string>());
+
+<List
+  navigationMode="items"
+  selectionMode="multiselect"
+  selectedItems={selected}
+  onSelectionChange={(_, data) => setSelected(data.selectedItems)}
+>
+  {items.map(item => (
+    <ListItem key={item.id} value={item.id}>
+      {item.name}
+    </ListItem>
+  ))}
+</List>;
+```
+
+## Multi-Action Items
+
+When each item has multiple interactive elements (e.g. a primary action + secondary buttons), use `navigationMode="composite"` and give each direct child a `role="gridcell"`:
+
+```tsx
+<List navigationMode="composite">
+  {items.map(item => (
+    <ListItem key={item.id} value={item.id} onAction={() => open(item)}>
+      <div role="gridcell">{item.name}</div>
+      <div role="gridcell">
+        <Button onClick={() => archive(item)}>Archive</Button>
+      </div>
+    </ListItem>
+  ))}
+</List>
+```
diff --git a/skills/fluentui-migrate-v8-to-v9/references/nav.md b/skills/fluentui-migrate-v8-to-v9/references/nav.md
new file mode 100644
index 00000000000000..5d1ccec51b38bf
--- /dev/null
+++ b/skills/fluentui-migrate-v8-to-v9/references/nav.md
@@ -0,0 +1,112 @@
+# Nav Migration
+
+v8 `Nav` used a `groups` array of `INavLinkGroup` with nested `INavLink` items. v9 `Nav` uses declarative JSX children (`NavItem`, `NavCategory`, `NavCategoryItem`) and integrates with `NavDrawer` for side-drawer navigation.
+
+Import from `@fluentui/react-components` — no separate package required.
+
+## Architecture Shift
+
+| v8                         | v9                                     |
+| -------------------------- | -------------------------------------- |
+| `groups` array prop        | `<NavCategory>` / `<NavItem>` children |
+| `INavLink.name`            | `<NavItem>` children (text)            |
+| `INavLink.url`             | `href` on `<NavItem>`                  |
+| `INavLink.onClick`         | `onClick` on `<NavItem>`               |
+| `INavLink.links` (nesting) | `<NavCategory>` + `<NavCategoryItem>`  |
+| `onLinkClick`              | `onNavItemSelect` on `<Nav>`           |
+| `onLinkExpandClick`        | `onNavCategoryItemToggle` on `<Nav>`   |
+| `selectedKey`              | `selectedValue` on `<Nav>`             |
+
+## Component Tree
+
+```tsx
+import {
+  Nav,
+  NavCategory,
+  NavCategoryItem,
+  NavDivider,
+  NavDrawer,
+  NavDrawerBody,
+  NavDrawerHeader,
+  NavItem,
+  NavSectionHeader,
+  NavSubItem,
+  NavSubItemGroup,
+} from '@fluentui/react-components';
+```
+
+| v9 Component       | Purpose                                          |
+| ------------------ | ------------------------------------------------ |
+| `NavDrawer`        | Side-drawer container (replaces `Panel` + `Nav`) |
+| `NavDrawerHeader`  | Header with hamburger button                     |
+| `NavDrawerBody`    | Scrollable body area                             |
+| `Nav`              | The nav list (standalone or inside `NavDrawer`)  |
+| `NavItem`          | Leaf navigation item                             |
+| `NavCategory`      | Expandable group (like v8 `INavLinkGroup`)       |
+| `NavCategoryItem`  | The clickable header of a `NavCategory`          |
+| `NavSubItemGroup`  | Sub-items under a `NavCategoryItem`              |
+| `NavSubItem`       | A child item in a sub-group                      |
+| `NavDivider`       | Horizontal divider between items                 |
+| `NavSectionHeader` | Non-interactive section label                    |
+
+## Nav Props
+
+| v8 `INavProps`       | v9 `NavProps`              | Notes                     |
+| -------------------- | -------------------------- | ------------------------- |
+| `groups`             | JSX children               |                           |
+| `selectedKey`        | `selectedValue`            |                           |
+| `initialSelectedKey` | `defaultSelectedValue`     |                           |
+| `onLinkClick`        | `onNavItemSelect`          | `(_, data) => data.value` |
+| `onLinkExpandClick`  | `onNavCategoryItemToggle`  |                           |
+| `isOnTop`            | Use `NavDrawer`            |                           |
+| `styles`             | `className` + `makeStyles` |                           |
+| `theme`              | —                          | Use `FluentProvider`      |
+
+## Before / After
+
+```tsx
+// v8 — data-driven groups
+import { Nav } from '@fluentui/react';
+
+<Nav
+  selectedKey="home"
+  onLinkClick={(_, item) => navigate(item?.url)}
+  groups={[
+    {
+      links: [
+        { name: 'Home', url: '/', key: 'home', iconProps: { iconName: 'Home' } },
+        {
+          name: 'Settings',
+          url: '',
+          key: 'settings',
+          links: [{ name: 'Profile', url: '/profile', key: 'profile' }],
+        },
+      ],
+    },
+  ]}
+/>;
+
+// v9 — declarative JSX
+import { Nav, NavItem, NavCategory, NavCategoryItem, NavSubItemGroup, NavSubItem } from '@fluentui/react-components';
+import { HomeRegular, SettingsRegular } from '@fluentui/react-icons';
+
+<Nav selectedValue="home" onNavItemSelect={(_, data) => navigate(data.value as string)}>
+  <NavItem icon={<HomeRegular />} value="home" href="/">
+    Home
+  </NavItem>
+  <NavCategory value="settings">
+    <NavCategoryItem icon={<SettingsRegular />}>Settings</NavCategoryItem>
+    <NavSubItemGroup>
+      <NavSubItem value="profile" href="/profile">
+        Profile
+      </NavSubItem>
+    </NavSubItemGroup>
+  </NavCategory>
+</Nav>;
+```
+
+## Accessibility Notes
+
+- Add `href` to all `NavItem`s that change the URL — even when using JS routing
+- Ensure hamburger icon buttons have an accessible name
+- Don't combine expand/collapse with link navigation on the same item
diff --git a/skills/fluentui-migrate-v8-to-v9/references/overflow.md b/skills/fluentui-migrate-v8-to-v9/references/overflow.md
new file mode 100644
index 00000000000000..8b6313fdccfb45
--- /dev/null
+++ b/skills/fluentui-migrate-v8-to-v9/references/overflow.md
@@ -0,0 +1,117 @@
+# OverflowSet → Overflow Migration
+
+v8 `OverflowSet` used render callbacks (`onRenderItem`, `onRenderOverflowButton`) with static `items` / `overflowItems` arrays. v9 `Overflow` is hook-based: every child wraps itself in `<OverflowItem>` and a set of utility hooks drives visibility and menu state.
+
+## Architecture Shift
+
+| v8 `OverflowSet`           | v9 `Overflow` + `OverflowItem`                |
+| -------------------------- | --------------------------------------------- |
+| `items` array prop         | `<OverflowItem>` children                     |
+| `overflowItems` array prop | Detected automatically by the overflow engine |
+| `onRenderItem` callback    | Each item renders itself                      |
+| `onRenderOverflowButton`   | `useOverflowMenu` hook + `<Menu>` you compose |
+| No priority concept        | `priority` prop on `<OverflowItem>`           |
+
+## Key v9 Hooks
+
+| Hook                       | Returns                                                        |
+| -------------------------- | -------------------------------------------------------------- |
+| `useOverflowMenu`          | `ref` to register the overflow button; `isOverflowing` boolean |
+| `useIsOverflowItemVisible` | Whether a specific item is currently visible                   |
+| `useOverflowCount`         | Number of currently hidden items                               |
+| `useOverflowGroupVisible`  | Visibility of an overflow group                                |
+
+## Prop Mapping — OverflowSet
+
+| v8                       | v9 equivalent                                 | Notes |
+| ------------------------ | --------------------------------------------- | ----- |
+| `items`                  | `<OverflowItem id="...">` children            |       |
+| `overflowItems`          | Auto-detected by `Overflow`                   |       |
+| `onRenderItem`           | Item renders itself                           |       |
+| `onRenderOverflowButton` | `useOverflowMenu` + your `<Menu>` composition |       |
+| `vertical`               | `overflowAxis="vertical"` on `<Overflow>`     |       |
+| `overflowMenuProps`      | Pass to your `<Menu>` directly                |       |
+| `styles`                 | `className` + `makeStyles`                    |       |
+| `role`                   | `role` on the container element               |       |
+
+## OverflowItem Props
+
+| Prop       | Type      | Notes                                                                    |
+| ---------- | --------- | ------------------------------------------------------------------------ |
+| `id`       | `string`  | Required; unique identifier used by the overflow engine                  |
+| `priority` | `number`  | Higher = overflows later (mutually exclusive with `pinned`)              |
+| `pinned`   | `boolean` | Never overflows (mutually exclusive with `priority`)                     |
+| `groupId`  | `string`  | Assign to a group; watch group visibility with `useOverflowGroupVisible` |
+
+## Before / After
+
+```tsx
+// v8 — render callbacks
+import { OverflowSet } from '@fluentui/react';
+
+<OverflowSet
+  items={[
+    { key: 'item1', name: 'Item 1', onClick: () => {} },
+    { key: 'item2', name: 'Item 2', onClick: () => {} },
+  ]}
+  overflowItems={[{ key: 'overflow1', name: 'More', onClick: () => {} }]}
+  onRenderItem={item => <CommandBarButton text={item.name} onClick={item.onClick} />}
+  onRenderOverflowButton={items => <CommandBarButton menuProps={{ items }} text="..." />}
+/>;
+
+// v9 — hook-based composition
+import {
+  Overflow,
+  OverflowItem,
+  Button,
+  Menu,
+  MenuItem,
+  MenuList,
+  MenuPopover,
+  MenuTrigger,
+  useOverflowMenu,
+  useIsOverflowItemVisible,
+  makeStyles,
+  mergeClasses,
+} from '@fluentui/react-components';
+
+const itemIds = ['item1', 'item2', 'item3'];
+
+function OverflowMenuButton() {
+  const { ref, isOverflowing } = useOverflowMenu<HTMLButtonElement>();
+  if (!isOverflowing) return null;
+  return (
+    <Menu>
+      <MenuTrigger disableButtonEnhancement>
+        <Button ref={ref}>+ more</Button>
+      </MenuTrigger>
+      <MenuPopover>
+        <MenuList>
+          {itemIds.map(id => (
+            <OverflowMenuItem key={id} id={id} />
+          ))}
+        </MenuList>
+      </MenuPopover>
+    </Menu>
+  );
+}
+
+function OverflowMenuItem({ id }: { id: string }) {
+  const isVisible = useIsOverflowItemVisible(id);
+  if (isVisible) return null;
+  return <MenuItem>{id}</MenuItem>;
+}
+
+<Overflow>
+  <div style={{ display: 'flex', overflow: 'hidden' }}>
+    {itemIds.map(id => (
+      <OverflowItem key={id} id={id}>
+        <Button>{id}</Button>
+      </OverflowItem>
+    ))}
+    <OverflowMenuButton />
+  </div>
+</Overflow>;
+```
+
+> **Note**: `OverflowItem` children must use `React.forwardRef` if they are custom components.
diff --git a/skills/fluentui-migrate-v8-to-v9/references/persona.md b/skills/fluentui-migrate-v8-to-v9/references/persona.md
new file mode 100644
index 00000000000000..93bc76fa3669e4
--- /dev/null
+++ b/skills/fluentui-migrate-v8-to-v9/references/persona.md
@@ -0,0 +1,81 @@
+# Persona Migration
+
+v9 `Persona` uses a slot-based API. Text lines are slots (`primaryText`, `secondaryText`, etc.); avatar and presence are composed via `Avatar` and `PresenceBadge` slots rather than flat image/initials props.
+
+## Prop Mapping
+
+| v8 `IPersonaProps`     | v9 `PersonaProps`                         | Notes                                                                 |
+| ---------------------- | ----------------------------------------- | --------------------------------------------------------------------- |
+| `text` / `primaryText` | `name` (or `primaryText` slot)            | `name` is the default for `primaryText`; use slots for custom content |
+| `secondaryText`        | `secondaryText` slot                      |                                                                       |
+| `tertiaryText`         | `tertiaryText` slot                       |                                                                       |
+| `optionalText`         | `quaternaryText` slot                     | Renamed                                                               |
+| `imageUrl`             | `avatar={{ image: { src: '...' } }}`      | Passed as shorthand to the `avatar` slot                              |
+| `imageInitials`        | `avatar={{ initials: '...' }}`            |                                                                       |
+| `initialsColor`        | `avatar={{ color: '...' }}`               | v9 uses token-based colors or `"colorful"`                            |
+| `presence`             | `presence={{ status: '...' }}`            | `PersonaPresence` enum → string status (see table below)              |
+| `presenceTitle`        | `presence={{ title: '...' }}`             |                                                                       |
+| `size`                 | `size`                                    | Different enum — see size table below                                 |
+| `hidePersonaDetails`   | `textPosition="below"` or omit text slots | Use slot composition                                                  |
+| `showSecondaryText`    | Include `secondaryText` slot              | v9 shows it unconditionally when provided                             |
+| `coinSize`             | `size` on the `avatar` slot               | Use token sizes                                                       |
+| `styles`               | `className` + `makeStyles`                |                                                                       |
+| `theme`                | —                                         | Use `FluentProvider`                                                  |
+| `componentRef`         | `ref`                                     |                                                                       |
+
+## Presence Status Mapping
+
+| v8 `PersonaPresence`      | v9 `status`          |
+| ------------------------- | -------------------- |
+| `PersonaPresence.online`  | `"available"`        |
+| `PersonaPresence.away`    | `"away"`             |
+| `PersonaPresence.busy`    | `"busy"`             |
+| `PersonaPresence.dnd`     | `"do-not-disturb"`   |
+| `PersonaPresence.blocked` | `"blocked"`          |
+| `PersonaPresence.offline` | `"offline"`          |
+| `PersonaPresence.none`    | omit `presence` prop |
+
+## Size Mapping
+
+| v8 `PersonaSize`      | v9 `size`            |
+| --------------------- | -------------------- |
+| `PersonaSize.size8`   | `"extra-small"`      |
+| `PersonaSize.size24`  | `"extra-small"`      |
+| `PersonaSize.size32`  | `"small"`            |
+| `PersonaSize.size40`  | `"medium"` (default) |
+| `PersonaSize.size48`  | `"medium"`           |
+| `PersonaSize.size56`  | `"large"`            |
+| `PersonaSize.size72`  | `"extra-large"`      |
+| `PersonaSize.size100` | `"huge"`             |
+| `PersonaSize.size120` | `"huge"`             |
+
+## Before / After
+
+```tsx
+// v8
+import { Persona, PersonaSize, PersonaPresence } from '@fluentui/react';
+<Persona
+  text="Alice Northwood"
+  secondaryText="Software Engineer"
+  imageUrl={avatarSrc}
+  size={PersonaSize.size48}
+  presence={PersonaPresence.online}
+/>;
+
+// v9
+import { Persona } from '@fluentui/react-components';
+<Persona
+  name="Alice Northwood"
+  secondaryText="Software Engineer"
+  avatar={{ image: { src: avatarSrc } }}
+  size="medium"
+  presence={{ status: 'available' }}
+/>;
+```
+
+## Text Position
+
+```tsx
+// v9 — text below avatar (was hidePersonaDetails=false + layout)
+<Persona name="Alice Northwood" secondaryText="Engineer" textPosition="below" size="large" />
+```
diff --git a/skills/fluentui-migrate-v8-to-v9/references/rating.md b/skills/fluentui-migrate-v8-to-v9/references/rating.md
new file mode 100644
index 00000000000000..2a4e7f62c706ba
--- /dev/null
+++ b/skills/fluentui-migrate-v8-to-v9/references/rating.md
@@ -0,0 +1,88 @@
+# Rating Migration
+
+v9 `Rating` has a cleaner API. The main differences are the `value` prop rename, a new `RatingDisplay` component for read-only display, and half-star support via `step`.
+
+## Key Differences
+
+- `rating` prop renamed to `value`
+- Read-only display → use `RatingDisplay` instead of `readOnly` prop
+- `icon` (string icon name) → `iconFilled` / `iconOutline` (React element types from `@fluentui/react-icons`)
+- `onChange` signature changed
+- New `step={0.5}` for half-star ratings
+- New `color` prop: `"neutral"` (default) \| `"brand"` \| `"marigold"`
+- `ariaLabelFormat` → `itemLabel` (function)
+
+## Prop Mapping
+
+| v8 `IRatingProps`        | v9 `RatingProps`             | Notes                                                       |
+| ------------------------ | ---------------------------- | ----------------------------------------------------------- |
+| `rating`                 | `value`                      | Renamed                                                     |
+| `max`                    | `max`                        | Default 5                                                   |
+| `min` / `allowZeroStars` | —                            | Use `value={0}` as initial value                            |
+| `readOnly`               | Use `<RatingDisplay>`        | Separate component for display-only                         |
+| `icon`                   | `iconFilled` / `iconOutline` | Pass a React component type (not an icon name string)       |
+| `size`                   | `size`                       | Values changed: see size table below                        |
+| `onChange`               | `onChange`                   | Type: `EventHandler<RatingOnChangeEventData>`; `data.value` |
+| `ariaLabelFormat`        | `itemLabel`                  | Now a function: `(rating) => string`                        |
+| `styles`                 | `className`                  | Use `makeStyles`                                            |
+| `theme`                  | —                            | Use `FluentProvider`                                        |
+
+## Size Mapping
+
+| v8 `RatingSize`    | v9 `size`                    |
+| ------------------ | ---------------------------- |
+| `RatingSize.Small` | `"small"`                    |
+| `RatingSize.Large` | `"large"`                    |
+| (default)          | `"extra-large"` (v9 default) |
+
+## Before / After
+
+```tsx
+// v8
+import { Rating, RatingSize } from '@fluentui/react';
+<Rating
+  rating={value}
+  max={5}
+  size={RatingSize.Large}
+  onChange={(_, v) => setValue(v ?? 0)}
+  ariaLabelFormat="{0} of {1} stars"
+/>;
+
+// v9
+import { Rating } from '@fluentui/react-components';
+<Rating
+  value={value}
+  max={5}
+  size="large"
+  onChange={(_, data) => setValue(data.value)}
+  itemLabel={v => `${v} of 5 stars`}
+/>;
+```
+
+## Read-Only Display
+
+```tsx
+// v8
+<Rating rating={3.5} readOnly />;
+
+// v9 — use RatingDisplay for read-only
+import { RatingDisplay } from '@fluentui/react-components';
+<RatingDisplay value={3.5} />;
+// RatingDisplay also shows a count:
+<RatingDisplay value={4.2} count={128} />;
+```
+
+## Half Stars
+
+```tsx
+// v9 — half-star precision
+<Rating value={3.5} step={0.5} />
+```
+
+## Custom Icon
+
+```tsx
+// v9
+import { HeartFilled, HeartRegular } from '@fluentui/react-icons';
+<Rating iconFilled={HeartFilled} iconOutline={HeartRegular} />;
+```
diff --git a/skills/fluentui-migrate-v8-to-v9/references/searchbox.md b/skills/fluentui-migrate-v8-to-v9/references/searchbox.md
new file mode 100644
index 00000000000000..90fede59e43020
--- /dev/null
+++ b/skills/fluentui-migrate-v8-to-v9/references/searchbox.md
@@ -0,0 +1,68 @@
+# SearchBox Migration
+
+v9 `SearchBox` is in `@fluentui/react-components`. The API is similar to v9 `Input` with a built-in dismiss button and search icon. Wrap in `<Field>` for labels.
+
+## Prop Mapping
+
+| v8 `ISearchBoxProps` | v9 `SearchBoxProps`        | Notes                                                                                        |
+| -------------------- | -------------------------- | -------------------------------------------------------------------------------------------- |
+| `value`              | `value`                    |                                                                                              |
+| `defaultValue`       | `defaultValue`             |                                                                                              |
+| `placeholder`        | `placeholder`              |                                                                                              |
+| `onChange`           | `onChange`                 | Type changed: `(_, data: InputOnChangeData) => void`; dismiss fires with `data.value === ''` |
+| `onSearch`           | —                          | Use native `onKeyDown` checking `event.key === 'Enter'`                                      |
+| `onClear`            | `onChange` with `''`       | Dismiss button calls `onChange` with empty string                                            |
+| `iconProps`          | `contentBefore` slot       | Pass `<SearchRegular />` or custom icon                                                      |
+| `underlined`         | `appearance="underline"`   |                                                                                              |
+| `disableAnimation`   | —                          | Not supported                                                                                |
+| `disabled`           | `disabled`                 |                                                                                              |
+| `className`          | `className`                | Applies to the outer wrapper                                                                 |
+| `styles`             | `className` + `makeStyles` |                                                                                              |
+| `theme`              | —                          | Use `FluentProvider`                                                                         |
+| `componentRef`       | `ref`                      |                                                                                              |
+
+## Appearance Values
+
+| v8                  | v9                    |
+| ------------------- | --------------------- |
+| Default             | `"outline"` (default) |
+| `underlined={true}` | `"underline"`         |
+| —                   | `"filled-darker"`     |
+| —                   | `"filled-lighter"`    |
+
+## Before / After
+
+```tsx
+// v8
+import { SearchBox } from '@fluentui/react';
+<SearchBox
+  placeholder="Search"
+  value={query}
+  onChange={(_, v) => setQuery(v ?? '')}
+  onSearch={v => doSearch(v)}
+  onClear={() => setQuery('')}
+/>;
+
+// v9
+import { SearchBox } from '@fluentui/react-components';
+<SearchBox
+  placeholder="Search"
+  value={query}
+  onChange={(_, data) => setQuery(data.value)}
+  onKeyDown={e => e.key === 'Enter' && doSearch(query)}
+/>;
+```
+
+## With Field (label + validation)
+
+```tsx
+import { Field, SearchBox } from '@fluentui/react-components';
+<Field label="Search products">
+  <SearchBox placeholder="Type to search..." />
+</Field>;
+```
+
+## Accessibility Notes
+
+- For a top-level site search area, wrap `SearchBox` in a `<div role="search">` element
+- Use `underline` or `outline` appearance when the surrounding background has low contrast
diff --git a/skills/fluentui-migrate-v8-to-v9/references/separator.md b/skills/fluentui-migrate-v8-to-v9/references/separator.md
new file mode 100644
index 00000000000000..f15cc964afe808
--- /dev/null
+++ b/skills/fluentui-migrate-v8-to-v9/references/separator.md
@@ -0,0 +1,44 @@
+# Separator → Divider Migration
+
+This is a straightforward rename. `Separator` (v8) → `Divider` (v9). The core props carry over unchanged; custom styles move to `makeStyles` + `className`.
+
+## Prop Mapping
+
+| v8             | v9             | Notes                                                     |
+| -------------- | -------------- | --------------------------------------------------------- |
+| `alignContent` | `alignContent` | Unchanged                                                 |
+| `children`     | `children`     | Content centered in the line                              |
+| `vertical`     | `vertical`     | Unchanged                                                 |
+| `styles`       | `className`    | Use `makeStyles`                                          |
+| `theme`        | —              | Use `FluentProvider`                                      |
+| —              | `appearance`   | New: `"default"` \| `"subtle"` \| `"brand"` \| `"strong"` |
+| —              | `inset`        | New: adds padding on both ends                            |
+
+## Before / After
+
+```tsx
+// v8
+import { Separator } from '@fluentui/react';
+<Separator vertical alignContent="end">
+  Label
+</Separator>;
+
+// v9
+import { Divider } from '@fluentui/react-components';
+<Divider vertical alignContent="end">
+  Label
+</Divider>;
+```
+
+Custom styles:
+
+```tsx
+// v8
+<Separator styles={{ root: { color: 'red' } }} />;
+
+// v9
+import { makeStyles, Divider } from '@fluentui/react-components';
+const useStyles = makeStyles({ divider: { color: 'red' } });
+const s = useStyles();
+<Divider className={s.divider} />;
+```
diff --git a/skills/fluentui-migrate-v8-to-v9/references/skeleton.md b/skills/fluentui-migrate-v8-to-v9/references/skeleton.md
new file mode 100644
index 00000000000000..63728fa5dc9b4d
--- /dev/null
+++ b/skills/fluentui-migrate-v8-to-v9/references/skeleton.md
@@ -0,0 +1,76 @@
+# Shimmer → Skeleton Migration
+
+`Shimmer` (v8) → `Skeleton` + `SkeletonItem` (v9). The data-loading gate (`isDataLoaded`) is removed — Skeleton is purely a visual placeholder; show/hide it with your own conditional rendering.
+
+## Key Differences
+
+- No `isDataLoaded` toggle — conditionally render `<Skeleton>` vs real content yourself
+- `shimmerElements` array (Line, Circle, Gap) → compose `<SkeletonItem>` children with CSS layout
+- `customElementsGroup` → use `<SkeletonItem>` children directly
+- `width` prop on `<Shimmer>` is equivalent to setting `width` on `<SkeletonItem>` (or use `className`)
+
+## Prop Mapping — Shimmer → Skeleton / SkeletonItem
+
+| v8 `IShimmerProps`    | v9 equivalent                                | Notes                                                |
+| --------------------- | -------------------------------------------- | ---------------------------------------------------- |
+| `isDataLoaded`        | —                                            | Conditionally render `<Skeleton>` vs real content    |
+| `shimmerElements`     | `<SkeletonItem>` children                    | Build layout with JSX + CSS instead of element array |
+| `customElementsGroup` | `<SkeletonItem>` children                    |                                                      |
+| `width`               | `width` on `<SkeletonItem>` (or `className`) | **Deprecated** in v9 — use `className`               |
+| `styles`              | `className` + `makeStyles`                   |                                                      |
+| `theme`               | —                                            | Use `FluentProvider`                                 |
+| `shimmerColors`       | —                                            | Use `className` + token overrides                    |
+
+## SkeletonItem Props
+
+| Prop         | Values                                                                                                         | Notes                                 |
+| ------------ | -------------------------------------------------------------------------------------------------------------- | ------------------------------------- |
+| `shape`      | `"rectangle"` (default) \| `"circle"`                                                                          |                                       |
+| `size`       | `16` \| `20` \| `24` \| `28` \| `32` \| `36` \| `40` \| `48` \| `56` \| `64` \| `72` \| `96` \| `120` \| `128` | Pixel height                          |
+| `animation`  | `"wave"` (default) \| `"pulse"`                                                                                | On `<Skeleton>`, applies to all items |
+| `appearance` | `"opaque"` (default) \| `"translucent"`                                                                        | On `<Skeleton>`                       |
+
+## Before / After
+
+```tsx
+// v8 — data-gated with isDataLoaded
+import { Shimmer, ShimmerElementType } from '@fluentui/react';
+
+<Shimmer
+  isDataLoaded={isLoaded}
+  shimmerElements={[
+    { type: ShimmerElementType.circle, height: 40 },
+    { type: ShimmerElementType.gap, width: 8 },
+    { type: ShimmerElementType.line },
+  ]}
+>
+  <MyContent />
+</Shimmer>;
+
+// v9 — conditional render
+import { Skeleton, SkeletonItem, makeStyles } from '@fluentui/react-components';
+
+const useStyles = makeStyles({
+  row: { display: 'flex', alignItems: 'center', gap: '8px' },
+});
+
+function LoadableContent({ isLoaded }: { isLoaded: boolean }) {
+  const s = useStyles();
+  if (!isLoaded) {
+    return (
+      <Skeleton aria-label="Loading content">
+        <div className={s.row}>
+          <SkeletonItem shape="circle" size={40} />
+          <SkeletonItem style={{ flex: 1 }} />
+        </div>
+      </Skeleton>
+    );
+  }
+  return <MyContent />;
+}
+```
+
+## Accessibility
+
+- Add `aria-label` to `<Skeleton>` (single loader) or `aria-busy="true"` to the container (multiple loaders)
+- Announce once when all content loads — don't add `aria-live` to individual `<Skeleton>` items
diff --git a/skills/fluentui-migrate-v8-to-v9/references/swatchpicker.md b/skills/fluentui-migrate-v8-to-v9/references/swatchpicker.md
new file mode 100644
index 00000000000000..1533ba052590bd
--- /dev/null
+++ b/skills/fluentui-migrate-v8-to-v9/references/swatchpicker.md
@@ -0,0 +1,101 @@
+# SwatchColorPicker → SwatchPicker Migration
+
+v8 `SwatchColorPicker` used a `colorCells` array prop. v9 `SwatchPicker` uses declarative `<ColorSwatch>` / `<ImageSwatch>` children and supports image swatches and empty swatch slots out of the box.
+
+## Key Differences
+
+- `colorCells` array → `<ColorSwatch>` children
+- `selectedId` → `selectedValue` (uses the `value` prop on each swatch)
+- `onChange` signature changed
+- Grid layout uses `<SwatchPickerRow>` or the `renderSwatchPickerGrid` utility
+- New swatch types: `ImageSwatch` (image-based), `EmptySwatch` (placeholder)
+
+## Component Tree
+
+```tsx
+import { SwatchPicker, SwatchPickerRow, ColorSwatch, ImageSwatch, EmptySwatch } from '@fluentui/react-components';
+```
+
+| v9 Component      | Purpose                               |
+| ----------------- | ------------------------------------- |
+| `SwatchPicker`    | Container; handles selection state    |
+| `SwatchPickerRow` | Optional row wrapper for grid layout  |
+| `ColorSwatch`     | Single color swatch                   |
+| `ImageSwatch`     | Image-based swatch (no v8 equivalent) |
+| `EmptySwatch`     | Transparent/no-color placeholder      |
+
+## Prop Mapping — SwatchColorPicker → SwatchPicker
+
+| v8                         | v9                                 | Notes                                                        |
+| -------------------------- | ---------------------------------- | ------------------------------------------------------------ |
+| `colorCells`               | `<ColorSwatch>` children           | Render one `<ColorSwatch value={id} color={color}>` per cell |
+| `selectedId`               | `selectedValue`                    | Must match the `value` prop on a `<ColorSwatch>`             |
+| `defaultSelectedId`        | `defaultSelectedValue`             |                                                              |
+| `onChange`                 | `onSelectionChange`                | `(ev, data: { selectedValue, selectedSwatch }) => void`      |
+| `columnCount`              | `<SwatchPickerRow>` children count | Layout is CSS-driven; use rows and CSS grid                  |
+| `cellHeight` / `cellWidth` | `size` on swatch                   | `"extra-small"` \| `"small"` \| `"medium"` \| `"large"`      |
+| `cellShape`                | `shape`                            | `"circular"` \| `"rounded"` \| `"square"`                    |
+| `disabled`                 | `disabled`                         |                                                              |
+| `isControlled`             | Use `selectedValue`                | Pass `selectedValue` for controlled mode                     |
+| `styles`                   | `className`                        | Use `makeStyles`                                             |
+| `theme`                    | —                                  | Use `FluentProvider`                                         |
+
+## Before / After
+
+```tsx
+// v8 — data-driven array
+import { SwatchColorPicker } from '@fluentui/react';
+
+<SwatchColorPicker
+  columnCount={4}
+  selectedId={selected}
+  onChange={(_, item) => setSelected(item?.id ?? '')}
+  colorCells={[
+    { id: 'red', label: 'Red', color: '#d13438' },
+    { id: 'blue', label: 'Blue', color: '#0078d4' },
+    { id: 'green', label: 'Green', color: '#107c10' },
+    { id: 'yellow', label: 'Yellow', color: '#fce100' },
+  ]}
+/>;
+
+// v9 — declarative children
+import { SwatchPicker, SwatchPickerRow, ColorSwatch } from '@fluentui/react-components';
+
+<SwatchPicker selectedValue={selected} onSelectionChange={(_, data) => setSelected(data.selectedValue)}>
+  <SwatchPickerRow>
+    <ColorSwatch value="red" color="#d13438" aria-label="Red" />
+    <ColorSwatch value="blue" color="#0078d4" aria-label="Blue" />
+    <ColorSwatch value="green" color="#107c10" aria-label="Green" />
+    <ColorSwatch value="yellow" color="#fce100" aria-label="Yellow" />
+  </SwatchPickerRow>
+</SwatchPicker>;
+```
+
+## Grid Layout Utility
+
+For programmatic grid generation use `renderSwatchPickerGrid`:
+
+```tsx
+import { SwatchPicker, renderSwatchPickerGrid, ColorSwatch } from '@fluentui/react-components';
+
+const colors = [
+  { value: 'red', color: '#d13438', 'aria-label': 'Red' },
+  { value: 'blue', color: '#0078d4', 'aria-label': 'Blue' },
+];
+
+<SwatchPicker selectedValue={selected} onSelectionChange={(_, data) => setSelected(data.selectedValue)}>
+  {renderSwatchPickerGrid({ items: colors, columnCount: 4 })}
+</SwatchPicker>;
+```
+
+## Image Swatches
+
+```tsx
+<SwatchPicker>
+  <SwatchPickerRow>
+    <ImageSwatch value="pattern1" src="/pattern1.png" aria-label="Pattern 1" />
+    <ImageSwatch value="pattern2" src="/pattern2.png" aria-label="Pattern 2" />
+    <EmptySwatch aria-label="No pattern" />
+  </SwatchPickerRow>
+</SwatchPicker>
+```
diff --git a/skills/fluentui-migrate-v8-to-v9/references/switch.md b/skills/fluentui-migrate-v8-to-v9/references/switch.md
new file mode 100644
index 00000000000000..abe96120842a66
--- /dev/null
+++ b/skills/fluentui-migrate-v8-to-v9/references/switch.md
@@ -0,0 +1,49 @@
+# Toggle → Switch Migration
+
+`Toggle` (v8) → `Switch` (v9). The name change is the biggest difference; the core API is similar.
+
+## Key Differences
+
+- `onText` / `offText` removed — use a dynamic `label` instead
+- `onChange` signature changed: `(ev, checked?) => void` → `(ev: ChangeEvent<HTMLInputElement>, data: SwitchOnChangeData) => void`
+- `inlineLabel` removed — use `labelPosition="before"` or `"after"` (default)
+- `label` is now a **slot** (accepts `string` or shorthand object)
+
+## Prop Mapping
+
+| v8 `IToggleProps` | v9 `SwitchProps` | Notes                                                      |
+| ----------------- | ---------------- | ---------------------------------------------------------- |
+| `checked`         | `checked`        |                                                            |
+| `defaultChecked`  | `defaultChecked` |                                                            |
+| `label`           | `label` slot     | Now a slot — accepts string or shorthand                   |
+| `onText`          | —                | Removed; use dynamic `label` or text next to the component |
+| `offText`         | —                | Removed; use dynamic `label`                               |
+| `inlineLabel`     | `labelPosition`  | `true` → `"before"`, default is `"after"`                  |
+| `onChange`        | `onChange`       | Type changed: `(ev, data: { checked: boolean }) => void`   |
+| `disabled`        | `disabled`       |                                                            |
+| `componentRef`    | `ref`            |                                                            |
+| `styles`          | `className`      | Use `makeStyles`                                           |
+| `theme`           | —                | Use `FluentProvider`                                       |
+
+## Before / After
+
+```tsx
+// v8
+import { Toggle } from '@fluentui/react';
+const [on, setOn] = React.useState(false);
+
+<Toggle label="Wi-Fi" onText="On" offText="Off" checked={on} onChange={(_, checked) => setOn(checked ?? false)} />;
+
+// v9
+import { Switch } from '@fluentui/react-components';
+const [on, setOn] = React.useState(false);
+
+<Switch label={on ? 'Wi-Fi On' : 'Wi-Fi Off'} checked={on} onChange={(_, data) => setOn(data.checked)} />;
+```
+
+## Label Position
+
+```tsx
+// v9 — label before the thumb (equivalent to v8 inlineLabel)
+<Switch label="Dark mode" labelPosition="before" checked={checked} onChange={...} />;
+```
diff --git a/skills/fluentui-migrate-v8-to-v9/references/tagpicker.md b/skills/fluentui-migrate-v8-to-v9/references/tagpicker.md
new file mode 100644
index 00000000000000..7b0f8cf590bd67
--- /dev/null
+++ b/skills/fluentui-migrate-v8-to-v9/references/tagpicker.md
@@ -0,0 +1,107 @@
+# TagPicker / PeoplePicker Migration
+
+v8 `TagPicker` and `PeoplePicker` used async `onResolveSuggestions` callbacks with data-driven items. v9 `TagPicker` is a composable component with declarative `<TagPickerOption>` children.
+
+## Component Structure
+
+### v8
+
+```
+<TagPicker>           — monolithic, async-suggestion-driven
+```
+
+### v9
+
+```
+<TagPicker>
+  <TagPickerControl>
+    <TagPickerGroup>  — renders the selected Tag chips
+      <Tag />         — one per selected item
+    </TagPickerGroup>
+    <TagPickerInput>  — the text input
+  </TagPickerControl>
+  <TagPickerList>
+    <TagPickerOption> — one per option (like <Option> in Combobox/Dropdown)
+  </TagPickerList>
+</TagPicker>
+```
+
+## Migration Strategy
+
+v8 `onResolveSuggestions` (async) → v9: filter options yourself in state/memo and render only matching `<TagPickerOption>` children.
+
+```tsx
+// v8
+<TagPicker
+  onResolveSuggestions={filter => allPeople.filter(p => p.text.includes(filter))}
+  selectedItems={selected}
+  onChange={items => setSelected(items ?? [])}
+/>;
+
+// v9
+const [query, setQuery] = React.useState('');
+const [selected, setSelected] = React.useState<string[]>([]);
+
+const visibleOptions = allOptions.filter(o => !selected.includes(o) && o.toLowerCase().includes(query.toLowerCase()));
+
+<TagPicker
+  selectedOptions={selected}
+  onOptionSelect={(_, data) => {
+    setSelected(data.selectedOptions);
+    setQuery('');
+  }}
+>
+  <TagPickerControl>
+    <TagPickerGroup>
+      {selected.map(opt => (
+        <Tag key={opt} shape="rounded" dismissible dismissIcon={{ 'aria-label': 'remove' }} value={opt}>
+          {opt}
+        </Tag>
+      ))}
+    </TagPickerGroup>
+    <TagPickerInput aria-label="Select people" value={query} onChange={e => setQuery(e.target.value)} />
+  </TagPickerControl>
+  <TagPickerList>
+    {visibleOptions.map(opt => (
+      <TagPickerOption key={opt} value={opt}>
+        {opt}
+      </TagPickerOption>
+    ))}
+  </TagPickerList>
+</TagPicker>;
+```
+
+## TagPicker Prop Mapping
+
+| v8 `IBasePickerProps`    | v9 `TagPickerProps`                                     | Notes                                              |
+| ------------------------ | ------------------------------------------------------- | -------------------------------------------------- |
+| `onResolveSuggestions`   | Filter options in render                                | Async lookup → filter `<TagPickerOption>` children |
+| `selectedItems`          | `selectedOptions`                                       | `string[]` of option values                        |
+| `onChange`               | `onOptionSelect`                                        | `(_, data) => data.selectedOptions`                |
+| `inputProps`             | Props on `<TagPickerInput>`                             |                                                    |
+| `itemLimit`              | Check `data.selectedOptions.length` in `onOptionSelect` |                                                    |
+| `getTextFromItem`        | `value` prop on `<TagPickerOption>`                     |                                                    |
+| `pickerSuggestionsProps` | Compose your own `<TagPickerList>` content              |                                                    |
+| `onEmptyInputFocus`      | Show all options when `query === ''` in your filter     |                                                    |
+| `disabled`               | `disabled`                                              |                                                    |
+| `styles`                 | `className` on sub-components                           |                                                    |
+| `theme`                  | —                                                       | Use `FluentProvider`                               |
+
+## TagPicker Props (v9)
+
+| Prop                     | Notes                                                                   |
+| ------------------------ | ----------------------------------------------------------------------- |
+| `open` / `defaultOpen`   | Controlled / uncontrolled dropdown visibility                           |
+| `selectedOptions`        | Controlled selected values (`string[]`)                                 |
+| `defaultSelectedOptions` | Uncontrolled initial selection                                          |
+| `onOptionSelect`         | `EventHandler<TagPickerOnOptionSelectData>`                             |
+| `onOpenChange`           | `EventHandler<TagPickerOnOpenChangeData>`                               |
+| `appearance`             | `"outline"` \| `"underline"` \| `"filled-darker"` \| `"filled-lighter"` |
+| `size`                   | `"medium"` \| `"large"` \| `"extra-large"`                              |
+| `inline`                 | Render popover inline in DOM order (not on `document.body`)             |
+
+## Accessibility Notes
+
+- Add `aria-label` to `<TagPickerInput>` — screen readers need an accessible name
+- Communicate to users that Backspace removes the last tag when input is focused
+- Known VoiceOver/Safari bug: dropdown items not navigable on iOS (same issue as `Combobox`)
diff --git a/skills/fluentui-migrate-v8-to-v9/references/teachingpopover.md b/skills/fluentui-migrate-v8-to-v9/references/teachingpopover.md
new file mode 100644
index 00000000000000..74d73bb738d9e4
--- /dev/null
+++ b/skills/fluentui-migrate-v8-to-v9/references/teachingpopover.md
@@ -0,0 +1,117 @@
+# TeachingBubble / Coachmark → TeachingPopover Migration
+
+Both v8 components map to v9 `TeachingPopover`. It uses the same composable trigger/surface pattern as `Popover`.
+
+## Component Renames
+
+| v8               | v9                |
+| ---------------- | ----------------- |
+| `TeachingBubble` | `TeachingPopover` |
+| `Coachmark`      | `TeachingPopover` |
+
+## Component Structure (v9)
+
+```
+<TeachingPopover>
+  <TeachingPopoverTrigger>   — the element that opens it
+  <TeachingPopoverSurface>
+    <TeachingPopoverHeader>  — title + close button
+    <TeachingPopoverBody>    — content + optional media slot
+    <TeachingPopoverFooter>  — action buttons
+    <TeachingPopoverCarousel> — optional multi-step carousel
+```
+
+## Prop Mapping — TeachingBubble → TeachingPopover
+
+| v8 `ITeachingBubbleProps`      | v9 equivalent                                                | Notes                                                                                                          |
+| ------------------------------ | ------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------- |
+| `headline`                     | `<TeachingPopoverHeader>` children                           |                                                                                                                |
+| `primaryButtonProps`           | `<Button>` in `<TeachingPopoverFooter>`                      |                                                                                                                |
+| `secondaryButtonProps`         | `<Button>` in `<TeachingPopoverFooter>`                      |                                                                                                                |
+| `illustrationImage`            | `media` slot on `<TeachingPopoverBody>`                      |                                                                                                                |
+| `hasCloseButton`               | `<TeachingPopoverHeader>` includes a close button by default |                                                                                                                |
+| `footerContent`                | `<TeachingPopoverFooter>` children                           |                                                                                                                |
+| `onDismiss`                    | `onOpenChange` on `<TeachingPopover>`                        | `(_, data) => !data.open`                                                                                      |
+| `calloutProps.target`          | `<TeachingPopoverTrigger>` wrapping target                   | Or `positioning` prop on `<TeachingPopover>`                                                                   |
+| `calloutProps.directionalHint` | `positioning` on `<TeachingPopover>`                         | See [Positioning docs](https://react.fluentui.dev/?path=/docs/concepts-developer-positioning-components--docs) |
+| `styles`                       | `className` on sub-components                                |                                                                                                                |
+| `theme`                        | —                                                            | Use `FluentProvider`                                                                                           |
+
+## Before / After
+
+```tsx
+// v8 — TeachingBubble
+import { TeachingBubble } from '@fluentui/react';
+<TeachingBubble
+  target="#my-button"
+  headline="Discover this feature"
+  primaryButtonProps={{ text: 'Next', onClick: handleNext }}
+  secondaryButtonProps={{ text: 'Dismiss', onClick: handleDismiss }}
+  onDismiss={handleDismiss}
+>
+  Here's how to use this new feature.
+</TeachingBubble>;
+
+// v9 — TeachingPopover
+import {
+  TeachingPopover,
+  TeachingPopoverTrigger,
+  TeachingPopoverSurface,
+  TeachingPopoverHeader,
+  TeachingPopoverBody,
+  TeachingPopoverFooter,
+  Button,
+} from '@fluentui/react-components';
+
+<TeachingPopover>
+  <TeachingPopoverTrigger disableButtonEnhancement>
+    <Button id="my-button">Feature</Button>
+  </TeachingPopoverTrigger>
+  <TeachingPopoverSurface>
+    <TeachingPopoverHeader>Discover this feature</TeachingPopoverHeader>
+    <TeachingPopoverBody>Here's how to use this new feature.</TeachingPopoverBody>
+    <TeachingPopoverFooter>
+      <Button appearance="primary" onClick={handleNext}>
+        Next
+      </Button>
+      <Button onClick={handleDismiss}>Dismiss</Button>
+    </TeachingPopoverFooter>
+  </TeachingPopoverSurface>
+</TeachingPopover>;
+```
+
+## Multi-Step (Carousel)
+
+For multi-step teaching flows (replaces v8 paginated `TeachingBubble`):
+
+```tsx
+import {
+  TeachingPopover,
+  TeachingPopoverCarousel,
+  TeachingPopoverCarouselCard,
+  TeachingPopoverCarouselNav,
+  TeachingPopoverCarouselNavButton,
+  // ...other imports
+} from '@fluentui/react-components';
+
+<TeachingPopover>
+  <TeachingPopoverTrigger disableButtonEnhancement>
+    <Button>Start tour</Button>
+  </TeachingPopoverTrigger>
+  <TeachingPopoverSurface>
+    <TeachingPopoverCarousel onFinish={handleFinish}>
+      <TeachingPopoverCarouselCard value="step1">
+        <TeachingPopoverHeader>Step 1</TeachingPopoverHeader>
+        <TeachingPopoverBody>First step content.</TeachingPopoverBody>
+      </TeachingPopoverCarouselCard>
+      <TeachingPopoverCarouselCard value="step2">
+        <TeachingPopoverHeader>Step 2</TeachingPopoverHeader>
+        <TeachingPopoverBody>Second step content.</TeachingPopoverBody>
+      </TeachingPopoverCarouselCard>
+      <TeachingPopoverCarouselNav>
+        {value => <TeachingPopoverCarouselNavButton value={value} />}
+      </TeachingPopoverCarouselNav>
+    </TeachingPopoverCarousel>
+  </TeachingPopoverSurface>
+</TeachingPopover>;
+```
diff --git a/skills/fluentui-migrate-v8-to-v9/references/text.md b/skills/fluentui-migrate-v8-to-v9/references/text.md
new file mode 100644
index 00000000000000..61f78c784f8b88
--- /dev/null
+++ b/skills/fluentui-migrate-v8-to-v9/references/text.md
@@ -0,0 +1,82 @@
+# Text Migration
+
+v9 `Text` replaces the v8 `variant` prop with individual style props (`size`, `weight`, `font`, etc.) that map directly to design tokens.
+
+## Prop Mapping
+
+| v8 `ITextProps` | v9 `TextProps`    | Notes                                                                |
+| --------------- | ----------------- | -------------------------------------------------------------------- |
+| `variant`       | `size` + `weight` | See variant → size/weight table below                                |
+| `nowrap`        | `wrap={false}`    | Inverted boolean                                                     |
+| `block`         | `block`           | Same                                                                 |
+| `as`            | `as`              | v9 supports `"h1"`–`"h6"`, `"p"`, `"span"`, `"strong"`, `"em"`, etc. |
+| `styles`        | `className`       | Use `makeStyles`                                                     |
+| `theme`         | —                 | Use `FluentProvider`                                                 |
+
+## Variant → Size / Weight Mapping
+
+| v8 `variant`       | v9 `size` | v9 `weight` |
+| ------------------ | --------- | ----------- |
+| `tiny`             | `100`     | `regular`   |
+| `xSmall`           | `200`     | `regular`   |
+| `small`            | `200`     | `regular`   |
+| `smallPlus`        | `200`     | `semibold`  |
+| `medium` (default) | `300`     | `regular`   |
+| `mediumPlus`       | `300`     | `semibold`  |
+| `large`            | `400`     | `regular`   |
+| `xLarge`           | `500`     | `semibold`  |
+| `xLargePlus`       | `600`     | `semibold`  |
+| `xxLarge`          | `700`     | `semibold`  |
+| `xxLargePlus`      | `800`     | `semibold`  |
+| `superLarge`       | `900`     | `semibold`  |
+| `mega`             | `1000`    | `semibold`  |
+
+## New Props in v9
+
+| Prop            | Values                                             |
+| --------------- | -------------------------------------------------- |
+| `italic`        | `boolean`                                          |
+| `underline`     | `boolean`                                          |
+| `strikethrough` | `boolean`                                          |
+| `truncate`      | `boolean` — clips text with `…` on block elements  |
+| `align`         | `"start"` \| `"center"` \| `"end"` \| `"justify"`  |
+| `font`          | `"base"` (default) \| `"numeric"` \| `"monospace"` |
+
+## Presets
+
+v9 also exports semantic preset components that match design token names:
+
+```tsx
+import {
+  Body1, Body1Strong, Body2, Caption1, Caption2,
+  Display, LargeTitle, Subtitle1, Subtitle2, Title1, Title2, Title3,
+} from '@fluentui/react-components';
+
+<Title1>Page heading</Title1>
+<Body1>Body text</Body1>
+<Caption1>Small caption</Caption1>
+```
+
+Prefer presets over manual `size`/`weight` when matching the Fluent design system — they stay in sync as tokens evolve.
+
+## Before / After
+
+```tsx
+// v8
+import { Text } from '@fluentui/react';
+<Text variant="xxLarge" block nowrap>
+  Heading
+</Text>;
+
+// v9 — using size/weight
+import { Text } from '@fluentui/react-components';
+<Text size={700} weight="semibold" block wrap={false}>
+  Heading
+</Text>;
+
+// v9 — using preset (preferred)
+import { Title2 } from '@fluentui/react-components';
+<Title2 block wrap={false}>
+  Heading
+</Title2>;
+```
diff --git a/skills/fluentui-migrate-v8-to-v9/references/textarea.md b/skills/fluentui-migrate-v8-to-v9/references/textarea.md
new file mode 100644
index 00000000000000..7e240812f7ba90
--- /dev/null
+++ b/skills/fluentui-migrate-v8-to-v9/references/textarea.md
@@ -0,0 +1,55 @@
+# Textarea Migration
+
+v8's `TextField` with `multiline` → v9's `Textarea`. For single-line input see [input.md](input.md).
+
+Wrap `Textarea` in `<Field>` to get a label, validation message, and required indicator (v8's `label` / `errorMessage` / `required` props are removed from the control itself).
+
+## Prop Mapping
+
+| v8                                               | v9             | Notes                                                              |
+| ------------------------------------------------ | -------------- | ------------------------------------------------------------------ |
+| `ariaLabel`                                      | `aria-label`   | Native HTML                                                        |
+| `autoAdjustHeight`                               | —              | Not yet supported                                                  |
+| `autoComplete`                                   | `autoComplete` |                                                                    |
+| `borderless`                                     | `appearance`   | `"filled-lighter"` or `"filled-darker"`                            |
+| `className`                                      | `className`    | Applies to `<textarea>`; for the container use the `textarea` slot |
+| `componentRef`                                   | `ref`          |                                                                    |
+| `defaultValue`                                   | `defaultValue` | Mutually exclusive with `value`                                    |
+| `disabled`                                       | `disabled`     |                                                                    |
+| `label`                                          | —              | Use `<Field label="...">` wrapper                                  |
+| `errorMessage`                                   | —              | Use `<Field validationState="error" validationMessage="...">`      |
+| `required`                                       | —              | Use `<Field required>`                                             |
+| `description`                                    | —              | Use `<Field hint="...">`                                           |
+| `multiline`                                      | —              | `Textarea` is multiline by default                                 |
+| `onChange`                                       | `onChange`     | TypeScript types changed                                           |
+| `readOnly`                                       | `readOnly`     | Native HTML prop (lowercase in v9)                                 |
+| `resizable`                                      | `resize`       | `"none"` \| `"horizontal"` \| `"vertical"` \| `"both"`             |
+| `styles`                                         | `className`    |                                                                    |
+| `theme`                                          | —              | Use `FluentProvider`                                               |
+| `underlined`                                     | —              | Not supported                                                      |
+| `value`                                          | `value`        | Mutually exclusive with `defaultValue`                             |
+| `iconProps`                                      | —              | Not supported on Textarea                                          |
+| `prefix` / `suffix`                              | —              | Not supported on Textarea                                          |
+| `inputClassName`                                 | `className`    | The class applies to `<textarea>` directly                         |
+| `invalid` / `errorMessage` / `onGetErrorMessage` | —              | Use `<Field>` for validation                                       |
+
+## Before / After
+
+```tsx
+// v8
+import { TextField } from '@fluentui/react';
+<TextField
+  label="Comments"
+  multiline
+  required
+  errorMessage={error}
+  value={value}
+  onChange={(_, v) => setValue(v ?? '')}
+/>;
+
+// v9
+import { Field, Textarea } from '@fluentui/react-components';
+<Field label="Comments" required validationState={error ? 'error' : 'none'} validationMessage={error}>
+  <Textarea value={value} onChange={(_, data) => setValue(data.value)} resize="vertical" />
+</Field>;
+```
diff --git a/skills/fluentui-migrate-v8-to-v9/references/theme.md b/skills/fluentui-migrate-v8-to-v9/references/theme.md
index 7a636d1fd86453..5d09d3c259f0b4 100644
--- a/skills/fluentui-migrate-v8-to-v9/references/theme.md
+++ b/skills/fluentui-migrate-v8-to-v9/references/theme.md
@@ -25,8 +25,8 @@ v8 applies theme values as a JS object on React context. v9 applies theme values
 | Default light | `webLightTheme`          |
 | Default dark  | `webDarkTheme`           |
 | High contrast | `teamsHighContrastTheme` |
-| Teams light   | `teamsDarkTheme`         |
-| Teams dark    | `teamsLightTheme`        |
+| Teams light   | `teamsLightTheme`        |
+| Teams dark    | `teamsDarkTheme`         |
 
 All built-in themes are exported from `@fluentui/react-components`.
 
@@ -138,6 +138,31 @@ const s = useStyles();
 <div className={s.root} style={{ width: `${dynamicWidth}px` }} />;
 ```
 
+## Nested FluentProvider (Token Overrides)
+
+Multiple `FluentProvider` instances can be nested. The inner provider overrides only the tokens it specifies — useful for dark sections, compact density, or brand color changes within a subtree:
+
+```tsx
+import { FluentProvider, webLightTheme, webDarkTheme } from '@fluentui/react-components';
+
+// Dark sidebar inside a light-theme app
+<FluentProvider theme={webLightTheme}>
+  <main>{/* light theme */}</main>
+  <FluentProvider theme={webDarkTheme}>
+    <aside>{/* dark theme — only this subtree */}</aside>
+  </FluentProvider>
+</FluentProvider>;
+```
+
+To override individual tokens without switching the whole theme, pass a partial token object:
+
+```tsx
+// Override just the brand color in one subtree
+<FluentProvider theme={{ colorBrandBackground: '#e00000' }}>
+  <Button appearance="primary">Red brand button</Button>
+</FluentProvider>
+```
+
 ## Component `styles` Prop → className
 
 ```tsx
diff --git a/skills/fluentui-migrate-v8-to-v9/references/toolbar.md b/skills/fluentui-migrate-v8-to-v9/references/toolbar.md
index 4089b2cb211126..7a0730f38aa0fb 100644
--- a/skills/fluentui-migrate-v8-to-v9/references/toolbar.md
+++ b/skills/fluentui-migrate-v8-to-v9/references/toolbar.md
@@ -127,6 +127,31 @@ import { ExportRegular } from '@fluentui/react-icons';
 </Menu>;
 ```
 
+## Radio Group (Mutually Exclusive Toggle Items)
+
+v8 used `checked` items inside a data-driven CommandBar with manual mutual-exclusion logic. v9 provides `ToolbarRadioGroup` + `ToolbarRadioButton`:
+
+```tsx
+import { Toolbar, ToolbarRadioGroup, ToolbarRadioButton } from '@fluentui/react-components';
+import { AlignLeftRegular, AlignCenterRegular, AlignRightRegular } from '@fluentui/react-icons';
+
+const [align, setAlign] = React.useState('left');
+
+<Toolbar checkedValues={{ align: [align] }} onCheckedValueChange={(_, data) => setAlign(data.checkedItems[0])}>
+  <ToolbarRadioGroup>
+    <ToolbarRadioButton name="align" value="left" icon={<AlignLeftRegular />}>
+      Left
+    </ToolbarRadioButton>
+    <ToolbarRadioButton name="align" value="center" icon={<AlignCenterRegular />}>
+      Center
+    </ToolbarRadioButton>
+    <ToolbarRadioButton name="align" value="right" icon={<AlignRightRegular />}>
+      Right
+    </ToolbarRadioButton>
+  </ToolbarRadioGroup>
+</Toolbar>;
+```
+
 ## Overflow Handling
 
 v8 `CommandBar` handles overflow automatically via the `overflowItems` array.
diff --git a/skills/fluentui-migrate-v8-to-v9/references/tree.md b/skills/fluentui-migrate-v8-to-v9/references/tree.md
new file mode 100644
index 00000000000000..25ba1879a3c654
--- /dev/null
+++ b/skills/fluentui-migrate-v8-to-v9/references/tree.md
@@ -0,0 +1,101 @@
+# GroupedList → Tree Migration
+
+v8 `GroupedList` is a multipurpose component. The right v9 migration target depends on your usage:
+
+| v8 usage                                   | v9 target             |
+| ------------------------------------------ | --------------------- |
+| Hierarchical data that expands / collapses | `Tree`                |
+| Flat or nested list (no expand/collapse)   | `List`                |
+| Tabular / grid data                        | `Table` or `DataGrid` |
+
+## GroupedList → Tree (expand/collapse hierarchies)
+
+### Architecture Shift
+
+v8 `GroupedList` is data-driven (`items` array + `groups` array + `onRenderCell` callback). v9 `Tree` uses declarative JSX children with `<TreeItem>` / `<TreeItemLayout>`.
+
+```tsx
+// v8 — data-driven
+import { GroupedList, IGroup } from '@fluentui/react';
+
+const items = ['Apple', 'Banana', 'Cherry', 'Date'];
+const groups: IGroup[] = [
+  { key: 'g1', name: 'Fruits A-C', startIndex: 0, count: 3 },
+  { key: 'g2', name: 'Fruits D-F', startIndex: 3, count: 1 },
+];
+
+<GroupedList items={items} groups={groups} onRenderCell={(depth, item) => <div>{item}</div>} />;
+
+// v9 — declarative JSX
+import { Tree, TreeItem, TreeItemLayout } from '@fluentui/react-components';
+
+<Tree aria-label="Fruits">
+  <TreeItem itemType="branch" value="g1">
+    <TreeItemLayout>Fruits A-C</TreeItemLayout>
+    <Tree>
+      {['Apple', 'Banana', 'Cherry'].map(name => (
+        <TreeItem key={name} itemType="leaf" value={name}>
+          <TreeItemLayout>{name}</TreeItemLayout>
+        </TreeItem>
+      ))}
+    </Tree>
+  </TreeItem>
+  <TreeItem itemType="branch" value="g2">
+    <TreeItemLayout>Fruits D-F</TreeItemLayout>
+    <Tree>
+      <TreeItem itemType="leaf" value="Date">
+        <TreeItemLayout>Date</TreeItemLayout>
+      </TreeItem>
+    </Tree>
+  </TreeItem>
+</Tree>;
+```
+
+## Key Tree Props
+
+| Prop               | Notes                                                 |
+| ------------------ | ----------------------------------------------------- |
+| `aria-label`       | Required for accessibility                            |
+| `openItems`        | Controlled set of expanded item values                |
+| `defaultOpenItems` | Uncontrolled initial expanded items                   |
+| `onOpenChange`     | `(_, data) => void` — `data.openItems` is the new set |
+| `checkedItems`     | Controlled checked items (for selectable trees)       |
+| `onCheckedChange`  | Selection callback                                    |
+| `selectionMode`    | `"single"` \| `"multiselect"` \| `undefined`          |
+| `appearance`       | `"subtle"` \| `"subtle-alpha"` \| `"transparent"`     |
+| `size`             | `"small"` \| `"medium"` \| `"large"`                  |
+
+## TreeItem Props
+
+| Prop       | Notes                                 |
+| ---------- | ------------------------------------- |
+| `value`    | Unique identifier (required)          |
+| `itemType` | `"branch"` (has children) \| `"leaf"` |
+
+## Prop Mapping — GroupedList → Tree
+
+| v8 `IGroupedListProps`           | v9 equivalent                                 |
+| -------------------------------- | --------------------------------------------- |
+| `items`                          | Data source for `<TreeItem>` children         |
+| `groups`                         | `<TreeItem itemType="branch">` wrappers       |
+| `onRenderCell`                   | `<TreeItemLayout>` content                    |
+| `onRenderGroupHeader`            | `<TreeItemLayout>` of the branch `<TreeItem>` |
+| `onRenderGroupFooter`            | Custom content after the nested `<Tree>`      |
+| `selection`                      | `selectionMode` + `checkedItems` on `<Tree>`  |
+| `groupProps.onToggleCollapseAll` | `onOpenChange` on `<Tree>`                    |
+| `styles`                         | `className` + `makeStyles`                    |
+| `theme`                          | Use `FluentProvider`                          |
+
+## Flat List Alternative
+
+If you don't need expand/collapse, use `List` from `@fluentui/react-components`:
+
+```tsx
+import { List, ListItem } from '@fluentui/react-components';
+
+<List>
+  {items.map(item => (
+    <ListItem key={item.key}>{item.name}</ListItem>
+  ))}
+</List>;
+```

From 65db1d4f58fe1a1a00e3d89afe5745d4596039d1 Mon Sep 17 00:00:00 2001
From: Dmytro Kirpa <dmytrokirpa@microsoft.com>
Date: Wed, 4 Mar 2026 18:37:59 +0100
Subject: [PATCH 2/6] feat(fluent-cli): implement migrate v8-to-v9  command and
 skill

---
 skills/fluentui-migrate-v8-to-v9/SKILL.md     | 158 ++++-----
 tools/cli/package.json                        |   2 +
 .../cli/src/commands/migrate/handler.spec.ts  |  19 --
 tools/cli/src/commands/migrate/handler.ts     |   6 -
 tools/cli/src/commands/migrate/index.ts       |  17 +-
 .../__tests__/fixtures/button-variants.tsx    |  10 +
 .../__tests__/fixtures/icon-known.tsx         |   3 +
 .../__tests__/fixtures/icon-unknown.tsx       |   3 +
 .../__tests__/fixtures/import-paths.tsx       |   3 +
 .../v8-to-v9/__tests__/fixtures/indented.tsx  |   7 +
 .../__tests__/fixtures/multi-annotation.tsx   |   8 +
 .../__tests__/fixtures/multi-import.tsx       |   8 +
 .../__tests__/fixtures/no-equivalent.tsx      |   8 +
 .../__tests__/fixtures/prop-rename.tsx        |   5 +
 .../__tests__/fixtures/styles-prop.tsx        |   3 +
 .../v8-to-v9/__tests__/fixtures/unrelated.tsx |   4 +
 .../__tests__/handler.integration.spec.ts     | 317 ++++++++++++++++++
 .../v8-to-v9/__tests__/handler.spec.ts        |  77 +++++
 .../src/commands/migrate/v8-to-v9/handler.ts  |  92 +++++
 .../src/commands/migrate/v8-to-v9/index.ts    |  31 ++
 .../migrate/v8-to-v9/utils/annotator/index.ts |  96 ++++++
 .../utils/annotator/rules/button-variants.ts  |  58 ++++
 .../utils/annotator/rules/component-rename.ts |  71 ++++
 .../utils/annotator/rules/dialog-props.ts     |  57 ++++
 .../utils/annotator/rules/enum-to-string.ts   |  66 ++++
 .../v8-to-v9/utils/annotator/rules/get-id.ts  |  37 ++
 .../utils/annotator/rules/icon-props.ts       | 103 ++++++
 .../utils/annotator/rules/import-paths.ts     |  58 ++++
 .../utils/annotator/rules/keycodes.ts         |  66 ++++
 .../utils/annotator/rules/label-extraction.ts |  48 +++
 .../utils/annotator/rules/no-equivalent.ts    |  37 ++
 .../annotator/rules/progress-bar-props.ts     |  40 +++
 .../utils/annotator/rules/prop-rename.ts      |  42 +++
 .../annotator/rules/remove-theme-prop.ts      |  39 +++
 .../utils/annotator/rules/styles-prop.ts      |  33 ++
 .../utils/annotator/rules/toggle-props.ts     |  53 +++
 .../utils/annotator/rules/use-boolean.ts      |  54 +++
 .../v8-to-v9/utils/annotator/rules/utils.ts   |  36 ++
 .../migrate/v8-to-v9/utils/annotator/types.ts |  34 ++
 .../v8-to-v9/utils/annotator/writer.ts        |  53 +++
 40 files changed, 1735 insertions(+), 127 deletions(-)
 delete mode 100644 tools/cli/src/commands/migrate/handler.spec.ts
 delete mode 100644 tools/cli/src/commands/migrate/handler.ts
 create mode 100644 tools/cli/src/commands/migrate/v8-to-v9/__tests__/fixtures/button-variants.tsx
 create mode 100644 tools/cli/src/commands/migrate/v8-to-v9/__tests__/fixtures/icon-known.tsx
 create mode 100644 tools/cli/src/commands/migrate/v8-to-v9/__tests__/fixtures/icon-unknown.tsx
 create mode 100644 tools/cli/src/commands/migrate/v8-to-v9/__tests__/fixtures/import-paths.tsx
 create mode 100644 tools/cli/src/commands/migrate/v8-to-v9/__tests__/fixtures/indented.tsx
 create mode 100644 tools/cli/src/commands/migrate/v8-to-v9/__tests__/fixtures/multi-annotation.tsx
 create mode 100644 tools/cli/src/commands/migrate/v8-to-v9/__tests__/fixtures/multi-import.tsx
 create mode 100644 tools/cli/src/commands/migrate/v8-to-v9/__tests__/fixtures/no-equivalent.tsx
 create mode 100644 tools/cli/src/commands/migrate/v8-to-v9/__tests__/fixtures/prop-rename.tsx
 create mode 100644 tools/cli/src/commands/migrate/v8-to-v9/__tests__/fixtures/styles-prop.tsx
 create mode 100644 tools/cli/src/commands/migrate/v8-to-v9/__tests__/fixtures/unrelated.tsx
 create mode 100644 tools/cli/src/commands/migrate/v8-to-v9/__tests__/handler.integration.spec.ts
 create mode 100644 tools/cli/src/commands/migrate/v8-to-v9/__tests__/handler.spec.ts
 create mode 100644 tools/cli/src/commands/migrate/v8-to-v9/handler.ts
 create mode 100644 tools/cli/src/commands/migrate/v8-to-v9/index.ts
 create mode 100644 tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/index.ts
 create mode 100644 tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/button-variants.ts
 create mode 100644 tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/component-rename.ts
 create mode 100644 tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/dialog-props.ts
 create mode 100644 tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/enum-to-string.ts
 create mode 100644 tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/get-id.ts
 create mode 100644 tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/icon-props.ts
 create mode 100644 tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/import-paths.ts
 create mode 100644 tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/keycodes.ts
 create mode 100644 tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/label-extraction.ts
 create mode 100644 tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/no-equivalent.ts
 create mode 100644 tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/progress-bar-props.ts
 create mode 100644 tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/prop-rename.ts
 create mode 100644 tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/remove-theme-prop.ts
 create mode 100644 tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/styles-prop.ts
 create mode 100644 tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/toggle-props.ts
 create mode 100644 tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/use-boolean.ts
 create mode 100644 tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/utils.ts
 create mode 100644 tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/types.ts
 create mode 100644 tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/writer.ts

diff --git a/skills/fluentui-migrate-v8-to-v9/SKILL.md b/skills/fluentui-migrate-v8-to-v9/SKILL.md
index da037730bafbd9..f9659ba3c3c14f 100644
--- a/skills/fluentui-migrate-v8-to-v9/SKILL.md
+++ b/skills/fluentui-migrate-v8-to-v9/SKILL.md
@@ -38,19 +38,20 @@ After completing a migration session, report using this structure:
 2. In a monorepo or if multiple `tsconfig.json` files exist, ask the user: _"Which directory or package should I migrate? (e.g., `packages/my-app/src`)"_
 3. If no tsconfig exists, default to searching from the repo root (`.`) and adjust from there
 
-Replace `<SOURCE_ROOT>` in the commands below with the path you identified:
+Replace `<SOURCE_ROOT>` in the commands below with the path you identified.
 
-```sh
-# All files importing from @fluentui/react — adjust path to your repo layout
-grep -rl "@fluentui/react" <SOURCE_ROOT> --include="*.tsx" --include="*.ts"
+**Check for existing migration annotations:**
 
-# Tally component usage to prioritize
-grep -rh "from '@fluentui/react'" <SOURCE_ROOT> --include="*.tsx" --include="*.ts" | sort | uniq -c | sort -rn
+```sh
+grep -rl "@fluent-migrate:" <SOURCE_ROOT> --include="*.ts" --include="*.tsx"
 ```
 
-Identify which components are used and how many times. Migrate high-count simple components first.
+- If annotations are found → proceed to Step 3 (annotations are the work queue).
+- If nothing is found → tell the user:
+
+  > "No migration annotations found. Please run `npx @fluentui/cli migrate v8-to-v9 --path <SOURCE_ROOT>` first, then re-invoke the skill."
 
-Skip files that import **only** from `@fluentui/react-components` — they are already migrated.
+  Stop until the user confirms the CLI has been run.
 
 ### Setup Boundary
 
@@ -65,13 +66,13 @@ If either condition is unmet, report what's needed and stop until the user confi
 
 ### Agent Execution Contract
 
-**Phase order:** assess (+ tsc baseline) → plan → mechanical pass → semantic pass → validate → report (Output Template above)
+**Phase order:** check for annotations (+ tsc baseline) → if missing, ask user to run CLI → process annotations (`auto` → `scaffold` → `manual` → `no-equivalent`) → validate → report (Output Template above)
 
 **Baseline TypeScript check before starting:** run the repo's TypeScript check command (`tsc --noEmit` or the equivalent in `package.json` scripts) before any changes and record the error count. In the Validation step, report TypeScript as ✅ if post-migration error count ≤ baseline — do not block on pre-existing errors.
 
 **Behavior-preserving default:** when uncertain, preserve existing behavior. Never silently drop functionality.
 
-**Confidence threshold:** if you are less than ~80% confident in a mapping, add an inline comment and flag it — do not skip it silently:
+**Confidence threshold for `manual` annotations:** if you are less than ~80% confident in a mapping, add an inline comment and flag it — do not skip it silently:
 
 ```tsx
 // MIGRATION ASSUMPTION: GroupedList mapped to Tree (expand/collapse usage detected). Verify if tabular layout was intended.
@@ -79,9 +80,9 @@ If either condition is unmet, report what's needed and stop until the user confi
 
 **Stop and escalate when:**
 
-- TypeScript errors remain after mechanical pass that you cannot resolve
-- A component has no known v9 equivalent and no clear workaround
-- More than 2 unresolved 1→many mappings in the same file (see Ambiguity Resolution below)
+- TypeScript errors remain after processing annotations that you cannot resolve
+- A `no-equivalent` annotation has no clear workaround from the component mapping table
+- More than 2 unresolved `manual` annotations in the same file
 
 In those cases: commit what's done, fill in the Output Template with status ⚠️ or ❌, list the blockers, and wait for user input.
 
@@ -113,88 +114,55 @@ import { PortalCompatProvider } from '@fluentui/react-portal-compat';
 </FluentProvider>;
 ```
 
-### Step 3 — Migrate (file by file)
-
-**Recommended order within a file:**
-
-#### Pass 1 — Mechanical (safe to automate)
-
-1. Update import statements (`@fluentui/react` → `@fluentui/react-components`)
-2. Rename components per the mapping table below (1→1 renames only; defer 1→many to Pass 2)
-3. Apply universal prop renames (applies to every component):
-   - `componentRef` → `ref`
-   - `ariaLabel` → `aria-label`
-   - `ariaHidden` → `aria-hidden`
-   - `ariaDescribedBy` → `aria-describedby`
-   - `ariaLabelledBy` → `aria-labelledby`
-   - Remove `styles` prop → replace with `makeStyles` + `className`
-   - Combine class names with `mergeClasses(s.a, s.b, extra)` (replaces `cx` / `mergeStyles` for className composition)
-   - Remove `theme` prop → handled by `FluentProvider`
-4. Apply component-specific prop changes (see reference files below)
-
-#### Pass 2 — Semantic (requires judgment)
-
-5. Replace v8-only utility imports (no v9 equivalent — remove the import and use the native alternative):
-   - `useBoolean` → `React.useState<boolean>(false)` (`const [open, setOpen] = React.useState(false)`)
-   - `KeyCodes.enter` / `KeyCodes.escape` → `event.key === 'Enter'` / `event.key === 'Escape'`
-   - `NeutralColors.xxx` / `SharedColors.xxx` → `tokens.colorXxx` inside `makeStyles`
-   - `mergeStyleSets` / `concatStyleSets` → `makeStyles` + `mergeClasses`
-   - `getRTL()` / `rtl` on ThemeProvider → `dir="rtl"` prop on `FluentProvider`
-   - `getTheme()` → use `tokens` in `makeStyles`; `createTheme()` → `createLightTheme(brandVariants)`
-   - `getId('prefix')` → `useId('prefix')` from `@fluentui/react-components` (hook — call inside component)
-6. Extract `label` props from form controls (TextField, SpinButton, Slider, ChoiceGroup):
-   - **Preferred:** wrap the control in `<Field>` — it handles label, `required`, `validationMessage`, and `validationState` via context without any `useId` wiring:
-     ```tsx
-     import { Field, Input } from '@fluentui/react-components';
-     <Field label="Email" required validationState="error" validationMessage="Required">
-       <Input />
-     </Field>;
-     ```
-   - **Alternative (manual):** separate `<Label htmlFor={id}>` + `useId` from `@fluentui/react-components`
-7. Migrate `iconProps={{ iconName: 'X' }}` → `icon={<XRegular />}` (see [icons.md](references/icons.md))
-8. Resolve 1→many mappings and architectural changes (ContextualMenu→Menu JSX, Stack→makeStyles, etc.) — see Ambiguity Resolution below
-
-**Recommended migration order across files:**
-
-1. Simple renames with no API change (Separator→Divider, Toggle→Switch, Shimmer→Skeleton, etc.)
-2. Components with prop renames only (Button, Checkbox, Tabs/Pivot, Input/TextField)
-3. Components requiring label extraction (SpinButton, ChoiceGroup→RadioGroup, Slider)
-4. Architectural changes (ContextualMenu→Menu JSX children, Stack→makeStyles, ThemeProvider→FluentProvider)
-
-### Codemod Guidance
-
-**Safe to automate (Pass 1):**
-
-- Import path: `@fluentui/react` → `@fluentui/react-components`
-- Universal prop renames (`componentRef→ref`, `ariaLabel→aria-label`, etc.)
-- 1→1 component renames: Separator→Divider, Toggle→Switch, Shimmer→Skeleton, Label→Label, Icon→SVG import, Fabric→FluentProvider, Layer→Portal, Overlay→Portal
-- Shim swaps: `import { XShim as X } from '@fluentui/react-migration-v8-v9'`
-
-**Manual only (Pass 2 — requires understanding intent):**
-
-- 1→many mappings: GroupedList, DetailsList, Popup (see Ambiguity Resolution below)
-- `styles` prop → `makeStyles` (must understand what styles were doing)
-- `Stack`/`StackItem` → flexbox via `makeStyles` (layout intent must be preserved)
-- `ContextualMenu` / `CommandBar` data-driven → JSX (tree structure must be reconstructed)
-- Icon name string → SVG component import (names don't always match 1:1; use the icons reference)
-- Any `onRender*` callback → slot (render logic must be understood)
-
-### Ambiguity Resolution Rules
-
-For **1→many mappings**, resolve in this order:
-
-1. Check the component's reference file — it usually identifies the right target based on usage pattern
-2. Use surrounding code context:
-   - Tabular data with columns → `DataGrid` (selection/sort) or `Table` (read-only)
-   - Nested items with expand/collapse → `Tree`
-   - Flat scrollable list → `List`
-   - Non-modal overlay → `Popover`; modal/blocking → `Dialog`
-3. If still ambiguous after steps 1–2, log an assumption comment:
-   ```tsx
-   // MIGRATION ASSUMPTION: GroupedList mapped to Tree (expand/collapse pattern detected). Verify intent.
-   ```
-
-**Escalation trigger:** more than 2 unresolved 1→many mappings in the same file → stop, report status ⚠️, and ask the user before continuing.
+### Step 3 — Migrate (annotation-driven)
+
+Process the `@fluent-migrate:` annotations as a work queue. Get all annotations:
+
+```sh
+grep -rn "@fluent-migrate:" <SOURCE_ROOT> --include="*.ts" --include="*.tsx"
+```
+
+Work through them in this order, removing each annotation comment after applying the change:
+
+#### 1. `auto` annotations — apply mechanically, no questions
+
+```sh
+grep -rn "@fluent-migrate:auto" <SOURCE_ROOT> --include="*.ts" --include="*.tsx"
+```
+
+Each annotation encodes exactly what to do in its payload. Apply the transformation on the line below the comment and remove the annotation. No user questions needed.
+
+#### 2. `scaffold` annotations — generate boilerplate with TODO placeholders
+
+```sh
+grep -rn "@fluent-migrate:scaffold" <SOURCE_ROOT> --include="*.ts" --include="*.tsx"
+```
+
+Generate the appropriate boilerplate skeleton with `// TODO:` placeholders. Do **not** fill in semantic values (style values, layout intent, etc.). Remove the annotation on completion.
+
+#### 3. `manual` annotations — read context, apply or ask
+
+```sh
+grep -rn "@fluent-migrate:manual" <SOURCE_ROOT> --include="*.ts" --include="*.tsx"
+```
+
+Read the surrounding code context to determine intent. The annotation's `note` field lists choices. Apply if confident (>80%), using the component mapping table and per-component references below as reference. If ambiguous, log an assumption comment or ask the user before applying. Remove the annotation on completion.
+
+#### 4. `no-equivalent` annotations — surface to user
+
+```sh
+grep -rn "@fluent-migrate:no-equivalent" <SOURCE_ROOT> --include="*.ts" --include="*.tsx"
+```
+
+Do not attempt migration. Report each one to the user with the recommended alternative from the deprecation table below. Wait for user direction before proceeding. Remove the annotation only after the user provides a resolution.
+
+#### Verify zero annotations remain
+
+```sh
+grep -r "@fluent-migrate:" <SOURCE_ROOT> --include="*.ts" --include="*.tsx"
+```
+
+Should return nothing. Any remaining annotations are blockers — include them in the Output Template as unresolved deltas, then proceed to Step 4.
 
 ### Step 4 — Validate
 
diff --git a/tools/cli/package.json b/tools/cli/package.json
index 231942bd7dc517..3dee465b405717 100644
--- a/tools/cli/package.json
+++ b/tools/cli/package.json
@@ -15,6 +15,8 @@
   ],
   "dependencies": {
     "@swc/helpers": "^0.5.1",
+    "fast-glob": "^3.3.3",
+    "ts-morph": "^23.0.0",
     "yargs": "^17.7.2"
   },
   "devDependencies": {
diff --git a/tools/cli/src/commands/migrate/handler.spec.ts b/tools/cli/src/commands/migrate/handler.spec.ts
deleted file mode 100644
index 5c35abdf7eba17..00000000000000
--- a/tools/cli/src/commands/migrate/handler.spec.ts
+++ /dev/null
@@ -1,19 +0,0 @@
-import { handler } from './handler';
-
-describe('migrate handler', () => {
-  let logSpy: jest.SpyInstance;
-
-  beforeEach(() => {
-    logSpy = jest.spyOn(console, 'log').mockImplementation();
-  });
-
-  afterEach(() => {
-    logSpy.mockRestore();
-  });
-
-  it('should execute without errors', async () => {
-    await handler({ _: ['migrate'], $0: 'fluentui-cli' });
-
-    expect(logSpy).toHaveBeenCalledWith('migrate command - not yet implemented');
-  });
-});
diff --git a/tools/cli/src/commands/migrate/handler.ts b/tools/cli/src/commands/migrate/handler.ts
deleted file mode 100644
index 0b029904dd985a..00000000000000
--- a/tools/cli/src/commands/migrate/handler.ts
+++ /dev/null
@@ -1,6 +0,0 @@
-import type { CommandHandler } from '../../utils/types';
-
-export const handler: CommandHandler = async argv => {
-  // TODO: Implement migrate command
-  console.log('migrate command - not yet implemented');
-};
diff --git a/tools/cli/src/commands/migrate/index.ts b/tools/cli/src/commands/migrate/index.ts
index 06f593b8af6f23..3c0315830251e5 100644
--- a/tools/cli/src/commands/migrate/index.ts
+++ b/tools/cli/src/commands/migrate/index.ts
@@ -1,13 +1,16 @@
 import type { CommandModule } from 'yargs';
+import v8ToV9Command from './v8-to-v9';
 
 const command: CommandModule = {
-  command: 'migrate',
-  describe: 'Run codemod migrations',
-  builder: yargs => yargs.version(false).help(),
-  handler: async argv => {
-    const { handler } = await import('./handler');
-    return handler(argv);
-  },
+  command: 'migrate <migration>',
+  describe: 'Run migration analysis and annotation',
+  builder: yargs =>
+    yargs
+      .command(v8ToV9Command)
+      .demandCommand(1, 'Specify a migration type: v8-to-v9')
+      .version(false)
+      .help(),
+  handler: () => {},
 };
 
 export default command;
diff --git a/tools/cli/src/commands/migrate/v8-to-v9/__tests__/fixtures/button-variants.tsx b/tools/cli/src/commands/migrate/v8-to-v9/__tests__/fixtures/button-variants.tsx
new file mode 100644
index 00000000000000..235a77770f2b65
--- /dev/null
+++ b/tools/cli/src/commands/migrate/v8-to-v9/__tests__/fixtures/button-variants.tsx
@@ -0,0 +1,10 @@
+import { PrimaryButton, DefaultButton, ActionButton, IconButton } from '@fluentui/react';
+
+export const MyComp = () => (
+  <div>
+    <PrimaryButton>Primary</PrimaryButton>
+    <DefaultButton>Default</DefaultButton>
+    <ActionButton>Action</ActionButton>
+    <IconButton iconProps={{ iconName: 'Add' }} />
+  </div>
+);
diff --git a/tools/cli/src/commands/migrate/v8-to-v9/__tests__/fixtures/icon-known.tsx b/tools/cli/src/commands/migrate/v8-to-v9/__tests__/fixtures/icon-known.tsx
new file mode 100644
index 00000000000000..c2795a30e8fc3e
--- /dev/null
+++ b/tools/cli/src/commands/migrate/v8-to-v9/__tests__/fixtures/icon-known.tsx
@@ -0,0 +1,3 @@
+import { IconButton } from '@fluentui/react';
+
+export const MyComp = () => <IconButton iconProps={{ iconName: 'Add' }} />;
diff --git a/tools/cli/src/commands/migrate/v8-to-v9/__tests__/fixtures/icon-unknown.tsx b/tools/cli/src/commands/migrate/v8-to-v9/__tests__/fixtures/icon-unknown.tsx
new file mode 100644
index 00000000000000..323d0c4c629146
--- /dev/null
+++ b/tools/cli/src/commands/migrate/v8-to-v9/__tests__/fixtures/icon-unknown.tsx
@@ -0,0 +1,3 @@
+import { IconButton } from '@fluentui/react';
+
+export const MyComp = () => <IconButton iconProps={{ iconName: 'SomeLegacyIcon' }} />;
diff --git a/tools/cli/src/commands/migrate/v8-to-v9/__tests__/fixtures/import-paths.tsx b/tools/cli/src/commands/migrate/v8-to-v9/__tests__/fixtures/import-paths.tsx
new file mode 100644
index 00000000000000..3550c4730fe93b
--- /dev/null
+++ b/tools/cli/src/commands/migrate/v8-to-v9/__tests__/fixtures/import-paths.tsx
@@ -0,0 +1,3 @@
+import { Button } from '@fluentui/react';
+
+export const MyButton = () => <Button />;
diff --git a/tools/cli/src/commands/migrate/v8-to-v9/__tests__/fixtures/indented.tsx b/tools/cli/src/commands/migrate/v8-to-v9/__tests__/fixtures/indented.tsx
new file mode 100644
index 00000000000000..26fe7c2284e3a9
--- /dev/null
+++ b/tools/cli/src/commands/migrate/v8-to-v9/__tests__/fixtures/indented.tsx
@@ -0,0 +1,7 @@
+import { PrimaryButton } from '@fluentui/react';
+
+export const MyComp = () => (
+  <div>
+    <PrimaryButton>Click</PrimaryButton>
+  </div>
+);
diff --git a/tools/cli/src/commands/migrate/v8-to-v9/__tests__/fixtures/multi-annotation.tsx b/tools/cli/src/commands/migrate/v8-to-v9/__tests__/fixtures/multi-annotation.tsx
new file mode 100644
index 00000000000000..7b958ff6167e8e
--- /dev/null
+++ b/tools/cli/src/commands/migrate/v8-to-v9/__tests__/fixtures/multi-annotation.tsx
@@ -0,0 +1,8 @@
+import { PrimaryButton, DefaultButton } from '@fluentui/react';
+
+export const MyComp = () => (
+  <div>
+    <PrimaryButton>Save</PrimaryButton>
+    <DefaultButton>Cancel</DefaultButton>
+  </div>
+);
diff --git a/tools/cli/src/commands/migrate/v8-to-v9/__tests__/fixtures/multi-import.tsx b/tools/cli/src/commands/migrate/v8-to-v9/__tests__/fixtures/multi-import.tsx
new file mode 100644
index 00000000000000..ba5509b6ab8b58
--- /dev/null
+++ b/tools/cli/src/commands/migrate/v8-to-v9/__tests__/fixtures/multi-import.tsx
@@ -0,0 +1,8 @@
+import { Button, TextField } from '@fluentui/react';
+
+export const MyComp = () => (
+  <div>
+    <Button />
+    <TextField />
+  </div>
+);
diff --git a/tools/cli/src/commands/migrate/v8-to-v9/__tests__/fixtures/no-equivalent.tsx b/tools/cli/src/commands/migrate/v8-to-v9/__tests__/fixtures/no-equivalent.tsx
new file mode 100644
index 00000000000000..2bc6e1ed08fd5f
--- /dev/null
+++ b/tools/cli/src/commands/migrate/v8-to-v9/__tests__/fixtures/no-equivalent.tsx
@@ -0,0 +1,8 @@
+import { HoverCard, ActivityItem } from '@fluentui/react';
+
+export const MyComp = () => (
+  <div>
+    <HoverCard />
+    <ActivityItem />
+  </div>
+);
diff --git a/tools/cli/src/commands/migrate/v8-to-v9/__tests__/fixtures/prop-rename.tsx b/tools/cli/src/commands/migrate/v8-to-v9/__tests__/fixtures/prop-rename.tsx
new file mode 100644
index 00000000000000..90adb1d0b0b3d7
--- /dev/null
+++ b/tools/cli/src/commands/migrate/v8-to-v9/__tests__/fixtures/prop-rename.tsx
@@ -0,0 +1,5 @@
+import { TextField } from '@fluentui/react';
+
+const ref = null;
+
+export const MyComp = () => <TextField ariaLabel="field" componentRef={ref!} />;
diff --git a/tools/cli/src/commands/migrate/v8-to-v9/__tests__/fixtures/styles-prop.tsx b/tools/cli/src/commands/migrate/v8-to-v9/__tests__/fixtures/styles-prop.tsx
new file mode 100644
index 00000000000000..289b784a4921b4
--- /dev/null
+++ b/tools/cli/src/commands/migrate/v8-to-v9/__tests__/fixtures/styles-prop.tsx
@@ -0,0 +1,3 @@
+import { TextField } from '@fluentui/react';
+
+export const MyComp = () => <TextField styles={{ root: { color: 'red' } }} />;
diff --git a/tools/cli/src/commands/migrate/v8-to-v9/__tests__/fixtures/unrelated.tsx b/tools/cli/src/commands/migrate/v8-to-v9/__tests__/fixtures/unrelated.tsx
new file mode 100644
index 00000000000000..ee538844d2f6e0
--- /dev/null
+++ b/tools/cli/src/commands/migrate/v8-to-v9/__tests__/fixtures/unrelated.tsx
@@ -0,0 +1,4 @@
+import React from 'react';
+import { Button } from 'some-other-lib';
+
+export const Comp = () => <Button />;
diff --git a/tools/cli/src/commands/migrate/v8-to-v9/__tests__/handler.integration.spec.ts b/tools/cli/src/commands/migrate/v8-to-v9/__tests__/handler.integration.spec.ts
new file mode 100644
index 00000000000000..81ee85f66a9870
--- /dev/null
+++ b/tools/cli/src/commands/migrate/v8-to-v9/__tests__/handler.integration.spec.ts
@@ -0,0 +1,317 @@
+import * as fs from 'fs/promises';
+import * as os from 'os';
+import * as path from 'path';
+import { analyzeFiles } from '../utils/annotator';
+import { writeAnnotations } from '../utils/annotator/writer';
+import { handler } from '../handler';
+
+const FIXTURES_DIR = path.join(__dirname, 'fixtures');
+
+async function mkTmpDir(): Promise<string> {
+  return fs.mkdtemp(path.join(os.tmpdir(), 'fluent-migrate-test-'));
+}
+
+/** Copy a fixture file into tmpDir and return the destination path. */
+async function copyFixture(tmpDir: string, name: string): Promise<string> {
+  const dest = path.join(tmpDir, name);
+  await fs.copyFile(path.join(FIXTURES_DIR, name), dest);
+  return dest;
+}
+
+// ─── suite ───────────────────────────────────────────────────────────────────
+
+describe('migrate v8-to-v9 — integration', () => {
+  let tmpDir: string;
+
+  beforeEach(async () => {
+    tmpDir = await mkTmpDir();
+  });
+
+  afterEach(async () => {
+    await fs.rm(tmpDir, { recursive: true, force: true });
+  });
+
+  // ── analyzeFiles ────────────────────────────────────────────────────────────
+
+  describe('analyzeFiles', () => {
+    it('returns empty results for files with no @fluentui/react imports', async () => {
+      await copyFixture(tmpDir, 'unrelated.tsx');
+
+      const results = await analyzeFiles(tmpDir);
+
+      expect(results).toHaveLength(0);
+    });
+
+    it('detects import-paths annotation on a @fluentui/react import', async () => {
+      await copyFixture(tmpDir, 'import-paths.tsx');
+
+      const results = await analyzeFiles(tmpDir);
+
+      expect(results).toHaveLength(1);
+      const importAnnotations = results[0].annotations.filter(a => a.codemod === 'import-paths');
+      expect(importAnnotations.length).toBeGreaterThan(0);
+      expect(importAnnotations[0].action).toBe('auto');
+      expect(importAnnotations[0].payload).toContain('@fluentui/react-components');
+    });
+
+    it('detects button-variant annotations for all v8 button variants', async () => {
+      await copyFixture(tmpDir, 'button-variants.tsx');
+
+      const results = await analyzeFiles(tmpDir);
+
+      expect(results).toHaveLength(1);
+      const variants = results[0].annotations.filter(a => a.codemod === 'button-variants');
+      expect(variants.length).toBe(4);
+      expect(variants.some(a => a.payload.includes('PrimaryButton'))).toBe(true);
+      expect(variants.some(a => a.payload.includes('DefaultButton'))).toBe(true);
+      expect(variants.some(a => a.payload.includes('ActionButton'))).toBe(true);
+      expect(variants.some(a => a.payload.includes('IconButton'))).toBe(true);
+      expect(variants.every(a => a.action === 'auto')).toBe(true);
+    });
+
+    it('detects styles prop as a scaffold annotation', async () => {
+      await copyFixture(tmpDir, 'styles-prop.tsx');
+
+      const results = await analyzeFiles(tmpDir);
+
+      expect(results).toHaveLength(1);
+      const styleAnnotations = results[0].annotations.filter(a => a.codemod === 'styles-prop');
+      expect(styleAnnotations).toHaveLength(1);
+      expect(styleAnnotations[0].action).toBe('scaffold');
+    });
+
+    it('detects no-equivalent annotations for deprecated components', async () => {
+      await copyFixture(tmpDir, 'no-equivalent.tsx');
+
+      const results = await analyzeFiles(tmpDir);
+
+      expect(results).toHaveLength(1);
+      const noEquiv = results[0].annotations.filter(a => a.action === 'no-equivalent');
+      expect(noEquiv.length).toBeGreaterThanOrEqual(2);
+    });
+
+    it('detects prop-rename annotations for legacy ARIA props', async () => {
+      await copyFixture(tmpDir, 'prop-rename.tsx');
+
+      const results = await analyzeFiles(tmpDir);
+
+      expect(results).toHaveLength(1);
+      const propAnnotations = results[0].annotations.filter(a => a.codemod === 'prop-rename');
+      expect(propAnnotations.length).toBeGreaterThanOrEqual(2);
+      expect(propAnnotations.some(a => a.payload.includes('ariaLabel'))).toBe(true);
+      expect(propAnnotations.some(a => a.payload.includes('componentRef'))).toBe(true);
+    });
+
+    it('detects icon-props annotation with auto action for a known icon name', async () => {
+      await copyFixture(tmpDir, 'icon-known.tsx');
+
+      const results = await analyzeFiles(tmpDir);
+
+      const iconAnnotations = results[0].annotations.filter(a => a.codemod === 'icon-props');
+      expect(iconAnnotations).toHaveLength(1);
+      expect(iconAnnotations[0].action).toBe('auto');
+      expect(iconAnnotations[0].payload).toContain('AddRegular');
+    });
+
+    it('detects icon-props annotation with manual action for an unknown icon name', async () => {
+      await copyFixture(tmpDir, 'icon-unknown.tsx');
+
+      const results = await analyzeFiles(tmpDir);
+
+      const iconAnnotations = results[0].annotations.filter(a => a.codemod === 'icon-props');
+      expect(iconAnnotations).toHaveLength(1);
+      expect(iconAnnotations[0].action).toBe('manual');
+    });
+
+    it('tracks @fluentui/react-components as a missing dep when import-paths is detected', async () => {
+      await copyFixture(tmpDir, 'import-paths.tsx');
+
+      const results = await analyzeFiles(tmpDir);
+
+      expect(results[0].missingDeps.some(d => d.name === '@fluentui/react-components')).toBe(true);
+    });
+
+    it('tracks @fluentui/react-icons as a missing dep when icon-props is detected', async () => {
+      await copyFixture(tmpDir, 'icon-known.tsx');
+
+      const results = await analyzeFiles(tmpDir);
+
+      expect(results[0].missingDeps.some(d => d.name === '@fluentui/react-icons')).toBe(true);
+    });
+
+    it('analyzes multiple files in a directory and skips non-fluent ones', async () => {
+      await Promise.all([
+        copyFixture(tmpDir, 'import-paths.tsx'),
+        copyFixture(tmpDir, 'button-variants.tsx'),
+        copyFixture(tmpDir, 'unrelated.tsx'),
+      ]);
+
+      const results = await analyzeFiles(tmpDir);
+
+      expect(results).toHaveLength(2);
+      const names = results.map(r => path.basename(r.filePath));
+      expect(names).toContain('import-paths.tsx');
+      expect(names).toContain('button-variants.tsx');
+      expect(names).not.toContain('unrelated.tsx');
+    });
+
+    it('deduplicates missing deps across multiple annotations in the same file', async () => {
+      await copyFixture(tmpDir, 'multi-import.tsx');
+
+      const results = await analyzeFiles(tmpDir);
+
+      const reactComponentsDeps = results[0].missingDeps.filter(d => d.name === '@fluentui/react-components');
+      expect(reactComponentsDeps).toHaveLength(1);
+    });
+  });
+
+  // ── writeAnnotations ─────────────────────────────────────────────────────────
+
+  describe('writeAnnotations', () => {
+    it('inserts @fluent-migrate: comments into the source file', async () => {
+      const filePath = await copyFixture(tmpDir, 'import-paths.tsx');
+
+      const results = await analyzeFiles(tmpDir);
+      await writeAnnotations(results);
+
+      const content = await fs.readFile(filePath, 'utf8');
+      expect(content).toMatchInlineSnapshot(`
+        "// @fluent-migrate:auto | import-paths | @fluentui/react → @fluentui/react-components
+        import { Button } from '@fluentui/react';
+
+        export const MyButton = () => <Button />;
+        "
+      `);
+    });
+
+    it('returns the number of files changed', async () => {
+      await Promise.all([copyFixture(tmpDir, 'import-paths.tsx'), copyFixture(tmpDir, 'button-variants.tsx')]);
+
+      const results = await analyzeFiles(tmpDir);
+      const { filesChanged } = await writeAnnotations(results);
+
+      expect(filesChanged).toBe(2);
+    });
+
+    it('is idempotent — running twice does not duplicate annotations', async () => {
+      const filePath = await copyFixture(tmpDir, 'import-paths.tsx');
+
+      const results1 = await analyzeFiles(tmpDir);
+      await writeAnnotations(results1);
+      const afterFirst = await fs.readFile(filePath, 'utf8');
+
+      const results2 = await analyzeFiles(tmpDir);
+      await writeAnnotations(results2);
+      const afterSecond = await fs.readFile(filePath, 'utf8');
+
+      expect(afterSecond).toBe(afterFirst);
+    });
+
+    it('preserves indentation of the target line in the inserted comment', async () => {
+      const filePath = await copyFixture(tmpDir, 'indented.tsx');
+
+      const results = await analyzeFiles(tmpDir);
+      await writeAnnotations(results);
+
+      const content = await fs.readFile(filePath, 'utf8');
+      expect(content).toMatchInlineSnapshot(`
+        "// @fluent-migrate:auto | import-paths | @fluentui/react → @fluentui/react-components
+        import { PrimaryButton } from '@fluentui/react';
+
+        export const MyComp = () => (
+          <div>
+            {/* @fluent-migrate:auto | button-variants | PrimaryButton → Button appearance=\\"primary\\" */}
+            <PrimaryButton>Click</PrimaryButton>
+          </div>
+        );
+        "
+      `);
+    });
+
+    it('annotates multiple sites in a single file', async () => {
+      const filePath = await copyFixture(tmpDir, 'multi-annotation.tsx');
+
+      const results = await analyzeFiles(tmpDir);
+      await writeAnnotations(results);
+
+      const content = await fs.readFile(filePath, 'utf8');
+      expect(content).toMatchInlineSnapshot(`
+        "// @fluent-migrate:auto | import-paths | @fluentui/react → @fluentui/react-components
+        import { PrimaryButton, DefaultButton } from '@fluentui/react';
+
+        export const MyComp = () => (
+          <div>
+            {/* @fluent-migrate:auto | button-variants | PrimaryButton → Button appearance=\\"primary\\" */}
+            <PrimaryButton>Save</PrimaryButton>
+            {/* @fluent-migrate:auto | button-variants | DefaultButton → Button */}
+            <DefaultButton>Cancel</DefaultButton>
+          </div>
+        );
+        "
+      `);
+    });
+  });
+
+  // ── handler end-to-end ───────────────────────────────────────────────────────
+
+  describe('handler (end-to-end)', () => {
+    let logs: string[];
+    let logSpy: jest.SpyInstance;
+
+    beforeEach(() => {
+      logs = [];
+      logSpy = jest.spyOn(console, 'log').mockImplementation((...args: unknown[]) => {
+        logs.push(args.map(String).join(' '));
+      });
+    });
+
+    afterEach(() => {
+      logSpy.mockRestore();
+    });
+
+    it('dry-run does not modify files', async () => {
+      const filePath = await copyFixture(tmpDir, 'import-paths.tsx');
+      const original = await fs.readFile(filePath, 'utf8');
+
+      await handler({ path: tmpDir, dryRun: true, _: [], $0: 'fluentui-cli' });
+
+      const after = await fs.readFile(filePath, 'utf8');
+      expect(after).toBe(original);
+    });
+
+    it('dry-run prints [dry-run] header and lists files that would be annotated', async () => {
+      await copyFixture(tmpDir, 'import-paths.tsx');
+
+      await handler({ path: tmpDir, dryRun: true, _: [], $0: 'fluentui-cli' });
+
+      expect(logs.some(l => l.includes('[dry-run]'))).toBe(true);
+      expect(logs.some(l => l.includes('import-paths.tsx'))).toBe(true);
+    });
+
+    it('write mode annotates files and prints summary with file count', async () => {
+      const filePath = await copyFixture(tmpDir, 'import-paths.tsx');
+
+      await handler({ path: tmpDir, dryRun: false, _: [], $0: 'fluentui-cli' });
+
+      const content = await fs.readFile(filePath, 'utf8');
+      expect(content).toContain('// @fluent-migrate:');
+      expect(logs.some(l => l.includes('Annotated'))).toBe(true);
+    });
+
+    it('write mode prints missing dep packages in the summary', async () => {
+      await copyFixture(tmpDir, 'import-paths.tsx');
+
+      await handler({ path: tmpDir, dryRun: false, _: [], $0: 'fluentui-cli' });
+
+      expect(logs.some(l => l.includes('@fluentui/react-components'))).toBe(true);
+    });
+
+    it('reports zero files annotated when no fluent imports are found', async () => {
+      await copyFixture(tmpDir, 'unrelated.tsx');
+
+      await handler({ path: tmpDir, dryRun: false, _: [], $0: 'fluentui-cli' });
+
+      expect(logs.some(l => l.includes('Annotated 0 files'))).toBe(true);
+    });
+  });
+});
diff --git a/tools/cli/src/commands/migrate/v8-to-v9/__tests__/handler.spec.ts b/tools/cli/src/commands/migrate/v8-to-v9/__tests__/handler.spec.ts
new file mode 100644
index 00000000000000..c4845e5c74fcec
--- /dev/null
+++ b/tools/cli/src/commands/migrate/v8-to-v9/__tests__/handler.spec.ts
@@ -0,0 +1,77 @@
+import { handler } from '../handler';
+import * as annotator from '../utils/annotator';
+import * as writer from '../utils/annotator/writer';
+
+jest.mock('../utils/annotator');
+jest.mock('../utils/annotator/writer');
+
+const mockAnalyzeFiles = annotator.analyzeFiles as jest.MockedFunction<typeof annotator.analyzeFiles>;
+const mockWriteAnnotations = writer.writeAnnotations as jest.MockedFunction<typeof writer.writeAnnotations>;
+
+describe('migrate v8-to-v9 handler', () => {
+  let logSpy: jest.SpyInstance;
+
+  beforeEach(() => {
+    logSpy = jest.spyOn(console, 'log').mockImplementation();
+    jest.clearAllMocks();
+  });
+
+  afterEach(() => {
+    logSpy.mockRestore();
+  });
+
+  it('calls analyzeFiles and writeAnnotations with the given path', async () => {
+    mockAnalyzeFiles.mockResolvedValue([]);
+    mockWriteAnnotations.mockResolvedValue({ filesChanged: 0 });
+
+    await handler({ path: 'src/', dryRun: false, _: [], $0: 'fluentui-cli' });
+
+    expect(mockAnalyzeFiles).toHaveBeenCalledWith('src/');
+    expect(mockWriteAnnotations).toHaveBeenCalled();
+  });
+
+  it('skips writeAnnotations in dry-run mode', async () => {
+    mockAnalyzeFiles.mockResolvedValue([]);
+
+    await handler({ path: 'src/', dryRun: true, _: [], $0: 'fluentui-cli' });
+
+    expect(mockAnalyzeFiles).toHaveBeenCalledWith('src/');
+    expect(mockWriteAnnotations).not.toHaveBeenCalled();
+  });
+
+  it('prints annotation counts after writing', async () => {
+    mockAnalyzeFiles.mockResolvedValue([
+      {
+        filePath: 'src/Button.tsx',
+        annotations: [
+          { action: 'auto', codemod: 'import-paths', payload: 'test', line: 1 },
+          { action: 'manual', codemod: 'component-rename', payload: 'test', line: 5 },
+        ],
+        missingDeps: [],
+      },
+    ]);
+    mockWriteAnnotations.mockResolvedValue({ filesChanged: 1 });
+
+    await handler({ path: 'src/', dryRun: false, _: [], $0: 'fluentui-cli' });
+
+    expect(logSpy).toHaveBeenCalledWith(expect.stringContaining('Annotated 1 files'));
+    expect(logSpy).toHaveBeenCalledWith(expect.stringContaining('auto'));
+    expect(logSpy).toHaveBeenCalledWith(expect.stringContaining('manual'));
+  });
+
+  it('prints [dry-run] preview without writing', async () => {
+    mockAnalyzeFiles.mockResolvedValue([
+      {
+        filePath: 'src/Button.tsx',
+        annotations: [{ action: 'scaffold', codemod: 'styles-prop', payload: 'test', line: 3 }],
+        missingDeps: [{ name: '@fluentui/react-components', reason: 'core v9 components' }],
+      },
+    ]);
+
+    await handler({ path: 'src/', dryRun: true, _: [], $0: 'fluentui-cli' });
+
+    expect(logSpy).toHaveBeenCalledWith(expect.stringContaining('[dry-run]'));
+    expect(logSpy).toHaveBeenCalledWith(expect.stringContaining('@fluentui/react-components'));
+    expect(mockWriteAnnotations).not.toHaveBeenCalled();
+  });
+});
diff --git a/tools/cli/src/commands/migrate/v8-to-v9/handler.ts b/tools/cli/src/commands/migrate/v8-to-v9/handler.ts
new file mode 100644
index 00000000000000..b25855fca0cdbf
--- /dev/null
+++ b/tools/cli/src/commands/migrate/v8-to-v9/handler.ts
@@ -0,0 +1,92 @@
+import type { CommandHandler } from '../../../utils/types';
+import { analyzeFiles } from './utils/annotator';
+import { writeAnnotations } from './utils/annotator/writer';
+import type { FileAnalysis } from './utils/annotator/types';
+
+interface V8ToV9Args {
+  path: string;
+  dryRun: boolean;
+}
+
+export const handler: CommandHandler<V8ToV9Args> = async argv => {
+  const results = await analyzeFiles(argv.path);
+
+  if (argv.dryRun) {
+    printDryRunReport(results);
+    return;
+  }
+
+  const { filesChanged } = await writeAnnotations(results);
+  printSummary(results, filesChanged);
+};
+
+function countByAction(results: FileAnalysis[]) {
+  const counts = { auto: 0, scaffold: 0, manual: 0, noEquivalent: 0 };
+  for (const file of results) {
+    for (const a of file.annotations) {
+      if (a.action === 'auto') counts.auto++;
+      else if (a.action === 'scaffold') counts.scaffold++;
+      else if (a.action === 'manual') counts.manual++;
+      else if (a.action === 'no-equivalent') counts.noEquivalent++;
+    }
+  }
+  return counts;
+}
+
+function collectDeps(results: FileAnalysis[]): Array<{ name: string; reason: string }> {
+  const seen = new Set<string>();
+  const deps: Array<{ name: string; reason: string }> = [];
+  for (const file of results) {
+    for (const dep of file.missingDeps) {
+      if (!seen.has(dep.name)) {
+        seen.add(dep.name);
+        deps.push(dep);
+      }
+    }
+  }
+  return deps;
+}
+
+function printSummary(results: FileAnalysis[], filesChanged: number): void {
+  const counts = countByAction(results);
+  const deps = collectDeps(results);
+
+  console.log(`\nAnnotated ${filesChanged} files`);
+  console.log(`  auto          ${counts.auto.toString().padStart(4)}  (safe to apply mechanically)`);
+  console.log(`  scaffold      ${counts.scaffold.toString().padStart(4)}  (boilerplate needed)`);
+  console.log(`  manual        ${counts.manual.toString().padStart(4)}  (requires judgment)`);
+  console.log(`  no-equivalent ${counts.noEquivalent.toString().padStart(4)}  (no v9 replacement)`);
+
+  if (deps.length > 0) {
+    console.log('\nRequired packages (not in package.json):');
+    for (const dep of deps) {
+      console.log(`  ${dep.name.padEnd(35)} — ${dep.reason}`);
+    }
+  }
+}
+
+function printDryRunReport(results: FileAnalysis[]): void {
+  const counts = countByAction(results);
+  const deps = collectDeps(results);
+
+  console.log('\n[dry-run] No files were modified.\n');
+  console.log(`Would annotate ${results.length} files`);
+  console.log(`  auto          ${counts.auto.toString().padStart(4)}  (safe to apply mechanically)`);
+  console.log(`  scaffold      ${counts.scaffold.toString().padStart(4)}  (boilerplate needed)`);
+  console.log(`  manual        ${counts.manual.toString().padStart(4)}  (requires judgment)`);
+  console.log(`  no-equivalent ${counts.noEquivalent.toString().padStart(4)}  (no v9 replacement)`);
+
+  if (deps.length > 0) {
+    console.log('\nRequired packages (not in package.json):');
+    for (const dep of deps) {
+      console.log(`  ${dep.name.padEnd(35)} — ${dep.reason}`);
+    }
+  }
+
+  if (results.length > 0) {
+    console.log('\nFiles that would be annotated:');
+    for (const file of results) {
+      console.log(`  ${file.filePath}  (${file.annotations.length} annotations)`);
+    }
+  }
+}
diff --git a/tools/cli/src/commands/migrate/v8-to-v9/index.ts b/tools/cli/src/commands/migrate/v8-to-v9/index.ts
new file mode 100644
index 00000000000000..b6763a861bac68
--- /dev/null
+++ b/tools/cli/src/commands/migrate/v8-to-v9/index.ts
@@ -0,0 +1,31 @@
+import type { CommandModule } from 'yargs';
+
+interface V8ToV9Args {
+  path: string;
+  dryRun: boolean;
+}
+
+const command: CommandModule<{}, V8ToV9Args> = {
+  command: 'v8-to-v9',
+  describe: 'Migrate Fluent UI v8 (@fluentui/react) to v9 (@fluentui/react-components)',
+  builder: yargs =>
+    yargs
+      .option('path', {
+        type: 'string',
+        demandOption: true,
+        describe: 'Source root to annotate (e.g. src/, app/, packages/my-app/src)',
+      })
+      .option('dry-run', {
+        type: 'boolean',
+        default: false,
+        describe: 'Preview annotations without writing files',
+      })
+      .version(false)
+      .help(),
+  handler: async argv => {
+    const { handler } = await import('./handler');
+    return handler(argv);
+  },
+};
+
+export default command;
diff --git a/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/index.ts b/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/index.ts
new file mode 100644
index 00000000000000..b59f54ccee8407
--- /dev/null
+++ b/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/index.ts
@@ -0,0 +1,96 @@
+import * as glob from 'fast-glob';
+import * as path from 'path';
+import { Project } from 'ts-morph';
+import type { FileAnalysis } from './types';
+import { detectImportPaths } from './rules/import-paths';
+import { detectComponentRenames } from './rules/component-rename';
+import { detectButtonVariants } from './rules/button-variants';
+import { detectPropRenames } from './rules/prop-rename';
+import { detectRemoveThemeProp } from './rules/remove-theme-prop';
+import { detectDialogProps } from './rules/dialog-props';
+import { detectEnumToString } from './rules/enum-to-string';
+import { detectToggleProps } from './rules/toggle-props';
+import { detectProgressBarProps } from './rules/progress-bar-props';
+import { detectUseBoolean } from './rules/use-boolean';
+import { detectKeyCodes } from './rules/keycodes';
+import { detectGetId } from './rules/get-id';
+import { detectIconProps } from './rules/icon-props';
+import { detectLabelExtraction } from './rules/label-extraction';
+import { detectStylesProp } from './rules/styles-prop';
+import { detectNoEquivalent } from './rules/no-equivalent';
+
+const RULES = [
+  detectImportPaths,
+  detectComponentRenames,
+  detectButtonVariants,
+  detectPropRenames,
+  detectRemoveThemeProp,
+  detectDialogProps,
+  detectEnumToString,
+  detectToggleProps,
+  detectProgressBarProps,
+  detectUseBoolean,
+  detectKeyCodes,
+  detectGetId,
+  detectIconProps,
+  detectLabelExtraction,
+  detectStylesProp,
+  detectNoEquivalent,
+];
+
+const DEP_REQUIREMENTS: Array<{ name: string; reason: string; triggerCodemod: string }> = [
+  {
+    name: '@fluentui/react-components',
+    reason: 'core v9 components',
+    triggerCodemod: 'import-paths',
+  },
+  {
+    name: '@fluentui/react-icons',
+    reason: 'SVG icon components (needed: icon-props migrations found)',
+    triggerCodemod: 'icon-props',
+  },
+];
+
+/**
+ * Pure detection engine — no file I/O.
+ * Both migrate and dry-run call this.
+ */
+export async function analyzeFiles(sourcePath: string): Promise<FileAnalysis[]> {
+  const absoluteSource = path.resolve(sourcePath);
+
+  const filePaths = await glob.glob(['**/*.ts', '**/*.tsx'], {
+    cwd: absoluteSource,
+    absolute: true,
+    ignore: ['**/node_modules/**', '**/*.d.ts'],
+  });
+
+  const project = new Project({ skipAddingFilesFromTsConfig: true });
+  project.addSourceFilesAtPaths(filePaths);
+
+  const results: FileAnalysis[] = [];
+
+  for (const sourceFile of project.getSourceFiles()) {
+    // Skip files with no @fluentui/react imports (already migrated or unrelated)
+    const hasFluentImport = sourceFile
+      .getImportDeclarations()
+      .some(d => d.getModuleSpecifierValue() === '@fluentui/react');
+    if (!hasFluentImport) continue;
+
+    const annotations = RULES.flatMap(rule => rule(sourceFile));
+    if (annotations.length === 0) continue;
+
+    // Determine which deps are needed based on detected codemods
+    const detectedCodemods = new Set(annotations.map(a => a.codemod));
+    const missingDeps = DEP_REQUIREMENTS.filter(dep => detectedCodemods.has(dep.triggerCodemod)).map(
+      ({ name, reason }) => ({ name, reason }),
+    );
+
+    results.push({
+      filePath: sourceFile.getFilePath(),
+      annotations,
+      missingDeps,
+    });
+  }
+
+  return results;
+}
diff --git a/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/button-variants.ts b/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/button-variants.ts
new file mode 100644
index 00000000000000..5eb4862e82a99c
--- /dev/null
+++ b/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/button-variants.ts
@@ -0,0 +1,58 @@
+import type { SourceFile, Node } from 'ts-morph';
+import { SyntaxKind } from 'ts-morph';
+import type { AnnotationResult } from '../types';
+import { getFluentImportNames, isJsxChild } from './utils';
+
+const BUTTON_VARIANTS: Record<string, string> = {
+  PrimaryButton: 'Button appearance="primary"',
+  DefaultButton: 'Button',
+  ActionButton: 'Button appearance="transparent"',
+  IconButton: 'Button (icon-only)',
+  CompoundButton: 'CompoundButton',
+};
+
+export function detectButtonVariants(sourceFile: SourceFile): AnnotationResult[] {
+  const results: AnnotationResult[] = [];
+  const fluentNames = getFluentImportNames(sourceFile);
+
+  sourceFile.forEachDescendant((node: Node) => {
+    if (node.getKind() !== SyntaxKind.JsxOpeningElement && node.getKind() !== SyntaxKind.JsxSelfClosingElement) {
+      return;
+    }
+
+    const tagName = node.getFirstChildByKind(SyntaxKind.Identifier)?.getText() ?? '';
+    if (!fluentNames.has(tagName) || !BUTTON_VARIANTS[tagName]) return;
+
+    const line = node.getStartLineNumber();
+    const insideJsx = isJsxChild(node);
+
+    if (tagName === 'IconButton') {
+      results.push({
+        action: 'auto',
+        codemod: 'button-variants',
+        payload: 'IconButton → Button (icon-only)',
+        note: 'add aria-label if missing',
+        line,
+        insideJsx,
+      });
+    } else if (tagName === 'CompoundButton') {
+      results.push({
+        action: 'auto',
+        codemod: 'button-variants',
+        payload: 'CompoundButton.secondaryText → secondaryContent',
+        line,
+        insideJsx,
+      });
+    } else {
+      results.push({
+        action: 'auto',
+        codemod: 'button-variants',
+        payload: `${tagName} → ${BUTTON_VARIANTS[tagName]}`,
+        line,
+        insideJsx,
+      });
+    }
+  });
+
+  return results;
+}
diff --git a/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/component-rename.ts b/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/component-rename.ts
new file mode 100644
index 00000000000000..d9f5973bba0f24
--- /dev/null
+++ b/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/component-rename.ts
@@ -0,0 +1,71 @@
+import type { SourceFile, Node } from 'ts-morph';
+import { SyntaxKind } from 'ts-morph';
+import type { AnnotationResult } from '../types';
+import { getFluentImportNames, isJsxChild } from './utils';
+
+/** 1→1 renames that are safe to apply automatically. */
+const AUTO_RENAMES: Record<string, string> = {
+  Separator: 'Divider',
+  Toggle: 'Switch',
+  Shimmer: 'Skeleton',
+  Fabric: 'FluentProvider',
+  Layer: 'Portal',
+  Overlay: 'Portal',
+  ProgressIndicator: 'ProgressBar',
+  SwatchColorPicker: 'SwatchPicker',
+  CommandButton: 'MenuButton',
+};
+
+/** 1→many — the agent must decide based on context. */
+const MANUAL_RENAMES: Record<string, { choices: string; ref: string }> = {
+  GroupedList: {
+    choices: 'Tree (expand/collapse), DataGrid (tabular), List (flat)',
+    ref: 'references/tree.md',
+  },
+  DetailsList: {
+    choices: 'DataGrid (selection/sort), Table (read-only)',
+    ref: 'references/datagrid.md',
+  },
+  Popup: {
+    choices: 'Popover (non-modal overlay), Dialog (modal/blocking)',
+    ref: '',
+  },
+};
+
+export function detectComponentRenames(sourceFile: SourceFile): AnnotationResult[] {
+  const results: AnnotationResult[] = [];
+  const fluentNames = getFluentImportNames(sourceFile);
+
+  sourceFile.forEachDescendant((node: Node) => {
+    if (node.getKind() !== SyntaxKind.JsxOpeningElement && node.getKind() !== SyntaxKind.JsxSelfClosingElement) {
+      return;
+    }
+
+    const tagName = node.getFirstChildByKind(SyntaxKind.Identifier)?.getText() ?? '';
+    if (!fluentNames.has(tagName)) return;
+
+    const insideJsx = isJsxChild(node);
+
+    if (AUTO_RENAMES[tagName]) {
+      results.push({
+        action: 'auto',
+        codemod: 'component-rename',
+        payload: `${tagName} → ${AUTO_RENAMES[tagName]}`,
+        line: node.getStartLineNumber(),
+        insideJsx,
+      });
+    } else if (MANUAL_RENAMES[tagName]) {
+      const { choices, ref } = MANUAL_RENAMES[tagName];
+      results.push({
+        action: 'manual',
+        codemod: 'component-rename',
+        payload: `${tagName} → ?`,
+        note: `choices: ${choices}${ref ? ` — see ${ref}` : ''}`,
+        line: node.getStartLineNumber(),
+        insideJsx,
+      });
+    }
+  });
+
+  return results;
+}
diff --git a/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/dialog-props.ts b/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/dialog-props.ts
new file mode 100644
index 00000000000000..ad805258f965ef
--- /dev/null
+++ b/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/dialog-props.ts
@@ -0,0 +1,57 @@
+import type { SourceFile, Node } from 'ts-morph';
+import { SyntaxKind } from 'ts-morph';
+import type { AnnotationResult } from '../types';
+import { getFluentImportNames } from './utils';
+
+const DIALOG_COMPONENTS = new Set(['Dialog', 'Modal']);
+
+export function detectDialogProps(sourceFile: SourceFile): AnnotationResult[] {
+  const results: AnnotationResult[] = [];
+  const fluentNames = getFluentImportNames(sourceFile);
+
+  sourceFile.forEachDescendant((node: Node) => {
+    if (node.getKind() !== SyntaxKind.JsxOpeningElement && node.getKind() !== SyntaxKind.JsxSelfClosingElement) {
+      return;
+    }
+
+    const tagName = node.getFirstChildByKind(SyntaxKind.Identifier)?.getText() ?? '';
+    if (!fluentNames.has(tagName) || !DIALOG_COMPONENTS.has(tagName)) return;
+
+    for (const attr of node.getDescendantsOfKind(SyntaxKind.JsxAttribute)) {
+      const propName = attr.getFirstChildByKind(SyntaxKind.Identifier)?.getText() ?? '';
+      const line = attr.getStartLineNumber();
+
+      switch (propName) {
+        case 'hidden':
+          results.push({ action: 'auto', codemod: 'dialog-props', payload: 'hidden={expr} → open={!expr}', line });
+          break;
+        case 'isOpen':
+          results.push({ action: 'auto', codemod: 'dialog-props', payload: 'isOpen → open', line });
+          break;
+        case 'onDismiss':
+          results.push({
+            action: 'auto',
+            codemod: 'dialog-props',
+            payload: 'onDismiss → onOpenChange',
+            note: 'signature: (_, { open }) => { if (!open) ... }',
+            line,
+          });
+          break;
+        case 'isBlocking':
+          results.push({ action: 'auto', codemod: 'dialog-props', payload: 'isBlocking=true → modalType="alert"', line });
+          break;
+        case 'dialogContentProps':
+          results.push({
+            action: 'scaffold',
+            codemod: 'dialog-props',
+            payload: 'dialogContentProps → DialogTitle + DialogBody structure',
+            note: 'see references/dialog.md',
+            line,
+          });
+          break;
+      }
+    }
+  });
+
+  return results;
+}
diff --git a/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/enum-to-string.ts b/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/enum-to-string.ts
new file mode 100644
index 00000000000000..af1f5892f3944c
--- /dev/null
+++ b/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/enum-to-string.ts
@@ -0,0 +1,66 @@
+import type { SourceFile, Node } from 'ts-morph';
+import { SyntaxKind } from 'ts-morph';
+import type { AnnotationResult } from '../types';
+
+const KNOWN_ENUM_MEMBERS: Record<string, Record<string, string>> = {
+  MessageBarType: {
+    error: 'error',
+    warning: 'warning',
+    info: 'info',
+    success: 'success',
+    blocked: 'blocked',
+    severeWarning: 'warning',
+  },
+  SpinnerSize: {
+    xSmall: 'extra-small',
+    small: 'small',
+    medium: 'medium',
+    large: 'large',
+  },
+  DialogType: {
+    normal: 'normal',
+    largeHeader: 'normal',
+    close: 'normal',
+  },
+  CheckboxVisibility: {
+    onHover: 'onHover',
+    always: 'always',
+    hidden: 'hidden',
+  },
+};
+
+export function detectEnumToString(sourceFile: SourceFile): AnnotationResult[] {
+  const results: AnnotationResult[] = [];
+
+  sourceFile.forEachDescendant((node: Node) => {
+    if (node.getKind() !== SyntaxKind.PropertyAccessExpression) return;
+
+    const children = node.getChildren();
+    const left = children[0]?.getText() ?? '';
+    const right = children[children.length - 1]?.getText() ?? '';
+
+    if (!KNOWN_ENUM_MEMBERS[left]) return;
+
+    const stringValue = KNOWN_ENUM_MEMBERS[left][right];
+    const line = node.getStartLineNumber();
+
+    if (stringValue) {
+      results.push({
+        action: 'auto',
+        codemod: 'enum-to-string',
+        payload: `${left}.${right} → "${stringValue}"`,
+        line,
+      });
+    } else {
+      results.push({
+        action: 'manual',
+        codemod: 'enum-to-string',
+        payload: `${left}.${right} → unknown member`,
+        note: 'find string equivalent manually',
+        line,
+      });
+    }
+  });
+
+  return results;
+}
diff --git a/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/get-id.ts b/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/get-id.ts
new file mode 100644
index 00000000000000..977d03f8c75194
--- /dev/null
+++ b/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/get-id.ts
@@ -0,0 +1,37 @@
+import type { SourceFile, Node } from 'ts-morph';
+import { SyntaxKind } from 'ts-morph';
+import type { AnnotationResult } from '../types';
+import { isInFunctionComponent } from './use-boolean';
+
+export function detectGetId(sourceFile: SourceFile): AnnotationResult[] {
+  const results: AnnotationResult[] = [];
+
+  const hasGetIdImport = sourceFile.getImportDeclarations().some(
+    decl =>
+      decl.getModuleSpecifierValue() === '@fluentui/react' &&
+      decl.getNamedImports().some(s => s.getName() === 'getId'),
+  );
+  if (!hasGetIdImport) return results;
+
+  sourceFile.forEachDescendant((node: Node) => {
+    if (node.getKind() !== SyntaxKind.CallExpression) return;
+
+    const expr = node.getFirstChild();
+    if (expr?.getText() !== 'getId') return;
+
+    const line = node.getStartLineNumber();
+    const insideComponent = isInFunctionComponent(node);
+
+    results.push({
+      action: insideComponent ? 'auto' : 'manual',
+      codemod: 'get-id',
+      payload: 'getId → useId hook',
+      note: insideComponent
+        ? 'add useId import from @fluentui/react-components'
+        : 'getId outside function component — cannot convert to hook | handle manually',
+      line,
+    });
+  });
+
+  return results;
+}
diff --git a/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/icon-props.ts b/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/icon-props.ts
new file mode 100644
index 00000000000000..6d9ae908a82843
--- /dev/null
+++ b/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/icon-props.ts
@@ -0,0 +1,103 @@
+import type { SourceFile, Node } from 'ts-morph';
+import { SyntaxKind } from 'ts-morph';
+import type { AnnotationResult } from '../types';
+import { getFluentImportNames } from './utils';
+
+// Known icon names that have a direct @fluentui/react-icons equivalent (subset)
+const KNOWN_ICONS = new Set([
+  'Add',
+  'Delete',
+  'Edit',
+  'Search',
+  'Settings',
+  'Filter',
+  'Download',
+  'Upload',
+  'Share',
+  'Copy',
+  'Cancel',
+  'CheckMark',
+  'ChevronDown',
+  'ChevronUp',
+  'ChevronLeft',
+  'ChevronRight',
+  'More',
+  'Save',
+  'Info',
+  'Warning',
+  'Error',
+  'Mail',
+  'Phone',
+  'Calendar',
+  'Home',
+  'Folder',
+  'FolderOpen',
+  'Tag',
+  'Globe',
+  'Lock',
+  'Unlock',
+  'User',
+  'Group',
+  'Refresh',
+  'Close',
+]);
+
+export function detectIconProps(sourceFile: SourceFile): AnnotationResult[] {
+  const results: AnnotationResult[] = [];
+  const fluentNames = getFluentImportNames(sourceFile);
+
+  sourceFile.forEachDescendant((node: Node) => {
+    if (node.getKind() !== SyntaxKind.JsxOpeningElement && node.getKind() !== SyntaxKind.JsxSelfClosingElement) {
+      return;
+    }
+
+    const tagName = node.getFirstChildByKind(SyntaxKind.Identifier)?.getText() ?? '';
+    if (!fluentNames.has(tagName)) return;
+
+    for (const attr of node.getDescendantsOfKind(SyntaxKind.JsxAttribute)) {
+      const propName = attr.getFirstChildByKind(SyntaxKind.Identifier)?.getText() ?? '';
+      if (propName !== 'iconProps') continue;
+
+      const line = attr.getStartLineNumber();
+
+      // Try to extract iconName value
+      const iconNameLiteral = attr
+        .getDescendantsOfKind(SyntaxKind.StringLiteral)
+        .find(s => {
+          const parent = s.getParent();
+          const grandparent = parent?.getParent();
+          return grandparent?.getKind() === SyntaxKind.ObjectLiteralExpression;
+        });
+
+      const iconName = iconNameLiteral?.getLiteralValue();
+
+      if (iconName && KNOWN_ICONS.has(iconName)) {
+        results.push({
+          action: 'auto',
+          codemod: 'icon-props',
+          payload: `iconProps.iconName="${iconName}" → icon={<${iconName}Regular />}`,
+          note: `add import from @fluentui/react-icons`,
+          line,
+        });
+      } else if (iconName) {
+        results.push({
+          action: 'manual',
+          codemod: 'icon-props',
+          payload: `iconProps.iconName="${iconName}" → unknown icon name`,
+          note: 'find SVG in @fluentui/react-icons or replace with custom — see references/icons.md',
+          line,
+        });
+      } else {
+        results.push({
+          action: 'manual',
+          codemod: 'icon-props',
+          payload: 'iconProps → dynamic icon name — cannot resolve statically',
+          note: 'see references/icons.md',
+          line,
+        });
+      }
+    }
+  });
+
+  return results;
+}
diff --git a/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/import-paths.ts b/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/import-paths.ts
new file mode 100644
index 00000000000000..2240d75102783b
--- /dev/null
+++ b/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/import-paths.ts
@@ -0,0 +1,58 @@
+import type { SourceFile } from 'ts-morph';
+import type { AnnotationResult } from '../types';
+
+// Components with no v9 equivalent — annotated as no-equivalent instead of auto
+const NO_EQUIVALENT = new Set([
+  'ActivityItem',
+  'MarqueeSelection',
+  'HoverCard',
+  'ResizeGroup',
+  'ScrollablePane',
+  'Announced',
+]);
+
+export function detectImportPaths(sourceFile: SourceFile): AnnotationResult[] {
+  const results: AnnotationResult[] = [];
+
+  for (const decl of sourceFile.getImportDeclarations()) {
+    if (decl.getModuleSpecifierValue() !== '@fluentui/react') {
+      continue;
+    }
+
+    const namedImports = decl.getNamedImports();
+    const line = decl.getStartLineNumber();
+
+    // Side-effect import: import '@fluentui/react'
+    if (namedImports.length === 0 && !decl.getDefaultImport() && !decl.getNamespaceImport()) {
+      results.push({
+        action: 'auto',
+        codemod: 'import-paths',
+        payload: '@fluentui/react → remove (side-effect import)',
+        line,
+      });
+      continue;
+    }
+
+    const noEquivSpecifiers = namedImports.filter(s => NO_EQUIVALENT.has(s.getName()));
+    for (const specifier of noEquivSpecifiers) {
+      results.push({
+        action: 'no-equivalent',
+        codemod: 'import-paths',
+        payload: `${specifier.getName()} — no v9 equivalent`,
+        line,
+      });
+    }
+
+    const hasEquivSpecifiers = namedImports.some(s => !NO_EQUIVALENT.has(s.getName()));
+    if (hasEquivSpecifiers) {
+      results.push({
+        action: 'auto',
+        codemod: 'import-paths',
+        payload: '@fluentui/react → @fluentui/react-components',
+        line,
+      });
+    }
+  }
+
+  return results;
+}
diff --git a/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/keycodes.ts b/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/keycodes.ts
new file mode 100644
index 00000000000000..05d4a1e8d81511
--- /dev/null
+++ b/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/keycodes.ts
@@ -0,0 +1,66 @@
+import type { SourceFile, Node } from 'ts-morph';
+import { SyntaxKind } from 'ts-morph';
+import type { AnnotationResult } from '../types';
+
+const KNOWN_KEYCODES: Record<string, string> = {
+  enter: 'Enter',
+  escape: 'Escape',
+  tab: 'Tab',
+  space: ' ',
+  backspace: 'Backspace',
+  del: 'Delete',
+  up: 'ArrowUp',
+  down: 'ArrowDown',
+  left: 'ArrowLeft',
+  right: 'ArrowRight',
+  home: 'Home',
+  end: 'End',
+  pageUp: 'PageUp',
+  pageDown: 'PageDown',
+  f1: 'F1',
+  f2: 'F2',
+};
+
+export function detectKeyCodes(sourceFile: SourceFile): AnnotationResult[] {
+  const results: AnnotationResult[] = [];
+
+  const hasKeyCodesImport = sourceFile.getImportDeclarations().some(
+    decl =>
+      decl.getModuleSpecifierValue() === '@fluentui/react' &&
+      decl.getNamedImports().some(s => s.getName() === 'KeyCodes'),
+  );
+  if (!hasKeyCodesImport) return results;
+
+  sourceFile.forEachDescendant((node: Node) => {
+    if (node.getKind() !== SyntaxKind.PropertyAccessExpression) return;
+
+    const children = node.getChildren();
+    const left = children[0]?.getText() ?? '';
+    const right = children[children.length - 1]?.getText() ?? '';
+
+    if (left !== 'KeyCodes') return;
+
+    const line = node.getStartLineNumber();
+    const keyValue = KNOWN_KEYCODES[right];
+
+    if (keyValue) {
+      results.push({
+        action: 'auto',
+        codemod: 'keycodes',
+        payload: `KeyCodes.${right} → '${keyValue}'`,
+        note: 'rewrite event.which/keyCode → event.key',
+        line,
+      });
+    } else {
+      results.push({
+        action: 'manual',
+        codemod: 'keycodes',
+        payload: `KeyCodes.${right} → unknown key code`,
+        note: 'find KeyboardEvent.key equivalent manually',
+        line,
+      });
+    }
+  });
+
+  return results;
+}
diff --git a/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/label-extraction.ts b/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/label-extraction.ts
new file mode 100644
index 00000000000000..80e7a5a01364be
--- /dev/null
+++ b/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/label-extraction.ts
@@ -0,0 +1,48 @@
+import type { SourceFile, Node } from 'ts-morph';
+import { SyntaxKind } from 'ts-morph';
+import type { AnnotationResult } from '../types';
+import { getFluentImportNames } from './utils';
+
+const LABEL_COMPONENTS = new Set(['TextField', 'SpinButton', 'Slider', 'ChoiceGroup']);
+
+export function detectLabelExtraction(sourceFile: SourceFile): AnnotationResult[] {
+  const results: AnnotationResult[] = [];
+  const fluentNames = getFluentImportNames(sourceFile);
+
+  sourceFile.forEachDescendant((node: Node) => {
+    if (node.getKind() !== SyntaxKind.JsxOpeningElement && node.getKind() !== SyntaxKind.JsxSelfClosingElement) {
+      return;
+    }
+
+    const tagName = node.getFirstChildByKind(SyntaxKind.Identifier)?.getText() ?? '';
+    if (!fluentNames.has(tagName) || !LABEL_COMPONENTS.has(tagName)) return;
+
+    for (const attr of node.getDescendantsOfKind(SyntaxKind.JsxAttribute)) {
+      const propName = attr.getFirstChildByKind(SyntaxKind.Identifier)?.getText() ?? '';
+      const line = attr.getStartLineNumber();
+
+      switch (propName) {
+        case 'label':
+          results.push({
+            action: 'scaffold',
+            codemod: 'label-extraction',
+            payload: `${tagName}.label → <Field label="..."><${tagName === 'TextField' ? 'Input' : tagName} /></Field>`,
+            note: 'also move: required, errorMessage→validationMessage, description→hint',
+            line,
+          });
+          break;
+        case 'onRenderLabel':
+          results.push({
+            action: 'manual',
+            codemod: 'label-extraction',
+            payload: `${tagName}.onRenderLabel → custom label slot`,
+            note: 'inspect render callback and convert to slot',
+            line,
+          });
+          break;
+      }
+    }
+  });
+
+  return results;
+}
diff --git a/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/no-equivalent.ts b/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/no-equivalent.ts
new file mode 100644
index 00000000000000..c0b242f7983093
--- /dev/null
+++ b/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/no-equivalent.ts
@@ -0,0 +1,37 @@
+import type { SourceFile, Node } from 'ts-morph';
+import { SyntaxKind } from 'ts-morph';
+import type { AnnotationResult } from '../types';
+import { getFluentImportNames, isJsxChild } from './utils';
+
+const DEPRECATED_COMPONENTS: Record<string, string> = {
+  ActivityItem: 'build with Avatar + Text + makeStyles flexbox — see SKILL.md deprecation list',
+  MarqueeSelection: 'use browser selection APIs or custom drag-select implementation',
+  HoverCard: 'use <Popover> with onMouseEnter/onMouseLeave on the trigger',
+  ResizeGroup: 'use Overflow component (<Overflow> + <OverflowItem>)',
+  ScrollablePane: 'use overflow: auto on a CSS container + position: sticky for sticky headers',
+  Announced: 'use a visually-hidden live region: <div role="status" aria-live="polite">',
+};
+
+export function detectNoEquivalent(sourceFile: SourceFile): AnnotationResult[] {
+  const results: AnnotationResult[] = [];
+  const fluentNames = getFluentImportNames(sourceFile);
+
+  sourceFile.forEachDescendant((node: Node) => {
+    if (node.getKind() !== SyntaxKind.JsxOpeningElement && node.getKind() !== SyntaxKind.JsxSelfClosingElement) {
+      return;
+    }
+
+    const tagName = node.getFirstChildByKind(SyntaxKind.Identifier)?.getText() ?? '';
+    if (!fluentNames.has(tagName) || !DEPRECATED_COMPONENTS[tagName]) return;
+
+    results.push({
+      action: 'no-equivalent',
+      codemod: 'no-equivalent',
+      payload: `${tagName} | ${DEPRECATED_COMPONENTS[tagName]}`,
+      line: node.getStartLineNumber(),
+      insideJsx: isJsxChild(node),
+    });
+  });
+
+  return results;
+}
diff --git a/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/progress-bar-props.ts b/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/progress-bar-props.ts
new file mode 100644
index 00000000000000..5c9facb56f45f3
--- /dev/null
+++ b/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/progress-bar-props.ts
@@ -0,0 +1,40 @@
+import type { SourceFile, Node } from 'ts-morph';
+import { SyntaxKind } from 'ts-morph';
+import type { AnnotationResult } from '../types';
+import { getFluentImportNames } from './utils';
+
+export function detectProgressBarProps(sourceFile: SourceFile): AnnotationResult[] {
+  const results: AnnotationResult[] = [];
+  const fluentNames = getFluentImportNames(sourceFile);
+
+  sourceFile.forEachDescendant((node: Node) => {
+    if (node.getKind() !== SyntaxKind.JsxOpeningElement && node.getKind() !== SyntaxKind.JsxSelfClosingElement) {
+      return;
+    }
+
+    const tagName = node.getFirstChildByKind(SyntaxKind.Identifier)?.getText() ?? '';
+    if (!fluentNames.has(tagName) || tagName !== 'ProgressIndicator') return;
+
+    for (const attr of node.getDescendantsOfKind(SyntaxKind.JsxAttribute)) {
+      const propName = attr.getFirstChildByKind(SyntaxKind.Identifier)?.getText() ?? '';
+      const line = attr.getStartLineNumber();
+
+      switch (propName) {
+        case 'percentComplete':
+          results.push({ action: 'auto', codemod: 'progress-bar-props', payload: 'percentComplete → value', line });
+          break;
+        case 'label':
+          results.push({
+            action: 'auto',
+            codemod: 'progress-bar-props',
+            payload: 'label → Field wrapper',
+            note: 'see label-extraction',
+            line,
+          });
+          break;
+      }
+    }
+  });
+
+  return results;
+}
diff --git a/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/prop-rename.ts b/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/prop-rename.ts
new file mode 100644
index 00000000000000..0313f18880a43b
--- /dev/null
+++ b/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/prop-rename.ts
@@ -0,0 +1,42 @@
+import type { SourceFile, Node } from 'ts-morph';
+import { SyntaxKind } from 'ts-morph';
+import type { AnnotationResult } from '../types';
+import { getFluentImportNames } from './utils';
+
+const PROP_RENAMES: Record<string, string> = {
+  ariaLabel: 'aria-label',
+  ariaHidden: 'aria-hidden',
+  ariaDescribedBy: 'aria-describedby',
+  ariaLabelledBy: 'aria-labelledby',
+  ariaPositionInSet: 'aria-posinset',
+  ariaSetSize: 'aria-setsize',
+  componentRef: 'ref',
+};
+
+export function detectPropRenames(sourceFile: SourceFile): AnnotationResult[] {
+  const results: AnnotationResult[] = [];
+  const fluentNames = getFluentImportNames(sourceFile);
+
+  sourceFile.forEachDescendant((node: Node) => {
+    if (node.getKind() !== SyntaxKind.JsxOpeningElement && node.getKind() !== SyntaxKind.JsxSelfClosingElement) {
+      return;
+    }
+
+    const tagName = node.getFirstChildByKind(SyntaxKind.Identifier)?.getText() ?? '';
+    if (!fluentNames.has(tagName)) return;
+
+    for (const attr of node.getDescendantsOfKind(SyntaxKind.JsxAttribute)) {
+      const propName = attr.getFirstChildByKind(SyntaxKind.Identifier)?.getText() ?? '';
+      if (PROP_RENAMES[propName]) {
+        results.push({
+          action: 'auto',
+          codemod: 'prop-rename',
+          payload: `${propName} → ${PROP_RENAMES[propName]}`,
+          line: attr.getStartLineNumber(),
+        });
+      }
+    }
+  });
+
+  return results;
+}
diff --git a/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/remove-theme-prop.ts b/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/remove-theme-prop.ts
new file mode 100644
index 00000000000000..879eaa487a8861
--- /dev/null
+++ b/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/remove-theme-prop.ts
@@ -0,0 +1,39 @@
+import type { SourceFile, Node } from 'ts-morph';
+import { SyntaxKind } from 'ts-morph';
+import type { AnnotationResult } from '../types';
+import { getFluentImportNames } from './utils';
+
+export function detectRemoveThemeProp(sourceFile: SourceFile): AnnotationResult[] {
+  const results: AnnotationResult[] = [];
+  const fluentNames = getFluentImportNames(sourceFile);
+
+  sourceFile.forEachDescendant((node: Node) => {
+    if (node.getKind() !== SyntaxKind.JsxOpeningElement && node.getKind() !== SyntaxKind.JsxSelfClosingElement) {
+      return;
+    }
+
+    const tagName = node.getFirstChildByKind(SyntaxKind.Identifier)?.getText() ?? '';
+    if (!fluentNames.has(tagName)) return;
+
+    for (const attr of node.getDescendantsOfKind(SyntaxKind.JsxAttribute)) {
+      const propName = attr.getFirstChildByKind(SyntaxKind.Identifier)?.getText() ?? '';
+      if (propName !== 'theme') continue;
+
+      // Non-trivial: value is an expression that isn't a bare identifier
+      const initializer = attr.getInitializer();
+      const isNonTrivial =
+        initializer?.getKind() === SyntaxKind.JsxExpression &&
+        initializer.getFirstChildByKind(SyntaxKind.Identifier) === undefined;
+
+      results.push({
+        action: 'auto',
+        codemod: 'remove-theme-prop',
+        payload: 'theme prop removed — handled by FluentProvider',
+        note: isNonTrivial ? 'warn: nested FluentProvider may be needed' : undefined,
+        line: attr.getStartLineNumber(),
+      });
+    }
+  });
+
+  return results;
+}
diff --git a/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/styles-prop.ts b/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/styles-prop.ts
new file mode 100644
index 00000000000000..deddc73a551066
--- /dev/null
+++ b/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/styles-prop.ts
@@ -0,0 +1,33 @@
+import type { SourceFile, Node } from 'ts-morph';
+import { SyntaxKind } from 'ts-morph';
+import type { AnnotationResult } from '../types';
+import { getFluentImportNames } from './utils';
+
+export function detectStylesProp(sourceFile: SourceFile): AnnotationResult[] {
+  const results: AnnotationResult[] = [];
+  const fluentNames = getFluentImportNames(sourceFile);
+
+  sourceFile.forEachDescendant((node: Node) => {
+    if (node.getKind() !== SyntaxKind.JsxOpeningElement && node.getKind() !== SyntaxKind.JsxSelfClosingElement) {
+      return;
+    }
+
+    const tagName = node.getFirstChildByKind(SyntaxKind.Identifier)?.getText() ?? '';
+    if (!fluentNames.has(tagName)) return;
+
+    for (const attr of node.getDescendantsOfKind(SyntaxKind.JsxAttribute)) {
+      const propName = attr.getFirstChildByKind(SyntaxKind.Identifier)?.getText() ?? '';
+      if (propName !== 'styles') continue;
+
+      results.push({
+        action: 'scaffold',
+        codemod: 'styles-prop',
+        payload: `${tagName}.styles → makeStyles skeleton`,
+        note: 'translate values manually using tokens — see references/theme.md',
+        line: attr.getStartLineNumber(),
+      });
+    }
+  });
+
+  return results;
+}
diff --git a/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/toggle-props.ts b/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/toggle-props.ts
new file mode 100644
index 00000000000000..a6948179dd6037
--- /dev/null
+++ b/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/toggle-props.ts
@@ -0,0 +1,53 @@
+import type { SourceFile, Node } from 'ts-morph';
+import { SyntaxKind } from 'ts-morph';
+import type { AnnotationResult } from '../types';
+import { getFluentImportNames } from './utils';
+
+export function detectToggleProps(sourceFile: SourceFile): AnnotationResult[] {
+  const results: AnnotationResult[] = [];
+  const fluentNames = getFluentImportNames(sourceFile);
+
+  sourceFile.forEachDescendant((node: Node) => {
+    if (node.getKind() !== SyntaxKind.JsxOpeningElement && node.getKind() !== SyntaxKind.JsxSelfClosingElement) {
+      return;
+    }
+
+    const tagName = node.getFirstChildByKind(SyntaxKind.Identifier)?.getText() ?? '';
+    if (!fluentNames.has(tagName) || tagName !== 'Toggle') return;
+
+    for (const attr of node.getDescendantsOfKind(SyntaxKind.JsxAttribute)) {
+      const propName = attr.getFirstChildByKind(SyntaxKind.Identifier)?.getText() ?? '';
+      const line = attr.getStartLineNumber();
+
+      switch (propName) {
+        case 'inlineLabel':
+          results.push({
+            action: 'auto',
+            codemod: 'toggle-props',
+            payload: 'inlineLabel → labelPosition="before"',
+            line,
+          });
+          break;
+        case 'onChange':
+          results.push({
+            action: 'auto',
+            codemod: 'toggle-props',
+            payload: 'onChange signature | (_, checked) → (_, { checked })',
+            line,
+          });
+          break;
+        case 'onText':
+        case 'offText':
+          results.push({
+            action: 'no-equivalent',
+            codemod: 'toggle-props',
+            payload: `${propName} | v9 Switch has no on/off labels — remove or build custom wrapper`,
+            line,
+          });
+          break;
+      }
+    }
+  });
+
+  return results;
+}
diff --git a/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/use-boolean.ts b/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/use-boolean.ts
new file mode 100644
index 00000000000000..c3a883124cfa30
--- /dev/null
+++ b/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/use-boolean.ts
@@ -0,0 +1,54 @@
+import type { SourceFile, Node } from 'ts-morph';
+import { SyntaxKind } from 'ts-morph';
+import type { AnnotationResult } from '../types';
+
+export function detectUseBoolean(sourceFile: SourceFile): AnnotationResult[] {
+  const results: AnnotationResult[] = [];
+
+  // Check if useBoolean is imported from @fluentui/react
+  const hasUseBooleanImport = sourceFile.getImportDeclarations().some(
+    decl =>
+      decl.getModuleSpecifierValue() === '@fluentui/react' &&
+      decl.getNamedImports().some(s => s.getName() === 'useBoolean'),
+  );
+  if (!hasUseBooleanImport) return results;
+
+  sourceFile.forEachDescendant((node: Node) => {
+    if (node.getKind() !== SyntaxKind.CallExpression) return;
+
+    const expr = node.getFirstChild();
+    if (expr?.getText() !== 'useBoolean') return;
+
+    const line = node.getStartLineNumber();
+
+    // Check if we're inside a function component (parent chain has a function/arrow function)
+    const isInsideFunctionComponent = isInFunctionComponent(node);
+
+    results.push({
+      action: isInsideFunctionComponent ? 'auto' : 'manual',
+      codemod: 'use-boolean',
+      payload: 'useBoolean → useState + named helpers',
+      note: isInsideFunctionComponent
+        ? undefined
+        : 'useBoolean outside function component — cannot convert to hook | handle manually',
+      line,
+    });
+  });
+
+  return results;
+}
+
+export function isInFunctionComponent(node: Node): boolean {
+  let current: Node | undefined = node.getParent();
+  while (current) {
+    const kind = current.getKind();
+    if (kind === SyntaxKind.ArrowFunction || kind === SyntaxKind.FunctionDeclaration || kind === SyntaxKind.FunctionExpression) {
+      return true;
+    }
+    if (kind === SyntaxKind.ClassDeclaration || kind === SyntaxKind.ClassExpression) {
+      return false;
+    }
+    current = current.getParent();
+  }
+  return false;
+}
diff --git a/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/utils.ts b/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/utils.ts
new file mode 100644
index 00000000000000..0d302c503eab51
--- /dev/null
+++ b/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/utils.ts
@@ -0,0 +1,36 @@
+import type { SourceFile, Node } from 'ts-morph';
+import { SyntaxKind } from 'ts-morph';
+
+/**
+ * Returns the set of names imported from @fluentui/react in a source file.
+ * Used by rules to avoid false positives on custom components with the same name.
+ */
+export function getFluentImportNames(sourceFile: SourceFile): Set<string> {
+  const names = new Set<string>();
+  for (const decl of sourceFile.getImportDeclarations()) {
+    if (decl.getModuleSpecifierValue() === '@fluentui/react') {
+      for (const named of decl.getNamedImports()) {
+        names.add(named.getAliasNode()?.getText() ?? named.getName());
+      }
+    }
+  }
+  return names;
+}
+
+/**
+ * Returns true when a JsxOpeningElement or JsxSelfClosingElement is a direct
+ * child of another JSX element (i.e. lives inside JSX children, not at the
+ * root of an expression).  The writer uses this to emit block-comment syntax
+ * instead of a line comment, since // inside JSX children is rendered as text.
+ */
+export function isJsxChild(node: Node): boolean {
+  if (node.getKind() === SyntaxKind.JsxOpeningElement) {
+    // JsxOpeningElement → parent JsxElement → grandparent must be another JsxElement
+    return node.getParent()?.getParent()?.getKind() === SyntaxKind.JsxElement;
+  }
+  if (node.getKind() === SyntaxKind.JsxSelfClosingElement) {
+    // JsxSelfClosingElement is a direct child — its parent is the containing JsxElement
+    return node.getParent()?.getKind() === SyntaxKind.JsxElement;
+  }
+  return false;
+}
diff --git a/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/types.ts b/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/types.ts
new file mode 100644
index 00000000000000..c48dc6f1bc5142
--- /dev/null
+++ b/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/types.ts
@@ -0,0 +1,34 @@
+import type { SourceFile } from 'ts-morph';
+
+export type AnnotationAction = 'auto' | 'scaffold' | 'manual' | 'no-equivalent';
+
+export interface Annotation {
+  action: AnnotationAction;
+  codemod: string;
+  payload: string;
+  note?: string;
+}
+
+/** Location-aware annotation produced by the detection engine. */
+export interface AnnotationResult extends Annotation {
+  /** 1-based line number in source; annotation comment goes on the line above. */
+  line: number;
+  /**
+   * True when the annotated node is a JSX child element (inside another JSX element).
+   * The writer emits JSX block comment syntax instead of a line comment to avoid
+   * creating invalid JSX text nodes.
+   */
+  insideJsx?: boolean;
+}
+
+/** Per-file output of analyzeFiles(). */
+export interface FileAnalysis {
+  filePath: string;
+  annotations: AnnotationResult[];
+  missingDeps: Array<{ name: string; reason: string }>;
+}
+
+export interface AnnotationRule {
+  name: string;
+  detect(sourceFile: SourceFile): AnnotationResult[];
+}
diff --git a/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/writer.ts b/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/writer.ts
new file mode 100644
index 00000000000000..cba70b4334ea72
--- /dev/null
+++ b/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/writer.ts
@@ -0,0 +1,53 @@
+import * as fs from 'fs/promises';
+import type { FileAnalysis, AnnotationResult } from './types';
+
+const ANNOTATION_TAG = '@fluent-migrate:';
+
+function formatAnnotation(a: AnnotationResult): string {
+  const parts = [a.action, a.codemod, a.payload];
+  if (a.note) parts.push(a.note);
+  const body = `${ANNOTATION_TAG}${parts.join(' | ')}`;
+  return a.insideJsx ? `{/* ${body} */}` : `// ${body}`;
+}
+
+/**
+ * Inserts @fluent-migrate: comments into source files based on FileAnalysis results.
+ * Idempotent: skips if an identical comment already exists on the line above the target.
+ */
+export async function writeAnnotations(results: FileAnalysis[]): Promise<{ filesChanged: number }> {
+  let filesChanged = 0;
+
+  for (const file of results) {
+    if (file.annotations.length === 0) continue;
+
+    const content = await fs.readFile(file.filePath, 'utf8');
+    const lines = content.split('\n');
+
+    // Sort annotations by line descending so insertions don't shift line numbers
+    const sorted = [...file.annotations].sort((a, b) => b.line - a.line);
+
+    let changed = false;
+
+    for (const annotation of sorted) {
+      const targetLine = annotation.line - 1; // convert to 0-based
+      const comment = formatAnnotation(annotation);
+
+      // Check if an identical annotation already exists on the line above (trimmed to ignore indent)
+      const lineAbove = lines[targetLine - 1]?.trim();
+      if (lineAbove === comment.trim()) continue;
+
+      // Determine indentation from the target line
+      const indent = lines[targetLine]?.match(/^(\s*)/)?.[1] ?? '';
+
+      lines.splice(targetLine, 0, `${indent}${comment}`);
+      changed = true;
+    }
+
+    if (changed) {
+      await fs.writeFile(file.filePath, lines.join('\n'), 'utf8');
+      filesChanged++;
+    }
+  }
+
+  return { filesChanged };
+}

From 2d3ed69984a0323be1ecc72f934a33143cb085a6 Mon Sep 17 00:00:00 2001
From: Dmytro Kirpa <dmytrokirpa@microsoft.com>
Date: Wed, 4 Mar 2026 18:47:55 +0100
Subject: [PATCH 3/6] update lockfile

---
 yarn.lock | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/yarn.lock b/yarn.lock
index e15f5e169d7c08..57457af98a8b8c 100644
--- a/yarn.lock
+++ b/yarn.lock
@@ -10093,7 +10093,7 @@ fast-fifo@^1.2.0, fast-fifo@^1.3.2:
   resolved "https://registry.yarnpkg.com/fast-fifo/-/fast-fifo-1.3.2.tgz#286e31de96eb96d38a97899815740ba2a4f3640c"
   integrity sha512-/d9sfos4yxzpwkDkuN7k2SqFKtYNmCTzgfEpz82x34IM9/zc8KGxQoXg1liNC/izpRM/MBdt44Nmx41ZWqk+FQ==
 
-fast-glob@^3.0.3, fast-glob@^3.1.1, fast-glob@^3.2.5, fast-glob@^3.2.9, fast-glob@^3.3.2:
+fast-glob@^3.0.3, fast-glob@^3.1.1, fast-glob@^3.2.5, fast-glob@^3.2.9, fast-glob@^3.3.2, fast-glob@^3.3.3:
   version "3.3.3"
   resolved "https://registry.yarnpkg.com/fast-glob/-/fast-glob-3.3.3.tgz#d06d585ce8dba90a16b0505c543c3ccfb3aeb818"
   integrity sha512-7MptL8U0cqcFdzIzwOTHoilX9x5BrNqye7Z/LuC7kCMRio1EMSyqRK3BEAUD7sXRq4iT4AzTVuZdhgQ2TCvYLg==

From 459af9d058d040a01a444360531c7e6dd87604e7 Mon Sep 17 00:00:00 2001
From: Dmytro Kirpa <dmytrokirpa@microsoft.com>
Date: Wed, 4 Mar 2026 21:08:45 +0100
Subject: [PATCH 4/6] fix formatting issues

---
 tools/cli/src/commands/migrate/index.ts        |  6 +-----
 .../utils/annotator/rules/dialog-props.ts      |  7 ++++++-
 .../v8-to-v9/utils/annotator/rules/get-id.ts   | 12 +++++++-----
 .../utils/annotator/rules/icon-props.ts        | 12 +++++-------
 .../v8-to-v9/utils/annotator/rules/keycodes.ts | 12 +++++++-----
 .../utils/annotator/rules/use-boolean.ts       | 18 ++++++++++++------
 6 files changed, 38 insertions(+), 29 deletions(-)

diff --git a/tools/cli/src/commands/migrate/index.ts b/tools/cli/src/commands/migrate/index.ts
index 3c0315830251e5..9f96301460db54 100644
--- a/tools/cli/src/commands/migrate/index.ts
+++ b/tools/cli/src/commands/migrate/index.ts
@@ -5,11 +5,7 @@ const command: CommandModule = {
   command: 'migrate <migration>',
   describe: 'Run migration analysis and annotation',
   builder: yargs =>
-    yargs
-      .command(v8ToV9Command)
-      .demandCommand(1, 'Specify a migration type: v8-to-v9')
-      .version(false)
-      .help(),
+    yargs.command(v8ToV9Command).demandCommand(1, 'Specify a migration type: v8-to-v9').version(false).help(),
   handler: () => {},
 };
 
diff --git a/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/dialog-props.ts b/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/dialog-props.ts
index ad805258f965ef..fb613971a1484d 100644
--- a/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/dialog-props.ts
+++ b/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/dialog-props.ts
@@ -38,7 +38,12 @@ export function detectDialogProps(sourceFile: SourceFile): AnnotationResult[] {
           });
           break;
         case 'isBlocking':
-          results.push({ action: 'auto', codemod: 'dialog-props', payload: 'isBlocking=true → modalType="alert"', line });
+          results.push({
+            action: 'auto',
+            codemod: 'dialog-props',
+            payload: 'isBlocking=true → modalType="alert"',
+            line,
+          });
           break;
         case 'dialogContentProps':
           results.push({
diff --git a/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/get-id.ts b/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/get-id.ts
index 977d03f8c75194..765906552822f1 100644
--- a/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/get-id.ts
+++ b/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/get-id.ts
@@ -6,11 +6,13 @@ import { isInFunctionComponent } from './use-boolean';
 export function detectGetId(sourceFile: SourceFile): AnnotationResult[] {
   const results: AnnotationResult[] = [];
 
-  const hasGetIdImport = sourceFile.getImportDeclarations().some(
-    decl =>
-      decl.getModuleSpecifierValue() === '@fluentui/react' &&
-      decl.getNamedImports().some(s => s.getName() === 'getId'),
-  );
+  const hasGetIdImport = sourceFile
+    .getImportDeclarations()
+    .some(
+      decl =>
+        decl.getModuleSpecifierValue() === '@fluentui/react' &&
+        decl.getNamedImports().some(s => s.getName() === 'getId'),
+    );
   if (!hasGetIdImport) return results;
 
   sourceFile.forEachDescendant((node: Node) => {
diff --git a/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/icon-props.ts b/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/icon-props.ts
index 6d9ae908a82843..05ca3ccfee669c 100644
--- a/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/icon-props.ts
+++ b/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/icon-props.ts
@@ -61,13 +61,11 @@ export function detectIconProps(sourceFile: SourceFile): AnnotationResult[] {
       const line = attr.getStartLineNumber();
 
       // Try to extract iconName value
-      const iconNameLiteral = attr
-        .getDescendantsOfKind(SyntaxKind.StringLiteral)
-        .find(s => {
-          const parent = s.getParent();
-          const grandparent = parent?.getParent();
-          return grandparent?.getKind() === SyntaxKind.ObjectLiteralExpression;
-        });
+      const iconNameLiteral = attr.getDescendantsOfKind(SyntaxKind.StringLiteral).find(s => {
+        const parent = s.getParent();
+        const grandparent = parent?.getParent();
+        return grandparent?.getKind() === SyntaxKind.ObjectLiteralExpression;
+      });
 
       const iconName = iconNameLiteral?.getLiteralValue();
 
diff --git a/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/keycodes.ts b/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/keycodes.ts
index 05d4a1e8d81511..17cc8cbd3f92d0 100644
--- a/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/keycodes.ts
+++ b/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/keycodes.ts
@@ -24,11 +24,13 @@ const KNOWN_KEYCODES: Record<string, string> = {
 export function detectKeyCodes(sourceFile: SourceFile): AnnotationResult[] {
   const results: AnnotationResult[] = [];
 
-  const hasKeyCodesImport = sourceFile.getImportDeclarations().some(
-    decl =>
-      decl.getModuleSpecifierValue() === '@fluentui/react' &&
-      decl.getNamedImports().some(s => s.getName() === 'KeyCodes'),
-  );
+  const hasKeyCodesImport = sourceFile
+    .getImportDeclarations()
+    .some(
+      decl =>
+        decl.getModuleSpecifierValue() === '@fluentui/react' &&
+        decl.getNamedImports().some(s => s.getName() === 'KeyCodes'),
+    );
   if (!hasKeyCodesImport) return results;
 
   sourceFile.forEachDescendant((node: Node) => {
diff --git a/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/use-boolean.ts b/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/use-boolean.ts
index c3a883124cfa30..436e092658d83d 100644
--- a/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/use-boolean.ts
+++ b/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/use-boolean.ts
@@ -6,11 +6,13 @@ export function detectUseBoolean(sourceFile: SourceFile): AnnotationResult[] {
   const results: AnnotationResult[] = [];
 
   // Check if useBoolean is imported from @fluentui/react
-  const hasUseBooleanImport = sourceFile.getImportDeclarations().some(
-    decl =>
-      decl.getModuleSpecifierValue() === '@fluentui/react' &&
-      decl.getNamedImports().some(s => s.getName() === 'useBoolean'),
-  );
+  const hasUseBooleanImport = sourceFile
+    .getImportDeclarations()
+    .some(
+      decl =>
+        decl.getModuleSpecifierValue() === '@fluentui/react' &&
+        decl.getNamedImports().some(s => s.getName() === 'useBoolean'),
+    );
   if (!hasUseBooleanImport) return results;
 
   sourceFile.forEachDescendant((node: Node) => {
@@ -42,7 +44,11 @@ export function isInFunctionComponent(node: Node): boolean {
   let current: Node | undefined = node.getParent();
   while (current) {
     const kind = current.getKind();
-    if (kind === SyntaxKind.ArrowFunction || kind === SyntaxKind.FunctionDeclaration || kind === SyntaxKind.FunctionExpression) {
+    if (
+      kind === SyntaxKind.ArrowFunction ||
+      kind === SyntaxKind.FunctionDeclaration ||
+      kind === SyntaxKind.FunctionExpression
+    ) {
       return true;
     }
     if (kind === SyntaxKind.ClassDeclaration || kind === SyntaxKind.ClassExpression) {

From 18e42708af74cb11d00bbf5522f440e34747f608 Mon Sep 17 00:00:00 2001
From: Dmytro Kirpa <dmytrokirpa@microsoft.com>
Date: Thu, 5 Mar 2026 14:34:28 +0100
Subject: [PATCH 5/6] review comments

---
 skills/fluentui-migrate-v8-to-v9/SKILL.md     |  77 +++++++------
 .../references/avatargroup.md                 |   6 +-
 .../references/breadcrumb.md                  |   8 +-
 .../references/button.md                      |  54 ++++++---
 .../references/callout.md                     |   6 +-
 .../references/card.md                        |   8 +-
 .../references/checkbox.md                    |  16 ++-
 .../references/colorpicker.md                 |   8 +-
 .../references/datagrid.md                    |   6 +-
 .../references/dialog.md                      |   8 +-
 .../references/drawer.md                      |   6 +-
 .../references/image.md                       |   8 +-
 .../references/input.md                       |  28 +++--
 .../references/keytips.md                     |   8 +-
 .../references/label.md                       |   8 +-
 .../references/link.md                        |   8 +-
 .../references/list.md                        |   8 +-
 .../references/menu.md                        |   6 +-
 .../references/messagebar.md                  |   6 +-
 .../references/nav.md                         |   8 +-
 .../references/overflow.md                    |   8 +-
 .../references/persona.md                     |   8 +-
 .../references/progressbar.md                 |  20 +++-
 .../references/radiogroup.md                  |  24 +++-
 .../references/rating.md                      |   8 +-
 .../references/searchbox.md                   |   8 +-
 .../references/separator.md                   |   8 +-
 .../references/skeleton.md                    |   8 +-
 .../references/slider.md                      |  28 +++--
 .../references/spinner.md                     |   6 +-
 .../references/swatchpicker.md                |   8 +-
 .../references/switch.md                      |   8 +-
 .../references/tabs.md                        |   6 +-
 .../references/teachingpopover.md             |   8 +-
 .../references/text.md                        |   8 +-
 .../references/textarea.md                    |   8 +-
 .../references/toolbar.md                     |   6 +-
 .../references/tooltip.md                     |   6 +-
 tools/cli/eslint.config.cjs                   |   8 +-
 tools/cli/src/commands/migrate/index.ts       |  32 +++++-
 .../__tests__/handler.integration.spec.ts     |  53 +++++++--
 .../v8-to-v9/__tests__/handler.spec.ts        |  10 +-
 .../src/commands/migrate/v8-to-v9/handler.ts  |  22 ++--
 .../src/commands/migrate/v8-to-v9/index.ts    |   2 +-
 .../v8-to-v9/utils/annotator/analyzer.ts      | 103 ++++++++++++++++++
 .../migrate/v8-to-v9/utils/annotator/index.ts |  99 +----------------
 .../utils/annotator/rules/button-variants.ts  |   9 +-
 .../utils/annotator/rules/component-rename.ts |   9 +-
 .../utils/annotator/rules/dialog-props.ts     |   8 +-
 .../utils/annotator/rules/enum-to-string.ts   |   8 +-
 .../v8-to-v9/utils/annotator/rules/get-id.ts  |  12 +-
 .../utils/annotator/rules/icon-props.ts       |  12 +-
 .../utils/annotator/rules/keycodes.ts         |  12 +-
 .../utils/annotator/rules/label-extraction.ts |   8 +-
 .../utils/annotator/rules/no-equivalent.ts    |   9 +-
 .../annotator/rules/progress-bar-props.ts     |   8 +-
 .../utils/annotator/rules/prop-rename.ts      |   8 +-
 .../annotator/rules/remove-theme-prop.ts      |  12 +-
 .../utils/annotator/rules/styles-prop.ts      |  12 +-
 .../utils/annotator/rules/toggle-props.ts     |   8 +-
 .../utils/annotator/rules/use-boolean.ts      |  12 +-
 .../v8-to-v9/utils/annotator/writer.ts        |  36 +++++-
 62 files changed, 648 insertions(+), 339 deletions(-)
 create mode 100644 tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/analyzer.ts

diff --git a/skills/fluentui-migrate-v8-to-v9/SKILL.md b/skills/fluentui-migrate-v8-to-v9/SKILL.md
index f9659ba3c3c14f..b04acd8ea4157b 100644
--- a/skills/fluentui-migrate-v8-to-v9/SKILL.md
+++ b/skills/fluentui-migrate-v8-to-v9/SKILL.md
@@ -12,18 +12,18 @@ After completing a migration session, report using this structure:
 ```
 ### Migration Report
 
-**Scope:** <files changed> files, <components migrated> component types migrated
-**Assumptions logged:** <count> (see inline `// MIGRATION ASSUMPTION:` comments)
-**Unresolved deltas:** <list or "none">
-**Shims still in place:** <list ShimComponent → target file — or "none">
-**Shim removal plan:** <for each shim: target v9 component when ready to replace — or "n/a">
-**Reference precedence used:** <component: decision made — or "none">
+**Scope:** 12 files, 4 component types migrated
+**Assumptions logged:** 2 (see inline `// MIGRATION ASSUMPTION:` comments)
+**Unresolved deltas:** none  (e.g. "GroupedList in DataView.tsx — awaiting user direction")
+**Shims still in place:** none  (e.g. "PrimaryButtonShim → src/Header.tsx")
+**Shim removal plan:** n/a  (e.g. "replace with Button appearance=primary once v8 deps removed")
+**Reference precedence used:** none  (e.g. "Dialog: used references/dialog.md over SKILL.md table")
 **Validation evidence:**
-  - TypeScript check (<command used>): ✅ / ❌ <error count> (baseline was <baseline count>)
-  - lint: ✅ / ❌ / ⏭️ skipped (no linter found)
-  - tests: ✅ / ❌ / ⏭️ skipped (no test command found)
-  - No remaining @fluentui/react imports: ✅ / ❌ <count remaining>
-**Final status:** ✅ Complete / ⚠️ Partial (see unresolved deltas) / ❌ Blocked (<reason>)
+  - TypeScript check (yarn tsc --noEmit): ✅  (e.g. ❌ 3 errors — baseline was 1)
+  - lint: ✅  (e.g. ⏭️ skipped — no linter found)
+  - tests: ✅  (e.g. ❌ 2 failing)
+  - No remaining @fluentui/react imports: ✅  (e.g. ❌ 3 remaining)
+**Final status:** ✅ Complete  (e.g. ⚠️ Partial — see unresolved deltas | ❌ Blocked: tsc errors)
 ```
 
 ---
@@ -32,16 +32,25 @@ After completing a migration session, report using this structure:
 
 ### Step 1 — Assess
 
-**Determine source root first:**
+**Determine project root and source directory:**
 
-1. Check `tsconfig.json` for `include` or `rootDir` to identify the source root (e.g., `src/`, `app/`, `lib/`)
-2. In a monorepo or if multiple `tsconfig.json` files exist, ask the user: _"Which directory or package should I migrate? (e.g., `packages/my-app/src`)"_
-3. If no tsconfig exists, default to searching from the repo root (`.`) and adjust from there
+1. Locate `package.json` to identify the **project root** — it is the source of truth. If multiple `package.json` files exist (monorepo), ask: _"Which package should I migrate? (e.g., `packages/my-app`)"_ — do not proceed until confirmed.
+2. Once the project root is confirmed, check `tsconfig.json` for `include` or `rootDir` to narrow down the **source directory** (e.g., `src/`, `app/`, `lib/`).
+3. If no `tsconfig.json` exists, treat the project root as the source root.
 
-Replace `<SOURCE_ROOT>` in the commands below with the path you identified.
+Use `<PROJECT_ROOT>` for the package root and `<SOURCE_ROOT>` for the narrowed source directory in the commands below.
 
 **Check for existing migration annotations:**
 
+First check for `.fluent-migrate/metadata.json` — written by the CLI after annotating, it lists annotated files deterministically:
+
+```sh
+cat <PROJECT_ROOT>/.fluent-migrate/metadata.json
+```
+
+- If `metadata.json` exists, use the `annotatedFiles` list directly as your work queue. Skip the grep scan.
+- If it does not exist, scan for annotations:
+
 ```sh
 grep -rl "@fluent-migrate:" <SOURCE_ROOT> --include="*.ts" --include="*.tsx"
 ```
@@ -64,28 +73,6 @@ Ready-to-proceed conditions (verify before starting Step 3):
 
 If either condition is unmet, report what's needed and stop until the user confirms setup is complete.
 
-### Agent Execution Contract
-
-**Phase order:** check for annotations (+ tsc baseline) → if missing, ask user to run CLI → process annotations (`auto` → `scaffold` → `manual` → `no-equivalent`) → validate → report (Output Template above)
-
-**Baseline TypeScript check before starting:** run the repo's TypeScript check command (`tsc --noEmit` or the equivalent in `package.json` scripts) before any changes and record the error count. In the Validation step, report TypeScript as ✅ if post-migration error count ≤ baseline — do not block on pre-existing errors.
-
-**Behavior-preserving default:** when uncertain, preserve existing behavior. Never silently drop functionality.
-
-**Confidence threshold for `manual` annotations:** if you are less than ~80% confident in a mapping, add an inline comment and flag it — do not skip it silently:
-
-```tsx
-// MIGRATION ASSUMPTION: GroupedList mapped to Tree (expand/collapse usage detected). Verify if tabular layout was intended.
-```
-
-**Stop and escalate when:**
-
-- TypeScript errors remain after processing annotations that you cannot resolve
-- A `no-equivalent` annotation has no clear workaround from the component mapping table
-- More than 2 unresolved `manual` annotations in the same file
-
-In those cases: commit what's done, fill in the Output Template with status ⚠️ or ❌, list the blockers, and wait for user input.
-
 ### Step 2 — User Setup (reference only)
 
 > **Agent note:** do not execute these commands. Report which packages are missing from `package.json` and wait for the user to confirm installation is complete before proceeding to Step 3.
@@ -116,7 +103,19 @@ import { PortalCompatProvider } from '@fluentui/react-portal-compat';
 
 ### Step 3 — Migrate (annotation-driven)
 
-Process the `@fluent-migrate:` annotations as a work queue. Get all annotations:
+**Before starting:** run the repo's TypeScript check command (`tsc --noEmit` or the `package.json` scripts equivalent) and record the error count as your baseline. After migration, TypeScript is ✅ if error count ≤ baseline — do not block on pre-existing errors.
+
+**Behavior-preserving default:** when uncertain, preserve existing behavior. Never silently drop functionality.
+
+**Stop and escalate when:**
+
+- TypeScript errors remain after processing annotations that you cannot resolve
+- A `no-equivalent` annotation has no clear workaround from the component mapping table
+- More than 2 unresolved `manual` annotations in the same file
+
+In those cases: commit what's done, fill in the Output Template with status ⚠️ or ❌, list the blockers, and wait for user input.
+
+Process the `@fluent-migrate:` annotations as a work queue. If `.fluent-migrate/metadata.json` exists, open each file it lists directly. Otherwise, get all annotations with:
 
 ```sh
 grep -rn "@fluent-migrate:" <SOURCE_ROOT> --include="*.ts" --include="*.tsx"
diff --git a/skills/fluentui-migrate-v8-to-v9/references/avatargroup.md b/skills/fluentui-migrate-v8-to-v9/references/avatargroup.md
index be6af59725a15e..5a7ac29a037e90 100644
--- a/skills/fluentui-migrate-v8-to-v9/references/avatargroup.md
+++ b/skills/fluentui-migrate-v8-to-v9/references/avatargroup.md
@@ -14,8 +14,9 @@ Use `partitionAvatarGroupItems` to split a list into inline vs overflow items ba
 
 ## Before / After Example
 
+### Before
+
 ```tsx
-// v8
 import { Facepile, IFacepilePersona } from '@fluentui/react';
 import { facepilePersonas } from '@fluentui/example-data';
 import { PersonaSize } from '@fluentui/react/lib/Persona';
@@ -26,8 +27,9 @@ const overflowPersonas = facepilePersonas.slice(3);
 <Facepile personaSize={PersonaSize.size32} personas={personas} overflowPersonas={overflowPersonas} />;
 ```
 
+### After
+
 ```tsx
-// v9
 import {
   AvatarGroup,
   AvatarGroupItem,
diff --git a/skills/fluentui-migrate-v8-to-v9/references/breadcrumb.md b/skills/fluentui-migrate-v8-to-v9/references/breadcrumb.md
index 3d0e59440f7ecc..8a06e34d71ba10 100644
--- a/skills/fluentui-migrate-v8-to-v9/references/breadcrumb.md
+++ b/skills/fluentui-migrate-v8-to-v9/references/breadcrumb.md
@@ -52,8 +52,9 @@ import {
 
 ## Before / After
 
+### Before
+
 ```tsx
-// v8 — data-driven
 import { Breadcrumb } from '@fluentui/react';
 <Breadcrumb
   items={[
@@ -62,8 +63,11 @@ import { Breadcrumb } from '@fluentui/react';
     { text: 'Components', key: 'components', isCurrentItem: true },
   ]}
 />;
+```
 
-// v9 — declarative
+### After
+
+```tsx
 import {
   Breadcrumb,
   BreadcrumbItem,
diff --git a/skills/fluentui-migrate-v8-to-v9/references/button.md b/skills/fluentui-migrate-v8-to-v9/references/button.md
index f22605e91cbc9c..554b3df5e7ef2b 100644
--- a/skills/fluentui-migrate-v8-to-v9/references/button.md
+++ b/skills/fluentui-migrate-v8-to-v9/references/button.md
@@ -18,12 +18,16 @@
 
 ### PrimaryButton
 
+**Before:**
+
 ```tsx
-// v8
 import { PrimaryButton } from '@fluentui/react';
 <PrimaryButton text="Submit" onClick={handleSubmit} />;
+```
 
-// v9
+**After:**
+
+```tsx
 import { Button } from '@fluentui/react-components';
 <Button appearance="primary" onClick={handleSubmit}>
   Submit
@@ -32,12 +36,16 @@ import { Button } from '@fluentui/react-components';
 
 ### ActionButton with icon
 
+**Before:**
+
 ```tsx
-// v8
 import { ActionButton } from '@fluentui/react';
 <ActionButton iconProps={{ iconName: 'Add' }}>Add item</ActionButton>;
+```
+
+**After:**
 
-// v9
+```tsx
 import { Button } from '@fluentui/react-components';
 import { AddRegular } from '@fluentui/react-icons';
 <Button appearance="transparent" icon={<AddRegular />}>
@@ -47,12 +55,16 @@ import { AddRegular } from '@fluentui/react-icons';
 
 ### IconButton
 
+**Before:**
+
 ```tsx
-// v8
 import { IconButton } from '@fluentui/react';
 <IconButton iconProps={{ iconName: 'Settings' }} title="Settings" />;
+```
 
-// v9
+**After:**
+
+```tsx
 import { Button } from '@fluentui/react-components';
 import { SettingsRegular } from '@fluentui/react-icons';
 <Button icon={<SettingsRegular />} aria-label="Settings" />;
@@ -60,14 +72,18 @@ import { SettingsRegular } from '@fluentui/react-icons';
 
 ### Button with href (navigation)
 
+**Before:**
+
 ```tsx
-// v8 — button that navigates via href
 import { DefaultButton, PrimaryButton } from '@fluentui/react';
 <DefaultButton href="/dashboard" target="_blank">
   Go to dashboard
 </DefaultButton>;
+```
+
+**After:**
 
-// v9 option A — use Link for inline text-style navigation
+```tsx
 import { Link } from '@fluentui/react-components';
 <Link href="/dashboard" target="_blank">
   Go to dashboard
@@ -86,8 +102,9 @@ design needs a button shape that navigates.
 
 ### Button with dropdown menu (`menuProps`)
 
+**Before:**
+
 ```tsx
-// v8 — button that opens a dropdown via menuProps
 import { DefaultButton } from '@fluentui/react';
 <DefaultButton
   text="Options"
@@ -98,8 +115,11 @@ import { DefaultButton } from '@fluentui/react';
     ],
   }}
 />;
+```
+
+**After:**
 
-// v9 — MenuButton inside Menu
+```tsx
 import { Menu, MenuTrigger, MenuPopover, MenuList, MenuItem, MenuButton } from '@fluentui/react-components';
 <Menu>
   <MenuTrigger disableButtonEnhancement>
@@ -118,23 +138,25 @@ For a primary-styled dropdown button: `<MenuButton appearance="primary">`.
 
 ### SplitButton
 
+**Before:**
+
 ```tsx
-// v8
 import { DefaultButton } from '@fluentui/react';
 <DefaultButton split menuProps={{ items: [...] }}>Action</DefaultButton>
+```
+
+**After:**
 
-// v9
+```tsx
 import { SplitButton, Menu, MenuItem, MenuList, MenuPopover, MenuTrigger } from '@fluentui/react-components';
 <Menu positioning="below-end">
-  <MenuTrigger>
-    {(triggerProps) => <SplitButton menuButton={triggerProps}>Action</SplitButton>}
-  </MenuTrigger>
+  <MenuTrigger>{triggerProps => <SplitButton menuButton={triggerProps}>Action</SplitButton>}</MenuTrigger>
   <MenuPopover>
     <MenuList>
       <MenuItem>Option 1</MenuItem>
     </MenuList>
   </MenuPopover>
-</Menu>
+</Menu>;
 ```
 
 ## Button Shims (Incremental Migration)
diff --git a/skills/fluentui-migrate-v8-to-v9/references/callout.md b/skills/fluentui-migrate-v8-to-v9/references/callout.md
index 669d756d89700c..6ddee51e438892 100644
--- a/skills/fluentui-migrate-v8-to-v9/references/callout.md
+++ b/skills/fluentui-migrate-v8-to-v9/references/callout.md
@@ -11,8 +11,9 @@ entirely — the trigger/surface relationship is established by co-location in J
 
 ## Before / After Example
 
+### Before
+
 ```tsx
-// v8
 import { Callout, DirectionalHint } from '@fluentui/react';
 
 const targetRef = React.useRef<HTMLButtonElement>(null);
@@ -36,8 +37,9 @@ const [isVisible, setIsVisible] = React.useState(false);
 </>;
 ```
 
+### After
+
 ```tsx
-// v9
 import { Popover, PopoverTrigger, PopoverSurface, Button } from '@fluentui/react-components';
 
 <Popover withArrow positioning="below-start">
diff --git a/skills/fluentui-migrate-v8-to-v9/references/card.md b/skills/fluentui-migrate-v8-to-v9/references/card.md
index f9adcfecb42046..8b4cd2e02b54ce 100644
--- a/skills/fluentui-migrate-v8-to-v9/references/card.md
+++ b/skills/fluentui-migrate-v8-to-v9/references/card.md
@@ -53,8 +53,9 @@ v8 `DocumentCard` and its variants map to v9's composable `Card` family in `@flu
 
 ## Before / After
 
+### Before
+
 ```tsx
-// v8
 import { DocumentCard, DocumentCardPreview, DocumentCardTitle, DocumentCardActivity } from '@fluentui/react';
 
 <DocumentCard onClick={handleClick}>
@@ -62,8 +63,11 @@ import { DocumentCard, DocumentCardPreview, DocumentCardTitle, DocumentCardActiv
   <DocumentCardTitle title="Report.pdf" />
   <DocumentCardActivity activity="Modified Jan 1" people={[{ name: 'Alice', profileImageSrc: avatarSrc }]} />
 </DocumentCard>;
+```
 
-// v9
+### After
+
+```tsx
 import { Card, CardHeader, CardPreview } from '@fluentui/react-components';
 
 <Card onClick={handleClick}>
diff --git a/skills/fluentui-migrate-v8-to-v9/references/checkbox.md b/skills/fluentui-migrate-v8-to-v9/references/checkbox.md
index b7546acaa0c6c1..a7ce2ae20625a0 100644
--- a/skills/fluentui-migrate-v8-to-v9/references/checkbox.md
+++ b/skills/fluentui-migrate-v8-to-v9/references/checkbox.md
@@ -32,8 +32,9 @@ import { Checkbox } from '@fluentui/react-components';
 
 ### Controlled Indeterminate
 
+**Before:**
+
 ```tsx
-// v8
 const [checked, setChecked] = React.useState(false);
 const [indeterminate, setIndeterminate] = React.useState(true);
 
@@ -45,8 +46,11 @@ const [indeterminate, setIndeterminate] = React.useState(true);
     setChecked(data.checked);
   }}
 />;
+```
 
-// v9
+**After:**
+
+```tsx
 const [checked, setChecked] = React.useState<boolean | 'mixed'>('mixed');
 
 <Checkbox checked={checked} onChange={(_, data) => setChecked(data.checked)} />;
@@ -54,11 +58,15 @@ const [checked, setChecked] = React.useState<boolean | 'mixed'>('mixed');
 
 ### Label Position
 
+**Before:**
+
 ```tsx
-// v8 — boxSide: 'end' puts the checkbox on the right
 <Checkbox label="Label on left" boxSide="end" />
+```
 
-// v9 — labelPosition: 'before' puts label on the left (checkbox on right)
+**After:**
+
+```tsx
 <Checkbox label="Label on left" labelPosition="before" />
 ```
 
diff --git a/skills/fluentui-migrate-v8-to-v9/references/colorpicker.md b/skills/fluentui-migrate-v8-to-v9/references/colorpicker.md
index 83a175c42ce6b3..adfb0106269e78 100644
--- a/skills/fluentui-migrate-v8-to-v9/references/colorpicker.md
+++ b/skills/fluentui-migrate-v8-to-v9/references/colorpicker.md
@@ -48,12 +48,16 @@ v9 ships a new `ColorPicker` in `@fluentui/react-components` with a revised API.
 
 ## Before / After
 
+### Before
+
 ```tsx
-// v8
 import { ColorPicker } from '@fluentui/react';
 <ColorPicker color={color} onChange={(_, c) => setColor(c)} />;
+```
 
-// v9
+### After
+
+```tsx
 import { ColorPicker } from '@fluentui/react-components';
 <ColorPicker color={hsv} onColorChange={(_, data) => setHsv(data.color)} />;
 ```
diff --git a/skills/fluentui-migrate-v8-to-v9/references/datagrid.md b/skills/fluentui-migrate-v8-to-v9/references/datagrid.md
index a4ff5fc3a0ea36..1ba78d0243d79c 100644
--- a/skills/fluentui-migrate-v8-to-v9/references/datagrid.md
+++ b/skills/fluentui-migrate-v8-to-v9/references/datagrid.md
@@ -15,8 +15,9 @@ Key shifts:
 
 ## Before / After Example
 
+### Before
+
 ```tsx
-// v8 — DetailsList
 import { DetailsList, IColumn, SelectionMode, Selection } from '@fluentui/react';
 
 interface Item {
@@ -55,8 +56,9 @@ const selection = new Selection();
 />;
 ```
 
+### After
+
 ```tsx
-// v9 — DataGrid
 import {
   DataGrid,
   DataGridHeader,
diff --git a/skills/fluentui-migrate-v8-to-v9/references/dialog.md b/skills/fluentui-migrate-v8-to-v9/references/dialog.md
index ba463c5926bedb..7b6733a2e1c1e3 100644
--- a/skills/fluentui-migrate-v8-to-v9/references/dialog.md
+++ b/skills/fluentui-migrate-v8-to-v9/references/dialog.md
@@ -182,15 +182,19 @@ import {
 
 ## v8 DialogFooter → DialogActions
 
+**Before:**
+
 ```tsx
-// v8
 import { DialogFooter } from '@fluentui/react';
 <DialogFooter>
   <PrimaryButton text="OK" />
   <DefaultButton text="Cancel" />
 </DialogFooter>;
+```
 
-// v9
+**After:**
+
+```tsx
 import { DialogActions } from '@fluentui/react-components';
 <DialogActions>
   <Button appearance="primary">OK</Button>
diff --git a/skills/fluentui-migrate-v8-to-v9/references/drawer.md b/skills/fluentui-migrate-v8-to-v9/references/drawer.md
index 7a2d9ee1002e4f..4c508dbd4f75bc 100644
--- a/skills/fluentui-migrate-v8-to-v9/references/drawer.md
+++ b/skills/fluentui-migrate-v8-to-v9/references/drawer.md
@@ -12,8 +12,9 @@ The v9 package exports two variants:
 
 ## Before / After Example
 
+### Before
+
 ```tsx
-// v8 — Panel
 import { Panel, PanelType, PrimaryButton, DefaultButton } from '@fluentui/react';
 
 <Panel
@@ -36,8 +37,9 @@ import { Panel, PanelType, PrimaryButton, DefaultButton } from '@fluentui/react'
 </Panel>;
 ```
 
+### After
+
 ```tsx
-// v9 — OverlayDrawer
 import {
   OverlayDrawer,
   DrawerHeader,
diff --git a/skills/fluentui-migrate-v8-to-v9/references/image.md b/skills/fluentui-migrate-v8-to-v9/references/image.md
index 142f3dbf702b43..f8ba5f8c16f5e6 100644
--- a/skills/fluentui-migrate-v8-to-v9/references/image.md
+++ b/skills/fluentui-migrate-v8-to-v9/references/image.md
@@ -41,12 +41,16 @@ The boolean style props from v8 (`isCenter`, `isCoverContain`, `isLandscape`, `i
 
 ## Before / After
 
+### Before
+
 ```tsx
-// v8
 import { Image, ImageFit } from '@fluentui/react';
 <Image src={imgSrc} imageFit={ImageFit.cover} width={200} height={150} shouldFadeIn />;
+```
 
-// v9
+### After
+
+```tsx
 import { Image, makeStyles } from '@fluentui/react-components';
 
 const useStyles = makeStyles({
diff --git a/skills/fluentui-migrate-v8-to-v9/references/input.md b/skills/fluentui-migrate-v8-to-v9/references/input.md
index 011826820a3ab4..7865dbc03d68e4 100644
--- a/skills/fluentui-migrate-v8-to-v9/references/input.md
+++ b/skills/fluentui-migrate-v8-to-v9/references/input.md
@@ -44,11 +44,15 @@ const errorId = useId('email-error');
 
 ### Multiline TextField → Textarea
 
+**Before:**
+
 ```tsx
-// v8
-<TextField multiline rows={4} label="Description" />;
+<TextField multiline rows={4} label="Description" />
+```
+
+**After:**
 
-// v9
+```tsx
 import { Field, Textarea } from '@fluentui/react-components';
 
 <Field label="Description">
@@ -58,11 +62,15 @@ import { Field, Textarea } from '@fluentui/react-components';
 
 ### Prefix / Suffix
 
+**Before:**
+
 ```tsx
-// v8
-<TextField prefix="https://" suffix=".com" />;
+<TextField prefix="https://" suffix=".com" />
+```
 
-// v9
+**After:**
+
+```tsx
 import { Input } from '@fluentui/react-components';
 <Input contentBefore="https://" contentAfter=".com" />;
 // Note: contentBefore/contentAfter accept ReactNode (slot), not just strings
@@ -70,12 +78,16 @@ import { Input } from '@fluentui/react-components';
 
 ### Underlined / Borderless appearance
 
+**Before:**
+
 ```tsx
-// v8
 <TextField underlined />
 <TextField borderless />
+```
+
+**After:**
 
-// v9
+```tsx
 <Input appearance="underline" />
 <Input appearance="filled-lighter" />
 ```
diff --git a/skills/fluentui-migrate-v8-to-v9/references/keytips.md b/skills/fluentui-migrate-v8-to-v9/references/keytips.md
index 60fcb626ebf44e..1d65c17f371b21 100644
--- a/skills/fluentui-migrate-v8-to-v9/references/keytips.md
+++ b/skills/fluentui-migrate-v8-to-v9/references/keytips.md
@@ -58,12 +58,16 @@ v9 components do **not** have a `keytipProps` prop — keytips are attached via
 
 ## Before / After
 
+### Before
+
 ```tsx
-// v8 — keytipProps on the component
 import { DefaultButton } from '@fluentui/react';
 <DefaultButton keytipProps={{ content: 'B', keySequences: ['b'] }}>Action</DefaultButton>;
+```
 
-// v9 — useKeytipRef hook
+### After
+
+```tsx
 import { Button } from '@fluentui/react-components';
 import { Keytips, useKeytipRef } from '@fluentui/react-keytips';
 
diff --git a/skills/fluentui-migrate-v8-to-v9/references/label.md b/skills/fluentui-migrate-v8-to-v9/references/label.md
index ff573193feaae9..11550e5485242d 100644
--- a/skills/fluentui-migrate-v8-to-v9/references/label.md
+++ b/skills/fluentui-migrate-v8-to-v9/references/label.md
@@ -15,12 +15,16 @@ v9 `Label` is a near drop-in replacement. The main addition is support for a **c
 
 ## Before / After
 
+### Before
+
 ```tsx
-// v8
 import { Label } from '@fluentui/react';
 <Label required>Email</Label>;
+```
 
-// v9
+### After
+
+```tsx
 import { Label } from '@fluentui/react-components';
 <Label required>Email</Label>;
 // Custom required indicator:
diff --git a/skills/fluentui-migrate-v8-to-v9/references/link.md b/skills/fluentui-migrate-v8-to-v9/references/link.md
index f664ab366536e8..f48b8db8bcd19b 100644
--- a/skills/fluentui-migrate-v8-to-v9/references/link.md
+++ b/skills/fluentui-migrate-v8-to-v9/references/link.md
@@ -29,13 +29,17 @@ v9 `Link` is a near drop-in replacement with improved accessibility and an `inli
 
 ## Before / After
 
+### Before
+
 ```tsx
-// v8
 import { Link } from '@fluentui/react';
 <Link href="/docs">Read the docs</Link>;
 <Link onClick={handleClick}>Click me</Link>;
+```
 
-// v9
+### After
+
+```tsx
 import { Link } from '@fluentui/react-components';
 <Link href="/docs">Read the docs</Link>;
 <Link onClick={handleClick}>Click me</Link>;
diff --git a/skills/fluentui-migrate-v8-to-v9/references/list.md b/skills/fluentui-migrate-v8-to-v9/references/list.md
index 41021ad02133c6..4ce177ebbfa10f 100644
--- a/skills/fluentui-migrate-v8-to-v9/references/list.md
+++ b/skills/fluentui-migrate-v8-to-v9/references/list.md
@@ -39,12 +39,16 @@ v9 `List` + `ListItem` replaces v8 `List`. The v9 component adds first-class key
 
 ## Before / After
 
+### Before
+
 ```tsx
-// v8 — data-driven
 import { List } from '@fluentui/react';
 <List items={contacts} onRenderCell={item => <div onClick={() => openContact(item)}>{item?.name}</div>} />;
+```
 
-// v9 — declarative + keyboard-accessible
+### After
+
+```tsx
 import { List, ListItem } from '@fluentui/react-components';
 <List navigationMode="items">
   {contacts.map(contact => (
diff --git a/skills/fluentui-migrate-v8-to-v9/references/menu.md b/skills/fluentui-migrate-v8-to-v9/references/menu.md
index b732f60eeb0e1d..75898286a7bdf2 100644
--- a/skills/fluentui-migrate-v8-to-v9/references/menu.md
+++ b/skills/fluentui-migrate-v8-to-v9/references/menu.md
@@ -8,8 +8,9 @@ In v9 menus are **declarative**: compose JSX children under `Menu`.
 
 ## Before / After Example
 
+### Before
+
 ```tsx
-// v8 — data-driven
 import { ContextualMenu, ContextualMenuItemType } from '@fluentui/react';
 
 <ContextualMenu
@@ -30,8 +31,9 @@ import { ContextualMenu, ContextualMenuItemType } from '@fluentui/react';
 />;
 ```
 
+### After
+
 ```tsx
-// v9 — declarative
 import {
   Menu,
   MenuTrigger,
diff --git a/skills/fluentui-migrate-v8-to-v9/references/messagebar.md b/skills/fluentui-migrate-v8-to-v9/references/messagebar.md
index 527e81f5854f71..c5c38715c214c0 100644
--- a/skills/fluentui-migrate-v8-to-v9/references/messagebar.md
+++ b/skills/fluentui-migrate-v8-to-v9/references/messagebar.md
@@ -8,8 +8,9 @@ v9 `MessageBar` is **composable**: content is structured via `MessageBarBody`, `
 
 ## Before / After Example
 
+### Before
+
 ```tsx
-// v8
 import { MessageBar, MessageBarType, MessageBarButton } from '@fluentui/react';
 
 <MessageBar
@@ -27,8 +28,9 @@ import { MessageBar, MessageBarType, MessageBarButton } from '@fluentui/react';
 </MessageBar>;
 ```
 
+### After
+
 ```tsx
-// v9
 import { MessageBar, MessageBarBody, MessageBarTitle, MessageBarActions, Button } from '@fluentui/react-components';
 import { DismissRegular } from '@fluentui/react-icons';
 
diff --git a/skills/fluentui-migrate-v8-to-v9/references/nav.md b/skills/fluentui-migrate-v8-to-v9/references/nav.md
index 5d1ccec51b38bf..c228dc6aa3dadc 100644
--- a/skills/fluentui-migrate-v8-to-v9/references/nav.md
+++ b/skills/fluentui-migrate-v8-to-v9/references/nav.md
@@ -64,8 +64,9 @@ import {
 
 ## Before / After
 
+### Before
+
 ```tsx
-// v8 — data-driven groups
 import { Nav } from '@fluentui/react';
 
 <Nav
@@ -85,8 +86,11 @@ import { Nav } from '@fluentui/react';
     },
   ]}
 />;
+```
 
-// v9 — declarative JSX
+### After
+
+```tsx
 import { Nav, NavItem, NavCategory, NavCategoryItem, NavSubItemGroup, NavSubItem } from '@fluentui/react-components';
 import { HomeRegular, SettingsRegular } from '@fluentui/react-icons';
 
diff --git a/skills/fluentui-migrate-v8-to-v9/references/overflow.md b/skills/fluentui-migrate-v8-to-v9/references/overflow.md
index 8b6313fdccfb45..638a60943215ac 100644
--- a/skills/fluentui-migrate-v8-to-v9/references/overflow.md
+++ b/skills/fluentui-migrate-v8-to-v9/references/overflow.md
@@ -45,8 +45,9 @@ v8 `OverflowSet` used render callbacks (`onRenderItem`, `onRenderOverflowButton`
 
 ## Before / After
 
+### Before
+
 ```tsx
-// v8 — render callbacks
 import { OverflowSet } from '@fluentui/react';
 
 <OverflowSet
@@ -58,8 +59,11 @@ import { OverflowSet } from '@fluentui/react';
   onRenderItem={item => <CommandBarButton text={item.name} onClick={item.onClick} />}
   onRenderOverflowButton={items => <CommandBarButton menuProps={{ items }} text="..." />}
 />;
+```
 
-// v9 — hook-based composition
+### After
+
+```tsx
 import {
   Overflow,
   OverflowItem,
diff --git a/skills/fluentui-migrate-v8-to-v9/references/persona.md b/skills/fluentui-migrate-v8-to-v9/references/persona.md
index 93bc76fa3669e4..c4bb11cdd3f853 100644
--- a/skills/fluentui-migrate-v8-to-v9/references/persona.md
+++ b/skills/fluentui-migrate-v8-to-v9/references/persona.md
@@ -51,8 +51,9 @@ v9 `Persona` uses a slot-based API. Text lines are slots (`primaryText`, `second
 
 ## Before / After
 
+### Before
+
 ```tsx
-// v8
 import { Persona, PersonaSize, PersonaPresence } from '@fluentui/react';
 <Persona
   text="Alice Northwood"
@@ -61,8 +62,11 @@ import { Persona, PersonaSize, PersonaPresence } from '@fluentui/react';
   size={PersonaSize.size48}
   presence={PersonaPresence.online}
 />;
+```
 
-// v9
+### After
+
+```tsx
 import { Persona } from '@fluentui/react-components';
 <Persona
   name="Alice Northwood"
diff --git a/skills/fluentui-migrate-v8-to-v9/references/progressbar.md b/skills/fluentui-migrate-v8-to-v9/references/progressbar.md
index c0aed158ee4acc..35c1b2c6dd634b 100644
--- a/skills/fluentui-migrate-v8-to-v9/references/progressbar.md
+++ b/skills/fluentui-migrate-v8-to-v9/references/progressbar.md
@@ -31,11 +31,15 @@ import { Field, ProgressBar } from '@fluentui/react-components';
 
 ### Indeterminate progress
 
+**Before:**
+
 ```tsx
-// v8 — omit percentComplete
-<ProgressIndicator label="Loading" />;
+<ProgressIndicator label="Loading" />
+```
+
+**After:**
 
-// v9 — omit value
+```tsx
 import { Field, ProgressBar } from '@fluentui/react-components';
 
 <Field label="Loading">
@@ -45,11 +49,15 @@ import { Field, ProgressBar } from '@fluentui/react-components';
 
 ### Without label (aria-label only)
 
+**Before:**
+
 ```tsx
-// v8
-<ProgressIndicator percentComplete={0.5} ariaLabel="Upload progress" />;
+<ProgressIndicator percentComplete={0.5} ariaLabel="Upload progress" />
+```
 
-// v9
+**After:**
+
+```tsx
 import { ProgressBar } from '@fluentui/react-components';
 
 <ProgressBar value={0.5} aria-label="Upload progress" />;
diff --git a/skills/fluentui-migrate-v8-to-v9/references/radiogroup.md b/skills/fluentui-migrate-v8-to-v9/references/radiogroup.md
index b8409fed3a6f0a..d13f5195922a76 100644
--- a/skills/fluentui-migrate-v8-to-v9/references/radiogroup.md
+++ b/skills/fluentui-migrate-v8-to-v9/references/radiogroup.md
@@ -60,12 +60,16 @@ const labelId = useId('label');
 
 ### Controlled (selectedKey → value)
 
+**Before:**
+
 ```tsx
-// v8
 const [selected, setSelected] = React.useState('A');
 <ChoiceGroup selectedKey={selected} options={options} onChange={(_, option) => option && setSelected(option.key)} />;
+```
 
-// v9
+**After:**
+
+```tsx
 const [selected, setSelected] = React.useState('A');
 <RadioGroup value={selected} onChange={(_, data) => setSelected(data.value)}>
   <Radio value="A" label="Option A" />
@@ -77,24 +81,32 @@ const [selected, setSelected] = React.useState('A');
 
 v9 accepts direct JSX instead of `onRenderField` callbacks:
 
+**Before:**
+
 ```tsx
-// v8 — onRenderField callback
 { key: 'A', text: 'With icon', onRenderField: (props, render) => (
   <div style={{ display: 'flex', gap: 5 }}>
     {render!(props)}
     <CatIcon />
   </div>
 )}
+```
 
-// v9 — customize the label slot directly
+**After:**
+
+```tsx
 import { AnimalCat24Regular } from '@fluentui/react-icons';
 
 <Radio
   value="A"
   label={{
-    children: <><AnimalCat24Regular /> With icon</>,
+    children: (
+      <>
+        <AnimalCat24Regular /> With icon
+      </>
+    ),
   }}
-/>
+/>;
 ```
 
 ## ChoiceGroup → RadioGroup Prop Mapping
diff --git a/skills/fluentui-migrate-v8-to-v9/references/rating.md b/skills/fluentui-migrate-v8-to-v9/references/rating.md
index 2a4e7f62c706ba..25d182f993d221 100644
--- a/skills/fluentui-migrate-v8-to-v9/references/rating.md
+++ b/skills/fluentui-migrate-v8-to-v9/references/rating.md
@@ -37,8 +37,9 @@ v9 `Rating` has a cleaner API. The main differences are the `value` prop rename,
 
 ## Before / After
 
+### Before
+
 ```tsx
-// v8
 import { Rating, RatingSize } from '@fluentui/react';
 <Rating
   rating={value}
@@ -47,8 +48,11 @@ import { Rating, RatingSize } from '@fluentui/react';
   onChange={(_, v) => setValue(v ?? 0)}
   ariaLabelFormat="{0} of {1} stars"
 />;
+```
 
-// v9
+### After
+
+```tsx
 import { Rating } from '@fluentui/react-components';
 <Rating
   value={value}
diff --git a/skills/fluentui-migrate-v8-to-v9/references/searchbox.md b/skills/fluentui-migrate-v8-to-v9/references/searchbox.md
index 90fede59e43020..64a6d75a40f6cb 100644
--- a/skills/fluentui-migrate-v8-to-v9/references/searchbox.md
+++ b/skills/fluentui-migrate-v8-to-v9/references/searchbox.md
@@ -32,8 +32,9 @@ v9 `SearchBox` is in `@fluentui/react-components`. The API is similar to v9 `Inp
 
 ## Before / After
 
+### Before
+
 ```tsx
-// v8
 import { SearchBox } from '@fluentui/react';
 <SearchBox
   placeholder="Search"
@@ -42,8 +43,11 @@ import { SearchBox } from '@fluentui/react';
   onSearch={v => doSearch(v)}
   onClear={() => setQuery('')}
 />;
+```
 
-// v9
+### After
+
+```tsx
 import { SearchBox } from '@fluentui/react-components';
 <SearchBox
   placeholder="Search"
diff --git a/skills/fluentui-migrate-v8-to-v9/references/separator.md b/skills/fluentui-migrate-v8-to-v9/references/separator.md
index f15cc964afe808..d8eda7dff2a905 100644
--- a/skills/fluentui-migrate-v8-to-v9/references/separator.md
+++ b/skills/fluentui-migrate-v8-to-v9/references/separator.md
@@ -16,14 +16,18 @@ This is a straightforward rename. `Separator` (v8) → `Divider` (v9). The core
 
 ## Before / After
 
+### Before
+
 ```tsx
-// v8
 import { Separator } from '@fluentui/react';
 <Separator vertical alignContent="end">
   Label
 </Separator>;
+```
 
-// v9
+### After
+
+```tsx
 import { Divider } from '@fluentui/react-components';
 <Divider vertical alignContent="end">
   Label
diff --git a/skills/fluentui-migrate-v8-to-v9/references/skeleton.md b/skills/fluentui-migrate-v8-to-v9/references/skeleton.md
index 63728fa5dc9b4d..a3d4c9dafa940b 100644
--- a/skills/fluentui-migrate-v8-to-v9/references/skeleton.md
+++ b/skills/fluentui-migrate-v8-to-v9/references/skeleton.md
@@ -32,8 +32,9 @@
 
 ## Before / After
 
+### Before
+
 ```tsx
-// v8 — data-gated with isDataLoaded
 import { Shimmer, ShimmerElementType } from '@fluentui/react';
 
 <Shimmer
@@ -46,8 +47,11 @@ import { Shimmer, ShimmerElementType } from '@fluentui/react';
 >
   <MyContent />
 </Shimmer>;
+```
 
-// v9 — conditional render
+### After
+
+```tsx
 import { Skeleton, SkeletonItem, makeStyles } from '@fluentui/react-components';
 
 const useStyles = makeStyles({
diff --git a/skills/fluentui-migrate-v8-to-v9/references/slider.md b/skills/fluentui-migrate-v8-to-v9/references/slider.md
index 72b4a01c278176..510a469542b442 100644
--- a/skills/fluentui-migrate-v8-to-v9/references/slider.md
+++ b/skills/fluentui-migrate-v8-to-v9/references/slider.md
@@ -58,11 +58,15 @@ const onChange = (_: React.ChangeEvent<HTMLInputElement>, data: SliderOnChangeDa
 
 v8 had a `showValue` prop. In v9, render the value yourself:
 
+**Before:**
+
 ```tsx
-// v8
-<Slider label="Volume" showValue value={value} min={0} max={100} />;
+<Slider label="Volume" showValue value={value} min={0} max={100} />
+```
+
+**After:**
 
-// v9 — embed value in the label slot
+```tsx
 import { Field, Slider } from '@fluentui/react-components';
 
 const [value, setValue] = React.useState(20);
@@ -74,21 +78,29 @@ const [value, setValue] = React.useState(20);
 
 ### With Step
 
+**Before:**
+
 ```tsx
-// v8 — snapToStep was a separate optional prop
 <Slider min={0} max={100} step={10} snapToStep />
+```
 
-// v9 — always snaps to step (snapToStep removed)
+**After:**
+
+```tsx
 <Slider min={0} max={100} step={10} />
 ```
 
 ### Vertical Slider
 
+**Before:**
+
 ```tsx
-// v8
-<Slider vertical label="Height" min={0} max={100} />;
+<Slider vertical label="Height" min={0} max={100} />
+```
+
+**After:**
 
-// v9 — same prop
+```tsx
 import { Field, Slider } from '@fluentui/react-components';
 
 <Field label="Height">
diff --git a/skills/fluentui-migrate-v8-to-v9/references/spinner.md b/skills/fluentui-migrate-v8-to-v9/references/spinner.md
index f3613c64d00e79..1ae550a1122204 100644
--- a/skills/fluentui-migrate-v8-to-v9/references/spinner.md
+++ b/skills/fluentui-migrate-v8-to-v9/references/spinner.md
@@ -8,15 +8,17 @@
 
 ## Before / After Example
 
+### Before
+
 ```tsx
-// v8
 import { Spinner, SpinnerSize } from '@fluentui/react';
 
 <Spinner size={SpinnerSize.large} label="Loading..." labelPosition="right" />;
 ```
 
+### After
+
 ```tsx
-// v9
 import { Spinner } from '@fluentui/react-components';
 
 <Spinner size="large" label="Loading..." labelPosition="after" />;
diff --git a/skills/fluentui-migrate-v8-to-v9/references/swatchpicker.md b/skills/fluentui-migrate-v8-to-v9/references/swatchpicker.md
index 1533ba052590bd..61feab6a1a1541 100644
--- a/skills/fluentui-migrate-v8-to-v9/references/swatchpicker.md
+++ b/skills/fluentui-migrate-v8-to-v9/references/swatchpicker.md
@@ -42,8 +42,9 @@ import { SwatchPicker, SwatchPickerRow, ColorSwatch, ImageSwatch, EmptySwatch }
 
 ## Before / After
 
+### Before
+
 ```tsx
-// v8 — data-driven array
 import { SwatchColorPicker } from '@fluentui/react';
 
 <SwatchColorPicker
@@ -57,8 +58,11 @@ import { SwatchColorPicker } from '@fluentui/react';
     { id: 'yellow', label: 'Yellow', color: '#fce100' },
   ]}
 />;
+```
 
-// v9 — declarative children
+### After
+
+```tsx
 import { SwatchPicker, SwatchPickerRow, ColorSwatch } from '@fluentui/react-components';
 
 <SwatchPicker selectedValue={selected} onSelectionChange={(_, data) => setSelected(data.selectedValue)}>
diff --git a/skills/fluentui-migrate-v8-to-v9/references/switch.md b/skills/fluentui-migrate-v8-to-v9/references/switch.md
index abe96120842a66..ce2c48865cda7a 100644
--- a/skills/fluentui-migrate-v8-to-v9/references/switch.md
+++ b/skills/fluentui-migrate-v8-to-v9/references/switch.md
@@ -27,14 +27,18 @@
 
 ## Before / After
 
+### Before
+
 ```tsx
-// v8
 import { Toggle } from '@fluentui/react';
 const [on, setOn] = React.useState(false);
 
 <Toggle label="Wi-Fi" onText="On" offText="Off" checked={on} onChange={(_, checked) => setOn(checked ?? false)} />;
+```
 
-// v9
+### After
+
+```tsx
 import { Switch } from '@fluentui/react-components';
 const [on, setOn] = React.useState(false);
 
diff --git a/skills/fluentui-migrate-v8-to-v9/references/tabs.md b/skills/fluentui-migrate-v8-to-v9/references/tabs.md
index e3a64f42336db1..f034fa0eaa5467 100644
--- a/skills/fluentui-migrate-v8-to-v9/references/tabs.md
+++ b/skills/fluentui-migrate-v8-to-v9/references/tabs.md
@@ -8,8 +8,9 @@ In v9 (`TabList`), `Tab` children are the **label only**. Tab content lives **ou
 
 ## Before / After Example
 
+### Before
+
 ```tsx
-// v8 — content inside PivotItem
 import { Pivot, PivotItem } from '@fluentui/react';
 
 <Pivot>
@@ -25,8 +26,9 @@ import { Pivot, PivotItem } from '@fluentui/react';
 </Pivot>;
 ```
 
+### After
+
 ```tsx
-// v9 — content is separate, driven by state
 import * as React from 'react';
 import { TabList, Tab } from '@fluentui/react-components';
 import type { SelectTabData, SelectTabEvent, TabValue } from '@fluentui/react-components';
diff --git a/skills/fluentui-migrate-v8-to-v9/references/teachingpopover.md b/skills/fluentui-migrate-v8-to-v9/references/teachingpopover.md
index 74d73bb738d9e4..badac6d8c0126d 100644
--- a/skills/fluentui-migrate-v8-to-v9/references/teachingpopover.md
+++ b/skills/fluentui-migrate-v8-to-v9/references/teachingpopover.md
@@ -39,8 +39,9 @@ Both v8 components map to v9 `TeachingPopover`. It uses the same composable trig
 
 ## Before / After
 
+### Before
+
 ```tsx
-// v8 — TeachingBubble
 import { TeachingBubble } from '@fluentui/react';
 <TeachingBubble
   target="#my-button"
@@ -51,8 +52,11 @@ import { TeachingBubble } from '@fluentui/react';
 >
   Here's how to use this new feature.
 </TeachingBubble>;
+```
 
-// v9 — TeachingPopover
+### After
+
+```tsx
 import {
   TeachingPopover,
   TeachingPopoverTrigger,
diff --git a/skills/fluentui-migrate-v8-to-v9/references/text.md b/skills/fluentui-migrate-v8-to-v9/references/text.md
index 61f78c784f8b88..7f9d3ae4cde8ca 100644
--- a/skills/fluentui-migrate-v8-to-v9/references/text.md
+++ b/skills/fluentui-migrate-v8-to-v9/references/text.md
@@ -61,14 +61,18 @@ Prefer presets over manual `size`/`weight` when matching the Fluent design syste
 
 ## Before / After
 
+### Before
+
 ```tsx
-// v8
 import { Text } from '@fluentui/react';
 <Text variant="xxLarge" block nowrap>
   Heading
 </Text>;
+```
 
-// v9 — using size/weight
+### After
+
+```tsx
 import { Text } from '@fluentui/react-components';
 <Text size={700} weight="semibold" block wrap={false}>
   Heading
diff --git a/skills/fluentui-migrate-v8-to-v9/references/textarea.md b/skills/fluentui-migrate-v8-to-v9/references/textarea.md
index 7e240812f7ba90..c137511a14096b 100644
--- a/skills/fluentui-migrate-v8-to-v9/references/textarea.md
+++ b/skills/fluentui-migrate-v8-to-v9/references/textarea.md
@@ -35,8 +35,9 @@ Wrap `Textarea` in `<Field>` to get a label, validation message, and required in
 
 ## Before / After
 
+### Before
+
 ```tsx
-// v8
 import { TextField } from '@fluentui/react';
 <TextField
   label="Comments"
@@ -46,8 +47,11 @@ import { TextField } from '@fluentui/react';
   value={value}
   onChange={(_, v) => setValue(v ?? '')}
 />;
+```
 
-// v9
+### After
+
+```tsx
 import { Field, Textarea } from '@fluentui/react-components';
 <Field label="Comments" required validationState={error ? 'error' : 'none'} validationMessage={error}>
   <Textarea value={value} onChange={(_, data) => setValue(data.value)} resize="vertical" />
diff --git a/skills/fluentui-migrate-v8-to-v9/references/toolbar.md b/skills/fluentui-migrate-v8-to-v9/references/toolbar.md
index 7a0730f38aa0fb..284c2c91b32941 100644
--- a/skills/fluentui-migrate-v8-to-v9/references/toolbar.md
+++ b/skills/fluentui-migrate-v8-to-v9/references/toolbar.md
@@ -11,8 +11,9 @@ pattern from `@fluentui/react-components`.
 
 ## Before / After Example
 
+### Before
+
 ```tsx
-// v8 — CommandBar
 import { CommandBar, ICommandBarItemProps } from '@fluentui/react';
 
 const items: ICommandBarItemProps[] = [
@@ -28,8 +29,9 @@ const farItems: ICommandBarItemProps[] = [
 <CommandBar items={items} farItems={farItems} />;
 ```
 
+### After
+
 ```tsx
-// v9 — Toolbar
 import { Toolbar, ToolbarButton, ToolbarDivider } from '@fluentui/react-components';
 import { AddRegular, EditRegular, DeleteRegular, InfoRegular } from '@fluentui/react-icons';
 import { makeStyles } from '@fluentui/react-components';
diff --git a/skills/fluentui-migrate-v8-to-v9/references/tooltip.md b/skills/fluentui-migrate-v8-to-v9/references/tooltip.md
index 30e940411ed9f8..a7615307248ed8 100644
--- a/skills/fluentui-migrate-v8-to-v9/references/tooltip.md
+++ b/skills/fluentui-migrate-v8-to-v9/references/tooltip.md
@@ -8,8 +8,9 @@ In v9, the child of `Tooltip` **is** the trigger and **must** be able to accept
 
 ## Before / After Example
 
+### Before
+
 ```tsx
-// v8
 import { Tooltip, DirectionalHint } from '@fluentui/react';
 import { DefaultButton } from '@fluentui/react';
 
@@ -18,8 +19,9 @@ import { DefaultButton } from '@fluentui/react';
 </Tooltip>;
 ```
 
+### After
+
 ```tsx
-// v9
 import { Tooltip, Button } from '@fluentui/react-components';
 
 <Tooltip content="This button deletes the item" relationship="description" positioning="below">
diff --git a/tools/cli/eslint.config.cjs b/tools/cli/eslint.config.cjs
index 827203cf8f59b7..f956e471b76c29 100644
--- a/tools/cli/eslint.config.cjs
+++ b/tools/cli/eslint.config.cjs
@@ -1,5 +1,11 @@
 // @ts-check
 const fluentPlugin = require('@fluentui/eslint-plugin');
+const nodeConfig = fluentPlugin.configs['flat/node'];
 
 /** @type {import("eslint").Linter.Config[]} */
-module.exports = [...fluentPlugin.configs['flat/node']];
+module.exports = [
+  {
+    ignores: ['src/commands/migrate/v8-to-v9/__tests__/fixtures/**'],
+  },
+  ...(Array.isArray(nodeConfig) ? nodeConfig : [nodeConfig]),
+];
diff --git a/tools/cli/src/commands/migrate/index.ts b/tools/cli/src/commands/migrate/index.ts
index 9f96301460db54..188fe1bcf93f66 100644
--- a/tools/cli/src/commands/migrate/index.ts
+++ b/tools/cli/src/commands/migrate/index.ts
@@ -1,12 +1,38 @@
 import type { CommandModule } from 'yargs';
 import v8ToV9Command from './v8-to-v9';
 
+const AVAILABLE_MIGRATIONS = ['v8-to-v9'];
+
 const command: CommandModule = {
-  command: 'migrate <migration>',
+  command: 'migrate [migration]',
   describe: 'Run migration analysis and annotation',
   builder: yargs =>
-    yargs.command(v8ToV9Command).demandCommand(1, 'Specify a migration type: v8-to-v9').version(false).help(),
-  handler: () => {},
+    yargs
+      .command(v8ToV9Command)
+      .option('list', {
+        alias: 'l',
+        type: 'boolean',
+        description: 'List all available migrations',
+      })
+      .check(argv => {
+        if (argv.list) {
+          return true;
+        }
+        if (!argv.migration) {
+          throw new Error(`No migration specified. Run --list to see available migrations.`);
+        }
+        return true;
+      })
+      .version(false)
+      .help(),
+  handler: argv => {
+    if ((argv as { list?: boolean }).list) {
+      console.log('Available migrations:');
+      for (const m of AVAILABLE_MIGRATIONS) {
+        console.log(`  ${m}`);
+      }
+    }
+  },
 };
 
 export default command;
diff --git a/tools/cli/src/commands/migrate/v8-to-v9/__tests__/handler.integration.spec.ts b/tools/cli/src/commands/migrate/v8-to-v9/__tests__/handler.integration.spec.ts
index 81ee85f66a9870..77bb122631860e 100644
--- a/tools/cli/src/commands/migrate/v8-to-v9/__tests__/handler.integration.spec.ts
+++ b/tools/cli/src/commands/migrate/v8-to-v9/__tests__/handler.integration.spec.ts
@@ -2,7 +2,7 @@ import * as fs from 'fs/promises';
 import * as os from 'os';
 import * as path from 'path';
 import { analyzeFiles } from '../utils/annotator';
-import { writeAnnotations } from '../utils/annotator/writer';
+import { writeAnnotations } from '../utils/annotator';
 import { handler } from '../handler';
 
 const FIXTURES_DIR = path.join(__dirname, 'fixtures');
@@ -48,6 +48,7 @@ describe('migrate v8-to-v9 — integration', () => {
       const results = await analyzeFiles(tmpDir);
 
       expect(results).toHaveLength(1);
+      expect(results[0].filePath).toContain('import-paths.tsx');
       const importAnnotations = results[0].annotations.filter(a => a.codemod === 'import-paths');
       expect(importAnnotations.length).toBeGreaterThan(0);
       expect(importAnnotations[0].action).toBe('auto');
@@ -62,10 +63,14 @@ describe('migrate v8-to-v9 — integration', () => {
       expect(results).toHaveLength(1);
       const variants = results[0].annotations.filter(a => a.codemod === 'button-variants');
       expect(variants.length).toBe(4);
-      expect(variants.some(a => a.payload.includes('PrimaryButton'))).toBe(true);
-      expect(variants.some(a => a.payload.includes('DefaultButton'))).toBe(true);
-      expect(variants.some(a => a.payload.includes('ActionButton'))).toBe(true);
-      expect(variants.some(a => a.payload.includes('IconButton'))).toBe(true);
+      expect(variants.map(a => a.payload)).toMatchInlineSnapshot(`
+        Array [
+          "PrimaryButton → Button appearance=\\"primary\\"",
+          "DefaultButton → Button",
+          "ActionButton → Button appearance=\\"transparent\\"",
+          "IconButton → Button (icon-only)",
+        ]
+      `);
       expect(variants.every(a => a.action === 'auto')).toBe(true);
     });
 
@@ -86,8 +91,9 @@ describe('migrate v8-to-v9 — integration', () => {
       const results = await analyzeFiles(tmpDir);
 
       expect(results).toHaveLength(1);
-      const noEquiv = results[0].annotations.filter(a => a.action === 'no-equivalent');
+      const noEquiv = results[0].annotations.filter(a => a.codemod === 'no-equivalent');
       expect(noEquiv.length).toBeGreaterThanOrEqual(2);
+      expect(noEquiv.every(a => a.action === 'no-equivalent')).toBe(true);
     });
 
     it('detects prop-rename annotations for legacy ARIA props', async () => {
@@ -98,8 +104,8 @@ describe('migrate v8-to-v9 — integration', () => {
       expect(results).toHaveLength(1);
       const propAnnotations = results[0].annotations.filter(a => a.codemod === 'prop-rename');
       expect(propAnnotations.length).toBeGreaterThanOrEqual(2);
-      expect(propAnnotations.some(a => a.payload.includes('ariaLabel'))).toBe(true);
-      expect(propAnnotations.some(a => a.payload.includes('componentRef'))).toBe(true);
+      expect(propAnnotations.some(a => a.payload === 'ariaLabel → aria-label')).toBe(true);
+      expect(propAnnotations.some(a => a.payload === 'componentRef → ref')).toBe(true);
     });
 
     it('detects icon-props annotation with auto action for a known icon name', async () => {
@@ -250,6 +256,18 @@ describe('migrate v8-to-v9 — integration', () => {
         "
       `);
     });
+
+    it('writes metadata.json listing annotated file paths when projectRoot is provided', async () => {
+      await copyFixture(tmpDir, 'import-paths.tsx');
+
+      const results = await analyzeFiles(tmpDir);
+      await writeAnnotations(results, tmpDir);
+
+      const metaContent = await fs.readFile(path.join(tmpDir, '.fluent-migrate', 'metadata.json'), 'utf8');
+      const meta = JSON.parse(metaContent);
+      expect(meta.version).toBe(1);
+      expect(meta.annotatedFiles).toEqual(['import-paths.tsx']);
+    });
   });
 
   // ── handler end-to-end ───────────────────────────────────────────────────────
@@ -269,7 +287,7 @@ describe('migrate v8-to-v9 — integration', () => {
       logSpy.mockRestore();
     });
 
-    it('dry-run does not modify files', async () => {
+    it('dryRun does not modify files', async () => {
       const filePath = await copyFixture(tmpDir, 'import-paths.tsx');
       const original = await fs.readFile(filePath, 'utf8');
 
@@ -279,12 +297,12 @@ describe('migrate v8-to-v9 — integration', () => {
       expect(after).toBe(original);
     });
 
-    it('dry-run prints [dry-run] header and lists files that would be annotated', async () => {
+    it('dryRun prints [dryRun] header and lists files that would be annotated', async () => {
       await copyFixture(tmpDir, 'import-paths.tsx');
 
       await handler({ path: tmpDir, dryRun: true, _: [], $0: 'fluentui-cli' });
 
-      expect(logs.some(l => l.includes('[dry-run]'))).toBe(true);
+      expect(logs.some(l => l.includes('[dryRun]'))).toBe(true);
       expect(logs.some(l => l.includes('import-paths.tsx'))).toBe(true);
     });
 
@@ -294,7 +312,7 @@ describe('migrate v8-to-v9 — integration', () => {
       await handler({ path: tmpDir, dryRun: false, _: [], $0: 'fluentui-cli' });
 
       const content = await fs.readFile(filePath, 'utf8');
-      expect(content).toContain('// @fluent-migrate:');
+      expect(content).toContain('// @fluent-migrate:auto | import-paths |');
       expect(logs.some(l => l.includes('Annotated'))).toBe(true);
     });
 
@@ -313,5 +331,16 @@ describe('migrate v8-to-v9 — integration', () => {
 
       expect(logs.some(l => l.includes('Annotated 0 files'))).toBe(true);
     });
+
+    it('write mode emits .fluent-migrate/metadata.json', async () => {
+      await copyFixture(tmpDir, 'import-paths.tsx');
+
+      await handler({ path: tmpDir, dryRun: false, _: [], $0: 'fluentui-cli' });
+
+      const metaPath = path.join(tmpDir, '.fluent-migrate', 'metadata.json');
+      const meta = JSON.parse(await fs.readFile(metaPath, 'utf8'));
+      expect(meta.version).toBe(1);
+      expect(meta.annotatedFiles).toContain('import-paths.tsx');
+    });
   });
 });
diff --git a/tools/cli/src/commands/migrate/v8-to-v9/__tests__/handler.spec.ts b/tools/cli/src/commands/migrate/v8-to-v9/__tests__/handler.spec.ts
index c4845e5c74fcec..a00c8c8b2d900b 100644
--- a/tools/cli/src/commands/migrate/v8-to-v9/__tests__/handler.spec.ts
+++ b/tools/cli/src/commands/migrate/v8-to-v9/__tests__/handler.spec.ts
@@ -1,12 +1,10 @@
 import { handler } from '../handler';
 import * as annotator from '../utils/annotator';
-import * as writer from '../utils/annotator/writer';
 
 jest.mock('../utils/annotator');
-jest.mock('../utils/annotator/writer');
 
 const mockAnalyzeFiles = annotator.analyzeFiles as jest.MockedFunction<typeof annotator.analyzeFiles>;
-const mockWriteAnnotations = writer.writeAnnotations as jest.MockedFunction<typeof writer.writeAnnotations>;
+const mockWriteAnnotations = annotator.writeAnnotations as jest.MockedFunction<typeof annotator.writeAnnotations>;
 
 describe('migrate v8-to-v9 handler', () => {
   let logSpy: jest.SpyInstance;
@@ -30,7 +28,7 @@ describe('migrate v8-to-v9 handler', () => {
     expect(mockWriteAnnotations).toHaveBeenCalled();
   });
 
-  it('skips writeAnnotations in dry-run mode', async () => {
+  it('skips writeAnnotations in dryRun mode', async () => {
     mockAnalyzeFiles.mockResolvedValue([]);
 
     await handler({ path: 'src/', dryRun: true, _: [], $0: 'fluentui-cli' });
@@ -59,7 +57,7 @@ describe('migrate v8-to-v9 handler', () => {
     expect(logSpy).toHaveBeenCalledWith(expect.stringContaining('manual'));
   });
 
-  it('prints [dry-run] preview without writing', async () => {
+  it('prints [dryRun] preview without writing', async () => {
     mockAnalyzeFiles.mockResolvedValue([
       {
         filePath: 'src/Button.tsx',
@@ -70,7 +68,7 @@ describe('migrate v8-to-v9 handler', () => {
 
     await handler({ path: 'src/', dryRun: true, _: [], $0: 'fluentui-cli' });
 
-    expect(logSpy).toHaveBeenCalledWith(expect.stringContaining('[dry-run]'));
+    expect(logSpy).toHaveBeenCalledWith(expect.stringContaining('[dryRun]'));
     expect(logSpy).toHaveBeenCalledWith(expect.stringContaining('@fluentui/react-components'));
     expect(mockWriteAnnotations).not.toHaveBeenCalled();
   });
diff --git a/tools/cli/src/commands/migrate/v8-to-v9/handler.ts b/tools/cli/src/commands/migrate/v8-to-v9/handler.ts
index b25855fca0cdbf..35da3d76a6d9c3 100644
--- a/tools/cli/src/commands/migrate/v8-to-v9/handler.ts
+++ b/tools/cli/src/commands/migrate/v8-to-v9/handler.ts
@@ -1,7 +1,6 @@
 import type { CommandHandler } from '../../../utils/types';
-import { analyzeFiles } from './utils/annotator';
-import { writeAnnotations } from './utils/annotator/writer';
-import type { FileAnalysis } from './utils/annotator/types';
+import { analyzeFiles, writeAnnotations } from './utils/annotator';
+import type { FileAnalysis } from './utils/annotator';
 
 interface V8ToV9Args {
   path: string;
@@ -16,7 +15,7 @@ export const handler: CommandHandler<V8ToV9Args> = async argv => {
     return;
   }
 
-  const { filesChanged } = await writeAnnotations(results);
+  const { filesChanged } = await writeAnnotations(results, argv.path);
   printSummary(results, filesChanged);
 };
 
@@ -24,10 +23,15 @@ function countByAction(results: FileAnalysis[]) {
   const counts = { auto: 0, scaffold: 0, manual: 0, noEquivalent: 0 };
   for (const file of results) {
     for (const a of file.annotations) {
-      if (a.action === 'auto') counts.auto++;
-      else if (a.action === 'scaffold') counts.scaffold++;
-      else if (a.action === 'manual') counts.manual++;
-      else if (a.action === 'no-equivalent') counts.noEquivalent++;
+      if (a.action === 'auto') {
+        counts.auto++;
+      } else if (a.action === 'scaffold') {
+        counts.scaffold++;
+      } else if (a.action === 'manual') {
+        counts.manual++;
+      } else if (a.action === 'no-equivalent') {
+        counts.noEquivalent++;
+      }
     }
   }
   return counts;
@@ -69,7 +73,7 @@ function printDryRunReport(results: FileAnalysis[]): void {
   const counts = countByAction(results);
   const deps = collectDeps(results);
 
-  console.log('\n[dry-run] No files were modified.\n');
+  console.log('\n[dryRun] No files were modified.\n');
   console.log(`Would annotate ${results.length} files`);
   console.log(`  auto          ${counts.auto.toString().padStart(4)}  (safe to apply mechanically)`);
   console.log(`  scaffold      ${counts.scaffold.toString().padStart(4)}  (boilerplate needed)`);
diff --git a/tools/cli/src/commands/migrate/v8-to-v9/index.ts b/tools/cli/src/commands/migrate/v8-to-v9/index.ts
index b6763a861bac68..a4424b73432b03 100644
--- a/tools/cli/src/commands/migrate/v8-to-v9/index.ts
+++ b/tools/cli/src/commands/migrate/v8-to-v9/index.ts
@@ -15,7 +15,7 @@ const command: CommandModule<{}, V8ToV9Args> = {
         demandOption: true,
         describe: 'Source root to annotate (e.g. src/, app/, packages/my-app/src)',
       })
-      .option('dry-run', {
+      .option('dryRun', {
         type: 'boolean',
         default: false,
         describe: 'Preview annotations without writing files',
diff --git a/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/analyzer.ts b/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/analyzer.ts
new file mode 100644
index 00000000000000..629ca47119b7bb
--- /dev/null
+++ b/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/analyzer.ts
@@ -0,0 +1,103 @@
+import * as glob from 'fast-glob';
+import * as path from 'path';
+import { Project } from 'ts-morph';
+import type { SourceFile } from 'ts-morph';
+
+import type { FileAnalysis, AnnotationResult } from './types';
+import { getFluentImportNames } from './rules/utils';
+import { detectImportPaths } from './rules/import-paths';
+import { detectComponentRenames } from './rules/component-rename';
+import { detectButtonVariants } from './rules/button-variants';
+import { detectPropRenames } from './rules/prop-rename';
+import { detectRemoveThemeProp } from './rules/remove-theme-prop';
+import { detectDialogProps } from './rules/dialog-props';
+import { detectEnumToString } from './rules/enum-to-string';
+import { detectToggleProps } from './rules/toggle-props';
+import { detectProgressBarProps } from './rules/progress-bar-props';
+import { detectUseBoolean } from './rules/use-boolean';
+import { detectKeyCodes } from './rules/keycodes';
+import { detectGetId } from './rules/get-id';
+import { detectIconProps } from './rules/icon-props';
+import { detectLabelExtraction } from './rules/label-extraction';
+import { detectStylesProp } from './rules/styles-prop';
+import { detectNoEquivalent } from './rules/no-equivalent';
+
+type Rule = (sourceFile: SourceFile, fluentNames: Set<string>) => AnnotationResult[];
+
+const RULES: Rule[] = [
+  detectImportPaths,
+  detectComponentRenames,
+  detectButtonVariants,
+  detectPropRenames,
+  detectRemoveThemeProp,
+  detectDialogProps,
+  detectEnumToString,
+  detectToggleProps,
+  detectProgressBarProps,
+  detectUseBoolean,
+  detectKeyCodes,
+  detectGetId,
+  detectIconProps,
+  detectLabelExtraction,
+  detectStylesProp,
+  detectNoEquivalent,
+];
+
+const DEP_REQUIREMENTS: Array<{ name: string; reason: string; triggerCodemod: string }> = [
+  {
+    name: '@fluentui/react-components',
+    reason: 'core v9 components',
+    triggerCodemod: 'import-paths',
+  },
+  {
+    name: '@fluentui/react-icons',
+    reason: 'SVG icon components (needed: icon-props migrations found)',
+    triggerCodemod: 'icon-props',
+  },
+];
+
+/**
+ * Pure detection engine — no file I/O.
+ * Both migrate and dryRun call this.
+ */
+export async function analyzeFiles(sourcePath: string): Promise<FileAnalysis[]> {
+  const absoluteSource = path.resolve(sourcePath);
+
+  const filePaths = await glob.glob(['**/*.ts', '**/*.tsx'], {
+    cwd: absoluteSource,
+    absolute: true,
+    ignore: ['**/node_modules/**', '**/*.d.ts'],
+  });
+
+  const project = new Project({ skipAddingFilesFromTsConfig: true });
+  project.addSourceFilesAtPaths(filePaths);
+
+  const results: FileAnalysis[] = [];
+
+  for (const sourceFile of project.getSourceFiles()) {
+    // Extract fluent import names once per file — passed to all rules to avoid repetitive work
+    const fluentNames = getFluentImportNames(sourceFile);
+    if (fluentNames.size === 0) {
+      continue;
+    }
+
+    const annotations = RULES.flatMap(rule => rule(sourceFile, fluentNames));
+    if (annotations.length === 0) {
+      continue;
+    }
+
+    // Determine which deps are needed based on detected codemods
+    const detectedCodemods = new Set(annotations.map(a => a.codemod));
+    const missingDeps = DEP_REQUIREMENTS.filter(dep => detectedCodemods.has(dep.triggerCodemod)).map(
+      ({ name, reason }) => ({ name, reason }),
+    );
+
+    results.push({
+      filePath: sourceFile.getFilePath(),
+      annotations,
+      missingDeps,
+    });
+  }
+
+  return results;
+}
diff --git a/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/index.ts b/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/index.ts
index b59f54ccee8407..3fd2ac563b1831 100644
--- a/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/index.ts
+++ b/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/index.ts
@@ -1,96 +1,3 @@
-import * as glob from 'fast-glob';
-import * as path from 'path';
-import { Project } from 'ts-morph';
-import type { FileAnalysis } from './types';
-import { detectImportPaths } from './rules/import-paths';
-import { detectComponentRenames } from './rules/component-rename';
-import { detectButtonVariants } from './rules/button-variants';
-import { detectPropRenames } from './rules/prop-rename';
-import { detectRemoveThemeProp } from './rules/remove-theme-prop';
-import { detectDialogProps } from './rules/dialog-props';
-import { detectEnumToString } from './rules/enum-to-string';
-import { detectToggleProps } from './rules/toggle-props';
-import { detectProgressBarProps } from './rules/progress-bar-props';
-import { detectUseBoolean } from './rules/use-boolean';
-import { detectKeyCodes } from './rules/keycodes';
-import { detectGetId } from './rules/get-id';
-import { detectIconProps } from './rules/icon-props';
-import { detectLabelExtraction } from './rules/label-extraction';
-import { detectStylesProp } from './rules/styles-prop';
-import { detectNoEquivalent } from './rules/no-equivalent';
-
-const RULES = [
-  detectImportPaths,
-  detectComponentRenames,
-  detectButtonVariants,
-  detectPropRenames,
-  detectRemoveThemeProp,
-  detectDialogProps,
-  detectEnumToString,
-  detectToggleProps,
-  detectProgressBarProps,
-  detectUseBoolean,
-  detectKeyCodes,
-  detectGetId,
-  detectIconProps,
-  detectLabelExtraction,
-  detectStylesProp,
-  detectNoEquivalent,
-];
-
-const DEP_REQUIREMENTS: Array<{ name: string; reason: string; triggerCodemod: string }> = [
-  {
-    name: '@fluentui/react-components',
-    reason: 'core v9 components',
-    triggerCodemod: 'import-paths',
-  },
-  {
-    name: '@fluentui/react-icons',
-    reason: 'SVG icon components (needed: icon-props migrations found)',
-    triggerCodemod: 'icon-props',
-  },
-];
-
-/**
- * Pure detection engine — no file I/O.
- * Both migrate and dry-run call this.
- */
-export async function analyzeFiles(sourcePath: string): Promise<FileAnalysis[]> {
-  const absoluteSource = path.resolve(sourcePath);
-
-  const filePaths = await glob.glob(['**/*.ts', '**/*.tsx'], {
-    cwd: absoluteSource,
-    absolute: true,
-    ignore: ['**/node_modules/**', '**/*.d.ts'],
-  });
-
-  const project = new Project({ skipAddingFilesFromTsConfig: true });
-  project.addSourceFilesAtPaths(filePaths);
-
-  const results: FileAnalysis[] = [];
-
-  for (const sourceFile of project.getSourceFiles()) {
-    // Skip files with no @fluentui/react imports (already migrated or unrelated)
-    const hasFluentImport = sourceFile
-      .getImportDeclarations()
-      .some(d => d.getModuleSpecifierValue() === '@fluentui/react');
-    if (!hasFluentImport) continue;
-
-    const annotations = RULES.flatMap(rule => rule(sourceFile));
-    if (annotations.length === 0) continue;
-
-    // Determine which deps are needed based on detected codemods
-    const detectedCodemods = new Set(annotations.map(a => a.codemod));
-    const missingDeps = DEP_REQUIREMENTS.filter(dep => detectedCodemods.has(dep.triggerCodemod)).map(
-      ({ name, reason }) => ({ name, reason }),
-    );
-
-    results.push({
-      filePath: sourceFile.getFilePath(),
-      annotations,
-      missingDeps,
-    });
-  }
-
-  return results;
-}
+export type { FileAnalysis } from './types';
+export { writeAnnotations } from './writer';
+export { analyzeFiles } from './analyzer';
diff --git a/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/button-variants.ts b/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/button-variants.ts
index 5eb4862e82a99c..2e8cf8dec2d03a 100644
--- a/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/button-variants.ts
+++ b/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/button-variants.ts
@@ -1,7 +1,7 @@
 import type { SourceFile, Node } from 'ts-morph';
 import { SyntaxKind } from 'ts-morph';
 import type { AnnotationResult } from '../types';
-import { getFluentImportNames, isJsxChild } from './utils';
+import { isJsxChild } from './utils';
 
 const BUTTON_VARIANTS: Record<string, string> = {
   PrimaryButton: 'Button appearance="primary"',
@@ -11,9 +11,8 @@ const BUTTON_VARIANTS: Record<string, string> = {
   CompoundButton: 'CompoundButton',
 };
 
-export function detectButtonVariants(sourceFile: SourceFile): AnnotationResult[] {
+export function detectButtonVariants(sourceFile: SourceFile, fluentNames: Set<string>): AnnotationResult[] {
   const results: AnnotationResult[] = [];
-  const fluentNames = getFluentImportNames(sourceFile);
 
   sourceFile.forEachDescendant((node: Node) => {
     if (node.getKind() !== SyntaxKind.JsxOpeningElement && node.getKind() !== SyntaxKind.JsxSelfClosingElement) {
@@ -21,7 +20,9 @@ export function detectButtonVariants(sourceFile: SourceFile): AnnotationResult[]
     }
 
     const tagName = node.getFirstChildByKind(SyntaxKind.Identifier)?.getText() ?? '';
-    if (!fluentNames.has(tagName) || !BUTTON_VARIANTS[tagName]) return;
+    if (!fluentNames.has(tagName) || !BUTTON_VARIANTS[tagName]) {
+      return;
+    }
 
     const line = node.getStartLineNumber();
     const insideJsx = isJsxChild(node);
diff --git a/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/component-rename.ts b/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/component-rename.ts
index d9f5973bba0f24..d70847ba54c46e 100644
--- a/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/component-rename.ts
+++ b/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/component-rename.ts
@@ -1,7 +1,7 @@
 import type { SourceFile, Node } from 'ts-morph';
 import { SyntaxKind } from 'ts-morph';
 import type { AnnotationResult } from '../types';
-import { getFluentImportNames, isJsxChild } from './utils';
+import { isJsxChild } from './utils';
 
 /** 1→1 renames that are safe to apply automatically. */
 const AUTO_RENAMES: Record<string, string> = {
@@ -32,9 +32,8 @@ const MANUAL_RENAMES: Record<string, { choices: string; ref: string }> = {
   },
 };
 
-export function detectComponentRenames(sourceFile: SourceFile): AnnotationResult[] {
+export function detectComponentRenames(sourceFile: SourceFile, fluentNames: Set<string>): AnnotationResult[] {
   const results: AnnotationResult[] = [];
-  const fluentNames = getFluentImportNames(sourceFile);
 
   sourceFile.forEachDescendant((node: Node) => {
     if (node.getKind() !== SyntaxKind.JsxOpeningElement && node.getKind() !== SyntaxKind.JsxSelfClosingElement) {
@@ -42,7 +41,9 @@ export function detectComponentRenames(sourceFile: SourceFile): AnnotationResult
     }
 
     const tagName = node.getFirstChildByKind(SyntaxKind.Identifier)?.getText() ?? '';
-    if (!fluentNames.has(tagName)) return;
+    if (!fluentNames.has(tagName)) {
+      return;
+    }
 
     const insideJsx = isJsxChild(node);
 
diff --git a/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/dialog-props.ts b/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/dialog-props.ts
index fb613971a1484d..2523e6b2a59e47 100644
--- a/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/dialog-props.ts
+++ b/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/dialog-props.ts
@@ -1,13 +1,11 @@
 import type { SourceFile, Node } from 'ts-morph';
 import { SyntaxKind } from 'ts-morph';
 import type { AnnotationResult } from '../types';
-import { getFluentImportNames } from './utils';
 
 const DIALOG_COMPONENTS = new Set(['Dialog', 'Modal']);
 
-export function detectDialogProps(sourceFile: SourceFile): AnnotationResult[] {
+export function detectDialogProps(sourceFile: SourceFile, fluentNames: Set<string>): AnnotationResult[] {
   const results: AnnotationResult[] = [];
-  const fluentNames = getFluentImportNames(sourceFile);
 
   sourceFile.forEachDescendant((node: Node) => {
     if (node.getKind() !== SyntaxKind.JsxOpeningElement && node.getKind() !== SyntaxKind.JsxSelfClosingElement) {
@@ -15,7 +13,9 @@ export function detectDialogProps(sourceFile: SourceFile): AnnotationResult[] {
     }
 
     const tagName = node.getFirstChildByKind(SyntaxKind.Identifier)?.getText() ?? '';
-    if (!fluentNames.has(tagName) || !DIALOG_COMPONENTS.has(tagName)) return;
+    if (!fluentNames.has(tagName) || !DIALOG_COMPONENTS.has(tagName)) {
+      return;
+    }
 
     for (const attr of node.getDescendantsOfKind(SyntaxKind.JsxAttribute)) {
       const propName = attr.getFirstChildByKind(SyntaxKind.Identifier)?.getText() ?? '';
diff --git a/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/enum-to-string.ts b/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/enum-to-string.ts
index af1f5892f3944c..84309b6f3ce25f 100644
--- a/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/enum-to-string.ts
+++ b/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/enum-to-string.ts
@@ -33,13 +33,17 @@ export function detectEnumToString(sourceFile: SourceFile): AnnotationResult[] {
   const results: AnnotationResult[] = [];
 
   sourceFile.forEachDescendant((node: Node) => {
-    if (node.getKind() !== SyntaxKind.PropertyAccessExpression) return;
+    if (node.getKind() !== SyntaxKind.PropertyAccessExpression) {
+      return;
+    }
 
     const children = node.getChildren();
     const left = children[0]?.getText() ?? '';
     const right = children[children.length - 1]?.getText() ?? '';
 
-    if (!KNOWN_ENUM_MEMBERS[left]) return;
+    if (!KNOWN_ENUM_MEMBERS[left]) {
+      return;
+    }
 
     const stringValue = KNOWN_ENUM_MEMBERS[left][right];
     const line = node.getStartLineNumber();
diff --git a/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/get-id.ts b/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/get-id.ts
index 765906552822f1..dd5fd95622fb9d 100644
--- a/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/get-id.ts
+++ b/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/get-id.ts
@@ -13,13 +13,19 @@ export function detectGetId(sourceFile: SourceFile): AnnotationResult[] {
         decl.getModuleSpecifierValue() === '@fluentui/react' &&
         decl.getNamedImports().some(s => s.getName() === 'getId'),
     );
-  if (!hasGetIdImport) return results;
+  if (!hasGetIdImport) {
+    return results;
+  }
 
   sourceFile.forEachDescendant((node: Node) => {
-    if (node.getKind() !== SyntaxKind.CallExpression) return;
+    if (node.getKind() !== SyntaxKind.CallExpression) {
+      return;
+    }
 
     const expr = node.getFirstChild();
-    if (expr?.getText() !== 'getId') return;
+    if (expr?.getText() !== 'getId') {
+      return;
+    }
 
     const line = node.getStartLineNumber();
     const insideComponent = isInFunctionComponent(node);
diff --git a/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/icon-props.ts b/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/icon-props.ts
index 05ca3ccfee669c..1421bd3f842a3c 100644
--- a/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/icon-props.ts
+++ b/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/icon-props.ts
@@ -1,7 +1,6 @@
 import type { SourceFile, Node } from 'ts-morph';
 import { SyntaxKind } from 'ts-morph';
 import type { AnnotationResult } from '../types';
-import { getFluentImportNames } from './utils';
 
 // Known icon names that have a direct @fluentui/react-icons equivalent (subset)
 const KNOWN_ICONS = new Set([
@@ -42,9 +41,8 @@ const KNOWN_ICONS = new Set([
   'Close',
 ]);
 
-export function detectIconProps(sourceFile: SourceFile): AnnotationResult[] {
+export function detectIconProps(sourceFile: SourceFile, fluentNames: Set<string>): AnnotationResult[] {
   const results: AnnotationResult[] = [];
-  const fluentNames = getFluentImportNames(sourceFile);
 
   sourceFile.forEachDescendant((node: Node) => {
     if (node.getKind() !== SyntaxKind.JsxOpeningElement && node.getKind() !== SyntaxKind.JsxSelfClosingElement) {
@@ -52,11 +50,15 @@ export function detectIconProps(sourceFile: SourceFile): AnnotationResult[] {
     }
 
     const tagName = node.getFirstChildByKind(SyntaxKind.Identifier)?.getText() ?? '';
-    if (!fluentNames.has(tagName)) return;
+    if (!fluentNames.has(tagName)) {
+      return;
+    }
 
     for (const attr of node.getDescendantsOfKind(SyntaxKind.JsxAttribute)) {
       const propName = attr.getFirstChildByKind(SyntaxKind.Identifier)?.getText() ?? '';
-      if (propName !== 'iconProps') continue;
+      if (propName !== 'iconProps') {
+        continue;
+      }
 
       const line = attr.getStartLineNumber();
 
diff --git a/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/keycodes.ts b/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/keycodes.ts
index 17cc8cbd3f92d0..692189af1e8764 100644
--- a/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/keycodes.ts
+++ b/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/keycodes.ts
@@ -31,16 +31,22 @@ export function detectKeyCodes(sourceFile: SourceFile): AnnotationResult[] {
         decl.getModuleSpecifierValue() === '@fluentui/react' &&
         decl.getNamedImports().some(s => s.getName() === 'KeyCodes'),
     );
-  if (!hasKeyCodesImport) return results;
+  if (!hasKeyCodesImport) {
+    return results;
+  }
 
   sourceFile.forEachDescendant((node: Node) => {
-    if (node.getKind() !== SyntaxKind.PropertyAccessExpression) return;
+    if (node.getKind() !== SyntaxKind.PropertyAccessExpression) {
+      return;
+    }
 
     const children = node.getChildren();
     const left = children[0]?.getText() ?? '';
     const right = children[children.length - 1]?.getText() ?? '';
 
-    if (left !== 'KeyCodes') return;
+    if (left !== 'KeyCodes') {
+      return;
+    }
 
     const line = node.getStartLineNumber();
     const keyValue = KNOWN_KEYCODES[right];
diff --git a/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/label-extraction.ts b/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/label-extraction.ts
index 80e7a5a01364be..e2c733c7329604 100644
--- a/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/label-extraction.ts
+++ b/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/label-extraction.ts
@@ -1,13 +1,11 @@
 import type { SourceFile, Node } from 'ts-morph';
 import { SyntaxKind } from 'ts-morph';
 import type { AnnotationResult } from '../types';
-import { getFluentImportNames } from './utils';
 
 const LABEL_COMPONENTS = new Set(['TextField', 'SpinButton', 'Slider', 'ChoiceGroup']);
 
-export function detectLabelExtraction(sourceFile: SourceFile): AnnotationResult[] {
+export function detectLabelExtraction(sourceFile: SourceFile, fluentNames: Set<string>): AnnotationResult[] {
   const results: AnnotationResult[] = [];
-  const fluentNames = getFluentImportNames(sourceFile);
 
   sourceFile.forEachDescendant((node: Node) => {
     if (node.getKind() !== SyntaxKind.JsxOpeningElement && node.getKind() !== SyntaxKind.JsxSelfClosingElement) {
@@ -15,7 +13,9 @@ export function detectLabelExtraction(sourceFile: SourceFile): AnnotationResult[
     }
 
     const tagName = node.getFirstChildByKind(SyntaxKind.Identifier)?.getText() ?? '';
-    if (!fluentNames.has(tagName) || !LABEL_COMPONENTS.has(tagName)) return;
+    if (!fluentNames.has(tagName) || !LABEL_COMPONENTS.has(tagName)) {
+      return;
+    }
 
     for (const attr of node.getDescendantsOfKind(SyntaxKind.JsxAttribute)) {
       const propName = attr.getFirstChildByKind(SyntaxKind.Identifier)?.getText() ?? '';
diff --git a/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/no-equivalent.ts b/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/no-equivalent.ts
index c0b242f7983093..28d4dc84377c8d 100644
--- a/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/no-equivalent.ts
+++ b/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/no-equivalent.ts
@@ -1,7 +1,7 @@
 import type { SourceFile, Node } from 'ts-morph';
 import { SyntaxKind } from 'ts-morph';
 import type { AnnotationResult } from '../types';
-import { getFluentImportNames, isJsxChild } from './utils';
+import { isJsxChild } from './utils';
 
 const DEPRECATED_COMPONENTS: Record<string, string> = {
   ActivityItem: 'build with Avatar + Text + makeStyles flexbox — see SKILL.md deprecation list',
@@ -12,9 +12,8 @@ const DEPRECATED_COMPONENTS: Record<string, string> = {
   Announced: 'use a visually-hidden live region: <div role="status" aria-live="polite">',
 };
 
-export function detectNoEquivalent(sourceFile: SourceFile): AnnotationResult[] {
+export function detectNoEquivalent(sourceFile: SourceFile, fluentNames: Set<string>): AnnotationResult[] {
   const results: AnnotationResult[] = [];
-  const fluentNames = getFluentImportNames(sourceFile);
 
   sourceFile.forEachDescendant((node: Node) => {
     if (node.getKind() !== SyntaxKind.JsxOpeningElement && node.getKind() !== SyntaxKind.JsxSelfClosingElement) {
@@ -22,7 +21,9 @@ export function detectNoEquivalent(sourceFile: SourceFile): AnnotationResult[] {
     }
 
     const tagName = node.getFirstChildByKind(SyntaxKind.Identifier)?.getText() ?? '';
-    if (!fluentNames.has(tagName) || !DEPRECATED_COMPONENTS[tagName]) return;
+    if (!fluentNames.has(tagName) || !DEPRECATED_COMPONENTS[tagName]) {
+      return;
+    }
 
     results.push({
       action: 'no-equivalent',
diff --git a/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/progress-bar-props.ts b/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/progress-bar-props.ts
index 5c9facb56f45f3..bf7a43a8cfc960 100644
--- a/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/progress-bar-props.ts
+++ b/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/progress-bar-props.ts
@@ -1,11 +1,9 @@
 import type { SourceFile, Node } from 'ts-morph';
 import { SyntaxKind } from 'ts-morph';
 import type { AnnotationResult } from '../types';
-import { getFluentImportNames } from './utils';
 
-export function detectProgressBarProps(sourceFile: SourceFile): AnnotationResult[] {
+export function detectProgressBarProps(sourceFile: SourceFile, fluentNames: Set<string>): AnnotationResult[] {
   const results: AnnotationResult[] = [];
-  const fluentNames = getFluentImportNames(sourceFile);
 
   sourceFile.forEachDescendant((node: Node) => {
     if (node.getKind() !== SyntaxKind.JsxOpeningElement && node.getKind() !== SyntaxKind.JsxSelfClosingElement) {
@@ -13,7 +11,9 @@ export function detectProgressBarProps(sourceFile: SourceFile): AnnotationResult
     }
 
     const tagName = node.getFirstChildByKind(SyntaxKind.Identifier)?.getText() ?? '';
-    if (!fluentNames.has(tagName) || tagName !== 'ProgressIndicator') return;
+    if (!fluentNames.has(tagName) || tagName !== 'ProgressIndicator') {
+      return;
+    }
 
     for (const attr of node.getDescendantsOfKind(SyntaxKind.JsxAttribute)) {
       const propName = attr.getFirstChildByKind(SyntaxKind.Identifier)?.getText() ?? '';
diff --git a/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/prop-rename.ts b/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/prop-rename.ts
index 0313f18880a43b..66f526c292fcd2 100644
--- a/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/prop-rename.ts
+++ b/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/prop-rename.ts
@@ -1,7 +1,6 @@
 import type { SourceFile, Node } from 'ts-morph';
 import { SyntaxKind } from 'ts-morph';
 import type { AnnotationResult } from '../types';
-import { getFluentImportNames } from './utils';
 
 const PROP_RENAMES: Record<string, string> = {
   ariaLabel: 'aria-label',
@@ -13,9 +12,8 @@ const PROP_RENAMES: Record<string, string> = {
   componentRef: 'ref',
 };
 
-export function detectPropRenames(sourceFile: SourceFile): AnnotationResult[] {
+export function detectPropRenames(sourceFile: SourceFile, fluentNames: Set<string>): AnnotationResult[] {
   const results: AnnotationResult[] = [];
-  const fluentNames = getFluentImportNames(sourceFile);
 
   sourceFile.forEachDescendant((node: Node) => {
     if (node.getKind() !== SyntaxKind.JsxOpeningElement && node.getKind() !== SyntaxKind.JsxSelfClosingElement) {
@@ -23,7 +21,9 @@ export function detectPropRenames(sourceFile: SourceFile): AnnotationResult[] {
     }
 
     const tagName = node.getFirstChildByKind(SyntaxKind.Identifier)?.getText() ?? '';
-    if (!fluentNames.has(tagName)) return;
+    if (!fluentNames.has(tagName)) {
+      return;
+    }
 
     for (const attr of node.getDescendantsOfKind(SyntaxKind.JsxAttribute)) {
       const propName = attr.getFirstChildByKind(SyntaxKind.Identifier)?.getText() ?? '';
diff --git a/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/remove-theme-prop.ts b/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/remove-theme-prop.ts
index 879eaa487a8861..d2ef452458c471 100644
--- a/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/remove-theme-prop.ts
+++ b/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/remove-theme-prop.ts
@@ -1,11 +1,9 @@
 import type { SourceFile, Node } from 'ts-morph';
 import { SyntaxKind } from 'ts-morph';
 import type { AnnotationResult } from '../types';
-import { getFluentImportNames } from './utils';
 
-export function detectRemoveThemeProp(sourceFile: SourceFile): AnnotationResult[] {
+export function detectRemoveThemeProp(sourceFile: SourceFile, fluentNames: Set<string>): AnnotationResult[] {
   const results: AnnotationResult[] = [];
-  const fluentNames = getFluentImportNames(sourceFile);
 
   sourceFile.forEachDescendant((node: Node) => {
     if (node.getKind() !== SyntaxKind.JsxOpeningElement && node.getKind() !== SyntaxKind.JsxSelfClosingElement) {
@@ -13,11 +11,15 @@ export function detectRemoveThemeProp(sourceFile: SourceFile): AnnotationResult[
     }
 
     const tagName = node.getFirstChildByKind(SyntaxKind.Identifier)?.getText() ?? '';
-    if (!fluentNames.has(tagName)) return;
+    if (!fluentNames.has(tagName)) {
+      return;
+    }
 
     for (const attr of node.getDescendantsOfKind(SyntaxKind.JsxAttribute)) {
       const propName = attr.getFirstChildByKind(SyntaxKind.Identifier)?.getText() ?? '';
-      if (propName !== 'theme') continue;
+      if (propName !== 'theme') {
+        continue;
+      }
 
       // Non-trivial: value is an expression that isn't a bare identifier
       const initializer = attr.getInitializer();
diff --git a/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/styles-prop.ts b/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/styles-prop.ts
index deddc73a551066..2bc2e9ecee0d86 100644
--- a/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/styles-prop.ts
+++ b/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/styles-prop.ts
@@ -1,11 +1,9 @@
 import type { SourceFile, Node } from 'ts-morph';
 import { SyntaxKind } from 'ts-morph';
 import type { AnnotationResult } from '../types';
-import { getFluentImportNames } from './utils';
 
-export function detectStylesProp(sourceFile: SourceFile): AnnotationResult[] {
+export function detectStylesProp(sourceFile: SourceFile, fluentNames: Set<string>): AnnotationResult[] {
   const results: AnnotationResult[] = [];
-  const fluentNames = getFluentImportNames(sourceFile);
 
   sourceFile.forEachDescendant((node: Node) => {
     if (node.getKind() !== SyntaxKind.JsxOpeningElement && node.getKind() !== SyntaxKind.JsxSelfClosingElement) {
@@ -13,11 +11,15 @@ export function detectStylesProp(sourceFile: SourceFile): AnnotationResult[] {
     }
 
     const tagName = node.getFirstChildByKind(SyntaxKind.Identifier)?.getText() ?? '';
-    if (!fluentNames.has(tagName)) return;
+    if (!fluentNames.has(tagName)) {
+      return;
+    }
 
     for (const attr of node.getDescendantsOfKind(SyntaxKind.JsxAttribute)) {
       const propName = attr.getFirstChildByKind(SyntaxKind.Identifier)?.getText() ?? '';
-      if (propName !== 'styles') continue;
+      if (propName !== 'styles') {
+        continue;
+      }
 
       results.push({
         action: 'scaffold',
diff --git a/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/toggle-props.ts b/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/toggle-props.ts
index a6948179dd6037..79cf0619c47c5c 100644
--- a/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/toggle-props.ts
+++ b/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/toggle-props.ts
@@ -1,11 +1,9 @@
 import type { SourceFile, Node } from 'ts-morph';
 import { SyntaxKind } from 'ts-morph';
 import type { AnnotationResult } from '../types';
-import { getFluentImportNames } from './utils';
 
-export function detectToggleProps(sourceFile: SourceFile): AnnotationResult[] {
+export function detectToggleProps(sourceFile: SourceFile, fluentNames: Set<string>): AnnotationResult[] {
   const results: AnnotationResult[] = [];
-  const fluentNames = getFluentImportNames(sourceFile);
 
   sourceFile.forEachDescendant((node: Node) => {
     if (node.getKind() !== SyntaxKind.JsxOpeningElement && node.getKind() !== SyntaxKind.JsxSelfClosingElement) {
@@ -13,7 +11,9 @@ export function detectToggleProps(sourceFile: SourceFile): AnnotationResult[] {
     }
 
     const tagName = node.getFirstChildByKind(SyntaxKind.Identifier)?.getText() ?? '';
-    if (!fluentNames.has(tagName) || tagName !== 'Toggle') return;
+    if (!fluentNames.has(tagName) || tagName !== 'Toggle') {
+      return;
+    }
 
     for (const attr of node.getDescendantsOfKind(SyntaxKind.JsxAttribute)) {
       const propName = attr.getFirstChildByKind(SyntaxKind.Identifier)?.getText() ?? '';
diff --git a/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/use-boolean.ts b/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/use-boolean.ts
index 436e092658d83d..1668716c361554 100644
--- a/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/use-boolean.ts
+++ b/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/use-boolean.ts
@@ -13,13 +13,19 @@ export function detectUseBoolean(sourceFile: SourceFile): AnnotationResult[] {
         decl.getModuleSpecifierValue() === '@fluentui/react' &&
         decl.getNamedImports().some(s => s.getName() === 'useBoolean'),
     );
-  if (!hasUseBooleanImport) return results;
+  if (!hasUseBooleanImport) {
+    return results;
+  }
 
   sourceFile.forEachDescendant((node: Node) => {
-    if (node.getKind() !== SyntaxKind.CallExpression) return;
+    if (node.getKind() !== SyntaxKind.CallExpression) {
+      return;
+    }
 
     const expr = node.getFirstChild();
-    if (expr?.getText() !== 'useBoolean') return;
+    if (expr?.getText() !== 'useBoolean') {
+      return;
+    }
 
     const line = node.getStartLineNumber();
 
diff --git a/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/writer.ts b/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/writer.ts
index cba70b4334ea72..1fc6ca6c3c341a 100644
--- a/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/writer.ts
+++ b/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/writer.ts
@@ -1,11 +1,16 @@
 import * as fs from 'fs/promises';
+import * as path from 'path';
 import type { FileAnalysis, AnnotationResult } from './types';
 
 const ANNOTATION_TAG = '@fluent-migrate:';
+const METADATA_DIR = '.fluent-migrate';
+const METADATA_FILE = 'metadata.json';
 
 function formatAnnotation(a: AnnotationResult): string {
   const parts = [a.action, a.codemod, a.payload];
-  if (a.note) parts.push(a.note);
+  if (a.note) {
+    parts.push(a.note);
+  }
   const body = `${ANNOTATION_TAG}${parts.join(' | ')}`;
   return a.insideJsx ? `{/* ${body} */}` : `// ${body}`;
 }
@@ -13,12 +18,21 @@ function formatAnnotation(a: AnnotationResult): string {
 /**
  * Inserts @fluent-migrate: comments into source files based on FileAnalysis results.
  * Idempotent: skips if an identical comment already exists on the line above the target.
+ *
+ * When `projectRoot` is provided, writes `.fluent-migrate/metadata.json` listing
+ * all annotated file paths so the skill can locate them without re-scanning.
  */
-export async function writeAnnotations(results: FileAnalysis[]): Promise<{ filesChanged: number }> {
+export async function writeAnnotations(
+  results: FileAnalysis[],
+  projectRoot?: string,
+): Promise<{ filesChanged: number }> {
   let filesChanged = 0;
+  const annotatedFiles: string[] = [];
 
   for (const file of results) {
-    if (file.annotations.length === 0) continue;
+    if (file.annotations.length === 0) {
+      continue;
+    }
 
     const content = await fs.readFile(file.filePath, 'utf8');
     const lines = content.split('\n');
@@ -34,7 +48,9 @@ export async function writeAnnotations(results: FileAnalysis[]): Promise<{ files
 
       // Check if an identical annotation already exists on the line above (trimmed to ignore indent)
       const lineAbove = lines[targetLine - 1]?.trim();
-      if (lineAbove === comment.trim()) continue;
+      if (lineAbove === comment.trim()) {
+        continue;
+      }
 
       // Determine indentation from the target line
       const indent = lines[targetLine]?.match(/^(\s*)/)?.[1] ?? '';
@@ -47,6 +63,18 @@ export async function writeAnnotations(results: FileAnalysis[]): Promise<{ files
       await fs.writeFile(file.filePath, lines.join('\n'), 'utf8');
       filesChanged++;
     }
+
+    annotatedFiles.push(file.filePath);
+  }
+
+  if (projectRoot && annotatedFiles.length > 0) {
+    const metaDir = path.join(projectRoot, METADATA_DIR);
+    await fs.mkdir(metaDir, { recursive: true });
+    const metadata = {
+      version: 1,
+      annotatedFiles: annotatedFiles.map(f => path.relative(projectRoot, f)),
+    };
+    await fs.writeFile(path.join(metaDir, METADATA_FILE), JSON.stringify(metadata, null, 2) + '\n', 'utf8');
   }
 
   return { filesChanged };

From 7c855c186d23302defeca2753b7145514f190730 Mon Sep 17 00:00:00 2001
From: Dmytro Kirpa <dmytrokirpa@microsoft.com>
Date: Thu, 5 Mar 2026 18:48:51 +0100
Subject: [PATCH 6/6] fix cli and codemod guidance to the skill

---
 skills/fluentui-migrate-v8-to-v9/SKILL.md     | 166 +++++++++++++++--
 tools/cli/src/commands/migrate/index.ts       |   9 -
 .../v8-to-v9/__tests__/handler.spec.ts        |  32 +++-
 .../src/commands/migrate/v8-to-v9/handler.ts  |  14 +-
 .../v8-to-v9/utils/annotator/analyzer.ts      |  42 ++++-
 .../utils/annotator/rules/component-rename.ts | 170 +++++++++++++++++-
 .../utils/annotator/rules/icon-props.ts       | 142 ++++++++++++---
 .../utils/annotator/rules/import-paths.ts     |  44 +++--
 .../utils/annotator/rules/label-extraction.ts |  10 +-
 .../utils/annotator/rules/no-equivalent.ts    |   8 +-
 .../utils/annotator/rules/toggle-props.ts     |   5 +-
 .../migrate/v8-to-v9/utils/annotator/types.ts |   7 -
 .../v8-to-v9/utils/annotator/writer.ts        |  41 ++++-
 13 files changed, 600 insertions(+), 90 deletions(-)

diff --git a/skills/fluentui-migrate-v8-to-v9/SKILL.md b/skills/fluentui-migrate-v8-to-v9/SKILL.md
index b04acd8ea4157b..bdfed67332f77d 100644
--- a/skills/fluentui-migrate-v8-to-v9/SKILL.md
+++ b/skills/fluentui-migrate-v8-to-v9/SKILL.md
@@ -42,13 +42,13 @@ Use `<PROJECT_ROOT>` for the package root and `<SOURCE_ROOT>` for the narrowed s
 
 **Check for existing migration annotations:**
 
-First check for `.fluent-migrate/metadata.json` — written by the CLI after annotating, it lists annotated files deterministically:
+First check for `.fluent-migrate/metadata.json` — written by the CLI after annotating, it lists annotated files deterministically. The CLI writes it to the same directory passed as `--path`, so look in `<SOURCE_ROOT>`:
 
 ```sh
-cat <PROJECT_ROOT>/.fluent-migrate/metadata.json
+cat <SOURCE_ROOT>/.fluent-migrate/metadata.json
 ```
 
-- If `metadata.json` exists, use the `annotatedFiles` list directly as your work queue. Skip the grep scan.
+- If `metadata.json` exists, use the `annotatedFiles` list as your work queue. **Paths are relative to the directory that contains `.fluent-migrate/`** (i.e. relative to `<SOURCE_ROOT>`). Resolve each path against `<SOURCE_ROOT>` before opening. Skip the grep scan.
 - If it does not exist, scan for annotations:
 
 ```sh
@@ -59,6 +59,8 @@ grep -rl "@fluent-migrate:" <SOURCE_ROOT> --include="*.ts" --include="*.tsx"
 - If nothing is found → tell the user:
 
   > "No migration annotations found. Please run `npx @fluentui/cli migrate v8-to-v9 --path <SOURCE_ROOT>` first, then re-invoke the skill."
+  >
+  > Tip: add `--dry-run` to preview which files would be annotated without writing any changes.
 
   Stop until the user confirms the CLI has been run.
 
@@ -115,6 +117,33 @@ import { PortalCompatProvider } from '@fluentui/react-portal-compat';
 
 In those cases: commit what's done, fill in the Output Template with status ⚠️ or ❌, list the blockers, and wait for user input.
 
+#### Annotation format
+
+Every annotation written by the CLI has this structure:
+
+```
+// @fluent-migrate:<action> | <codemod> | <payload> | <note>
+```
+
+Inside JSX (where a line comment is a syntax error):
+
+```tsx
+{
+  /* @fluent-migrate:<action> | <codemod> | <payload> | <note> */
+}
+```
+
+Fields:
+
+- `action` — `auto`, `scaffold`, `manual`, or `no-equivalent`
+- `codemod` — identifies the transformation rule (see Codemod → Reference Index)
+- `payload` — machine-readable hint (e.g. `Toggle → Switch`, `@fluentui/react → @fluentui/react-components`)
+- `note` — optional human-readable context; may reference a file (e.g. `see references/dialog.md`)
+
+The annotation always sits on the line **above** the node it describes.
+
+---
+
 Process the `@fluent-migrate:` annotations as a work queue. If `.fluent-migrate/metadata.json` exists, open each file it lists directly. Otherwise, get all annotations with:
 
 ```sh
@@ -137,7 +166,7 @@ Each annotation encodes exactly what to do in its payload. Apply the transformat
 grep -rn "@fluent-migrate:scaffold" <SOURCE_ROOT> --include="*.ts" --include="*.tsx"
 ```
 
-Generate the appropriate boilerplate skeleton with `// TODO:` placeholders. Do **not** fill in semantic values (style values, layout intent, etc.). Remove the annotation on completion.
+The annotation `payload` specifies the target structure (e.g. `TextField.label → <Field label="..."><Input /></Field>`). Apply the transformation mechanically using the payload as the template. Add `// TODO:` placeholders only for values you cannot infer from surrounding context (e.g. specific style token values). Remove the annotation on completion.
 
 #### 3. `manual` annotations — read context, apply or ask
 
@@ -153,7 +182,12 @@ Read the surrounding code context to determine intent. The annotation's `note` f
 grep -rn "@fluent-migrate:no-equivalent" <SOURCE_ROOT> --include="*.ts" --include="*.tsx"
 ```
 
-Do not attempt migration. Report each one to the user with the recommended alternative from the deprecation table below. Wait for user direction before proceeding. Remove the annotation only after the user provides a resolution.
+Do not attempt migration. Report each one to the user with the recommended alternative. Wait for user direction before proceeding. Remove the annotation only after the user provides a resolution.
+
+All `no-equivalent` annotations use `codemod: no-equivalent`. The `note` field always contains the specific guidance. Two common sub-cases:
+
+- **Component-level** (`payload` is a component name, e.g. `ActivityItem`, `Stack` in JSX) → the `note` is the deprecation table entry; the deprecation table below lists recommended alternatives.
+- **Prop- or specifier-level** (`payload` is a prop name or import specifier name, e.g. `onText`, `offText`) → follow the `note` directly (e.g. "remove the prop or build a custom wrapper", "remove this import specifier").
 
 #### Verify zero annotations remain
 
@@ -163,6 +197,108 @@ grep -r "@fluent-migrate:" <SOURCE_ROOT> --include="*.ts" --include="*.tsx"
 
 Should return nothing. Any remaining annotations are blockers — include them in the Output Template as unresolved deltas, then proceed to Step 4.
 
+#### Cross-check remaining v8 imports against the component mapping table
+
+The CLI annotates JSX usages it knows about, but does not annotate every component. After clearing all annotations, scan for any `@fluentui/react` imports that survived the import-path change:
+
+```sh
+grep -rn "from '@fluentui/react'" <SOURCE_ROOT> --include="*.ts" --include="*.tsx"
+```
+
+For each surviving named import, look it up in the **Component Mapping** table below. If the v9 equivalent has a different name or a structural API change, apply that migration now before moving to Step 4.
+
+### Codemod → Reference Index
+
+When processing an annotation, use the `codemod` field to load the right reference before applying the change. For codemods marked "— see inline" below, follow the inline instructions in this section.
+
+| `codemod`            | Reference                                                                                                            |
+| -------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| `button-variants`    | [references/button.md](references/button.md)                                                                         |
+| `component-rename`   | Component mapping table (this file); for `manual` annotations also load the ref named in the annotation's note field |
+| `dialog-props`       | [references/dialog.md](references/dialog.md)                                                                         |
+| `enum-to-string`     | — see inline                                                                                                         |
+| `get-id`             | — see inline                                                                                                         |
+| `icon-props`         | [references/icons.md](references/icons.md)                                                                           |
+| `import-paths`       | — see inline                                                                                                         |
+| `keycodes`           | — see inline                                                                                                         |
+| `label-extraction`   | [references/input.md](references/input.md), [references/label.md](references/label.md)                               |
+| `no-equivalent`      | Deprecation table (this file) — surface to user, do not migrate                                                      |
+| `progress-bar-props` | [references/progressbar.md](references/progressbar.md)                                                               |
+| `prop-rename`        | — see inline                                                                                                         |
+| `remove-theme-prop`  | [references/theme.md](references/theme.md)                                                                           |
+| `styles-prop`        | [references/theme.md](references/theme.md)                                                                           |
+| `toggle-props`       | [references/switch.md](references/switch.md)                                                                         |
+| `use-boolean`        | — see inline                                                                                                         |
+
+#### `enum-to-string`
+
+Replace the enum member access with the string literal from the payload. Remove the migrated enum from the `@fluentui/react` import.
+
+```tsx
+// annotation payload: MessageBarType.error → "error"
+intent={MessageBarType.error}  →  intent="error"
+```
+
+#### `get-id`
+
+Replace `getId(prefix?)` with the `useId(prefix?)` hook from `@fluentui/react-components`, called at the top level of the function component.
+
+```tsx
+// before
+const id = getId('field');
+
+// after
+import { useId } from '@fluentui/react-components';
+const id = useId('field');
+```
+
+For `manual` annotations (outside a function component), restructure the class before converting.
+
+#### `import-paths`
+
+- `payload: @fluentui/react → @fluentui/react-components` (action: `auto`) — change the module specifier. Keep named imports that have v9 equivalents; specifiers with a `no-equivalent` annotation are handled separately.
+- `payload: @fluentui/react → remove (side-effect import)` (action: `auto`) — delete the entire import statement.
+- `payload: <Component> → <compat-package>` (action: `manual`) — the named import must move to a separate compat package. Remove the specifier from the `@fluentui/react` import and add a new import using the exact compat export name: `CalendarCompat` from `@fluentui/react-calendar-compat`, `DatePickerCompat` from `@fluentui/react-datepicker-compat`, `TimePickerCompat` from `@fluentui/react-timepicker-compat`. If `@fluentui/react-components` is also needed, keep both import lines.
+
+#### `keycodes`
+
+Replace `KeyCodes.X` with the string literal from the payload. Rewrite surrounding key-event checks from `event.which`/`event.keyCode` to `event.key`. Remove `KeyCodes` from the `@fluentui/react` import.
+
+```tsx
+// before
+if (event.which === KeyCodes.enter)
+// after
+if (event.key === 'Enter')
+```
+
+#### `prop-rename`
+
+Rename the JSX prop as specified in the payload (`oldProp → newProp`). Common cases: `ariaLabel → aria-label`, `componentRef → ref`.
+
+```tsx
+// annotation payload: componentRef → ref
+<Dialog componentRef={myRef}  →  <Dialog ref={myRef}
+```
+
+#### `use-boolean`
+
+Replace `useBoolean(initial)` with `useState(initial)` and expand the three tuple helpers inline.
+
+```tsx
+// before
+const [isOpen, { setTrue: openDialog, setFalse: closeDialog, toggle: toggleDialog }] = useBoolean(false);
+
+// after
+const [isOpen, setIsOpen] = useState(false);
+const openDialog = () => setIsOpen(true);
+const closeDialog = () => setIsOpen(false);
+const toggleDialog = () => setIsOpen(prev => !prev);
+```
+
+Remove `useBoolean` from the `@fluentui/react` import; add `useState` from `react`. For `manual` annotations (outside a function component), restructure before converting.
+
+---
+
 ### Step 4 — Validate
 
 Run the host repo's own commands. Do not assume `npx tsc` or `npm test` — check `package.json` scripts first.
@@ -265,7 +401,7 @@ Rule of thumb: add `disableButtonEnhancement` when the trigger child is a Fluent
 | `Breadcrumb`                      | `Breadcrumb`                                               | `items` array → declarative `BreadcrumbItem`/`BreadcrumbButton`/`BreadcrumbLink` children — see [breadcrumb.md](references/breadcrumb.md)         |
 | `Calendar`                        | `CalendarCompat`                                           | `@fluentui/react-calendar-compat`                                                                                                                 |
 | `Callout`                         | `Popover`                                                  | Composable trigger/surface; `target` ref → `PopoverTrigger` — see [callout.md](references/callout.md)                                             |
-| `Checkbox`                        | `Checkbox`                                                 | API mostly same                                                                                                                                   |
+| `Checkbox`                        | `Checkbox`                                                 | `indeterminate` → `checked="mixed"`; `CheckboxShim` available — see [checkbox.md](references/checkbox.md)                                         |
 | `ChoiceGroup`                     | `RadioGroup`                                               | Renamed; options array → `Radio` children                                                                                                         |
 | `Coachmark`                       | `TeachingPopover`                                          | Composable trigger/surface/header/body/footer — see [teachingpopover.md](references/teachingpopover.md)                                           |
 | `CommandBar` / `CommandBarButton` | `Toolbar`                                                  | Data-driven → JSX children — see [toolbar.md](references/toolbar.md)                                                                              |
@@ -374,15 +510,15 @@ import { InfoLabel } from '@fluentui/react-components';
 
 ### Deprecated with no v9 equivalent
 
-| v8                 | Recommended alternative                                                                                          |
-| ------------------ | ---------------------------------------------------------------------------------------------------------------- |
-| `ActivityItem`     | Build with `Avatar` + `Text` + `makeStyles` flexbox layout                                                       |
-| `Announced`        | Use a visually-hidden live region: `<div role="status" aria-live="polite" aria-atomic="true">...</div>`          |
-| `HoverCard`        | Use `<Popover>` with `onMouseEnter`/`onMouseLeave` on the trigger (or `openOnHover` prop if available)           |
-| `MarqueeSelection` | Use browser selection APIs or a custom `onPointerDown`/`onPointerMove` drag-select implementation                |
-| `Pickers`          | Use `TagPicker` (multi-select) or `Combobox`/`Dropdown` (single/multi-select) — see tagpicker.md and dropdown.md |
-| `ResizeGroup`      | Use the `Overflow` component (`<Overflow>` + `<OverflowItem>`) — see [overflow.md](references/overflow.md)       |
-| `ScrollablePane`   | Use `overflow: auto` on a CSS container + `position: sticky` for sticky headers; no FluentUI wrapper needed      |
+| v8                                                                | Recommended alternative                                                                                                                                               |
+| ----------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ActivityItem`                                                    | Build with `Avatar` + `Text` + `makeStyles` flexbox layout                                                                                                            |
+| `Announced`                                                       | Use a visually-hidden live region: `<div role="status" aria-live="polite" aria-atomic="true">...</div>`                                                               |
+| `HoverCard`                                                       | Use `<Popover>` with `onMouseEnter`/`onMouseLeave` on the trigger (or `openOnHover` prop if available)                                                                |
+| `MarqueeSelection`                                                | Use browser selection APIs or a custom `onPointerDown`/`onPointerMove` drag-select implementation                                                                     |
+| `NormalPeoplePicker` / `ListPeoplePicker` / `CompactPeoplePicker` | Use `TagPicker` (multi-select) or `Combobox`/`Dropdown` (single/multi-select) — see [tagpicker.md](references/tagpicker.md) and [dropdown.md](references/dropdown.md) |
+| `ResizeGroup`                                                     | Use the `Overflow` component (`<Overflow>` + `<OverflowItem>`) — see [overflow.md](references/overflow.md)                                                            |
+| `ScrollablePane`                                                  | Use `overflow: auto` on a CSS container + `position: sticky` for sticky headers; no FluentUI wrapper needed                                                           |
 
 ---
 
diff --git a/tools/cli/src/commands/migrate/index.ts b/tools/cli/src/commands/migrate/index.ts
index 188fe1bcf93f66..51599bd1bac4ae 100644
--- a/tools/cli/src/commands/migrate/index.ts
+++ b/tools/cli/src/commands/migrate/index.ts
@@ -14,15 +14,6 @@ const command: CommandModule = {
         type: 'boolean',
         description: 'List all available migrations',
       })
-      .check(argv => {
-        if (argv.list) {
-          return true;
-        }
-        if (!argv.migration) {
-          throw new Error(`No migration specified. Run --list to see available migrations.`);
-        }
-        return true;
-      })
       .version(false)
       .help(),
   handler: argv => {
diff --git a/tools/cli/src/commands/migrate/v8-to-v9/__tests__/handler.spec.ts b/tools/cli/src/commands/migrate/v8-to-v9/__tests__/handler.spec.ts
index a00c8c8b2d900b..532cd6086e6c13 100644
--- a/tools/cli/src/commands/migrate/v8-to-v9/__tests__/handler.spec.ts
+++ b/tools/cli/src/commands/migrate/v8-to-v9/__tests__/handler.spec.ts
@@ -1,17 +1,22 @@
 import { handler } from '../handler';
 import * as annotator from '../utils/annotator';
+import * as fs from 'fs/promises';
 
 jest.mock('../utils/annotator');
+jest.mock('fs/promises');
 
 const mockAnalyzeFiles = annotator.analyzeFiles as jest.MockedFunction<typeof annotator.analyzeFiles>;
 const mockWriteAnnotations = annotator.writeAnnotations as jest.MockedFunction<typeof annotator.writeAnnotations>;
+const mockStat = fs.stat as jest.MockedFunction<typeof fs.stat>;
 
 describe('migrate v8-to-v9 handler', () => {
   let logSpy: jest.SpyInstance;
 
   beforeEach(() => {
-    logSpy = jest.spyOn(console, 'log').mockImplementation();
     jest.clearAllMocks();
+    logSpy = jest.spyOn(console, 'log').mockImplementation();
+    // Default: path exists and is a directory
+    mockStat.mockResolvedValue({ isDirectory: () => true } as Awaited<ReturnType<typeof fs.stat>>);
   });
 
   afterEach(() => {
@@ -25,7 +30,7 @@ describe('migrate v8-to-v9 handler', () => {
     await handler({ path: 'src/', dryRun: false, _: [], $0: 'fluentui-cli' });
 
     expect(mockAnalyzeFiles).toHaveBeenCalledWith('src/');
-    expect(mockWriteAnnotations).toHaveBeenCalled();
+    expect(mockWriteAnnotations).toHaveBeenCalledWith(expect.any(Array), 'src/');
   });
 
   it('skips writeAnnotations in dryRun mode', async () => {
@@ -52,7 +57,7 @@ describe('migrate v8-to-v9 handler', () => {
 
     await handler({ path: 'src/', dryRun: false, _: [], $0: 'fluentui-cli' });
 
-    expect(logSpy).toHaveBeenCalledWith(expect.stringContaining('Annotated 1 files'));
+    expect(logSpy).toHaveBeenCalledWith(expect.stringContaining('Annotated 1 file'));
     expect(logSpy).toHaveBeenCalledWith(expect.stringContaining('auto'));
     expect(logSpy).toHaveBeenCalledWith(expect.stringContaining('manual'));
   });
@@ -72,4 +77,25 @@ describe('migrate v8-to-v9 handler', () => {
     expect(logSpy).toHaveBeenCalledWith(expect.stringContaining('@fluentui/react-components'));
     expect(mockWriteAnnotations).not.toHaveBeenCalled();
   });
+
+  it('errors and skips analysis when --path does not exist', async () => {
+    mockStat.mockRejectedValue(Object.assign(new Error('ENOENT'), { code: 'ENOENT' }));
+
+    await expect(handler({ path: 'nonexistent/', dryRun: false, _: [], $0: 'fluentui-cli' })).rejects.toThrow(
+      'Error: --path does not exist: nonexistent/',
+    );
+
+    expect(mockAnalyzeFiles).not.toHaveBeenCalled();
+    expect(mockWriteAnnotations).not.toHaveBeenCalled();
+  });
+
+  it('errors and skips analysis when --path is a file', async () => {
+    mockStat.mockResolvedValue({ isDirectory: () => false } as Awaited<ReturnType<typeof fs.stat>>);
+
+    await expect(handler({ path: 'src/Button.tsx', dryRun: false, _: [], $0: 'fluentui-cli' })).rejects.toThrow(
+      'Error: --path must be a directory, got a file: src/Button.tsx',
+    );
+
+    expect(mockAnalyzeFiles).not.toHaveBeenCalled();
+  });
 });
diff --git a/tools/cli/src/commands/migrate/v8-to-v9/handler.ts b/tools/cli/src/commands/migrate/v8-to-v9/handler.ts
index 35da3d76a6d9c3..9fcd93e802df7e 100644
--- a/tools/cli/src/commands/migrate/v8-to-v9/handler.ts
+++ b/tools/cli/src/commands/migrate/v8-to-v9/handler.ts
@@ -1,3 +1,4 @@
+import * as fs from 'fs/promises';
 import type { CommandHandler } from '../../../utils/types';
 import { analyzeFiles, writeAnnotations } from './utils/annotator';
 import type { FileAnalysis } from './utils/annotator';
@@ -8,6 +9,17 @@ interface V8ToV9Args {
 }
 
 export const handler: CommandHandler<V8ToV9Args> = async argv => {
+  let stat: Awaited<ReturnType<typeof fs.stat>>;
+  try {
+    stat = await fs.stat(argv.path);
+  } catch {
+    throw new Error(`Error: --path does not exist: ${argv.path}`);
+  }
+
+  if (!stat.isDirectory()) {
+    throw new Error(`Error: --path must be a directory, got a file: ${argv.path}`);
+  }
+
   const results = await analyzeFiles(argv.path);
 
   if (argv.dryRun) {
@@ -55,7 +67,7 @@ function printSummary(results: FileAnalysis[], filesChanged: number): void {
   const counts = countByAction(results);
   const deps = collectDeps(results);
 
-  console.log(`\nAnnotated ${filesChanged} files`);
+  console.log(`\nAnnotated ${filesChanged} ${filesChanged === 1 ? 'file' : 'files'}`);
   console.log(`  auto          ${counts.auto.toString().padStart(4)}  (safe to apply mechanically)`);
   console.log(`  scaffold      ${counts.scaffold.toString().padStart(4)}  (boilerplate needed)`);
   console.log(`  manual        ${counts.manual.toString().padStart(4)}  (requires judgment)`);
diff --git a/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/analyzer.ts b/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/analyzer.ts
index 629ca47119b7bb..cdd0da59728ffe 100644
--- a/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/analyzer.ts
+++ b/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/analyzer.ts
@@ -1,3 +1,4 @@
+import * as fs from 'fs/promises';
 import * as glob from 'fast-glob';
 import * as path from 'path';
 import { Project } from 'ts-morph';
@@ -57,11 +58,42 @@ const DEP_REQUIREMENTS: Array<{ name: string; reason: string; triggerCodemod: st
 ];
 
 /**
- * Pure detection engine — no file I/O.
+ * Walk up from dir to find the nearest package.json and return its combined dependency names.
+ * Returns an empty set if no package.json is found.
+ */
+async function getInstalledPackages(startDir: string): Promise<Set<string>> {
+  let dir = path.resolve(startDir);
+  while (true) {
+    try {
+      const raw = await fs.readFile(path.join(dir, 'package.json'), 'utf8');
+      const pkg = JSON.parse(raw) as {
+        dependencies?: Record<string, string>;
+        devDependencies?: Record<string, string>;
+        peerDependencies?: Record<string, string>;
+      };
+      return new Set([
+        ...Object.keys(pkg.dependencies ?? {}),
+        ...Object.keys(pkg.devDependencies ?? {}),
+        ...Object.keys(pkg.peerDependencies ?? {}),
+      ]);
+    } catch {
+      const parent = path.dirname(dir);
+      if (parent === dir) {
+        break;
+      } // reached filesystem root
+      dir = parent;
+    }
+  }
+  return new Set<string>();
+}
+
+/**
+ * Pure detection engine — no file I/O beyond reading package.json for dep filtering.
  * Both migrate and dryRun call this.
  */
 export async function analyzeFiles(sourcePath: string): Promise<FileAnalysis[]> {
   const absoluteSource = path.resolve(sourcePath);
+  const installedPackages = await getInstalledPackages(absoluteSource);
 
   const filePaths = await glob.glob(['**/*.ts', '**/*.tsx'], {
     cwd: absoluteSource,
@@ -86,11 +118,11 @@ export async function analyzeFiles(sourcePath: string): Promise<FileAnalysis[]>
       continue;
     }
 
-    // Determine which deps are needed based on detected codemods
+    // Determine which deps are needed based on detected codemods, filtered by what's already installed
     const detectedCodemods = new Set(annotations.map(a => a.codemod));
-    const missingDeps = DEP_REQUIREMENTS.filter(dep => detectedCodemods.has(dep.triggerCodemod)).map(
-      ({ name, reason }) => ({ name, reason }),
-    );
+    const missingDeps = DEP_REQUIREMENTS.filter(
+      dep => detectedCodemods.has(dep.triggerCodemod) && !installedPackages.has(dep.name),
+    ).map(({ name, reason }) => ({ name, reason }));
 
     results.push({
       filePath: sourceFile.getFilePath(),
diff --git a/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/component-rename.ts b/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/component-rename.ts
index d70847ba54c46e..900c20c57ccba9 100644
--- a/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/component-rename.ts
+++ b/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/component-rename.ts
@@ -9,11 +9,16 @@ const AUTO_RENAMES: Record<string, string> = {
   Toggle: 'Switch',
   Shimmer: 'Skeleton',
   Fabric: 'FluentProvider',
+  ThemeProvider: 'FluentProvider',
   Layer: 'Portal',
   Overlay: 'Portal',
   ProgressIndicator: 'ProgressBar',
   SwatchColorPicker: 'SwatchPicker',
   CommandButton: 'MenuButton',
+  ChoiceGroup: 'RadioGroup',
+  TeachingBubble: 'TeachingPopover',
+  Coachmark: 'TeachingPopover',
+  Facepile: 'AvatarGroup',
 };
 
 /** 1→many — the agent must decide based on context. */
@@ -26,10 +31,150 @@ const MANUAL_RENAMES: Record<string, { choices: string; ref: string }> = {
     choices: 'DataGrid (selection/sort), Table (read-only)',
     ref: 'references/datagrid.md',
   },
+  TextField: {
+    choices: 'Input (single-line), Textarea (multiline)',
+    ref: 'references/input.md',
+  },
   Popup: {
     choices: 'Popover (non-modal overlay), Dialog (modal/blocking)',
     ref: '',
   },
+  FocusTrapZone: {
+    choices: 'Dialog (modal), Popover (trapFocus), or @fluentui/react-tabster (useFocusFinders) for custom traps',
+    ref: '',
+  },
+  FocusZone: {
+    choices:
+      'components with built-in arrow navigation (TabList, Menu, etc.) or @fluentui/react-tabster (useMergedTabsterAttributes_unstable)',
+    ref: '',
+  },
+};
+
+/** 1→1 rename but inner API changed significantly — agent must consult the reference before rewriting. */
+const STRUCTURAL_RENAMES: Record<string, { target: string; note: string; ref: string }> = {
+  Panel: {
+    target: 'OverlayDrawer',
+    note: 'restructure with DrawerHeader + DrawerBody; PanelType → position+size',
+    ref: 'references/drawer.md',
+  },
+  Callout: {
+    target: 'Popover',
+    note: 'composable trigger/surface; target ref → PopoverTrigger; directionalHint → positioning',
+    ref: 'references/callout.md',
+  },
+  ContextualMenu: {
+    target: 'Menu',
+    note: 'items array → declarative JSX children',
+    ref: 'references/menu.md',
+  },
+  CommandBar: {
+    target: 'Toolbar',
+    note: 'items array → ToolbarButton JSX children; overflow via Overflow+OverflowItem',
+    ref: 'references/toolbar.md',
+  },
+  CommandBarButton: {
+    target: 'ToolbarButton',
+    note: 'becomes JSX child of Toolbar',
+    ref: 'references/toolbar.md',
+  },
+  Pivot: {
+    target: 'TabList',
+    note: 'content panels move outside TabList; PivotItem → Tab',
+    ref: 'references/tabs.md',
+  },
+  PivotItem: {
+    target: 'Tab',
+    note: 'content panel moves outside TabList',
+    ref: 'references/tabs.md',
+  },
+  OverflowSet: {
+    target: 'Overflow',
+    note: 'hook-based; onRenderItem → OverflowItem; useOverflowMenu',
+    ref: 'references/overflow.md',
+  },
+  PeoplePicker: {
+    target: 'TagPicker',
+    note: 'onResolveSuggestions → filter TagPickerOption children; composable structure',
+    ref: 'references/tagpicker.md',
+  },
+  ComboBox: {
+    target: 'Combobox',
+    note: 'casing change; options array → Option children; onOptionSelect replaces onChange',
+    ref: 'references/dropdown.md',
+  },
+  Modal: {
+    target: 'Dialog',
+    note: 'isOpen → open; isBlocking → modalType="alert"; wrap children in DialogSurface+DialogBody — see references/dialog.md',
+    ref: 'references/dialog.md',
+  },
+};
+
+/** Same name in v9 but API changed significantly — agent must rewrite usage. */
+const API_REWRITES: Record<string, { note: string; ref: string }> = {
+  Dropdown: {
+    note: 'options array → Option children; onOptionSelect replaces onChange',
+    ref: 'references/dropdown.md',
+  },
+  Breadcrumb: {
+    note: 'items array → BreadcrumbItem/BreadcrumbButton/BreadcrumbLink children; overflow via Overflow',
+    ref: 'references/breadcrumb.md',
+  },
+  Nav: {
+    note: 'groups array → NavItem/NavCategory JSX children; NavDrawer for side panels',
+    ref: 'references/nav.md',
+  },
+  List: {
+    note: 'items+onRenderCell → ListItem children; selectionMode+navigationMode added',
+    ref: 'references/list.md',
+  },
+  Checkbox: {
+    note: 'indeterminate prop → checked="mixed"; CheckboxShim available for incremental migration',
+    ref: 'references/checkbox.md',
+  },
+  Tooltip: {
+    note: 'relationship prop now required; directionalHint → positioning; trigger must use forwardRef',
+    ref: 'references/tooltip.md',
+  },
+  MessageBar: {
+    note: 'messageBarType → intent string; composable children (MessageBarBody, MessageBarActions, MessageBarTitle)',
+    ref: 'references/messagebar.md',
+  },
+  Spinner: {
+    note: 'SpinnerSize enum → string size; labelPosition renamed; label prop removed — wrap with Field',
+    ref: 'references/spinner.md',
+  },
+  Text: {
+    note: 'variant → size+weight; nowrap → wrap={false}; use presets (Body1, Title2, etc.)',
+    ref: 'references/text.md',
+  },
+  Link: {
+    note: 'inline prop for prose context; appearance="subtle"; disabledFocusable replaces disabled',
+    ref: 'references/link.md',
+  },
+  SearchBox: {
+    note: 'onSearch → onKeyDown; onClear → onChange with empty string; underlined → appearance="underline"',
+    ref: 'references/searchbox.md',
+  },
+  Image: {
+    note: 'imageFit → fit; shouldFadeIn removed; no wrapper div',
+    ref: 'references/image.md',
+  },
+  Persona: {
+    note: 'slot-based; imageUrl/imageInitials/presence → avatar slot; PersonaPresence enum → string status',
+    ref: 'references/persona.md',
+  },
+  Rating: {
+    note: 'rating → value; readOnly → use RatingDisplay instead; icon string → iconFilled/iconOutline component',
+    ref: 'references/rating.md',
+  },
+  Slider: {
+    note: 'label prop removed — wrap with Field; onChange signature changed',
+    ref: 'references/slider.md',
+  },
+  SpinButton: {
+    note: 'label prop removed — wrap with Field; onChange signature changed',
+    ref: 'references/spinbutton.md',
+  },
 };
 
 export function detectComponentRenames(sourceFile: SourceFile, fluentNames: Set<string>): AnnotationResult[] {
@@ -46,13 +191,14 @@ export function detectComponentRenames(sourceFile: SourceFile, fluentNames: Set<
     }
 
     const insideJsx = isJsxChild(node);
+    const line = node.getStartLineNumber();
 
     if (AUTO_RENAMES[tagName]) {
       results.push({
         action: 'auto',
         codemod: 'component-rename',
         payload: `${tagName} → ${AUTO_RENAMES[tagName]}`,
-        line: node.getStartLineNumber(),
+        line,
         insideJsx,
       });
     } else if (MANUAL_RENAMES[tagName]) {
@@ -62,7 +208,27 @@ export function detectComponentRenames(sourceFile: SourceFile, fluentNames: Set<
         codemod: 'component-rename',
         payload: `${tagName} → ?`,
         note: `choices: ${choices}${ref ? ` — see ${ref}` : ''}`,
-        line: node.getStartLineNumber(),
+        line,
+        insideJsx,
+      });
+    } else if (STRUCTURAL_RENAMES[tagName]) {
+      const { target, note, ref } = STRUCTURAL_RENAMES[tagName];
+      results.push({
+        action: 'manual',
+        codemod: 'component-rename',
+        payload: `${tagName} → ${target}`,
+        note: `${note} — see ${ref}`,
+        line,
+        insideJsx,
+      });
+    } else if (API_REWRITES[tagName]) {
+      const { note, ref } = API_REWRITES[tagName];
+      results.push({
+        action: 'manual',
+        codemod: 'component-rename',
+        payload: `${tagName} (API rewrite)`,
+        note: `${note} — see ${ref}`,
+        line,
         insideJsx,
       });
     }
diff --git a/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/icon-props.ts b/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/icon-props.ts
index 1421bd3f842a3c..9c82a357ddf2cb 100644
--- a/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/icon-props.ts
+++ b/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/icon-props.ts
@@ -2,43 +2,139 @@ import type { SourceFile, Node } from 'ts-morph';
 import { SyntaxKind } from 'ts-morph';
 import type { AnnotationResult } from '../types';
 
-// Known icon names that have a direct @fluentui/react-icons equivalent (subset)
+// Known icon names that have a direct @fluentui/react-icons equivalent.
+// The v9 icon name is the v8 name + "Regular" suffix (e.g. Add → AddRegular).
 const KNOWN_ICONS = new Set([
+  // Navigation & actions
   'Add',
-  'Delete',
-  'Edit',
-  'Search',
-  'Settings',
-  'Filter',
-  'Download',
-  'Upload',
-  'Share',
-  'Copy',
+  'AddCircle',
+  'ArrowClockwise',
+  'ArrowCounterclockwise',
+  'ArrowDown',
+  'ArrowDownload',
+  'ArrowLeft',
+  'ArrowRight',
+  'ArrowUp',
+  'ArrowUpload',
+  'Attach',
+  'Backspace',
+  'Bookmark',
+  'BookmarkAdd',
+  'Calendar',
+  'CalendarAdd',
+  'Call',
+  'Camera',
   'Cancel',
   'CheckMark',
   'ChevronDown',
-  'ChevronUp',
   'ChevronLeft',
   'ChevronRight',
-  'More',
-  'Save',
-  'Info',
-  'Warning',
+  'ChevronUp',
+  'CircleSmall',
+  'ClipboardPaste',
+  'Clock',
+  'Close',
+  'Cloud',
+  'CloudArrowUp',
+  'Code',
+  'Color',
+  'Comment',
+  'CommentAdd',
+  'Copy',
+  'Cut',
+  'DataBar',
+  'Delete',
+  'Dismiss',
+  'Document',
+  'DocumentAdd',
+  'DocumentCopy',
+  'DocumentEdit',
+  'Download',
+  'Edit',
+  'Emoji',
   'Error',
-  'Mail',
-  'Phone',
-  'Calendar',
-  'Home',
+  'Eye',
+  'EyeOff',
+  'Filter',
+  'Flag',
   'Folder',
+  'FolderAdd',
   'FolderOpen',
-  'Tag',
   'Globe',
+  'Grid',
+  'Group',
+  'Heart',
+  'Help',
+  'Home',
+  'Image',
+  'Info',
+  'Key',
+  'Laugh',
+  'Link',
+  'List',
+  'Location',
   'Lock',
+  'LockClosed',
+  'LockOpen',
+  'Mail',
+  'MailAdd',
+  'MailRead',
+  'Map',
+  'Megaphone',
+  'Mention',
+  'Mic',
+  'MicOff',
+  'More',
+  'MoreHorizontal',
+  'MoreVertical',
+  'Move',
+  'Navigation',
+  'Open',
+  'Options',
+  'Organization',
+  'Pause',
+  'People',
+  'PeopleAdd',
+  'Person',
+  'PersonAdd',
+  'Phone',
+  'Pin',
+  'Play',
+  'Print',
+  'Question',
+  'Refresh',
+  'Rename',
+  'Reply',
+  'ReplyAll',
+  'Save',
+  'Search',
+  'Send',
+  'Settings',
+  'Share',
+  'Shield',
+  'SignOut',
+  'Sparkle',
+  'Star',
+  'StarAdd',
+  'Stop',
+  'Subtract',
+  'SubtractCircle',
+  'Tag',
+  'TaskList',
+  'Text',
+  'Thumblike',
+  'ThumbDislike',
+  'Timer',
+  'Translate',
   'Unlock',
+  'Upload',
   'User',
-  'Group',
-  'Refresh',
-  'Close',
+  'Video',
+  'VideoOff',
+  'Warning',
+  'Wrench',
+  'ZoomIn',
+  'ZoomOut',
 ]);
 
 export function detectIconProps(sourceFile: SourceFile, fluentNames: Set<string>): AnnotationResult[] {
diff --git a/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/import-paths.ts b/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/import-paths.ts
index 2240d75102783b..915f67b29e77ad 100644
--- a/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/import-paths.ts
+++ b/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/import-paths.ts
@@ -1,17 +1,15 @@
 import type { SourceFile } from 'ts-morph';
 import type { AnnotationResult } from '../types';
+import { DEPRECATED_COMPONENT_NAMES } from './no-equivalent';
 
-// Components with no v9 equivalent — annotated as no-equivalent instead of auto
-const NO_EQUIVALENT = new Set([
-  'ActivityItem',
-  'MarqueeSelection',
-  'HoverCard',
-  'ResizeGroup',
-  'ScrollablePane',
-  'Announced',
-]);
-
-export function detectImportPaths(sourceFile: SourceFile): AnnotationResult[] {
+/** v8 components that live in separate compat packages, not @fluentui/react-components. */
+const COMPAT_PACKAGES: Record<string, string> = {
+  Calendar: '@fluentui/react-calendar-compat',
+  DatePicker: '@fluentui/react-datepicker-compat',
+  TimePicker: '@fluentui/react-timepicker-compat',
+};
+
+export function detectImportPaths(sourceFile: SourceFile, _fluentNames: Set<string>): AnnotationResult[] {
   const results: AnnotationResult[] = [];
 
   for (const decl of sourceFile.getImportDeclarations()) {
@@ -33,17 +31,35 @@ export function detectImportPaths(sourceFile: SourceFile): AnnotationResult[] {
       continue;
     }
 
-    const noEquivSpecifiers = namedImports.filter(s => NO_EQUIVALENT.has(s.getName()));
+    const noEquivSpecifiers = namedImports.filter(s => DEPRECATED_COMPONENT_NAMES.has(s.getName()));
     for (const specifier of noEquivSpecifiers) {
       results.push({
         action: 'no-equivalent',
+        codemod: 'no-equivalent',
+        payload: specifier.getName(),
+        note: 'no v9 equivalent — remove this import specifier',
+        line,
+      });
+    }
+
+    // Compat-package components need a separate import — annotate each one as manual.
+    const compatSpecifiers = namedImports.filter(
+      s => !DEPRECATED_COMPONENT_NAMES.has(s.getName()) && COMPAT_PACKAGES[s.getName()],
+    );
+    for (const specifier of compatSpecifiers) {
+      const pkg = COMPAT_PACKAGES[specifier.getName()];
+      results.push({
+        action: 'manual',
         codemod: 'import-paths',
-        payload: `${specifier.getName()} — no v9 equivalent`,
+        payload: `${specifier.getName()} → ${pkg}`,
+        note: `split import; move specifier to a separate "import { ... } from '${pkg}'"`,
         line,
       });
     }
 
-    const hasEquivSpecifiers = namedImports.some(s => !NO_EQUIVALENT.has(s.getName()));
+    const hasEquivSpecifiers = namedImports.some(
+      s => !DEPRECATED_COMPONENT_NAMES.has(s.getName()) && !COMPAT_PACKAGES[s.getName()],
+    );
     if (hasEquivSpecifiers) {
       results.push({
         action: 'auto',
diff --git a/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/label-extraction.ts b/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/label-extraction.ts
index e2c733c7329604..ede5e1d50f9ae9 100644
--- a/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/label-extraction.ts
+++ b/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/label-extraction.ts
@@ -2,7 +2,13 @@ import type { SourceFile, Node } from 'ts-morph';
 import { SyntaxKind } from 'ts-morph';
 import type { AnnotationResult } from '../types';
 
-const LABEL_COMPONENTS = new Set(['TextField', 'SpinButton', 'Slider', 'ChoiceGroup']);
+const LABEL_COMPONENTS = new Set(['TextField', 'SpinButton', 'Slider', 'ChoiceGroup', 'Spinner', 'ProgressIndicator']);
+
+/** Maps v8 component names to their v9 equivalents for use in scaffold payloads. */
+const V9_NAME: Record<string, string> = {
+  TextField: 'Input',
+  ProgressIndicator: 'ProgressBar',
+};
 
 export function detectLabelExtraction(sourceFile: SourceFile, fluentNames: Set<string>): AnnotationResult[] {
   const results: AnnotationResult[] = [];
@@ -26,7 +32,7 @@ export function detectLabelExtraction(sourceFile: SourceFile, fluentNames: Set<s
           results.push({
             action: 'scaffold',
             codemod: 'label-extraction',
-            payload: `${tagName}.label → <Field label="..."><${tagName === 'TextField' ? 'Input' : tagName} /></Field>`,
+            payload: `${tagName}.label → <Field label="..."><${V9_NAME[tagName] ?? tagName} /></Field>`,
             note: 'also move: required, errorMessage→validationMessage, description→hint',
             line,
           });
diff --git a/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/no-equivalent.ts b/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/no-equivalent.ts
index 28d4dc84377c8d..7889d9decfedfc 100644
--- a/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/no-equivalent.ts
+++ b/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/no-equivalent.ts
@@ -10,8 +10,13 @@ const DEPRECATED_COMPONENTS: Record<string, string> = {
   ResizeGroup: 'use Overflow component (<Overflow> + <OverflowItem>)',
   ScrollablePane: 'use overflow: auto on a CSS container + position: sticky for sticky headers',
   Announced: 'use a visually-hidden live region: <div role="status" aria-live="polite">',
+  Stack: 'replace with makeStyles + flexbox layout — see references/stack.md',
+  StackItem: 'replace with makeStyles + flexbox layout — see references/stack.md',
 };
 
+/** Exported so import-paths can suppress the auto annotation for deprecated-component imports. */
+export const DEPRECATED_COMPONENT_NAMES = new Set(Object.keys(DEPRECATED_COMPONENTS));
+
 export function detectNoEquivalent(sourceFile: SourceFile, fluentNames: Set<string>): AnnotationResult[] {
   const results: AnnotationResult[] = [];
 
@@ -28,7 +33,8 @@ export function detectNoEquivalent(sourceFile: SourceFile, fluentNames: Set<stri
     results.push({
       action: 'no-equivalent',
       codemod: 'no-equivalent',
-      payload: `${tagName} | ${DEPRECATED_COMPONENTS[tagName]}`,
+      payload: tagName,
+      note: DEPRECATED_COMPONENTS[tagName],
       line: node.getStartLineNumber(),
       insideJsx: isJsxChild(node),
     });
diff --git a/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/toggle-props.ts b/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/toggle-props.ts
index 79cf0619c47c5c..675af0c04404ab 100644
--- a/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/toggle-props.ts
+++ b/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/toggle-props.ts
@@ -40,8 +40,9 @@ export function detectToggleProps(sourceFile: SourceFile, fluentNames: Set<strin
         case 'offText':
           results.push({
             action: 'no-equivalent',
-            codemod: 'toggle-props',
-            payload: `${propName} | v9 Switch has no on/off labels — remove or build custom wrapper`,
+            codemod: 'no-equivalent',
+            payload: propName,
+            note: 'v9 Switch has no on/off labels — remove the prop or build a custom wrapper',
             line,
           });
           break;
diff --git a/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/types.ts b/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/types.ts
index c48dc6f1bc5142..d86d7d8b60a9ed 100644
--- a/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/types.ts
+++ b/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/types.ts
@@ -1,5 +1,3 @@
-import type { SourceFile } from 'ts-morph';
-
 export type AnnotationAction = 'auto' | 'scaffold' | 'manual' | 'no-equivalent';
 
 export interface Annotation {
@@ -27,8 +25,3 @@ export interface FileAnalysis {
   annotations: AnnotationResult[];
   missingDeps: Array<{ name: string; reason: string }>;
 }
-
-export interface AnnotationRule {
-  name: string;
-  detect(sourceFile: SourceFile): AnnotationResult[];
-}
diff --git a/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/writer.ts b/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/writer.ts
index 1fc6ca6c3c341a..9d78062efb5d13 100644
--- a/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/writer.ts
+++ b/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/writer.ts
@@ -6,6 +6,29 @@ const ANNOTATION_TAG = '@fluent-migrate:';
 const METADATA_DIR = '.fluent-migrate';
 const METADATA_FILE = 'metadata.json';
 
+/**
+ * Searches backward from targetLine through consecutive annotation comment lines to detect
+ * whether an identical comment already exists. This handles the case where multiple
+ * annotations target the same original source line — a simple one-line-above check
+ * would miss duplicates that were inserted in previous runs.
+ */
+function annotationAlreadyPresent(lines: string[], targetLine: number, comment: string): boolean {
+  const commentTrimmed = comment.trim();
+  let i = targetLine - 1;
+  while (i >= 0) {
+    const lineTrimmed = lines[i].trim();
+    if (lineTrimmed === commentTrimmed) {
+      return true;
+    }
+    // Stop at the first line that is not a fluent-migrate annotation comment
+    if (!lineTrimmed.startsWith('// @fluent-migrate:') && !lineTrimmed.startsWith('{/* @fluent-migrate:')) {
+      break;
+    }
+    i--;
+  }
+  return false;
+}
+
 function formatAnnotation(a: AnnotationResult): string {
   const parts = [a.action, a.codemod, a.payload];
   if (a.note) {
@@ -17,7 +40,8 @@ function formatAnnotation(a: AnnotationResult): string {
 
 /**
  * Inserts @fluent-migrate: comments into source files based on FileAnalysis results.
- * Idempotent: skips if an identical comment already exists on the line above the target.
+ * Idempotent: skips if an identical comment already exists in the annotation block above the target.
+ * Handles multiple annotations targeting the same source line by tracking per-line insertion offsets.
  *
  * When `projectRoot` is provided, writes `.fluent-migrate/metadata.json` listing
  * all annotated file paths so the skill can locate them without re-scanning.
@@ -37,18 +61,22 @@ export async function writeAnnotations(
     const content = await fs.readFile(file.filePath, 'utf8');
     const lines = content.split('\n');
 
-    // Sort annotations by line descending so insertions don't shift line numbers
+    // Sort annotations by line descending so insertions at higher lines don't shift lower ones.
     const sorted = [...file.annotations].sort((a, b) => b.line - a.line);
 
     let changed = false;
+    // Track how many annotations have been inserted for each original source line so that
+    // subsequent insertions at the same line land after the already-inserted ones.
+    const sameLineInsertions = new Map<number, number>();
 
     for (const annotation of sorted) {
-      const targetLine = annotation.line - 1; // convert to 0-based
+      const existingInsertions = sameLineInsertions.get(annotation.line) ?? 0;
+      // Offset targetLine by the number of annotations already inserted at this original line
+      const targetLine = annotation.line - 1 + existingInsertions; // convert to 0-based + offset
       const comment = formatAnnotation(annotation);
 
-      // Check if an identical annotation already exists on the line above (trimmed to ignore indent)
-      const lineAbove = lines[targetLine - 1]?.trim();
-      if (lineAbove === comment.trim()) {
+      // Search backward through the annotation block above the target for an identical comment
+      if (annotationAlreadyPresent(lines, targetLine, comment)) {
         continue;
       }
 
@@ -56,6 +84,7 @@ export async function writeAnnotations(
       const indent = lines[targetLine]?.match(/^(\s*)/)?.[1] ?? '';
 
       lines.splice(targetLine, 0, `${indent}${comment}`);
+      sameLineInsertions.set(annotation.line, existingInsertions + 1);
       changed = true;
     }