From 4b604bfbcf432deac652f370bcd3c2e3313f3133 Mon Sep 17 00:00:00 2001
From: Dmytro Kirpa <dmytrokirpa@microsoft.com>
Date: Mon, 2 Mar 2026 15:25:54 +0100
Subject: [PATCH 01/14] initial plan

---
 docs/plans/fluent-cli.md | 441 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 441 insertions(+)
 create mode 100644 docs/plans/fluent-cli.md

diff --git a/docs/plans/fluent-cli.md b/docs/plans/fluent-cli.md
new file mode 100644
index 0000000000000..1bf70660439a3
--- /dev/null
+++ b/docs/plans/fluent-cli.md
@@ -0,0 +1,441 @@
+# Fluent UI v9 Agentic Migration — Project Spec
+
+## 1) Objective
+
+Build an **agentic migration solution** for Fluent UI React v9 that consists of exactly two products:
+
+1. **Agent Skills** — deterministic instructions/workflows AI coding agents can follow for complex migrations.
+2. **CLI** — executable migration engine that performs Nx-style migrations and AST transformations.
+
+The skills are the **primary source of migration logic and sequencing**; the CLI is a **supportive execution utility** for codemods, reporting, and deterministic automation steps.
+
+---
+
+## 2) Problem Statement
+
+Current migrations (v8 → v9 and v9 minor upgrades) are inconsistent and largely manual:
+
+- no official migration skill system that encodes migration strategy,
+- no stable bridge between agent workflow decisions and codemod execution,
+- no repeatable agent workflows tied to deterministic transform tooling.
+
+Result: high migration cost, inconsistent outcomes, and low confidence for large codebases.
+
+---
+
+## 3) Scope
+
+### In scope (MVP)
+
+- Define and version **agent skills** for v8 → v9 migration.
+- Publish a CLI package (`@fluentui/cli`) as a support tool with:
+  - codemod execution (`migrate`) for skill-selected steps,
+  - AST-based transforms (jscodeshift initially),
+  - migration diagnostics/reporting (`report`),
+  - dry-run support and machine-readable output for agents.
+- Ensure skills invoke CLI only for deterministic/mechanical edits and analysis.
+- Implement and ship the two required MVP codemods: `deprecated-packages`, `deprecated-props`.
+
+### Out of scope (MVP)
+
+- Full auto-migration for every v8 component.
+- IDE plugin UI.
+- New runtime shim framework.
+- Cross-framework migrations beyond React/TS.
+- Migration recommendation hints in `report` output (Phase 2).
+
+---
+
+## 4) Success Criteria
+
+- Agent can execute end-to-end migration workflow on a sample app with no custom prompts.
+- Skills own migration planning decisions; CLI only executes requested codemods reliably.
+- CLI provides deterministic output (`dry-run` + applied mode) and idempotent transforms.
+- For MVP migrations, at least 80% of targeted mechanical edits are automated.
+- Type-check/test failure count after migration is lower than baseline manual approach.
+
+---
+
+## 5) Architecture
+
+### 5.1 Agent Skills Layer
+
+Skills are the migration control plane and contain:
+
+- decision trees (when to run which migration),
+- sequencing rules (report → dry-run → apply → verify),
+- stop conditions (unsafe diff size, parser failures, unresolved imports),
+- escalation rules (manual review checkpoints).
+
+Skills select migration steps, call CLI commands, and evaluate outcomes before proceeding.
+
+### 5.2 CLI Layer
+
+CLI is an execution/data plane and contains:
+
+- transform runner,
+- reporting/analysis commands,
+- structured result output for agent consumption.
+
+Primary transform engine for MVP: **jscodeshift** (TS/TSX parser defaults). CLI does not own migration strategy.
+
+---
+
+## 6) CLI Spec
+
+CLI command behavior is intentionally minimal and execution-focused; migration strategy remains in skills.
+
+### 6.1 Commands
+
+#### `migrate`
+
+Run codemods selected by skills (from `migrations.json` or by migration name).
+
+```sh
+npx @fluentui/cli migrate [migration-name] [path] [options]
+
+# Registry-driven run (Nx-style):
+npx @fluentui/cli migrate --run-migrations=migrations.json src/
+
+# Direct migration run:
+npx @fluentui/cli migrate deprecated-packages src/
+
+# Semver-filtered run (typically skill-driven):
+npx @fluentui/cli migrate src/ --from 8 --to 9
+```
+
+Options:
+
+- `--run-migrations <path>` — registry file path
+- `--from <semver>` — lower bound
+- `--to <semver>` — upper bound
+- `-d, --dry-run` — preview without writing
+- `-l, --list` — list known migrations
+- `--cpus <n>` — worker count
+- `--parser <tsx|ts|babel|babel-ts>` — default: `tsx`
+- `--json` — emit machine-readable result summary to stdout
+
+#### `report`
+
+Produce diagnostics data for agents to decide migration steps. Writes structured JSON to a file by default (output can be large).
+
+```sh
+npx @fluentui/cli report [path] [options]
+```
+
+Options:
+
+- `--output <file>` — default: `./fluent-report.json`
+- `--print` — print compact summary to stdout instead of writing file
+- `--json` — emit full JSON to stdout (for agent piping)
+
+Output sections:
+
+1. **Environment** — Node, OS, npm versions (always included).
+2. **Installed packages** — all `@fluentui/*` and `@fluentui-contrib/*` versions (always included).
+3. **Usage inventory** — imports + JSX props per component across scanned path (only when `[path]` is provided).
+
+Terminal summary always printed after file write:
+
+```sh
+Report written to fluent-report.json
+
+Node: 22.21.1  |  OS: darwin-arm64  |  npm: 10.9.4
+Installed:  @fluentui/react-components@9.73.1  @fluentui/react@8.125.5  (+1 more)
+Usage:      312 usages across 14 components in src/
+```
+
+JSON schema (`fluent-report.json`):
+
+```json
+{
+  "generatedAt": "2026-03-02T10:00:00.000Z",
+  "env": { "node": "22.21.1", "os": "darwin-arm64", "npm": "10.9.4" },
+  "packages": {
+    "@fluentui/react-components": "9.73.1",
+    "@fluentui/react": "8.125.5"
+  },
+  "usage": {
+    "scannedPath": "src/",
+    "totalUsages": 312,
+    "components": [
+      { "name": "Button", "package": "@fluentui/react-components", "usages": 142, "props": ["appearance", "icon"] },
+      { "name": "DefaultButton", "package": "@fluentui/react", "usages": 37, "props": ["text", "onClick"] }
+    ]
+  }
+}
+```
+
+`usage` is `null` when no path is provided.
+
+Migration recommendation hints are **Phase 2** — MVP `report` is data-only.
+
+---
+
+### 6.2 Migration Registry Contract (`migrations.json`)
+
+`migrations.json` is an execution catalog consumed by CLI; it is not the migration strategy source.
+
+```json
+{
+  "version": "1",
+  "migrations": [
+    {
+      "name": "deprecated-packages",
+      "version": "9.0.0",
+      "fromVersion": "8.0.0",
+      "description": "Replace deprecated @fluentui package imports with supported equivalents",
+      "package": "@fluentui/react-components",
+      "kind": "ast",
+      "implementation": "./dist/transforms/v9/deprecated-packages.js",
+      "idempotent": true
+    },
+    {
+      "name": "deprecated-props",
+      "version": "9.0.0",
+      "fromVersion": "8.0.0",
+      "description": "Replace @deprecated props across v9 components with their supported replacements",
+      "package": "@fluentui/react-components",
+      "kind": "ast",
+      "implementation": "./dist/transforms/v9/deprecated-props.js",
+      "idempotent": true
+    }
+  ]
+}
+```
+
+Fields:
+
+- `kind`: `ast` | `nx-generator` | `composite`
+- `implementation`: path to compiled entrypoint, resolved from package root
+- `idempotent`: required declaration — transforms that cannot guarantee idempotency are not permitted in MVP
+
+---
+
+### 6.3 Migration Types
+
+1. **AST transform** (default): codemods for imports, props, JSX shape. Implemented as standard jscodeshift transforms.
+2. **Nx-style migration wrapper**: invokes migration-style scripts through the unified CLI contract.
+3. **Composite migration**: ordered list of atomic migrations with shared context.
+
+---
+
+## 7) Agent Skills Spec
+
+Skills are the authoritative migration source for this project.
+
+### 7.1 Location
+
+`skills/<skill-name>.md` at the **repo root**. Versioned with the codebase. Distributed via the `npx skills add` tooling (external).
+
+> Note: `packages/react-components/react-components-agent-skills/` exists as an empty placeholder — it is **not used** for this project.
+
+### 7.2 Skill Inventory (MVP)
+
+| Skill file                            | Purpose                               |
+| ------------------------------------- | ------------------------------------- |
+| `skills/fluentui-migrate-v8-to-v9.md` | End-to-end v8 → v9 migration workflow |
+
+### 7.3 Skill Workflow Contract
+
+Every skill must follow this baseline sequence:
+
+1. Run `@fluentui/cli report [path] --json` and parse the JSON output.
+2. Determine applicable migration plan from skill rules.
+3. Resolve needed codemod steps against CLI migration list (`migrate --list --json`).
+4. Run `migrate --dry-run --json` and evaluate risk signals against safety thresholds.
+5. Run `migrate --json` (apply step) if safe; confirm with user if large-diff gate triggers.
+6. Run verification (`npx nx run-many -t type-check` on touched projects).
+7. Produce final summary: migrations run, files changed, remaining manual follow-ups.
+
+### 7.4 Skill Safety Thresholds
+
+Defined as named constants in the skill file (hardcoded defaults, documented for review):
+
+| Constant                  | Default | Meaning                                               |
+| ------------------------- | ------- | ----------------------------------------------------- |
+| `PARSE_ERROR_RATE_LIMIT`  | `0.05`  | Stop if >5% of files fail to parse                    |
+| `LARGE_DIFF_FILE_COUNT`   | `100`   | Require human confirmation if >100 files changed      |
+| `UNRESOLVED_IMPORT_LIMIT` | `0`     | Stop if any unresolved imports remain after transform |
+
+### 7.5 Safety Rules
+
+- Never run apply step before dry-run succeeds.
+- Stop if parser error rate exceeds `PARSE_ERROR_RATE_LIMIT`.
+- Stop if transform claims success but outputs unresolved imports.
+- Require human confirmation when changed file count exceeds `LARGE_DIFF_FILE_COUNT`.
+
+---
+
+## 8) Required Codemods (MVP)
+
+### `deprecated-packages`
+
+Rewrites imports from deprecated `@fluentui` packages to their current equivalents.
+
+Deprecated packages (source: `packages/react-components/deprecated/`):
+
+| Deprecated import             | Replacement                           | Note                                                                |
+| ----------------------------- | ------------------------------------- | ------------------------------------------------------------------- |
+| `@fluentui/react-alert`       | `@fluentui/react-toast`               | Insert `// TODO: also consider @fluentui/react-message-bar` comment |
+| `@fluentui/react-infobutton`  | `@fluentui/react-infolabel`           | Rename component `InfoButton` → `InfoLabel`                         |
+| `@fluentui/react-virtualizer` | `@fluentui-contrib/react-virtualizer` | Package moved to contrib                                            |
+
+**Source of truth**: read `packages/react-components/deprecated/*/README.md` before implementing.
+
+### `deprecated-props`
+
+Renames (or removes) deprecated component props to their supported replacements.
+
+Known deprecated props (source: `@deprecated` JSDoc tags in `packages/react-components/`):
+
+| Component            | Deprecated prop       | Replacement                          |
+| -------------------- | --------------------- | ------------------------------------ |
+| `TableSelectionCell` | `hidden`              | `invisible`                          |
+| `Popover`            | `legacyTrapFocus`     | `inertTrapFocus`                     |
+| `Calendar` (compat)  | `overlayedWithButton` | `overlaidWithButton`                 |
+| `PositioningOptions` | `positionFixed`       | `strategy="fixed"` (value transform) |
+| `TagPickerList`      | `disableAutoFocus`    | _(remove — prop has no effect)_      |
+
+**Source of truth**: search `@deprecated` across `packages/react-components/` before implementing to catch any additions.
+
+### Transform conventions
+
+```typescript
+import type { Transform, API, FileInfo } from 'jscodeshift';
+const transform: Transform = (file: FileInfo, api: API): string | void => { ... };
+export default transform;
+// Return undefined → nochange (no write). Must be idempotent.
+```
+
+---
+
+## 9) Package Layout
+
+```sh
+packages/cli/
+├── bin/fluentui.js              # #!/usr/bin/env node shebang
+├── migrations.json              # execution catalog (ships in npm package)
+├── src/
+│   ├── index.ts                 # yargs root — registers migrate + report
+│   ├── types.ts                 # MigrationEntry, RunnerOptions, ReportOutput, ...
+│   ├── commands/
+│   │   ├── migrate.ts
+│   │   └── report.ts
+│   ├── runner/
+│   │   ├── MigrationRunner.ts   # loads registry, filters, invokes jscodeshift Runner API
+│   │   └── semverFilter.ts      # normaliseVersion(), filterMigrationsByRange()
+│   ├── report/
+│   │   ├── packageScanner.ts    # globs node_modules for @fluentui/* versions
+│   │   └── UsageCollector.ts    # jscodeshift read-only visitor for imports + JSX props
+│   ├── transforms/
+│   │   └── v9/
+│   │       ├── deprecated-packages.ts
+│   │       └── deprecated-props.ts
+│   └── __tests__/
+│       ├── semverFilter.test.ts
+│       ├── MigrationRunner.test.ts
+│       ├── report/packageScanner.test.ts
+│       └── transforms/
+│           ├── deprecated-packages/   # golden input/output fixtures
+│           └── deprecated-props/      # golden input/output fixtures
+├── package.json
+├── project.json                 # @nx/js:swc build target, platform:node tag
+├── .swcrc                       # copy from tools/visual-regression-assert/.swcrc
+├── tsconfig.json
+├── tsconfig.lib.json
+├── tsconfig.spec.json
+├── jest.config.ts
+└── eslint.config.js
+```
+
+Skills (repo root, versioned with code):
+
+```sh
+skills/
+└── fluentui-migrate-v8-to-v9.md
+```
+
+---
+
+## 10) Build Tooling
+
+Mirrors `tools/visual-regression-assert/` — the canonical modern Node CLI package in the repo.
+
+| Concern        | Tool                                                                          |
+| -------------- | ----------------------------------------------------------------------------- |
+| Build executor | `@nx/js:swc` — output to `packages/cli/dist/`                                 |
+| SWC config     | `.swcrc` — copy from `tools/visual-regression-assert/.swcrc`                  |
+| Tests          | `@swc/jest` reading `.swcrc`, `testEnvironment: node`                         |
+| TypeScript     | Solution config: `tsconfig.json` → `tsconfig.lib.json` + `tsconfig.spec.json` |
+| Lint           | ESLint flat config, `@fluentui/eslint-plugin` `flat/node` base                |
+
+Workspace changes required:
+
+| File                 | Change                                                      |
+| -------------------- | ----------------------------------------------------------- |
+| `nx.json`            | Add `"packages/cli/**"` to workspace plugin `include` array |
+| `tsconfig.base.json` | Add `"@fluentui/cli": ["packages/cli/src/index.ts"]`        |
+
+---
+
+## 11) Implementation Phases
+
+### Phase 0 — Scaffold
+
+- Create `packages/cli/` with all config files (build, test, lint, TypeScript).
+- Update `nx.json` + `tsconfig.base.json`.
+- Verify `nx build cli` and `nx test cli` pass on empty stubs.
+
+### Phase 1 — Core Engine
+
+- Implement `types.ts`, `semverFilter.ts`, `MigrationRunner.ts` with tests.
+- Implement `migrate` command shell + `--list`, `--dry-run`, `--json` modes.
+- Create `migrations.json` with two entries (stubs, implementations not yet wired).
+- Verify CLI responds correctly to all flags against stub transforms.
+
+### Phase 2 — Codemods
+
+- Implement `deprecated-packages.ts` with golden tests + idempotency test.
+- Implement `deprecated-props.ts` with golden tests + idempotency test.
+- Wire transforms into `migrations.json`.
+
+### Phase 3 — Report Command
+
+- Implement `packageScanner.ts` + tests.
+- Implement `UsageCollector.ts` + tests.
+- Implement `report.ts` command (file write, `--print`, `--json`).
+
+### Phase 4 — Agent Skill
+
+- Author `skills/fluentui-migrate-v8-to-v9/SKILL.md` with safety thresholds, 7-step workflow, CLI invocations.
+- Validate workflow against real CLI output on a sample v8 codebase.
+
+---
+
+## 12) Verification Strategy
+
+- **Unit tests**: runner, semver filter, registry parsing.
+- **Golden tests**: each transform has `*.input.tsx` / `*.output.tsx` fixture pairs.
+- **Idempotency test**: run each transform twice — second run must return `undefined` (no change).
+- **Integration test**: sample v8 app → CLI migrate → typecheck passes.
+- **Skill E2E**: simulated agent execution path using real CLI `--json` outputs.
+
+---
+
+## 13) Risks and Mitigations
+
+- **API drift**: registry versioning + semver gates.
+- **False-positive transforms**: conservative AST matching + dry-run diff review.
+- **Agent overreach**: enforce skills-first policy; CLI is execution-only.
+- **Large monorepo runtime cost**: path scoping + `--cpus` worker control + incremental runs.
+
+---
+
+## 14) Open Decisions — Resolved
+
+| Decision                       | Resolution                                                                                             |
+| ------------------------------ | ------------------------------------------------------------------------------------------------------ |
+| Skills packaging location      | `skills/<name>.md` at repo root. `react-components-agent-skills/` placeholder not used.                |
+| Report migration hints in MVP  | Phase 2 only. MVP `report` is data-only.                                                               |
+| Safety gate threshold defaults | Hardcoded named constants in skill file: parse error 5%, diff gate 100 files, zero unresolved imports. |

From 09aa6bb3f7a993d1c651e35c32e37f27d8a9e1b7 Mon Sep 17 00:00:00 2001
From: Dmytro Kirpa <dmytrokirpa@microsoft.com>
Date: Mon, 2 Mar 2026 16:29:53 +0100
Subject: [PATCH 02/14] wip

---
 docs/plans/fluent-cli.md                      |   4 +-
 skills/fluentui-migrate-v8-to-v9/SKILL.md     | 169 ++++++++
 .../references/codemod-catalog.md             | 363 ++++++++++++++++++
 3 files changed, 533 insertions(+), 3 deletions(-)
 create mode 100644 skills/fluentui-migrate-v8-to-v9/SKILL.md
 create mode 100644 skills/fluentui-migrate-v8-to-v9/references/codemod-catalog.md

diff --git a/docs/plans/fluent-cli.md b/docs/plans/fluent-cli.md
index 1bf70660439a3..6daf71ef2396d 100644
--- a/docs/plans/fluent-cli.md
+++ b/docs/plans/fluent-cli.md
@@ -226,9 +226,7 @@ Skills are the authoritative migration source for this project.
 
 ### 7.1 Location
 
-`skills/<skill-name>.md` at the **repo root**. Versioned with the codebase. Distributed via the `npx skills add` tooling (external).
-
-> Note: `packages/react-components/react-components-agent-skills/` exists as an empty placeholder — it is **not used** for this project.
+`skills/<skill-name>/SKILL.md` at the **repo root**. Versioned with the codebase. Distributed via the `npx skills add` tooling (external).
 
 ### 7.2 Skill Inventory (MVP)
 
diff --git a/skills/fluentui-migrate-v8-to-v9/SKILL.md b/skills/fluentui-migrate-v8-to-v9/SKILL.md
new file mode 100644
index 0000000000000..9b618b2bea173
--- /dev/null
+++ b/skills/fluentui-migrate-v8-to-v9/SKILL.md
@@ -0,0 +1,169 @@
+---
+name: fluentui-migrate-v8-to-v9
+description: >
+  Orchestrates end-to-end migration of a codebase from Fluent UI React v8 (@fluentui/react) to v9
+  (@fluentui/react-components) using the @fluentui/cli toolchain. Use this skill when asked to
+  migrate a project, run migration codemods, analyze what needs to change, or generate a migration
+  plan. Covers: CLI report/migrate commands, codemod selection and sequencing, safety evaluation,
+  verification, and identifying what requires manual migration vs. what can be automated.
+---
+
+# Fluent UI v8 → v9 Migration Workflow
+
+## Safety Thresholds
+
+```
+PARSE_ERROR_RATE_LIMIT  = 0.05   # Stop if >5% of files fail to parse
+LARGE_DIFF_FILE_COUNT   = 100    # Require human confirmation if >100 files changed
+UNRESOLVED_IMPORT_LIMIT = 0      # Stop if any unresolved imports remain after transform
+```
+
+## Safety Rules
+
+- **Never run apply before dry-run succeeds.**
+- Stop if parse error rate exceeds `PARSE_ERROR_RATE_LIMIT`.
+- Stop if transform succeeds but leaves unresolved imports.
+- Require user confirmation when changed file count exceeds `LARGE_DIFF_FILE_COUNT`.
+
+---
+
+## 7-Step Migration Workflow
+
+### Step 1 — Assess (Report)
+
+```sh
+npx @fluentui/cli report <path> --json
+```
+
+Parse the JSON output. Check:
+
+- Which `@fluentui/*` packages are installed and at what versions
+- Total usage count and per-component breakdown
+- Presence of both v8 and v9 packages (mixed mode)
+
+Save the report path for later reference:
+
+```sh
+npx @fluentui/cli report src/ --output ./fluent-report.json
+```
+
+### Step 2 — Plan
+
+From the report output, decide which codemods apply. Use [codemod-catalog.md](references/codemod-catalog.md) to:
+
+1. Identify Tier 1 (mechanical) transforms to run immediately
+2. Identify Tier 2 (partial) transforms that need post-run validation
+3. Identify Tier 3 (manual) patterns that need human migration — estimate scope from usage counts
+
+List available codemods:
+
+```sh
+npx @fluentui/cli migrate --list --json
+```
+
+### Step 3 — Dry Run
+
+Run selected codemods in dry-run mode:
+
+```sh
+# Single codemod
+npx @fluentui/cli migrate deprecated-packages <path> --dry-run --json
+
+# All applicable codemods from registry
+npx @fluentui/cli migrate --run-migrations=migrations.json <path> --dry-run --json
+```
+
+Evaluate dry-run output:
+
+- Check `parseErrors` count against `PARSE_ERROR_RATE_LIMIT`
+- Check `filesChanged` against `LARGE_DIFF_FILE_COUNT`
+- Check `unresolvedImports` against `UNRESOLVED_IMPORT_LIMIT`
+- Stop and report if any threshold is exceeded
+
+### Step 4 — Confirm (if threshold triggered)
+
+If `filesChanged > LARGE_DIFF_FILE_COUNT`, pause and show the user:
+
+- Total files that will be changed
+- Breakdown by codemod
+- Ask for explicit confirmation before proceeding
+
+### Step 5 — Apply
+
+```sh
+npx @fluentui/cli migrate deprecated-packages <path> --json
+npx @fluentui/cli migrate deprecated-props <path> --json
+# ... additional codemods in sequenced order
+```
+
+Run codemods in this sequence (order matters for idempotency):
+
+1. `deprecated-packages` — fix package imports first
+2. `deprecated-props` — fix deprecated props
+3. `import-paths` — consolidate deep path imports to barrel
+4. `aria-props` — aria prop renames
+5. `component-ref` — componentRef → ref
+6. `component-renames` — 1:1 renames
+7. `button-variants` — button variant transforms
+8. Remaining Tier 2 codemods
+
+After each codemod, check returned JSON for errors before proceeding.
+
+### Step 6 — Verify
+
+Run type-check on all touched packages:
+
+```sh
+# In the fluentui monorepo:
+npx nx run-many -t type-check --projects=<touched-projects>
+
+# In a standalone project:
+npx tsc --noEmit
+```
+
+Report any type errors to the user. Type errors after mechanical transforms indicate either:
+
+- A codemod missed a pattern → investigate and fix manually
+- A Tier 3 change still needed → direct user to manual steps
+
+### Step 7 — Summarize
+
+Produce a final summary:
+
+- Codemods run and files changed per codemod
+- Remaining manual migration items (from Tier 3 detection in report)
+- Any type-check failures still open
+- Recommended next actions
+
+---
+
+## Codemod Decision Guide
+
+Load [codemod-catalog.md](references/codemod-catalog.md) to determine:
+
+- Which patterns in the codebase are mechanical (run codemod)
+- Which are partial (run codemod + validate)
+- Which are manual (flag with TODO, estimate effort)
+
+**Key question per usage**: "Can this be transformed without reading surrounding context?" → Yes = Tier 1-2, No = Tier 3.
+
+## Common Flags
+
+```sh
+# Run with TypeScript/TSX parser (default):
+npx @fluentui/cli migrate <codemod> src/ --parser tsx
+
+# Control parallelism for large codebases:
+npx @fluentui/cli migrate <codemod> src/ --cpus 4
+
+# Version-filtered run (skill-driven):
+npx @fluentui/cli migrate src/ --from 8 --to 9
+```
+
+## Component-Specific Migration Guidance
+
+For detailed prop mapping and examples when doing manual or partial migration steps, refer to the companion `fluentui-v8-to-v9` skill which contains:
+
+- Per-component migration guides (Button, Menu, Input, Tabs, Stack, Theme)
+- Full component mapping table
+- Troubleshooting guide
diff --git a/skills/fluentui-migrate-v8-to-v9/references/codemod-catalog.md b/skills/fluentui-migrate-v8-to-v9/references/codemod-catalog.md
new file mode 100644
index 0000000000000..e224f934e0a9e
--- /dev/null
+++ b/skills/fluentui-migrate-v8-to-v9/references/codemod-catalog.md
@@ -0,0 +1,363 @@
+# Codemod Catalog: FluentUI v8 → v9
+
+This catalog classifies every known v8→v9 migration pattern by how much can be automated.
+
+## Tier Classification
+
+| Tier  | Label      | Definition                                                                                     |
+| ----- | ---------- | ---------------------------------------------------------------------------------------------- |
+| **1** | Mechanical | Safe, idempotent, 1:1 transforms. Full automation with high confidence.                        |
+| **2** | Partial    | Automatable with caveats — value transforms, structural prop moves, require validation.        |
+| **3** | Manual     | Architectural changes requiring human judgment. Flag with TODO comment, do not auto-transform. |
+
+---
+
+## Tier 1 — Mechanical (Safe to Automate)
+
+### 1.1 Deprecated Package Imports → Supported Packages
+
+> Codemod name: `deprecated-packages`
+
+| Deprecated import             | Replacement                           | Extra action                                                     |
+| ----------------------------- | ------------------------------------- | ---------------------------------------------------------------- |
+| `@fluentui/react-alert`       | `@fluentui/react-toast`               | Add `// TODO: also consider @fluentui/react-message-bar` comment |
+| `@fluentui/react-infobutton`  | `@fluentui/react-infolabel`           | Rename `InfoButton` → `InfoLabel` in same file                   |
+| `@fluentui/react-virtualizer` | `@fluentui-contrib/react-virtualizer` |                                                                  |
+
+**Source of truth**: `packages/react-components/deprecated/*/README.md`
+
+### 1.2 Hook Import Migration
+
+| v8 import                            | v9 import                                |
+| ------------------------------------ | ---------------------------------------- |
+| `useId` from `@fluentui/react-hooks` | `useId` from `@fluentui/react-utilities` |
+
+### 1.3 Deprecated Props → Supported Replacements
+
+> Codemod name: `deprecated-props`
+
+| Component            | Deprecated prop       | Replacement            | Transform type  |
+| -------------------- | --------------------- | ---------------------- | --------------- |
+| `TableSelectionCell` | `hidden`              | `invisible`            | Rename          |
+| `Popover`            | `legacyTrapFocus`     | `inertTrapFocus`       | Rename          |
+| `Calendar` (compat)  | `overlayedWithButton` | `overlaidWithButton`   | Rename          |
+| `PositioningOptions` | `positionFixed`       | `strategy="fixed"`     | Value transform |
+| `TagPickerList`      | `disableAutoFocus`    | _(remove — no effect)_ | Remove prop     |
+
+**Source of truth**: search `@deprecated` across `packages/react-components/` before implementing.
+
+### 1.4 Aria Prop Renames (All Components)
+
+All components: v8 used camelCase custom props; v9 uses native HTML attributes.
+
+| v8 prop             | v9 prop            |
+| ------------------- | ------------------ |
+| `ariaLabel`         | `aria-label`       |
+| `ariaHidden`        | `aria-hidden`      |
+| `ariaDescribedBy`   | `aria-describedby` |
+| `ariaLabelledBy`    | `aria-labelledby`  |
+| `ariaPositionInSet` | `aria-posinset`    |
+| `ariaSetSize`       | `aria-setsize`     |
+
+### 1.5 Ref Migration (All Components)
+
+| v8             | v9    |
+| -------------- | ----- |
+| `componentRef` | `ref` |
+
+### 1.6 Import Path Consolidation
+
+v8 allowed deep path imports (e.g. `@fluentui/react/lib/Button`). v9 uses the barrel export only.
+
+```ts
+// v8 (both forms valid)
+import { Button } from '@fluentui/react';
+import { Button } from '@fluentui/react/lib/Button';
+
+// v9 (only barrel)
+import { Button } from '@fluentui/react-components';
+```
+
+Codemod: rewrite any `@fluentui/react/lib/*` to the barrel `@fluentui/react-components` (with correct named export per component-mapping).
+
+### 1.7 Direct Component Renames (1:1, No Prop Changes)
+
+| v8 component        | v9 component     | Notes                                    |
+| ------------------- | ---------------- | ---------------------------------------- |
+| `Separator`         | `Divider`        | Same import package                      |
+| `Toggle`            | `Switch`         |                                          |
+| `Shimmer`           | `Skeleton`       |                                          |
+| `ProgressIndicator` | `ProgressBar`    |                                          |
+| `ComboBox`          | `Combobox`       | Case change only                         |
+| `ThemeProvider`     | `FluentProvider` | theme prop also needs migration (Tier 2) |
+| `Fabric`            | `FluentProvider` |                                          |
+| `Panel`             | `Drawer`         |                                          |
+| `Layer`             | `Portal`         |                                          |
+| `DocumentCard`      | `Card`           |                                          |
+| `SearchBox`         | `SearchBox`      | Same name, new package                   |
+| `Breadcrumb`        | `Breadcrumb`     | Same name, new package                   |
+| `Spinner`           | `Spinner`        | Same name, new package                   |
+| `Tooltip`           | `Tooltip`        | Same name, new package                   |
+| `Slider`            | `Slider`         | Same name, new package                   |
+| `MessageBar`        | `MessageBar`     | Same name, new package                   |
+| `Nav`               | `Nav`            | Same name, new package                   |
+
+---
+
+## Tier 2 — Partially Automatable (Validate Output)
+
+### 2.1 Button Variant → appearance Prop
+
+| v8 component       | v9 equivalent                     | Transform          |
+| ------------------ | --------------------------------- | ------------------ |
+| `DefaultButton`    | `Button`                          | Rename             |
+| `PrimaryButton`    | `Button appearance="primary"`     | Rename + add prop  |
+| `ActionButton`     | `Button appearance="transparent"` | Rename + add prop  |
+| `CommandButton`    | `Button`                          | Rename             |
+| `CommandBarButton` | `Button`                          | Rename             |
+| `ToggleButton`     | `ToggleButton`                    | Import change only |
+| `CompoundButton`   | `CompoundButton`                  | Import change only |
+
+**Caveat**: `IconButton` requires removing text children — flag if children exist.
+
+### 2.2 Button `text` Prop → `children`
+
+```tsx
+// v8
+<PrimaryButton text="Submit" />
+// v9
+<Button appearance="primary">Submit</Button>
+```
+
+Automatable when `text` is a static string literal. Flag if `text` is a variable or expression — generate TODO comment.
+
+### 2.3 Button `primary` Prop → `appearance`
+
+```tsx
+// v8: <Button primary />
+// v9: <Button appearance="primary" />
+```
+
+Straightforward prop value transform.
+
+### 2.4 Checkbox `indeterminate` → `checked="mixed"`
+
+```tsx
+// v8: <Checkbox indeterminate={true} />
+// v9: <Checkbox checked="mixed" />
+```
+
+Safe when `indeterminate` is statically `true`. Flag dynamic values.
+
+### 2.5 TextField `multiline` → `Textarea`
+
+```tsx
+// v8: <TextField multiline rows={3} />
+// v9: <Textarea rows={3} />
+```
+
+Automatable when `multiline` is statically `true`. When dynamic (e.g. `multiline={isMultiline}`), generate TODO comment and leave unchanged.
+
+### 2.6 Pivot/TabList Prop Renames
+
+| v8 `Pivot` prop      | v9 `TabList` prop      |
+| -------------------- | ---------------------- |
+| `defaultSelectedKey` | `defaultSelectedValue` |
+| `selectedKey`        | `selectedValue`        |
+| `onLinkClick`        | `onTabSelect`          |
+| `linkSize`           | `size`                 |
+
+| v8 `PivotItem` prop | v9 `Tab` prop                   |
+| ------------------- | ------------------------------- |
+| `itemKey`           | `value`                         |
+| `headerText`        | children (move to JSX children) |
+| `itemIcon`          | `icon` slot                     |
+
+**Caveat**: `headerText` → children requires moving prop to JSX children — automatable for static string values.
+
+### 2.7 Input Prop Renames
+
+| v8 `TextField` prop | v9 `Input` prop               |
+| ------------------- | ----------------------------- |
+| `prefix`            | `contentBefore`               |
+| `suffix`            | `contentAfter`                |
+| `inputClassName`    | `input` slot                  |
+| `underlined`        | `appearance="underline"`      |
+| `borderless`        | `appearance="filled-lighter"` |
+| `elementRef`        | `ref`                         |
+
+### 2.8 RadioGroup Prop Renames
+
+| v8 `ChoiceGroup`     | v9 `RadioGroup`   |
+| -------------------- | ----------------- |
+| `defaultSelectedKey` | `defaultValue`    |
+| `selectedKey`        | `value`           |
+| `ariaLabelledBy`     | `aria-labelledby` |
+
+### 2.9 `styles` Prop → TODO Comment
+
+The `styles` prop is removed in v9. Codemod should:
+
+1. Remove the `styles` prop
+2. Insert `{/* TODO: migrate styles to makeStyles — see https://aka.ms/fluentui-v9-styles */}` comment above the JSX element
+
+**Do not attempt to auto-convert style objects** — they require manual `makeStyles` authoring.
+
+### 2.10 `mergeStyles` / `mergeStyleSets` → TODO Comment
+
+Flag any imports of `mergeStyles`, `mergeStyleSets`, `IStyle` from `@fluentui/react`:
+
+- Add `// TODO: replace mergeStyles with makeStyles from @fluentui/react-components` comment
+- Do not remove the code — leave it for manual migration
+
+### 2.11 Icon Migration (Requires Name Mapping Table)
+
+```tsx
+// v8
+<Button iconProps={{ iconName: 'Add' }} />;
+
+// v9
+import { AddRegular } from '@fluentui/react-icons';
+<Button icon={<AddRegular />} />;
+```
+
+Automatable **only if** an icon name → React component mapping table exists. Without the table, flag all `iconProps` usages with:
+
+```ts
+// TODO: replace iconProps={{ iconName: 'Add' }} with icon slot using @fluentui/react-icons
+```
+
+---
+
+## Tier 3 — Manual Only (Flag and Comment)
+
+These patterns require architectural changes. A codemod should **detect and annotate** but not transform.
+
+### 3.1 ContextualMenu / menuProps → Menu JSX Children
+
+**Why manual**: Items array must be converted to JSX component hierarchy with correct component types per item type.
+
+```tsx
+// v8 — data-driven
+<ContextualMenu items={[
+  { key: 'a', text: 'Action A', onClick: handleA },
+  { key: 'div1', itemType: ContextualMenuItemType.Divider },
+  { key: 'sub', text: 'Submenu', subMenuProps: { items: [...] } },
+]} />
+
+// v9 — declarative
+<Menu>
+  <MenuTrigger>...</MenuTrigger>
+  <MenuPopover>
+    <MenuList>
+      <MenuItem onClick={handleA}>Action A</MenuItem>
+      <MenuDivider />
+      <Menu>
+        <MenuTrigger><MenuItem hasSubmenu>Submenu</MenuItem></MenuTrigger>
+        <MenuPopover><MenuList>...</MenuList></MenuPopover>
+      </Menu>
+    </MenuList>
+  </MenuPopover>
+</Menu>
+```
+
+**Codemod action**: detect `ContextualMenu` usages, insert `// TODO: migrate ContextualMenu to Menu with JSX children` comment.
+
+### 3.2 Stack / StackItem → makeStyles + Flexbox
+
+**Why manual**: Stack's layout props map to CSS flexbox properties that require per-component `makeStyles` definitions.
+
+**Codemod action**: detect `Stack` imports and usages, insert comment. Optionally offer `StackShim` as a temporary bridge.
+
+```ts
+// TODO: Replace Stack with makeStyles flexbox — see fluentui-v8-to-v9 skill stack.md
+```
+
+### 3.3 Label Extraction from Component Props
+
+**Why manual**: Components like `TextField`, `ChoiceGroup`, `CheckBox` had a `label` prop that v9 splits into a separate `<Label>` element requiring a `useId`-linked `htmlFor`/`aria-labelledby`.
+
+```tsx
+// v8
+<TextField label="Email" />
+
+// v9 — requires new Label element and ID coordination
+const emailId = useId('email');
+<Label htmlFor={emailId}>Email</Label>
+<Input id={emailId} />
+```
+
+**Codemod action**: flag `label` props on `TextField`, `ChoiceGroup`, `SpinButton`, `Slider` with TODO comment.
+
+### 3.4 ChoiceGroup options Array → RadioGroup + Radio Children
+
+**Why manual**: `options` array maps to `Radio` components — data-driven patterns need to become JSX.
+
+**Codemod action**: detect `ChoiceGroup options={...}` and insert TODO comment.
+
+### 3.5 Facepile personas Array → AvatarGroup Children
+
+**Why manual**: `personas` array + overflow logic needs to be refactored to `AvatarGroup` + `AvatarGroupItem` + `AvatarGroupPopover` using `partitionAvatarGroupItems`.
+
+**Codemod action**: detect `Facepile` usages, insert TODO comment.
+
+### 3.6 Custom Theme Migration
+
+**Why manual**: v8 `IPalette` → v9 `BrandVariants` requires expanding 9 theme colors to 16 + mapping semantic tokens.
+
+**Codemod action**: detect `ThemeProvider theme={customVar}` where theme is not a Fluent built-in, insert TODO comment with reference to theme shim utilities.
+
+### 3.7 onRender\* Callbacks → Slot Pattern
+
+**Why manual**: Each `onRender*` prop maps to a specific v9 slot, and the slot API (accepts JSX, shorthand, or render function) requires case-by-case analysis.
+
+**Codemod action**: detect any `onRender` prop names and insert TODO comment per occurrence.
+
+### 3.8 DetailsList → DataGrid
+
+**Why manual**: Completely different API — columns, rows, selection, sorting all change significantly.
+
+**Codemod action**: detect `DetailsList` imports and flag with TODO comment.
+
+### 3.9 Pivot Content → State-Managed Tab Content
+
+**Why manual**: `PivotItem` children (tab content) must be extracted out of the `TabList` hierarchy and rendered conditionally based on selected tab state.
+
+**Codemod action**: after renaming `Pivot` → `TabList`, detect `Tab` components with children that aren't the tab label and insert TODO comment.
+
+---
+
+## Summary: What to Build as Codemods
+
+### MVP Codemods (per spec)
+
+| Codemod               | Tier | Status           |
+| --------------------- | ---- | ---------------- |
+| `deprecated-packages` | 1    | Required for MVP |
+| `deprecated-props`    | 1    | Required for MVP |
+
+### Recommended Next Codemods (High ROI)
+
+| Codemod               | Tier | Description                                            |
+| --------------------- | ---- | ------------------------------------------------------ |
+| `import-paths`        | 1    | Rewrite `@fluentui/react/lib/*` deep imports to barrel |
+| `aria-props`          | 1    | `ariaLabel` → `aria-label` etc. across all components  |
+| `component-ref`       | 1    | `componentRef` → `ref` across all components           |
+| `component-renames`   | 1    | 1:1 renames (Separator→Divider, Toggle→Switch, etc.)   |
+| `button-variants`     | 2    | PrimaryButton → `Button appearance="primary"`, etc.    |
+| `button-text-prop`    | 2    | `text` prop → children (static strings only)           |
+| `textfield-multiline` | 2    | `TextField multiline` → `Textarea` (static only)       |
+| `pivot-props`         | 2    | Pivot/PivotItem prop renames                           |
+| `styles-flag`         | 2    | Remove `styles` prop + insert TODO comment             |
+| `todo-annotations`    | 3    | Detect Tier 3 patterns, insert TODO comments + skip    |
+
+### Detection-Only Codemods (for `report` command)
+
+These should be detected by `UsageCollector` and surfaced in `fluent-report.json` usage inventory:
+
+- All `ContextualMenu` / `menuProps` usages → manual migration count
+- All `Stack` / `StackItem` usages → manual migration count
+- All `label` prop usages on text inputs → manual migration count
+- All `onRender*` prop usages → manual migration count
+- All `styles` prop usages → partially-automatable count
+- All `iconProps` usages → flag for icon name mapping

From d9ac8388053afa703181642ae16cf0d12f4bb3a5 Mon Sep 17 00:00:00 2001
From: Dmytro Kirpa <dmytrokirpa@microsoft.com>
Date: Mon, 2 Mar 2026 23:56:41 +0100
Subject: [PATCH 03/14] feat: add fluentui-migrate-v8-to-v9 skill

---
 skills/fluentui-migrate-v8-to-v9/SKILL.md     | 452 ++++++++++++++----
 .../references/avatargroup.md                 |  90 ++++
 .../references/button.md                      | 163 +++++++
 .../references/callout.md                     | 169 +++++++
 .../references/checkbox.md                    | 106 ++++
 .../references/codemod-catalog.md             | 363 --------------
 .../references/datagrid.md                    | 236 +++++++++
 .../references/dialog.md                      | 211 ++++++++
 .../references/drawer.md                      | 157 ++++++
 .../references/dropdown.md                    | 246 ++++++++++
 .../references/icons.md                       | 114 +++++
 .../references/input.md                       | 123 +++++
 .../references/menu.md                        | 144 ++++++
 .../references/messagebar.md                  | 135 ++++++
 .../references/progressbar.md                 |  96 ++++
 .../references/radiogroup.md                  | 132 +++++
 .../references/slider.md                      | 122 +++++
 .../references/spinbutton.md                  | 137 ++++++
 .../references/spinner.md                     |  69 +++
 .../references/stack.md                       | 153 ++++++
 .../references/tabs.md                        | 103 ++++
 .../references/theme.md                       | 205 ++++++++
 .../references/toolbar.md                     | 236 +++++++++
 .../references/tooltip.md                     | 130 +++++
 24 files changed, 3623 insertions(+), 469 deletions(-)
 create mode 100644 skills/fluentui-migrate-v8-to-v9/references/avatargroup.md
 create mode 100644 skills/fluentui-migrate-v8-to-v9/references/button.md
 create mode 100644 skills/fluentui-migrate-v8-to-v9/references/callout.md
 create mode 100644 skills/fluentui-migrate-v8-to-v9/references/checkbox.md
 delete mode 100644 skills/fluentui-migrate-v8-to-v9/references/codemod-catalog.md
 create mode 100644 skills/fluentui-migrate-v8-to-v9/references/datagrid.md
 create mode 100644 skills/fluentui-migrate-v8-to-v9/references/dialog.md
 create mode 100644 skills/fluentui-migrate-v8-to-v9/references/drawer.md
 create mode 100644 skills/fluentui-migrate-v8-to-v9/references/dropdown.md
 create mode 100644 skills/fluentui-migrate-v8-to-v9/references/icons.md
 create mode 100644 skills/fluentui-migrate-v8-to-v9/references/input.md
 create mode 100644 skills/fluentui-migrate-v8-to-v9/references/menu.md
 create mode 100644 skills/fluentui-migrate-v8-to-v9/references/messagebar.md
 create mode 100644 skills/fluentui-migrate-v8-to-v9/references/progressbar.md
 create mode 100644 skills/fluentui-migrate-v8-to-v9/references/radiogroup.md
 create mode 100644 skills/fluentui-migrate-v8-to-v9/references/slider.md
 create mode 100644 skills/fluentui-migrate-v8-to-v9/references/spinbutton.md
 create mode 100644 skills/fluentui-migrate-v8-to-v9/references/spinner.md
 create mode 100644 skills/fluentui-migrate-v8-to-v9/references/stack.md
 create mode 100644 skills/fluentui-migrate-v8-to-v9/references/tabs.md
 create mode 100644 skills/fluentui-migrate-v8-to-v9/references/theme.md
 create mode 100644 skills/fluentui-migrate-v8-to-v9/references/toolbar.md
 create mode 100644 skills/fluentui-migrate-v8-to-v9/references/tooltip.md

diff --git a/skills/fluentui-migrate-v8-to-v9/SKILL.md b/skills/fluentui-migrate-v8-to-v9/SKILL.md
index 9b618b2bea173..c7bd906ac4bde 100644
--- a/skills/fluentui-migrate-v8-to-v9/SKILL.md
+++ b/skills/fluentui-migrate-v8-to-v9/SKILL.md
@@ -1,169 +1,409 @@
 ---
 name: fluentui-migrate-v8-to-v9
-description: >
-  Orchestrates end-to-end migration of a codebase from Fluent UI React v8 (@fluentui/react) to v9
-  (@fluentui/react-components) using the @fluentui/cli toolchain. Use this skill when asked to
-  migrate a project, run migration codemods, analyze what needs to change, or generate a migration
-  plan. Covers: CLI report/migrate commands, codemod selection and sequencing, safety evaluation,
-  verification, and identifying what requires manual migration vs. what can be automated.
+description: 'Guides migration from Fluent UI React v8 (@fluentui/react) to v9 (@fluentui/react-components). Use when asked to migrate a component or codebase, explain what replaces a v8 component, compare v8 and v9 APIs, or troubleshoot visual/styling issues after migration. Covers: component mapping, prop changes, architectural shifts (FluentProvider, Griffel makeStyles, slots, declarative children), and common troubleshooting.'
 ---
 
-# Fluent UI v8 → v9 Migration Workflow
+# Fluent UI v8 → v9 Migration
 
-## Safety Thresholds
+## Migration Workflow
 
-```
-PARSE_ERROR_RATE_LIMIT  = 0.05   # Stop if >5% of files fail to parse
-LARGE_DIFF_FILE_COUNT   = 100    # Require human confirmation if >100 files changed
-UNRESOLVED_IMPORT_LIMIT = 0      # Stop if any unresolved imports remain after transform
-```
+### Step 1 — Assess
 
-## Safety Rules
+Find all files using v8:
 
-- **Never run apply before dry-run succeeds.**
-- Stop if parse error rate exceeds `PARSE_ERROR_RATE_LIMIT`.
-- Stop if transform succeeds but leaves unresolved imports.
-- Require user confirmation when changed file count exceeds `LARGE_DIFF_FILE_COUNT`.
+```sh
+# All files importing from @fluentui/react
+grep -rl "@fluentui/react" src/ --include="*.tsx" --include="*.ts"
 
----
+# Tally component usage to prioritize
+grep -rh "from '@fluentui/react'" src/ | sort | uniq -c | sort -rn
+```
 
-## 7-Step Migration Workflow
+Identify which components are used and how many times. Migrate high-count simple components first.
 
-### Step 1 — Assess (Report)
+### Step 2 — Setup
 
 ```sh
-npx @fluentui/cli report <path> --json
+npm install @fluentui/react-components @fluentui/react-icons
+# If running v8 + v9 side-by-side:
+npm install @fluentui/react-portal-compat
+# Shim package for incremental migration (optional — see below):
+npm install @fluentui/react-migration-v8-v9
 ```
 
-Parse the JSON output. Check:
+Wrap the app root (or each subtree using v9 components):
+
+```tsx
+import { FluentProvider, webLightTheme } from '@fluentui/react-components';
+// If v9 inside v8 Callout/Panel:
+import { PortalCompatProvider } from '@fluentui/react-portal-compat';
 
-- Which `@fluentui/*` packages are installed and at what versions
-- Total usage count and per-component breakdown
-- Presence of both v8 and v9 packages (mixed mode)
+<FluentProvider theme={webLightTheme}>
+  <PortalCompatProvider>
+    {' '}
+    {/* only if needed */}
+    <App />
+  </PortalCompatProvider>
+</FluentProvider>;
+```
 
-Save the report path for later reference:
+### Step 3 — Migrate (file by file)
+
+**Recommended order within a file:**
+
+1. Update import statements (`@fluentui/react` → `@fluentui/react-components`)
+2. Rename components per the mapping table below
+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)
+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))
+
+**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)
+
+### Step 4 — Verify
 
 ```sh
-npx @fluentui/cli report src/ --output ./fluent-report.json
-```
+# After each file or batch — catch type errors early:
+npx tsc --noEmit
 
-### Step 2 — Plan
+# Confirm no v8 imports remain:
+grep -r "from '@fluentui/react'" src/ --include="*.tsx" --include="*.ts"
+# Should only show @fluentui/react-components imports
+```
 
-From the report output, decide which codemods apply. Use [codemod-catalog.md](references/codemod-catalog.md) to:
+**Visual / runtime checks (open the app after each batch):**
 
-1. Identify Tier 1 (mechanical) transforms to run immediately
-2. Identify Tier 2 (partial) transforms that need post-run validation
-3. Identify Tier 3 (manual) patterns that need human migration — estimate scope from usage counts
+- **Unstyled components** (raw HTML with no Fluent design) → `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
+- **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
 
-List available codemods:
+---
 
-```sh
-npx @fluentui/cli migrate --list --json
+## Key Architectural Shifts
+
+| Area             | v8                                             | v9                                                               |
+| ---------------- | ---------------------------------------------- | ---------------------------------------------------------------- |
+| Styling          | Runtime CSS-in-JS via `mergeStyles`            | Build-time atomic CSS via Griffel `makeStyles`                   |
+| Theme            | `ThemeProvider` + JS theme object on context   | `FluentProvider` + CSS variables                                 |
+| Theme tokens     | Component-specific (`buttonBackgroundHovered`) | Semantic design tokens (`colorNeutralBackground1Hover`)          |
+| Style override   | `styles` prop on every component               | `className` prop + `makeStyles`                                  |
+| Menu / pickers   | Data-driven (items array)                      | Declarative JSX children                                         |
+| Render callbacks | `onRender*` props                              | Slots (accept JSX, shorthand, or render fn)                      |
+| Ref              | `componentRef`                                 | `ref` (standard React ref)                                       |
+| Aria props       | camelCase (`ariaLabel`)                        | Native HTML (`aria-label`)                                       |
+| Icons            | `iconProps={{ iconName: 'Add' }}`              | `icon={<AddRegular />}` from `@fluentui/react-icons`             |
+| Form labels      | `label` prop on the control                    | `<Field label="...">` wrapping the control                       |
+| Polymorphism     | No `as` prop; use `href` on Button             | `as` prop changes rendered element: `<Button as="a" href="...">` |
+
+## Slot System (v9 Core Concept)
+
+v9 components expose named **slots** instead of `onRender*` callbacks. Every slot prop accepts:
+
+1. **JSX element** — `icon={<AddRegular />}`
+2. **Shorthand object** — `label={{ children: 'Name', style: { fontWeight: 'bold' } }}`
+3. **`null`** — removes the slot entirely: `icon={null}`
+4. **Render function** (advanced) — `icon={(props) => <span {...props} className="my-icon" />}`
+
+```tsx
+// v8 — render callback
+<Button onRenderIcon={() => <MyIcon />} onRenderText={() => <b>Bold text</b>} />
+
+// v9 — slots
+<Button icon={<MyIcon />}>
+  <b>Bold text</b>
+</Button>
+
+// v9 — shorthand object for extra props
+<Button icon={{ children: <MyIcon />, style: { color: 'red' } }}>Label</Button>
+
+// v9 — remove a default slot
+<Button icon={null} />  // hides the default icon
 ```
 
-### Step 3 — Dry Run
+## `disableButtonEnhancement` on Trigger Components
 
-Run selected codemods in dry-run mode:
+`MenuTrigger`, `PopoverTrigger`, and `DialogTrigger` automatically wrap their child in a `<button>` unless the child is already interactive. When using FluentUI button components (`Button`, `ToolbarButton`, `SplitButton`, etc.) as a trigger, always add `disableButtonEnhancement` to prevent nested `<button>` in the DOM:
 
-```sh
-# Single codemod
-npx @fluentui/cli migrate deprecated-packages <path> --dry-run --json
+```tsx
+// WRONG — Button is already a <button>; without disableButtonEnhancement
+// FluentUI wraps it in another <button> → invalid HTML
+<MenuTrigger>
+  <Button>Open menu</Button>  // ❌ nested <button><button>
+</MenuTrigger>
+
+// CORRECT — disableButtonEnhancement tells the trigger not to wrap
+<MenuTrigger disableButtonEnhancement>
+  <Button>Open menu</Button>  // ✅ single <button>
+</MenuTrigger>
 
-# All applicable codemods from registry
-npx @fluentui/cli migrate --run-migrations=migrations.json <path> --dry-run --json
+// OK — non-button trigger (e.g., custom div) does NOT need it
+<PopoverTrigger>
+  <div role="button" tabIndex={0}>Click me</div>  // ✅ wrapped in <button> → valid
+</PopoverTrigger>
 ```
 
-Evaluate dry-run output:
+Rule of thumb: add `disableButtonEnhancement` when the trigger child is a FluentUI `Button`, `ToolbarButton`, `MenuItem`, `Tab`, or any component that already renders `<button>`.
+
+## 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) |
+
+### New in v9 (no v8 equivalent)
+
+`Accordion`, `Avatar`, `AvatarGroup`, `Badge` / `CounterBadge` / `PresenceBadge`, `Carousel`, `Drawer`, `InfoLabel`, `Popover`, `ProgressBar`, `Skeleton`, `Switch`, `SwatchPicker`, `Toast` / `Toaster`, `TeachingPopover`, `TabList`
+
+#### Toast / Toaster (quick start)
+
+v9 provides a first-class toast system. If the v8 codebase used a third-party library (react-toastify, etc.) or custom toast state, migrate to `Toaster`:
+
+```tsx
+import { useToastController, Toaster, Toast, ToastTitle, ToastBody } from '@fluentui/react-components';
+
+// 1. Mount <Toaster> once near the root (inside FluentProvider):
+<Toaster toasterId="main" />;
+
+// 2. Dispatch toasts from anywhere using the controller hook:
+const { dispatchToast } = useToastController('main');
+
+dispatchToast(
+  <Toast>
+    <ToastTitle>Upload complete</ToastTitle>
+    <ToastBody>Your file has been saved.</ToastBody>
+  </Toast>,
+  { intent: 'success' },
+);
+```
 
-- Check `parseErrors` count against `PARSE_ERROR_RATE_LIMIT`
-- Check `filesChanged` against `LARGE_DIFF_FILE_COUNT`
-- Check `unresolvedImports` against `UNRESOLVED_IMPORT_LIMIT`
-- Stop and report if any threshold is exceeded
+`intent` values: `"info"` (default) | `"success"` | `"warning"` | `"error"`.
 
-### Step 4 — Confirm (if threshold triggered)
+### Deprecated with no v9 equivalent
 
-If `filesChanged > LARGE_DIFF_FILE_COUNT`, pause and show the user:
+`ActivityItem`, `Announced`, `HoverCard`, `MarqueeSelection`, `Pickers`, `ResizeGroup`, `ScrollablePane`
 
-- Total files that will be changed
-- Breakdown by codemod
-- Ask for explicit confirmation before proceeding
+---
 
-### Step 5 — Apply
+## Common Troubleshooting
 
-```sh
-npx @fluentui/cli migrate deprecated-packages <path> --json
-npx @fluentui/cli migrate deprecated-props <path> --json
-# ... additional codemods in sequenced order
+**Components render with no styles**
+Wrap the app (or subtree) with `FluentProvider`:
+
+```tsx
+import { FluentProvider, webLightTheme } from '@fluentui/react-components';
+<FluentProvider theme={webLightTheme}>
+  <App />
+</FluentProvider>;
+```
+
+**v9 components inside v8 `Callout` / `Panel` have no styles**
+v8 portals render their children outside the `FluentProvider` DOM subtree, so v9 CSS variable injection doesn't reach them. Fix: add `PortalCompatProvider` inside `FluentProvider` — it makes v8 portals inherit the v9 theme context.
+
+```tsx
+import { PortalCompatProvider } from '@fluentui/react-portal-compat';
+<FluentProvider>
+  <PortalCompatProvider>{/* app */}</PortalCompatProvider>
+</FluentProvider>;
 ```
 
-Run codemods in this sequence (order matters for idempotency):
+**v8 `Callout` appears beneath a v9 `Dialog` (z-index stacking)**
+v9 portals render to `document.body` by default, appearing above the v8 layer host even when they shouldn't. Fix: tell v9 portals to mount inside the same v8 layer host so both share the same stacking context.
 
-1. `deprecated-packages` — fix package imports first
-2. `deprecated-props` — fix deprecated props
-3. `import-paths` — consolidate deep path imports to barrel
-4. `aria-props` — aria prop renames
-5. `component-ref` — componentRef → ref
-6. `component-renames` — 1:1 renames
-7. `button-variants` — button variant transforms
-8. Remaining Tier 2 codemods
+```tsx
+import { PortalMountNodeProvider } from '@fluentui/react-components';
+const mountNode = document.getElementById('fluent-default-layer-host');
+<FluentProvider>
+  <PortalMountNodeProvider mountNode={mountNode}>{/* app */}</PortalMountNodeProvider>
+</FluentProvider>;
+```
 
-After each codemod, check returned JSON for errors before proceeding.
+**When to use which:**
 
-### Step 6 — Verify
+- `PortalCompatProvider` — v9 components _inside_ a v8 portal have no styles (theme context problem)
+- `PortalMountNodeProvider` — v9 and v8 portals have wrong z-order relative to each other (stacking problem)
 
-Run type-check on all touched packages:
+**`styles` prop no longer exists**
+Replace with `makeStyles` + `className`:
 
-```sh
-# In the fluentui monorepo:
-npx nx run-many -t type-check --projects=<touched-projects>
+```tsx
+// v8
+<Button styles={{ root: { color: 'red' } }} />;
 
-# In a standalone project:
-npx tsc --noEmit
+// v9
+const useStyles = makeStyles({ btn: { color: 'red' } });
+const s = useStyles();
+<Button className={s.btn} />;
 ```
 
-Report any type errors to the user. Type errors after mechanical transforms indicate either:
+---
 
-- A codemod missed a pattern → investigate and fix manually
-- A Tier 3 change still needed → direct user to manual steps
+## Shim Package — Incremental Migration
 
-### Step 7 — Summarize
+`@fluentui/react-migration-v8-v9` provides shim components that **accept v8 props but render v9 components**. Use them to unblock the build during incremental migration, then replace shims with native v9 components file-by-file.
 
-Produce a final summary:
+**Strategy:** swap the import path + add `Shim` suffix → build passes → migrate to native v9 → remove shim.
 
-- Codemods run and files changed per codemod
-- Remaining manual migration items (from Tier 3 detection in report)
-- Any type-check failures still open
-- Recommended next actions
+### Available shims
 
----
+| Shim                 | Replaces                          | Import                            |
+| -------------------- | --------------------------------- | --------------------------------- |
+| `DefaultButtonShim`  | `DefaultButton`                   | `@fluentui/react-migration-v8-v9` |
+| `PrimaryButtonShim`  | `PrimaryButton`                   | `@fluentui/react-migration-v8-v9` |
+| `ActionButtonShim`   | `ActionButton`                    | `@fluentui/react-migration-v8-v9` |
+| `CommandButtonShim`  | `CommandButton`                   | `@fluentui/react-migration-v8-v9` |
+| `CompoundButtonShim` | `CompoundButton`                  | `@fluentui/react-migration-v8-v9` |
+| `MenuButtonShim`     | `MenuButton` (v8)                 | `@fluentui/react-migration-v8-v9` |
+| `ToggleButtonShim`   | `ToggleButton` (v8)               | `@fluentui/react-migration-v8-v9` |
+| `CheckboxShim`       | `Checkbox`                        | `@fluentui/react-migration-v8-v9` |
+| `MenuItemShim`       | `ContextualMenuItem` item objects | `@fluentui/react-migration-v8-v9` |
+| `StackShim`          | `Stack`                           | `@fluentui/react-migration-v8-v9` |
+| `StackItemShim`      | `Stack.Item`                      | `@fluentui/react-migration-v8-v9` |
 
-## Codemod Decision Guide
+### Usage pattern
 
-Load [codemod-catalog.md](references/codemod-catalog.md) to determine:
+```tsx
+// Step 1 — swap import to shim (v8 props still work, component now renders v9)
+import { PrimaryButtonShim as PrimaryButton } from '@fluentui/react-migration-v8-v9';
 
-- Which patterns in the codebase are mechanical (run codemod)
-- Which are partial (run codemod + validate)
-- Which are manual (flag with TODO, estimate effort)
+// No other changes needed — v8 props are accepted as-is:
+<PrimaryButton text="Submit" onClick={handleSubmit} />;
 
-**Key question per usage**: "Can this be transformed without reading surrounding context?" → Yes = Tier 1-2, No = Tier 3.
+// Step 2 — later, replace with native v9
+import { Button } from '@fluentui/react-components';
+<Button appearance="primary" onClick={handleSubmit}>
+  Submit
+</Button>;
+```
 
-## Common Flags
+### Theme helpers
 
-```sh
-# Run with TypeScript/TSX parser (default):
-npx @fluentui/cli migrate <codemod> src/ --parser tsx
+```ts
+import { createV8Theme, createV9Theme, createBrandVariants } from '@fluentui/react-migration-v8-v9';
 
-# Control parallelism for large codebases:
-npx @fluentui/cli migrate <codemod> src/ --cpus 4
+// Make v8 components match your v9 theme during side-by-side migration:
+const v8CompatTheme = createV8Theme(myV9Theme, myBrandVariants);
 
-# Version-filtered run (skill-driven):
-npx @fluentui/cli migrate src/ --from 8 --to 9
-```
+// Make v9 components match your existing v8 theme:
+const v9CompatTheme = createV9Theme(myV8Theme);
 
-## Component-Specific Migration Guidance
+// Derive a v9 BrandVariants ramp from a v8 IPalette:
+const brandVariants = createBrandVariants(myV8Palette);
+```
 
-For detailed prop mapping and examples when doing manual or partial migration steps, refer to the companion `fluentui-v8-to-v9` skill which contains:
+---
 
-- Per-component migration guides (Button, Menu, Input, Tabs, Stack, Theme)
-- Full component mapping table
-- Troubleshooting guide
+## Per-Component Detail References
+
+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)
+- **Button** (all variants, full prop table) → [references/button.md](references/button.md)
+- **Checkbox** (`indeterminate` → `checked="mixed"`, CheckboxShim) → [references/checkbox.md](references/checkbox.md)
+- **ChoiceGroup / RadioGroup** (`options` array → `Radio` children) → [references/radiogroup.md](references/radiogroup.md)
+- **Facepile / AvatarGroup** (`personas` array → children) → [references/avatargroup.md](references/avatargroup.md)
+- **Menu / ContextualMenu** (data-driven → JSX) → [references/menu.md](references/menu.md)
+- **TextField / Input / Textarea** → [references/input.md](references/input.md)
+- **Pivot / TabList** (content separation) → [references/tabs.md](references/tabs.md)
+- **SpinButton** (label extraction, `onChange` signature change) → [references/spinbutton.md](references/spinbutton.md)
+- **Slider** (label extraction, `onChange` signature change, `showValue` removed) → [references/slider.md](references/slider.md)
+- **Stack → makeStyles flexbox** → [references/stack.md](references/stack.md)
+- **Theme / FluentProvider / makeStyles** → [references/theme.md](references/theme.md)
+- **Dialog / Modal** (composable structure, `hidden` inversion, `modalType`) → [references/dialog.md](references/dialog.md)
+- **Dropdown / Combobox** (options array → `Option` children, `onOptionSelect`) → [references/dropdown.md](references/dropdown.md)
+- **DetailsList / DataGrid** (column definitions, selection Set, sort) → [references/datagrid.md](references/datagrid.md)
+- **Panel / Drawer** (`PanelType` → position + size, `DrawerHeader`, `DrawerBody`) → [references/drawer.md](references/drawer.md)
+- **Tooltip** (`directionalHint` → `positioning`, `relationship` prop, forwardRef trigger) → [references/tooltip.md](references/tooltip.md)
+- **MessageBar** (`messageBarType` → `intent`, composable body/actions) → [references/messagebar.md](references/messagebar.md)
+- **Spinner** (`SpinnerSize` enum → string `size`, `labelPosition` renames) → [references/spinner.md](references/spinner.md)
+- **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)
diff --git a/skills/fluentui-migrate-v8-to-v9/references/avatargroup.md b/skills/fluentui-migrate-v8-to-v9/references/avatargroup.md
new file mode 100644
index 0000000000000..be6af59725a15
--- /dev/null
+++ b/skills/fluentui-migrate-v8-to-v9/references/avatargroup.md
@@ -0,0 +1,90 @@
+# Facepile → AvatarGroup Migration
+
+## Architecture Change
+
+v8 `Facepile` accepts a `personas` array prop and an `overflowPersonas` array.
+
+v9 `AvatarGroup` uses three components:
+
+- `AvatarGroup` — main container (inline items)
+- `AvatarGroupItem` — replaces individual `Persona` items
+- `AvatarGroupPopover` — renders the overflow button + popover with overflow items
+
+Use `partitionAvatarGroupItems` to split a list into inline vs overflow items based on layout.
+
+## Before / After Example
+
+```tsx
+// v8
+import { Facepile, IFacepilePersona } from '@fluentui/react';
+import { facepilePersonas } from '@fluentui/example-data';
+import { PersonaSize } from '@fluentui/react/lib/Persona';
+
+const personas: IFacepilePersona[] = facepilePersonas.slice(0, 3);
+const overflowPersonas = facepilePersonas.slice(3);
+
+<Facepile personaSize={PersonaSize.size32} personas={personas} overflowPersonas={overflowPersonas} />;
+```
+
+```tsx
+// v9
+import {
+  AvatarGroup,
+  AvatarGroupItem,
+  AvatarGroupPopover,
+  partitionAvatarGroupItems,
+} from '@fluentui/react-components';
+
+const names = [
+  'Johnie McConnell',
+  'Allan Munger',
+  'Erik Nason',
+  'Kristin Patterson',
+  'Daisy Phillips',
+  'Carole Poland',
+];
+
+const { inlineItems, overflowItems } = partitionAvatarGroupItems({ items: names });
+
+<AvatarGroup size={32}>
+  {inlineItems.map(name => (
+    <AvatarGroupItem name={name} key={name} />
+  ))}
+  {overflowItems.length > 0 && (
+    <AvatarGroupPopover>
+      {overflowItems.map(name => (
+        <AvatarGroupItem name={name} key={name} />
+      ))}
+    </AvatarGroupPopover>
+  )}
+</AvatarGroup>;
+```
+
+## partitionAvatarGroupItems Options
+
+```ts
+const { inlineItems, overflowItems } = partitionAvatarGroupItems({
+  items: names,
+  layout: 'spread', // 'spread' | 'stack' | 'pie' — controls overflow behavior
+  maxInlineItems: 5, // override max inline count (default depends on layout)
+});
+```
+
+## Facepile → AvatarGroup Prop Mapping
+
+| v8 `IFacepileProps`      | v9                                          | Notes                                          |
+| ------------------------ | ------------------------------------------- | ---------------------------------------------- |
+| `personas`               | `children` (`AvatarGroupItem` elements)     | Use `partitionAvatarGroupItems` to split items |
+| `overflowPersonas`       | `AvatarGroupPopover` children               |                                                |
+| `personaSize`            | `size` on `AvatarGroup`                     | Numeric pixel value                            |
+| `maxDisplayablePersonas` | `maxAvatars` in `partitionAvatarGroupItems` |                                                |
+| `getPersonaProps`        | `AvatarGroupItem` props                     | Pass props directly to each `AvatarGroupItem`  |
+| `onRenderPersona`        | Render custom `AvatarGroupItem`             |                                                |
+| `onRenderPersonaCoin`    | `avatar` slot on `AvatarGroupItem`          |                                                |
+| `overflowButtonProps`    | `AvatarGroupPopover` props                  |                                                |
+| `overflowButtonType`     | `indicator` prop on `AvatarGroupPopover`    |                                                |
+| `addButtonProps`         | —                                           | Not available in v9                            |
+| `showAddButton`          | —                                           | Not available in v9                            |
+| `showTooltip`            | —                                           | Tooltips handled differently in v9             |
+| `className`              | `className`                                 |                                                |
+| `styles`                 | `className`                                 |                                                |
diff --git a/skills/fluentui-migrate-v8-to-v9/references/button.md b/skills/fluentui-migrate-v8-to-v9/references/button.md
new file mode 100644
index 0000000000000..6468df87a8d48
--- /dev/null
+++ b/skills/fluentui-migrate-v8-to-v9/references/button.md
@@ -0,0 +1,163 @@
+# Button Migration
+
+## Variant Mapping
+
+| v8                     | v9                                | Notes                                     |
+| ---------------------- | --------------------------------- | ----------------------------------------- |
+| `DefaultButton`        | `Button`                          |                                           |
+| `PrimaryButton`        | `Button appearance="primary"`     |                                           |
+| `ActionButton`         | `Button appearance="transparent"` |                                           |
+| `CommandButton`        | `MenuButton`                      | Use when triggering a menu                |
+| `CommandBarButton`     | `ToolbarButton`                   | Inside a `Toolbar`; standalone → `Button` |
+| `CompoundButton`       | `CompoundButton`                  | Same name, new package                    |
+| `ContextualMenuButton` | `Menu` / `MenuButton`             |                                           |
+| `Button split`         | `SplitButton`                     |                                           |
+| `Button toggle`        | `ToggleButton`                    | Same name, new package                    |
+
+## Before / After Examples
+
+### PrimaryButton
+
+```tsx
+// v8
+import { PrimaryButton } from '@fluentui/react';
+<PrimaryButton text="Submit" onClick={handleSubmit} />;
+
+// v9
+import { Button } from '@fluentui/react-components';
+<Button appearance="primary" onClick={handleSubmit}>
+  Submit
+</Button>;
+```
+
+### ActionButton with icon
+
+```tsx
+// v8
+import { ActionButton } from '@fluentui/react';
+<ActionButton iconProps={{ iconName: 'Add' }}>Add item</ActionButton>;
+
+// v9
+import { Button } from '@fluentui/react-components';
+import { AddRegular } from '@fluentui/react-icons';
+<Button appearance="transparent" icon={<AddRegular />}>
+  Add item
+</Button>;
+```
+
+### IconButton
+
+```tsx
+// v8
+import { IconButton } from '@fluentui/react';
+<IconButton iconProps={{ iconName: 'Settings' }} title="Settings" />;
+
+// v9
+import { Button } from '@fluentui/react-components';
+import { SettingsRegular } from '@fluentui/react-icons';
+<Button icon={<SettingsRegular />} aria-label="Settings" />;
+```
+
+### Button with href (navigation)
+
+```tsx
+// v8 — button that navigates via href
+import { DefaultButton, PrimaryButton } from '@fluentui/react';
+<DefaultButton href="/dashboard" target="_blank">
+  Go to dashboard
+</DefaultButton>;
+
+// v9 option A — use Link for inline text-style navigation
+import { Link } from '@fluentui/react-components';
+<Link href="/dashboard" target="_blank">
+  Go to dashboard
+</Link>;
+
+// v9 option B — use Button rendered as <a> to keep button appearance
+import { Button } from '@fluentui/react-components';
+<Button as="a" href="/dashboard" target="_blank" appearance="primary">
+  Go to dashboard
+</Button>;
+```
+
+`Button as="a"` renders the full button affordance as an anchor element (correct `<a>` in the DOM,
+supports `href`, `target`, `rel`). Use `Link` for inline prose links; use `Button as="a"` when the
+design needs a button shape that navigates.
+
+### SplitButton
+
+```tsx
+// v8
+import { DefaultButton } from '@fluentui/react';
+<DefaultButton split menuProps={{ items: [...] }}>Action</DefaultButton>
+
+// v9
+import { SplitButton, Menu, MenuItem, MenuList, MenuPopover, MenuTrigger } from '@fluentui/react-components';
+<Menu positioning="below-end">
+  <MenuTrigger>
+    {(triggerProps) => <SplitButton menuButton={triggerProps}>Action</SplitButton>}
+  </MenuTrigger>
+  <MenuPopover>
+    <MenuList>
+      <MenuItem>Option 1</MenuItem>
+    </MenuList>
+  </MenuPopover>
+</Menu>
+```
+
+## Button Shims (Incremental Migration)
+
+All button variants have a shim in `@fluentui/react-migration-v8-v9` that accepts v8 props:
+
+```tsx
+// Swap the import — no other code changes needed
+import {
+  DefaultButtonShim as DefaultButton,
+  PrimaryButtonShim as PrimaryButton,
+  ActionButtonShim as ActionButton,
+  CommandButtonShim as CommandButton,
+  CompoundButtonShim as CompoundButton,
+  MenuButtonShim as MenuButton,
+  ToggleButtonShim as ToggleButton,
+} from '@fluentui/react-migration-v8-v9';
+
+// v8 props still work:
+<PrimaryButton text="Submit" iconProps={{ iconName: 'Add' }} onClick={handler} />;
+```
+
+Replace shims with native v9 components (see examples above) when ready.
+
+## Prop Mapping
+
+| v8 `IButtonProps`     | v9 `ButtonProps`                         | Notes                                                     |
+| --------------------- | ---------------------------------------- | --------------------------------------------------------- |
+| `allowDisabledFocus`  | `disabledFocusable`                      |                                                           |
+| `ariaLabel`           | `aria-label`                             | Native HTML                                               |
+| `ariaDescription`     | —                                        | Removed                                                   |
+| `ariaHidden`          | `aria-hidden`                            | Native HTML                                               |
+| `checked`             | `checked` (ToggleButton)                 |                                                           |
+| `className`           | `className`                              |                                                           |
+| `children`            | `children`                               |                                                           |
+| `componentRef`        | `ref`                                    |                                                           |
+| `data`                | —                                        | Removed                                                   |
+| `disabled`            | `disabled`                               |                                                           |
+| `href`                | `as="a"` + `href`                        | `<Button as="a" href="...">` or use `Link` for text links |
+| `iconProps`           | `icon` (slot)                            | Pass `<IconComponent />`                                  |
+| `menuAs`              | —                                        | Use `Menu` + HTML `as`                                    |
+| `menuIconProps`       | `menuIcon` slot (MenuButton)             |                                                           |
+| `menuProps`           | —                                        | Use `Menu` + `MenuButton`                                 |
+| `onMenuClick`         | `onClick`                                | Native HTML                                               |
+| `onRenderChildren`    | `children`                               |                                                           |
+| `onRenderDescription` | `secondaryContent` slot (CompoundButton) |                                                           |
+| `onRenderIcon`        | `icon` slot                              |                                                           |
+| `onRenderMenuIcon`    | `icon` (MenuButton)                      |                                                           |
+| `onRenderText`        | `children`                               |                                                           |
+| `primary`             | `appearance="primary"`                   |                                                           |
+| `primaryDisabled`     | —                                        | Use SplitButton                                           |
+| `secondaryText`       | `secondaryContent` slot (CompoundButton) |                                                           |
+| `split`               | —                                        | Use `SplitButton`                                         |
+| `styles`              | `className` + `makeStyles`               |                                                           |
+| `text`                | `children`                               | Move to JSX children                                      |
+| `theme`               | —                                        | Use `FluentProvider`                                      |
+| `toggle`              | —                                        | Use `ToggleButton`                                        |
+| `uniqueId`            | `key`                                    | React key                                                 |
diff --git a/skills/fluentui-migrate-v8-to-v9/references/callout.md b/skills/fluentui-migrate-v8-to-v9/references/callout.md
new file mode 100644
index 0000000000000..669d756d89700
--- /dev/null
+++ b/skills/fluentui-migrate-v8-to-v9/references/callout.md
@@ -0,0 +1,169 @@
+# Callout → Popover Migration
+
+## Architecture Change
+
+v8 `Callout` is a standalone component positioned next to a `target` element (ref or DOM node)
+and configured via flat props (`directionalHint`, `isBeakVisible`, `gapSpace`).
+
+v9 `Popover` is **composable**: `PopoverTrigger` wraps the element that opens the popover,
+and `PopoverSurface` contains the floating content. This eliminates the need for a `target` ref
+entirely — the trigger/surface relationship is established by co-location in JSX.
+
+## Before / After Example
+
+```tsx
+// v8
+import { Callout, DirectionalHint } from '@fluentui/react';
+
+const targetRef = React.useRef<HTMLButtonElement>(null);
+const [isVisible, setIsVisible] = React.useState(false);
+
+<>
+  <button ref={targetRef} onClick={() => setIsVisible(true)}>
+    Open
+  </button>
+  {isVisible && (
+    <Callout
+      target={targetRef}
+      onDismiss={() => setIsVisible(false)}
+      directionalHint={DirectionalHint.bottomLeftEdge}
+      isBeakVisible
+      gapSpace={8}
+    >
+      <p style={{ padding: 16 }}>Callout content</p>
+    </Callout>
+  )}
+</>;
+```
+
+```tsx
+// v9
+import { Popover, PopoverTrigger, PopoverSurface, Button } from '@fluentui/react-components';
+
+<Popover withArrow positioning="below-start">
+  <PopoverTrigger disableButtonEnhancement>
+    <Button>Open</Button>
+  </PopoverTrigger>
+  <PopoverSurface style={{ padding: 16 }}>
+    <p>Popover content</p>
+  </PopoverSurface>
+</Popover>;
+```
+
+## Controlled Popover
+
+```tsx
+// v9 — controlled open state (equivalent to Callout hidden={!isVisible})
+const [open, setOpen] = React.useState(false);
+
+<Popover open={open} onOpenChange={(_, data) => setOpen(data.open)} positioning="below-start">
+  <PopoverTrigger disableButtonEnhancement>
+    <Button onClick={() => setOpen(true)}>Open</Button>
+  </PopoverTrigger>
+  <PopoverSurface style={{ padding: 16 }}>
+    <p>Content</p>
+    <Button onClick={() => setOpen(false)}>Close</Button>
+  </PopoverSurface>
+</Popover>;
+```
+
+**Critical:** `hidden={false}` (visible) in v8 → `open={true}` in v9. The logic is inverted.
+
+## Focus Trap (`setInitialFocus` → `trapFocus`)
+
+```tsx
+// v8 — setInitialFocus moves focus into Callout on open
+<Callout target={targetRef} setInitialFocus onDismiss={handleClose}>
+  <FocusTrapZone>
+    <button>Focusable</button>
+  </FocusTrapZone>
+</Callout>
+
+// v9 — trapFocus moves focus in AND traps it; Escape still dismisses
+<Popover trapFocus>
+  <PopoverTrigger disableButtonEnhancement>
+    <Button>Open</Button>
+  </PopoverTrigger>
+  <PopoverSurface>
+    <button>Focusable</button>
+    <Button onClick={() => setOpen(false)}>Close</Button>
+  </PopoverSurface>
+</Popover>
+```
+
+Use `inertTrapFocus` instead of `trapFocus` for a softer accessibility trap (marks background content
+with the `inert` attribute but doesn't require an explicit close button for keyboard users):
+
+```tsx
+<Popover inertTrapFocus>
+```
+
+## Custom Trigger (non-button element)
+
+If the trigger is a custom component, it must forward its `ref` — the same requirement as `Tooltip`.
+
+```tsx
+// v9 — custom trigger must forward ref
+const MyTrigger = React.forwardRef<HTMLDivElement, React.HTMLAttributes<HTMLDivElement>>((props, ref) => (
+  <div ref={ref} role="button" tabIndex={0} {...props} />
+));
+
+<Popover>
+  <PopoverTrigger disableButtonEnhancement>
+    <MyTrigger>Click me</MyTrigger>
+  </PopoverTrigger>
+  <PopoverSurface>Content</PopoverSurface>
+</Popover>;
+```
+
+## DirectionalHint → positioning
+
+| v8 `DirectionalHint` | v9 `positioning`  |
+| -------------------- | ----------------- |
+| `topCenter`          | `"above"`         |
+| `topLeftEdge`        | `"above-start"`   |
+| `topRightEdge`       | `"above-end"`     |
+| `topAutoEdge`        | `"above"`         |
+| `bottomCenter`       | `"below"`         |
+| `bottomLeftEdge`     | `"below-start"`   |
+| `bottomRightEdge`    | `"below-end"`     |
+| `bottomAutoEdge`     | `"below"`         |
+| `leftCenter`         | `"before"`        |
+| `leftTopEdge`        | `"before-top"`    |
+| `leftBottomEdge`     | `"before-bottom"` |
+| `rightCenter`        | `"after"`         |
+| `rightTopEdge`       | `"after-top"`     |
+| `rightBottomEdge`    | `"after-bottom"`  |
+
+For `gapSpace`, pass positioning as an object:
+
+```tsx
+// v8
+<Callout directionalHint={DirectionalHint.bottomLeftEdge} gapSpace={8} />
+
+// v9
+<Popover positioning={{ position: 'below', align: 'start', offset: { mainAxis: 8 } }}>
+```
+
+## ICalloutProps → PopoverProps
+
+| v8                       | v9                                       | Notes                                                          |
+| ------------------------ | ---------------------------------------- | -------------------------------------------------------------- |
+| `target`                 | `<PopoverTrigger>` child                 | Replaces ref-based targeting; trigger is co-located in JSX     |
+| `hidden`                 | `open` (inverted)                        | `hidden={false}` = `open={true}`                               |
+| `onDismiss`              | `onOpenChange`                           | `(ev, data) => data.open === false` on close                   |
+| `directionalHint`        | `positioning`                            | String or object; see table above                              |
+| `gapSpace`               | `positioning={{ offset: { mainAxis } }}` | Pass positioning as object with `offset`                       |
+| `isBeakVisible`          | `withArrow`                              |                                                                |
+| `beakWidth`              | —                                        | Removed                                                        |
+| `setInitialFocus`        | `trapFocus`                              | Also traps focus; use `inertTrapFocus` for softer trap         |
+| `calloutMaxHeight`       | `style` on `<PopoverSurface>`            | `<PopoverSurface style={{ maxHeight: '...' }}>`                |
+| `calloutMaxWidth`        | `style` on `<PopoverSurface>`            | `<PopoverSurface style={{ maxWidth: '...' }}>`                 |
+| `preventDismissOnScroll` | `closeOnScroll={false}`                  | Inverted logic — v9 default is `closeOnScroll={false}`         |
+| `coverTarget`            | —                                        | No direct equivalent                                           |
+| `doNotLayer`             | `mountNode` prop                         | Pass a DOM node to render outside the default portal container |
+| `styles`                 | `className` on `<PopoverSurface>`        |                                                                |
+| `theme`                  | `FluentProvider`                         |                                                                |
+| `componentRef`           | `ref` on `<PopoverSurface>`              |                                                                |
+| —                        | `trapFocus`                              | New — moves focus in and traps it                              |
+| —                        | `inertTrapFocus`                         | New — softer focus trap via `inert` attribute                  |
diff --git a/skills/fluentui-migrate-v8-to-v9/references/checkbox.md b/skills/fluentui-migrate-v8-to-v9/references/checkbox.md
new file mode 100644
index 0000000000000..b7546acaa0c6c
--- /dev/null
+++ b/skills/fluentui-migrate-v8-to-v9/references/checkbox.md
@@ -0,0 +1,106 @@
+# Checkbox Migration
+
+## Key Changes
+
+- `indeterminate={true}` → `checked="mixed"`
+- `defaultIndeterminate` → `defaultChecked="mixed"`
+- `boxSide` → `labelPosition`
+- `checkmarkIconProps` → `indicator` slot
+- `componentRef` → `ref`
+
+## Before / After Examples
+
+### Basic Migration
+
+```tsx
+// v8
+import { Checkbox } from '@fluentui/react';
+
+<Checkbox checked label="Checked" />
+<Checkbox disabled label="Disabled" />
+<Checkbox indeterminate={true} label="Indeterminate" />
+```
+
+```tsx
+// v9
+import { Checkbox } from '@fluentui/react-components';
+
+<Checkbox checked label="Checked" />
+<Checkbox disabled label="Disabled" />
+<Checkbox checked="mixed" label="Mixed" />
+```
+
+### Controlled Indeterminate
+
+```tsx
+// v8
+const [checked, setChecked] = React.useState(false);
+const [indeterminate, setIndeterminate] = React.useState(true);
+
+<Checkbox
+  indeterminate={indeterminate}
+  checked={checked}
+  onChange={(_, data) => {
+    setIndeterminate(false);
+    setChecked(data.checked);
+  }}
+/>;
+
+// v9
+const [checked, setChecked] = React.useState<boolean | 'mixed'>('mixed');
+
+<Checkbox checked={checked} onChange={(_, data) => setChecked(data.checked)} />;
+```
+
+### Label Position
+
+```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)
+<Checkbox label="Label on left" labelPosition="before" />
+```
+
+### Circular Variant (new in v9)
+
+```tsx
+<Checkbox shape="circular" label="Circular checkbox" />
+```
+
+## CheckboxShim (Interim Bridge)
+
+`CheckboxShim` accepts v8 props and renders a v9 `Checkbox`. Use only for temporary migration — migrate to `Checkbox` directly for new code.
+
+```tsx
+import { CheckboxShim as Checkbox } from '@fluentui/react-migration-v8-v9';
+
+// Keep using v8 props:
+<Checkbox indeterminate={true} label="Still using v8 API" />;
+```
+
+## Prop Mapping
+
+| v8                     | v9                       | CheckboxShim      | Notes                                           |
+| ---------------------- | ------------------------ | ----------------- | ----------------------------------------------- |
+| `componentRef`         | `ref`                    | `componentRef`    |                                                 |
+| `checked`              | `checked`                | `checked`         | Mutually exclusive with `defaultChecked`        |
+| `defaultChecked`       | `defaultChecked`         | `defaultChecked`  | Mutually exclusive with `checked`               |
+| `indeterminate`        | `checked="mixed"`        | `indeterminate`   | v9 merges indeterminate into `checked`          |
+| `defaultIndeterminate` | `defaultChecked="mixed"` | —                 |                                                 |
+| `label`                | `label`                  | `label`           | Slot — accepts string or JSX                    |
+| `boxSide`              | `labelPosition`          | —                 | `'end'` → `'before'` (label before = box after) |
+| `checkmarkIconProps`   | `indicator` slot         | —                 |                                                 |
+| `disabled`             | `disabled`               | `disabled`        |                                                 |
+| `required`             | `required`               | `required`        |                                                 |
+| `onChange`             | `onChange`               | `onChange`        | TypeScript types changed                        |
+| `className`            | `className`              | `className`       |                                                 |
+| `ariaLabel`            | `aria-label`             | `ariaLabel`       |                                                 |
+| `ariaLabelledBy`       | `aria-labelledby`        | `ariaLabelledBy`  |                                                 |
+| `ariaDescribedBy`      | `aria-describedby`       | `ariaDescribedBy` |                                                 |
+| `id`                   | `id`                     | `id`              |                                                 |
+| `name`                 | `name`                   | `name`            |                                                 |
+| `inputProps`           | —                        | —                 | Pass props directly to the `input` slot         |
+| `onRenderLabel`        | —                        | `onRenderLabel`   | Use `label` slot in v9                          |
+| `styles`               | `className`              | `className`       |                                                 |
+| `theme`                | —                        | `theme`           | Use `FluentProvider`                            |
diff --git a/skills/fluentui-migrate-v8-to-v9/references/codemod-catalog.md b/skills/fluentui-migrate-v8-to-v9/references/codemod-catalog.md
deleted file mode 100644
index e224f934e0a9e..0000000000000
--- a/skills/fluentui-migrate-v8-to-v9/references/codemod-catalog.md
+++ /dev/null
@@ -1,363 +0,0 @@
-# Codemod Catalog: FluentUI v8 → v9
-
-This catalog classifies every known v8→v9 migration pattern by how much can be automated.
-
-## Tier Classification
-
-| Tier  | Label      | Definition                                                                                     |
-| ----- | ---------- | ---------------------------------------------------------------------------------------------- |
-| **1** | Mechanical | Safe, idempotent, 1:1 transforms. Full automation with high confidence.                        |
-| **2** | Partial    | Automatable with caveats — value transforms, structural prop moves, require validation.        |
-| **3** | Manual     | Architectural changes requiring human judgment. Flag with TODO comment, do not auto-transform. |
-
----
-
-## Tier 1 — Mechanical (Safe to Automate)
-
-### 1.1 Deprecated Package Imports → Supported Packages
-
-> Codemod name: `deprecated-packages`
-
-| Deprecated import             | Replacement                           | Extra action                                                     |
-| ----------------------------- | ------------------------------------- | ---------------------------------------------------------------- |
-| `@fluentui/react-alert`       | `@fluentui/react-toast`               | Add `// TODO: also consider @fluentui/react-message-bar` comment |
-| `@fluentui/react-infobutton`  | `@fluentui/react-infolabel`           | Rename `InfoButton` → `InfoLabel` in same file                   |
-| `@fluentui/react-virtualizer` | `@fluentui-contrib/react-virtualizer` |                                                                  |
-
-**Source of truth**: `packages/react-components/deprecated/*/README.md`
-
-### 1.2 Hook Import Migration
-
-| v8 import                            | v9 import                                |
-| ------------------------------------ | ---------------------------------------- |
-| `useId` from `@fluentui/react-hooks` | `useId` from `@fluentui/react-utilities` |
-
-### 1.3 Deprecated Props → Supported Replacements
-
-> Codemod name: `deprecated-props`
-
-| Component            | Deprecated prop       | Replacement            | Transform type  |
-| -------------------- | --------------------- | ---------------------- | --------------- |
-| `TableSelectionCell` | `hidden`              | `invisible`            | Rename          |
-| `Popover`            | `legacyTrapFocus`     | `inertTrapFocus`       | Rename          |
-| `Calendar` (compat)  | `overlayedWithButton` | `overlaidWithButton`   | Rename          |
-| `PositioningOptions` | `positionFixed`       | `strategy="fixed"`     | Value transform |
-| `TagPickerList`      | `disableAutoFocus`    | _(remove — no effect)_ | Remove prop     |
-
-**Source of truth**: search `@deprecated` across `packages/react-components/` before implementing.
-
-### 1.4 Aria Prop Renames (All Components)
-
-All components: v8 used camelCase custom props; v9 uses native HTML attributes.
-
-| v8 prop             | v9 prop            |
-| ------------------- | ------------------ |
-| `ariaLabel`         | `aria-label`       |
-| `ariaHidden`        | `aria-hidden`      |
-| `ariaDescribedBy`   | `aria-describedby` |
-| `ariaLabelledBy`    | `aria-labelledby`  |
-| `ariaPositionInSet` | `aria-posinset`    |
-| `ariaSetSize`       | `aria-setsize`     |
-
-### 1.5 Ref Migration (All Components)
-
-| v8             | v9    |
-| -------------- | ----- |
-| `componentRef` | `ref` |
-
-### 1.6 Import Path Consolidation
-
-v8 allowed deep path imports (e.g. `@fluentui/react/lib/Button`). v9 uses the barrel export only.
-
-```ts
-// v8 (both forms valid)
-import { Button } from '@fluentui/react';
-import { Button } from '@fluentui/react/lib/Button';
-
-// v9 (only barrel)
-import { Button } from '@fluentui/react-components';
-```
-
-Codemod: rewrite any `@fluentui/react/lib/*` to the barrel `@fluentui/react-components` (with correct named export per component-mapping).
-
-### 1.7 Direct Component Renames (1:1, No Prop Changes)
-
-| v8 component        | v9 component     | Notes                                    |
-| ------------------- | ---------------- | ---------------------------------------- |
-| `Separator`         | `Divider`        | Same import package                      |
-| `Toggle`            | `Switch`         |                                          |
-| `Shimmer`           | `Skeleton`       |                                          |
-| `ProgressIndicator` | `ProgressBar`    |                                          |
-| `ComboBox`          | `Combobox`       | Case change only                         |
-| `ThemeProvider`     | `FluentProvider` | theme prop also needs migration (Tier 2) |
-| `Fabric`            | `FluentProvider` |                                          |
-| `Panel`             | `Drawer`         |                                          |
-| `Layer`             | `Portal`         |                                          |
-| `DocumentCard`      | `Card`           |                                          |
-| `SearchBox`         | `SearchBox`      | Same name, new package                   |
-| `Breadcrumb`        | `Breadcrumb`     | Same name, new package                   |
-| `Spinner`           | `Spinner`        | Same name, new package                   |
-| `Tooltip`           | `Tooltip`        | Same name, new package                   |
-| `Slider`            | `Slider`         | Same name, new package                   |
-| `MessageBar`        | `MessageBar`     | Same name, new package                   |
-| `Nav`               | `Nav`            | Same name, new package                   |
-
----
-
-## Tier 2 — Partially Automatable (Validate Output)
-
-### 2.1 Button Variant → appearance Prop
-
-| v8 component       | v9 equivalent                     | Transform          |
-| ------------------ | --------------------------------- | ------------------ |
-| `DefaultButton`    | `Button`                          | Rename             |
-| `PrimaryButton`    | `Button appearance="primary"`     | Rename + add prop  |
-| `ActionButton`     | `Button appearance="transparent"` | Rename + add prop  |
-| `CommandButton`    | `Button`                          | Rename             |
-| `CommandBarButton` | `Button`                          | Rename             |
-| `ToggleButton`     | `ToggleButton`                    | Import change only |
-| `CompoundButton`   | `CompoundButton`                  | Import change only |
-
-**Caveat**: `IconButton` requires removing text children — flag if children exist.
-
-### 2.2 Button `text` Prop → `children`
-
-```tsx
-// v8
-<PrimaryButton text="Submit" />
-// v9
-<Button appearance="primary">Submit</Button>
-```
-
-Automatable when `text` is a static string literal. Flag if `text` is a variable or expression — generate TODO comment.
-
-### 2.3 Button `primary` Prop → `appearance`
-
-```tsx
-// v8: <Button primary />
-// v9: <Button appearance="primary" />
-```
-
-Straightforward prop value transform.
-
-### 2.4 Checkbox `indeterminate` → `checked="mixed"`
-
-```tsx
-// v8: <Checkbox indeterminate={true} />
-// v9: <Checkbox checked="mixed" />
-```
-
-Safe when `indeterminate` is statically `true`. Flag dynamic values.
-
-### 2.5 TextField `multiline` → `Textarea`
-
-```tsx
-// v8: <TextField multiline rows={3} />
-// v9: <Textarea rows={3} />
-```
-
-Automatable when `multiline` is statically `true`. When dynamic (e.g. `multiline={isMultiline}`), generate TODO comment and leave unchanged.
-
-### 2.6 Pivot/TabList Prop Renames
-
-| v8 `Pivot` prop      | v9 `TabList` prop      |
-| -------------------- | ---------------------- |
-| `defaultSelectedKey` | `defaultSelectedValue` |
-| `selectedKey`        | `selectedValue`        |
-| `onLinkClick`        | `onTabSelect`          |
-| `linkSize`           | `size`                 |
-
-| v8 `PivotItem` prop | v9 `Tab` prop                   |
-| ------------------- | ------------------------------- |
-| `itemKey`           | `value`                         |
-| `headerText`        | children (move to JSX children) |
-| `itemIcon`          | `icon` slot                     |
-
-**Caveat**: `headerText` → children requires moving prop to JSX children — automatable for static string values.
-
-### 2.7 Input Prop Renames
-
-| v8 `TextField` prop | v9 `Input` prop               |
-| ------------------- | ----------------------------- |
-| `prefix`            | `contentBefore`               |
-| `suffix`            | `contentAfter`                |
-| `inputClassName`    | `input` slot                  |
-| `underlined`        | `appearance="underline"`      |
-| `borderless`        | `appearance="filled-lighter"` |
-| `elementRef`        | `ref`                         |
-
-### 2.8 RadioGroup Prop Renames
-
-| v8 `ChoiceGroup`     | v9 `RadioGroup`   |
-| -------------------- | ----------------- |
-| `defaultSelectedKey` | `defaultValue`    |
-| `selectedKey`        | `value`           |
-| `ariaLabelledBy`     | `aria-labelledby` |
-
-### 2.9 `styles` Prop → TODO Comment
-
-The `styles` prop is removed in v9. Codemod should:
-
-1. Remove the `styles` prop
-2. Insert `{/* TODO: migrate styles to makeStyles — see https://aka.ms/fluentui-v9-styles */}` comment above the JSX element
-
-**Do not attempt to auto-convert style objects** — they require manual `makeStyles` authoring.
-
-### 2.10 `mergeStyles` / `mergeStyleSets` → TODO Comment
-
-Flag any imports of `mergeStyles`, `mergeStyleSets`, `IStyle` from `@fluentui/react`:
-
-- Add `// TODO: replace mergeStyles with makeStyles from @fluentui/react-components` comment
-- Do not remove the code — leave it for manual migration
-
-### 2.11 Icon Migration (Requires Name Mapping Table)
-
-```tsx
-// v8
-<Button iconProps={{ iconName: 'Add' }} />;
-
-// v9
-import { AddRegular } from '@fluentui/react-icons';
-<Button icon={<AddRegular />} />;
-```
-
-Automatable **only if** an icon name → React component mapping table exists. Without the table, flag all `iconProps` usages with:
-
-```ts
-// TODO: replace iconProps={{ iconName: 'Add' }} with icon slot using @fluentui/react-icons
-```
-
----
-
-## Tier 3 — Manual Only (Flag and Comment)
-
-These patterns require architectural changes. A codemod should **detect and annotate** but not transform.
-
-### 3.1 ContextualMenu / menuProps → Menu JSX Children
-
-**Why manual**: Items array must be converted to JSX component hierarchy with correct component types per item type.
-
-```tsx
-// v8 — data-driven
-<ContextualMenu items={[
-  { key: 'a', text: 'Action A', onClick: handleA },
-  { key: 'div1', itemType: ContextualMenuItemType.Divider },
-  { key: 'sub', text: 'Submenu', subMenuProps: { items: [...] } },
-]} />
-
-// v9 — declarative
-<Menu>
-  <MenuTrigger>...</MenuTrigger>
-  <MenuPopover>
-    <MenuList>
-      <MenuItem onClick={handleA}>Action A</MenuItem>
-      <MenuDivider />
-      <Menu>
-        <MenuTrigger><MenuItem hasSubmenu>Submenu</MenuItem></MenuTrigger>
-        <MenuPopover><MenuList>...</MenuList></MenuPopover>
-      </Menu>
-    </MenuList>
-  </MenuPopover>
-</Menu>
-```
-
-**Codemod action**: detect `ContextualMenu` usages, insert `// TODO: migrate ContextualMenu to Menu with JSX children` comment.
-
-### 3.2 Stack / StackItem → makeStyles + Flexbox
-
-**Why manual**: Stack's layout props map to CSS flexbox properties that require per-component `makeStyles` definitions.
-
-**Codemod action**: detect `Stack` imports and usages, insert comment. Optionally offer `StackShim` as a temporary bridge.
-
-```ts
-// TODO: Replace Stack with makeStyles flexbox — see fluentui-v8-to-v9 skill stack.md
-```
-
-### 3.3 Label Extraction from Component Props
-
-**Why manual**: Components like `TextField`, `ChoiceGroup`, `CheckBox` had a `label` prop that v9 splits into a separate `<Label>` element requiring a `useId`-linked `htmlFor`/`aria-labelledby`.
-
-```tsx
-// v8
-<TextField label="Email" />
-
-// v9 — requires new Label element and ID coordination
-const emailId = useId('email');
-<Label htmlFor={emailId}>Email</Label>
-<Input id={emailId} />
-```
-
-**Codemod action**: flag `label` props on `TextField`, `ChoiceGroup`, `SpinButton`, `Slider` with TODO comment.
-
-### 3.4 ChoiceGroup options Array → RadioGroup + Radio Children
-
-**Why manual**: `options` array maps to `Radio` components — data-driven patterns need to become JSX.
-
-**Codemod action**: detect `ChoiceGroup options={...}` and insert TODO comment.
-
-### 3.5 Facepile personas Array → AvatarGroup Children
-
-**Why manual**: `personas` array + overflow logic needs to be refactored to `AvatarGroup` + `AvatarGroupItem` + `AvatarGroupPopover` using `partitionAvatarGroupItems`.
-
-**Codemod action**: detect `Facepile` usages, insert TODO comment.
-
-### 3.6 Custom Theme Migration
-
-**Why manual**: v8 `IPalette` → v9 `BrandVariants` requires expanding 9 theme colors to 16 + mapping semantic tokens.
-
-**Codemod action**: detect `ThemeProvider theme={customVar}` where theme is not a Fluent built-in, insert TODO comment with reference to theme shim utilities.
-
-### 3.7 onRender\* Callbacks → Slot Pattern
-
-**Why manual**: Each `onRender*` prop maps to a specific v9 slot, and the slot API (accepts JSX, shorthand, or render function) requires case-by-case analysis.
-
-**Codemod action**: detect any `onRender` prop names and insert TODO comment per occurrence.
-
-### 3.8 DetailsList → DataGrid
-
-**Why manual**: Completely different API — columns, rows, selection, sorting all change significantly.
-
-**Codemod action**: detect `DetailsList` imports and flag with TODO comment.
-
-### 3.9 Pivot Content → State-Managed Tab Content
-
-**Why manual**: `PivotItem` children (tab content) must be extracted out of the `TabList` hierarchy and rendered conditionally based on selected tab state.
-
-**Codemod action**: after renaming `Pivot` → `TabList`, detect `Tab` components with children that aren't the tab label and insert TODO comment.
-
----
-
-## Summary: What to Build as Codemods
-
-### MVP Codemods (per spec)
-
-| Codemod               | Tier | Status           |
-| --------------------- | ---- | ---------------- |
-| `deprecated-packages` | 1    | Required for MVP |
-| `deprecated-props`    | 1    | Required for MVP |
-
-### Recommended Next Codemods (High ROI)
-
-| Codemod               | Tier | Description                                            |
-| --------------------- | ---- | ------------------------------------------------------ |
-| `import-paths`        | 1    | Rewrite `@fluentui/react/lib/*` deep imports to barrel |
-| `aria-props`          | 1    | `ariaLabel` → `aria-label` etc. across all components  |
-| `component-ref`       | 1    | `componentRef` → `ref` across all components           |
-| `component-renames`   | 1    | 1:1 renames (Separator→Divider, Toggle→Switch, etc.)   |
-| `button-variants`     | 2    | PrimaryButton → `Button appearance="primary"`, etc.    |
-| `button-text-prop`    | 2    | `text` prop → children (static strings only)           |
-| `textfield-multiline` | 2    | `TextField multiline` → `Textarea` (static only)       |
-| `pivot-props`         | 2    | Pivot/PivotItem prop renames                           |
-| `styles-flag`         | 2    | Remove `styles` prop + insert TODO comment             |
-| `todo-annotations`    | 3    | Detect Tier 3 patterns, insert TODO comments + skip    |
-
-### Detection-Only Codemods (for `report` command)
-
-These should be detected by `UsageCollector` and surfaced in `fluent-report.json` usage inventory:
-
-- All `ContextualMenu` / `menuProps` usages → manual migration count
-- All `Stack` / `StackItem` usages → manual migration count
-- All `label` prop usages on text inputs → manual migration count
-- All `onRender*` prop usages → manual migration count
-- All `styles` prop usages → partially-automatable count
-- All `iconProps` usages → flag for icon name mapping
diff --git a/skills/fluentui-migrate-v8-to-v9/references/datagrid.md b/skills/fluentui-migrate-v8-to-v9/references/datagrid.md
new file mode 100644
index 0000000000000..a4ff5fc3a0ea3
--- /dev/null
+++ b/skills/fluentui-migrate-v8-to-v9/references/datagrid.md
@@ -0,0 +1,236 @@
+# DetailsList / DataGrid Migration
+
+## Architecture Change
+
+v8 `DetailsList` and v9 `DataGrid` share the same `items` + `columns` concept, but the column definitions
+and rendering are completely restructured.
+
+Key shifts:
+
+- Columns are defined with `createTableColumn()` factory, which takes typed render functions instead of string `fieldName` + `onRenderColumn` callbacks
+- The grid body uses a **render-props pattern** — `DataGridBody` / `DataGridRow` children are functions, not arrays
+- Selection uses a `Set` of item keys, not a `Selection` class
+- Sorting is declarative (`sortable` prop + `sortState`) instead of per-column `isSorted` flags
+- `getRowId` prop specifies which field to use as the row key
+
+## Before / After Example
+
+```tsx
+// v8 — DetailsList
+import { DetailsList, IColumn, SelectionMode, Selection } from '@fluentui/react';
+
+interface Item {
+  id: string;
+  name: string;
+  age: number;
+}
+
+const columns: IColumn[] = [
+  {
+    key: 'name',
+    name: 'Name',
+    fieldName: 'name',
+    minWidth: 100,
+    maxWidth: 200,
+    isSortable: true,
+    onRender: (item: Item) => <strong>{item.name}</strong>,
+  },
+  {
+    key: 'age',
+    name: 'Age',
+    fieldName: 'age',
+    minWidth: 50,
+    maxWidth: 100,
+  },
+];
+
+const selection = new Selection();
+
+<DetailsList
+  items={items}
+  columns={columns}
+  selectionMode={SelectionMode.single}
+  selection={selection}
+  onItemInvoked={handleItemInvoked}
+/>;
+```
+
+```tsx
+// v9 — DataGrid
+import {
+  DataGrid,
+  DataGridHeader,
+  DataGridRow,
+  DataGridHeaderCell,
+  DataGridBody,
+  DataGridCell,
+  TableColumnDefinition,
+  TableCellLayout,
+  createTableColumn,
+} from '@fluentui/react-components';
+
+interface Item {
+  id: string;
+  name: string;
+  age: number;
+}
+
+const columns: TableColumnDefinition<Item>[] = [
+  createTableColumn<Item>({
+    columnId: 'name',
+    compare: (a, b) => a.name.localeCompare(b.name),
+    renderHeaderCell: () => 'Name',
+    renderCell: item => (
+      <TableCellLayout>
+        <strong>{item.name}</strong>
+      </TableCellLayout>
+    ),
+  }),
+  createTableColumn<Item>({
+    columnId: 'age',
+    compare: (a, b) => a.age - b.age,
+    renderHeaderCell: () => 'Age',
+    renderCell: item => <TableCellLayout>{item.age}</TableCellLayout>,
+  }),
+];
+
+<DataGrid
+  items={items}
+  columns={columns}
+  getRowId={item => item.id}
+  selectionMode="single"
+  onSelectionChange={(_, data) => console.log([...data.selectedItems])}
+  sortable
+>
+  <DataGridHeader>
+    <DataGridRow>{({ renderHeaderCell }) => <DataGridHeaderCell>{renderHeaderCell()}</DataGridHeaderCell>}</DataGridRow>
+  </DataGridHeader>
+  <DataGridBody<Item>>
+    {({ item, rowId }) => (
+      <DataGridRow<Item> key={rowId} onClick={() => handleItemInvoked(item)}>
+        {({ renderCell }) => <DataGridCell>{renderCell(item)}</DataGridCell>}
+      </DataGridRow>
+    )}
+  </DataGridBody>
+</DataGrid>;
+```
+
+## Sorting
+
+```tsx
+// v9 — controlled sort state
+const [sortState, setSortState] = React.useState<{ sortColumn?: string; sortDirection?: 'ascending' | 'descending' }>(
+  {},
+);
+
+<DataGrid
+  items={items}
+  columns={columns}
+  sortable
+  sortState={sortState}
+  onSortChange={(_, nextSort) => setSortState(nextSort)}
+>
+  ...
+</DataGrid>;
+```
+
+With sort, `compare` on each `createTableColumn` handles the ordering. `DataGridHeaderCell` renders a sort indicator automatically when `sortable` is set.
+
+## Multi-select
+
+```tsx
+// v9 — controlled multi-select with a Set of row IDs
+const [selectedRows, setSelectedRows] = React.useState(new Set<string>());
+
+<DataGrid
+  items={items}
+  columns={columns}
+  getRowId={item => item.id}
+  selectionMode="multiselect"
+  selectedItems={selectedRows}
+  onSelectionChange={(_, data) => setSelectedRows(new Set(data.selectedItems as string[]))}
+>
+  ...
+</DataGrid>;
+```
+
+## Column Resizing
+
+```tsx
+// v9 — column resizing (no v8 equivalent built-in)
+import { DataGridProps } from '@fluentui/react-components';
+
+const columnSizingOptions: DataGridProps['columnSizingOptions'] = {
+  name: { minWidth: 100, defaultWidth: 200 },
+  age: { minWidth: 50, defaultWidth: 100 },
+};
+
+<DataGrid items={items} columns={columns} resizableColumns columnSizingOptions={columnSizingOptions}>
+  ...
+</DataGrid>;
+```
+
+## IColumn → TableColumnDefinition
+
+| v8 `IColumn`           | v9 `createTableColumn` option      | Notes                                       |
+| ---------------------- | ---------------------------------- | ------------------------------------------- |
+| `key`                  | `columnId`                         |                                             |
+| `name`                 | `renderHeaderCell`                 | Return a string or JSX                      |
+| `fieldName`            | `renderCell`                       | Access `item.fieldName` inside `renderCell` |
+| `onRender`             | `renderCell`                       |                                             |
+| `onRenderHeader`       | `renderHeaderCell`                 |                                             |
+| `isSortable` + sort cb | `compare` + `sortable` prop        | `compare` is a typed comparator             |
+| `isSorted`             | `sortState.sortColumn`             | Set via `sortState` prop on `DataGrid`      |
+| `isSortedDescending`   | `sortState.sortDirection`          |                                             |
+| `minWidth`             | `columnSizingOptions[id].minWidth` |                                             |
+| `maxWidth`             | `columnSizingOptions[id].maxWidth` |                                             |
+| `isResizable`          | `resizableColumns` on `DataGrid`   |                                             |
+
+## IDetailsListProps → DataGridProps
+
+| v8                    | v9                                    | Notes                                     |
+| --------------------- | ------------------------------------- | ----------------------------------------- |
+| `items`               | `items`                               |                                           |
+| `columns`             | `columns`                             | Different shape — use `createTableColumn` |
+| `selectionMode`       | `selectionMode`                       | `"single"` \| `"multiselect"` (string)    |
+| `selection`           | `selectedItems` + `onSelectionChange` | `Set` of row IDs, not `Selection` class   |
+| `getKey`              | `getRowId`                            |                                           |
+| `onItemInvoked`       | `onClick` on `<DataGridRow>`          |                                           |
+| `onActiveItemChanged` | `onClick` on `<DataGridRow>`          |                                           |
+| `onRenderRow`         | Children function of `<DataGridBody>` |                                           |
+| `onRenderItemColumn`  | `renderCell` in `createTableColumn`   |                                           |
+| `checkboxVisibility`  | `selectionAppearance`                 | `"checkbox"` \| `"brand"` \| `"none"`     |
+| `groups`              | —                                     | Use `Tree` for grouped/hierarchical data  |
+| `compact`             | `size="small"`                        |                                           |
+| `styles`              | `className` + `makeStyles`            |                                           |
+| `theme`               | `FluentProvider`                      |                                           |
+
+## Selection class → Set
+
+```tsx
+// v8 — Selection class
+import { Selection } from '@fluentui/react';
+
+const selection = new Selection({
+  onSelectionChanged: () => {
+    const selected = selection.getSelection() as Item[];
+    console.log(selected);
+  },
+});
+
+<DetailsList selection={selection} selectionMode={SelectionMode.multiple} />;
+```
+
+```tsx
+// v9 — Set of row IDs
+const [selectedItems, setSelectedItems] = React.useState(new Set<string>());
+
+<DataGrid
+  selectionMode="multiselect"
+  selectedItems={selectedItems}
+  onSelectionChange={(_, data) => setSelectedItems(new Set(data.selectedItems as string[]))}
+  getRowId={item => item.id}
+>
+  ...
+</DataGrid>;
+```
diff --git a/skills/fluentui-migrate-v8-to-v9/references/dialog.md b/skills/fluentui-migrate-v8-to-v9/references/dialog.md
new file mode 100644
index 0000000000000..ba463c5926bed
--- /dev/null
+++ b/skills/fluentui-migrate-v8-to-v9/references/dialog.md
@@ -0,0 +1,211 @@
+# Dialog / Modal Migration
+
+## Architecture Change
+
+In v8, `Dialog` is controlled via `hidden` prop (inverted logic) and composed via a `dialogContentProps` object.
+`Modal` is a separate component with `isOpen`.
+
+In v9, both map to a single `Dialog` that uses declarative JSX children and `open` / `onOpenChange`.
+The structure is: `Dialog` → `DialogSurface` → `DialogBody` → `DialogTitle` + `DialogContent` + `DialogActions`.
+
+**Critical:** v8 `hidden={false}` means visible — v9 `open={true}` means visible. The logic is inverted.
+
+## Before / After Example — Dialog
+
+```tsx
+// v8
+import { Dialog, DialogFooter, DialogType, PrimaryButton, DefaultButton } from '@fluentui/react';
+
+<Dialog
+  hidden={!isOpen}
+  onDismiss={handleClose}
+  dialogContentProps={{
+    type: DialogType.normal,
+    title: 'Delete item',
+    subText: 'Are you sure you want to delete this item?',
+  }}
+  modalProps={{ isBlocking: true }}
+>
+  <DialogFooter>
+    <PrimaryButton onClick={handleConfirm} text="Delete" />
+    <DefaultButton onClick={handleClose} text="Cancel" />
+  </DialogFooter>
+</Dialog>;
+```
+
+```tsx
+// v9
+import {
+  Dialog,
+  DialogSurface,
+  DialogBody,
+  DialogTitle,
+  DialogContent,
+  DialogActions,
+  Button,
+} from '@fluentui/react-components';
+
+<Dialog
+  open={isOpen}
+  onOpenChange={(_, data) => setIsOpen(data.open)}
+  // modalType="modal" is the default — blocks backdrop dismiss
+>
+  <DialogSurface>
+    <DialogBody>
+      <DialogTitle>Delete item</DialogTitle>
+      <DialogContent>Are you sure you want to delete this item?</DialogContent>
+      <DialogActions>
+        <Button appearance="primary" onClick={handleConfirm}>
+          Delete
+        </Button>
+        <Button onClick={handleClose}>Cancel</Button>
+      </DialogActions>
+    </DialogBody>
+  </DialogSurface>
+</Dialog>;
+```
+
+## With a trigger button (uncontrolled)
+
+```tsx
+// v9 — uncontrolled via DialogTrigger (no isOpen state needed)
+import {
+  Dialog,
+  DialogTrigger,
+  DialogSurface,
+  DialogBody,
+  DialogTitle,
+  DialogContent,
+  DialogActions,
+  Button,
+} from '@fluentui/react-components';
+
+<Dialog>
+  <DialogTrigger disableButtonEnhancement>
+    <Button>Open dialog</Button>
+  </DialogTrigger>
+  <DialogSurface>
+    <DialogBody>
+      <DialogTitle>Confirm</DialogTitle>
+      <DialogContent>Are you sure?</DialogContent>
+      <DialogActions>
+        <DialogTrigger disableButtonEnhancement>
+          <Button appearance="primary">Yes</Button>
+        </DialogTrigger>
+        <DialogTrigger disableButtonEnhancement>
+          <Button>Cancel</Button>
+        </DialogTrigger>
+      </DialogActions>
+    </DialogBody>
+  </DialogSurface>
+</Dialog>;
+```
+
+## Before / After Example — Modal → Dialog
+
+```tsx
+// v8 Modal
+import { Modal } from '@fluentui/react';
+
+<Modal isOpen={isOpen} onDismiss={handleClose} isBlocking={false}>
+  <div>
+    <h2>Modal heading</h2>
+    <p>Modal body content</p>
+    <button onClick={handleClose}>Close</button>
+  </div>
+</Modal>;
+```
+
+```tsx
+// v9 — Dialog with modalType="non-modal" (light dismiss, no blocking overlay)
+import {
+  Dialog,
+  DialogSurface,
+  DialogBody,
+  DialogTitle,
+  DialogContent,
+  DialogActions,
+  Button,
+} from '@fluentui/react-components';
+
+<Dialog open={isOpen} onOpenChange={(_, data) => setIsOpen(data.open)} modalType="non-modal">
+  <DialogSurface>
+    <DialogBody>
+      <DialogTitle>Modal heading</DialogTitle>
+      <DialogContent>Modal body content</DialogContent>
+      <DialogActions>
+        <Button onClick={handleClose}>Close</Button>
+      </DialogActions>
+    </DialogBody>
+  </DialogSurface>
+</Dialog>;
+```
+
+## modalType Values
+
+| v9 `modalType` | Behavior                                                                 | v8 equivalent                        |
+| -------------- | ------------------------------------------------------------------------ | ------------------------------------ |
+| `"modal"`      | Default. Has backdrop overlay; Escape or click outside dismisses.        | `isBlocking={false}` (v8 default)    |
+| `"non-modal"`  | No backdrop; content behind is interactive; Escape still dismisses.      | `isBlocking={false}` without overlay |
+| `"alert"`      | Blocks everything including Escape; user must choose an explicit action. | `isBlocking={true}` + focus trap     |
+
+## IDialogProps → DialogProps
+
+| v8                              | v9                                          | Notes                                        |
+| ------------------------------- | ------------------------------------------- | -------------------------------------------- |
+| `hidden`                        | `open` (inverted)                           | `hidden={false}` = `open={true}`             |
+| `onDismiss`                     | `onOpenChange`                              | `(ev, data) => data.open === false` on close |
+| `dialogContentProps.title`      | `<DialogTitle>`                             | JSX child                                    |
+| `dialogContentProps.subText`    | `<DialogContent>`                           | JSX child                                    |
+| `dialogContentProps.type`       | `modalType` on `<Dialog>`                   | See table above                              |
+| `dialogContentProps.titleProps` | Props on `<DialogTitle>`                    |                                              |
+| `dialogContentProps.styles`     | `className` + `makeStyles`                  |                                              |
+| `modalProps.isBlocking`         | `modalType="alert"`                         |                                              |
+| `modalProps.layerProps`         | —                                           | Not supported                                |
+| `minWidth` / `maxWidth`         | `style` or `className` on `<DialogSurface>` |                                              |
+| `styles`                        | `className` + `makeStyles`                  |                                              |
+| `theme`                         | `FluentProvider`                            |                                              |
+
+## IModalProps → DialogProps
+
+| v8                           | v9                               | Notes                              |
+| ---------------------------- | -------------------------------- | ---------------------------------- |
+| `isOpen`                     | `open`                           |                                    |
+| `onDismiss`                  | `onOpenChange`                   |                                    |
+| `isBlocking`                 | `modalType="alert"`              | Prevents Escape + backdrop dismiss |
+| `isDarkOverlay`              | CSS on `DialogSurface` backdrop  |                                    |
+| `scrollableContentClassName` | `className` on `<DialogSurface>` |                                    |
+| `containerClassName`         | `className` on `<DialogSurface>` |                                    |
+| `layerProps`                 | —                                | Not supported                      |
+| `styles`                     | `className` + `makeStyles`       |                                    |
+| `theme`                      | `FluentProvider`                 |                                    |
+
+## v8 DialogFooter → DialogActions
+
+```tsx
+// v8
+import { DialogFooter } from '@fluentui/react';
+<DialogFooter>
+  <PrimaryButton text="OK" />
+  <DefaultButton text="Cancel" />
+</DialogFooter>;
+
+// v9
+import { DialogActions } from '@fluentui/react-components';
+<DialogActions>
+  <Button appearance="primary">OK</Button>
+  <Button>Cancel</Button>
+</DialogActions>;
+```
+
+## Custom close button in title
+
+```tsx
+// v9 — add a close button to the title area via the action slot
+import { DialogTitle, Button } from '@fluentui/react-components';
+import { DismissRegular } from '@fluentui/react-icons';
+
+<DialogTitle action={<Button appearance="subtle" icon={<DismissRegular />} onClick={handleClose} aria-label="Close" />}>
+  Dialog title
+</DialogTitle>;
+```
diff --git a/skills/fluentui-migrate-v8-to-v9/references/drawer.md b/skills/fluentui-migrate-v8-to-v9/references/drawer.md
new file mode 100644
index 0000000000000..7a2d9ee1002e4
--- /dev/null
+++ b/skills/fluentui-migrate-v8-to-v9/references/drawer.md
@@ -0,0 +1,157 @@
+# Panel / Drawer Migration
+
+## Architecture Change
+
+v8 `Panel` is controlled via `isOpen` and configured through flat props (`headerText`, `type`, `onRenderFooterContent`).
+
+v9 `Drawer` is composable: content is structured via `DrawerHeader`, `DrawerBody`, and `DrawerFooter` children.
+The v9 package exports two variants:
+
+- **`OverlayDrawer`** — floats over content with a backdrop (equivalent to v8 Panel)
+- **`InlineDrawer`** — embedded in the layout and pushes content (no v8 equivalent)
+
+## Before / After Example
+
+```tsx
+// v8 — Panel
+import { Panel, PanelType, PrimaryButton, DefaultButton } from '@fluentui/react';
+
+<Panel
+  isOpen={isOpen}
+  onDismiss={handleClose}
+  type={PanelType.medium}
+  headerText="Settings"
+  isBlocking={false}
+  hasCloseButton
+  onRenderFooterContent={() => (
+    <>
+      <PrimaryButton onClick={handleSave} styles={{ root: { marginRight: 8 } }}>
+        Save
+      </PrimaryButton>
+      <DefaultButton onClick={handleClose}>Cancel</DefaultButton>
+    </>
+  )}
+>
+  <p>Panel body content</p>
+</Panel>;
+```
+
+```tsx
+// v9 — OverlayDrawer
+import {
+  OverlayDrawer,
+  DrawerHeader,
+  DrawerHeaderTitle,
+  DrawerBody,
+  DrawerFooter,
+  Button,
+} from '@fluentui/react-components';
+import { DismissRegular } from '@fluentui/react-icons';
+
+<OverlayDrawer
+  open={isOpen}
+  onOpenChange={(_, data) => setIsOpen(data.open)}
+  position="end"
+  size="medium"
+  modalType="non-modal" // isBlocking={false} equivalent
+>
+  <DrawerHeader>
+    <DrawerHeaderTitle
+      action={<Button appearance="subtle" icon={<DismissRegular />} onClick={handleClose} aria-label="Close" />}
+    >
+      Settings
+    </DrawerHeaderTitle>
+  </DrawerHeader>
+
+  <DrawerBody>
+    <p>Panel body content</p>
+  </DrawerBody>
+
+  <DrawerFooter>
+    <Button appearance="primary" onClick={handleSave}>
+      Save
+    </Button>
+    <Button onClick={handleClose}>Cancel</Button>
+  </DrawerFooter>
+</OverlayDrawer>;
+```
+
+## PanelType → position + size
+
+| v8 `PanelType`   | v9 `position` | v9 `size`  | Notes                                         |
+| ---------------- | ------------- | ---------- | --------------------------------------------- |
+| `SmallFixedFar`  | `"end"`       | `"small"`  |                                               |
+| `SmallFixedNear` | `"start"`     | `"small"`  |                                               |
+| `SmallFluid`     | `"end"`       | `"small"`  | Full height; custom width via CSS             |
+| `Medium`         | `"end"`       | `"medium"` | Default                                       |
+| `Large`          | `"end"`       | `"large"`  |                                               |
+| `LargeFixed`     | `"end"`       | `"large"`  |                                               |
+| `ExtraLarge`     | `"end"`       | `"full"`   |                                               |
+| `Custom`         | `"end"`       | custom CSS | `style={{ width: '...' }}` on `DrawerSurface` |
+| `CustomNear`     | `"start"`     | custom CSS |                                               |
+
+## modalType Values
+
+| v9 `modalType` | v8 equivalent                        | Behavior                                    |
+| -------------- | ------------------------------------ | ------------------------------------------- |
+| `"modal"`      | `isBlocking={false}` (v8 default)    | Backdrop present; Escape + click-away close |
+| `"non-modal"`  | `isBlocking={false}` + light dismiss | No backdrop; content behind is interactive  |
+| `"alert"`      | `isBlocking={true}`                  | No dismiss on Escape or click-away          |
+
+> Note: v8 Panel default `isBlocking={false}` (click-away dismisses) is equivalent to v9 `modalType="modal"` (backdrop present, click-away dismisses). The defaults match — no explicit `modalType` is needed when migrating a Panel that used its defaults. Only set `modalType="alert"` if the Panel used `isBlocking={true}`.
+
+## IPanelProps → OverlayDrawerProps
+
+| v8                      | v9                                            | Notes                                        |
+| ----------------------- | --------------------------------------------- | -------------------------------------------- |
+| `isOpen`                | `open`                                        |                                              |
+| `onDismiss`             | `onOpenChange`                                | `(ev, data) => data.open === false` on close |
+| `type`                  | `position` + `size`                           | See table above                              |
+| `headerText`            | `<DrawerHeaderTitle>` children                |                                              |
+| `onRenderHeader`        | `<DrawerHeader>` children                     |                                              |
+| `hasCloseButton`        | Button in `DrawerHeaderTitle` `action` slot   | See example above                            |
+| `isBlocking`            | `modalType`                                   |                                              |
+| `isLightDismiss`        | `modalType="non-modal"`                       |                                              |
+| `onRenderFooterContent` | `<DrawerFooter>` children                     |                                              |
+| `onRenderBody`          | `<DrawerBody>` children                       |                                              |
+| `onRenderNavigation`    | `<DrawerHeaderNavigation>` children           |                                              |
+| `customWidth`           | `style={{ width: '...' }}` on `DrawerSurface` |                                              |
+| `styles`                | `className` + `makeStyles`                    |                                              |
+| `theme`                 | `FluentProvider`                              |                                              |
+| `layerProps`            | —                                             | Not supported                                |
+| `componentRef`          | `ref`                                         |                                              |
+
+## InlineDrawer (no v8 equivalent)
+
+Use when the drawer should push page content rather than overlay it:
+
+```tsx
+import { InlineDrawer, DrawerHeader, DrawerHeaderTitle, DrawerBody } from '@fluentui/react-components';
+import { makeStyles } from '@fluentui/react-components';
+
+const useStyles = makeStyles({
+  root: { display: 'flex', height: '480px' },
+  content: { flex: 1, padding: '16px' },
+});
+
+function App() {
+  const s = useStyles();
+  const [open, setOpen] = React.useState(false);
+  return (
+    <div className={s.root}>
+      <InlineDrawer open={open} position="start" separator>
+        <DrawerHeader>
+          <DrawerHeaderTitle>Navigation</DrawerHeaderTitle>
+        </DrawerHeader>
+        <DrawerBody>
+          <p>Side nav content</p>
+        </DrawerBody>
+      </InlineDrawer>
+      <div className={s.content}>
+        <Button onClick={() => setOpen(o => !o)}>Toggle</Button>
+        <p>Main content</p>
+      </div>
+    </div>
+  );
+}
+```
diff --git a/skills/fluentui-migrate-v8-to-v9/references/dropdown.md b/skills/fluentui-migrate-v8-to-v9/references/dropdown.md
new file mode 100644
index 0000000000000..7afd16fa5c489
--- /dev/null
+++ b/skills/fluentui-migrate-v8-to-v9/references/dropdown.md
@@ -0,0 +1,246 @@
+# Dropdown / Combobox Migration
+
+## Architecture Change
+
+In v8, both components are **data-driven**: pass an `options` array of `IDropdownOption` / `IComboBoxOption` objects.
+
+In v9, both are **declarative**: compose `<Option>` (and `<OptionGroup>`) as JSX children. This is the same pattern shift as `ContextualMenu` → `Menu`.
+
+The `onChange` callback is also renamed to `onOptionSelect` with a different signature.
+
+## Dropdown
+
+### Before / After — basic
+
+```tsx
+// v8
+import { Dropdown, IDropdownOption } from '@fluentui/react';
+
+const options: IDropdownOption[] = [
+  { key: 'apple', text: 'Apple' },
+  { key: 'banana', text: 'Banana' },
+  { key: 'cherry', text: 'Cherry', disabled: true },
+];
+
+<Dropdown
+  label="Fruit"
+  placeholder="Select an option"
+  options={options}
+  selectedKey={selectedKey}
+  onChange={(_, option) => setSelectedKey(option?.key as string)}
+/>;
+```
+
+```tsx
+// v9
+import { Dropdown, Option, Field } from '@fluentui/react-components';
+
+// Track both the display value (text) and the key (value)
+const [selectedKey, setSelectedKey] = React.useState('');
+const [selectedValue, setSelectedValue] = React.useState('');
+
+<Field label="Fruit">
+  <Dropdown
+    placeholder="Select an option"
+    value={selectedValue}
+    selectedOptions={[selectedKey]}
+    onOptionSelect={(_, data) => {
+      setSelectedKey(data.optionValue ?? '');
+      setSelectedValue(data.optionText ?? '');
+    }}
+  >
+    <Option value="apple">Apple</Option>
+    <Option value="banana">Banana</Option>
+    <Option disabled value="cherry">
+      Cherry
+    </Option>
+  </Dropdown>
+</Field>;
+```
+
+### Before / After — multi-select
+
+```tsx
+// v8
+<Dropdown
+  multiSelect
+  options={options}
+  selectedKeys={selectedKeys}
+  onChange={(_, option) => {
+    if (option?.selected) {
+      setSelectedKeys(prev => [...prev, option.key as string]);
+    } else {
+      setSelectedKeys(prev => prev.filter(k => k !== option?.key));
+    }
+  }}
+/>
+```
+
+```tsx
+// v9
+<Dropdown
+  multiselect
+  selectedOptions={selectedKeys}
+  value={selectedKeys.join(', ')}
+  onOptionSelect={(_, data) => setSelectedKeys(data.selectedOptions)}
+>
+  <Option value="apple">Apple</Option>
+  <Option value="banana">Banana</Option>
+  <Option value="cherry">Cherry</Option>
+</Dropdown>
+```
+
+### Before / After — grouped options
+
+```tsx
+// v8
+import { DropdownMenuItemType } from '@fluentui/react';
+
+const options: IDropdownOption[] = [
+  { key: 'fruitsHeader', text: 'Fruits', itemType: DropdownMenuItemType.Header },
+  { key: 'apple', text: 'Apple' },
+  { key: 'banana', text: 'Banana' },
+  { key: 'divider', text: '-', itemType: DropdownMenuItemType.Divider },
+  { key: 'vegsHeader', text: 'Vegetables', itemType: DropdownMenuItemType.Header },
+  { key: 'carrot', text: 'Carrot' },
+];
+```
+
+```tsx
+// v9
+import { Dropdown, Option, OptionGroup } from '@fluentui/react-components';
+
+<Dropdown>
+  <OptionGroup label="Fruits">
+    <Option value="apple">Apple</Option>
+    <Option value="banana">Banana</Option>
+  </OptionGroup>
+  <OptionGroup label="Vegetables">
+    <Option value="carrot">Carrot</Option>
+  </OptionGroup>
+</Dropdown>;
+```
+
+## IDropdownProps → DropdownProps
+
+| v8                   | v9                               | Notes                                                                         |
+| -------------------- | -------------------------------- | ----------------------------------------------------------------------------- |
+| `options`            | `<Option>` children              | Each `IDropdownOption` → `<Option>`                                           |
+| `selectedKey`        | `selectedOptions={[key]}`        | v9 takes an array even for single select                                      |
+| `selectedKeys`       | `selectedOptions={keys}`         | Multi-select                                                                  |
+| `defaultSelectedKey` | `defaultSelectedOptions={[key]}` |                                                                               |
+| `onChange`           | `onOptionSelect`                 | `(ev, data) => void`; data has `optionValue`, `optionText`, `selectedOptions` |
+| `placeholder`        | `placeholder`                    |                                                                               |
+| `label`              | `<Field label="...">` wrapper    | Same as other form controls                                                   |
+| `disabled`           | `disabled`                       |                                                                               |
+| `required`           | `required` on `<Field>`          |                                                                               |
+| `errorMessage`       | `validationMessage` on `<Field>` |                                                                               |
+| `multiSelect`        | `multiselect`                    | Casing change                                                                 |
+| `calloutProps`       | `Listbox` props / `positioning`  |                                                                               |
+| `styles`             | `className` + `makeStyles`       |                                                                               |
+| `theme`              | `FluentProvider`                 |                                                                               |
+| `componentRef`       | `ref`                            |                                                                               |
+
+## IDropdownOption → Option
+
+| v8 `IDropdownOption` | v9 `Option`            | Notes                                                           |
+| -------------------- | ---------------------- | --------------------------------------------------------------- |
+| `key`                | `value`                | `<Option value="apple">`                                        |
+| `text`               | `children`             | `<Option>Apple</Option>`                                        |
+| `disabled`           | `disabled`             |                                                                 |
+| `hidden`             | —                      | Remove from the list instead                                    |
+| `title`              | `title`                |                                                                 |
+| `itemType: Header`   | `OptionGroup` label    | See grouped options example above                               |
+| `itemType: Divider`  | `OptionGroup` boundary | No `OptionDivider` in v9; use separate `<OptionGroup>` elements |
+
+---
+
+## Combobox
+
+### Before / After — Combobox basic
+
+```tsx
+// v8
+import { ComboBox, IComboBoxOption } from '@fluentui/react';
+
+const options: IComboBoxOption[] = [
+  { key: 'apple', text: 'Apple' },
+  { key: 'banana', text: 'Banana' },
+];
+
+<ComboBox
+  label="Fruit"
+  placeholder="Select or type"
+  options={options}
+  selectedKey={selectedKey}
+  onChange={(_, option, __, value) => {
+    if (option) setSelectedKey(option.key as string);
+    else setInputValue(value ?? '');
+  }}
+  allowFreeInput
+/>;
+```
+
+```tsx
+// v9
+import { Combobox, Option, Field } from '@fluentui/react-components';
+
+const [selectedKey, setSelectedKey] = React.useState('');
+const [inputValue, setInputValue] = React.useState('');
+
+<Field label="Fruit">
+  <Combobox
+    placeholder="Select or type"
+    value={inputValue}
+    selectedOptions={[selectedKey]}
+    onOptionSelect={(_, data) => {
+      setSelectedKey(data.optionValue ?? '');
+      setInputValue(data.optionText ?? '');
+    }}
+    onChange={e => setInputValue(e.target.value)} // freeform typing
+    freeform // allow values not in the list
+  >
+    <Option value="apple">Apple</Option>
+    <Option value="banana">Banana</Option>
+  </Combobox>
+</Field>;
+```
+
+### Filtering (autocomplete)
+
+```tsx
+// v9 — filter options based on input value
+const [query, setQuery] = React.useState('');
+const matches = options.filter(o => o.toLowerCase().includes(query.toLowerCase()));
+
+<Combobox
+  value={query}
+  onChange={e => setQuery(e.target.value)}
+  onOptionSelect={(_, data) => setQuery(data.optionText ?? '')}
+>
+  {matches.map(o => (
+    <Option key={o} value={o}>
+      {o}
+    </Option>
+  ))}
+</Combobox>;
+```
+
+## IComboBoxProps → ComboboxProps
+
+| v8                   | v9                               | Notes                                                       |
+| -------------------- | -------------------------------- | ----------------------------------------------------------- |
+| `options`            | `<Option>` children              |                                                             |
+| `selectedKey`        | `selectedOptions={[key]}`        |                                                             |
+| `onChange`           | `onOptionSelect` + `onChange`    | `onOptionSelect` for list picks; `onChange` for typed input |
+| `allowFreeInput`     | `freeform`                       |                                                             |
+| `autoComplete`       | `autoComplete`                   | `"on"` or `"off"`                                           |
+| `label`              | `<Field label="...">` wrapper    |                                                             |
+| `placeholder`        | `placeholder`                    |                                                             |
+| `disabled`           | `disabled`                       |                                                             |
+| `multiSelect`        | `multiselect`                    |                                                             |
+| `text` (display val) | `value`                          | The text shown in the input                                 |
+| `errorMessage`       | `validationMessage` on `<Field>` |                                                             |
+| `styles`             | `className` + `makeStyles`       |                                                             |
+| `theme`              | `FluentProvider`                 |                                                             |
+| `componentRef`       | `ref`                            |                                                             |
diff --git a/skills/fluentui-migrate-v8-to-v9/references/icons.md b/skills/fluentui-migrate-v8-to-v9/references/icons.md
new file mode 100644
index 0000000000000..e780c25c1cda5
--- /dev/null
+++ b/skills/fluentui-migrate-v8-to-v9/references/icons.md
@@ -0,0 +1,114 @@
+# Icon Migration
+
+## Naming Convention
+
+v8 uses string icon names via `iconProps={{ iconName: 'Add' }}`.
+v9 uses SVG React components from `@fluentui/react-icons`:
+
+```tsx
+// v8
+import { DefaultButton } from '@fluentui/react';
+<DefaultButton iconProps={{ iconName: 'Add' }} text="Add item" />;
+
+// v9
+import { Button } from '@fluentui/react-components';
+import { AddRegular } from '@fluentui/react-icons';
+<Button icon={<AddRegular />}>Add item</Button>;
+```
+
+## Regular vs Filled
+
+- Use `Regular` (outline) by default
+- Use `Filled` for selected, active, or toggled states
+
+```tsx
+import { StarRegular, StarFilled } from '@fluentui/react-icons';
+<Button icon={isStarred ? <StarFilled /> : <StarRegular />} />;
+```
+
+## Common v8 iconName → v9 Component
+
+| v8 `iconName`     | v9 Component            | Notes                   |
+| ----------------- | ----------------------- | ----------------------- |
+| `Add`             | `AddRegular`            |                         |
+| `AddFriend`       | `PersonAddRegular`      |                         |
+| `ArrowDown`       | `ArrowDownRegular`      |                         |
+| `ArrowLeft`       | `ArrowLeftRegular`      |                         |
+| `ArrowRight`      | `ArrowRightRegular`     |                         |
+| `ArrowUp`         | `ArrowUpRegular`        |                         |
+| `Attach`          | `AttachRegular`         |                         |
+| `Back`            | `ArrowLeftRegular`      |                         |
+| `Cancel`          | `DismissRegular`        | Renamed                 |
+| `CheckMark`       | `CheckmarkRegular`      | Renamed (lowercase 'm') |
+| `ChevronDown`     | `ChevronDownRegular`    |                         |
+| `ChevronLeft`     | `ChevronLeftRegular`    |                         |
+| `ChevronRight`    | `ChevronRightRegular`   |                         |
+| `ChevronUp`       | `ChevronUpRegular`      |                         |
+| `CircleRing`      | `CircleRegular`         | Renamed                 |
+| `Clear`           | `DismissRegular`        | Renamed                 |
+| `Close`           | `DismissRegular`        | Renamed                 |
+| `Copy`            | `CopyRegular`           |                         |
+| `Delete`          | `DeleteRegular`         |                         |
+| `Download`        | `ArrowDownloadRegular`  | Renamed                 |
+| `Edit`            | `EditRegular`           |                         |
+| `Error`           | `ErrorCircleRegular`    | Renamed                 |
+| `Filter`          | `FilterRegular`         |                         |
+| `Forward`         | `ArrowRightRegular`     |                         |
+| `Globe`           | `GlobeRegular`          |                         |
+| `Home`            | `HomeRegular`           |                         |
+| `Info`            | `InfoRegular`           |                         |
+| `Link`            | `LinkRegular`           |                         |
+| `List`            | `ListRegular`           |                         |
+| `Mail`            | `MailRegular`           |                         |
+| `More`            | `MoreHorizontalRegular` | Renamed                 |
+| `MoreVertical`    | `MoreVerticalRegular`   |                         |
+| `OpenInNewWindow` | `OpenRegular`           | Renamed                 |
+| `People`          | `PeopleRegular`         |                         |
+| `Pin`             | `PinRegular`            |                         |
+| `Print`           | `PrintRegular`          |                         |
+| `Refresh`         | `ArrowClockwiseRegular` | Renamed                 |
+| `Save`            | `SaveRegular`           |                         |
+| `Search`          | `SearchRegular`         |                         |
+| `Send`            | `SendRegular`           |                         |
+| `Settings`        | `SettingsRegular`       |                         |
+| `Share`           | `ShareRegular`          |                         |
+| `Star`            | `StarRegular`           |                         |
+| `Tag`             | `TagRegular`            |                         |
+| `Unknown`         | `QuestionCircleRegular` | Renamed                 |
+| `Upload`          | `ArrowUploadRegular`    | Renamed                 |
+| `User`            | `PersonRegular`         | Renamed                 |
+| `Warning`         | `WarningRegular`        |                         |
+
+## Finding Icon Names
+
+If an icon name isn't in the table above, the pattern is usually:
+
+1. Convert `PascalCase` iconName to the same name + `Regular` suffix
+2. Check [Fluent UI Icons](https://react.fluentui.dev/?path=/story/icons-catalog--docs) for the full catalog
+
+Search the icons package:
+
+```sh
+# Find icons matching a keyword (grep the type declarations)
+grep -r "export.*Regular" node_modules/@fluentui/react-icons/lib/components/ 2>/dev/null | grep -i "dismiss" | head -10
+
+# Alternative: search the index type file
+grep "Dismiss" node_modules/@fluentui/react-icons/lib/index.d.ts 2>/dev/null | head -10
+```
+
+The online catalog is authoritative: https://react.fluentui.dev/?path=/story/icons-catalog--docs
+
+## Standalone Icon Usage
+
+```tsx
+// v8
+import { Icon } from '@fluentui/react';
+<Icon iconName="Add" />
+
+// v9
+import { AddRegular } from '@fluentui/react-icons';
+<AddRegular />
+
+// With custom size/color
+<AddRegular fontSize={24} style={{ color: 'blue' }} />
+```
diff --git a/skills/fluentui-migrate-v8-to-v9/references/input.md b/skills/fluentui-migrate-v8-to-v9/references/input.md
new file mode 100644
index 0000000000000..011826820a3ab
--- /dev/null
+++ b/skills/fluentui-migrate-v8-to-v9/references/input.md
@@ -0,0 +1,123 @@
+# Input / Textarea Migration
+
+## Overview
+
+| v8                        | v9         | When                             |
+| ------------------------- | ---------- | -------------------------------- |
+| `TextField` (single-line) | `Input`    | Default                          |
+| `TextField multiline`     | `Textarea` | When `multiline` prop is present |
+
+## Before / After Examples
+
+### Basic TextField → Input (preferred: Field wrapper)
+
+```tsx
+// v8
+import { TextField } from '@fluentui/react';
+<TextField label="Email" required errorMessage="Required" />;
+```
+
+```tsx
+// v9 — preferred: use Field to wrap Input (handles label, required, validation automatically)
+import { Field, Input } from '@fluentui/react-components';
+
+<Field label="Email" required validationState="error" validationMessage="Required">
+  <Input />
+</Field>;
+```
+
+```tsx
+// v9 — alternative: manual wiring with useId
+import { Input, Label, Text, useId } from '@fluentui/react-components';
+
+const emailId = useId('email');
+const errorId = useId('email-error');
+
+<div>
+  <Label htmlFor={emailId} required>
+    Email
+  </Label>
+  <Input id={emailId} required aria-invalid aria-describedby={errorId} />
+  <Text id={errorId}>Required</Text>
+</div>;
+```
+
+### Multiline TextField → Textarea
+
+```tsx
+// v8
+<TextField multiline rows={4} label="Description" />;
+
+// v9
+import { Field, Textarea } from '@fluentui/react-components';
+
+<Field label="Description">
+  <Textarea rows={4} />
+</Field>;
+```
+
+### Prefix / Suffix
+
+```tsx
+// v8
+<TextField prefix="https://" suffix=".com" />;
+
+// v9
+import { Input } from '@fluentui/react-components';
+<Input contentBefore="https://" contentAfter=".com" />;
+// Note: contentBefore/contentAfter accept ReactNode (slot), not just strings
+```
+
+### Underlined / Borderless appearance
+
+```tsx
+// v8
+<TextField underlined />
+<TextField borderless />
+
+// v9
+<Input appearance="underline" />
+<Input appearance="filled-lighter" />
+```
+
+## Prop Mapping
+
+| v8 `TextField`             | v9 `Input`                               | Notes                                                      |
+| -------------------------- | ---------------------------------------- | ---------------------------------------------------------- |
+| `componentRef`             | `ref`                                    | Returns DOM node, not ITextField                           |
+| `elementRef`               | `ref`                                    |                                                            |
+| `multiline`                | —                                        | Use `Textarea` instead                                     |
+| `resizable`                | —                                        | Textarea only                                              |
+| `autoAdjustHeight`         | —                                        | See Textarea docs                                          |
+| `underlined`               | `appearance="underline"`                 |                                                            |
+| `borderless`               | `appearance="filled-lighter"`            |                                                            |
+| `label`                    | `<Field label="...">` wrapping `<Input>` | Preferred; or manual `<Label>` + `useId`                   |
+| `required`                 | `required` on `<Field>`                  | Field propagates to input via context                      |
+| `onRenderLabel`            | —                                        | Use slots                                                  |
+| `description`              | `hint` slot on `<Field>`                 | `<Field hint="...">`                                       |
+| `onRenderDescription`      | —                                        |                                                            |
+| `onRenderInput`            | —                                        | Use slots                                                  |
+| `prefix`                   | `contentBefore` slot                     | Accepts ReactNode                                          |
+| `suffix`                   | `contentAfter` slot                      | Accepts ReactNode                                          |
+| `iconProps`                | `contentBefore` or `contentAfter` slot   |                                                            |
+| `defaultValue`             | `defaultValue`                           | Mutually exclusive with `value`                            |
+| `value`                    | `value`                                  | Mutually exclusive with `defaultValue`                     |
+| `disabled`                 | `disabled`                               |                                                            |
+| `readOnly`                 | `readOnly`                               | Native HTML prop                                           |
+| `invalid`                  | `validationState="error"` on `<Field>`   | Use `Field` wrapper; or `aria-invalid` on `Input` directly |
+| `errorMessage`             | `validationMessage` on `<Field>`         | `<Field validationState="error" validationMessage="...">`  |
+| `onChange`                 | `onChange`                               | TypeScript types changed                                   |
+| `onNotifyValidationResult` | —                                        |                                                            |
+| `onGetErrorMessage`        | —                                        |                                                            |
+| `deferredValidationTime`   | —                                        |                                                            |
+| `className`                | `className`                              |                                                            |
+| `inputClassName`           | `input` slot                             |                                                            |
+| `ariaLabel`                | `aria-label`                             |                                                            |
+| `validateOnFocusIn`        | —                                        |                                                            |
+| `validateOnFocusOut`       | —                                        |                                                            |
+| `validateOnLoad`           | —                                        |                                                            |
+| `theme`                    | —                                        | Use `FluentProvider`                                       |
+| `styles`                   | `className` + `makeStyles`               |                                                            |
+| `autoComplete`             | `autoComplete`                           | Native HTML prop                                           |
+| `canRevealPassword`        | —                                        | Not built-in                                               |
+| `revealPasswordAriaLabel`  | —                                        | Not built-in                                               |
diff --git a/skills/fluentui-migrate-v8-to-v9/references/menu.md b/skills/fluentui-migrate-v8-to-v9/references/menu.md
new file mode 100644
index 0000000000000..b732f60eeb0e1
--- /dev/null
+++ b/skills/fluentui-migrate-v8-to-v9/references/menu.md
@@ -0,0 +1,144 @@
+# Menu Migration
+
+## Architecture Change
+
+In v8 menus are **data-driven**: pass an `items` array to `ContextualMenu` or `menuProps` on a button.
+
+In v9 menus are **declarative**: compose JSX children under `Menu`.
+
+## Before / After Example
+
+```tsx
+// v8 — data-driven
+import { ContextualMenu, ContextualMenuItemType } from '@fluentui/react';
+
+<ContextualMenu
+  target={targetRef}
+  items={[
+    { key: 'new', text: 'New', onClick: handleNew },
+    { key: 'div1', itemType: ContextualMenuItemType.Divider },
+    { key: 'open', text: 'Open', iconProps: { iconName: 'FolderOpen' } },
+    {
+      key: 'recent',
+      text: 'Recent',
+      subMenuProps: {
+        items: [{ key: 'file1', text: 'file1.txt' }],
+      },
+    },
+  ]}
+  onDismiss={handleDismiss}
+/>;
+```
+
+```tsx
+// v9 — declarative
+import {
+  Menu,
+  MenuTrigger,
+  MenuPopover,
+  MenuList,
+  MenuItem,
+  MenuDivider,
+  MenuButton,
+} from '@fluentui/react-components';
+import { FolderOpenRegular } from '@fluentui/react-icons';
+
+<Menu>
+  <MenuTrigger disableButtonEnhancement>
+    <MenuButton>Open menu</MenuButton>
+  </MenuTrigger>
+  <MenuPopover>
+    <MenuList>
+      <MenuItem onClick={handleNew}>New</MenuItem>
+      <MenuDivider />
+      <MenuItem icon={<FolderOpenRegular />}>Open</MenuItem>
+      <Menu>
+        <MenuTrigger disableButtonEnhancement>
+          <MenuItem hasSubmenu>Recent</MenuItem>
+        </MenuTrigger>
+        <MenuPopover>
+          <MenuList>
+            <MenuItem>file1.txt</MenuItem>
+          </MenuList>
+        </MenuPopover>
+      </Menu>
+    </MenuList>
+  </MenuPopover>
+</Menu>;
+```
+
+## itemType Enum → Component Mapping
+
+| v8 `ContextualMenuItemType` | v9 component                           |
+| --------------------------- | -------------------------------------- |
+| `Normal`                    | `MenuItem`                             |
+| `Divider`                   | `MenuDivider`                          |
+| `Header`                    | `MenuGroupHeader` (inside `MenuGroup`) |
+| `Section`                   | `MenuGroup`                            |
+| Checkable item (`canCheck`) | `MenuItemCheckbox`                     |
+| Radio item                  | `MenuItemRadio`                        |
+| Split item (`split`)        | `MenuSplitGroup`                       |
+
+## IContextualMenuProps → MenuProps
+
+| v8                | v9                           | Notes                                        |
+| ----------------- | ---------------------------- | -------------------------------------------- |
+| `items`           | children                     | JSX `MenuItem`, etc.                         |
+| `hidden`          | `open` / `onOpenChange`      | Controlled via `MenuTrigger` / `MenuPopover` |
+| `directionalHint` | `positioning`                |                                              |
+| `onDismiss`       | `onOpenChange`               |                                              |
+| `onItemClick`     | `onClick` on each `MenuItem` |                                              |
+| `calloutProps`    | `MenuPopover` props          |                                              |
+| `styles`          | `className` + `makeStyles`   |                                              |
+| `theme`           | `FluentProvider`             |                                              |
+
+## IContextualMenuItem → MenuItemProps
+
+| v8                     | v9                                          | Notes                    |
+| ---------------------- | ------------------------------------------- | ------------------------ |
+| `text`                 | `children`                                  |                          |
+| `key`                  | `key`                                       | React key                |
+| `onClick`              | `onClick`                                   |                          |
+| `disabled`             | `disabled`                                  |                          |
+| `iconProps`            | `icon` slot                                 | Pass `<IconComponent />` |
+| `secondaryText`        | `secondaryContent` slot                     |                          |
+| `ariaLabel`            | `aria-label`                                |                          |
+| `componentRef`         | `ref`                                       |                          |
+| `items` (submenu)      | `children` inside nested `<Menu>`           |                          |
+| `itemType`             | Use appropriate component (see table above) |                          |
+| `canCheck` / `checked` | `MenuItemCheckbox` / `MenuItemRadio`        |                          |
+| `split`                | `MenuSplitGroup`                            |                          |
+| `style` / `styles`     | `className` + `makeStyles`                  |                          |
+| `role`                 | —                                           | Set by component         |
+| `inactive`             | —                                           | Removed                  |
+
+## IContextualMenuSection → MenuGroup
+
+| v8                             | v9                                    |
+| ------------------------------ | ------------------------------------- |
+| `title`                        | `MenuGroupHeader` children            |
+| `items`                        | `MenuGroup` children                  |
+| `topDivider` / `bottomDivider` | — Removed; add `MenuDivider` manually |
+
+## MenuItemShim (Incremental Migration)
+
+`MenuItemShim` accepts a v8 `IContextualMenuItem` object and renders a v9 `MenuItem`. Use it to keep existing `items` arrays working while the rest of the component migrates.
+
+```tsx
+import { MenuItemShim } from '@fluentui/react-migration-v8-v9';
+
+// v8 items array can stay unchanged:
+const items: IContextualMenuItem[] = [
+  { key: 'new', text: 'New', onClick: handleNew },
+  { key: 'open', text: 'Open', iconProps: { iconName: 'FolderOpen' } },
+];
+
+// Render inside v9 MenuList:
+<MenuList>
+  {items.map(item => (
+    <MenuItemShim key={item.key} item={item} />
+  ))}
+</MenuList>;
+```
+
+Replace with native `MenuItem` JSX (see example above) when ready.
diff --git a/skills/fluentui-migrate-v8-to-v9/references/messagebar.md b/skills/fluentui-migrate-v8-to-v9/references/messagebar.md
new file mode 100644
index 0000000000000..527e81f5854f7
--- /dev/null
+++ b/skills/fluentui-migrate-v8-to-v9/references/messagebar.md
@@ -0,0 +1,135 @@
+# MessageBar Migration
+
+## Architecture Change
+
+v8 `MessageBar` is a flat component: all configuration (type, dismiss, actions) is passed as props.
+
+v9 `MessageBar` is **composable**: content is structured via `MessageBarBody`, `MessageBarTitle`, and `MessageBarActions` children. Dismiss is a button in `MessageBarActions`'s `containerAction` slot.
+
+## Before / After Example
+
+```tsx
+// v8
+import { MessageBar, MessageBarType, MessageBarButton } from '@fluentui/react';
+
+<MessageBar
+  messageBarType={MessageBarType.error}
+  isMultiline={false}
+  onDismiss={() => setVisible(false)}
+  dismissButtonAriaLabel="Close"
+  actions={
+    <div>
+      <MessageBarButton onClick={handleAction}>Retry</MessageBarButton>
+    </div>
+  }
+>
+  Upload failed. Please try again.
+</MessageBar>;
+```
+
+```tsx
+// v9
+import { MessageBar, MessageBarBody, MessageBarTitle, MessageBarActions, Button } from '@fluentui/react-components';
+import { DismissRegular } from '@fluentui/react-icons';
+
+<MessageBar intent="error">
+  <MessageBarBody>
+    <MessageBarTitle>Upload failed</MessageBarTitle>
+    Please try again.
+  </MessageBarBody>
+  <MessageBarActions
+    containerAction={
+      <Button
+        appearance="transparent"
+        icon={<DismissRegular />}
+        onClick={() => setVisible(false)}
+        aria-label="Dismiss"
+      />
+    }
+  >
+    <Button onClick={handleAction}>Retry</Button>
+  </MessageBarActions>
+</MessageBar>;
+```
+
+## MessageBarType → intent
+
+| v8 `MessageBarType`            | v9 `intent` | Notes                                      |
+| ------------------------------ | ----------- | ------------------------------------------ |
+| `MessageBarType.info`          | `"info"`    | Default                                    |
+| `MessageBarType.success`       | `"success"` |                                            |
+| `MessageBarType.warning`       | `"warning"` |                                            |
+| `MessageBarType.severeWarning` | `"warning"` | No separate "severe" in v9                 |
+| `MessageBarType.error`         | `"error"`   |                                            |
+| `MessageBarType.blocked`       | `"error"`   | No direct equivalent; use `"error"` intent |
+
+## Simple (no actions, no dismiss)
+
+```tsx
+// v8
+<MessageBar>This is an informational message.</MessageBar>;
+
+// v9
+import { MessageBar, MessageBarBody } from '@fluentui/react-components';
+
+<MessageBar>
+  <MessageBarBody>This is an informational message.</MessageBarBody>
+</MessageBar>;
+```
+
+## Multiline
+
+```tsx
+// v8
+<MessageBar isMultiline={true}>
+  Long message that wraps to multiple lines.
+</MessageBar>
+
+// v9 — multiline is the default; use layout="multiline" explicitly if needed
+<MessageBar layout="multiline">
+  <MessageBarBody>Long message that wraps to multiple lines.</MessageBarBody>
+</MessageBar>
+```
+
+## Controlled Visibility Pattern
+
+```tsx
+// v9 — render the MessageBar conditionally (no built-in open/close)
+const [visible, setVisible] = React.useState(true);
+
+{
+  visible && (
+    <MessageBar intent="warning">
+      <MessageBarBody>Warning: your session will expire soon.</MessageBarBody>
+      <MessageBarActions
+        containerAction={
+          <Button
+            appearance="transparent"
+            icon={<DismissRegular />}
+            onClick={() => setVisible(false)}
+            aria-label="Dismiss"
+          />
+        }
+      />
+    </MessageBar>
+  );
+}
+```
+
+## IMessageBarProps → MessageBarProps
+
+| v8                        | v9                                   | Notes                                                 |
+| ------------------------- | ------------------------------------ | ----------------------------------------------------- |
+| `messageBarType`          | `intent`                             | See table above                                       |
+| `isMultiline`             | `layout`                             | `"singleline"` \| `"multiline"` \| `"auto"` (default) |
+| `onDismiss`               | Button in `containerAction` slot     | Provide `<Button onClick={...}>` explicitly           |
+| `dismissButtonAriaLabel`  | `aria-label` on the dismiss `Button` |                                                       |
+| `actions`                 | `<MessageBarActions>` children       |                                                       |
+| `isBlocking`              | —                                    | Removed; v9 MessageBar never blocks the page          |
+| `overflowButtonAriaLabel` | —                                    | Removed                                               |
+| `truncated`               | —                                    | Removed; handled via `layout`                         |
+| `expandButtonProps`       | —                                    | Removed                                               |
+| `messageBarIconProps`     | `icon` slot on `<MessageBar>`        | Pass `<IconComponent />` to `icon` slot               |
+| `className`               | `className`                          |                                                       |
+| `styles`                  | `className` + `makeStyles`           |                                                       |
+| `theme`                   | `FluentProvider`                     |                                                       |
diff --git a/skills/fluentui-migrate-v8-to-v9/references/progressbar.md b/skills/fluentui-migrate-v8-to-v9/references/progressbar.md
new file mode 100644
index 0000000000000..c0aed158ee4ac
--- /dev/null
+++ b/skills/fluentui-migrate-v8-to-v9/references/progressbar.md
@@ -0,0 +1,96 @@
+# ProgressIndicator → ProgressBar Migration
+
+## Key Changes
+
+- Component renamed: `ProgressIndicator` → `ProgressBar`
+- `percentComplete` prop renamed to `value` (same 0–1 range, `max` defaults to `1`)
+- `label` prop removed → wrap `ProgressBar` in `<Field label="...">`
+- `description` prop removed → use `<Field hint="...">`
+- Indeterminate state: v8 omits `percentComplete`; v9 omits `value`
+- `barHeight` removed → use `thickness` prop
+
+## Before / After Example
+
+### Determinate progress
+
+```tsx
+// v8
+import { ProgressIndicator } from '@fluentui/react';
+
+<ProgressIndicator label="Uploading files" description="12 of 100 files" percentComplete={0.12} />;
+```
+
+```tsx
+// v9
+import { Field, ProgressBar } from '@fluentui/react-components';
+
+<Field label="Uploading files" hint="12 of 100 files">
+  <ProgressBar value={0.12} />
+</Field>;
+```
+
+### Indeterminate progress
+
+```tsx
+// v8 — omit percentComplete
+<ProgressIndicator label="Loading" />;
+
+// v9 — omit value
+import { Field, ProgressBar } from '@fluentui/react-components';
+
+<Field label="Loading">
+  <ProgressBar />
+</Field>;
+```
+
+### Without label (aria-label only)
+
+```tsx
+// v8
+<ProgressIndicator percentComplete={0.5} ariaLabel="Upload progress" />;
+
+// v9
+import { ProgressBar } from '@fluentui/react-components';
+
+<ProgressBar value={0.5} aria-label="Upload progress" />;
+```
+
+## Custom max value
+
+```tsx
+// v9 — use max prop when your value range is not 0–1
+import { Field, ProgressBar } from '@fluentui/react-components';
+
+const filesUploaded = 42;
+const totalFiles = 100;
+
+<Field label="Uploading files" hint={`${filesUploaded} of ${totalFiles}`}>
+  <ProgressBar value={filesUploaded} max={totalFiles} />
+</Field>;
+```
+
+## Thickness
+
+```tsx
+// v9 — thin or medium bar
+<ProgressBar value={0.5} thickness="large" />
+// thickness: "medium" (default) | "large"
+```
+
+## IProgressIndicatorProps → ProgressBarProps
+
+| v8                | v9                         | Notes                                                                |
+| ----------------- | -------------------------- | -------------------------------------------------------------------- |
+| `percentComplete` | `value`                    | Same 0–1 range; `max` defaults to `1`                                |
+| `label`           | `<Field label="...">`      | Wrap `ProgressBar` in `Field`                                        |
+| `description`     | `<Field hint="...">`       | `hint` slot on `Field`                                               |
+| `ariaLabel`       | `aria-label`               | Native HTML prop                                                     |
+| `ariaValueText`   | `aria-valuetext`           | Native HTML prop                                                     |
+| `barHeight`       | `thickness`                | `"medium"` \| `"large"`                                              |
+| `progressHidden`  | —                          | Conditionally render the component instead                           |
+| `className`       | `className`                |                                                                      |
+| `styles`          | `className` + `makeStyles` |                                                                      |
+| `theme`           | `FluentProvider`           |                                                                      |
+| `componentRef`    | `ref`                      |                                                                      |
+| —                 | `max`                      | New — custom maximum value (default `1`)                             |
+| —                 | `color`                    | New — `"brand"` (default) \| `"success"` \| `"warning"` \| `"error"` |
diff --git a/skills/fluentui-migrate-v8-to-v9/references/radiogroup.md b/skills/fluentui-migrate-v8-to-v9/references/radiogroup.md
new file mode 100644
index 0000000000000..b8409fed3a6f0
--- /dev/null
+++ b/skills/fluentui-migrate-v8-to-v9/references/radiogroup.md
@@ -0,0 +1,132 @@
+# ChoiceGroup → RadioGroup Migration
+
+## Architecture Change
+
+In v8, `ChoiceGroup` accepts options via an `options` array prop.
+In v9, `RadioGroup` accepts `Radio` elements as JSX children.
+
+The `label` prop is removed. Two options:
+
+- **Preferred:** wrap `RadioGroup` in `<Field label="...">` — Field renders the label and wires accessibility via context.
+- **Alternative:** separate `<Label id={labelId}>` + `aria-labelledby={labelId}` on `RadioGroup`.
+
+## Before / After Examples
+
+### Basic Migration
+
+```tsx
+// v8
+import { ChoiceGroup, IChoiceGroupOption } from '@fluentui/react';
+
+const options: IChoiceGroupOption[] = [
+  { key: 'A', text: 'Option A' },
+  { key: 'B', text: 'Option B' },
+  { key: 'C', text: 'Option C', disabled: true },
+];
+
+<ChoiceGroup defaultSelectedKey="B" options={options} label="Pick one" required />;
+```
+
+```tsx
+// v9 — preferred: Field wrapper
+import { Field, Radio, RadioGroup } from '@fluentui/react-components';
+
+<Field label="Pick one" required>
+  <RadioGroup defaultValue="B">
+    <Radio value="A" label="Option A" />
+    <Radio value="B" label="Option B" />
+    <Radio value="C" label="Option C" disabled />
+  </RadioGroup>
+</Field>;
+```
+
+```tsx
+// v9 — alternative: manual label wiring
+import { Label, Radio, RadioGroup, useId } from '@fluentui/react-components';
+
+const labelId = useId('label');
+
+<>
+  <Label id={labelId} required>
+    Pick one
+  </Label>
+  <RadioGroup aria-labelledby={labelId} defaultValue="B">
+    <Radio value="A" label="Option A" />
+    <Radio value="B" label="Option B" />
+    <Radio value="C" label="Option C" disabled />
+  </RadioGroup>
+</>;
+```
+
+### Controlled (selectedKey → value)
+
+```tsx
+// v8
+const [selected, setSelected] = React.useState('A');
+<ChoiceGroup selectedKey={selected} options={options} onChange={(_, option) => option && setSelected(option.key)} />;
+
+// v9
+const [selected, setSelected] = React.useState('A');
+<RadioGroup value={selected} onChange={(_, data) => setSelected(data.value)}>
+  <Radio value="A" label="Option A" />
+  <Radio value="B" label="Option B" />
+</RadioGroup>;
+```
+
+### Custom Option Rendering
+
+v9 accepts direct JSX instead of `onRenderField` callbacks:
+
+```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
+import { AnimalCat24Regular } from '@fluentui/react-icons';
+
+<Radio
+  value="A"
+  label={{
+    children: <><AnimalCat24Regular /> With icon</>,
+  }}
+/>
+```
+
+## ChoiceGroup → RadioGroup Prop Mapping
+
+| v8 `IChoiceGroupProps` | v9 `RadioGroupProps`    | Notes                                       |
+| ---------------------- | ----------------------- | ------------------------------------------- |
+| `componentRef`         | `ref`                   |                                             |
+| `options`              | `children`              | Use `<Radio>` children instead of array     |
+| `defaultSelectedKey`   | `defaultValue`          | Mutually exclusive with `value`             |
+| `selectedKey`          | `value`                 | Mutually exclusive with `defaultValue`      |
+| `onChange`             | `onChange`              | TypeScript types changed                    |
+| `label`                | `<Field label="...">`   | Preferred; or `<Label>` + `aria-labelledby` |
+| `ariaLabelledBy`       | `aria-labelledby`       | Native HTML prop in v9                      |
+| `required`             | `required` on `<Field>` | Or on `<Label>` when using manual wiring    |
+| `styles`               | `className`             |                                             |
+| `theme`                | —                       | Use `FluentProvider`                        |
+
+## IChoiceGroupOption → Radio Prop Mapping
+
+| v8 `IChoiceGroupOption` | v9 `RadioProps` | Notes                                             |
+| ----------------------- | --------------- | ------------------------------------------------- |
+| `key`                   | `key`           | Only needed when `.map()`-ing an array            |
+| `text`                  | `label`         | Slot — accepts string, JSX, or shorthand object   |
+| `disabled`              | `disabled`      |                                                   |
+| `ariaLabel`             | `aria-label`    | Native HTML prop                                  |
+| `onRenderField`         | —               | Provide custom JSX child to `RadioGroup` instead  |
+| `onRenderLabel`         | `label` slot    | Pass custom component to `label` slot             |
+| `iconProps`             | —               | Use slots to customize `Radio`                    |
+| `imageSrc`              | —               | Use slots to customize `Radio`                    |
+| `styles`                | `className`     |                                                   |
+| `theme`                 | —               | Use `FluentProvider`                              |
+| `checked`               | `checked`       | Prefer `value` on `RadioGroup` for controlled use |
+| `onChange`              | `onChange`      | TypeScript types changed                          |
+| `name`                  | `name`          | Inherited from `RadioGroup` by default            |
+| `required`              | `required`      |                                                   |
diff --git a/skills/fluentui-migrate-v8-to-v9/references/slider.md b/skills/fluentui-migrate-v8-to-v9/references/slider.md
new file mode 100644
index 0000000000000..72b4a01c27817
--- /dev/null
+++ b/skills/fluentui-migrate-v8-to-v9/references/slider.md
@@ -0,0 +1,122 @@
+# Slider Migration
+
+## Key Changes
+
+- `label` prop removed → wrap in `<Field label="...">` (same pattern as SpinButton, Input)
+- `onChange` signature changed: `(event, value: number)` → `(event, data: { value: number })`
+- `showValue` removed — no built-in value display; render the value in JSX manually
+- `originFromZero` removed — no v9 equivalent
+- `snapToStep` removed — v9 always snaps to `step` increments automatically
+- `size` prop added: `"small"` | `"medium"` (new in v9)
+
+## Before / After Examples
+
+### Basic Migration
+
+```tsx
+// v8
+import { Slider } from '@fluentui/react';
+
+<Slider label="Volume" min={0} max={100} defaultValue={20} />;
+```
+
+```tsx
+// v9 — wrap in Field for label
+import { Field, Slider } from '@fluentui/react-components';
+
+<Field label="Volume">
+  <Slider min={0} max={100} defaultValue={20} />
+</Field>;
+```
+
+### Controlled
+
+```tsx
+// v8
+const [value, setValue] = React.useState(20);
+
+<Slider label="Volume" min={0} max={100} value={value} onChange={(_, newValue) => setValue(newValue)} />;
+```
+
+```tsx
+// v9
+import { Field, Slider } from '@fluentui/react-components';
+import type { SliderOnChangeData } from '@fluentui/react-components';
+
+const [value, setValue] = React.useState(20);
+
+const onChange = (_: React.ChangeEvent<HTMLInputElement>, data: SliderOnChangeData) => {
+  setValue(data.value);
+};
+
+<Field label="Volume">
+  <Slider min={0} max={100} value={value} onChange={onChange} />
+</Field>;
+```
+
+### Displaying the Current Value
+
+v8 had a `showValue` prop. In v9, render the value yourself:
+
+```tsx
+// v8
+<Slider label="Volume" showValue value={value} min={0} max={100} />;
+
+// v9 — embed value in the label slot
+import { Field, Slider } from '@fluentui/react-components';
+
+const [value, setValue] = React.useState(20);
+
+<Field label={`Volume: ${value}`}>
+  <Slider min={0} max={100} value={value} onChange={(_, data) => setValue(data.value)} />
+</Field>;
+```
+
+### With Step
+
+```tsx
+// v8 — snapToStep was a separate optional prop
+<Slider min={0} max={100} step={10} snapToStep />
+
+// v9 — always snaps to step (snapToStep removed)
+<Slider min={0} max={100} step={10} />
+```
+
+### Vertical Slider
+
+```tsx
+// v8
+<Slider vertical label="Height" min={0} max={100} />;
+
+// v9 — same prop
+import { Field, Slider } from '@fluentui/react-components';
+
+<Field label="Height">
+  <Slider vertical min={0} max={100} />
+</Field>;
+```
+
+## Prop Mapping
+
+| v8 `ISliderProps` | v9 `SliderProps`           | Notes                                                        |
+| ----------------- | -------------------------- | ------------------------------------------------------------ |
+| `componentRef`    | `ref`                      |                                                              |
+| `value`           | `value`                    | Mutually exclusive with `defaultValue`                       |
+| `defaultValue`    | `defaultValue`             | Mutually exclusive with `value`                              |
+| `min`             | `min`                      |                                                              |
+| `max`             | `max`                      |                                                              |
+| `step`            | `step`                     |                                                              |
+| `vertical`        | `vertical`                 |                                                              |
+| `disabled`        | `disabled`                 |                                                              |
+| `label`           | `<Field label="...">`      | Preferred; or `<Label htmlFor={id}>` + `useId`               |
+| `showValue`       | —                          | Removed; render value in JSX (e.g. in `<Field label={...}>`) |
+| `valueFormat`     | —                          | Removed; format the value in JSX manually                    |
+| `snapToStep`      | —                          | Removed; v9 always snaps to `step`                           |
+| `originFromZero`  | —                          | Removed; no v9 equivalent                                    |
+| `onChange`        | `onChange`                 | `(event, data) => void` where `data.value` is `number`       |
+| `ariaLabel`       | `aria-label`               | Native HTML prop                                             |
+| `ariaValueText`   | `aria-valuetext`           | Native HTML prop                                             |
+| `className`       | `className`                |                                                              |
+| `styles`          | `className` + `makeStyles` |                                                              |
+| `theme`           | —                          | Use `FluentProvider`                                         |
+| —                 | `size`                     | New: `"small"` \| `"medium"` (default)                       |
diff --git a/skills/fluentui-migrate-v8-to-v9/references/spinbutton.md b/skills/fluentui-migrate-v8-to-v9/references/spinbutton.md
new file mode 100644
index 0000000000000..0d0d80908ee83
--- /dev/null
+++ b/skills/fluentui-migrate-v8-to-v9/references/spinbutton.md
@@ -0,0 +1,137 @@
+# SpinButton Migration
+
+## Key Changes
+
+- `label` prop removed → preferred: wrap in `<Field label="...">`, or manual `<Label htmlFor={id}>` with `useId`
+- `value` / `defaultValue` type changed: `string` → `number`
+- `onIncrement` / `onDecrement` / `onValidate` removed → use `onChange` with `data.value` / `data.displayValue`
+- New `displayValue` prop for formatted display (e.g., with units)
+
+## Before / After Examples
+
+### Basic Migration
+
+```tsx
+// v8
+import { SpinButton } from '@fluentui/react';
+
+const [value, setValue] = React.useState('5');
+
+<SpinButton
+  label="Quantity"
+  value={value}
+  onChange={(_, newValue) => newValue !== undefined && setValue(newValue)}
+  incrementButtonAriaLabel="Increment"
+  decrementButtonAriaLabel="Decrement"
+  styles={{ spinButtonWrapper: { width: 300 } }}
+/>;
+```
+
+```tsx
+// v9 — preferred: Field wrapper handles label wiring automatically
+import { Field, SpinButton } from '@fluentui/react-components';
+import type { SpinButtonChangeEvent, SpinButtonOnChangeData } from '@fluentui/react-components';
+
+const [value, setValue] = React.useState(5); // number, not string
+
+const onChange = (e: SpinButtonChangeEvent, data: SpinButtonOnChangeData) => {
+  if (data.value !== undefined) {
+    setValue(data.value); // stepped via buttons/hotkeys
+  } else if (data.displayValue !== undefined) {
+    const n = Number(data.displayValue);
+    if (!isNaN(n)) setValue(n); // typed manually
+  }
+};
+
+<Field label="Quantity">
+  <SpinButton value={value} min={0} max={100} onChange={onChange} />
+</Field>;
+```
+
+```tsx
+// v9 — alternative: manual label wiring with useId + makeStyles for sizing
+import { makeStyles, Label, SpinButton, useId } from '@fluentui/react-components';
+import type { SpinButtonChangeEvent, SpinButtonOnChangeData } from '@fluentui/react-components';
+
+const useStyles = makeStyles({
+  layout: { display: 'flex', flexDirection: 'column', maxWidth: '300px' },
+});
+
+const spinButtonId = useId('spinbutton');
+const s = useStyles();
+const [value, setValue] = React.useState(5);
+
+<div className={s.layout}>
+  <Label htmlFor={spinButtonId}>Quantity</Label>
+  <SpinButton id={spinButtonId} value={value} min={0} max={100} onChange={onChange} />
+</div>;
+```
+
+### Custom Suffix (onIncrement/onDecrement → displayValue)
+
+```tsx
+// v8 — separate onIncrement / onDecrement / onValidate callbacks
+<SpinButton
+  defaultValue="7 cm"
+  onIncrement={value => String(Math.min(getNum(value) + 2, 100)) + ' cm'}
+  onDecrement={value => String(Math.max(getNum(value) - 2, 0)) + ' cm'}
+  onValidate={value => String(clamp(getNum(value))) + ' cm'}
+/>
+```
+
+```tsx
+// v9 — use displayValue prop + handle data.displayValue in onChange
+const [value, setValue] = React.useState(7);
+const [displayValue, setDisplayValue] = React.useState('7 cm');
+
+const onChange = (e: SpinButtonChangeEvent, data: SpinButtonOnChangeData) => {
+  if (data.value !== undefined) {
+    setValue(data.value);
+    setDisplayValue(`${data.value} cm`);
+  } else if (data.displayValue !== undefined) {
+    const n = getNumericPart(data.displayValue);
+    if (n !== undefined) {
+      setValue(n);
+      setDisplayValue(`${n} cm`);
+    }
+  }
+};
+
+<SpinButton
+  id={spinButtonId}
+  value={value}
+  displayValue={displayValue}
+  step={2}
+  min={0}
+  max={100}
+  onChange={onChange}
+/>;
+```
+
+## Prop Mapping
+
+| v8 `ISpinButtonProps`      | v9 `SpinButtonProps`     | Notes                                                                                                          |
+| -------------------------- | ------------------------ | -------------------------------------------------------------------------------------------------------------- |
+| `componentRef`             | `ref`                    |                                                                                                                |
+| `value`                    | `value`                  | Type changed `string` → `number`; mutually exclusive with `defaultValue`                                       |
+| `defaultValue`             | `defaultValue`           | Type changed `string` → `number`; mutually exclusive with `value`                                              |
+| `min`                      | `min`                    |                                                                                                                |
+| `max`                      | `max`                    |                                                                                                                |
+| `step`                     | `step`                   |                                                                                                                |
+| `precision`                | `precision`              |                                                                                                                |
+| `onChange`                 | `onChange`               | TypeScript types changed; now receives `(e, data)` with `data.value` (number) and `data.displayValue` (string) |
+| `onIncrement`              | `onChange`               | Handle `data.value` in `onChange`                                                                              |
+| `onDecrement`              | `onChange`               | Handle `data.value` in `onChange`                                                                              |
+| `onValidate`               | —                        | Removed; validate in `onChange`                                                                                |
+| `label`                    | `<Field label="...">`    | Preferred; or manual `<Label htmlFor={useId()}>` + `id`                                                        |
+| `labelPosition`            | `orientation` on `Field` | `"horizontal"` for side-by-side                                                                                |
+| `ariaLabel`                | `aria-label`             |                                                                                                                |
+| `ariaDescribedBy`          | `aria-describedby`       |                                                                                                                |
+| `ariaValueText`            | `aria-valuetext`         | Set internally by SpinButton; can be overridden                                                                |
+| `iconProps`                | —                        | Use `<Icon>` component separately                                                                              |
+| `incrementButtonAriaLabel` | —                        | Set internally; use `aria-label` if needed                                                                     |
+| `decrementButtonAriaLabel` | —                        | Set internally; use `aria-label` if needed                                                                     |
+| `className`                | `className`              |                                                                                                                |
+| `styles`                   | `className`              |                                                                                                                |
+| `theme`                    | —                        | Use `FluentProvider`                                                                                           |
+| —                          | `displayValue`           | New in v9 — formatted display string (separate from `value`)                                                   |
diff --git a/skills/fluentui-migrate-v8-to-v9/references/spinner.md b/skills/fluentui-migrate-v8-to-v9/references/spinner.md
new file mode 100644
index 0000000000000..f3613c64d00e7
--- /dev/null
+++ b/skills/fluentui-migrate-v8-to-v9/references/spinner.md
@@ -0,0 +1,69 @@
+# Spinner Migration
+
+## Key Changes
+
+- `size` prop changes from `SpinnerSize` enum to a string literal
+- `labelPosition` values renamed (`"right"` → `"after"`, `"left"` → `"before"`, `"top"` → `"above"`, `"bottom"` → `"below"`)
+- No structural API change — Spinner remains a single self-contained component
+
+## Before / After Example
+
+```tsx
+// v8
+import { Spinner, SpinnerSize } from '@fluentui/react';
+
+<Spinner size={SpinnerSize.large} label="Loading..." labelPosition="right" />;
+```
+
+```tsx
+// v9
+import { Spinner } from '@fluentui/react-components';
+
+<Spinner size="large" label="Loading..." labelPosition="after" />;
+```
+
+## SpinnerSize Enum → size String
+
+| v8 `SpinnerSize`     | v9 `size`       |
+| -------------------- | --------------- |
+| `SpinnerSize.xSmall` | `"extra-small"` |
+| `SpinnerSize.small`  | `"small"`       |
+| `SpinnerSize.medium` | `"medium"`      |
+| `SpinnerSize.large`  | `"large"`       |
+
+v9 also adds `"tiny"`, `"extra-large"`, and `"huge"` sizes with no v8 equivalent.
+
+## labelPosition Values
+
+| v8         | v9         |
+| ---------- | ---------- |
+| `"right"`  | `"after"`  |
+| `"left"`   | `"before"` |
+| `"top"`    | `"above"`  |
+| `"bottom"` | `"below"`  |
+
+Default in both v8 and v9: label appears below the spinner.
+
+## Appearance Variants (new in v9)
+
+```tsx
+// v9 — inverted appearance for dark backgrounds
+<Spinner appearance="inverted" label="Loading..." />
+// v9 — primary appearance
+<Spinner appearance="primary" label="Loading..." />
+```
+
+## ISpinnerProps → SpinnerProps
+
+| v8              | v9                         | Notes                                  |
+| --------------- | -------------------------- | -------------------------------------- |
+| `size`          | `size`                     | Enum → string literal; see table above |
+| `label`         | `label`                    | Slot — accepts string or JSX           |
+| `labelPosition` | `labelPosition`            | Renamed values; see table above        |
+| `ariaLabel`     | `aria-label`               | Native HTML prop                       |
+| `ariaLive`      | `aria-live`                | Native HTML prop                       |
+| `className`     | `className`                |                                        |
+| `styles`        | `className` + `makeStyles` |                                        |
+| `theme`         | `FluentProvider`           |                                        |
+| `componentRef`  | `ref`                      |                                        |
+| —               | `appearance`               | New: `"primary"` \| `"inverted"`       |
diff --git a/skills/fluentui-migrate-v8-to-v9/references/stack.md b/skills/fluentui-migrate-v8-to-v9/references/stack.md
new file mode 100644
index 0000000000000..4ba34a11171a3
--- /dev/null
+++ b/skills/fluentui-migrate-v8-to-v9/references/stack.md
@@ -0,0 +1,153 @@
+# Stack Migration
+
+## Overview
+
+v9 has no `Stack` component. Replace it with a plain `div` styled using `makeStyles` and CSS flexbox.
+
+As an interim bridge, `StackShim` is available:
+
+```tsx
+import { StackShim } from '@fluentui/react-migration-v8-v9';
+```
+
+## Default Stack (column layout)
+
+```tsx
+// v8
+<Stack>{children}</Stack>;
+
+// v9
+const useStyles = makeStyles({
+  root: {
+    display: 'flex',
+    flexDirection: 'column',
+    flexWrap: 'nowrap',
+    width: 'auto',
+    height: 'auto',
+    boxSizing: 'border-box',
+  },
+});
+const s = useStyles();
+<div className={s.root}>{children}</div>;
+```
+
+## Prop → CSS Reference
+
+### `horizontal`
+
+```ts
+// Stack horizontal
+flexDirection: 'row';
+// default (vertical)
+flexDirection: 'column';
+```
+
+### `reversed`
+
+```ts
+// horizontal + reversed
+flexDirection: 'row-reverse';
+// vertical + reversed
+flexDirection: 'column-reverse';
+```
+
+### `tokens.childrenGap` (spacing between items)
+
+```ts
+// Preferred: CSS gap (v9 dropped IE11 support)
+gap: '10px'
+
+// Alternative: margin on children (use when gap is insufficient)
+'> :not(:last-child)': { marginBottom: '10px' } // vertical
+'> :not(:last-child)': { marginRight: '10px' }  // horizontal
+```
+
+### `tokens.padding`
+
+```ts
+padding: '10px';
+```
+
+### `tokens.maxWidth` / `tokens.maxHeight`
+
+```ts
+maxWidth: '400px';
+maxHeight: '200px';
+```
+
+### `grow`
+
+```ts
+'> *': { flexGrow: 1 }
+```
+
+### `disableShrink`
+
+```ts
+'> *': { flexShrink: 0 }
+```
+
+### `wrap`
+
+```ts
+// Adds a wrapping inner div
+// outer
+flexWrap: 'wrap',
+overflow: 'visible',
+height: '100%',
+
+// inner wrapper div
+display: 'flex',
+flexWrap: 'wrap',
+overflow: 'visible',
+boxSizing: 'border-box',
+width: '100%',
+maxWidth: '100vw',
+```
+
+### `verticalFill`
+
+```ts
+height: '100%';
+```
+
+### `horizontalAlign` / `verticalAlign`
+
+Alignment depends on `flex-direction`:
+
+| Direction          | Horizontal →      | Vertical ↓        |
+| ------------------ | ----------------- | ----------------- |
+| `column` (default) | `align-items`     | `justify-content` |
+| `row` (horizontal) | `justify-content` | `align-items`     |
+
+Value mapping: `start` → `flex-start`, `end` → `flex-end`, `center` → `center`, `space-between` → `space-between`
+
+## StackItem → makeStyles
+
+```tsx
+// v8
+<Stack.Item grow align="center">
+  {child}
+</Stack.Item>;
+
+// v9
+const useStyles = makeStyles({
+  item: {
+    flexGrow: 1,
+    alignSelf: 'center',
+  },
+});
+const s = useStyles();
+<div className={s.item}>{child}</div>;
+```
+
+### StackItem prop → CSS
+
+| v8 `IStackItemProps` | CSS                               |
+| -------------------- | --------------------------------- |
+| `grow`               | `flex-grow: 1` (or numeric value) |
+| `shrink`             | `flex-shrink: 1`                  |
+| `disableShrink`      | `flex-shrink: 0`                  |
+| `align`              | `align-self`                      |
+| `verticalFill`       | `height: 100%`                    |
+| `order`              | `order`                           |
diff --git a/skills/fluentui-migrate-v8-to-v9/references/tabs.md b/skills/fluentui-migrate-v8-to-v9/references/tabs.md
new file mode 100644
index 0000000000000..e3a64f42336db
--- /dev/null
+++ b/skills/fluentui-migrate-v8-to-v9/references/tabs.md
@@ -0,0 +1,103 @@
+# Tabs Migration (Pivot → TabList)
+
+## Architecture Change
+
+In v8 (`Pivot`), tab labels and tab content are co-located inside `PivotItem` children.
+
+In v9 (`TabList`), `Tab` children are the **label only**. Tab content lives **outside** `TabList` and is shown/hidden by state.
+
+## Before / After Example
+
+```tsx
+// v8 — content inside PivotItem
+import { Pivot, PivotItem } from '@fluentui/react';
+
+<Pivot>
+  <PivotItem headerText="First Tab">
+    <p>Content for first tab</p>
+  </PivotItem>
+  <PivotItem headerText="Second Tab">
+    <p>Content for second tab</p>
+  </PivotItem>
+  <PivotItem headerText="Third Tab">
+    <p>Content for third tab</p>
+  </PivotItem>
+</Pivot>;
+```
+
+```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';
+
+const [selectedValue, setSelectedValue] = React.useState<TabValue>('tab1');
+
+const onTabSelect = (_event: SelectTabEvent, data: SelectTabData) => {
+  setSelectedValue(data.value);
+};
+
+<>
+  <TabList selectedValue={selectedValue} onTabSelect={onTabSelect}>
+    <Tab value="tab1">First Tab</Tab>
+    <Tab value="tab2">Second Tab</Tab>
+    <Tab value="tab3">Third Tab</Tab>
+  </TabList>
+
+  <div>
+    {selectedValue === 'tab1' && <p>Content for first tab</p>}
+    {selectedValue === 'tab2' && <p>Content for second tab</p>}
+    {selectedValue === 'tab3' && <p>Content for third tab</p>}
+  </div>
+</>;
+```
+
+## Tab with Icon
+
+```tsx
+// v8
+<PivotItem headerText="Files" itemIcon="Folder" />;
+
+// v9
+import { FolderRegular } from '@fluentui/react-icons';
+<Tab value="files" icon={<FolderRegular />}>
+  Files
+</Tab>;
+```
+
+## Pivot → TabList Prop Mapping
+
+| v8 `Pivot`           | v9 `TabList`               | Notes                |
+| -------------------- | -------------------------- | -------------------- |
+| `componentRef`       | `ref`                      |                      |
+| `className`          | `className`                |                      |
+| `defaultSelectedKey` | `defaultSelectedValue`     |                      |
+| `selectedKey`        | `selectedValue`            |                      |
+| `onLinkClick`        | `onTabSelect`              | New event signature  |
+| `linkSize`           | `size`                     |                      |
+| `focusZoneProps`     | —                          | Removed              |
+| `getTabId`           | —                          | Removed              |
+| `headersOnly`        | —                          | Removed              |
+| `linkFormat`         | —                          | Removed              |
+| `overflowAriaLabel`  | —                          | Removed              |
+| `overflowBehavior`   | —                          | Removed              |
+| `styles`             | `className` + `makeStyles` |                      |
+| `theme`              | —                          | Use `FluentProvider` |
+| —                    | `appearance`               | New in v9            |
+| —                    | `vertical`                 | New in v9            |
+
+## PivotItem → Tab Prop Mapping
+
+| v8 `PivotItem`      | v9 `Tab`     | Notes                                     |
+| ------------------- | ------------ | ----------------------------------------- |
+| `componentRef`      | `ref`        |                                           |
+| `headerText`        | `children`   | Move text to JSX children                 |
+| `itemKey`           | `value`      |                                           |
+| `itemIcon`          | `icon` slot  | Pass `<IconComponent />`                  |
+| `ariaLabel`         | `aria-label` |                                           |
+| `linkText`          | —            | Removed                                   |
+| `headerButtonProps` | —            | Removed                                   |
+| `itemCount`         | —            | Removed                                   |
+| `onRenderItemLink`  | —            | Removed                                   |
+| `keytipProps`       | —            | Removed                                   |
+| `alwaysRender`      | —            | Removed; manage rendering in content area |
diff --git a/skills/fluentui-migrate-v8-to-v9/references/theme.md b/skills/fluentui-migrate-v8-to-v9/references/theme.md
new file mode 100644
index 0000000000000..7a636d1fd8645
--- /dev/null
+++ b/skills/fluentui-migrate-v8-to-v9/references/theme.md
@@ -0,0 +1,205 @@
+# Theme Migration
+
+## Provider
+
+```tsx
+// v8
+import { ThemeProvider } from '@fluentui/react';
+<ThemeProvider theme={myTheme}>
+  <App />
+</ThemeProvider>;
+
+// v9
+import { FluentProvider, webLightTheme } from '@fluentui/react-components';
+<FluentProvider theme={webLightTheme}>
+  <App />
+</FluentProvider>;
+```
+
+v8 applies theme values as a JS object on React context. v9 applies theme values as **CSS variables** in the DOM.
+
+## Default Themes
+
+| v8            | v9                       |
+| ------------- | ------------------------ |
+| Default light | `webLightTheme`          |
+| Default dark  | `webDarkTheme`           |
+| High contrast | `teamsHighContrastTheme` |
+| Teams light   | `teamsDarkTheme`         |
+| Teams dark    | `teamsLightTheme`        |
+
+All built-in themes are exported from `@fluentui/react-components`.
+
+## Side-by-Side (v8 + v9)
+
+When running both versions simultaneously, add a `FluentProvider` at every point where you use v9 components:
+
+```tsx
+import { ThemeProvider } from '@fluentui/react';
+import { FluentProvider, webLightTheme } from '@fluentui/react-components';
+
+<ThemeProvider theme={v8Theme}>
+  <FluentProvider theme={webLightTheme}>{/* v9 components here */}</FluentProvider>
+</ThemeProvider>;
+```
+
+## Token Naming
+
+v8 tokens are component-scoped:
+
+```ts
+theme.semanticColors.buttonBackground;
+theme.semanticColors.buttonBackgroundHovered;
+```
+
+v9 tokens are purpose-scoped (neutral/brand + usage + state):
+
+```ts
+tokens.colorNeutralBackground1;
+tokens.colorNeutralBackground1Hover;
+tokens.colorBrandBackground;
+```
+
+Use v9 tokens in `makeStyles`:
+
+```ts
+import { makeStyles, tokens } from '@fluentui/react-components';
+
+const useStyles = makeStyles({
+  root: {
+    backgroundColor: tokens.colorNeutralBackground1,
+    ':hover': { backgroundColor: tokens.colorNeutralBackground1Hover },
+  },
+});
+```
+
+## Styling: mergeStyles → makeStyles
+
+```tsx
+// v8
+import { mergeStyles, mergeStyleSets } from '@fluentui/react';
+
+const containerClass = mergeStyles({ display: 'flex', gap: '8px' });
+const styles = mergeStyleSets({
+  root: { padding: '16px' },
+  title: { fontWeight: 'bold' },
+});
+
+// v9
+import { makeStyles, mergeClasses } from '@fluentui/react-components';
+
+const useStyles = makeStyles({
+  container: { display: 'flex', gap: '8px' },
+  root: { padding: '16px' },
+  title: { fontWeight: 'bold' },
+});
+
+function MyComponent({ extra }: { extra?: string }) {
+  const s = useStyles();
+  return <div className={mergeClasses(s.root, extra)}>{...}</div>;
+}
+```
+
+Key differences:
+
+- `makeStyles` returns a **hook** — call it inside the component
+- `mergeClasses` replaces `mergeStyles` for combining class names
+- Styles are **static** (no function-in-styles) — use component state passed to the hook via parameters if needed
+
+## Dynamic Styles
+
+`makeStyles` is **static** — the style object cannot contain runtime expressions or variables. Use multiple named rules combined with `mergeClasses` instead:
+
+```tsx
+// WRONG — makeStyles does not accept runtime expressions
+const useStyles = makeStyles({
+  root: { color: isError ? 'red' : 'black' }, // ❌ will not work
+});
+
+// CORRECT — define separate rules, merge conditionally
+const useStyles = makeStyles({
+  root: { color: tokens.colorNeutralForeground1 },
+  error: { color: tokens.colorPaletteRedForeground1 },
+  small: { fontSize: '12px' },
+});
+
+function MyComponent({ isError, isSmall }: { isError: boolean; isSmall: boolean }) {
+  const s = useStyles();
+  return <span className={mergeClasses(s.root, isError && s.error, isSmall && s.small)}>text</span>;
+}
+```
+
+For styles that depend on **numeric or string values** (e.g., dynamic width), use inline `style` for the dynamic part and `makeStyles` for the static shell:
+
+```tsx
+// OK — inline style for truly dynamic values
+const useStyles = makeStyles({ root: { display: 'flex' } });
+const s = useStyles();
+<div className={s.root} style={{ width: `${dynamicWidth}px` }} />;
+```
+
+## Component `styles` Prop → className
+
+```tsx
+// v8 — styles prop
+<Button styles={{ root: { color: 'red' }, label: { fontWeight: 'bold' } }} />;
+
+// v9 — className only; no per-slot styles prop
+const useStyles = makeStyles({
+  btn: { color: 'red', fontWeight: 'bold' },
+});
+const s = useStyles();
+<Button className={s.btn} />;
+```
+
+## Custom Theme Migration
+
+### IPalette → BrandVariants
+
+v8 uses `IPalette` (12 neutral + 9 theme colors). v9 uses `BrandVariants` (16-step ramp).
+
+```ts
+// v9 BrandVariants shape — 16 steps from darkest (10) to lightest (160)
+const myBrand: BrandVariants = {
+  10: '#020305',
+  20: '#111723',
+  30: '#16263D',
+  40: '#193253',
+  50: '#1B3F6A',
+  60: '#1B4D83',
+  70: '#1B5C9E',
+  80: '#1A6CB9',
+  90: '#1471BE',
+  100: '#2079C7',
+  110: '#3086CF',
+  120: '#4F9AD6',
+  130: '#6DAEDE',
+  140: '#91C5E8',
+  150: '#B9D9F2',
+  160: '#E0EEF9',
+};
+
+import { createLightTheme, createDarkTheme } from '@fluentui/react-components';
+
+const myLightTheme = createLightTheme(myBrand);
+const myDarkTheme = createDarkTheme(myBrand);
+
+// Usage — dark theme with CSS variable injection:
+<FluentProvider theme={myDarkTheme}>
+  <App />
+</FluentProvider>;
+```
+
+### Theme Shim Utilities
+
+These helpers are published in `@fluentui/react-migration-v8-v9`:
+
+```ts
+import { createV8Theme, createV9Theme, createBrandVariants } from '@fluentui/react-migration-v8-v9';
+```
+
+| Function              | Input                    | Output        | Use case                             |
+| --------------------- | ------------------------ | ------------- | ------------------------------------ |
+| `createV8Theme`       | v9 theme + BrandVariants | v8 theme      | Make v8 components look like v9      |
+| `createV9Theme`       | v8 theme                 | v9 theme      | Keep v9 components looking like v8   |
+| `createBrandVariants` | v8 IPalette              | BrandVariants | Derive v9 brand ramp from v8 palette |
diff --git a/skills/fluentui-migrate-v8-to-v9/references/toolbar.md b/skills/fluentui-migrate-v8-to-v9/references/toolbar.md
new file mode 100644
index 0000000000000..4089b2cb21112
--- /dev/null
+++ b/skills/fluentui-migrate-v8-to-v9/references/toolbar.md
@@ -0,0 +1,236 @@
+# Toolbar Migration (CommandBar → Toolbar)
+
+## Architecture Change
+
+v8 `CommandBar` is **data-driven**: items are passed as `ICommandBarItemProps[]` arrays —
+one for primary items, one for overflow items, one for far-right items.
+
+v9 `Toolbar` is **declarative**: items are JSX children using `ToolbarButton`,
+`ToolbarToggleButton`, `ToolbarDivider`, etc. Overflow requires the `Overflow` + `OverflowItem`
+pattern from `@fluentui/react-components`.
+
+## Before / After Example
+
+```tsx
+// v8 — CommandBar
+import { CommandBar, ICommandBarItemProps } from '@fluentui/react';
+
+const items: ICommandBarItemProps[] = [
+  { key: 'new', text: 'New', iconProps: { iconName: 'Add' }, onClick: handleNew },
+  { key: 'edit', text: 'Edit', iconProps: { iconName: 'Edit' }, onClick: handleEdit },
+  { key: 'delete', text: 'Delete', iconProps: { iconName: 'Delete' }, disabled: true },
+];
+
+const farItems: ICommandBarItemProps[] = [
+  { key: 'info', text: 'Info', iconProps: { iconName: 'Info' }, onClick: handleInfo },
+];
+
+<CommandBar items={items} farItems={farItems} />;
+```
+
+```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';
+
+const useStyles = makeStyles({ spacer: { marginLeft: 'auto' } });
+
+function MyToolbar() {
+  const s = useStyles();
+  return (
+    <Toolbar>
+      <ToolbarButton icon={<AddRegular />} onClick={handleNew}>
+        New
+      </ToolbarButton>
+      <ToolbarButton icon={<EditRegular />} onClick={handleEdit}>
+        Edit
+      </ToolbarButton>
+      <ToolbarButton icon={<DeleteRegular />} disabled>
+        Delete
+      </ToolbarButton>
+      {/* farItems equivalent: push to far end with marginLeft: auto */}
+      <ToolbarDivider className={s.spacer} />
+      <ToolbarButton icon={<InfoRegular />} onClick={handleInfo}>
+        Info
+      </ToolbarButton>
+    </Toolbar>
+  );
+}
+```
+
+## CommandBarButton → ToolbarButton
+
+`CommandBarButton` maps to `ToolbarButton` when used inside a `CommandBar` / `Toolbar`.
+When used standalone (outside a CommandBar), replace with `Button`.
+
+```tsx
+// v8
+import { CommandBarButton } from '@fluentui/react';
+<CommandBarButton iconProps={{ iconName: 'Add' }}>New</CommandBarButton>;
+
+// v9 — inside Toolbar
+import { ToolbarButton } from '@fluentui/react-components';
+import { AddRegular } from '@fluentui/react-icons';
+<ToolbarButton icon={<AddRegular />}>New</ToolbarButton>;
+```
+
+## Toggle Items
+
+```tsx
+// v8 — checked CommandBar item
+const items: ICommandBarItemProps[] = [
+  { key: 'bold', text: 'Bold', iconProps: { iconName: 'Bold' }, checked: isBold, onClick: toggleBold },
+];
+
+// v9 — ToolbarToggleButton
+import { ToolbarToggleButton } from '@fluentui/react-components';
+import { TextBoldRegular } from '@fluentui/react-icons';
+
+<ToolbarToggleButton icon={<TextBoldRegular />} checked={isBold} onClick={toggleBold}>
+  Bold
+</ToolbarToggleButton>;
+```
+
+## SubMenu Items
+
+```tsx
+// v8 — subMenuProps on a CommandBar item
+const items: ICommandBarItemProps[] = [
+  {
+    key: 'export',
+    text: 'Export',
+    iconProps: { iconName: 'Export' },
+    subMenuProps: {
+      items: [
+        { key: 'csv', text: 'Export as CSV', onClick: exportCsv },
+        { key: 'pdf', text: 'Export as PDF', onClick: exportPdf },
+      ],
+    },
+  },
+];
+
+// v9 — wrap ToolbarButton in Menu as the trigger
+import { Menu, MenuTrigger, MenuPopover, MenuList, MenuItem, ToolbarButton } from '@fluentui/react-components';
+import { ExportRegular } from '@fluentui/react-icons';
+
+<Menu>
+  <MenuTrigger disableButtonEnhancement>
+    <ToolbarButton icon={<ExportRegular />}>Export</ToolbarButton>
+  </MenuTrigger>
+  <MenuPopover>
+    <MenuList>
+      <MenuItem onClick={exportCsv}>Export as CSV</MenuItem>
+      <MenuItem onClick={exportPdf}>Export as PDF</MenuItem>
+    </MenuList>
+  </MenuPopover>
+</Menu>;
+```
+
+## Overflow Handling
+
+v8 `CommandBar` handles overflow automatically via the `overflowItems` array.
+v9 requires the `Overflow` + `OverflowItem` pattern:
+
+```tsx
+import {
+  Toolbar,
+  ToolbarButton,
+  ToolbarDivider,
+  Overflow,
+  OverflowItem,
+  Menu,
+  MenuTrigger,
+  MenuPopover,
+  MenuList,
+  MenuItem,
+  useOverflowMenu,
+  useIsOverflowItemVisible,
+} from '@fluentui/react-components';
+import { AddRegular, EditRegular, DeleteRegular, MoreHorizontalRegular } from '@fluentui/react-icons';
+
+// Overflow menu — shows only items currently hidden by Overflow
+const OverflowMenuItems = () => {
+  const isNew = useIsOverflowItemVisible('new');
+  const isEdit = useIsOverflowItemVisible('edit');
+  const isDelete = useIsOverflowItemVisible('delete');
+  return (
+    <>
+      {!isNew && <MenuItem onClick={handleNew}>New</MenuItem>}
+      {!isEdit && <MenuItem onClick={handleEdit}>Edit</MenuItem>}
+      {!isDelete && <MenuItem disabled>Delete</MenuItem>}
+    </>
+  );
+};
+
+const OverflowMenuButton = () => {
+  const { ref, isOverflowing } = useOverflowMenu<HTMLButtonElement>();
+  if (!isOverflowing) return null;
+  return (
+    <Menu>
+      <MenuTrigger disableButtonEnhancement>
+        <ToolbarButton ref={ref} icon={<MoreHorizontalRegular />} aria-label="More actions" />
+      </MenuTrigger>
+      <MenuPopover>
+        <MenuList>
+          <OverflowMenuItems />
+        </MenuList>
+      </MenuPopover>
+    </Menu>
+  );
+};
+
+function ToolbarWithOverflow() {
+  return (
+    <Overflow>
+      <Toolbar>
+        <OverflowItem id="new">
+          <ToolbarButton icon={<AddRegular />} onClick={handleNew}>
+            New
+          </ToolbarButton>
+        </OverflowItem>
+        <OverflowItem id="edit">
+          <ToolbarButton icon={<EditRegular />} onClick={handleEdit}>
+            Edit
+          </ToolbarButton>
+        </OverflowItem>
+        <OverflowItem id="delete">
+          <ToolbarButton icon={<DeleteRegular />} disabled>
+            Delete
+          </ToolbarButton>
+        </OverflowItem>
+        <OverflowMenuButton />
+      </Toolbar>
+    </Overflow>
+  );
+}
+```
+
+## ICommandBarProps → ToolbarProps
+
+| v8                 | v9                                      | Notes                                                     |
+| ------------------ | --------------------------------------- | --------------------------------------------------------- |
+| `items`            | `children` (`ToolbarButton`, etc.)      | JSX children replace the items array                      |
+| `overflowItems`    | `Overflow` + `OverflowItem` pattern     | See overflow example above                                |
+| `farItems`         | `ToolbarDivider` + `marginLeft: 'auto'` | Push items to the far end with a styled divider or spacer |
+| `buttonAs`         | —                                       | Wrap in `ToolbarButton` directly                          |
+| `overflowButtonAs` | Custom `ToolbarButton` in overflow menu | See overflow example above                                |
+| `className`        | `className`                             |                                                           |
+| `styles`           | `className` + `makeStyles`              |                                                           |
+| `theme`            | `FluentProvider`                        |                                                           |
+
+## ICommandBarItemProps → ToolbarButton Props
+
+| v8 item prop   | v9                                 | Notes                                 |
+| -------------- | ---------------------------------- | ------------------------------------- |
+| `text`         | `children`                         | Move to JSX children                  |
+| `key`          | `key`                              | React key on the JSX element          |
+| `iconProps`    | `icon` slot                        | Pass `<IconComponent />`              |
+| `onClick`      | `onClick`                          |                                       |
+| `disabled`     | `disabled`                         |                                       |
+| `checked`      | `checked` on `ToolbarToggleButton` | Use `ToolbarToggleButton`             |
+| `subMenuProps` | Wrap in `Menu` + `MenuTrigger`     | See subMenu example above             |
+| `split`        | `SplitButton`                      | See button.md for SplitButton pattern |
+| `iconOnly`     | No `children`, add `aria-label`    | Keep `icon` slot, omit text children  |
+| `ariaLabel`    | `aria-label`                       |                                       |
+| `styles`       | `className` + `makeStyles`         |                                       |
diff --git a/skills/fluentui-migrate-v8-to-v9/references/tooltip.md b/skills/fluentui-migrate-v8-to-v9/references/tooltip.md
new file mode 100644
index 0000000000000..30e940411ed9f
--- /dev/null
+++ b/skills/fluentui-migrate-v8-to-v9/references/tooltip.md
@@ -0,0 +1,130 @@
+# Tooltip Migration
+
+## Architecture Change
+
+In v8, `Tooltip` wraps its trigger child and the child does **not** need to be a `forwardRef` component.
+
+In v9, the child of `Tooltip` **is** the trigger and **must** be able to accept a `ref` — meaning it must be either a native DOM element or a component wrapped with `React.forwardRef`. The trigger child automatically receives the necessary ARIA attributes.
+
+## Before / After Example
+
+```tsx
+// v8
+import { Tooltip, DirectionalHint } from '@fluentui/react';
+import { DefaultButton } from '@fluentui/react';
+
+<Tooltip content="This button deletes the item" directionalHint={DirectionalHint.bottomCenter}>
+  <DefaultButton text="Delete" />
+</Tooltip>;
+```
+
+```tsx
+// v9
+import { Tooltip, Button } from '@fluentui/react-components';
+
+<Tooltip content="This button deletes the item" relationship="description" positioning="below">
+  <Button>Delete</Button>
+</Tooltip>;
+```
+
+## `relationship` Prop (required — no v8 equivalent)
+
+The `relationship` prop controls the ARIA semantics of the tooltip:
+
+| `relationship`   | Effect                                          | When to use                                         |
+| ---------------- | ----------------------------------------------- | --------------------------------------------------- |
+| `"description"`  | Adds `aria-describedby` pointing to the tooltip | Tooltip adds context to an already-labelled element |
+| `"label"`        | Adds `aria-labelledby` pointing to the tooltip  | Tooltip IS the accessible name (icon-only buttons)  |
+| `"inaccessible"` | No ARIA wiring                                  | Purely decorative tooltips                          |
+
+**Important:** For icon-only buttons where the tooltip is the accessible name, use `relationship="label"` and remove `aria-label` from the button.
+
+## DirectionalHint → positioning
+
+| v8 `DirectionalHint` | v9 `positioning`  |
+| -------------------- | ----------------- |
+| `topCenter`          | `"above"`         |
+| `topLeftEdge`        | `"above-start"`   |
+| `topRightEdge`       | `"above-end"`     |
+| `topAutoEdge`        | `"above"`         |
+| `bottomCenter`       | `"below"`         |
+| `bottomLeftEdge`     | `"below-start"`   |
+| `bottomRightEdge`    | `"below-end"`     |
+| `bottomAutoEdge`     | `"below"`         |
+| `leftCenter`         | `"before"`        |
+| `leftTopEdge`        | `"before-top"`    |
+| `leftBottomEdge`     | `"before-bottom"` |
+| `rightCenter`        | `"after"`         |
+| `rightTopEdge`       | `"after-top"`     |
+| `rightBottomEdge`    | `"after-bottom"`  |
+
+## Icon-only Button Tooltip
+
+```tsx
+// v8 — title prop or Tooltip wrapping
+import { IconButton } from '@fluentui/react';
+<IconButton iconProps={{ iconName: 'Delete' }} title="Delete item" />;
+
+// v9 — use Tooltip with relationship="label"
+import { Tooltip, Button } from '@fluentui/react-components';
+import { DeleteRegular } from '@fluentui/react-icons';
+
+<Tooltip content="Delete item" relationship="label">
+  <Button icon={<DeleteRegular />} />
+</Tooltip>;
+```
+
+**Do not** add both `aria-label` and `relationship="label"` — that creates duplicate labelling.
+
+## Tooltip on a Custom Component
+
+If wrapping a custom component that does not forward `ref`, use `React.forwardRef`:
+
+```tsx
+// v9 — custom trigger component must forward ref
+const MyTrigger = React.forwardRef<HTMLButtonElement, React.HTMLAttributes<HTMLButtonElement>>((props, ref) => (
+  <button ref={ref} {...props} />
+));
+
+<Tooltip content="Tooltip on custom component" relationship="description">
+  <MyTrigger>Custom trigger</MyTrigger>
+</Tooltip>;
+```
+
+## Controlled Visible State
+
+```tsx
+// v9 — show/hide programmatically
+const [visible, setVisible] = React.useState(false);
+
+<Tooltip
+  content="Programmatic tooltip"
+  relationship="description"
+  visible={visible}
+  onVisibleChange={(_, data) => setVisible(data.visible)}
+>
+  <Button onFocus={() => setVisible(true)} onBlur={() => setVisible(false)}>
+    Focus me
+  </Button>
+</Tooltip>;
+```
+
+## ITooltipProps → TooltipProps
+
+| v8                     | v9                         | Notes                                                 |
+| ---------------------- | -------------------------- | ----------------------------------------------------- |
+| `content`              | `content`                  | ReactNode in both                                     |
+| `directionalHint`      | `positioning`              | See table above                                       |
+| `delay`                | `showDelay` / `hideDelay`  | Separate delays in v9; milliseconds                   |
+| `id`                   | —                          | ID is auto-managed via `relationship` ARIA wiring     |
+| `calloutProps`         | —                          | No direct equivalent; use `positioning` for placement |
+| `hostClassName`        | —                          | Removed                                               |
+| `directionalHintFixed` | —                          | Use `positioning` with an offset                      |
+| `isBeakVisible`        | `withArrow`                | `withArrow={true}` shows the arrow                    |
+| `beakWidth`            | —                          | Removed                                               |
+| `onRenderContent`      | `content` slot             | Pass ReactNode to `content`                           |
+| `styles`               | `className` + `makeStyles` |                                                       |
+| `theme`                | `FluentProvider`           |                                                       |
+| —                      | `relationship`             | **Required** — controls ARIA semantics                |
+| —                      | `visible`                  | New — controlled visibility                           |
+| —                      | `onVisibleChange`          | New — `(ev, data) => data.visible`                    |

From e1af8a99a1315d7df8dfadd848a45f58c9c6383f Mon Sep 17 00:00:00 2001
From: Martin Hochel <martinhochel@microsoft.com>
Date: Wed, 4 Mar 2026 09:40:57 +0100
Subject: [PATCH 04/14] feat(cli): bootstrap fluentui-cli (#35829)

---
 tools/cli/.swcrc              | 29 +++++++++++++++++++++++++++++
 tools/cli/README.md           | 11 +++++++++++
 tools/cli/bin/fluentui-cli.js |  5 +++++
 tools/cli/eslint.config.cjs   |  5 +++++
 tools/cli/jest.config.ts      | 29 +++++++++++++++++++++++++++++
 tools/cli/package.json        | 19 +++++++++++++++++++
 tools/cli/project.json        | 18 ++++++++++++++++++
 tools/cli/src/index.ts        |  1 +
 tools/cli/tsconfig.json       | 17 +++++++++++++++++
 tools/cli/tsconfig.lib.json   | 12 ++++++++++++
 tools/cli/tsconfig.spec.json  |  9 +++++++++
 tsconfig.base.all.json        |  1 +
 tsconfig.base.json            |  1 +
 13 files changed, 157 insertions(+)
 create mode 100644 tools/cli/.swcrc
 create mode 100644 tools/cli/README.md
 create mode 100755 tools/cli/bin/fluentui-cli.js
 create mode 100644 tools/cli/eslint.config.cjs
 create mode 100644 tools/cli/jest.config.ts
 create mode 100644 tools/cli/package.json
 create mode 100644 tools/cli/project.json
 create mode 100644 tools/cli/src/index.ts
 create mode 100644 tools/cli/tsconfig.json
 create mode 100644 tools/cli/tsconfig.lib.json
 create mode 100644 tools/cli/tsconfig.spec.json

diff --git a/tools/cli/.swcrc b/tools/cli/.swcrc
new file mode 100644
index 0000000000000..25741bb92261e
--- /dev/null
+++ b/tools/cli/.swcrc
@@ -0,0 +1,29 @@
+{
+  "jsc": {
+    "target": "es2020",
+    "parser": {
+      "syntax": "typescript",
+      "decorators": true,
+      "dynamicImport": true
+    },
+    "transform": {
+      "decoratorMetadata": true,
+      "legacyDecorator": true
+    },
+    "keepClassNames": true,
+    "externalHelpers": true,
+    "loose": true
+  },
+  "module": {
+    "type": "commonjs"
+  },
+  "sourceMaps": true,
+  "exclude": [
+    "jest.config.ts",
+    ".*\\.spec.tsx?$",
+    ".*\\.test.tsx?$",
+    "./src/jest-setup.ts$",
+    "./**/jest-setup.ts$",
+    ".*.js$"
+  ]
+}
diff --git a/tools/cli/README.md b/tools/cli/README.md
new file mode 100644
index 0000000000000..f7abc84a489a8
--- /dev/null
+++ b/tools/cli/README.md
@@ -0,0 +1,11 @@
+# cli
+
+This library was generated with [Nx](https://nx.dev).
+
+## Building
+
+Run `nx build cli` to build the library.
+
+## Running unit tests
+
+Run `nx test cli` to execute the unit tests via [Jest](https://jestjs.io).
diff --git a/tools/cli/bin/fluentui-cli.js b/tools/cli/bin/fluentui-cli.js
new file mode 100755
index 0000000000000..40750eb7f9095
--- /dev/null
+++ b/tools/cli/bin/fluentui-cli.js
@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+// @ts-check
+
+console.log('TODO');
diff --git a/tools/cli/eslint.config.cjs b/tools/cli/eslint.config.cjs
new file mode 100644
index 0000000000000..827203cf8f59b
--- /dev/null
+++ b/tools/cli/eslint.config.cjs
@@ -0,0 +1,5 @@
+// @ts-check
+const fluentPlugin = require('@fluentui/eslint-plugin');
+
+/** @type {import("eslint").Linter.Config[]} */
+module.exports = [...fluentPlugin.configs['flat/node']];
diff --git a/tools/cli/jest.config.ts b/tools/cli/jest.config.ts
new file mode 100644
index 0000000000000..2fd082c49cfac
--- /dev/null
+++ b/tools/cli/jest.config.ts
@@ -0,0 +1,29 @@
+/* eslint-disable */
+import { readFileSync } from 'node:fs';
+const { join } = require('node:path');
+
+// Reading the SWC compilation config and remove the "exclude"
+// for the test files to be compiled by SWC
+const { exclude: _, ...swcJestConfig } = JSON.parse(readFileSync(join(__dirname, '.swcrc'), 'utf-8'));
+
+// disable .swcrc look-up by SWC core because we're passing in swcJestConfig ourselves.
+// If we do not disable this, SWC Core will read .swcrc and won't transform our test files due to "exclude"
+if (swcJestConfig.swcrc === undefined) {
+  swcJestConfig.swcrc = false;
+}
+
+// Uncomment if using global setup/teardown files being transformed via swc
+// https://nx.dev/nx-api/jest/documents/overview#global-setupteardown-with-nx-libraries
+// jest needs EsModule Interop to find the default exported setup/teardown functions
+// swcJestConfig.module.noInterop = false;
+
+export default {
+  displayName: 'cli',
+  preset: '../../jest.preset.js',
+  transform: {
+    '^.+\\.tsx?$': ['@swc/jest', swcJestConfig],
+  },
+  moduleFileExtensions: ['ts', 'tsx', 'js'],
+  testEnvironment: 'node',
+  coverageDirectory: '../../coverage/tools/cli',
+};
diff --git a/tools/cli/package.json b/tools/cli/package.json
new file mode 100644
index 0000000000000..25f42c751158a
--- /dev/null
+++ b/tools/cli/package.json
@@ -0,0 +1,19 @@
+{
+  "name": "@fluentui/cli",
+  "version": "0.0.1",
+  "private": true,
+  "type": "commonjs",
+  "main": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "bin": {
+    "fluentui-cli": "./bin/fluentui-cli.js"
+  },
+  "files": [
+    "*.md",
+    "bin",
+    "dist"
+  ],
+  "dependencies": {
+    "@swc/helpers": "^0.5.1"
+  }
+}
diff --git a/tools/cli/project.json b/tools/cli/project.json
new file mode 100644
index 0000000000000..3e021154c0977
--- /dev/null
+++ b/tools/cli/project.json
@@ -0,0 +1,18 @@
+{
+  "name": "cli",
+  "$schema": "../../node_modules/nx/schemas/project-schema.json",
+  "sourceRoot": "tools/cli/src",
+  "projectType": "library",
+  "tags": ["platform:node", "tools"],
+  "targets": {
+    "build": {
+      "executor": "@nx/js:swc",
+      "outputs": ["{options.outputPath}"],
+      "options": {
+        "outputPath": "{projectRoot}/dist",
+        "main": "tools/cli/src/index.ts",
+        "tsConfig": "tools/cli/tsconfig.lib.json"
+      }
+    }
+  }
+}
diff --git a/tools/cli/src/index.ts b/tools/cli/src/index.ts
new file mode 100644
index 0000000000000..cb0ff5c3b541f
--- /dev/null
+++ b/tools/cli/src/index.ts
@@ -0,0 +1 @@
+export {};
diff --git a/tools/cli/tsconfig.json b/tools/cli/tsconfig.json
new file mode 100644
index 0000000000000..d3a3c0beff34c
--- /dev/null
+++ b/tools/cli/tsconfig.json
@@ -0,0 +1,17 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "module": "commonjs",
+    "noEmit": true
+  },
+  "files": [],
+  "include": [],
+  "references": [
+    {
+      "path": "./tsconfig.lib.json"
+    },
+    {
+      "path": "./tsconfig.spec.json"
+    }
+  ]
+}
diff --git a/tools/cli/tsconfig.lib.json b/tools/cli/tsconfig.lib.json
new file mode 100644
index 0000000000000..6b3ebc893a00e
--- /dev/null
+++ b/tools/cli/tsconfig.lib.json
@@ -0,0 +1,12 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "module": "CommonJS",
+    "noEmit": false,
+    "outDir": "../../dist/out-tsc",
+    "declaration": true,
+    "types": ["node"]
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["jest.config.ts", "src/**/*.spec.ts", "src/**/*.test.ts"]
+}
diff --git a/tools/cli/tsconfig.spec.json b/tools/cli/tsconfig.spec.json
new file mode 100644
index 0000000000000..f6d8ffcc9fb9b
--- /dev/null
+++ b/tools/cli/tsconfig.spec.json
@@ -0,0 +1,9 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "outDir": "../../dist/out-tsc",
+    "module": "commonjs",
+    "types": ["jest", "node"]
+  },
+  "include": ["jest.config.ts", "src/**/*.test.ts", "src/**/*.spec.ts", "src/**/*.d.ts"]
+}
diff --git a/tsconfig.base.all.json b/tsconfig.base.all.json
index 9b9756df7a1a0..f69fe88089e0a 100644
--- a/tsconfig.base.all.json
+++ b/tsconfig.base.all.json
@@ -62,6 +62,7 @@
       "@fluentui/babel-preset-storybook-full-source": [
         "packages/react-components/babel-preset-storybook-full-source/src/index.ts"
       ],
+      "@fluentui/cli": ["tools/cli/src/index.ts"],
       "@fluentui/component-selector-preview": [
         "packages/react-components/component-selector-preview/library/src/index.ts"
       ],
diff --git a/tsconfig.base.json b/tsconfig.base.json
index ded6aaaa1f252..de2c195b01cea 100644
--- a/tsconfig.base.json
+++ b/tsconfig.base.json
@@ -17,6 +17,7 @@
         "packages/react-components/babel-preset-storybook-full-source/src/index.ts"
       ],
       "@fluentui/chart-utilities": ["packages/charts/chart-utilities/src/index.ts"],
+      "@fluentui/cli": ["tools/cli/src/index.ts"],
       "@fluentui/component-selector-preview": [
         "packages/react-components/component-selector-preview/library/src/index.ts"
       ],

From 15f612022015f7848b6e3e30bc2e860b0b759f3e Mon Sep 17 00:00:00 2001
From: Martin Hochel <martinhochel@microsoft.com>
Date: Wed, 4 Mar 2026 13:21:19 +0100
Subject: [PATCH 05/14] feat(fluentui-cli): bootstrap commands infra (#35830)

---
 .github/skills/fluentui-cli/SKILL.md          | 116 +++++++++++++++
 .../references/adding-commands.md             | 135 ++++++++++++++++++
 tools/cli/bin/fluentui-cli.js                 |   4 +-
 tools/cli/package.json                        |   6 +-
 tools/cli/src/cli.ts                          |  25 ++++
 .../cli/src/commands/migrate/handler.spec.ts  |  19 +++
 tools/cli/src/commands/migrate/handler.ts     |   6 +
 tools/cli/src/commands/migrate/index.ts       |  13 ++
 tools/cli/src/commands/report/handler.spec.ts |  19 +++
 tools/cli/src/commands/report/handler.ts      |   6 +
 tools/cli/src/commands/report/index.ts        |  13 ++
 tools/cli/src/utils/index.ts                  |   1 +
 tools/cli/src/utils/types.ts                  |   6 +
 tools/workspace-plugin/generators.json        |   5 +
 .../src/generators/cli-command/README.md      |  52 +++++++
 .../cli-command/files/handler.spec.ts__tmpl__ |  19 +++
 .../cli-command/files/handler.ts__tmpl__      |   6 +
 .../cli-command/files/index.ts__tmpl__        |  16 +++
 .../generators/cli-command/generator.spec.ts  | 106 ++++++++++++++
 .../src/generators/cli-command/generator.ts   |  82 +++++++++++
 .../src/generators/cli-command/schema.json    |  29 ++++
 .../src/generators/cli-command/schema.ts      |  15 ++
 22 files changed, 697 insertions(+), 2 deletions(-)
 create mode 100644 .github/skills/fluentui-cli/SKILL.md
 create mode 100644 .github/skills/fluentui-cli/references/adding-commands.md
 create mode 100644 tools/cli/src/cli.ts
 create mode 100644 tools/cli/src/commands/migrate/handler.spec.ts
 create mode 100644 tools/cli/src/commands/migrate/handler.ts
 create mode 100644 tools/cli/src/commands/migrate/index.ts
 create mode 100644 tools/cli/src/commands/report/handler.spec.ts
 create mode 100644 tools/cli/src/commands/report/handler.ts
 create mode 100644 tools/cli/src/commands/report/index.ts
 create mode 100644 tools/cli/src/utils/index.ts
 create mode 100644 tools/cli/src/utils/types.ts
 create mode 100644 tools/workspace-plugin/src/generators/cli-command/README.md
 create mode 100644 tools/workspace-plugin/src/generators/cli-command/files/handler.spec.ts__tmpl__
 create mode 100644 tools/workspace-plugin/src/generators/cli-command/files/handler.ts__tmpl__
 create mode 100644 tools/workspace-plugin/src/generators/cli-command/files/index.ts__tmpl__
 create mode 100644 tools/workspace-plugin/src/generators/cli-command/generator.spec.ts
 create mode 100644 tools/workspace-plugin/src/generators/cli-command/generator.ts
 create mode 100644 tools/workspace-plugin/src/generators/cli-command/schema.json
 create mode 100644 tools/workspace-plugin/src/generators/cli-command/schema.ts

diff --git a/.github/skills/fluentui-cli/SKILL.md b/.github/skills/fluentui-cli/SKILL.md
new file mode 100644
index 0000000000000..a5e52373e8976
--- /dev/null
+++ b/.github/skills/fluentui-cli/SKILL.md
@@ -0,0 +1,116 @@
+---
+name: fluentui-cli
+description: 'Guides working with @fluentui/cli — the internal Fluent UI command-line tool. Use when asked to add a new CLI command, modify an existing command, understand CLI architecture, debug CLI issues, or work with the CLI build/test workflow. Covers: architecture overview, yargs conventions, lazy-loading pattern, testing, and available Nx generators.'
+---
+
+# `@fluentui/cli`
+
+The `@fluentui/cli` package (`tools/cli/`) is the internal Fluent UI command-line tool built with **yargs**. It uses a modular, lazy-loading architecture where each command lives in its own directory and is only loaded at runtime when invoked.
+
+## Architecture
+
+### File Structure
+
+```
+tools/cli/
+├── bin/fluentui-cli.js              # Node entry point (requires compiled output)
+├── src/
+│   ├── cli.ts                       # Main yargs setup, registers all commands
+│   ├── index.ts                     # Public API re-exports
+│   ├── utils/
+│   │   ├── index.ts                 # Barrel exports
+│   │   └── types.ts                 # Shared CommandHandler type
+│   └── commands/
+│       ├── migrate/                 # Command module
+│       │   ├── index.ts             # CommandModule definition (eagerly loaded)
+│       │   ├── handler.ts           # Handler implementation (lazy-loaded)
+│       │   └── handler.spec.ts      # Tests
+│       └── report/                  # Command module
+│           ├── index.ts
+│           ├── handler.ts
+│           └── handler.spec.ts
+```
+
+### Lazy Loading Pattern
+
+Command definitions (name, description, options builder) are eagerly imported — they are lightweight. The actual handler logic is **lazy-loaded via dynamic `import()`** only when the command is invoked:
+
+```typescript
+// index.ts — always loaded (lightweight)
+handler: async argv => {
+  // handler.ts only loaded when this specific command runs
+  const { handler } = await import('./handler');
+  return handler(argv);
+},
+```
+
+This means running `fluentui-cli migrate` will never load the code for `report` or any other command.
+
+### CommandHandler Type
+
+All handlers use the shared `CommandHandler<T>` type from `src/utils/types.ts`:
+
+```typescript
+import type { ArgumentsCamelCase } from 'yargs';
+
+export type CommandHandler<T = {}> = (argv: ArgumentsCamelCase<T>) => Promise<void>;
+```
+
+### Command Registration in cli.ts
+
+Each command is imported and registered in `tools/cli/src/cli.ts`:
+
+```typescript
+import yargs from 'yargs';
+import migrateCommand from './commands/migrate';
+import reportCommand from './commands/report';
+
+export async function main(argv: string[]): Promise<void> {
+  await yargs(argv)
+    .scriptName('fluentui-cli')
+    .usage('$0 <command> [options]')
+    .command(migrateCommand)
+    .command(reportCommand)
+    .demandCommand(1, 'You need to specify a command to run.')
+    .help()
+    .strict()
+    .parse();
+}
+```
+
+## Build & Test
+
+```sh
+# Build the CLI
+yarn nx run cli:build
+
+# Run tests
+yarn nx run cli:test
+
+# Test --help output
+node tools/cli/bin/fluentui-cli.js --help
+node tools/cli/bin/fluentui-cli.js <command-name> --help
+```
+
+## Conventions
+
+- **Always use the Nx generator** to scaffold new commands — do not create command files manually. See the [adding commands](references/adding-commands.md) reference.
+- Place shared utilities in `tools/cli/src/utils/` and export through the barrel file.
+- Every command must support `--help` (handled by yargs `.help()` in the builder).
+- Handler files must export a named `handler` constant typed with `CommandHandler<T>`.
+- Tests live adjacent to handlers as `handler.spec.ts`.
+
+## Common Patterns
+
+### Subcommands (nested commands)
+
+If a command needs subcommands, use yargs nested command pattern in the builder:
+
+```typescript
+builder: yargs =>
+  yargs
+    .command('run', 'Run migrations', subBuilder => subBuilder, subHandler)
+    .command('list', 'List available migrations', subBuilder => subBuilder, subHandler)
+    .demandCommand(1)
+    .help(),
+```
diff --git a/.github/skills/fluentui-cli/references/adding-commands.md b/.github/skills/fluentui-cli/references/adding-commands.md
new file mode 100644
index 0000000000000..ab6f3aac928c1
--- /dev/null
+++ b/.github/skills/fluentui-cli/references/adding-commands.md
@@ -0,0 +1,135 @@
+# Adding a New CLI Command
+
+## Step 1 — Scaffold the Command
+
+Run the `cli-command` Nx generator:
+
+```sh
+yarn nx g @fluentui/workspace-plugin:cli-command <command-name> --description "<short description>"
+```
+
+### Example
+
+```sh
+yarn nx g @fluentui/workspace-plugin:cli-command analyze --description "Analyze bundle sizes"
+```
+
+### What Gets Generated
+
+```
+tools/cli/src/commands/<command-name>/
+├── index.ts          # Yargs CommandModule definition (lightweight, eagerly loaded)
+├── handler.ts        # Handler implementation (lazy-loaded via dynamic import)
+└── handler.spec.ts   # Jest unit tests for the handler
+```
+
+The generator also **automatically registers** the new command in `tools/cli/src/cli.ts` by:
+
+1. Adding an import statement for the command module
+2. Adding a `.command()` registration call
+
+Preview what will be generated without writing to disk:
+
+```sh
+yarn nx g @fluentui/workspace-plugin:cli-command <command-name> --dry-run
+```
+
+## Step 2 — Implement the Handler
+
+Open `tools/cli/src/commands/<command-name>/handler.ts` and implement the command logic:
+
+```typescript
+import type { CommandHandler } from '../../utils/types';
+
+// Define the shape of your command's arguments
+interface AnalyzeArgs {
+  project?: string;
+  verbose?: boolean;
+}
+
+export const handler: CommandHandler<AnalyzeArgs> = async argv => {
+  const { project, verbose } = argv;
+
+  // Your implementation here
+  console.log(`Analyzing${project ? ` project: ${project}` : ''}...`);
+};
+```
+
+## Step 3 — Add Options and Arguments
+
+Edit `tools/cli/src/commands/<command-name>/index.ts` to add yargs options in the `builder`:
+
+```typescript
+import type { CommandModule } from 'yargs';
+
+const command: CommandModule = {
+  command: 'analyze',
+  describe: 'Analyze bundle sizes',
+  builder: yargs =>
+    yargs
+      .option('project', {
+        alias: 'p',
+        type: 'string',
+        describe: 'Project name to analyze',
+      })
+      .option('verbose', {
+        type: 'boolean',
+        default: false,
+        describe: 'Show detailed output',
+      })
+      .version(false)
+      .help(),
+  handler: async argv => {
+    const { handler } = await import('./handler');
+    return handler(argv);
+  },
+};
+
+export default command;
+```
+
+## Step 4 — Write Tests
+
+Update `tools/cli/src/commands/<command-name>/handler.spec.ts` with meaningful tests:
+
+```typescript
+import { handler } from './handler';
+
+describe('analyze handler', () => {
+  let logSpy: jest.SpyInstance;
+
+  beforeEach(() => {
+    logSpy = jest.spyOn(console, 'log').mockImplementation();
+  });
+
+  afterEach(() => {
+    logSpy.mockRestore();
+  });
+
+  it('should analyze all projects when no project specified', async () => {
+    await handler({ _: ['analyze'], $0: 'fluentui-cli' });
+
+    expect(logSpy).toHaveBeenCalledWith('Analyzing...');
+  });
+
+  it('should analyze specific project when specified', async () => {
+    await handler({ _: ['analyze'], $0: 'fluentui-cli', project: 'react-button' });
+
+    expect(logSpy).toHaveBeenCalledWith('Analyzing project: react-button...');
+  });
+});
+```
+
+## Step 5 — Verify
+
+```sh
+# Build the CLI
+yarn nx run cli:build
+
+# Run tests
+yarn nx run cli:test
+
+# Test --help output
+node tools/cli/bin/fluentui-cli.js --help
+node tools/cli/bin/fluentui-cli.js <command-name> --help
+```
diff --git a/tools/cli/bin/fluentui-cli.js b/tools/cli/bin/fluentui-cli.js
index 40750eb7f9095..e7b64bac11d43 100755
--- a/tools/cli/bin/fluentui-cli.js
+++ b/tools/cli/bin/fluentui-cli.js
@@ -2,4 +2,6 @@
 
 // @ts-check
 
-console.log('TODO');
+const { main } = require('../dist/src/cli');
+
+main(process.argv.slice(2));
diff --git a/tools/cli/package.json b/tools/cli/package.json
index 25f42c751158a..231942bd7dc51 100644
--- a/tools/cli/package.json
+++ b/tools/cli/package.json
@@ -14,6 +14,10 @@
     "dist"
   ],
   "dependencies": {
-    "@swc/helpers": "^0.5.1"
+    "@swc/helpers": "^0.5.1",
+    "yargs": "^17.7.2"
+  },
+  "devDependencies": {
+    "@types/yargs": "^17.0.33"
   }
 }
diff --git a/tools/cli/src/cli.ts b/tools/cli/src/cli.ts
new file mode 100644
index 0000000000000..ac1bd84cf977d
--- /dev/null
+++ b/tools/cli/src/cli.ts
@@ -0,0 +1,25 @@
+import yargs from 'yargs';
+
+import migrateCommand from './commands/migrate';
+import reportCommand from './commands/report';
+
+export async function main(argv: string[]): Promise<void> {
+  await yargs(argv)
+    .scriptName('fluentui-cli')
+    .usage('$0 <command> [options]')
+    .command(migrateCommand)
+    .command(reportCommand)
+    .demandCommand(1, 'You need to specify a command to run.')
+    .help()
+    .strict()
+    .fail((message, error, yargsInstance) => {
+      if (error) {
+        console.error(error.message);
+      } else if (message) {
+        yargsInstance.showHelp();
+        console.error(`\n${message}`);
+      }
+      process.exit(1);
+    })
+    .parse();
+}
diff --git a/tools/cli/src/commands/migrate/handler.spec.ts b/tools/cli/src/commands/migrate/handler.spec.ts
new file mode 100644
index 0000000000000..5c35abdf7eba1
--- /dev/null
+++ b/tools/cli/src/commands/migrate/handler.spec.ts
@@ -0,0 +1,19 @@
+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
new file mode 100644
index 0000000000000..0b029904dd985
--- /dev/null
+++ b/tools/cli/src/commands/migrate/handler.ts
@@ -0,0 +1,6 @@
+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
new file mode 100644
index 0000000000000..06f593b8af6f2
--- /dev/null
+++ b/tools/cli/src/commands/migrate/index.ts
@@ -0,0 +1,13 @@
+import type { CommandModule } from 'yargs';
+
+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);
+  },
+};
+
+export default command;
diff --git a/tools/cli/src/commands/report/handler.spec.ts b/tools/cli/src/commands/report/handler.spec.ts
new file mode 100644
index 0000000000000..8a1f84a0ac420
--- /dev/null
+++ b/tools/cli/src/commands/report/handler.spec.ts
@@ -0,0 +1,19 @@
+import { handler } from './handler';
+
+describe('report handler', () => {
+  let logSpy: jest.SpyInstance;
+
+  beforeEach(() => {
+    logSpy = jest.spyOn(console, 'log').mockImplementation();
+  });
+
+  afterEach(() => {
+    logSpy.mockRestore();
+  });
+
+  it('should execute without errors', async () => {
+    await handler({ _: ['report'], $0: 'fluentui-cli' });
+
+    expect(logSpy).toHaveBeenCalledWith('report command - not yet implemented');
+  });
+});
diff --git a/tools/cli/src/commands/report/handler.ts b/tools/cli/src/commands/report/handler.ts
new file mode 100644
index 0000000000000..04d6841efdb8e
--- /dev/null
+++ b/tools/cli/src/commands/report/handler.ts
@@ -0,0 +1,6 @@
+import type { CommandHandler } from '../../utils/types';
+
+export const handler: CommandHandler = async argv => {
+  // TODO: Implement report command
+  console.log('report command - not yet implemented');
+};
diff --git a/tools/cli/src/commands/report/index.ts b/tools/cli/src/commands/report/index.ts
new file mode 100644
index 0000000000000..2724afd935957
--- /dev/null
+++ b/tools/cli/src/commands/report/index.ts
@@ -0,0 +1,13 @@
+import type { CommandModule } from 'yargs';
+
+const command: CommandModule = {
+  command: 'report',
+  describe: 'Generate reports',
+  builder: yargs => yargs.version(false).help(),
+  handler: async argv => {
+    const { handler } = await import('./handler');
+    return handler(argv);
+  },
+};
+
+export default command;
diff --git a/tools/cli/src/utils/index.ts b/tools/cli/src/utils/index.ts
new file mode 100644
index 0000000000000..75a69b03e2e20
--- /dev/null
+++ b/tools/cli/src/utils/index.ts
@@ -0,0 +1 @@
+export type { CommandHandler } from './types';
diff --git a/tools/cli/src/utils/types.ts b/tools/cli/src/utils/types.ts
new file mode 100644
index 0000000000000..9843d04eb21a1
--- /dev/null
+++ b/tools/cli/src/utils/types.ts
@@ -0,0 +1,6 @@
+import type { ArgumentsCamelCase } from 'yargs';
+
+/**
+ * A command handler function that receives parsed CLI arguments.
+ */
+export type CommandHandler<T = {}> = (argv: ArgumentsCamelCase<T>) => Promise<void>;
diff --git a/tools/workspace-plugin/generators.json b/tools/workspace-plugin/generators.json
index 3a882f4f0b422..f660434ee7803 100644
--- a/tools/workspace-plugin/generators.json
+++ b/tools/workspace-plugin/generators.json
@@ -96,6 +96,11 @@
       "schema": "./src/generators/epic-generator/schema.json",
       "description": "DEPRECATED: Create a migration tracker issue epic and subsequent team sub-issues on GitHub for React v9",
       "hidden": true
+    },
+    "cli-command": {
+      "implementation": "./src/generators/cli-command/generator",
+      "schema": "./src/generators/cli-command/schema.json",
+      "description": "Create a new CLI command for @fluentui/cli"
     }
   }
 }
diff --git a/tools/workspace-plugin/src/generators/cli-command/README.md b/tools/workspace-plugin/src/generators/cli-command/README.md
new file mode 100644
index 0000000000000..d612d7eceb2d5
--- /dev/null
+++ b/tools/workspace-plugin/src/generators/cli-command/README.md
@@ -0,0 +1,52 @@
+# cli-command
+
+Workspace generator that scaffolds a new CLI command for the `@fluentui/cli` package.
+
+## Usage
+
+```sh
+yarn nx g @fluentui/workspace-plugin:cli-command <name>
+```
+
+Show what will be generated without writing to disk:
+
+```sh
+yarn nx g @fluentui/workspace-plugin:cli-command <name> --dry-run
+```
+
+### Examples
+
+```sh
+yarn nx g @fluentui/workspace-plugin:cli-command analyze --description "Analyze bundle sizes"
+```
+
+This generates:
+
+```
+tools/cli/src/commands/analyze/
+├── index.ts          # CommandModule with lazy-loaded handler
+├── handler.ts        # Handler implementation
+└── handler.spec.ts   # Handler tests
+```
+
+And registers the command in `tools/cli/src/cli.ts`.
+
+## Options
+
+#### `name`
+
+Type: `string` (required)
+
+The command name (e.g., `migrate`, `report`, `analyze`). Must start with a lowercase letter and contain only lowercase letters, numbers, and hyphens.
+
+#### `description`
+
+Type: `string`
+
+Short description shown in `--help` output. Defaults to `"TODO: Add description"`.
+
+#### `skipFormat`
+
+Type: `boolean` (default: `false`)
+
+Skip formatting files after generation.
diff --git a/tools/workspace-plugin/src/generators/cli-command/files/handler.spec.ts__tmpl__ b/tools/workspace-plugin/src/generators/cli-command/files/handler.spec.ts__tmpl__
new file mode 100644
index 0000000000000..8b5b20d580c1d
--- /dev/null
+++ b/tools/workspace-plugin/src/generators/cli-command/files/handler.spec.ts__tmpl__
@@ -0,0 +1,19 @@
+import { handler } from './handler';
+
+describe('<%= name %> handler', () => {
+  let logSpy: jest.SpyInstance;
+
+  beforeEach(() => {
+    logSpy = jest.spyOn(console, 'log').mockImplementation();
+  });
+
+  afterEach(() => {
+    logSpy.mockRestore();
+  });
+
+  it('should execute without errors', async () => {
+    await handler({ _: ['<%= name %>'], $0: 'fluentui-cli' });
+
+    expect(logSpy).toHaveBeenCalledWith('<%= name %> command - not yet implemented');
+  });
+});
diff --git a/tools/workspace-plugin/src/generators/cli-command/files/handler.ts__tmpl__ b/tools/workspace-plugin/src/generators/cli-command/files/handler.ts__tmpl__
new file mode 100644
index 0000000000000..7d6ac1ca3cef4
--- /dev/null
+++ b/tools/workspace-plugin/src/generators/cli-command/files/handler.ts__tmpl__
@@ -0,0 +1,6 @@
+import type { CommandHandler } from '../../utils/types';
+
+export const handler: CommandHandler = async argv => {
+  // TODO: Implement <%= name %> command
+  console.log('<%= name %> command - not yet implemented');
+};
diff --git a/tools/workspace-plugin/src/generators/cli-command/files/index.ts__tmpl__ b/tools/workspace-plugin/src/generators/cli-command/files/index.ts__tmpl__
new file mode 100644
index 0000000000000..48050869ee0d9
--- /dev/null
+++ b/tools/workspace-plugin/src/generators/cli-command/files/index.ts__tmpl__
@@ -0,0 +1,16 @@
+import type { CommandModule } from 'yargs';
+
+const command: CommandModule = {
+  command: '<%= name %>',
+  describe: '<%= description %>',
+  builder: yargs =>
+    yargs
+      .version(false)
+      .help(),
+  handler: async argv => {
+    const { handler } = await import('./handler');
+    return handler(argv);
+  },
+};
+
+export default command;
diff --git a/tools/workspace-plugin/src/generators/cli-command/generator.spec.ts b/tools/workspace-plugin/src/generators/cli-command/generator.spec.ts
new file mode 100644
index 0000000000000..ef4790e2047f3
--- /dev/null
+++ b/tools/workspace-plugin/src/generators/cli-command/generator.spec.ts
@@ -0,0 +1,106 @@
+import { createTreeWithEmptyWorkspace } from '@nx/devkit/testing';
+import { Tree } from '@nx/devkit';
+
+import generator from './generator';
+import { CliCommandGeneratorSchema } from './schema';
+
+describe('cli-command generator', () => {
+  let tree: Tree;
+
+  beforeEach(() => {
+    tree = createTreeWithEmptyWorkspace();
+
+    // Seed the tree with a minimal cli.ts that the generator will modify
+    tree.write(
+      'tools/cli/src/cli.ts',
+      [
+        "import yargs from 'yargs';",
+        '',
+        'export async function main(argv: string[]): Promise<void> {',
+        '  await yargs(argv)',
+        "    .scriptName('fluentui-cli')",
+        "    .usage('$0 <command> [options]')",
+        "    .demandCommand(1, 'You need to specify a command to run.')",
+        '    .help()',
+        '    .strict()',
+        '    .parse();',
+        '}',
+        '',
+      ].join('\n'),
+    );
+  });
+
+  it('should generate command files', async () => {
+    const options: CliCommandGeneratorSchema = { name: 'analyze', description: 'Analyze bundles' };
+    await generator(tree, options);
+
+    expect(tree.exists('tools/cli/src/commands/analyze/index.ts')).toBeTruthy();
+    expect(tree.exists('tools/cli/src/commands/analyze/handler.ts')).toBeTruthy();
+    expect(tree.exists('tools/cli/src/commands/analyze/handler.spec.ts')).toBeTruthy();
+  });
+
+  it('should generate CommandModule with correct name and description', async () => {
+    const options: CliCommandGeneratorSchema = { name: 'analyze', description: 'Analyze bundles' };
+    await generator(tree, options);
+
+    const content = tree.read('tools/cli/src/commands/analyze/index.ts', 'utf-8')!;
+
+    expect(content).toContain("command: 'analyze'");
+    expect(content).toContain("describe: 'Analyze bundles'");
+    expect(content).toContain("await import('./handler')");
+  });
+
+  it('should generate handler with placeholder implementation', async () => {
+    const options: CliCommandGeneratorSchema = { name: 'analyze', description: 'Analyze bundles' };
+    await generator(tree, options);
+
+    const content = tree.read('tools/cli/src/commands/analyze/handler.ts', 'utf-8')!;
+
+    expect(content).toContain('TODO: Implement analyze command');
+    expect(content).toContain("import type { CommandHandler } from '../../utils/types'");
+  });
+
+  it('should register command in cli.ts', async () => {
+    const options: CliCommandGeneratorSchema = { name: 'analyze', description: 'Analyze bundles' };
+    await generator(tree, options);
+
+    const content = tree.read('tools/cli/src/cli.ts', 'utf-8')!;
+
+    expect(content).toContain("import analyzeCommand from './commands/analyze'");
+    expect(content).toContain('.command(analyzeCommand)');
+  });
+
+  it('should use default description when not provided', async () => {
+    const options: CliCommandGeneratorSchema = { name: 'analyze' };
+    await generator(tree, options);
+
+    const content = tree.read('tools/cli/src/commands/analyze/index.ts', 'utf-8')!;
+
+    expect(content).toContain("describe: 'TODO: Add description'");
+  });
+
+  it('should throw when command already exists', async () => {
+    tree.write('tools/cli/src/commands/analyze/index.ts', 'export default {}');
+
+    await expect(generator(tree, { name: 'analyze' })).rejects.toThrow('Command "analyze" already exists');
+  });
+
+  it('should throw when name is empty', async () => {
+    await expect(generator(tree, { name: '' })).rejects.toThrow('name is required');
+  });
+
+  it('should not duplicate registration if command import already exists', async () => {
+    await generator(tree, { name: 'analyze' });
+    // Manually remove the generated files so we can re-run (simulating re-registration)
+    tree.delete('tools/cli/src/commands/analyze/index.ts');
+    tree.delete('tools/cli/src/commands/analyze/handler.ts');
+    tree.delete('tools/cli/src/commands/analyze/handler.spec.ts');
+
+    await generator(tree, { name: 'analyze' });
+
+    const content = tree.read('tools/cli/src/cli.ts', 'utf-8')!;
+    const importMatches = content.match(/import analyzeCommand/g);
+
+    expect(importMatches).toHaveLength(1);
+  });
+});
diff --git a/tools/workspace-plugin/src/generators/cli-command/generator.ts b/tools/workspace-plugin/src/generators/cli-command/generator.ts
new file mode 100644
index 0000000000000..0c6d6a3309370
--- /dev/null
+++ b/tools/workspace-plugin/src/generators/cli-command/generator.ts
@@ -0,0 +1,82 @@
+import path from 'path';
+import { Tree, formatFiles, names, generateFiles } from '@nx/devkit';
+
+import { CliCommandGeneratorSchema } from './schema';
+
+interface NormalizedSchema extends ReturnType<typeof normalizeOptions> {}
+
+const CLI_PROJECT_ROOT = 'tools/cli';
+const COMMANDS_DIR = 'src/commands';
+
+export default async function (tree: Tree, schema: CliCommandGeneratorSchema) {
+  const options = normalizeOptions(schema);
+
+  assertCommandDoesNotExist(tree, options);
+
+  addFiles(tree, options);
+  registerCommand(tree, options);
+
+  if (!options.skipFormat) {
+    await formatFiles(tree);
+  }
+}
+
+function normalizeOptions(options: CliCommandGeneratorSchema) {
+  if (!options.name || options.name.length === 0) {
+    throw new Error('name is required');
+  }
+
+  return {
+    ...options,
+    ...names(options.name),
+    description: options.description ?? 'TODO: Add description',
+    skipFormat: options.skipFormat ?? false,
+    commandDir: path.join(CLI_PROJECT_ROOT, COMMANDS_DIR, options.name),
+    cliEntryPath: path.join(CLI_PROJECT_ROOT, 'src/cli.ts'),
+  };
+}
+
+function assertCommandDoesNotExist(tree: Tree, options: NormalizedSchema) {
+  if (tree.exists(path.join(options.commandDir, 'index.ts'))) {
+    throw new Error(`Command "${options.name}" already exists at ${options.commandDir}`);
+  }
+}
+
+function addFiles(tree: Tree, options: NormalizedSchema) {
+  const templateOptions = {
+    ...options,
+    tmpl: '',
+  };
+
+  generateFiles(tree, path.join(__dirname, 'files'), options.commandDir, templateOptions);
+}
+
+function registerCommand(tree: Tree, options: NormalizedSchema) {
+  const cliPath = options.cliEntryPath;
+  const content = tree.read(cliPath, 'utf-8');
+
+  if (!content) {
+    throw new Error(`CLI entry file not found at ${cliPath}`);
+  }
+
+  const importName = `${options.propertyName}Command`;
+  const importPath = `./commands/${options.name}`;
+
+  if (content.includes(importPath)) {
+    return;
+  }
+
+  // Add import after the last existing command import
+  const importStatement = `import ${importName} from '${importPath}';\n`;
+  const lastImportIndex = content.lastIndexOf('import ');
+  const lastImportEnd = content.indexOf('\n', lastImportIndex) + 1;
+  const withImport = content.slice(0, lastImportEnd) + importStatement + content.slice(lastImportEnd);
+
+  // Add .command() registration before .demandCommand()
+  const commandRegistration = `    .command(${importName})\n`;
+  const demandCommandIndex = withImport.indexOf('.demandCommand(');
+  const insertPoint = withImport.lastIndexOf('\n', demandCommandIndex) + 1;
+  const withCommand = withImport.slice(0, insertPoint) + commandRegistration + withImport.slice(insertPoint);
+
+  tree.write(cliPath, withCommand);
+}
diff --git a/tools/workspace-plugin/src/generators/cli-command/schema.json b/tools/workspace-plugin/src/generators/cli-command/schema.json
new file mode 100644
index 0000000000000..b7f825a8d6af6
--- /dev/null
+++ b/tools/workspace-plugin/src/generators/cli-command/schema.json
@@ -0,0 +1,29 @@
+{
+  "$schema": "http://json-schema.org/schema",
+  "$id": "CliCommand",
+  "type": "object",
+  "properties": {
+    "name": {
+      "type": "string",
+      "description": "Command name (e.g. 'migrate', 'report')",
+      "$default": {
+        "$source": "argv",
+        "index": 0
+      },
+      "x-prompt": "What name would you like to use for the CLI command?",
+      "pattern": "^[a-z][a-z0-9-]*$"
+    },
+    "description": {
+      "type": "string",
+      "description": "Short description of the command shown in --help",
+      "default": "TODO: Add description",
+      "x-prompt": "Provide a short description for the command:"
+    },
+    "skipFormat": {
+      "description": "Skip formatting files",
+      "type": "boolean",
+      "default": false
+    }
+  },
+  "required": ["name"]
+}
diff --git a/tools/workspace-plugin/src/generators/cli-command/schema.ts b/tools/workspace-plugin/src/generators/cli-command/schema.ts
new file mode 100644
index 0000000000000..a52978b8f9540
--- /dev/null
+++ b/tools/workspace-plugin/src/generators/cli-command/schema.ts
@@ -0,0 +1,15 @@
+export interface CliCommandGeneratorSchema {
+  /**
+   * Command name (e.g. 'migrate', 'report')
+   */
+  name: string;
+  /**
+   * Short description of the command shown in --help
+   * @default 'TODO: Add description'
+   */
+  description?: string;
+  /**
+   * @default false
+   */
+  skipFormat?: boolean;
+}

From e568178c3e260cc313c59641e458f26e3cac1959 Mon Sep 17 00:00:00 2001
From: Dmytro Kirpa <dmytrokirpa@microsoft.com>
Date: Thu, 5 Mar 2026 20:47:20 +0100
Subject: [PATCH 06/14] feat(fluent-cli): implement migrate v8-to-v9 command
 and skill (#35836)

---
 skills/fluentui-migrate-v8-to-v9/SKILL.md     | 516 ++++++++++++++----
 .../references/avatargroup.md                 |   6 +-
 .../references/breadcrumb.md                  |  96 ++++
 .../references/button.md                      |  82 ++-
 .../references/callout.md                     |   6 +-
 .../references/card.md                        |  83 +++
 .../references/charts.md                      |  49 ++
 .../references/checkbox.md                    |  16 +-
 .../references/colorpicker.md                 |  63 +++
 .../references/datagrid.md                    |   6 +-
 .../references/dialog.md                      |   8 +-
 .../references/drawer.md                      |   6 +-
 .../references/image.md                       |  71 +++
 .../references/input.md                       |  28 +-
 .../references/keytips.md                     |  80 +++
 .../references/label.md                       |  45 ++
 .../references/link.md                        |  85 +++
 .../references/list.md                        |  96 ++++
 .../references/menu.md                        |   6 +-
 .../references/messagebar.md                  |   6 +-
 .../references/nav.md                         | 116 ++++
 .../references/overflow.md                    | 121 ++++
 .../references/persona.md                     |  85 +++
 .../references/progressbar.md                 |  20 +-
 .../references/radiogroup.md                  |  24 +-
 .../references/rating.md                      |  92 ++++
 .../references/searchbox.md                   |  72 +++
 .../references/separator.md                   |  48 ++
 .../references/skeleton.md                    |  80 +++
 .../references/slider.md                      |  28 +-
 .../references/spinner.md                     |   6 +-
 .../references/swatchpicker.md                | 105 ++++
 .../references/switch.md                      |  53 ++
 .../references/tabs.md                        |   6 +-
 .../references/tagpicker.md                   | 107 ++++
 .../references/teachingpopover.md             | 121 ++++
 .../references/text.md                        |  86 +++
 .../references/textarea.md                    |  59 ++
 .../references/theme.md                       |  29 +-
 .../references/toolbar.md                     |  31 +-
 .../references/tooltip.md                     |   6 +-
 .../references/tree.md                        | 101 ++++
 tools/cli/eslint.config.cjs                   |   8 +-
 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       |  28 +-
 .../__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     | 346 ++++++++++++
 .../v8-to-v9/__tests__/handler.spec.ts        | 101 ++++
 .../src/commands/migrate/v8-to-v9/handler.ts  | 108 ++++
 .../src/commands/migrate/v8-to-v9/index.ts    |  31 ++
 .../v8-to-v9/utils/annotator/analyzer.ts      | 135 +++++
 .../migrate/v8-to-v9/utils/annotator/index.ts |   3 +
 .../utils/annotator/rules/button-variants.ts  |  59 ++
 .../utils/annotator/rules/component-rename.ts | 238 ++++++++
 .../utils/annotator/rules/dialog-props.ts     |  62 +++
 .../utils/annotator/rules/enum-to-string.ts   |  70 +++
 .../v8-to-v9/utils/annotator/rules/get-id.ts  |  45 ++
 .../utils/annotator/rules/icon-props.ts       | 199 +++++++
 .../utils/annotator/rules/import-paths.ts     |  74 +++
 .../utils/annotator/rules/keycodes.ts         |  74 +++
 .../utils/annotator/rules/label-extraction.ts |  54 ++
 .../utils/annotator/rules/no-equivalent.ts    |  44 ++
 .../annotator/rules/progress-bar-props.ts     |  40 ++
 .../utils/annotator/rules/prop-rename.ts      |  42 ++
 .../annotator/rules/remove-theme-prop.ts      |  41 ++
 .../utils/annotator/rules/styles-prop.ts      |  35 ++
 .../utils/annotator/rules/toggle-props.ts     |  54 ++
 .../utils/annotator/rules/use-boolean.ts      |  66 +++
 .../v8-to-v9/utils/annotator/rules/utils.ts   |  36 ++
 .../migrate/v8-to-v9/utils/annotator/types.ts |  27 +
 .../v8-to-v9/utils/annotator/writer.ts        | 110 ++++
 yarn.lock                                     |   2 +-
 84 files changed, 4747 insertions(+), 224 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
 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/analyzer.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 c7bd906ac4bde..bdfed67332f77 100644
--- a/skills/fluentui-migrate-v8-to-v9/SKILL.md
+++ b/skills/fluentui-migrate-v8-to-v9/SKILL.md
@@ -5,23 +5,79 @@ 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:** 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 (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)
+```
+
+---
+
 ## Migration Workflow
 
 ### Step 1 — Assess
 
-Find all files using v8:
+**Determine project root and source directory:**
+
+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.
+
+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. The CLI writes it to the same directory passed as `--path`, so look in `<SOURCE_ROOT>`:
 
 ```sh
-# All files importing from @fluentui/react
-grep -rl "@fluentui/react" src/ --include="*.tsx" --include="*.ts"
+cat <SOURCE_ROOT>/.fluent-migrate/metadata.json
+```
 
-# Tally component usage to prioritize
-grep -rh "from '@fluentui/react'" src/ | sort | uniq -c | sort -rn
+- 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
+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."
+  >
+  > 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.
 
-### Step 2 — Setup
+### 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.
+
+### 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
@@ -47,64 +103,226 @@ import { PortalCompatProvider } from '@fluentui/react-portal-compat';
 </FluentProvider>;
 ```
 
-### Step 3 — Migrate (file by file)
-
-**Recommended order within a file:**
-
-1. Update import statements (`@fluentui/react` → `@fluentui/react-components`)
-2. Rename components per the mapping table below
-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)
-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))
-
-**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)
-
-### Step 4 — Verify
+### Step 3 — Migrate (annotation-driven)
+
+**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.
+
+#### 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
+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"
+```
+
+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
+
+```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. 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
 
 ```sh
-# After each file or batch — catch type errors early:
-npx tsc --noEmit
+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:
 
-# Confirm no v8 imports remain:
-grep -r "from '@fluentui/react'" src/ --include="*.tsx" --include="*.ts"
-# Should only show @fluentui/react-components imports
+```sh
+grep -rn "from '@fluentui/react'" <SOURCE_ROOT> --include="*.ts" --include="*.tsx"
 ```
 
-**Visual / runtime checks (open the app after each batch):**
+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`
 
-- **Unstyled components** (raw HTML with no Fluent design) → `FluentProvider` is missing or the component is rendered outside it
+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.
+
+**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 +395,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`                                                 | `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)                                                                              |
+| `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 +488,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                                                                     |
+| `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                                                           |
 
 ---
 
@@ -383,6 +632,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 +658,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/avatargroup.md b/skills/fluentui-migrate-v8-to-v9/references/avatargroup.md
index be6af59725a15..5a7ac29a037e9 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
new file mode 100644
index 0000000000000..8a06e34d71ba1
--- /dev/null
+++ b/skills/fluentui-migrate-v8-to-v9/references/breadcrumb.md
@@ -0,0 +1,96 @@
+# 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
+
+### Before
+
+```tsx
+import { Breadcrumb } from '@fluentui/react';
+<Breadcrumb
+  items={[
+    { text: 'Home', key: 'home', href: '/' },
+    { text: 'Docs', key: 'docs', href: '/docs' },
+    { text: 'Components', key: 'components', isCurrentItem: true },
+  ]}
+/>;
+```
+
+### After
+
+```tsx
+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 6468df87a8d48..554b3df5e7ef2 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} />;
+```
+
+**After:**
 
-// v9
+```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
@@ -84,25 +100,63 @@ 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`)
+
+**Before:**
+
+```tsx
+import { DefaultButton } from '@fluentui/react';
+<DefaultButton
+  text="Options"
+  menuProps={{
+    items: [
+      { key: 'edit', text: 'Edit', onClick: handleEdit },
+      { key: 'delete', text: 'Delete', onClick: handleDelete },
+    ],
+  }}
+/>;
+```
+
+**After:**
+
+```tsx
+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
 
+**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 669d756d89700..6ddee51e43889 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
new file mode 100644
index 0000000000000..8b4cd2e02b54c
--- /dev/null
+++ b/skills/fluentui-migrate-v8-to-v9/references/card.md
@@ -0,0 +1,83 @@
+# 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
+
+### Before
+
+```tsx
+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>;
+```
+
+### After
+
+```tsx
+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 0000000000000..52c6ba902a05c
--- /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/checkbox.md b/skills/fluentui-migrate-v8-to-v9/references/checkbox.md
index b7546acaa0c6c..a7ce2ae20625a 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
new file mode 100644
index 0000000000000..adfb0106269e7
--- /dev/null
+++ b/skills/fluentui-migrate-v8-to-v9/references/colorpicker.md
@@ -0,0 +1,63 @@
+# 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
+
+### Before
+
+```tsx
+import { ColorPicker } from '@fluentui/react';
+<ColorPicker color={color} onChange={(_, c) => setColor(c)} />;
+```
+
+### 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 a4ff5fc3a0ea3..1ba78d0243d79 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 ba463c5926bed..7b6733a2e1c1e 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 7a2d9ee1002e4..4c508dbd4f75b 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
new file mode 100644
index 0000000000000..f8ba5f8c16f5e
--- /dev/null
+++ b/skills/fluentui-migrate-v8-to-v9/references/image.md
@@ -0,0 +1,71 @@
+# 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
+
+### Before
+
+```tsx
+import { Image, ImageFit } from '@fluentui/react';
+<Image src={imgSrc} imageFit={ImageFit.cover} width={200} height={150} shouldFadeIn />;
+```
+
+### After
+
+```tsx
+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/input.md b/skills/fluentui-migrate-v8-to-v9/references/input.md
index 011826820a3ab..7865dbc03d68e 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
new file mode 100644
index 0000000000000..1d65c17f371b2
--- /dev/null
+++ b/skills/fluentui-migrate-v8-to-v9/references/keytips.md
@@ -0,0 +1,80 @@
+# 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
+
+### Before
+
+```tsx
+import { DefaultButton } from '@fluentui/react';
+<DefaultButton keytipProps={{ content: 'B', keySequences: ['b'] }}>Action</DefaultButton>;
+```
+
+### After
+
+```tsx
+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 0000000000000..11550e5485242
--- /dev/null
+++ b/skills/fluentui-migrate-v8-to-v9/references/label.md
@@ -0,0 +1,45 @@
+# 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
+
+### Before
+
+```tsx
+import { Label } from '@fluentui/react';
+<Label required>Email</Label>;
+```
+
+### After
+
+```tsx
+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 0000000000000..f48b8db8bcd19
--- /dev/null
+++ b/skills/fluentui-migrate-v8-to-v9/references/link.md
@@ -0,0 +1,85 @@
+# 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
+
+### Before
+
+```tsx
+import { Link } from '@fluentui/react';
+<Link href="/docs">Read the docs</Link>;
+<Link onClick={handleClick}>Click me</Link>;
+```
+
+### After
+
+```tsx
+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 0000000000000..4ce177ebbfa10
--- /dev/null
+++ b/skills/fluentui-migrate-v8-to-v9/references/list.md
@@ -0,0 +1,96 @@
+# 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
+
+### Before
+
+```tsx
+import { List } from '@fluentui/react';
+<List items={contacts} onRenderCell={item => <div onClick={() => openContact(item)}>{item?.name}</div>} />;
+```
+
+### After
+
+```tsx
+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/menu.md b/skills/fluentui-migrate-v8-to-v9/references/menu.md
index b732f60eeb0e1..75898286a7bdf 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 527e81f5854f7..c5c38715c214c 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
new file mode 100644
index 0000000000000..c228dc6aa3dad
--- /dev/null
+++ b/skills/fluentui-migrate-v8-to-v9/references/nav.md
@@ -0,0 +1,116 @@
+# 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
+
+### Before
+
+```tsx
+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' }],
+        },
+      ],
+    },
+  ]}
+/>;
+```
+
+### After
+
+```tsx
+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 0000000000000..638a60943215a
--- /dev/null
+++ b/skills/fluentui-migrate-v8-to-v9/references/overflow.md
@@ -0,0 +1,121 @@
+# 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
+
+### Before
+
+```tsx
+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="..." />}
+/>;
+```
+
+### After
+
+```tsx
+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 0000000000000..c4bb11cdd3f85
--- /dev/null
+++ b/skills/fluentui-migrate-v8-to-v9/references/persona.md
@@ -0,0 +1,85 @@
+# 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
+
+### Before
+
+```tsx
+import { Persona, PersonaSize, PersonaPresence } from '@fluentui/react';
+<Persona
+  text="Alice Northwood"
+  secondaryText="Software Engineer"
+  imageUrl={avatarSrc}
+  size={PersonaSize.size48}
+  presence={PersonaPresence.online}
+/>;
+```
+
+### After
+
+```tsx
+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/progressbar.md b/skills/fluentui-migrate-v8-to-v9/references/progressbar.md
index c0aed158ee4ac..35c1b2c6dd634 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 b8409fed3a6f0..d13f5195922a7 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
new file mode 100644
index 0000000000000..25d182f993d22
--- /dev/null
+++ b/skills/fluentui-migrate-v8-to-v9/references/rating.md
@@ -0,0 +1,92 @@
+# 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
+
+### Before
+
+```tsx
+import { Rating, RatingSize } from '@fluentui/react';
+<Rating
+  rating={value}
+  max={5}
+  size={RatingSize.Large}
+  onChange={(_, v) => setValue(v ?? 0)}
+  ariaLabelFormat="{0} of {1} stars"
+/>;
+```
+
+### After
+
+```tsx
+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 0000000000000..64a6d75a40f6c
--- /dev/null
+++ b/skills/fluentui-migrate-v8-to-v9/references/searchbox.md
@@ -0,0 +1,72 @@
+# 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
+
+### Before
+
+```tsx
+import { SearchBox } from '@fluentui/react';
+<SearchBox
+  placeholder="Search"
+  value={query}
+  onChange={(_, v) => setQuery(v ?? '')}
+  onSearch={v => doSearch(v)}
+  onClear={() => setQuery('')}
+/>;
+```
+
+### After
+
+```tsx
+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 0000000000000..d8eda7dff2a90
--- /dev/null
+++ b/skills/fluentui-migrate-v8-to-v9/references/separator.md
@@ -0,0 +1,48 @@
+# 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
+
+### Before
+
+```tsx
+import { Separator } from '@fluentui/react';
+<Separator vertical alignContent="end">
+  Label
+</Separator>;
+```
+
+### After
+
+```tsx
+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 0000000000000..a3d4c9dafa940
--- /dev/null
+++ b/skills/fluentui-migrate-v8-to-v9/references/skeleton.md
@@ -0,0 +1,80 @@
+# 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
+
+### Before
+
+```tsx
+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>;
+```
+
+### After
+
+```tsx
+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/slider.md b/skills/fluentui-migrate-v8-to-v9/references/slider.md
index 72b4a01c27817..510a469542b44 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 f3613c64d00e7..1ae550a112220 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
new file mode 100644
index 0000000000000..61feab6a1a154
--- /dev/null
+++ b/skills/fluentui-migrate-v8-to-v9/references/swatchpicker.md
@@ -0,0 +1,105 @@
+# 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
+
+### Before
+
+```tsx
+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' },
+  ]}
+/>;
+```
+
+### After
+
+```tsx
+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 0000000000000..ce2c48865cda7
--- /dev/null
+++ b/skills/fluentui-migrate-v8-to-v9/references/switch.md
@@ -0,0 +1,53 @@
+# 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
+
+### Before
+
+```tsx
+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)} />;
+```
+
+### After
+
+```tsx
+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/tabs.md b/skills/fluentui-migrate-v8-to-v9/references/tabs.md
index e3a64f42336db..f034fa0eaa546 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/tagpicker.md b/skills/fluentui-migrate-v8-to-v9/references/tagpicker.md
new file mode 100644
index 0000000000000..7b0f8cf590bd6
--- /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 0000000000000..badac6d8c0126
--- /dev/null
+++ b/skills/fluentui-migrate-v8-to-v9/references/teachingpopover.md
@@ -0,0 +1,121 @@
+# 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
+
+### Before
+
+```tsx
+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>;
+```
+
+### After
+
+```tsx
+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 0000000000000..7f9d3ae4cde8c
--- /dev/null
+++ b/skills/fluentui-migrate-v8-to-v9/references/text.md
@@ -0,0 +1,86 @@
+# 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
+
+### Before
+
+```tsx
+import { Text } from '@fluentui/react';
+<Text variant="xxLarge" block nowrap>
+  Heading
+</Text>;
+```
+
+### After
+
+```tsx
+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 0000000000000..c137511a14096
--- /dev/null
+++ b/skills/fluentui-migrate-v8-to-v9/references/textarea.md
@@ -0,0 +1,59 @@
+# 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
+
+### Before
+
+```tsx
+import { TextField } from '@fluentui/react';
+<TextField
+  label="Comments"
+  multiline
+  required
+  errorMessage={error}
+  value={value}
+  onChange={(_, v) => setValue(v ?? '')}
+/>;
+```
+
+### 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" />
+</Field>;
+```
diff --git a/skills/fluentui-migrate-v8-to-v9/references/theme.md b/skills/fluentui-migrate-v8-to-v9/references/theme.md
index 7a636d1fd8645..5d09d3c259f0b 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 4089b2cb21112..284c2c91b3294 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';
@@ -127,6 +129,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/tooltip.md b/skills/fluentui-migrate-v8-to-v9/references/tooltip.md
index 30e940411ed9f..a7615307248ed 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/skills/fluentui-migrate-v8-to-v9/references/tree.md b/skills/fluentui-migrate-v8-to-v9/references/tree.md
new file mode 100644
index 0000000000000..25ba1879a3c65
--- /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>;
+```
diff --git a/tools/cli/eslint.config.cjs b/tools/cli/eslint.config.cjs
index 827203cf8f59b..f956e471b76c2 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/package.json b/tools/cli/package.json
index 231942bd7dc51..3dee465b40571 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 5c35abdf7eba1..0000000000000
--- 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 0b029904dd985..0000000000000
--- 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 06f593b8af6f2..51599bd1bac4a 100644
--- a/tools/cli/src/commands/migrate/index.ts
+++ b/tools/cli/src/commands/migrate/index.ts
@@ -1,12 +1,28 @@
 import type { CommandModule } from 'yargs';
+import v8ToV9Command from './v8-to-v9';
+
+const AVAILABLE_MIGRATIONS = ['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)
+      .option('list', {
+        alias: 'l',
+        type: 'boolean',
+        description: 'List all available migrations',
+      })
+      .version(false)
+      .help(),
+  handler: argv => {
+    if ((argv as { list?: boolean }).list) {
+      console.log('Available migrations:');
+      for (const m of AVAILABLE_MIGRATIONS) {
+        console.log(`  ${m}`);
+      }
+    }
   },
 };
 
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 0000000000000..235a77770f2b6
--- /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 0000000000000..c2795a30e8fc3
--- /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 0000000000000..323d0c4c62914
--- /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 0000000000000..3550c4730fe93
--- /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 0000000000000..26fe7c2284e3a
--- /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 0000000000000..7b958ff6167e8
--- /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 0000000000000..ba5509b6ab8b5
--- /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 0000000000000..2bc6e1ed08fd5
--- /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 0000000000000..90adb1d0b0b3d
--- /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 0000000000000..289b784a4921b
--- /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 0000000000000..ee538844d2f6e
--- /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 0000000000000..77bb122631860
--- /dev/null
+++ b/tools/cli/src/commands/migrate/v8-to-v9/__tests__/handler.integration.spec.ts
@@ -0,0 +1,346 @@
+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';
+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);
+      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');
+      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.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);
+    });
+
+    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.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 () => {
+      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 === '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 () => {
+      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>
+        );
+        "
+      `);
+    });
+
+    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 ───────────────────────────────────────────────────────
+
+  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('dryRun 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('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('[dryRun]'))).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:auto | import-paths |');
+      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);
+    });
+
+    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
new file mode 100644
index 0000000000000..532cd6086e6c1
--- /dev/null
+++ b/tools/cli/src/commands/migrate/v8-to-v9/__tests__/handler.spec.ts
@@ -0,0 +1,101 @@
+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(() => {
+    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(() => {
+    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).toHaveBeenCalledWith(expect.any(Array), 'src/');
+  });
+
+  it('skips writeAnnotations in dryRun 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 file'));
+    expect(logSpy).toHaveBeenCalledWith(expect.stringContaining('auto'));
+    expect(logSpy).toHaveBeenCalledWith(expect.stringContaining('manual'));
+  });
+
+  it('prints [dryRun] 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('[dryRun]'));
+    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
new file mode 100644
index 0000000000000..9fcd93e802df7
--- /dev/null
+++ b/tools/cli/src/commands/migrate/v8-to-v9/handler.ts
@@ -0,0 +1,108 @@
+import * as fs from 'fs/promises';
+import type { CommandHandler } from '../../../utils/types';
+import { analyzeFiles, writeAnnotations } from './utils/annotator';
+import type { FileAnalysis } from './utils/annotator';
+
+interface V8ToV9Args {
+  path: string;
+  dryRun: boolean;
+}
+
+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) {
+    printDryRunReport(results);
+    return;
+  }
+
+  const { filesChanged } = await writeAnnotations(results, argv.path);
+  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} ${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)`);
+  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[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)`);
+  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 0000000000000..a4424b73432b0
--- /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('dryRun', {
+        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/analyzer.ts b/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/analyzer.ts
new file mode 100644
index 0000000000000..cdd0da59728ff
--- /dev/null
+++ b/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/analyzer.ts
@@ -0,0 +1,135 @@
+import * as fs from 'fs/promises';
+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',
+  },
+];
+
+/**
+ * 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,
+    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, 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) && !installedPackages.has(dep.name),
+    ).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
new file mode 100644
index 0000000000000..3fd2ac563b183
--- /dev/null
+++ b/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/index.ts
@@ -0,0 +1,3 @@
+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
new file mode 100644
index 0000000000000..2e8cf8dec2d03
--- /dev/null
+++ b/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/button-variants.ts
@@ -0,0 +1,59 @@
+import type { SourceFile, Node } from 'ts-morph';
+import { SyntaxKind } from 'ts-morph';
+import type { AnnotationResult } from '../types';
+import { 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, fluentNames: Set<string>): AnnotationResult[] {
+  const results: AnnotationResult[] = [];
+
+  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 0000000000000..900c20c57ccba
--- /dev/null
+++ b/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/component-rename.ts
@@ -0,0 +1,238 @@
+import type { SourceFile, Node } from 'ts-morph';
+import { SyntaxKind } from 'ts-morph';
+import type { AnnotationResult } from '../types';
+import { 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',
+  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. */
+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',
+  },
+  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[] {
+  const results: AnnotationResult[] = [];
+
+  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);
+    const line = node.getStartLineNumber();
+
+    if (AUTO_RENAMES[tagName]) {
+      results.push({
+        action: 'auto',
+        codemod: 'component-rename',
+        payload: `${tagName} → ${AUTO_RENAMES[tagName]}`,
+        line,
+        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,
+        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,
+      });
+    }
+  });
+
+  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 0000000000000..2523e6b2a59e4
--- /dev/null
+++ b/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/dialog-props.ts
@@ -0,0 +1,62 @@
+import type { SourceFile, Node } from 'ts-morph';
+import { SyntaxKind } from 'ts-morph';
+import type { AnnotationResult } from '../types';
+
+const DIALOG_COMPONENTS = new Set(['Dialog', 'Modal']);
+
+export function detectDialogProps(sourceFile: SourceFile, fluentNames: Set<string>): AnnotationResult[] {
+  const results: AnnotationResult[] = [];
+
+  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 0000000000000..84309b6f3ce25
--- /dev/null
+++ b/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/enum-to-string.ts
@@ -0,0 +1,70 @@
+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 0000000000000..dd5fd95622fb9
--- /dev/null
+++ b/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/get-id.ts
@@ -0,0 +1,45 @@
+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 0000000000000..9c82a357ddf2c
--- /dev/null
+++ b/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/icon-props.ts
@@ -0,0 +1,199 @@
+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.
+// The v9 icon name is the v8 name + "Regular" suffix (e.g. Add → AddRegular).
+const KNOWN_ICONS = new Set([
+  // Navigation & actions
+  'Add',
+  'AddCircle',
+  'ArrowClockwise',
+  'ArrowCounterclockwise',
+  'ArrowDown',
+  'ArrowDownload',
+  'ArrowLeft',
+  'ArrowRight',
+  'ArrowUp',
+  'ArrowUpload',
+  'Attach',
+  'Backspace',
+  'Bookmark',
+  'BookmarkAdd',
+  'Calendar',
+  'CalendarAdd',
+  'Call',
+  'Camera',
+  'Cancel',
+  'CheckMark',
+  'ChevronDown',
+  'ChevronLeft',
+  'ChevronRight',
+  'ChevronUp',
+  'CircleSmall',
+  'ClipboardPaste',
+  'Clock',
+  'Close',
+  'Cloud',
+  'CloudArrowUp',
+  'Code',
+  'Color',
+  'Comment',
+  'CommentAdd',
+  'Copy',
+  'Cut',
+  'DataBar',
+  'Delete',
+  'Dismiss',
+  'Document',
+  'DocumentAdd',
+  'DocumentCopy',
+  'DocumentEdit',
+  'Download',
+  'Edit',
+  'Emoji',
+  'Error',
+  'Eye',
+  'EyeOff',
+  'Filter',
+  'Flag',
+  'Folder',
+  'FolderAdd',
+  'FolderOpen',
+  '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',
+  'Video',
+  'VideoOff',
+  'Warning',
+  'Wrench',
+  'ZoomIn',
+  'ZoomOut',
+]);
+
+export function detectIconProps(sourceFile: SourceFile, fluentNames: Set<string>): AnnotationResult[] {
+  const results: AnnotationResult[] = [];
+
+  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 0000000000000..915f67b29e77a
--- /dev/null
+++ b/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/import-paths.ts
@@ -0,0 +1,74 @@
+import type { SourceFile } from 'ts-morph';
+import type { AnnotationResult } from '../types';
+import { DEPRECATED_COMPONENT_NAMES } from './no-equivalent';
+
+/** 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()) {
+    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 => 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()} → ${pkg}`,
+        note: `split import; move specifier to a separate "import { ... } from '${pkg}'"`,
+        line,
+      });
+    }
+
+    const hasEquivSpecifiers = namedImports.some(
+      s => !DEPRECATED_COMPONENT_NAMES.has(s.getName()) && !COMPAT_PACKAGES[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 0000000000000..692189af1e876
--- /dev/null
+++ b/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/keycodes.ts
@@ -0,0 +1,74 @@
+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 0000000000000..ede5e1d50f9ae
--- /dev/null
+++ b/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/label-extraction.ts
@@ -0,0 +1,54 @@
+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', '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[] = [];
+
+  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="..."><${V9_NAME[tagName] ?? 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 0000000000000..7889d9decfedf
--- /dev/null
+++ b/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/no-equivalent.ts
@@ -0,0 +1,44 @@
+import type { SourceFile, Node } from 'ts-morph';
+import { SyntaxKind } from 'ts-morph';
+import type { AnnotationResult } from '../types';
+import { 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">',
+  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[] = [];
+
+  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,
+      note: 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 0000000000000..bf7a43a8cfc96
--- /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';
+
+export function detectProgressBarProps(sourceFile: SourceFile, fluentNames: Set<string>): AnnotationResult[] {
+  const results: AnnotationResult[] = [];
+
+  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 0000000000000..66f526c292fcd
--- /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';
+
+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, fluentNames: Set<string>): AnnotationResult[] {
+  const results: AnnotationResult[] = [];
+
+  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 0000000000000..d2ef452458c47
--- /dev/null
+++ b/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/remove-theme-prop.ts
@@ -0,0 +1,41 @@
+import type { SourceFile, Node } from 'ts-morph';
+import { SyntaxKind } from 'ts-morph';
+import type { AnnotationResult } from '../types';
+
+export function detectRemoveThemeProp(sourceFile: SourceFile, fluentNames: Set<string>): AnnotationResult[] {
+  const results: AnnotationResult[] = [];
+
+  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 0000000000000..2bc2e9ecee0d8
--- /dev/null
+++ b/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/styles-prop.ts
@@ -0,0 +1,35 @@
+import type { SourceFile, Node } from 'ts-morph';
+import { SyntaxKind } from 'ts-morph';
+import type { AnnotationResult } from '../types';
+
+export function detectStylesProp(sourceFile: SourceFile, fluentNames: Set<string>): AnnotationResult[] {
+  const results: AnnotationResult[] = [];
+
+  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 0000000000000..675af0c04404a
--- /dev/null
+++ b/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/toggle-props.ts
@@ -0,0 +1,54 @@
+import type { SourceFile, Node } from 'ts-morph';
+import { SyntaxKind } from 'ts-morph';
+import type { AnnotationResult } from '../types';
+
+export function detectToggleProps(sourceFile: SourceFile, fluentNames: Set<string>): AnnotationResult[] {
+  const results: AnnotationResult[] = [];
+
+  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: 'no-equivalent',
+            payload: propName,
+            note: 'v9 Switch has no on/off labels — remove the prop or build a 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 0000000000000..1668716c36155
--- /dev/null
+++ b/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/use-boolean.ts
@@ -0,0 +1,66 @@
+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 0000000000000..0d302c503eab5
--- /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 0000000000000..d86d7d8b60a9e
--- /dev/null
+++ b/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/types.ts
@@ -0,0 +1,27 @@
+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 }>;
+}
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 0000000000000..9d78062efb5d1
--- /dev/null
+++ b/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/writer.ts
@@ -0,0 +1,110 @@
+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';
+
+/**
+ * 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) {
+    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 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.
+ */
+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;
+    }
+
+    const content = await fs.readFile(file.filePath, 'utf8');
+    const lines = content.split('\n');
+
+    // 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 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);
+
+      // Search backward through the annotation block above the target for an identical comment
+      if (annotationAlreadyPresent(lines, targetLine, comment)) {
+        continue;
+      }
+
+      // Determine indentation from the target line
+      const indent = lines[targetLine]?.match(/^(\s*)/)?.[1] ?? '';
+
+      lines.splice(targetLine, 0, `${indent}${comment}`);
+      sameLineInsertions.set(annotation.line, existingInsertions + 1);
+      changed = true;
+    }
+
+    if (changed) {
+      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 };
+}
diff --git a/yarn.lock b/yarn.lock
index 2a0964696b419..2676ef6af6770 100644
--- a/yarn.lock
+++ b/yarn.lock
@@ -10077,7 +10077,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 7aff3955790ee478e9bd647a07872ba3d05953fc Mon Sep 17 00:00:00 2001
From: Martin Hochel <martinhochel@microsoft.com>
Date: Fri, 6 Mar 2026 14:53:35 +0100
Subject: [PATCH 07/14] feat(cli): add banner (#35841)

---
 tools/cli/src/cli.ts | 12 +++++++++++-
 1 file changed, 11 insertions(+), 1 deletion(-)

diff --git a/tools/cli/src/cli.ts b/tools/cli/src/cli.ts
index ac1bd84cf977d..ffd1f035dc883 100644
--- a/tools/cli/src/cli.ts
+++ b/tools/cli/src/cli.ts
@@ -3,10 +3,20 @@ import yargs from 'yargs';
 import migrateCommand from './commands/migrate';
 import reportCommand from './commands/report';
 
+const BANNER = `
+  ███████╗██╗     ██╗   ██╗███████╗███╗   ██╗████████╗  ██╗   ██╗██╗
+  ██╔════╝██║     ██║   ██║██╔════╝████╗  ██║╚══██╔══╝  ██║   ██║██║
+  █████╗  ██║     ██║   ██║█████╗  ██╔██╗ ██║   ██║     ██║   ██║██║
+  ██╔══╝  ██║     ██║   ██║██╔══╝  ██║╚██╗██║   ██║     ██║   ██║██║
+  ██║     ███████╗╚██████╔╝███████╗██║ ╚████║   ██║     ╚██████╔╝██║
+  ╚═╝     ╚══════╝ ╚═════╝ ╚══════╝╚═╝  ╚═══╝   ╚═╝      ╚═════╝ ╚═╝
+                                                               CLI
+`;
+
 export async function main(argv: string[]): Promise<void> {
   await yargs(argv)
     .scriptName('fluentui-cli')
-    .usage('$0 <command> [options]')
+    .usage(`${BANNER}\n  $0 <command> [options]`)
     .command(migrateCommand)
     .command(reportCommand)
     .demandCommand(1, 'You need to specify a command to run.')

From 5c51d78244d808ddf42b8b94a13731b931152bef Mon Sep 17 00:00:00 2001
From: Martin Hochel <martinhochel@microsoft.com>
Date: Tue, 7 Apr 2026 14:49:29 +0200
Subject: [PATCH 08/14] feat(cli): implement `report` command with `info` and
 `usage` subcommands (#35842)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 tools/cli/.swcrc                              |   1 +
 tools/cli/eslint.config.cjs                   |   2 +-
 tools/cli/src/commands/report/README.md       | 105 +++
 .../@proj/react-components/index.d.ts         |  84 +++
 .../@proj/react-components/package.json       |   5 +
 .../@types/react/index.d.ts                   |  26 +
 .../@types/react/package.json                 |   5 +
 .../__fixtures__/sample-app/package.json      |  15 +
 .../AzureLightTheme/AzureLightTheme.ts        |   4 +
 .../src/components/AzureLightTheme/index.ts   |   1 +
 .../packages/azure-theme/src/index.ts         |   1 +
 .../sample-app/src/basic-usage.tsx            |  26 +
 .../__fixtures__/sample-app/src/hook-args.tsx |  27 +
 .../sample-app/src/mixed-imports.tsx          |  24 +
 .../sample-app/src/path-alias-imports.tsx     |   9 +
 .../sample-app/src/type-imports.ts            |  12 +
 .../__fixtures__/sample-app/src/type-refs.tsx |  20 +
 .../__fixtures__/sample-app/tsconfig.json     |  18 +
 .../src/commands/report/commands/info.spec.ts |  27 +
 .../cli/src/commands/report/commands/info.ts  |  23 +
 .../commands/report/commands/usage.spec.ts    |  78 +++
 .../cli/src/commands/report/commands/usage.ts |  45 ++
 tools/cli/src/commands/report/handler.spec.ts |  19 -
 tools/cli/src/commands/report/handler.ts      |   6 -
 .../commands/report/impl/ast-parser.spec.ts   | 344 ++++++++++
 .../src/commands/report/impl/ast-parser.ts    | 567 ++++++++++++++++
 .../report/impl/file-discovery.spec.ts        | 193 ++++++
 .../commands/report/impl/file-discovery.ts    |  82 +++
 .../report/impl/html-reporter.spec.ts         | 305 +++++++++
 .../src/commands/report/impl/html-reporter.ts | 394 +++++++++++
 tools/cli/src/commands/report/impl/index.ts   |  18 +
 .../commands/report/impl/info-report.spec.ts  | 105 +++
 .../src/commands/report/impl/info-report.ts   |  90 +++
 .../report/impl/markdown-reporter.spec.ts     | 224 +++++++
 .../commands/report/impl/markdown-reporter.ts | 159 +++++
 .../report/impl/package-resolver.spec.ts      | 261 ++++++++
 .../commands/report/impl/package-resolver.ts  | 221 ++++++
 tools/cli/src/commands/report/impl/types.ts   | 273 ++++++++
 .../commands/report/impl/usage-report.spec.ts | 630 ++++++++++++++++++
 .../src/commands/report/impl/usage-report.ts  | 390 +++++++++++
 tools/cli/src/commands/report/index.ts        |  17 +-
 tools/cli/tsconfig.lib.json                   |   2 +-
 42 files changed, 4826 insertions(+), 32 deletions(-)
 create mode 100644 tools/cli/src/commands/report/README.md
 create mode 100644 tools/cli/src/commands/report/__fixtures__/sample-app/_mock_node_modules/@proj/react-components/index.d.ts
 create mode 100644 tools/cli/src/commands/report/__fixtures__/sample-app/_mock_node_modules/@proj/react-components/package.json
 create mode 100644 tools/cli/src/commands/report/__fixtures__/sample-app/_mock_node_modules/@types/react/index.d.ts
 create mode 100644 tools/cli/src/commands/report/__fixtures__/sample-app/_mock_node_modules/@types/react/package.json
 create mode 100644 tools/cli/src/commands/report/__fixtures__/sample-app/package.json
 create mode 100644 tools/cli/src/commands/report/__fixtures__/sample-app/packages/azure-theme/src/components/AzureLightTheme/AzureLightTheme.ts
 create mode 100644 tools/cli/src/commands/report/__fixtures__/sample-app/packages/azure-theme/src/components/AzureLightTheme/index.ts
 create mode 100644 tools/cli/src/commands/report/__fixtures__/sample-app/packages/azure-theme/src/index.ts
 create mode 100644 tools/cli/src/commands/report/__fixtures__/sample-app/src/basic-usage.tsx
 create mode 100644 tools/cli/src/commands/report/__fixtures__/sample-app/src/hook-args.tsx
 create mode 100644 tools/cli/src/commands/report/__fixtures__/sample-app/src/mixed-imports.tsx
 create mode 100644 tools/cli/src/commands/report/__fixtures__/sample-app/src/path-alias-imports.tsx
 create mode 100644 tools/cli/src/commands/report/__fixtures__/sample-app/src/type-imports.ts
 create mode 100644 tools/cli/src/commands/report/__fixtures__/sample-app/src/type-refs.tsx
 create mode 100644 tools/cli/src/commands/report/__fixtures__/sample-app/tsconfig.json
 create mode 100644 tools/cli/src/commands/report/commands/info.spec.ts
 create mode 100644 tools/cli/src/commands/report/commands/info.ts
 create mode 100644 tools/cli/src/commands/report/commands/usage.spec.ts
 create mode 100644 tools/cli/src/commands/report/commands/usage.ts
 delete mode 100644 tools/cli/src/commands/report/handler.spec.ts
 delete mode 100644 tools/cli/src/commands/report/handler.ts
 create mode 100644 tools/cli/src/commands/report/impl/ast-parser.spec.ts
 create mode 100644 tools/cli/src/commands/report/impl/ast-parser.ts
 create mode 100644 tools/cli/src/commands/report/impl/file-discovery.spec.ts
 create mode 100644 tools/cli/src/commands/report/impl/file-discovery.ts
 create mode 100644 tools/cli/src/commands/report/impl/html-reporter.spec.ts
 create mode 100644 tools/cli/src/commands/report/impl/html-reporter.ts
 create mode 100644 tools/cli/src/commands/report/impl/index.ts
 create mode 100644 tools/cli/src/commands/report/impl/info-report.spec.ts
 create mode 100644 tools/cli/src/commands/report/impl/info-report.ts
 create mode 100644 tools/cli/src/commands/report/impl/markdown-reporter.spec.ts
 create mode 100644 tools/cli/src/commands/report/impl/markdown-reporter.ts
 create mode 100644 tools/cli/src/commands/report/impl/package-resolver.spec.ts
 create mode 100644 tools/cli/src/commands/report/impl/package-resolver.ts
 create mode 100644 tools/cli/src/commands/report/impl/types.ts
 create mode 100644 tools/cli/src/commands/report/impl/usage-report.spec.ts
 create mode 100644 tools/cli/src/commands/report/impl/usage-report.ts

diff --git a/tools/cli/.swcrc b/tools/cli/.swcrc
index 25741bb92261e..adf80780a17cc 100644
--- a/tools/cli/.swcrc
+++ b/tools/cli/.swcrc
@@ -20,6 +20,7 @@
   "sourceMaps": true,
   "exclude": [
     "jest.config.ts",
+    "__fixtures__",
     ".*\\.spec.tsx?$",
     ".*\\.test.tsx?$",
     "./src/jest-setup.ts$",
diff --git a/tools/cli/eslint.config.cjs b/tools/cli/eslint.config.cjs
index f956e471b76c2..3d8d982fe7c2e 100644
--- a/tools/cli/eslint.config.cjs
+++ b/tools/cli/eslint.config.cjs
@@ -5,7 +5,7 @@ const nodeConfig = fluentPlugin.configs['flat/node'];
 /** @type {import("eslint").Linter.Config[]} */
 module.exports = [
   {
-    ignores: ['src/commands/migrate/v8-to-v9/__tests__/fixtures/**'],
+    ignores: ['src/commands/migrate/v8-to-v9/__tests__/fixtures/**', 'src/**/__fixtures__/**'],
   },
   ...(Array.isArray(nodeConfig) ? nodeConfig : [nodeConfig]),
 ];
diff --git a/tools/cli/src/commands/report/README.md b/tools/cli/src/commands/report/README.md
new file mode 100644
index 0000000000000..d2d025f14063a
--- /dev/null
+++ b/tools/cli/src/commands/report/README.md
@@ -0,0 +1,105 @@
+# `report` command
+
+The `report` command generates reports about Fluent UI package usage in a codebase. It has two subcommands targeting different audiences and use cases.
+
+## Subcommands
+
+### `report info`
+
+Quick package & environment summary intended for **end-users** reporting issues.
+
+```bash
+fluentui report info
+```
+
+Outputs a copy-paste-friendly block with:
+
+- System info (Node version, OS, package manager)
+- Installed Fluent UI and related packages with versions
+- Duplicate package warnings (multiple resolved versions)
+
+No flags — runs against the current project and prints to stdout.
+
+#### Tracked packages
+
+| Scope          | Packages                                                |
+| -------------- | ------------------------------------------------------- |
+| Fluent scoped  | `@fluentui/*`, `@fluentui-contrib/*`                    |
+| Fluent related | `tabster`, `keyborg`, `@griffel/*`                      |
+| 3rd party      | `react`, `@types/react`, `typescript`, `@floating-ui/*` |
+
+### `report usage`
+
+Deep codebase analysis of Fluent UI API usage intended for the **core team** to understand how consumers use the library.
+
+```bash
+fluentui report usage [--path <dir>] [--reporter json|markdown|html] [--include <glob>...] [--exclude <glob>...]
+```
+
+| Flag         | Alias | Default   | Description                                  |
+| ------------ | ----- | --------- | -------------------------------------------- |
+| `--path`     | `-p`  | git root  | Root directory for file traversal            |
+| `--reporter` | `-r`  | `json`    | Output format: `json`, `markdown`, or `html` |
+| `--include`  | —     | all files | Glob patterns to include                     |
+| `--exclude`  | —     | none      | Glob patterns to exclude                     |
+
+Traverses `.ts` and `.tsx` files (skipping gitignored files), resolves imports from tracked packages, and classifies every imported symbol into one of five categories.
+
+#### Categories
+
+| Category       | What it captures                                     | Tracked details                                  |
+| -------------- | ---------------------------------------------------- | ------------------------------------------------ |
+| **Components** | React components (JSX elements)                      | Per-component prop usage with values             |
+| **Hooks**      | React hooks (`use*` naming)                          | Call-site argument usage with values             |
+| **Types**      | TypeScript interfaces, type aliases, enums           | `typeof` reference count, generic type arguments |
+| **Others**     | Value exports (constants, utility functions, themes) | Call-site argument usage when invoked            |
+| **Unknowns**   | Symbols whose `.d.ts` could not be resolved          | Naming-convention-based description              |
+
+#### Output formats
+
+- **JSON** — machine-readable metadata with a `legend`, `fileMap`, and per-package `packages` map. Default.
+- **Markdown** — summary tables and per-package breakdowns; concise, no prop details.
+- **HTML** — self-contained report with collapsible prop/argument details and dark mode support.
+
+## Architecture
+
+```
+report/
+├── index.ts                   # Parent command — registers subcommands
+├── commands/
+│   ├── info.ts                # `report info` subcommand
+│   └── usage.ts               # `report usage` subcommand
+├── impl/
+│   ├── types.ts               # All type definitions
+│   ├── ast-parser.ts          # ts-morph AST parser (symbol classification, JSX/call/type-ref extraction)
+│   ├── file-discovery.ts      # Source file traversal (respects .gitignore)
+│   ├── package-resolver.ts    # Package version resolution and reportable-package filtering
+│   ├── usage-report.ts         # Core analysis engine — collects metadata from AST parser
+│   ├── info-report.ts          # Package/system info collection and formatting
+│   ├── markdown-reporter.ts   # Markdown output formatter
+│   ├── html-reporter.ts       # HTML output formatter
+│   └── index.ts               # Barrel exports
+├── __fixtures__/              # Test fixtures (sample-app with mock node_modules)
+├── SPEC.md                    # Original specification
+└── README.md                  # This file
+```
+
+### How symbol classification works
+
+1. **Import scanning** — all `import` declarations from tracked packages are collected
+2. **Type resolution** — each symbol is resolved through its `.d.ts` declaration:
+   - Functions returning JSX → `component`
+   - `use*` naming or hook signatures → `hook`
+   - Interfaces, type aliases, enums → `type`
+   - Everything else with a resolved `.d.ts` → `other`
+   - Unresolvable `.d.ts` → `unknown`
+3. **Usage enrichment** — JSX props, call arguments, `typeof` references, and generic type arguments are captured
+4. **Deduplication** — symbols appearing in multiple categories are reconciled (e.g., a component found via both JSX and value reference)
+
+### Testing
+
+```bash
+yarn nx run cli:test
+```
+
+Tests use a fixture-based approach with a `__fixtures__/sample-app/` containing mock `_mock_node_modules` with `.d.ts` declarations. The `usage-report.spec.ts` uses a mock `AstParser` for isolated unit testing.
diff --git a/tools/cli/src/commands/report/__fixtures__/sample-app/_mock_node_modules/@proj/react-components/index.d.ts b/tools/cli/src/commands/report/__fixtures__/sample-app/_mock_node_modules/@proj/react-components/index.d.ts
new file mode 100644
index 0000000000000..8c9ee3a585506
--- /dev/null
+++ b/tools/cli/src/commands/report/__fixtures__/sample-app/_mock_node_modules/@proj/react-components/index.d.ts
@@ -0,0 +1,84 @@
+import * as React from 'react';
+
+// Component — function returning JSX.Element
+export declare function Button(props: ButtonProps): JSX.Element;
+
+// Component — function returning JSX.Element
+export declare function Input(props: InputProps): JSX.Element;
+
+// Component — function returning JSX.Element
+export declare function FluentProvider(props: FluentProviderProps): JSX.Element;
+
+// Component — function returning JSX.Element
+export declare function Tooltip(props: TooltipProps): JSX.Element;
+
+// Hook
+export declare function useId(prefix?: string): string;
+
+// Hook
+export declare function useToastController(): { dispatchToast: () => void };
+
+// Hook with options
+export declare function useArrowNavigationGroup(options?: {
+  axis?: 'vertical' | 'horizontal' | 'grid';
+  circular?: boolean;
+  memorizeCurrent?: boolean;
+  tabbable?: boolean;
+  unstable_hasDefault?: boolean;
+}): Record<string, string>;
+
+// Pure type — interface
+export interface ButtonProps {
+  appearance?: 'primary' | 'secondary';
+  size?: 'small' | 'medium' | 'large';
+  icon?: JSX.Element;
+  disabled?: boolean;
+  children?: React.ReactNode;
+}
+
+// Pure type — interface
+export interface InputProps {
+  placeholder?: string;
+  appearance?: 'outline' | 'filled';
+  contentBefore?: JSX.Element;
+}
+
+// Pure type — interface
+export interface FluentProviderProps {
+  theme?: Record<string, string>;
+  children?: React.ReactNode;
+}
+
+// Pure type — interface
+export interface TooltipProps {
+  content?: string;
+  relationship?: string;
+  children?: React.ReactNode;
+}
+
+// Other — constant (not a component, not a type)
+export declare const tokens: Record<string, string>;
+
+// Other — constant (theme object)
+export declare const webLightTheme: Record<string, string>;
+
+// Other — constant (PascalCase but NOT a component)
+export declare const AzureLightTheme: Record<string, string>;
+
+// Other — utility function
+export declare function makeStyles<T extends Record<string, Record<string, unknown>>>(
+  styles: T,
+): () => Record<keyof T, string>;
+
+// Generic type — for testing generic type reference tracking
+export type ColumnDef<TData> = {
+  id: string;
+  header: string;
+  cell: (data: TData) => React.ReactNode;
+};
+
+// Other — constant (PascalCase, looks like component but is a string constant)
+export declare const Tab: string;
+
+// Other — constant
+export declare const Enter: string;
diff --git a/tools/cli/src/commands/report/__fixtures__/sample-app/_mock_node_modules/@proj/react-components/package.json b/tools/cli/src/commands/report/__fixtures__/sample-app/_mock_node_modules/@proj/react-components/package.json
new file mode 100644
index 0000000000000..b8a99811f361a
--- /dev/null
+++ b/tools/cli/src/commands/report/__fixtures__/sample-app/_mock_node_modules/@proj/react-components/package.json
@@ -0,0 +1,5 @@
+{
+  "name": "@proj/react-components",
+  "version": "9.0.0-fixture",
+  "types": "index.d.ts"
+}
diff --git a/tools/cli/src/commands/report/__fixtures__/sample-app/_mock_node_modules/@types/react/index.d.ts b/tools/cli/src/commands/report/__fixtures__/sample-app/_mock_node_modules/@types/react/index.d.ts
new file mode 100644
index 0000000000000..0f909cece3808
--- /dev/null
+++ b/tools/cli/src/commands/report/__fixtures__/sample-app/_mock_node_modules/@types/react/index.d.ts
@@ -0,0 +1,26 @@
+declare namespace React {
+  type ReactNode = string | number | boolean | null | undefined | React.ReactElement;
+  interface ReactElement {
+    type: string;
+    props: Record<string, unknown>;
+    key: string | null;
+  }
+  type FC<P = {}> = (props: P) => ReactElement | null;
+  type FunctionComponent<P = {}> = FC<P>;
+}
+
+declare namespace JSX {
+  interface Element extends React.ReactElement {}
+  interface IntrinsicElements {
+    div: Record<string, unknown>;
+    span: Record<string, unknown>;
+  }
+}
+
+declare module 'react' {
+  export = React;
+  export as namespace React;
+}
+
+export = React;
+export as namespace React;
diff --git a/tools/cli/src/commands/report/__fixtures__/sample-app/_mock_node_modules/@types/react/package.json b/tools/cli/src/commands/report/__fixtures__/sample-app/_mock_node_modules/@types/react/package.json
new file mode 100644
index 0000000000000..9272fa42ab5ce
--- /dev/null
+++ b/tools/cli/src/commands/report/__fixtures__/sample-app/_mock_node_modules/@types/react/package.json
@@ -0,0 +1,5 @@
+{
+  "name": "@types/react",
+  "version": "18.0.0-fixture",
+  "types": "index.d.ts"
+}
diff --git a/tools/cli/src/commands/report/__fixtures__/sample-app/package.json b/tools/cli/src/commands/report/__fixtures__/sample-app/package.json
new file mode 100644
index 0000000000000..0d1670db6ea46
--- /dev/null
+++ b/tools/cli/src/commands/report/__fixtures__/sample-app/package.json
@@ -0,0 +1,15 @@
+{
+  "name": "sample-app",
+  "version": "1.0.0",
+  "dependencies": {
+    "@proj/react-components": "^9.50.0",
+    "@proj/react-icons": "^2.0.200",
+    "react": "^18.2.0",
+    "@types/react": "^18.2.0",
+    "typescript": "^5.3.0",
+    "@griffel/react": "^1.5.0"
+  },
+  "devDependencies": {
+    "@proj/eslint-plugin": "^1.0.0"
+  }
+}
diff --git a/tools/cli/src/commands/report/__fixtures__/sample-app/packages/azure-theme/src/components/AzureLightTheme/AzureLightTheme.ts b/tools/cli/src/commands/report/__fixtures__/sample-app/packages/azure-theme/src/components/AzureLightTheme/AzureLightTheme.ts
new file mode 100644
index 0000000000000..e9c1679b22137
--- /dev/null
+++ b/tools/cli/src/commands/report/__fixtures__/sample-app/packages/azure-theme/src/components/AzureLightTheme/AzureLightTheme.ts
@@ -0,0 +1,4 @@
+export const AzureLightTheme: Record<string, string> = {
+  colorBrandBackground: '#0078d4',
+  colorBrandForeground1: '#0078d4',
+};
diff --git a/tools/cli/src/commands/report/__fixtures__/sample-app/packages/azure-theme/src/components/AzureLightTheme/index.ts b/tools/cli/src/commands/report/__fixtures__/sample-app/packages/azure-theme/src/components/AzureLightTheme/index.ts
new file mode 100644
index 0000000000000..9c6559211df2d
--- /dev/null
+++ b/tools/cli/src/commands/report/__fixtures__/sample-app/packages/azure-theme/src/components/AzureLightTheme/index.ts
@@ -0,0 +1 @@
+export { AzureLightTheme } from './AzureLightTheme';
diff --git a/tools/cli/src/commands/report/__fixtures__/sample-app/packages/azure-theme/src/index.ts b/tools/cli/src/commands/report/__fixtures__/sample-app/packages/azure-theme/src/index.ts
new file mode 100644
index 0000000000000..20f9e42015c00
--- /dev/null
+++ b/tools/cli/src/commands/report/__fixtures__/sample-app/packages/azure-theme/src/index.ts
@@ -0,0 +1 @@
+export { AzureLightTheme } from './components/AzureLightTheme';
diff --git a/tools/cli/src/commands/report/__fixtures__/sample-app/src/basic-usage.tsx b/tools/cli/src/commands/report/__fixtures__/sample-app/src/basic-usage.tsx
new file mode 100644
index 0000000000000..f6256e36a9fa5
--- /dev/null
+++ b/tools/cli/src/commands/report/__fixtures__/sample-app/src/basic-usage.tsx
@@ -0,0 +1,26 @@
+import React from 'react';
+import { Button, Input, makeStyles, tokens } from '@proj/react-components';
+import { useId } from '@proj/react-components';
+import { SearchRegular } from '@proj/react-icons';
+
+const useStyles = makeStyles({
+  root: {
+    display: 'flex',
+    gap: tokens.spacingHorizontalM,
+  },
+});
+
+export const SearchForm = () => {
+  const inputId = useId('search-input');
+  const styles = useStyles();
+
+  return (
+    <div className={styles.root}>
+      <Input id={inputId} placeholder="Search..." appearance="outline" contentBefore={<SearchRegular />} />
+      <Button appearance="primary" size="medium" icon={<SearchRegular />}>
+        Search
+      </Button>
+      <Button appearance="secondary">Cancel</Button>
+    </div>
+  );
+};
diff --git a/tools/cli/src/commands/report/__fixtures__/sample-app/src/hook-args.tsx b/tools/cli/src/commands/report/__fixtures__/sample-app/src/hook-args.tsx
new file mode 100644
index 0000000000000..e6350c482c71e
--- /dev/null
+++ b/tools/cli/src/commands/report/__fixtures__/sample-app/src/hook-args.tsx
@@ -0,0 +1,27 @@
+import React from 'react';
+import { useArrowNavigationGroup, useId } from '@proj/react-components';
+
+const circular = true;
+
+export const NavGroup = () => {
+  const id = useId('nav');
+
+  // Explicit property assignments — values should be captured as literals
+  const attrs = useArrowNavigationGroup({
+    axis: 'vertical',
+    memorizeCurrent: true,
+    unstable_hasDefault: true,
+  });
+
+  // Mix of explicit and shorthand — `circular` is shorthand (value = variable ref)
+  const attrs2 = useArrowNavigationGroup({
+    axis: 'horizontal',
+    circular,
+  });
+
+  return (
+    <div id={id} {...attrs} {...attrs2}>
+      <span>Navigation group</span>
+    </div>
+  );
+};
diff --git a/tools/cli/src/commands/report/__fixtures__/sample-app/src/mixed-imports.tsx b/tools/cli/src/commands/report/__fixtures__/sample-app/src/mixed-imports.tsx
new file mode 100644
index 0000000000000..5b664db9bcfb2
--- /dev/null
+++ b/tools/cli/src/commands/report/__fixtures__/sample-app/src/mixed-imports.tsx
@@ -0,0 +1,24 @@
+import React from 'react';
+import { FluentProvider, webLightTheme, Tooltip, useToastController } from '@proj/react-components';
+import { makeStyles } from '@griffel/react';
+
+const useStyles = makeStyles({
+  wrapper: {
+    padding: '20px',
+  },
+});
+
+export const App: React.FC<{ children: React.ReactNode }> = ({ children }) => {
+  const styles = useStyles();
+  const { dispatchToast } = useToastController();
+
+  return (
+    <FluentProvider theme={webLightTheme}>
+      <div className={styles.wrapper}>
+        <Tooltip content="App wrapper" relationship="description">
+          <span>{children}</span>
+        </Tooltip>
+      </div>
+    </FluentProvider>
+  );
+};
diff --git a/tools/cli/src/commands/report/__fixtures__/sample-app/src/path-alias-imports.tsx b/tools/cli/src/commands/report/__fixtures__/sample-app/src/path-alias-imports.tsx
new file mode 100644
index 0000000000000..2908ac565e5d4
--- /dev/null
+++ b/tools/cli/src/commands/report/__fixtures__/sample-app/src/path-alias-imports.tsx
@@ -0,0 +1,9 @@
+import React from 'react';
+import { AzureLightTheme } from '@sample/azure-theme';
+import { FluentProvider } from '@proj/react-components';
+
+export const ThemedApp = () => (
+  <FluentProvider theme={AzureLightTheme}>
+    <span>Hello</span>
+  </FluentProvider>
+);
diff --git a/tools/cli/src/commands/report/__fixtures__/sample-app/src/type-imports.ts b/tools/cli/src/commands/report/__fixtures__/sample-app/src/type-imports.ts
new file mode 100644
index 0000000000000..e28df445cd98f
--- /dev/null
+++ b/tools/cli/src/commands/report/__fixtures__/sample-app/src/type-imports.ts
@@ -0,0 +1,12 @@
+import type { ButtonProps, InputProps } from '@proj/react-components';
+import type { FluentIcon } from '@proj/react-icons';
+
+export type CustomButtonProps = ButtonProps & {
+  tooltip?: string;
+};
+
+export type SearchInputProps = InputProps & {
+  onSearch?: (value: string) => void;
+};
+
+export type IconType = FluentIcon;
diff --git a/tools/cli/src/commands/report/__fixtures__/sample-app/src/type-refs.tsx b/tools/cli/src/commands/report/__fixtures__/sample-app/src/type-refs.tsx
new file mode 100644
index 0000000000000..c3bfc266df3e4
--- /dev/null
+++ b/tools/cli/src/commands/report/__fixtures__/sample-app/src/type-refs.tsx
@@ -0,0 +1,20 @@
+import { Button, FluentProvider } from '@proj/react-components';
+import type { ButtonProps, ColumnDef } from '@proj/react-components';
+
+type MyButtonProps = ButtonProps & {
+  tooltip?: string;
+};
+
+const meta: { component: typeof Button } = {
+  component: Button,
+};
+
+// Generic type usage — ColumnDef with type argument
+type UserColumn = ColumnDef<{ name: string; age: number }>;
+type ProductColumn = ColumnDef<{ id: number; price: number }>;
+
+export const App = () => (
+  <FluentProvider>
+    <Button>Click</Button>
+  </FluentProvider>
+);
diff --git a/tools/cli/src/commands/report/__fixtures__/sample-app/tsconfig.json b/tools/cli/src/commands/report/__fixtures__/sample-app/tsconfig.json
new file mode 100644
index 0000000000000..a8780a6af0f91
--- /dev/null
+++ b/tools/cli/src/commands/report/__fixtures__/sample-app/tsconfig.json
@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "moduleResolution": "node",
+    "jsx": "react-jsx",
+    "strict": true,
+    "esModuleInterop": true,
+    "baseUrl": ".",
+    "paths": {
+      "@sample/azure-theme": ["packages/azure-theme/src/index.ts"],
+      "@proj/react-components": ["_mock_node_modules/@proj/react-components/index.d.ts"],
+      "react": ["_mock_node_modules/@types/react/index.d.ts"]
+    },
+    "typeRoots": []
+  },
+  "include": ["src/**/*"]
+}
diff --git a/tools/cli/src/commands/report/commands/info.spec.ts b/tools/cli/src/commands/report/commands/info.spec.ts
new file mode 100644
index 0000000000000..bb865f436baac
--- /dev/null
+++ b/tools/cli/src/commands/report/commands/info.spec.ts
@@ -0,0 +1,27 @@
+jest.mock('../impl/info-report', () => ({
+  runInfoReport: jest.fn().mockResolvedValue(undefined),
+}));
+
+describe('report info command', () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+  });
+
+  it('should call runInfoReport with no output', async () => {
+    const infoCommand = (await import('./info')).default;
+
+    await (infoCommand.handler as Function)({ _: ['report', 'info'], $0: 'fluentui-cli' });
+
+    const { runInfoReport } = require('../impl/info-report');
+    expect(runInfoReport).toHaveBeenCalledWith(undefined);
+  });
+
+  it('should pass output to runInfoReport', async () => {
+    const infoCommand = (await import('./info')).default;
+
+    await (infoCommand.handler as Function)({ _: ['report', 'info'], $0: 'fluentui-cli', output: 'info.txt' });
+
+    const { runInfoReport } = require('../impl/info-report');
+    expect(runInfoReport).toHaveBeenCalledWith('info.txt');
+  });
+});
diff --git a/tools/cli/src/commands/report/commands/info.ts b/tools/cli/src/commands/report/commands/info.ts
new file mode 100644
index 0000000000000..981477821ec41
--- /dev/null
+++ b/tools/cli/src/commands/report/commands/info.ts
@@ -0,0 +1,23 @@
+import type { CommandModule } from 'yargs';
+
+import type { InfoArgs } from '../impl/types';
+
+const infoCommand: CommandModule<{}, InfoArgs> = {
+  command: 'info',
+  describe: 'Quick package & environment summary for issue reporting',
+  builder: yargs =>
+    yargs
+      .option('output', {
+        alias: 'o',
+        type: 'string',
+        describe: 'Output file path (default: stdout)',
+      })
+      .version(false)
+      .help(),
+  handler: async argv => {
+    const { runInfoReport } = await import('../impl/info-report');
+    return runInfoReport(argv.output);
+  },
+};
+
+export default infoCommand;
diff --git a/tools/cli/src/commands/report/commands/usage.spec.ts b/tools/cli/src/commands/report/commands/usage.spec.ts
new file mode 100644
index 0000000000000..d831d8060a3e2
--- /dev/null
+++ b/tools/cli/src/commands/report/commands/usage.spec.ts
@@ -0,0 +1,78 @@
+jest.mock('../impl/usage-report', () => ({
+  runUsageReport: jest.fn().mockResolvedValue(undefined),
+}));
+
+describe('report usage command', () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+  });
+
+  it('should call runUsageReport with default args', async () => {
+    const usageCommand = (await import('./usage')).default;
+
+    await (usageCommand.handler as Function)({
+      _: ['report', 'usage'],
+      $0: 'fluentui-cli',
+      reporter: 'json',
+    });
+
+    const { runUsageReport } = require('../impl/usage-report');
+    expect(runUsageReport).toHaveBeenCalledWith(undefined, 'json', undefined, undefined, undefined);
+  });
+
+  it('should pass path and reporter to runUsageReport', async () => {
+    const usageCommand = (await import('./usage')).default;
+
+    await (usageCommand.handler as Function)({
+      _: ['report', 'usage'],
+      $0: 'fluentui-cli',
+      path: '/some/path',
+      reporter: 'markdown',
+    });
+
+    const { runUsageReport } = require('../impl/usage-report');
+    expect(runUsageReport).toHaveBeenCalledWith('/some/path', 'markdown', undefined, undefined, undefined);
+  });
+
+  it('should pass html reporter to runUsageReport', async () => {
+    const usageCommand = (await import('./usage')).default;
+
+    await (usageCommand.handler as Function)({
+      _: ['report', 'usage'],
+      $0: 'fluentui-cli',
+      reporter: 'html',
+    });
+
+    const { runUsageReport } = require('../impl/usage-report');
+    expect(runUsageReport).toHaveBeenCalledWith(undefined, 'html', undefined, undefined, undefined);
+  });
+
+  it('should pass include and exclude to runUsageReport', async () => {
+    const usageCommand = (await import('./usage')).default;
+
+    await (usageCommand.handler as Function)({
+      _: ['report', 'usage'],
+      $0: 'fluentui-cli',
+      reporter: 'json',
+      include: ['src/**'],
+      exclude: ['**/*.test.*'],
+    });
+
+    const { runUsageReport } = require('../impl/usage-report');
+    expect(runUsageReport).toHaveBeenCalledWith(undefined, 'json', ['src/**'], ['**/*.test.*'], undefined);
+  });
+
+  it('should pass output to runUsageReport', async () => {
+    const usageCommand = (await import('./usage')).default;
+
+    await (usageCommand.handler as Function)({
+      _: ['report', 'usage'],
+      $0: 'fluentui-cli',
+      reporter: 'json',
+      output: 'report.json',
+    });
+
+    const { runUsageReport } = require('../impl/usage-report');
+    expect(runUsageReport).toHaveBeenCalledWith(undefined, 'json', undefined, undefined, 'report.json');
+  });
+});
diff --git a/tools/cli/src/commands/report/commands/usage.ts b/tools/cli/src/commands/report/commands/usage.ts
new file mode 100644
index 0000000000000..9aabdb9861fea
--- /dev/null
+++ b/tools/cli/src/commands/report/commands/usage.ts
@@ -0,0 +1,45 @@
+import type { CommandModule } from 'yargs';
+
+import type { UsageArgs } from '../impl/types';
+
+const usageCommand: CommandModule<{}, UsageArgs> = {
+  command: 'usage',
+  describe: 'Deep codebase usage analysis of Fluent UI APIs',
+  builder: yargs =>
+    yargs
+      .option('path', {
+        alias: 'p',
+        type: 'string',
+        describe: 'Root path for file traversal (defaults to git root)',
+      })
+      .option('reporter', {
+        alias: 'r',
+        type: 'string',
+        choices: ['json', 'markdown', 'html'] as const,
+        default: 'json' as const,
+        describe: 'Output format',
+      })
+      .option('include', {
+        type: 'string',
+        array: true,
+        describe: 'Glob patterns to include files',
+      })
+      .option('exclude', {
+        type: 'string',
+        array: true,
+        describe: 'Glob patterns to exclude files',
+      })
+      .option('output', {
+        alias: 'o',
+        type: 'string',
+        describe: 'Output file path (default: stdout)',
+      })
+      .version(false)
+      .help(),
+  handler: async argv => {
+    const { runUsageReport } = await import('../impl/usage-report');
+    return runUsageReport(argv.path, argv.reporter, argv.include, argv.exclude, argv.output);
+  },
+};
+
+export default usageCommand;
diff --git a/tools/cli/src/commands/report/handler.spec.ts b/tools/cli/src/commands/report/handler.spec.ts
deleted file mode 100644
index 8a1f84a0ac420..0000000000000
--- a/tools/cli/src/commands/report/handler.spec.ts
+++ /dev/null
@@ -1,19 +0,0 @@
-import { handler } from './handler';
-
-describe('report handler', () => {
-  let logSpy: jest.SpyInstance;
-
-  beforeEach(() => {
-    logSpy = jest.spyOn(console, 'log').mockImplementation();
-  });
-
-  afterEach(() => {
-    logSpy.mockRestore();
-  });
-
-  it('should execute without errors', async () => {
-    await handler({ _: ['report'], $0: 'fluentui-cli' });
-
-    expect(logSpy).toHaveBeenCalledWith('report command - not yet implemented');
-  });
-});
diff --git a/tools/cli/src/commands/report/handler.ts b/tools/cli/src/commands/report/handler.ts
deleted file mode 100644
index 04d6841efdb8e..0000000000000
--- a/tools/cli/src/commands/report/handler.ts
+++ /dev/null
@@ -1,6 +0,0 @@
-import type { CommandHandler } from '../../utils/types';
-
-export const handler: CommandHandler = async argv => {
-  // TODO: Implement report command
-  console.log('report command - not yet implemented');
-};
diff --git a/tools/cli/src/commands/report/impl/ast-parser.spec.ts b/tools/cli/src/commands/report/impl/ast-parser.spec.ts
new file mode 100644
index 0000000000000..d8ec7ce196934
--- /dev/null
+++ b/tools/cli/src/commands/report/impl/ast-parser.spec.ts
@@ -0,0 +1,344 @@
+import * as path from 'node:path';
+
+import { TsMorphAstParser } from './ast-parser';
+
+const FIXTURES_DIR = path.join(__dirname, '..', '__fixtures__', 'sample-app', 'src');
+const FIXTURES_ROOT = path.join(__dirname, '..', '__fixtures__', 'sample-app');
+const TSCONFIG_PATH = path.join(FIXTURES_ROOT, 'tsconfig.json');
+
+describe('TsMorphAstParser', () => {
+  let parser: TsMorphAstParser;
+
+  beforeAll(() => {
+    parser = new TsMorphAstParser();
+    parser.createProject(
+      [
+        path.join(FIXTURES_DIR, 'basic-usage.tsx'),
+        path.join(FIXTURES_DIR, 'type-imports.ts'),
+        path.join(FIXTURES_DIR, 'mixed-imports.tsx'),
+        path.join(FIXTURES_DIR, 'type-refs.tsx'),
+      ],
+      TSCONFIG_PATH,
+    );
+  });
+
+  describe('getSourceFiles', () => {
+    it('should return all added source files', () => {
+      const files = parser.getSourceFiles();
+      expect(files).toHaveLength(4);
+      expect(files.some(f => f.endsWith('basic-usage.tsx'))).toBe(true);
+      expect(files.some(f => f.endsWith('type-imports.ts'))).toBe(true);
+      expect(files.some(f => f.endsWith('mixed-imports.tsx'))).toBe(true);
+      expect(files.some(f => f.endsWith('type-refs.tsx'))).toBe(true);
+    });
+
+    it('should not include resolved dependency files (e.g., .d.ts from node_modules)', () => {
+      const files = parser.getSourceFiles();
+      const dtsFiles = files.filter(f => f.endsWith('.d.ts'));
+      const nodeModulesFiles = files.filter(f => f.includes('node_modules'));
+      expect(dtsFiles).toHaveLength(0);
+      expect(nodeModulesFiles).toHaveLength(0);
+    });
+  });
+
+  describe('getImportDeclarations', () => {
+    it('should extract named imports from basic-usage.tsx', () => {
+      const filePath = path.join(FIXTURES_DIR, 'basic-usage.tsx');
+      const imports = parser.getImportDeclarations(filePath);
+
+      const fluentImport = imports.find(i => i.moduleSpecifier === '@proj/react-components' && !i.isTypeOnly);
+      expect(fluentImport).toBeDefined();
+      expect(fluentImport!.namedImports).toEqual(expect.arrayContaining(['Button', 'Input', 'makeStyles', 'tokens']));
+    });
+
+    it('should detect type-only imports from type-imports.ts', () => {
+      const filePath = path.join(FIXTURES_DIR, 'type-imports.ts');
+      const imports = parser.getImportDeclarations(filePath);
+
+      const typeImport = imports.find(i => i.moduleSpecifier === '@proj/react-components');
+      expect(typeImport).toBeDefined();
+      expect(typeImport!.isTypeOnly).toBe(true);
+      expect(typeImport!.namedImports).toEqual(expect.arrayContaining(['ButtonProps', 'InputProps']));
+    });
+
+    it('should extract imports from @proj/react-icons', () => {
+      const filePath = path.join(FIXTURES_DIR, 'basic-usage.tsx');
+      const imports = parser.getImportDeclarations(filePath);
+
+      const iconsImport = imports.find(i => i.moduleSpecifier === '@proj/react-icons');
+      expect(iconsImport).toBeDefined();
+      expect(iconsImport!.namedImports).toContain('SearchRegular');
+    });
+
+    it('should return empty array for unknown file', () => {
+      const imports = parser.getImportDeclarations('/nonexistent/file.ts');
+      expect(imports).toEqual([]);
+    });
+  });
+
+  describe('getJsxElementUsages', () => {
+    it('should detect JSX component usages with props', () => {
+      const filePath = path.join(FIXTURES_DIR, 'basic-usage.tsx');
+      const usages = parser.getJsxElementUsages(filePath);
+
+      const buttonUsages = usages.filter(u => u.componentName === 'Button');
+      expect(buttonUsages.length).toBeGreaterThanOrEqual(2);
+
+      const primaryButton = buttonUsages.find(u => u.props.appearance === 'primary');
+      expect(primaryButton).toBeDefined();
+      expect(primaryButton!.moduleSpecifier).toBe('@proj/react-components');
+      expect(primaryButton!.props.size).toBe('medium');
+    });
+
+    it('should detect Input component with props', () => {
+      const filePath = path.join(FIXTURES_DIR, 'basic-usage.tsx');
+      const usages = parser.getJsxElementUsages(filePath);
+
+      const inputUsages = usages.filter(u => u.componentName === 'Input');
+      expect(inputUsages).toHaveLength(1);
+      expect(inputUsages[0].props.placeholder).toBe('Search...');
+      expect(inputUsages[0].props.appearance).toBe('outline');
+    });
+
+    it('should detect components from mixed-imports.tsx', () => {
+      const filePath = path.join(FIXTURES_DIR, 'mixed-imports.tsx');
+      const usages = parser.getJsxElementUsages(filePath);
+
+      const fluentProvider = usages.find(u => u.componentName === 'FluentProvider');
+      expect(fluentProvider).toBeDefined();
+      expect(fluentProvider!.moduleSpecifier).toBe('@proj/react-components');
+
+      const tooltip = usages.find(u => u.componentName === 'Tooltip');
+      expect(tooltip).toBeDefined();
+      expect(tooltip!.props.content).toBe('App wrapper');
+      expect(tooltip!.props.relationship).toBe('description');
+    });
+
+    it('should return empty array for file without JSX', () => {
+      const filePath = path.join(FIXTURES_DIR, 'type-imports.ts');
+      const usages = parser.getJsxElementUsages(filePath);
+      expect(usages).toEqual([]);
+    });
+  });
+
+  describe('getCallExpressionUsages', () => {
+    it('should detect hook calls in basic-usage.tsx', () => {
+      const filePath = path.join(FIXTURES_DIR, 'basic-usage.tsx');
+      const calls = parser.getCallExpressionUsages(filePath);
+
+      const useIdCall = calls.find(c => c.functionName === 'useId');
+      expect(useIdCall).toBeDefined();
+      expect(useIdCall!.moduleSpecifier).toBe('@proj/react-components');
+    });
+
+    it('should detect function calls in mixed-imports.tsx', () => {
+      const filePath = path.join(FIXTURES_DIR, 'mixed-imports.tsx');
+      const calls = parser.getCallExpressionUsages(filePath);
+
+      const makeStylesCall = calls.find(c => c.functionName === 'makeStyles');
+      expect(makeStylesCall).toBeDefined();
+      expect(makeStylesCall!.moduleSpecifier).toBe('@griffel/react');
+    });
+  });
+
+  describe('getTypeReferenceUsages', () => {
+    it('should detect typeof references', () => {
+      const filePath = path.join(FIXTURES_DIR, 'type-refs.tsx');
+      const usages = parser.getTypeReferenceUsages(filePath);
+
+      const typeofButton = usages.find(u => u.symbolName === 'Button' && u.kind === 'typeof');
+      expect(typeofButton).toBeDefined();
+      expect(typeofButton!.moduleSpecifier).toBe('@proj/react-components');
+    });
+
+    it('should detect generic type references with type arguments', () => {
+      const filePath = path.join(FIXTURES_DIR, 'type-refs.tsx');
+      const usages = parser.getTypeReferenceUsages(filePath);
+
+      const genericUsages = usages.filter(u => u.symbolName === 'ColumnDef' && u.kind === 'generic');
+      expect(genericUsages).toHaveLength(2);
+      expect(genericUsages[0].moduleSpecifier).toBe('@proj/react-components');
+      expect(genericUsages[0].typeArgs).toBeDefined();
+      expect(genericUsages[0].typeArgs!.length).toBe(1);
+    });
+
+    it('should return empty for file without type references', () => {
+      const filePath = path.join(FIXTURES_DIR, 'type-imports.ts');
+      const usages = parser.getTypeReferenceUsages(filePath);
+
+      // type-imports.ts only has `import type` but no typeof or generic usage
+      const typeofUsages = usages.filter(u => u.kind === 'typeof');
+      expect(typeofUsages).toHaveLength(0);
+    });
+  });
+
+  describe('getValueReferenceUsages', () => {
+    it('should detect value references to imported symbols', () => {
+      const filePath = path.join(FIXTURES_DIR, 'type-refs.tsx');
+      const usages = parser.getValueReferenceUsages(filePath);
+
+      // Button is used as a value in `component: Button`
+      const buttonRef = usages.find(u => u.symbolName === 'Button');
+      expect(buttonRef).toBeDefined();
+      expect(buttonRef!.moduleSpecifier).toBe('@proj/react-components');
+    });
+
+    it('should not include JSX tag names in value references', () => {
+      const filePath = path.join(FIXTURES_DIR, 'basic-usage.tsx');
+      const usages = parser.getValueReferenceUsages(filePath);
+
+      // Button and Input are used as JSX, not value references (except contentBefore={<SearchRegular />} style)
+      // JSX tag names should be excluded
+      const buttonJsxRef = usages.filter(u => u.symbolName === 'Button');
+      // Button only appears in JSX tags, should not be in value refs
+      expect(buttonJsxRef).toHaveLength(0);
+    });
+  });
+
+  describe('classifySymbol', () => {
+    it('should classify function components returning JSX as "component"', () => {
+      const filePath = path.join(FIXTURES_DIR, 'basic-usage.tsx');
+
+      expect(parser.classifySymbol(filePath, 'Button', '@proj/react-components')).toBe('component');
+      expect(parser.classifySymbol(filePath, 'Input', '@proj/react-components')).toBe('component');
+    });
+
+    it('should classify hooks as "hook"', () => {
+      const filePath = path.join(FIXTURES_DIR, 'basic-usage.tsx');
+
+      expect(parser.classifySymbol(filePath, 'useId', '@proj/react-components')).toBe('hook');
+    });
+
+    it('should classify interfaces/types as "type"', () => {
+      const filePath = path.join(FIXTURES_DIR, 'type-imports.ts');
+
+      expect(parser.classifySymbol(filePath, 'ButtonProps', '@proj/react-components')).toBe('type');
+      expect(parser.classifySymbol(filePath, 'InputProps', '@proj/react-components')).toBe('type');
+    });
+
+    it('should classify constants as "other" even if PascalCase', () => {
+      const filePath = path.join(FIXTURES_DIR, 'mixed-imports.tsx');
+
+      expect(parser.classifySymbol(filePath, 'webLightTheme', '@proj/react-components')).toBe('other');
+    });
+
+    it('should classify hooks from mixed imports correctly', () => {
+      const filePath = path.join(FIXTURES_DIR, 'mixed-imports.tsx');
+
+      expect(parser.classifySymbol(filePath, 'useToastController', '@proj/react-components')).toBe('hook');
+    });
+
+    it('should fall back to "unknown" for unresolvable symbols', () => {
+      const filePath = path.join(FIXTURES_DIR, 'basic-usage.tsx');
+
+      // Symbol not imported in this file
+      expect(parser.classifySymbol(filePath, 'NonExistent', 'non-existent-module')).toBe('unknown');
+    });
+
+    it('should classify unresolvable symbols as "unknown" instead of guessing', () => {
+      const filePath = path.join(FIXTURES_DIR, 'basic-usage.tsx');
+
+      // These use fallback since they may not resolve from the import
+      // The fallback now returns 'unknown' for all unresolvable symbols
+      const freshParser = new TsMorphAstParser();
+      freshParser.createProject([path.join(FIXTURES_DIR, 'basic-usage.tsx')]);
+
+      expect(freshParser.classifySymbol(filePath, 'CustomButtonProps', 'nonexistent-module')).toBe('unknown');
+      expect(freshParser.classifySymbol(filePath, 'IColor', 'nonexistent-module')).toBe('unknown');
+      expect(freshParser.classifySymbol(filePath, 'RowRenderer', 'nonexistent-module')).toBe('unknown');
+      expect(freshParser.classifySymbol(filePath, 'AzureLightTheme', 'nonexistent-module')).toBe('unknown');
+    });
+  });
+
+  describe('error handling', () => {
+    it('should throw if createProject was not called', () => {
+      const freshParser = new TsMorphAstParser();
+      expect(() => freshParser.getSourceFiles()).toThrow('call createProject()');
+    });
+  });
+
+  describe('describeUnknownSymbol', () => {
+    it('should describe hook-like names', () => {
+      expect(parser.describeUnknownSymbol('useCustomHook')).toBe('Likely a React hook (use* naming convention)');
+    });
+
+    it('should describe type-like names with known suffixes', () => {
+      expect(parser.describeUnknownSymbol('ButtonProps')).toBe('Likely a type/interface (*Props naming convention)');
+      expect(parser.describeUnknownSymbol('RowRenderer')).toBe('Likely a type/interface (*Renderer naming convention)');
+    });
+
+    it('should describe I-prefixed names as interfaces', () => {
+      expect(parser.describeUnknownSymbol('IColor')).toBe('Likely an interface (I* naming convention)');
+    });
+
+    it('should describe PascalCase names generically', () => {
+      expect(parser.describeUnknownSymbol('AzureLightTheme')).toBe(
+        'PascalCase symbol — could be a component, constant, or type',
+      );
+    });
+
+    it('should return default description for other names', () => {
+      expect(parser.describeUnknownSymbol('someThing')).toBe('Unresolved symbol — .d.ts not available');
+    });
+  });
+
+  describe('hook argument value extraction', () => {
+    let hookParser: TsMorphAstParser;
+
+    beforeAll(() => {
+      hookParser = new TsMorphAstParser();
+      hookParser.createProject([path.join(FIXTURES_DIR, 'hook-args.tsx')], TSCONFIG_PATH);
+    });
+
+    it('should extract literal property values from hook calls, not property names', () => {
+      const filePath = path.join(FIXTURES_DIR, 'hook-args.tsx');
+      const calls = hookParser.getCallExpressionUsages(filePath);
+
+      const navCalls = calls.filter(c => c.functionName === 'useArrowNavigationGroup');
+      expect(navCalls.length).toBe(2);
+
+      // First call: useArrowNavigationGroup({ axis: 'vertical', memorizeCurrent: true, unstable_hasDefault: true })
+      const firstCall = navCalls[0];
+      expect(firstCall.args.axis).toBe("'vertical'");
+      expect(firstCall.args.memorizeCurrent).toBe('true');
+      expect(firstCall.args.unstable_hasDefault).toBe('true');
+
+      // Second call: useArrowNavigationGroup({ axis: 'horizontal', circular })
+      const secondCall = navCalls[1];
+      expect(secondCall.args.axis).toBe("'horizontal'");
+      // Shorthand property: value is the variable name (can't statically resolve)
+      expect(secondCall.args.circular).toBe('circular');
+    });
+
+    it('should not return resolved .d.ts files from getSourceFiles', () => {
+      const files = hookParser.getSourceFiles();
+      expect(files).toHaveLength(1);
+      expect(files[0]).toContain('hook-args.tsx');
+    });
+  });
+
+  describe('path alias resolution', () => {
+    let aliasParser: TsMorphAstParser;
+
+    beforeAll(() => {
+      aliasParser = new TsMorphAstParser();
+      aliasParser.createProject([path.join(FIXTURES_DIR, 'path-alias-imports.tsx')], TSCONFIG_PATH);
+    });
+
+    it('should classify path-aliased symbols resolving to .ts source as "unknown"', () => {
+      const filePath = path.join(FIXTURES_DIR, 'path-alias-imports.tsx');
+
+      // Path aliases resolve to .ts source files, not .d.ts — classified as unknown
+      const result = aliasParser.classifySymbol(filePath, 'AzureLightTheme', '@sample/azure-theme');
+      expect(result).toBe('unknown');
+    });
+
+    it('should still resolve .d.ts-based symbols correctly', () => {
+      const filePath = path.join(FIXTURES_DIR, 'path-alias-imports.tsx');
+
+      // FluentProvider comes from node_modules .d.ts — should resolve as component
+      const result = aliasParser.classifySymbol(filePath, 'FluentProvider', '@proj/react-components');
+      expect(result).toBe('component');
+    });
+  });
+});
diff --git a/tools/cli/src/commands/report/impl/ast-parser.ts b/tools/cli/src/commands/report/impl/ast-parser.ts
new file mode 100644
index 0000000000000..0a63033cbfc54
--- /dev/null
+++ b/tools/cli/src/commands/report/impl/ast-parser.ts
@@ -0,0 +1,567 @@
+import {
+  Project,
+  SyntaxKind,
+  Node,
+  type SourceFile,
+  type JsxOpeningElement,
+  type JsxSelfClosingElement,
+} from 'ts-morph';
+
+import type {
+  AstParser,
+  ImportInfo,
+  JsxUsageInfo,
+  CallUsageInfo,
+  SymbolClassification,
+  TypeRefUsageInfo,
+} from './types';
+
+/** Type names that indicate a JSX return type. */
+const JSX_TYPE_NAMES = new Set([
+  'Element',
+  'ReactElement',
+  'ReactNode',
+  'JSX.Element',
+  'React.ReactElement',
+  'React.ReactNode',
+]);
+
+/** Name patterns that strongly suggest a pure type (interface/type alias). */
+const TYPE_NAME_SUFFIXES = [
+  'Props',
+  'State',
+  'Slots',
+  'Type',
+  'Data',
+  'Event',
+  'Handler',
+  'Params',
+  'Renderer',
+  'Element',
+  'Colors',
+  'Geometry',
+];
+
+/**
+ * ts-morph implementation of the AstParser interface.
+ * Can be replaced with raw TypeScript compiler API or another parser.
+ */
+export class TsMorphAstParser implements AstParser {
+  private project: Project | null = null;
+
+  /** Cache classification results per (moduleSpecifier::symbolName) for consistency across files. */
+  private classificationCache = new Map<string, SymbolClassification>();
+
+  /** The original user source file paths (excludes resolved dependencies). */
+  private userFilePaths = new Set<string>();
+
+  public createProject(filePaths: string[], tsConfigPath?: string, rootPath?: string): void {
+    if (tsConfigPath) {
+      this.project = new Project({ tsConfigFilePath: tsConfigPath, skipAddingFilesFromTsConfig: true });
+    } else {
+      this.project = new Project({
+        compilerOptions: {
+          jsx: 2 /* JsxEmit.React */,
+          allowJs: true,
+          moduleResolution: 2 /* ModuleResolutionKind.NodeJs */,
+          ...(rootPath ? { baseUrl: rootPath } : {}),
+        },
+        skipAddingFilesFromTsConfig: true,
+      });
+    }
+
+    this.project.addSourceFilesAtPaths(filePaths);
+
+    // Track which files are the user's source files before resolving dependencies
+    this.userFilePaths = new Set(this.project.getSourceFiles().map(sf => sf.getFilePath()));
+
+    // Resolve import dependencies so ts-morph can follow path aliases
+    // and node_modules .d.ts files for symbol classification.
+    this.project.resolveSourceFileDependencies();
+
+    this.classificationCache.clear();
+  }
+
+  public getSourceFiles(): string[] {
+    this._ensureProject();
+    // Only return user source files, not resolved library dependencies
+    return this.project!.getSourceFiles()
+      .map(sf => sf.getFilePath())
+      .filter(fp => this.userFilePaths.has(fp));
+  }
+
+  public getImportDeclarations(filePath: string): ImportInfo[] {
+    const sourceFile = this._getSourceFile(filePath);
+    if (!sourceFile) {
+      return [];
+    }
+
+    return sourceFile.getImportDeclarations().map(decl => {
+      const namedImports = decl.getNamedImports().map(ni => ni.getName());
+      const defaultImport = decl.getDefaultImport();
+      if (defaultImport) {
+        namedImports.unshift(defaultImport.getText());
+      }
+
+      return {
+        moduleSpecifier: decl.getModuleSpecifierValue(),
+        namedImports,
+        isTypeOnly: decl.isTypeOnly(),
+      };
+    });
+  }
+
+  public getJsxElementUsages(filePath: string): JsxUsageInfo[] {
+    const sourceFile = this._getSourceFile(filePath);
+    if (!sourceFile) {
+      return [];
+    }
+
+    const importMap = this._buildImportMap(sourceFile);
+    const usages: JsxUsageInfo[] = [];
+
+    // Collect JSX opening elements and self-closing elements
+    const openingElements = sourceFile.getDescendantsOfKind(SyntaxKind.JsxOpeningElement);
+    const selfClosingElements = sourceFile.getDescendantsOfKind(SyntaxKind.JsxSelfClosingElement);
+
+    for (const element of [...openingElements, ...selfClosingElements]) {
+      const tagName = element.getTagNameNode().getText();
+      const moduleSpecifier = importMap.get(tagName);
+
+      // Only track components that come from tracked imports (PascalCase)
+      if (moduleSpecifier && /^[A-Z]/.test(tagName)) {
+        const props = this._extractJsxProps(element);
+        usages.push({ componentName: tagName, props, moduleSpecifier });
+      }
+    }
+
+    return usages;
+  }
+
+  public getCallExpressionUsages(filePath: string): CallUsageInfo[] {
+    const sourceFile = this._getSourceFile(filePath);
+    if (!sourceFile) {
+      return [];
+    }
+
+    const importMap = this._buildImportMap(sourceFile);
+    const usages: CallUsageInfo[] = [];
+
+    const callExpressions = sourceFile.getDescendantsOfKind(SyntaxKind.CallExpression);
+
+    for (const call of callExpressions) {
+      const expression = call.getExpression();
+      const functionName = expression.getText();
+      const moduleSpecifier = importMap.get(functionName);
+
+      if (moduleSpecifier) {
+        const args = this._extractCallArgs(call);
+        usages.push({ functionName, args, moduleSpecifier });
+      }
+    }
+
+    return usages;
+  }
+
+  public getTypeReferenceUsages(filePath: string): TypeRefUsageInfo[] {
+    const sourceFile = this._getSourceFile(filePath);
+    if (!sourceFile) {
+      return [];
+    }
+
+    const importMap = this._buildImportMap(sourceFile);
+    const usages: TypeRefUsageInfo[] = [];
+
+    // Track typeof X in type positions (TypeQuery nodes)
+    const typeQueries = sourceFile.getDescendantsOfKind(SyntaxKind.TypeQuery);
+    for (const tq of typeQueries) {
+      const exprName = tq.getExprName().getText();
+      const moduleSpecifier = importMap.get(exprName);
+      if (moduleSpecifier) {
+        usages.push({ symbolName: exprName, moduleSpecifier, kind: 'typeof' });
+      }
+    }
+
+    // Track type references with generics (e.g., RowRenderer<Item>)
+    const typeRefs = sourceFile.getDescendantsOfKind(SyntaxKind.TypeReference);
+    for (const tr of typeRefs) {
+      const typeName = tr.getTypeName().getText();
+      const moduleSpecifier = importMap.get(typeName);
+      if (moduleSpecifier) {
+        const typeArgs = tr.getTypeArguments().map(ta => ta.getText());
+        if (typeArgs.length > 0) {
+          usages.push({ symbolName: typeName, moduleSpecifier, kind: 'generic', typeArgs });
+        }
+      }
+    }
+
+    return usages;
+  }
+
+  public getValueReferenceUsages(filePath: string): Array<{ symbolName: string; moduleSpecifier: string }> {
+    const sourceFile = this._getSourceFile(filePath);
+    if (!sourceFile) {
+      return [];
+    }
+
+    const importMap = this._buildImportMap(sourceFile);
+    const usages: Array<{ symbolName: string; moduleSpecifier: string }> = [];
+
+    const identifiers = sourceFile.getDescendantsOfKind(SyntaxKind.Identifier);
+
+    for (const ident of identifiers) {
+      const name = ident.getText();
+      const moduleSpecifier = importMap.get(name);
+      if (!moduleSpecifier) {
+        continue;
+      }
+
+      const parent = ident.getParent();
+      if (!parent) {
+        continue;
+      }
+
+      // Skip identifiers that are part of import declarations
+      if (ident.getFirstAncestorByKind(SyntaxKind.ImportDeclaration)) {
+        continue;
+      }
+
+      // Skip JSX tag names (already tracked by getJsxElementUsages)
+      const parentKind = parent.getKind();
+      if (
+        parentKind === SyntaxKind.JsxOpeningElement ||
+        parentKind === SyntaxKind.JsxSelfClosingElement ||
+        parentKind === SyntaxKind.JsxClosingElement
+      ) {
+        continue;
+      }
+
+      // Skip call expression callees (already tracked by getCallExpressionUsages)
+      if (parentKind === SyntaxKind.CallExpression) {
+        const callExpr = parent.asKind(SyntaxKind.CallExpression)!;
+        if (callExpr.getExpression() === ident) {
+          continue;
+        }
+      }
+
+      // Skip type positions (typeof, type annotations, etc.)
+      if (ident.getFirstAncestorByKind(SyntaxKind.TypeQuery)) {
+        continue;
+      }
+      if (ident.getFirstAncestorByKind(SyntaxKind.TypeReference)) {
+        continue;
+      }
+
+      usages.push({ symbolName: name, moduleSpecifier });
+    }
+
+    return usages;
+  }
+
+  public classifySymbol(filePath: string, symbolName: string, moduleSpecifier: string): SymbolClassification {
+    // Check cache first for consistency across files
+    const cacheKey = `${moduleSpecifier}::${symbolName}`;
+    const cached = this.classificationCache.get(cacheKey);
+    if (cached) {
+      return cached;
+    }
+
+    // Quick hook check by naming convention (reliable enough)
+    if (/^use[A-Z]/.test(symbolName)) {
+      this.classificationCache.set(cacheKey, 'hook');
+      return 'hook';
+    }
+
+    const sourceFile = this._getSourceFile(filePath);
+    if (!sourceFile) {
+      const result = this._fallbackClassify(symbolName);
+      this.classificationCache.set(cacheKey, result);
+      return result;
+    }
+
+    // Find the import declaration that imports this symbol from the given module
+    const importDecl = sourceFile.getImportDeclarations().find(d => d.getModuleSpecifierValue() === moduleSpecifier);
+    if (!importDecl) {
+      const result = this._fallbackClassify(symbolName);
+      this.classificationCache.set(cacheKey, result);
+      return result;
+    }
+
+    // Try to resolve the symbol via the type checker
+    try {
+      const namedImport = importDecl.getNamedImports().find(ni => {
+        const alias = ni.getAliasNode();
+        return alias ? alias.getText() === symbolName : ni.getName() === symbolName;
+      });
+
+      if (!namedImport) {
+        const defaultImport = importDecl.getDefaultImport();
+        if (defaultImport && defaultImport.getText() === symbolName) {
+          const result = this._classifyFromNode(defaultImport, symbolName);
+          this.classificationCache.set(cacheKey, result);
+          return result;
+        }
+        const result = this._fallbackClassify(symbolName);
+        this.classificationCache.set(cacheKey, result);
+        return result;
+      }
+
+      const result = this._classifyFromNode(namedImport, symbolName);
+      this.classificationCache.set(cacheKey, result);
+      return result;
+    } catch {
+      const result = this._fallbackClassify(symbolName);
+      this.classificationCache.set(cacheKey, result);
+      return result;
+    }
+  }
+
+  /**
+   * Generate a description for an unknown symbol based on naming conventions.
+   * Used when .d.ts resolution failed and the symbol is classified as 'unknown'.
+   */
+  public describeUnknownSymbol(symbolName: string): string {
+    if (/^use[A-Z]/.test(symbolName)) {
+      return 'Likely a React hook (use* naming convention)';
+    }
+
+    for (const suffix of TYPE_NAME_SUFFIXES) {
+      if (symbolName.endsWith(suffix) && symbolName.length > suffix.length) {
+        return `Likely a type/interface (*${suffix} naming convention)`;
+      }
+    }
+
+    if (/^I[A-Z]/.test(symbolName) && symbolName.length > 2) {
+      return 'Likely an interface (I* naming convention)';
+    }
+
+    if (/^[A-Z]/.test(symbolName)) {
+      return 'PascalCase symbol — could be a component, constant, or type';
+    }
+
+    return 'Unresolved symbol — .d.ts not available';
+  }
+
+  // ---- Private helpers ----
+
+  /**
+   * Classify a symbol by resolving its declaration from an AST node.
+   */
+  private _classifyFromNode(node: Node, symbolName: string): SymbolClassification {
+    try {
+      const symbol = node.getSymbol();
+      if (!symbol) {
+        return this._fallbackClassify(symbolName);
+      }
+
+      // Follow aliases to the actual declaration
+      const aliased = symbol.getAliasedSymbol() ?? symbol;
+      const declarations = aliased.getDeclarations();
+
+      if (declarations.length === 0) {
+        return this._fallbackClassify(symbolName);
+      }
+
+      // Only classify from .d.ts declarations.
+      // If resolved declarations come from non-.d.ts files (e.g., .ts/.tsx source
+      // in symlinked node_modules), treat as unknown — we only trust type declarations.
+      const dtsDeclarations = declarations.filter(d => d.getSourceFile().getFilePath().endsWith('.d.ts'));
+      if (dtsDeclarations.length === 0) {
+        return this._fallbackClassify(symbolName);
+      }
+
+      return this._classifyFromDeclarations(dtsDeclarations, symbolName);
+    } catch {
+      return this._fallbackClassify(symbolName);
+    }
+  }
+
+  /**
+   * Classify a symbol from its resolved declarations.
+   */
+  private _classifyFromDeclarations(
+    declarations: ReadonlyArray<import('ts-morph').Node>,
+    symbolName: string,
+  ): SymbolClassification {
+    for (const decl of declarations) {
+      // Pure type: interface or type alias
+      if (Node.isInterfaceDeclaration(decl) || Node.isTypeAliasDeclaration(decl)) {
+        return 'type';
+      }
+
+      // Function declaration: check return type
+      if (Node.isFunctionDeclaration(decl)) {
+        if (this._returnsJsx(decl.getReturnType().getText())) {
+          return 'component';
+        }
+        continue;
+      }
+
+      // Variable declaration (const MyComponent: FC = ...) or arrow function
+      if (Node.isVariableDeclaration(decl)) {
+        const typeText = decl.getType().getText();
+        // Check for React.FC, React.ForwardRefExoticComponent, etc.
+        if (this._isReactComponentType(typeText)) {
+          return 'component';
+        }
+        // Check if the initializer is an arrow function that returns JSX
+        const init = decl.getInitializer();
+        if (init && (Node.isArrowFunction(init) || Node.isFunctionExpression(init))) {
+          if (this._returnsJsx(init.getReturnType().getText())) {
+            return 'component';
+          }
+        }
+        continue;
+      }
+
+      // Class declaration: check for render() method
+      if (Node.isClassDeclaration(decl)) {
+        const renderMethod = decl.getMethod('render');
+        if (renderMethod && this._returnsJsx(renderMethod.getReturnType().getText())) {
+          return 'component';
+        }
+        continue;
+      }
+
+      // Enum declaration — treat as type
+      if (Node.isEnumDeclaration(decl)) {
+        return 'type';
+      }
+    }
+
+    return 'other';
+  }
+
+  /**
+   * Check if a return type text indicates JSX.
+   */
+  private _returnsJsx(returnTypeText: string): boolean {
+    for (const jsxType of JSX_TYPE_NAMES) {
+      if (returnTypeText.includes(jsxType)) {
+        return true;
+      }
+    }
+    return false;
+  }
+
+  /**
+   * Check if a type text indicates a React component type (FC, ForwardRefExoticComponent, etc.).
+   */
+  private _isReactComponentType(typeText: string): boolean {
+    const componentTypePatterns = [
+      'React.FC',
+      'React.FunctionComponent',
+      'React.ForwardRefExoticComponent',
+      'ForwardRefComponent',
+      'FC<',
+      'FunctionComponent<',
+      'ForwardRefExoticComponent<',
+    ];
+    return componentTypePatterns.some(p => typeText.includes(p));
+  }
+
+  /**
+   * Fallback when type resolution is unavailable — returns 'unknown'.
+   */
+  private _fallbackClassify(_name: string): SymbolClassification {
+    return 'unknown';
+  }
+
+  private _ensureProject(): void {
+    if (!this.project) {
+      throw new Error('AstParser: call createProject() before using the parser');
+    }
+  }
+
+  private _getSourceFile(filePath: string): SourceFile | undefined {
+    this._ensureProject();
+    return this.project!.getSourceFile(filePath);
+  }
+
+  /**
+   * Build a map from imported identifier name to its module specifier.
+   */
+  private _buildImportMap(sourceFile: SourceFile): Map<string, string> {
+    const map = new Map<string, string>();
+
+    for (const decl of sourceFile.getImportDeclarations()) {
+      const moduleSpec = decl.getModuleSpecifierValue();
+
+      const defaultImport = decl.getDefaultImport();
+      if (defaultImport) {
+        map.set(defaultImport.getText(), moduleSpec);
+      }
+
+      for (const named of decl.getNamedImports()) {
+        const alias = named.getAliasNode();
+        map.set(alias ? alias.getText() : named.getName(), moduleSpec);
+      }
+    }
+
+    return map;
+  }
+
+  /**
+   * Extract props from a JSX element as key-value pairs.
+   */
+  private _extractJsxProps(element: JsxOpeningElement | JsxSelfClosingElement): Record<string, string | undefined> {
+    const props: Record<string, string | undefined> = {};
+
+    for (const attr of element.getAttributes()) {
+      if (attr.getKind() === SyntaxKind.JsxAttribute) {
+        const jsxAttr = attr.asKind(SyntaxKind.JsxAttribute)!;
+        const name = jsxAttr.getNameNode().getText();
+        const initializer = jsxAttr.getInitializer();
+
+        if (!initializer) {
+          // Boolean shorthand: <Button disabled />
+          props[name] = 'true';
+        } else if (initializer.getKind() === SyntaxKind.StringLiteral) {
+          props[name] = initializer.asKind(SyntaxKind.StringLiteral)!.getLiteralValue();
+        } else if (initializer.getKind() === SyntaxKind.JsxExpression) {
+          const expression = initializer.asKind(SyntaxKind.JsxExpression)!.getExpression();
+          props[name] = expression ? expression.getText() : undefined;
+        }
+      }
+    }
+
+    return props;
+  }
+
+  /**
+   * Extract call expression arguments as a simplified record.
+   * For object literal arguments, extracts property names and their values.
+   */
+  private _extractCallArgs(call: import('ts-morph').CallExpression): Record<string, string | undefined> {
+    const args: Record<string, string | undefined> = {};
+    const callArgs = call.getArguments();
+
+    for (let i = 0; i < callArgs.length; i++) {
+      const arg = callArgs[i];
+
+      if (arg.getKind() === SyntaxKind.ObjectLiteralExpression) {
+        const objLiteral = arg.asKind(SyntaxKind.ObjectLiteralExpression)!;
+        const properties = objLiteral.getProperties();
+
+        if (properties.length === 0) {
+          // Capture empty object literals explicitly
+          args[`arg${i}`] = '{}';
+        } else {
+          for (const prop of properties) {
+            if (prop.getKind() === SyntaxKind.PropertyAssignment) {
+              const propAssignment = prop.asKind(SyntaxKind.PropertyAssignment)!;
+              args[propAssignment.getName()] = propAssignment.getInitializerOrThrow().getText();
+            } else if (prop.getKind() === SyntaxKind.ShorthandPropertyAssignment) {
+              const shorthand = prop.asKind(SyntaxKind.ShorthandPropertyAssignment)!;
+              args[shorthand.getName()] = shorthand.getName();
+            }
+          }
+        }
+      } else {
+        args[`arg${i}`] = arg.getText();
+      }
+    }
+
+    return args;
+  }
+}
diff --git a/tools/cli/src/commands/report/impl/file-discovery.spec.ts b/tools/cli/src/commands/report/impl/file-discovery.spec.ts
new file mode 100644
index 0000000000000..584b85907c772
--- /dev/null
+++ b/tools/cli/src/commands/report/impl/file-discovery.spec.ts
@@ -0,0 +1,193 @@
+import { execSync } from 'node:child_process';
+
+import * as fg from 'fast-glob';
+
+import { discoverSourceFiles, filterSourceFiles } from './file-discovery';
+
+jest.mock('node:child_process', () => ({
+  execSync: jest.fn(),
+}));
+
+jest.mock('fast-glob', () => ({
+  globSync: jest.fn(),
+}));
+
+const mockExecSync = execSync as jest.MockedFunction<typeof execSync>;
+const mockGlobSync = fg.globSync as jest.MockedFunction<typeof fg.globSync>;
+
+describe('file-discovery', () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+  });
+
+  describe('discoverSourceFiles', () => {
+    it('should return .ts and .tsx files from git ls-files output', () => {
+      mockExecSync.mockReturnValue(
+        [
+          'src/App.tsx',
+          'src/utils.ts',
+          'src/styles.css',
+          'src/index.ts',
+          'README.md',
+          'package.json',
+          'src/types.d.ts',
+        ].join('\n') + '\n',
+      );
+
+      const files = discoverSourceFiles('/mock/root');
+
+      expect(files).toHaveLength(3);
+      expect(files).toEqual(
+        expect.arrayContaining([
+          expect.stringContaining('App.tsx'),
+          expect.stringContaining('utils.ts'),
+          expect.stringContaining('index.ts'),
+        ]),
+      );
+    });
+
+    it('should exclude .d.ts declaration files', () => {
+      mockExecSync.mockReturnValue('src/types.d.ts\nsrc/globals.d.ts\nsrc/main.ts\n');
+
+      const files = discoverSourceFiles('/mock/root');
+
+      expect(files).toHaveLength(1);
+      expect(files[0]).toContain('main.ts');
+    });
+
+    it('should return absolute paths', () => {
+      mockExecSync.mockReturnValue('src/App.tsx\n');
+
+      const files = discoverSourceFiles('/mock/root');
+
+      expect(files[0]).toMatch(/^\/mock\/root/);
+    });
+
+    it('should return empty array on git error', () => {
+      mockExecSync.mockImplementation(() => {
+        throw new Error('Not a git repository');
+      });
+
+      const files = discoverSourceFiles('/mock/root');
+
+      expect(files).toEqual([]);
+    });
+
+    it('should handle empty git output', () => {
+      mockExecSync.mockReturnValue('');
+
+      const files = discoverSourceFiles('/mock/root');
+
+      expect(files).toEqual([]);
+    });
+
+    it('should pass correct git arguments', () => {
+      mockExecSync.mockReturnValue('');
+
+      discoverSourceFiles('/mock/root');
+
+      expect(mockExecSync).toHaveBeenCalledWith(
+        'git ls-files --cached --others --exclude-standard',
+        expect.objectContaining({ cwd: '/mock/root' }),
+      );
+    });
+  });
+
+  describe('filterSourceFiles', () => {
+    const ROOT = '/project';
+    const files = [
+      '/project/src/App.tsx',
+      '/project/src/utils.ts',
+      '/project/src/components/Button.tsx',
+      '/project/src/components/Input.tsx',
+      '/project/test/App.test.tsx',
+      '/project/test/utils.test.ts',
+    ];
+
+    it('should return all files when no include/exclude is provided', () => {
+      expect(filterSourceFiles(files, ROOT)).toEqual(files);
+    });
+
+    it('should return all files when include and exclude are empty arrays', () => {
+      expect(filterSourceFiles(files, ROOT, [], [])).toEqual(files);
+    });
+
+    it('should include only files matching include patterns', () => {
+      mockGlobSync.mockReturnValueOnce(['src/components/Button.tsx', 'src/components/Input.tsx']);
+
+      const result = filterSourceFiles(files, ROOT, ['src/components/**']);
+
+      expect(mockGlobSync).toHaveBeenCalledWith(
+        ['src/components/**'],
+        expect.objectContaining({ cwd: ROOT, dot: true, onlyFiles: true }),
+      );
+      expect(result).toHaveLength(2);
+      expect(result).toEqual(['/project/src/components/Button.tsx', '/project/src/components/Input.tsx']);
+    });
+
+    it('should support multiple include patterns', () => {
+      mockGlobSync.mockReturnValueOnce(['src/App.tsx', 'src/components/Button.tsx', 'src/components/Input.tsx']);
+
+      const result = filterSourceFiles(files, ROOT, ['src/App.tsx', 'src/components/**']);
+
+      expect(result).toHaveLength(3);
+    });
+
+    it('should exclude files matching exclude patterns', () => {
+      mockGlobSync.mockReturnValueOnce(['test/App.test.tsx', 'test/utils.test.ts']);
+
+      const result = filterSourceFiles(files, ROOT, undefined, ['test/**']);
+
+      expect(result).toHaveLength(4);
+      expect(result.every(f => !f.includes('/test/'))).toBe(true);
+    });
+
+    it('should support wildcard exclude patterns', () => {
+      mockGlobSync.mockReturnValueOnce(['test/App.test.tsx', 'test/utils.test.ts']);
+
+      const result = filterSourceFiles(files, ROOT, undefined, ['**/*.test.*']);
+
+      expect(result).toHaveLength(4);
+      expect(result.every(f => !f.includes('.test.'))).toBe(true);
+    });
+
+    it('should apply both include and exclude together', () => {
+      // include call
+      mockGlobSync.mockReturnValueOnce([
+        'src/App.tsx',
+        'src/utils.ts',
+        'src/components/Button.tsx',
+        'src/components/Input.tsx',
+      ]);
+      // exclude call
+      mockGlobSync.mockReturnValueOnce(['src/utils.ts']);
+
+      const result = filterSourceFiles(files, ROOT, ['src/**'], ['src/utils.ts']);
+
+      expect(result).toHaveLength(3);
+      expect(result).not.toContain('/project/src/utils.ts');
+    });
+
+    it('should return empty when include matches nothing from discovered files', () => {
+      mockGlobSync.mockReturnValueOnce([]);
+
+      const result = filterSourceFiles(files, ROOT, ['nonexistent/**']);
+
+      expect(result).toEqual([]);
+    });
+
+    it('should support extension-based patterns', () => {
+      mockGlobSync.mockReturnValueOnce([
+        'src/App.tsx',
+        'src/components/Button.tsx',
+        'src/components/Input.tsx',
+        'test/App.test.tsx',
+      ]);
+
+      const result = filterSourceFiles(files, ROOT, ['**/*.tsx']);
+
+      expect(result).toHaveLength(4);
+      expect(result.every(f => f.endsWith('.tsx'))).toBe(true);
+    });
+  });
+});
diff --git a/tools/cli/src/commands/report/impl/file-discovery.ts b/tools/cli/src/commands/report/impl/file-discovery.ts
new file mode 100644
index 0000000000000..4101a0ee2582e
--- /dev/null
+++ b/tools/cli/src/commands/report/impl/file-discovery.ts
@@ -0,0 +1,82 @@
+import { execSync } from 'node:child_process';
+import * as path from 'node:path';
+
+import * as fg from 'fast-glob';
+
+/**
+ * Discover `.ts` and `.tsx` source files under the given root path,
+ * respecting `.gitignore` rules by using `git ls-files`.
+ *
+ * @param rootPath - The root directory to search for source files.
+ * @returns Array of absolute file paths.
+ */
+export function discoverSourceFiles(rootPath: string): string[] {
+  const absoluteRoot = path.resolve(rootPath);
+
+  try {
+    // Use git ls-files to get tracked and untracked (but not ignored) files
+    // --cached: tracked files
+    // --others: untracked files
+    // --exclude-standard: respect .gitignore
+    const output = execSync('git ls-files --cached --others --exclude-standard', {
+      cwd: absoluteRoot,
+      encoding: 'utf-8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+      maxBuffer: 50 * 1024 * 1024,
+    });
+
+    return output
+      .split('\n')
+      .filter(line => line.length > 0)
+      .filter(file => /\.tsx?$/.test(file))
+      .filter(file => !file.endsWith('.d.ts'))
+      .map(file => path.resolve(absoluteRoot, file));
+  } catch {
+    // Fallback: if git is not available, return empty
+    return [];
+  }
+}
+
+/**
+ * Filter a list of absolute file paths using include/exclude glob patterns.
+ * Uses fast-glob to resolve patterns against the filesystem, then intersects
+ * with the provided file list.
+ *
+ * @param filePaths - Absolute file paths to filter.
+ * @param rootPath - Root directory for resolving relative paths in patterns.
+ * @param include - Glob patterns to include. When provided, only matching files are kept.
+ * @param exclude - Glob patterns to exclude. Matching files are removed.
+ * @returns Filtered absolute file paths.
+ */
+export function filterSourceFiles(
+  filePaths: string[],
+  rootPath: string,
+  include?: string[],
+  exclude?: string[],
+): string[] {
+  if (!include?.length && !exclude?.length) {
+    return filePaths;
+  }
+
+  const absoluteRoot = path.resolve(rootPath);
+  const relativeSet = new Set(filePaths.map(fp => path.relative(absoluteRoot, fp)));
+
+  let selected: Set<string>;
+
+  if (include?.length) {
+    const matched = new Set(fg.globSync(include, { cwd: absoluteRoot, dot: true, onlyFiles: true }));
+    // Intersect fast-glob results with our discovered file list
+    selected = new Set([...relativeSet].filter(rel => matched.has(rel)));
+  } else {
+    selected = new Set(relativeSet);
+  }
+
+  if (exclude?.length) {
+    const excluded = new Set<string>(fg.globSync(exclude, { cwd: absoluteRoot, dot: true, onlyFiles: true }));
+    for (const ex of excluded) {
+      selected.delete(ex);
+    }
+  }
+
+  return filePaths.filter(fp => selected.has(path.relative(absoluteRoot, fp)));
+}
diff --git a/tools/cli/src/commands/report/impl/html-reporter.spec.ts b/tools/cli/src/commands/report/impl/html-reporter.spec.ts
new file mode 100644
index 0000000000000..d1dfdd4df7fb6
--- /dev/null
+++ b/tools/cli/src/commands/report/impl/html-reporter.spec.ts
@@ -0,0 +1,305 @@
+import { formatMetadataAsHtml } from './html-reporter';
+import type { UsageReportOutput } from './types';
+
+const TEST_LEGEND: UsageReportOutput['legend'] = {
+  components: { name: 'Components', description: 'React components (JSX elements).' },
+  hooks: { name: 'Hooks', description: 'React hooks (use* naming convention).' },
+  types: { name: 'Types', description: 'TypeScript interfaces, type aliases, and enums.' },
+  others: { name: 'Other Exports', description: 'Value exports that are not components or hooks.' },
+  unknowns: { name: 'Unknowns', description: 'Symbols whose .d.ts declarations could not be resolved.' },
+};
+
+describe('html-reporter', () => {
+  it('should produce a valid HTML document', () => {
+    const reportData: UsageReportOutput = {
+      legend: TEST_LEGEND,
+      fileMap: ['src/App.tsx', 'src/utils.ts'],
+      packages: {
+        '@proj/react-components': {
+          components: {
+            Button: {
+              props: {
+                appearance: { values: ['primary', 'secondary'], count: 3 },
+                size: { values: ['medium'], count: 1 },
+              },
+              count: 5,
+            },
+          },
+          hooks: {
+            useId: { props: { arg0: { values: ["'my-id'"], count: 2 } }, count: 2 },
+          },
+          types: { ButtonProps: { count: 1, typeofCount: 0, props: {} } },
+          others: { tokens: { props: {}, count: 3 } },
+          unknowns: {},
+          count: 11,
+        },
+      },
+    };
+
+    const output = formatMetadataAsHtml(reportData);
+
+    expect(output).toContain('<!DOCTYPE html>');
+    expect(output).toContain('<title>Fluent UI Usage Report</title>');
+    expect(output).toContain('</html>');
+    expect(output).toContain('Legend');
+    expect(output).toContain('<strong>Components</strong>');
+    expect(output).toContain('<strong>Types</strong>');
+  });
+
+  it('should render summary table with correct counts', () => {
+    const reportData: UsageReportOutput = {
+      legend: TEST_LEGEND,
+      fileMap: ['src/App.tsx'],
+      packages: {
+        '@proj/react-components': {
+          components: { Button: { props: {}, count: 2 } },
+          hooks: { useId: { props: {}, count: 1 } },
+          types: { ButtonProps: { count: 1, typeofCount: 0, props: {} } },
+          others: { tokens: { props: {}, count: 1 } },
+          unknowns: {},
+          count: 5,
+        },
+      },
+    };
+
+    const output = formatMetadataAsHtml(reportData);
+
+    expect(output).toContain('<a href="#pkg--proj-react-components"><code>@proj/react-components</code></a>');
+    expect(output).toContain('id="pkg--proj-react-components"');
+    // Components: 1, Hooks: 1, Types: 1, Others: 1, Unknowns: 0, Total: 5
+    expect(output).toContain('<td>1</td>');
+    expect(output).toContain('<td>5</td>');
+  });
+
+  it('should render component prop details with values', () => {
+    const reportData: UsageReportOutput = {
+      legend: TEST_LEGEND,
+      fileMap: ['src/App.tsx'],
+      packages: {
+        '@proj/react-components': {
+          components: {
+            Button: {
+              props: {
+                appearance: { values: ['primary', 'secondary'], count: 3 },
+              },
+              count: 3,
+            },
+          },
+          hooks: {},
+          types: {},
+          others: {},
+          unknowns: {},
+          count: 3,
+        },
+      },
+    };
+
+    const output = formatMetadataAsHtml(reportData);
+
+    // Component Props section
+    expect(output).toContain('Component Props');
+    expect(output).toContain('<details class="symbol-props">');
+    expect(output).toContain('<code>Button</code>');
+    expect(output).toContain('<code>appearance</code>');
+    expect(output).toContain('<code>primary</code>');
+    expect(output).toContain('<code>secondary</code>');
+  });
+
+  it('should render hook argument details', () => {
+    const reportData: UsageReportOutput = {
+      legend: TEST_LEGEND,
+      fileMap: ['src/App.tsx'],
+      packages: {
+        '@proj/react-components': {
+          components: {},
+          hooks: {
+            useId: { props: { arg0: { values: ["'my-id'"], count: 1 } }, count: 1 },
+          },
+          types: {},
+          others: {},
+          unknowns: {},
+          count: 1,
+        },
+      },
+    };
+
+    const output = formatMetadataAsHtml(reportData);
+
+    expect(output).toContain('Hook Arguments');
+    expect(output).toContain('<code>useId</code>');
+    expect(output).toContain('<code>arg0</code>');
+    expect(output).toContain("<code>'my-id'</code>");
+  });
+
+  it('should not render prop details when props are empty', () => {
+    const reportData: UsageReportOutput = {
+      legend: TEST_LEGEND,
+      fileMap: ['src/App.tsx'],
+      packages: {
+        '@proj/react-components': {
+          components: {
+            Divider: { props: {}, count: 2 },
+          },
+          hooks: {},
+          types: {},
+          others: {},
+          unknowns: {},
+          count: 2,
+        },
+      },
+    };
+
+    const output = formatMetadataAsHtml(reportData);
+
+    expect(output).toContain('<code>Divider</code>');
+    expect(output).not.toContain('Component Props');
+    expect(output).not.toContain('<details class="symbol-props">');
+  });
+
+  it('should render unknowns with descriptions', () => {
+    const reportData: UsageReportOutput = {
+      legend: TEST_LEGEND,
+      fileMap: ['src/App.tsx'],
+      packages: {
+        '@proj/react-components': {
+          components: {},
+          hooks: {},
+          types: {},
+          others: {},
+          unknowns: {
+            SomeConstant: { props: {}, count: 3, description: 'PascalCase symbol' },
+            CustomProps: { props: {}, count: 1, description: 'Likely a type' },
+          },
+          count: 4,
+        },
+      },
+    };
+
+    const output = formatMetadataAsHtml(reportData);
+
+    expect(output).toContain('Unknowns');
+    expect(output).toContain('<code>SomeConstant</code>');
+    expect(output).toContain('PascalCase symbol');
+    expect(output).toContain('<code>CustomProps</code>');
+    expect(output).toContain('Likely a type');
+    expect(output).toContain('.d.ts');
+  });
+
+  it('should handle empty metadata', () => {
+    const output = formatMetadataAsHtml({ legend: TEST_LEGEND, fileMap: [], packages: {} });
+
+    expect(output).toContain('<!DOCTYPE html>');
+    expect(output).toContain('No Fluent UI package usage found.');
+  });
+
+  it('should render file map section with file paths', () => {
+    const reportData: UsageReportOutput = {
+      legend: TEST_LEGEND,
+      fileMap: ['src/App.tsx', 'src/utils.ts'],
+      packages: {
+        '@proj/react-components': {
+          components: { Button: { props: {}, count: 1 } },
+          hooks: {},
+          types: {},
+          others: {},
+          unknowns: {},
+          count: 1,
+        },
+      },
+    };
+
+    const output = formatMetadataAsHtml(reportData);
+
+    expect(output).toContain('Files analyzed:');
+    expect(output).toContain('<code>src/App.tsx</code>');
+    expect(output).toContain('<code>src/utils.ts</code>');
+  });
+
+  it('should escape HTML special characters', () => {
+    const reportData: UsageReportOutput = {
+      legend: TEST_LEGEND,
+      fileMap: ['src/App.tsx'],
+      packages: {
+        '@proj/react-components': {
+          components: {
+            Button: {
+              props: {
+                onClick: { values: ['() => { alert("<xss>") }'], count: 1 },
+              },
+              count: 1,
+            },
+          },
+          hooks: {},
+          types: {},
+          others: {},
+          unknowns: {},
+          count: 1,
+        },
+      },
+    };
+
+    const output = formatMetadataAsHtml(reportData);
+
+    expect(output).not.toContain('<xss>');
+    expect(output).toContain('&lt;xss&gt;');
+  });
+
+  it('should show dash for props with no values', () => {
+    const reportData: UsageReportOutput = {
+      legend: TEST_LEGEND,
+      fileMap: ['src/App.tsx'],
+      packages: {
+        '@proj/react-components': {
+          components: {
+            Button: {
+              props: {
+                disabled: { values: [], count: 2 },
+              },
+              count: 2,
+            },
+          },
+          hooks: {},
+          types: {},
+          others: {},
+          unknowns: {},
+          count: 2,
+        },
+      },
+    };
+
+    const output = formatMetadataAsHtml(reportData);
+
+    expect(output).toContain('<span class="muted">—</span>');
+  });
+
+  it('should render multiple packages as separate sections', () => {
+    const reportData: UsageReportOutput = {
+      legend: TEST_LEGEND,
+      fileMap: ['src/App.tsx'],
+      packages: {
+        '@griffel/react': {
+          components: {},
+          hooks: {},
+          types: {},
+          others: { makeStyles: { props: {}, count: 1 } },
+          unknowns: {},
+          count: 1,
+        },
+        '@proj/react-components': {
+          components: { Button: { props: {}, count: 1 } },
+          hooks: {},
+          types: {},
+          others: {},
+          unknowns: {},
+          count: 1,
+        },
+      },
+    };
+
+    const output = formatMetadataAsHtml(reportData);
+
+    expect(output).toContain('<code>@proj/react-components</code>');
+    expect(output).toContain('<code>@griffel/react</code>');
+    expect(output).toContain('<code>makeStyles</code>');
+  });
+});
diff --git a/tools/cli/src/commands/report/impl/html-reporter.ts b/tools/cli/src/commands/report/impl/html-reporter.ts
new file mode 100644
index 0000000000000..93a6cd9c37064
--- /dev/null
+++ b/tools/cli/src/commands/report/impl/html-reporter.ts
@@ -0,0 +1,394 @@
+import type {
+  UsageReportOutput,
+  Metadata,
+  CategoryLegendEntry,
+  ComponentUsage,
+  HookUsage,
+  FunctionUsage,
+  PropUsage,
+  TypeUsage,
+  UnknownSymbolUsage,
+} from './types';
+
+/**
+ * Format UsageReportOutput as a self-contained HTML report.
+ * HTML provides comprehensive prop/argument detail that markdown intentionally omits.
+ */
+export function formatMetadataAsHtml(data: UsageReportOutput): string {
+  const { legend, fileMap, packages: metadata } = data;
+  const packageNames = Object.keys(metadata).sort();
+
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<title>Fluent UI Usage Report</title>
+${renderStyles()}
+</head>
+<body>
+<main>
+<h1>Fluent UI Codebase Usage Report</h1>
+${
+  packageNames.length === 0 && fileMap.length === 0
+    ? '<p class="empty">No Fluent UI package usage found.</p>'
+    : renderBody(legend, metadata, packageNames, fileMap)
+}
+</main>
+</body>
+</html>`;
+}
+
+// ---------------------------------------------------------------------------
+// Top-level sections
+// ---------------------------------------------------------------------------
+
+function renderBody(
+  legend: Record<string, CategoryLegendEntry>,
+  metadata: Metadata,
+  packageNames: string[],
+  fileMap: string[],
+): string {
+  return [
+    renderLegend(legend),
+    renderFileMap(fileMap),
+    renderSummaryTable(metadata, packageNames),
+    ...packageNames.map(name => renderPackageSection(name, metadata[name])),
+  ].join('\n');
+}
+
+function renderLegend(legend: Record<string, CategoryLegendEntry>): string {
+  const rows = Object.values(legend)
+    .map(entry => `<tr><td><strong>${esc(entry.name)}</strong></td><td>${esc(entry.description)}</td></tr>`)
+    .join('\n');
+
+  return `<section class="legend">
+<details open>
+<summary><h2 style="display:inline">Legend</h2></summary>
+<table>
+<thead><tr><th>Category</th><th>Description</th></tr></thead>
+<tbody>
+${rows}
+</tbody>
+</table>
+</details>
+</section>`;
+}
+
+function renderFileMap(fileMap: string[]): string {
+  if (fileMap.length === 0) {
+    return '';
+  }
+
+  const fileItems = fileMap.map(f => `<li><code>${esc(f)}</code></li>`).join('\n');
+
+  return `<section class="file-map">
+<details>
+<summary><strong>Files analyzed:</strong> ${fileMap.length}</summary>
+<ul class="file-list">
+${fileItems}
+</ul>
+</details>
+</section>`;
+}
+
+function renderSummaryTable(metadata: Metadata, packageNames: string[]): string {
+  const scopeGroups = groupByScope(packageNames);
+
+  const scopeSections = scopeGroups.map(([scope, names]) => {
+    const rows = names.map(name => {
+      const pkg = metadata[name];
+      const anchor = toAnchorId(name);
+      return `<tr>
+<td><a href="#${anchor}"><code>${esc(name)}</code></a></td>
+<td>${Object.keys(pkg.components).length}</td>
+<td>${Object.keys(pkg.hooks).length}</td>
+<td>${Object.keys(pkg.types).length}</td>
+<td>${Object.keys(pkg.others).length}</td>
+<td>${Object.keys(pkg.unknowns).length}</td>
+<td>${pkg.count}</td>
+</tr>`;
+    });
+
+    return `<h3>${esc(scope)}</h3>
+<table>
+<thead><tr>
+<th>Package</th><th>Components</th><th>Hooks</th><th>Types</th><th>Others</th><th>Unknowns</th><th>Total&nbsp;Imports</th>
+</tr></thead>
+<tbody>
+${rows.join('\n')}
+</tbody>
+</table>`;
+  });
+
+  return `<section class="summary">
+<h2>Summary</h2>
+${scopeSections.join('\n')}
+</section>`;
+}
+
+function renderPackageSection(name: string, pkg: Metadata[string]): string {
+  const sections: string[] = [];
+  const anchor = toAnchorId(name);
+
+  if (Object.keys(pkg.components).length > 0) {
+    sections.push(renderComponentsSection(pkg.components));
+  }
+  if (Object.keys(pkg.hooks).length > 0) {
+    sections.push(renderHooksSection(pkg.hooks));
+  }
+  if (Object.keys(pkg.types).length > 0) {
+    sections.push(renderTypesSection(pkg.types));
+  }
+  if (Object.keys(pkg.others).length > 0) {
+    sections.push(renderFunctionsSection('Other Exports', pkg.others));
+  }
+  if (Object.keys(pkg.unknowns).length > 0) {
+    sections.push(renderUnknownsSection(pkg.unknowns));
+  }
+
+  return `<section class="package" id="${anchor}">
+<h2><code>${esc(name)}</code></h2>
+${sections.join('\n')}
+</section>`;
+}
+
+// ---------------------------------------------------------------------------
+// Components — overview table + per-component prop details
+// ---------------------------------------------------------------------------
+
+function renderComponentsSection(components: Record<string, ComponentUsage>): string {
+  const sorted = Object.entries(components).sort(([, a], [, b]) => b.count - a.count);
+
+  const overviewRows = sorted.map(
+    ([name, usage]) =>
+      `<tr><td><code>${esc(name)}</code></td><td>${usage.count}</td><td>${Object.keys(usage.props).length}</td></tr>`,
+  );
+
+  const propDetails = sorted
+    .filter(([, usage]) => Object.keys(usage.props).length > 0)
+    .map(([name, usage]) => renderPropDetailsBlock(name, 'component', usage.props));
+
+  return `<div class="category">
+<h3>Components</h3>
+<table>
+<thead><tr><th>Component</th><th>Usages</th><th>Unique Props</th></tr></thead>
+<tbody>${overviewRows.join('\n')}</tbody>
+</table>
+${propDetails.length > 0 ? `<div class="prop-details"><h4>Component Props</h4>${propDetails.join('\n')}</div>` : ''}
+</div>`;
+}
+
+// ---------------------------------------------------------------------------
+// Hooks — overview table + per-hook argument details
+// ---------------------------------------------------------------------------
+
+function renderHooksSection(hooks: Record<string, HookUsage>): string {
+  const sorted = Object.entries(hooks).sort(([, a], [, b]) => b.count - a.count);
+
+  const overviewRows = sorted.map(
+    ([name, usage]) =>
+      `<tr><td><code>${esc(name)}</code></td><td>${usage.count}</td><td>${Object.keys(usage.props).length}</td></tr>`,
+  );
+
+  const argDetails = sorted
+    .filter(([, usage]) => Object.keys(usage.props).length > 0)
+    .map(([name, usage]) => renderPropDetailsBlock(name, 'hook', usage.props));
+
+  return `<div class="category">
+<h3>Hooks</h3>
+<table>
+<thead><tr><th>Hook</th><th>Usages</th><th>Unique Args</th></tr></thead>
+<tbody>${overviewRows.join('\n')}</tbody>
+</table>
+${argDetails.length > 0 ? `<div class="prop-details"><h4>Hook Arguments</h4>${argDetails.join('\n')}</div>` : ''}
+</div>`;
+}
+
+// ---------------------------------------------------------------------------
+// Functions / other exports — overview table + per-function arg details
+// ---------------------------------------------------------------------------
+
+function renderFunctionsSection(title: string, functions: Record<string, FunctionUsage>): string {
+  const sorted = Object.entries(functions).sort(([, a], [, b]) => b.count - a.count);
+  const overviewRows = sorted.map(
+    ([name, usage]) =>
+      `<tr><td><code>${esc(name)}</code></td><td>${usage.count}</td><td>${Object.keys(usage.props).length}</td></tr>`,
+  );
+
+  const argDetails = sorted
+    .filter(([, usage]) => Object.keys(usage.props).length > 0)
+    .map(([name, usage]) => renderPropDetailsBlock(name, 'function', usage.props));
+
+  return `<div class="category">
+<h3>${esc(title)}</h3>
+<table>
+<thead><tr><th>Symbol</th><th>Usages</th><th>Unique Args</th></tr></thead>
+<tbody>${overviewRows.join('\n')}</tbody>
+</table>
+${argDetails.length > 0 ? `<div class="prop-details"><h4>Function Arguments</h4>${argDetails.join('\n')}</div>` : ''}
+</div>`;
+}
+
+// ---------------------------------------------------------------------------
+// Prop / argument detail block (shared by components, hooks & functions)
+// ---------------------------------------------------------------------------
+
+function renderPropDetailsBlock(
+  symbolName: string,
+  _kind: 'component' | 'hook' | 'function',
+  props: Record<string, PropUsage>,
+): string {
+  const rows = Object.entries(props)
+    .sort(([, a], [, b]) => b.count - a.count)
+    .map(([propName, usage]) => {
+      const valuesHtml =
+        usage.values.length === 0
+          ? '<span class="muted">—</span>'
+          : `<ul class="values">${usage.values.map(v => `<li><code>${esc(v)}</code></li>`).join('')}</ul>`;
+      return `<tr><td><code>${esc(propName)}</code></td><td>${usage.count}</td><td>${valuesHtml}</td></tr>`;
+    });
+
+  return `<details class="symbol-props">
+<summary><code>${esc(symbolName)}</code> — ${Object.keys(props).length} prop(s)</summary>
+<table>
+<thead><tr><th>Prop</th><th>Usages</th><th>Values</th></tr></thead>
+<tbody>${rows.join('\n')}</tbody>
+</table>
+</details>`;
+}
+
+// ---------------------------------------------------------------------------
+// Types — overview table with typeof count + per-type generic arg details
+// ---------------------------------------------------------------------------
+
+function renderTypesSection(types: Record<string, TypeUsage>): string {
+  const sorted = Object.entries(types).sort(([, a], [, b]) => b.count - a.count);
+
+  const overviewRows = sorted.map(
+    ([name, usage]) =>
+      `<tr><td><code>${esc(name)}</code></td><td>${usage.count}</td><td>${usage.typeofCount}</td><td>${
+        Object.keys(usage.props).length
+      }</td></tr>`,
+  );
+
+  const argDetails = sorted
+    .filter(([, usage]) => Object.keys(usage.props).length > 0)
+    .map(([name, usage]) => renderPropDetailsBlock(name, 'function', usage.props));
+
+  return `<div class="category">
+<h3>Types</h3>
+<table>
+<thead><tr><th>Symbol</th><th>Usages</th><th>typeof</th><th>Type Args</th></tr></thead>
+<tbody>${overviewRows.join('\n')}</tbody>
+</table>
+${
+  argDetails.length > 0 ? `<div class="prop-details"><h4>Generic Type Arguments</h4>${argDetails.join('\n')}</div>` : ''
+}
+</div>`;
+}
+
+// ---------------------------------------------------------------------------
+// Unknowns
+// ---------------------------------------------------------------------------
+
+function renderUnknownsSection(unknowns: Record<string, UnknownSymbolUsage>): string {
+  const sorted = Object.entries(unknowns).sort(([, a], [, b]) => b.count - a.count);
+  const rows = sorted.map(
+    ([name, usage]) =>
+      `<tr><td><code>${esc(name)}</code></td><td>${usage.count}</td><td>${
+        Object.keys(usage.props).length
+      }</td><td>${esc(usage.description)}</td></tr>`,
+  );
+
+  const argDetails = sorted
+    .filter(([, usage]) => Object.keys(usage.props).length > 0)
+    .map(([name, usage]) => renderPropDetailsBlock(name, 'function', usage.props));
+
+  return `<div class="category unknowns">
+<h3>Unknowns</h3>
+<p class="note">Symbols whose <code>.d.ts</code> declarations could not be resolved. Install types or add declarations to improve classification.</p>
+<table>
+<thead><tr><th>Symbol</th><th>Usages</th><th>Unique Args</th><th>Description</th></tr></thead>
+<tbody>${rows.join('\n')}</tbody>
+</table>
+${
+  argDetails.length > 0
+    ? `<div class="prop-details"><h4>Unknown Symbol Arguments</h4>${argDetails.join('\n')}</div>`
+    : ''
+}
+</div>`;
+}
+
+// ---------------------------------------------------------------------------
+// Utilities
+// ---------------------------------------------------------------------------
+
+function esc(text: string): string {
+  return text.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+}
+
+/** Convert a package name to a URL-safe anchor id. */
+function toAnchorId(name: string): string {
+  return 'pkg-' + name.replace(/[^a-zA-Z0-9-]/g, '-');
+}
+
+/**
+ * Group package names by npm scope. Scoped packages (@scope/name) are grouped
+ * under their scope; unscoped packages go under "Other Packages".
+ */
+function groupByScope(packageNames: string[]): Array<[string, string[]]> {
+  const groups = new Map<string, string[]>();
+  for (const name of packageNames) {
+    const scope = name.startsWith('@') ? name.split('/')[0] : 'Other Packages';
+    if (!groups.has(scope)) {
+      groups.set(scope, []);
+    }
+    groups.get(scope)!.push(name);
+  }
+  return [...groups.entries()].sort(([a], [b]) => a.localeCompare(b));
+}
+
+function renderStyles(): string {
+  return `<style>
+:root { --bg: #fff; --fg: #1a1a1a; --muted: #6b7280; --border: #e5e7eb; --accent: #0078d4; --accent-light: #e8f4fd; --code-bg: #f3f4f6; --section-bg: #fafafa; }
+@media (prefers-color-scheme: dark) {
+  :root { --bg: #1e1e1e; --fg: #d4d4d4; --muted: #9ca3af; --border: #374151; --accent: #4fc3f7; --accent-light: #1e3a4d; --code-bg: #2d2d2d; --section-bg: #252525; }
+}
+*, *::before, *::after { box-sizing: border-box; }
+html { scroll-behavior: smooth; }
+body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; background: var(--bg); color: var(--fg); line-height: 1.6; margin: 0; padding: 2rem; }
+main { max-width: 960px; margin: 0 auto; }
+h1 { border-bottom: 2px solid var(--accent); padding-bottom: .5rem; }
+h2 { margin-top: 2rem; }
+h2 code { font-size: 1em; }
+h3 { margin-top: 1.25rem; color: var(--accent); }
+h4 { margin: 1rem 0 .5rem; font-size: .95rem; color: var(--muted); }
+code { background: var(--code-bg); padding: .15em .35em; border-radius: 3px; font-size: .9em; }
+table { width: 100%; border-collapse: collapse; margin: .5rem 0 1rem; font-size: .9rem; }
+th, td { text-align: left; padding: .45rem .75rem; border: 1px solid var(--border); }
+th { background: var(--section-bg); font-weight: 600; }
+tr:hover { background: var(--accent-light); }
+.summary table a { color: var(--accent); text-decoration: none; }
+.summary table a:hover { text-decoration: underline; }
+.summary table th:not(:first-child), .summary table td:not(:first-child) { text-align: center; }
+.category { margin-bottom: 1.5rem; }
+.prop-details { margin-top: .75rem; padding-left: .25rem; }
+details.symbol-props { margin: .4rem 0; }
+details.symbol-props summary { cursor: pointer; padding: .3rem .5rem; border-radius: 4px; }
+details.symbol-props summary:hover { background: var(--accent-light); }
+details.symbol-props[open] summary { font-weight: 600; }
+details.symbol-props table { margin-top: .25rem; }
+ul.values { list-style: none; margin: 0; padding: 0; display: flex; flex-wrap: wrap; gap: .35rem; }
+ul.values li { display: inline; }
+ul.values li code { font-size: .85em; background: var(--accent-light); border: 1px solid var(--border); padding: .1em .45em; border-radius: 10px; }
+.muted { color: var(--muted); }
+.note { font-size: .85rem; color: var(--muted); margin: .25rem 0 .5rem; }
+.empty { color: var(--muted); font-style: italic; }
+.package { border-top: 1px solid var(--border); padding-top: 1rem; }
+.file-map { margin-bottom: 1rem; }
+.file-map summary { cursor: pointer; }
+ul.file-list { columns: 2; column-gap: 2rem; list-style: none; padding: 0; margin: .5rem 0; font-size: .85rem; }
+ul.file-list li { padding: .1rem 0; break-inside: avoid; }
+</style>`;
+}
diff --git a/tools/cli/src/commands/report/impl/index.ts b/tools/cli/src/commands/report/impl/index.ts
new file mode 100644
index 0000000000000..a09c62aff88af
--- /dev/null
+++ b/tools/cli/src/commands/report/impl/index.ts
@@ -0,0 +1,18 @@
+export type {
+  InfoArgs,
+  UsageArgs,
+  SystemInfo,
+  ResolvedPackage,
+  DuplicatePackage,
+  InfoReportData,
+  PropUsage,
+  ComponentUsage,
+  HookUsage,
+  SymbolUsage,
+  PackageUsageData,
+  Metadata,
+  ImportInfo,
+  JsxUsageInfo,
+  CallUsageInfo,
+  AstParser,
+} from './types';
diff --git a/tools/cli/src/commands/report/impl/info-report.spec.ts b/tools/cli/src/commands/report/impl/info-report.spec.ts
new file mode 100644
index 0000000000000..561250fdf4148
--- /dev/null
+++ b/tools/cli/src/commands/report/impl/info-report.spec.ts
@@ -0,0 +1,105 @@
+import { formatInfoReport, collectInfoReportData } from './info-report';
+import type { InfoReportData } from './types';
+
+jest.mock('./package-resolver', () => ({
+  getGitRoot: jest.fn().mockReturnValue('/mock/root'),
+  getSystemInfo: jest.fn().mockReturnValue({
+    node: '22.21.1',
+    os: 'darwin-arm64',
+    nativeTarget: 'aarch64-macos',
+    packageManager: 'yarn 1.22.19',
+  }),
+  getMatchingPackages: jest
+    .fn()
+    .mockReturnValue(['@proj/react-components', '@proj/react-icons', '@types/react', 'react', 'typescript']),
+  resolvePackageVersions: jest.fn().mockReturnValue([
+    { name: '@proj/react-components', version: '9.50.0' },
+    { name: '@proj/react-icons', version: '2.0.200' },
+    { name: '@types/react', version: '18.2.45' },
+    { name: 'react', version: '18.2.0' },
+    { name: 'typescript', version: '5.3.3' },
+  ]),
+  findDuplicatePackages: jest.fn().mockReturnValue([{ name: '@proj/react-icons', versions: ['2.0.200', '2.0.195'] }]),
+}));
+
+describe('info-report', () => {
+  describe('collectInfoReportData', () => {
+    it('should collect system info, packages, and duplicates', () => {
+      const data = collectInfoReportData();
+
+      expect(data.system.node).toBe('22.21.1');
+      expect(data.system.os).toBe('darwin-arm64');
+      expect(data.system.packageManager).toBe('yarn 1.22.19');
+      expect(data.packages).toHaveLength(5);
+      expect(data.duplicates).toHaveLength(1);
+      expect(data.duplicates[0].name).toBe('@proj/react-icons');
+    });
+  });
+
+  describe('formatInfoReport', () => {
+    it('should produce formatted output matching the SPEC', () => {
+      const data: InfoReportData = {
+        system: {
+          node: '22.21.1',
+          os: 'darwin-arm64',
+          nativeTarget: 'aarch64-macos',
+          packageManager: 'yarn 1.22.19',
+        },
+        packages: [
+          { name: '@proj/react-components', version: '9.50.0' },
+          { name: '@proj/react-icons', version: '2.0.200' },
+          { name: 'react', version: '18.2.0' },
+          { name: 'typescript', version: '5.3.3' },
+        ],
+        duplicates: [{ name: '@proj/react-icons', versions: ['2.0.195', '2.0.200'] }],
+      };
+
+      const output = formatInfoReport(data);
+
+      expect(output).toContain('FluentCLI   Report complete');
+      expect(output).toContain('Node           : 22.21.1');
+      expect(output).toContain('OS             : darwin-arm64');
+      expect(output).toContain('Native Target  : aarch64-macos');
+      expect(output).toContain('yarn           : 1.22.19');
+      expect(output).toContain('@proj/react-components');
+      expect(output).toContain('9.50.0');
+      expect(output).toContain('🚨 Duplicates:');
+      expect(output).toContain('@proj/react-icons: 2.0.195, 2.0.200');
+    });
+
+    it('should omit duplicates section when none found', () => {
+      const data: InfoReportData = {
+        system: {
+          node: '22.0.0',
+          os: 'linux-x64',
+          nativeTarget: 'x86_64-linux',
+          packageManager: 'npm 10.0.0',
+        },
+        packages: [{ name: 'react', version: '18.2.0' }],
+        duplicates: [],
+      };
+
+      const output = formatInfoReport(data);
+
+      expect(output).not.toContain('Duplicates');
+      expect(output).toContain('react');
+    });
+
+    it('should omit packages section when none found', () => {
+      const data: InfoReportData = {
+        system: {
+          node: '22.0.0',
+          os: 'linux-x64',
+          nativeTarget: 'x86_64-linux',
+          packageManager: 'npm 10.0.0',
+        },
+        packages: [],
+        duplicates: [],
+      };
+
+      const output = formatInfoReport(data);
+
+      expect(output).not.toContain('Packages:');
+    });
+  });
+});
diff --git a/tools/cli/src/commands/report/impl/info-report.ts b/tools/cli/src/commands/report/impl/info-report.ts
new file mode 100644
index 0000000000000..5c42a16704b16
--- /dev/null
+++ b/tools/cli/src/commands/report/impl/info-report.ts
@@ -0,0 +1,90 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import type { InfoReportData } from './types';
+import {
+  getSystemInfo,
+  getMatchingPackages,
+  resolvePackageVersions,
+  findDuplicatePackages,
+  getGitRoot,
+} from './package-resolver';
+
+/**
+ * Generate the short report data by reading system info and installed packages.
+ * Always operates from the git root directory.
+ */
+export function collectInfoReportData(): InfoReportData {
+  const rootDir = getGitRoot();
+  const system = getSystemInfo(rootDir);
+  const matchingNames = getMatchingPackages(rootDir);
+  const packages = resolvePackageVersions(matchingNames, rootDir);
+  const duplicates = findDuplicatePackages(matchingNames, rootDir);
+
+  return { system, packages, duplicates };
+}
+
+/**
+ * Format the short report data into a human-readable string.
+ */
+export function formatInfoReport(data: InfoReportData): string {
+  const lines: string[] = [];
+
+  lines.push('FluentCLI   Report complete - copy this into the issue template');
+  lines.push('');
+  lines.push('System:');
+  lines.push('');
+  lines.push(`  Node           : ${data.system.node}`);
+  lines.push(`  OS             : ${data.system.os}`);
+  lines.push(`  Native Target  : ${data.system.nativeTarget}`);
+  lines.push(
+    `  ${data.system.packageManager.split(' ')[0].padEnd(15)}: ${data.system.packageManager
+      .split(' ')
+      .slice(1)
+      .join(' ')}`,
+  );
+  lines.push('---------------------------------------');
+  lines.push('');
+
+  if (data.packages.length > 0) {
+    lines.push('Packages:');
+    lines.push('');
+
+    const maxNameLen = Math.max(...data.packages.map(p => p.name.length));
+    for (const pkg of data.packages) {
+      lines.push(`  ${pkg.name.padEnd(maxNameLen + 2)}: ${pkg.version}`);
+    }
+    lines.push('---------------------------------------');
+    lines.push('');
+  }
+
+  if (data.duplicates.length > 0) {
+    lines.push('🚨 Duplicates:');
+    lines.push('');
+    for (const dup of data.duplicates) {
+      lines.push(`  - ${dup.name}: ${dup.versions.join(', ')}`);
+    }
+    lines.push('---------------------------------------');
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Run the short report: collect data and print to stdout or write to file.
+ *
+ * @param output - Output file path. When provided, writes to file instead of stdout.
+ */
+export async function runInfoReport(output?: string): Promise<void> {
+  const data = collectInfoReportData();
+  const formatted = formatInfoReport(data);
+
+  if (output) {
+    const outputPath = path.resolve(output);
+    fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+    fs.writeFileSync(outputPath, formatted, 'utf-8');
+    console.log(`Report written to ${outputPath}`);
+  } else {
+    console.log(formatted);
+  }
+}
diff --git a/tools/cli/src/commands/report/impl/markdown-reporter.spec.ts b/tools/cli/src/commands/report/impl/markdown-reporter.spec.ts
new file mode 100644
index 0000000000000..00f165fc18c89
--- /dev/null
+++ b/tools/cli/src/commands/report/impl/markdown-reporter.spec.ts
@@ -0,0 +1,224 @@
+import { formatMetadataAsMarkdown } from './markdown-reporter';
+import type { UsageReportOutput } from './types';
+
+const TEST_LEGEND: UsageReportOutput['legend'] = {
+  components: { name: 'Components', description: 'React components (JSX elements).' },
+  hooks: { name: 'Hooks', description: 'React hooks (use* naming convention).' },
+  types: { name: 'Types', description: 'TypeScript interfaces, type aliases, and enums.' },
+  others: { name: 'Other Exports', description: 'Value exports that are not components or hooks.' },
+  unknowns: { name: 'Unknowns', description: 'Symbols whose .d.ts declarations could not be resolved.' },
+};
+
+describe('markdown-reporter', () => {
+  it('should produce a report with summary table and per-package sections', () => {
+    const reportData: UsageReportOutput = {
+      legend: TEST_LEGEND,
+      fileMap: ['src/App.tsx', 'src/utils.ts'],
+      packages: {
+        '@proj/react-components': {
+          components: {
+            Button: {
+              props: {
+                appearance: { values: ['primary', 'secondary'], count: 3 },
+                size: { values: ['medium'], count: 1 },
+              },
+              count: 3,
+            },
+            Input: {
+              props: {
+                placeholder: { values: ['Search...'], count: 1 },
+              },
+              count: 1,
+            },
+          },
+          hooks: {
+            useId: { props: { arg0: { values: ["'my-id'"], count: 1 } }, count: 1 },
+          },
+          types: {
+            ButtonProps: { count: 2, typeofCount: 0, props: {} },
+          },
+          others: {
+            tokens: { props: {}, count: 3 },
+            webLightTheme: { props: {}, count: 1 },
+          },
+          unknowns: {},
+          count: 12,
+        },
+      },
+    };
+
+    const output = formatMetadataAsMarkdown(reportData);
+
+    // Title
+    expect(output).toContain('# Fluent UI Codebase Usage Report');
+
+    // Legend
+    expect(output).toContain('## Legend');
+    expect(output).toContain('| **Components** |');
+    expect(output).toContain('| **Types** |');
+
+    // Summary table
+    expect(output).toContain('## Summary');
+    expect(output).toContain('| `@proj/react-components` | 2 | 1 | 1 | 2 | 0 | 12 |');
+
+    // Components section — just symbol + count, no props
+    expect(output).toContain('### Components');
+    expect(output).toContain('| `Button` | 3 |');
+    expect(output).toContain('| `Input` | 1 |');
+    expect(output).not.toContain('appearance');
+    expect(output).not.toContain('primary');
+
+    // Hooks section — just symbol + count, no arguments
+    expect(output).toContain('### Hooks');
+    expect(output).toContain('| `useId` | 1 |');
+    expect(output).not.toContain("'my-id'");
+
+    // Types section — now includes typeof count and type args
+    expect(output).toContain('### Types');
+    expect(output).toContain('| `ButtonProps` | 2 | 0 | 0 |');
+
+    // Others section
+    expect(output).toContain('### Other Exports');
+    expect(output).toContain('| `tokens` | 3 |');
+  });
+
+  it('should handle empty metadata', () => {
+    const output = formatMetadataAsMarkdown({ legend: TEST_LEGEND, fileMap: [], packages: {} });
+
+    expect(output).toContain('# Fluent UI Codebase Usage Report');
+    expect(output).toContain('No Fluent UI package usage found.');
+  });
+
+  it('should include files analyzed count', () => {
+    const reportData: UsageReportOutput = {
+      legend: TEST_LEGEND,
+      fileMap: ['src/App.tsx', 'src/utils.ts', 'src/helpers.ts'],
+      packages: {},
+    };
+
+    const output = formatMetadataAsMarkdown(reportData);
+
+    expect(output).toContain('**Files analyzed:** 3');
+  });
+
+  it('should handle package with only others', () => {
+    const reportData: UsageReportOutput = {
+      legend: TEST_LEGEND,
+      fileMap: ['src/App.tsx'],
+      packages: {
+        '@griffel/react': {
+          components: {},
+          hooks: {},
+          types: {},
+          others: {
+            makeStyles: { props: {}, count: 5 },
+          },
+          unknowns: {},
+          count: 5,
+        },
+      },
+    };
+
+    const output = formatMetadataAsMarkdown(reportData);
+
+    expect(output).toContain('`@griffel/react`');
+    expect(output).toContain('| `makeStyles` | 5 |');
+    expect(output).not.toContain('### Components');
+    expect(output).not.toContain('### Hooks');
+    expect(output).not.toContain('### Types');
+  });
+
+  it('should sort symbols by usage count descending', () => {
+    const reportData: UsageReportOutput = {
+      legend: TEST_LEGEND,
+      fileMap: ['src/App.tsx'],
+      packages: {
+        '@proj/react-components': {
+          components: {
+            Tooltip: { props: {}, count: 1 },
+            Button: { props: {}, count: 10 },
+            Input: { props: {}, count: 5 },
+          },
+          hooks: {},
+          types: {},
+          others: {},
+          unknowns: {},
+          count: 16,
+        },
+      },
+    };
+
+    const output = formatMetadataAsMarkdown(reportData);
+
+    const buttonIdx = output.indexOf('`Button`');
+    const inputIdx = output.indexOf('`Input`');
+    const tooltipIdx = output.indexOf('`Tooltip`');
+
+    expect(buttonIdx).toBeLessThan(inputIdx);
+    expect(inputIdx).toBeLessThan(tooltipIdx);
+  });
+
+  it('should handle multiple packages sorted alphabetically', () => {
+    const reportData: UsageReportOutput = {
+      legend: TEST_LEGEND,
+      fileMap: ['src/App.tsx'],
+      packages: {
+        '@griffel/react': {
+          components: {},
+          hooks: {},
+          types: {},
+          others: { makeStyles: { props: {}, count: 1 } },
+          unknowns: {},
+          count: 1,
+        },
+        '@proj/react-components': {
+          components: { Button: { props: {}, count: 1 } },
+          hooks: {},
+          types: {},
+          others: {},
+          unknowns: {},
+          count: 1,
+        },
+      },
+    };
+
+    const output = formatMetadataAsMarkdown(reportData);
+
+    const projIdx = output.indexOf('## `@proj/react-components`');
+    const griffelIdx = output.indexOf('## `@griffel/react`');
+
+    expect(griffelIdx).toBeLessThan(projIdx);
+  });
+
+  it('should render unknowns section with descriptions', () => {
+    const reportData: UsageReportOutput = {
+      legend: TEST_LEGEND,
+      fileMap: ['src/App.tsx'],
+      packages: {
+        '@proj/react-components': {
+          components: {},
+          hooks: {},
+          types: {},
+          others: {},
+          unknowns: {
+            SomeConstant: {
+              props: {},
+              count: 3,
+              description: 'PascalCase symbol — could be a component, constant, or type',
+            },
+            CustomProps: { props: {}, count: 1, description: 'Likely a type/interface (*Props naming convention)' },
+          },
+          count: 4,
+        },
+      },
+    };
+
+    const output = formatMetadataAsMarkdown(reportData);
+
+    expect(output).toContain('### Unknowns');
+    expect(output).toContain('`.d.ts` declarations could not be resolved');
+    expect(output).toContain('| `SomeConstant` | 3 | PascalCase symbol');
+    expect(output).toContain('| `CustomProps` | 1 | Likely a type/interface');
+    expect(output).toContain('| 2 | 4 |');
+  });
+});
diff --git a/tools/cli/src/commands/report/impl/markdown-reporter.ts b/tools/cli/src/commands/report/impl/markdown-reporter.ts
new file mode 100644
index 0000000000000..d48b6463d900f
--- /dev/null
+++ b/tools/cli/src/commands/report/impl/markdown-reporter.ts
@@ -0,0 +1,159 @@
+import type {
+  UsageReportOutput,
+  ComponentUsage,
+  HookUsage,
+  FunctionUsage,
+  TypeUsage,
+  UnknownSymbolUsage,
+} from './types';
+
+/**
+ * Format UsageReportOutput as a structured Markdown report.
+ * Markdown output is intentionally concise — no prop details.
+ * Use the HTML reporter for comprehensive prop analysis.
+ */
+export function formatMetadataAsMarkdown(data: UsageReportOutput): string {
+  const { legend, fileMap, packages: metadata } = data;
+  const lines: string[] = [];
+
+  lines.push('# Fluent UI Codebase Usage Report');
+  lines.push('');
+
+  // Legend
+  lines.push('## Legend');
+  lines.push('');
+  lines.push('| Category | Description |');
+  lines.push('| -------- | ----------- |');
+  for (const entry of Object.values(legend)) {
+    lines.push(`| **${entry.name}** | ${entry.description} |`);
+  }
+  lines.push('');
+
+  // File map
+  lines.push(`**Files analyzed:** ${fileMap.length}`);
+  lines.push('');
+
+  const packageNames = Object.keys(metadata).sort();
+
+  if (packageNames.length === 0) {
+    lines.push('No Fluent UI package usage found.');
+    return lines.join('\n');
+  }
+
+  // Summary tables grouped by npm scope
+  lines.push('## Summary');
+  lines.push('');
+
+  const scopeGroups = groupByScope(packageNames);
+  for (const [scope, names] of scopeGroups) {
+    lines.push(`### ${scope}`);
+    lines.push('');
+    lines.push('| Package | Components | Hooks | Types | Others | Unknowns | Total Imports |');
+    lines.push('| ------- | ---------- | ----- | ----- | ------ | -------- | ------------- |');
+
+    for (const name of names) {
+      const pkg = metadata[name];
+      lines.push(
+        `| \`${name}\` | ${Object.keys(pkg.components).length} | ${Object.keys(pkg.hooks).length} | ${
+          Object.keys(pkg.types).length
+        } | ${Object.keys(pkg.others).length} | ${Object.keys(pkg.unknowns).length} | ${pkg.count} |`,
+      );
+    }
+    lines.push('');
+  }
+
+  // Detailed sections per package
+  for (const name of packageNames) {
+    const pkg = metadata[name];
+    lines.push(`## \`${name}\``);
+    lines.push('');
+
+    if (Object.keys(pkg.components).length > 0) {
+      lines.push(...formatSymbolsWithCount('Components', pkg.components));
+    }
+
+    if (Object.keys(pkg.hooks).length > 0) {
+      lines.push(...formatSymbolsWithCount('Hooks', pkg.hooks));
+    }
+
+    if (Object.keys(pkg.types).length > 0) {
+      lines.push(...formatTypesSection(pkg.types));
+    }
+
+    if (Object.keys(pkg.others).length > 0) {
+      lines.push(...formatSymbolsWithCount('Other Exports', pkg.others));
+    }
+
+    if (Object.keys(pkg.unknowns).length > 0) {
+      lines.push(...formatUnknownsSection(pkg.unknowns));
+    }
+  }
+
+  return lines.join('\n');
+}
+
+function formatSymbolsWithCount(
+  title: string,
+  symbols: Record<string, ComponentUsage | HookUsage | FunctionUsage>,
+): string[] {
+  const lines: string[] = [];
+  lines.push(`### ${title}`);
+  lines.push('');
+  lines.push('| Symbol | Usages |');
+  lines.push('| ------ | ------ |');
+
+  for (const [name, usage] of Object.entries(symbols).sort(([, a], [, b]) => b.count - a.count)) {
+    lines.push(`| \`${name}\` | ${usage.count} |`);
+  }
+  lines.push('');
+  return lines;
+}
+
+function formatTypesSection(types: Record<string, TypeUsage>): string[] {
+  const lines: string[] = [];
+  lines.push('### Types');
+  lines.push('');
+  lines.push('| Symbol | Usages | typeof | Type Args |');
+  lines.push('| ------ | ------ | ------ | --------- |');
+
+  for (const [name, usage] of Object.entries(types).sort(([, a], [, b]) => b.count - a.count)) {
+    lines.push(`| \`${name}\` | ${usage.count} | ${usage.typeofCount} | ${Object.keys(usage.props).length} |`);
+  }
+  lines.push('');
+  return lines;
+}
+
+function formatUnknownsSection(unknowns: Record<string, UnknownSymbolUsage>): string[] {
+  const lines: string[] = [];
+  lines.push('### Unknowns');
+  lines.push('');
+  lines.push(
+    '> Symbols whose `.d.ts` declarations could not be resolved. Install types or add declarations to improve classification.',
+  );
+  lines.push('');
+  lines.push('| Symbol | Usages | Description |');
+  lines.push('| ------ | ------ | ----------- |');
+
+  for (const [name, usage] of Object.entries(unknowns).sort(([, a], [, b]) => b.count - a.count)) {
+    lines.push(`| \`${name}\` | ${usage.count} | ${usage.description} |`);
+  }
+  lines.push('');
+  return lines;
+}
+
+/**
+ * Group package names by npm scope. Scoped packages (@scope/name) are grouped
+ * under their scope; unscoped packages go under "Other Packages".
+ * Returns entries sorted by scope name, with each group's packages sorted alphabetically.
+ */
+function groupByScope(packageNames: string[]): Array<[string, string[]]> {
+  const groups = new Map<string, string[]>();
+  for (const name of packageNames) {
+    const scope = name.startsWith('@') ? name.split('/')[0] : 'Other Packages';
+    if (!groups.has(scope)) {
+      groups.set(scope, []);
+    }
+    groups.get(scope)!.push(name);
+  }
+  return [...groups.entries()].sort(([a], [b]) => a.localeCompare(b));
+}
diff --git a/tools/cli/src/commands/report/impl/package-resolver.spec.ts b/tools/cli/src/commands/report/impl/package-resolver.spec.ts
new file mode 100644
index 0000000000000..c367eea0b1243
--- /dev/null
+++ b/tools/cli/src/commands/report/impl/package-resolver.spec.ts
@@ -0,0 +1,261 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { execSync } from 'node:child_process';
+
+import {
+  isReportablePackage,
+  isReportablePackageForLong,
+  getSystemInfo,
+  getMatchingPackages,
+  resolvePackageVersions,
+  findDuplicatePackages,
+  getGitRoot,
+} from './package-resolver';
+
+jest.mock('node:child_process', () => ({
+  execSync: jest.fn(),
+}));
+
+jest.mock('node:fs', () => ({
+  existsSync: jest.fn(),
+  readFileSync: jest.fn(),
+  readdirSync: jest.fn(),
+}));
+
+const mockExecSync = execSync as jest.MockedFunction<typeof execSync>;
+const mockExistsSync = fs.existsSync as jest.MockedFunction<typeof fs.existsSync>;
+const mockReadFileSync = fs.readFileSync as jest.MockedFunction<typeof fs.readFileSync>;
+const mockReaddirSync = fs.readdirSync as jest.MockedFunction<typeof fs.readdirSync>;
+
+describe('package-resolver', () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+  });
+
+  describe('isReportablePackage', () => {
+    it('should match @fluentui scoped packages', () => {
+      expect(isReportablePackage('@fluentui/react-components')).toBe(true);
+      expect(isReportablePackage('@fluentui/react-icons')).toBe(true);
+    });
+
+    it('should match @fluentui-contrib scoped packages', () => {
+      expect(isReportablePackage('@fluentui-contrib/shadow-dom')).toBe(true);
+    });
+
+    it('should match @griffel scoped packages', () => {
+      expect(isReportablePackage('@griffel/react')).toBe(true);
+    });
+
+    it('should match @floating-ui scoped packages', () => {
+      expect(isReportablePackage('@floating-ui/dom')).toBe(true);
+    });
+
+    it('should match exact fluent-related packages', () => {
+      expect(isReportablePackage('tabster')).toBe(true);
+      expect(isReportablePackage('keyborg')).toBe(true);
+    });
+
+    it('should match third-party exact packages', () => {
+      expect(isReportablePackage('react')).toBe(true);
+      expect(isReportablePackage('@types/react')).toBe(true);
+      expect(isReportablePackage('typescript')).toBe(true);
+    });
+
+    it('should not match unrelated packages', () => {
+      expect(isReportablePackage('lodash')).toBe(false);
+      expect(isReportablePackage('@babel/core')).toBe(false);
+      expect(isReportablePackage('react-dom')).toBe(false);
+    });
+  });
+
+  describe('isReportablePackageForLong', () => {
+    it('should match @fluentui and @griffel scoped packages', () => {
+      expect(isReportablePackageForLong('@fluentui/react-components')).toBe(true);
+      expect(isReportablePackageForLong('@fluentui-contrib/shadow-dom')).toBe(true);
+      expect(isReportablePackageForLong('@griffel/react')).toBe(true);
+    });
+
+    it('should match fluent-related exact packages', () => {
+      expect(isReportablePackageForLong('tabster')).toBe(true);
+      expect(isReportablePackageForLong('keyborg')).toBe(true);
+    });
+
+    it('should NOT match react, @types/react, typescript', () => {
+      expect(isReportablePackageForLong('react')).toBe(false);
+      expect(isReportablePackageForLong('@types/react')).toBe(false);
+      expect(isReportablePackageForLong('typescript')).toBe(false);
+    });
+
+    it('should NOT match @floating-ui packages', () => {
+      expect(isReportablePackageForLong('@floating-ui/dom')).toBe(false);
+    });
+
+    it('should NOT match unrelated packages', () => {
+      expect(isReportablePackageForLong('lodash')).toBe(false);
+    });
+  });
+
+  describe('getSystemInfo', () => {
+    it('should return system info with detected package manager', () => {
+      mockExistsSync.mockImplementation((p: fs.PathLike) => {
+        return String(p).endsWith('yarn.lock');
+      });
+      mockExecSync.mockReturnValue('1.22.19\n');
+
+      const info = getSystemInfo('/mock/root');
+
+      expect(info.node).toBe(process.version.replace(/^v/, ''));
+      expect(info.os).toBe(`${process.platform}-${process.arch}`);
+      expect(info.packageManager).toBe('yarn 1.22.19');
+    });
+
+    it('should detect npm when package-lock.json exists', () => {
+      mockExistsSync.mockImplementation((p: fs.PathLike) => {
+        return String(p).endsWith('package-lock.json');
+      });
+      mockExecSync.mockReturnValue('10.0.0\n');
+
+      const info = getSystemInfo('/mock/root');
+
+      expect(info.packageManager).toBe('npm 10.0.0');
+    });
+
+    it('should return "unknown" when no lock file found', () => {
+      mockExistsSync.mockReturnValue(false);
+
+      const info = getSystemInfo('/mock/root');
+
+      expect(info.packageManager).toBe('unknown');
+    });
+  });
+
+  describe('getMatchingPackages', () => {
+    it('should return matching packages from package.json', () => {
+      mockExistsSync.mockReturnValue(true);
+      mockReadFileSync.mockReturnValue(
+        JSON.stringify({
+          dependencies: {
+            '@fluentui/react-components': '^9.50.0',
+            react: '^18.2.0',
+            lodash: '^4.0.0',
+          },
+          devDependencies: {
+            typescript: '^5.3.0',
+            '@babel/core': '^7.0.0',
+          },
+        }),
+      );
+
+      const packages = getMatchingPackages('/mock/root');
+
+      expect(packages).toContain('@fluentui/react-components');
+      expect(packages).toContain('react');
+      expect(packages).toContain('typescript');
+      expect(packages).not.toContain('lodash');
+      expect(packages).not.toContain('@babel/core');
+    });
+
+    it('should return empty array when package.json not found', () => {
+      mockExistsSync.mockReturnValue(false);
+
+      const packages = getMatchingPackages('/mock/root');
+
+      expect(packages).toEqual([]);
+    });
+  });
+
+  describe('resolvePackageVersions', () => {
+    it('should resolve installed versions from node_modules', () => {
+      mockReadFileSync.mockImplementation((p: fs.PathOrFileDescriptor) => {
+        const filePath = String(p);
+        if (filePath.includes('@fluentui/react-components')) {
+          return JSON.stringify({ version: '9.50.0' });
+        }
+        if (filePath.includes('react') && !filePath.includes('@')) {
+          return JSON.stringify({ version: '18.2.0' });
+        }
+        throw new Error('not found');
+      });
+
+      const packages = resolvePackageVersions(['@fluentui/react-components', 'react', 'nonexistent'], '/mock/root');
+
+      expect(packages).toEqual([
+        { name: '@fluentui/react-components', version: '9.50.0' },
+        { name: 'react', version: '18.2.0' },
+      ]);
+    });
+  });
+
+  describe('findDuplicatePackages', () => {
+    it('should detect duplicate packages with different versions', () => {
+      // Top-level version
+      mockReadFileSync.mockImplementation((p: fs.PathOrFileDescriptor) => {
+        const filePath = String(p);
+        if (filePath === path.join('/mock/root', 'node_modules', '@fluentui/react-icons', 'package.json')) {
+          return JSON.stringify({ version: '2.0.200' });
+        }
+        // Nested version under some-package
+        if (filePath.includes('some-package') && filePath.includes('@fluentui/react-icons')) {
+          return JSON.stringify({ version: '2.0.195' });
+        }
+        throw new Error('not found');
+      });
+
+      mockExistsSync.mockImplementation((p: fs.PathLike) => {
+        const filePath = String(p);
+        return filePath.includes('node_modules');
+      });
+
+      mockReaddirSync.mockImplementation((p: fs.PathLike) => {
+        const dirPath = String(p);
+        if (dirPath === path.join('/mock/root', 'node_modules')) {
+          return ['some-package', '@fluentui'] as unknown as ReturnType<typeof fs.readdirSync>;
+        }
+        if (dirPath.endsWith('@fluentui')) {
+          return ['react-icons'] as unknown as ReturnType<typeof fs.readdirSync>;
+        }
+        return [] as unknown as ReturnType<typeof fs.readdirSync>;
+      });
+
+      const duplicates = findDuplicatePackages(['@fluentui/react-icons'], '/mock/root');
+
+      expect(duplicates).toHaveLength(1);
+      expect(duplicates[0].name).toBe('@fluentui/react-icons');
+      expect(duplicates[0].versions).toHaveLength(2);
+    });
+
+    it('should return empty array when no duplicates', () => {
+      mockReadFileSync.mockImplementation((p: fs.PathOrFileDescriptor) => {
+        const filePath = String(p);
+        if (filePath === path.join('/mock/root', 'node_modules', 'react', 'package.json')) {
+          return JSON.stringify({ version: '18.2.0' });
+        }
+        throw new Error('not found');
+      });
+
+      mockExistsSync.mockImplementation((p: fs.PathLike) => {
+        const filePath = String(p);
+        if (filePath === path.join('/mock/root', 'node_modules')) {
+          return true;
+        }
+        return false;
+      });
+
+      mockReaddirSync.mockReturnValue([] as unknown as ReturnType<typeof fs.readdirSync>);
+
+      const duplicates = findDuplicatePackages(['react'], '/mock/root');
+
+      expect(duplicates).toEqual([]);
+    });
+  });
+
+  describe('getGitRoot', () => {
+    it('should return trimmed git root path', () => {
+      mockExecSync.mockReturnValue('/Users/test/project\n');
+
+      const root = getGitRoot();
+
+      expect(root).toBe('/Users/test/project');
+    });
+  });
+});
diff --git a/tools/cli/src/commands/report/impl/package-resolver.ts b/tools/cli/src/commands/report/impl/package-resolver.ts
new file mode 100644
index 0000000000000..290da40b4c721
--- /dev/null
+++ b/tools/cli/src/commands/report/impl/package-resolver.ts
@@ -0,0 +1,221 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { execSync } from 'node:child_process';
+
+import type { SystemInfo, ResolvedPackage, DuplicatePackage } from './types';
+
+/**
+ * Package name patterns we're interested in for reporting.
+ */
+const FLUENT_SCOPED_PATTERNS = ['@fluentui/', '@fluentui-contrib/'];
+const FLUENT_RELATED_PATTERNS = ['@griffel/'];
+const FLUENT_RELATED_EXACT = ['tabster', 'keyborg'];
+const THIRD_PARTY_PATTERNS = ['@floating-ui/'];
+const THIRD_PARTY_EXACT = ['react', '@types/react', 'typescript'];
+
+/**
+ * Checks if a package name matches our reporting criteria (short report — includes 3rd-party).
+ */
+export function isReportablePackage(name: string): boolean {
+  for (const pattern of [...FLUENT_SCOPED_PATTERNS, ...FLUENT_RELATED_PATTERNS, ...THIRD_PARTY_PATTERNS]) {
+    if (name.startsWith(pattern)) {
+      return true;
+    }
+  }
+  return [...FLUENT_RELATED_EXACT, ...THIRD_PARTY_EXACT].includes(name);
+}
+
+/**
+ * Checks if a package name matches long report criteria (excludes generic 3rd-party like react/typescript).
+ */
+export function isReportablePackageForLong(name: string): boolean {
+  for (const pattern of [...FLUENT_SCOPED_PATTERNS, ...FLUENT_RELATED_PATTERNS]) {
+    if (name.startsWith(pattern)) {
+      return true;
+    }
+  }
+  return FLUENT_RELATED_EXACT.includes(name);
+}
+
+/**
+ * Get system information for the short report.
+ */
+export function getSystemInfo(rootDir: string): SystemInfo {
+  const nodeVersion = process.version.replace(/^v/, '');
+  const os = `${process.platform}-${process.arch}`;
+  const nativeTarget = getNativeTarget();
+  const packageManager = detectPackageManager(rootDir);
+
+  return { node: nodeVersion, os, nativeTarget, packageManager };
+}
+
+function getNativeTarget(): string {
+  const arch = process.arch === 'arm64' ? 'aarch64' : process.arch === 'x64' ? 'x86_64' : process.arch;
+  const platform = process.platform === 'darwin' ? 'macos' : process.platform === 'win32' ? 'windows' : 'linux';
+  return `${arch}-${platform}`;
+}
+
+function detectPackageManager(rootDir: string): string {
+  const lockFiles: Array<{ file: string; name: string; command: string }> = [
+    { file: 'yarn.lock', name: 'yarn', command: 'yarn --version' },
+    { file: 'pnpm-lock.yaml', name: 'pnpm', command: 'pnpm --version' },
+    { file: 'package-lock.json', name: 'npm', command: 'npm --version' },
+    { file: 'bun.lockb', name: 'bun', command: 'bun --version' },
+  ];
+
+  for (const { file, name, command } of lockFiles) {
+    if (fs.existsSync(path.join(rootDir, file))) {
+      try {
+        const version = execSync(command, { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] }).trim();
+        return `${name} ${version}`;
+      } catch {
+        return name;
+      }
+    }
+  }
+  return 'unknown';
+}
+
+/**
+ * Read package.json and return all dependency names that match reporting criteria.
+ */
+export function getMatchingPackages(rootDir: string): string[] {
+  const packageJsonPath = path.join(rootDir, 'package.json');
+  if (!fs.existsSync(packageJsonPath)) {
+    return [];
+  }
+
+  const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf-8'));
+  const allDeps = {
+    ...packageJson.dependencies,
+    ...packageJson.devDependencies,
+  };
+
+  return Object.keys(allDeps).filter(isReportablePackage).sort();
+}
+
+/**
+ * Resolve installed versions for the given package names.
+ */
+export function resolvePackageVersions(packages: string[], rootDir: string): ResolvedPackage[] {
+  return packages
+    .map(name => {
+      const version = resolveInstalledVersion(name, rootDir);
+      return version ? { name, version } : null;
+    })
+    .filter((pkg): pkg is ResolvedPackage => pkg !== null);
+}
+
+function resolveInstalledVersion(packageName: string, rootDir: string): string | null {
+  const pkgJsonPath = path.join(rootDir, 'node_modules', packageName, 'package.json');
+  try {
+    const pkgJson = JSON.parse(fs.readFileSync(pkgJsonPath, 'utf-8'));
+    return pkgJson.version ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Find packages that have multiple versions installed (not deduped).
+ * Walks the node_modules tree to find nested versions.
+ */
+export function findDuplicatePackages(packages: string[], rootDir: string): DuplicatePackage[] {
+  const duplicates: DuplicatePackage[] = [];
+
+  for (const packageName of packages) {
+    const versions = findAllInstalledVersions(packageName, rootDir);
+    if (versions.length > 1) {
+      duplicates.push({ name: packageName, versions: versions.sort() });
+    }
+  }
+
+  return duplicates;
+}
+
+function findAllInstalledVersions(packageName: string, rootDir: string): string[] {
+  const versions = new Set<string>();
+
+  // Check top-level node_modules
+  const topLevelVersion = resolveInstalledVersion(packageName, rootDir);
+  if (topLevelVersion) {
+    versions.add(topLevelVersion);
+  }
+
+  // Walk nested node_modules directories for additional versions
+  walkNestedNodeModules(rootDir, packageName, versions);
+
+  return Array.from(versions);
+}
+
+function walkNestedNodeModules(rootDir: string, packageName: string, versions: Set<string>, depth = 0): void {
+  if (depth > 5) {
+    return;
+  }
+
+  const nodeModulesDir = path.join(rootDir, 'node_modules');
+  if (!fs.existsSync(nodeModulesDir)) {
+    return;
+  }
+
+  let entries: string[];
+  try {
+    entries = fs.readdirSync(nodeModulesDir);
+  } catch {
+    return;
+  }
+
+  for (const entry of entries) {
+    if (entry.startsWith('.')) {
+      continue;
+    }
+
+    const entryPath = path.join(nodeModulesDir, entry);
+
+    if (entry.startsWith('@')) {
+      // Scoped package — read subdirectories
+      let scopedEntries: string[];
+      try {
+        scopedEntries = fs.readdirSync(entryPath);
+      } catch {
+        continue;
+      }
+      for (const scopedEntry of scopedEntries) {
+        const scopedPackageName = `${entry}/${scopedEntry}`;
+        const nestedPkgJsonPath = path.join(entryPath, scopedEntry, 'node_modules', packageName, 'package.json');
+        tryAddVersion(nestedPkgJsonPath, versions);
+
+        // Recurse into the scoped package's node_modules
+        if (scopedPackageName !== packageName) {
+          walkNestedNodeModules(path.join(entryPath, scopedEntry), packageName, versions, depth + 1);
+        }
+      }
+    } else {
+      // Regular package — check for nested copy of our target
+      const nestedPkgJsonPath = path.join(entryPath, 'node_modules', packageName, 'package.json');
+      tryAddVersion(nestedPkgJsonPath, versions);
+
+      if (entry !== packageName) {
+        walkNestedNodeModules(entryPath, packageName, versions, depth + 1);
+      }
+    }
+  }
+}
+
+function tryAddVersion(pkgJsonPath: string, versions: Set<string>): void {
+  try {
+    const pkgJson = JSON.parse(fs.readFileSync(pkgJsonPath, 'utf-8'));
+    if (pkgJson.version) {
+      versions.add(pkgJson.version);
+    }
+  } catch {
+    // Package not found at this path
+  }
+}
+
+/**
+ * Get the git root directory.
+ */
+export function getGitRoot(): string {
+  return execSync('git rev-parse --show-toplevel', { encoding: 'utf-8' }).trim();
+}
diff --git a/tools/cli/src/commands/report/impl/types.ts b/tools/cli/src/commands/report/impl/types.ts
new file mode 100644
index 0000000000000..7d862b94cc124
--- /dev/null
+++ b/tools/cli/src/commands/report/impl/types.ts
@@ -0,0 +1,273 @@
+// ============================================================================
+// Report command types
+// ============================================================================
+
+/**
+ * Parsed CLI arguments for the `report info` subcommand.
+ */
+
+export interface InfoArgs {
+  /** Output file path. Defaults to stdout. */
+  output?: string;
+}
+
+/**
+ * Parsed CLI arguments for the `report usage` subcommand.
+ */
+export interface UsageArgs {
+  /** Root path for file traversal. Defaults to git root. */
+  path?: string;
+  /** Output format. Defaults to 'json'. */
+  reporter?: 'json' | 'markdown' | 'html';
+  /** Glob patterns to include. Only matching files are analyzed. */
+  include?: string[];
+  /** Glob patterns to exclude. Matching files are skipped. */
+  exclude?: string[];
+  /** Output file path. Defaults to stdout. */
+  output?: string;
+}
+
+/**
+ * System information included in the short report.
+ */
+export interface SystemInfo {
+  node: string;
+  os: string;
+  nativeTarget: string;
+  packageManager: string;
+}
+
+/**
+ * A resolved package with its installed version.
+ */
+export interface ResolvedPackage {
+  name: string;
+  version: string;
+}
+
+/**
+ * A package with multiple installed versions (duplicate).
+ */
+export interface DuplicatePackage {
+  name: string;
+  versions: string[];
+}
+
+/**
+ * Data collected for the short report output.
+ */
+export interface InfoReportData {
+  system: SystemInfo;
+  packages: ResolvedPackage[];
+  duplicates: DuplicatePackage[];
+}
+
+// ============================================================================
+// Long report (Metadata) types
+// ============================================================================
+
+/**
+ * Prop usage information — tracks which values are used and how many times.
+ */
+export interface PropUsage {
+  values: string[];
+  count: number;
+}
+
+/**
+ * Component usage information — tracks props and usage count.
+ */
+export interface ComponentUsage {
+  props: Record<string, PropUsage>;
+  count: number;
+}
+
+/**
+ * Hook usage information — tracks argument props and usage count.
+ */
+export interface HookUsage {
+  props: Record<string, PropUsage>;
+  count: number;
+}
+
+/**
+ * Type/symbol usage — tracks count only.
+ */
+export interface SymbolUsage {
+  count: number;
+}
+
+/**
+ * Type usage — tracks count, typeof references, and generic type arguments.
+ * Richer than SymbolUsage: distinguishes `typeof X` from standard annotations
+ * and captures generic type params (e.g., `DataGridProps<{hello: 'world'}>`)
+ * similarly to how component/hook props are captured.
+ */
+export interface TypeUsage {
+  count: number;
+  /** Number of typeof references (e.g., `typeof Button`). */
+  typeofCount: number;
+  /** Generic type argument usage — captured like component/hook props. */
+  props: Record<string, PropUsage>;
+}
+
+/**
+ * Function/utility usage — tracks count and call arguments.
+ */
+export interface FunctionUsage {
+  props: Record<string, PropUsage>;
+  count: number;
+}
+
+/**
+ * Unknown symbol usage — symbol whose .d.ts couldn't be resolved.
+ * Includes a description hinting at what the symbol might be.
+ * If the symbol is callable, props tracks its call arguments.
+ */
+export interface UnknownSymbolUsage {
+  props: Record<string, PropUsage>;
+  count: number;
+  description: string;
+}
+
+/**
+ * Usage data for a single package import.
+ */
+export interface PackageUsageData {
+  components: Record<string, ComponentUsage>;
+  hooks: Record<string, HookUsage>;
+  types: Record<string, TypeUsage>;
+  others: Record<string, FunctionUsage>;
+  unknowns: Record<string, UnknownSymbolUsage>;
+  count: number;
+}
+
+/**
+ * Full metadata structure produced by the long report.
+ * Keys are package import specifiers (e.g. `@proj/react-components`).
+ */
+export type Metadata = Record<string, PackageUsageData>;
+
+/**
+ * Describes a single report category in the legend.
+ */
+export interface CategoryLegendEntry {
+  /** Human-readable category name. */
+  name: string;
+  /** Short description of what the category contains. */
+  description: string;
+}
+
+/**
+ * Complete long report output including the file map and per-package metadata.
+ */
+export interface UsageReportOutput {
+  /** Describes each category used in the report. */
+  legend: Record<string, CategoryLegendEntry>;
+  /** Relative paths of all source files analyzed. */
+  fileMap: string[];
+  /** Per-package usage metadata. */
+  packages: Metadata;
+}
+
+// ============================================================================
+// AST parser abstraction types
+// ============================================================================
+
+/**
+ * Represents a single named import from a module.
+ */
+export interface ImportInfo {
+  moduleSpecifier: string;
+  namedImports: string[];
+  isTypeOnly: boolean;
+}
+
+/**
+ * Represents a JSX element usage with its props.
+ */
+export interface JsxUsageInfo {
+  componentName: string;
+  props: Record<string, string | undefined>;
+  moduleSpecifier: string;
+}
+
+/**
+ * Represents a function call expression usage.
+ */
+export interface CallUsageInfo {
+  functionName: string;
+  args: Record<string, string | undefined>;
+  moduleSpecifier: string;
+}
+
+/**
+ * Represents a type reference usage (typeof or generic type params).
+ */
+export interface TypeRefUsageInfo {
+  symbolName: string;
+  moduleSpecifier: string;
+  kind: 'typeof' | 'generic';
+  typeArgs?: string[];
+}
+
+/**
+ * Classification of an imported symbol based on its type definition.
+ */
+export type SymbolClassification = 'component' | 'hook' | 'type' | 'other' | 'unknown';
+
+/**
+ * Abstract AST parser interface.
+ * Implementations can use ts-morph, raw TypeScript compiler API, or any other parser.
+ */
+export interface AstParser {
+  /**
+   * Initialize a project from source files.
+   */
+  createProject(filePaths: string[], tsConfigPath?: string, rootPath?: string): void;
+
+  /**
+   * Get all source file paths in the project.
+   */
+  getSourceFiles(): string[];
+
+  /**
+   * Get all import declarations from a source file.
+   */
+  getImportDeclarations(filePath: string): ImportInfo[];
+
+  /**
+   * Get all JSX element usages from a source file.
+   */
+  getJsxElementUsages(filePath: string): JsxUsageInfo[];
+
+  /**
+   * Get all function call expression usages from a source file.
+   */
+  getCallExpressionUsages(filePath: string): CallUsageInfo[];
+
+  /**
+   * Classify an imported symbol by resolving its type definition.
+   *
+   * @param filePath - Source file containing the import.
+   * @param symbolName - The imported symbol name.
+   * @param moduleSpecifier - The module specifier of the import.
+   * @returns The symbol classification.
+   */
+  classifySymbol(filePath: string, symbolName: string, moduleSpecifier: string): SymbolClassification;
+
+  /**
+   * Generate a description for an unknown symbol based on naming conventions.
+   */
+  describeUnknownSymbol(symbolName: string): string;
+
+  /**
+   * Get type reference usages (typeof and generic type params) from a source file.
+   */
+  getTypeReferenceUsages(filePath: string): TypeRefUsageInfo[];
+
+  /**
+   * Get value reference usages (non-JSX, non-call identifier references) from a source file.
+   */
+  getValueReferenceUsages(filePath: string): Array<{ symbolName: string; moduleSpecifier: string }>;
+}
diff --git a/tools/cli/src/commands/report/impl/usage-report.spec.ts b/tools/cli/src/commands/report/impl/usage-report.spec.ts
new file mode 100644
index 0000000000000..9f18824da1700
--- /dev/null
+++ b/tools/cli/src/commands/report/impl/usage-report.spec.ts
@@ -0,0 +1,630 @@
+import { collectUsageReportData } from './usage-report';
+import type {
+  AstParser,
+  ImportInfo,
+  JsxUsageInfo,
+  CallUsageInfo,
+  SymbolClassification,
+  TypeRefUsageInfo,
+} from './types';
+
+jest.mock('./package-resolver', () => ({
+  getGitRoot: jest.fn().mockReturnValue('/mock/root'),
+  isReportablePackageForLong: jest.fn().mockReturnValue(true),
+}));
+
+jest.mock('./file-discovery', () => ({
+  discoverSourceFiles: jest.fn().mockReturnValue(['/mock/root/src/App.tsx', '/mock/root/src/types.ts']),
+  filterSourceFiles: jest.fn().mockImplementation((files: string[]) => files),
+}));
+
+jest.mock('node:fs', () => ({
+  ...jest.requireActual('node:fs'),
+  existsSync: jest.fn().mockReturnValue(false),
+}));
+
+function createMockParser(
+  imports: Record<string, ImportInfo[]>,
+  jsxUsages: Record<string, JsxUsageInfo[]>,
+  callUsages: Record<string, CallUsageInfo[]>,
+  classifications?: Record<string, SymbolClassification>,
+  typeRefUsages?: Record<string, TypeRefUsageInfo[]>,
+  valueRefUsages?: Record<string, Array<{ symbolName: string; moduleSpecifier: string }>>,
+): AstParser {
+  return {
+    createProject: jest.fn(),
+    getSourceFiles: jest.fn().mockReturnValue(Object.keys(imports)),
+    getImportDeclarations: jest.fn((filePath: string) => imports[filePath] ?? []),
+    getJsxElementUsages: jest.fn((filePath: string) => jsxUsages[filePath] ?? []),
+    getCallExpressionUsages: jest.fn((filePath: string) => callUsages[filePath] ?? []),
+    getTypeReferenceUsages: jest.fn((filePath: string) => (typeRefUsages ?? {})[filePath] ?? []),
+    getValueReferenceUsages: jest.fn((filePath: string) => (valueRefUsages ?? {})[filePath] ?? []),
+    classifySymbol: jest.fn((_filePath: string, symbolName: string, _moduleSpecifier: string) => {
+      if (classifications && symbolName in classifications) {
+        return classifications[symbolName];
+      }
+      // Default fallback
+      if (/^use[A-Z]/.test(symbolName)) {
+        return 'hook';
+      }
+      if (/^[A-Z]/.test(symbolName)) {
+        return 'component';
+      }
+      return 'other';
+    }),
+    describeUnknownSymbol: jest.fn((symbolName: string) => {
+      if (/^use[A-Z]/.test(symbolName)) {
+        return 'Likely a React hook (use* naming convention)';
+      }
+      if (/Props$/.test(symbolName)) {
+        return 'Likely a type/interface (*Props naming convention)';
+      }
+      if (/^[A-Z]/.test(symbolName)) {
+        return 'PascalCase symbol — could be a component, constant, or type';
+      }
+      return 'Unresolved symbol — .d.ts not available';
+    }),
+  };
+}
+
+describe('usage-report', () => {
+  it('should collect metadata for component usages', () => {
+    const parser = createMockParser(
+      {
+        '/mock/root/src/App.tsx': [
+          {
+            moduleSpecifier: '@proj/react-components',
+            namedImports: ['Button', 'Input'],
+            isTypeOnly: false,
+          },
+        ],
+      },
+      {
+        '/mock/root/src/App.tsx': [
+          {
+            componentName: 'Button',
+            props: { appearance: 'primary', size: 'medium' },
+            moduleSpecifier: '@proj/react-components',
+          },
+          {
+            componentName: 'Button',
+            props: { appearance: 'secondary' },
+            moduleSpecifier: '@proj/react-components',
+          },
+          {
+            componentName: 'Input',
+            props: { placeholder: 'Search...' },
+            moduleSpecifier: '@proj/react-components',
+          },
+        ],
+      },
+      {},
+    );
+
+    const result = collectUsageReportData('/mock/root', parser);
+
+    expect(result.packages['@proj/react-components']).toBeDefined();
+
+    const pkg = result.packages['@proj/react-components'];
+    expect(pkg.components.Button.count).toBe(2);
+    expect(pkg.components.Button.props.appearance.values).toEqual(['primary', 'secondary']);
+    expect(pkg.components.Button.props.appearance.count).toBe(2);
+    expect(pkg.components.Input.count).toBe(1);
+  });
+
+  it('should collect metadata for hook usages', () => {
+    const parser = createMockParser(
+      {
+        '/mock/root/src/App.tsx': [
+          {
+            moduleSpecifier: '@proj/react-components',
+            namedImports: ['useId', 'useToastController'],
+            isTypeOnly: false,
+          },
+        ],
+      },
+      {},
+      {
+        '/mock/root/src/App.tsx': [
+          {
+            functionName: 'useId',
+            args: { arg0: "'my-id'" },
+            moduleSpecifier: '@proj/react-components',
+          },
+          {
+            functionName: 'useToastController',
+            args: {},
+            moduleSpecifier: '@proj/react-components',
+          },
+        ],
+      },
+    );
+
+    const result = collectUsageReportData('/mock/root', parser);
+
+    const pkg = result.packages['@proj/react-components'];
+    expect(pkg.hooks.useId.count).toBe(1);
+    expect(pkg.hooks.useId.props.arg0.values).toEqual(["'my-id'"]);
+    expect(pkg.hooks.useToastController.count).toBe(1);
+  });
+
+  it('should collect metadata for type-only imports', () => {
+    const parser = createMockParser(
+      {
+        '/mock/root/src/types.ts': [
+          {
+            moduleSpecifier: '@proj/react-components',
+            namedImports: ['ButtonProps', 'InputProps'],
+            isTypeOnly: true,
+          },
+        ],
+      },
+      {},
+      {},
+    );
+
+    const result = collectUsageReportData('/mock/root', parser);
+
+    const pkg = result.packages['@proj/react-components'];
+    expect(pkg.types.ButtonProps.count).toBe(1);
+    expect(pkg.types.ButtonProps.typeofCount).toBe(0);
+    expect(pkg.types.ButtonProps.props).toEqual({});
+    expect(pkg.types.InputProps.count).toBe(1);
+    expect(pkg.types.InputProps.typeofCount).toBe(0);
+  });
+
+  it('should track "other" symbols (non-component, non-hook, non-type)', () => {
+    const parser = createMockParser(
+      {
+        '/mock/root/src/App.tsx': [
+          {
+            moduleSpecifier: '@proj/react-components',
+            namedImports: ['tokens', 'webLightTheme'],
+            isTypeOnly: false,
+          },
+        ],
+      },
+      {},
+      {},
+    );
+
+    const result = collectUsageReportData('/mock/root', parser);
+
+    const pkg = result.packages['@proj/react-components'];
+    expect(pkg.others.tokens.count).toBe(1);
+    expect(pkg.others.webLightTheme.count).toBe(1);
+  });
+
+  it('should skip non-reportable packages', () => {
+    const { isReportablePackageForLong } = require('./package-resolver');
+    isReportablePackageForLong.mockImplementation((name: string) => name !== 'lodash');
+
+    const parser = createMockParser(
+      {
+        '/mock/root/src/App.tsx': [
+          {
+            moduleSpecifier: 'lodash',
+            namedImports: ['debounce'],
+            isTypeOnly: false,
+          },
+        ],
+      },
+      {},
+      {},
+    );
+
+    const result = collectUsageReportData('/mock/root', parser);
+
+    expect(result.packages.lodash).toBeUndefined();
+
+    isReportablePackageForLong.mockReturnValue(true);
+  });
+
+  it('should return empty metadata when no files are found', () => {
+    const { discoverSourceFiles } = require('./file-discovery');
+    discoverSourceFiles.mockReturnValueOnce([]);
+
+    const result = collectUsageReportData('/mock/root');
+
+    expect(result.fileMap).toEqual([]);
+    expect(result.packages).toEqual({});
+    expect(result.legend).toBeDefined();
+    expect(result.legend.components).toBeDefined();
+    expect(result.legend.types).toBeDefined();
+  });
+
+  it('should pass include/exclude to filterSourceFiles', () => {
+    const { filterSourceFiles } = require('./file-discovery');
+    const parser = createMockParser({ '/mock/root/src/App.tsx': [] }, {}, {});
+
+    collectUsageReportData('/mock/root', parser, ['src/**'], ['**/*.test.*']);
+
+    expect(filterSourceFiles).toHaveBeenCalledWith(
+      ['/mock/root/src/App.tsx', '/mock/root/src/types.ts'],
+      '/mock/root',
+      ['src/**'],
+      ['**/*.test.*'],
+    );
+  });
+
+  it('should pass auto-detected tsconfig to createProject', () => {
+    const { existsSync } = require('node:fs');
+    existsSync.mockImplementation((p: string) => p === '/mock/root/tsconfig.json');
+
+    const parser = createMockParser({ '/mock/root/src/App.tsx': [] }, {}, {});
+
+    collectUsageReportData('/mock/root', parser);
+
+    expect(parser.createProject).toHaveBeenCalledWith(expect.any(Array), '/mock/root/tsconfig.json', '/mock/root');
+
+    existsSync.mockReturnValue(false);
+  });
+
+  it('should fall back to tsconfig.base.json when tsconfig.json is missing', () => {
+    const { existsSync } = require('node:fs');
+    existsSync.mockImplementation((p: string) => p === '/mock/root/tsconfig.base.json');
+
+    const parser = createMockParser({ '/mock/root/src/App.tsx': [] }, {}, {});
+
+    collectUsageReportData('/mock/root', parser);
+
+    expect(parser.createProject).toHaveBeenCalledWith(expect.any(Array), '/mock/root/tsconfig.base.json', '/mock/root');
+
+    existsSync.mockReturnValue(false);
+  });
+
+  it('should pass undefined tsconfig when none found', () => {
+    const parser = createMockParser({ '/mock/root/src/App.tsx': [] }, {}, {});
+
+    collectUsageReportData('/mock/root', parser);
+
+    expect(parser.createProject).toHaveBeenCalledWith(expect.any(Array), undefined, '/mock/root');
+  });
+
+  it('should handle multiple packages in same file', () => {
+    const parser = createMockParser(
+      {
+        '/mock/root/src/App.tsx': [
+          {
+            moduleSpecifier: '@proj/react-components',
+            namedImports: ['Button'],
+            isTypeOnly: false,
+          },
+          {
+            moduleSpecifier: '@griffel/react',
+            namedImports: ['makeStyles'],
+            isTypeOnly: false,
+          },
+        ],
+      },
+      {
+        '/mock/root/src/App.tsx': [
+          {
+            componentName: 'Button',
+            props: { appearance: 'primary' },
+            moduleSpecifier: '@proj/react-components',
+          },
+        ],
+      },
+      {},
+    );
+
+    const result = collectUsageReportData('/mock/root', parser);
+
+    expect(result.packages['@proj/react-components']).toBeDefined();
+    expect(result.packages['@griffel/react']).toBeDefined();
+    expect(result.packages['@griffel/react'].others.makeStyles.count).toBe(1);
+  });
+
+  it('should exclude non-reportable packages from long report', () => {
+    const { isReportablePackageForLong } = require('./package-resolver');
+    isReportablePackageForLong.mockImplementation((name: string) => name !== 'react');
+
+    const parser = createMockParser(
+      {
+        '/mock/root/src/App.tsx': [
+          {
+            moduleSpecifier: 'react',
+            namedImports: ['useState', 'useEffect'],
+            isTypeOnly: false,
+          },
+          {
+            moduleSpecifier: '@proj/react-components',
+            namedImports: ['Button'],
+            isTypeOnly: false,
+          },
+        ],
+      },
+      {},
+      {},
+    );
+
+    const result = collectUsageReportData('/mock/root', parser);
+
+    expect(result.packages.react).toBeUndefined();
+    expect(result.packages['@proj/react-components']).toBeDefined();
+
+    isReportablePackageForLong.mockReturnValue(true);
+  });
+
+  it('should classify PascalCase non-component symbols as "others" via classifySymbol', () => {
+    const parser = createMockParser(
+      {
+        '/mock/root/src/App.tsx': [
+          {
+            moduleSpecifier: '@proj/react-components',
+            namedImports: ['AzureLightTheme', 'tokens'],
+            isTypeOnly: false,
+          },
+        ],
+      },
+      {},
+      {},
+      { AzureLightTheme: 'other', tokens: 'other' },
+    );
+
+    const result = collectUsageReportData('/mock/root', parser);
+
+    const pkg = result.packages['@proj/react-components'];
+    expect(pkg.others.AzureLightTheme.count).toBe(1);
+    expect(pkg.others.tokens.count).toBe(1);
+    expect(pkg.components.AzureLightTheme).toBeUndefined();
+  });
+
+  it('should classify pure types (interfaces) without import type keyword', () => {
+    const parser = createMockParser(
+      {
+        '/mock/root/src/App.tsx': [
+          {
+            moduleSpecifier: '@proj/react-components',
+            namedImports: ['ButtonProps', 'Button'],
+            isTypeOnly: false,
+          },
+        ],
+      },
+      {},
+      {},
+      { ButtonProps: 'type', Button: 'component' },
+    );
+
+    const result = collectUsageReportData('/mock/root', parser);
+
+    const pkg = result.packages['@proj/react-components'];
+    expect(pkg.types.ButtonProps.count).toBe(1);
+    expect(pkg.types.ButtonProps.typeofCount).toBe(0);
+    expect(pkg.types.ButtonProps.props).toEqual({});
+    expect(pkg.components.Button).toBeDefined();
+    expect(pkg.others.ButtonProps).toBeUndefined();
+  });
+
+  it('should track typeof as type usage with typeofCount', () => {
+    const parser = createMockParser(
+      {
+        '/mock/root/src/App.tsx': [
+          {
+            moduleSpecifier: '@proj/react-components',
+            namedImports: ['Button'],
+            isTypeOnly: false,
+          },
+        ],
+      },
+      {},
+      {},
+      { Button: 'component' },
+      {
+        '/mock/root/src/App.tsx': [
+          { symbolName: 'Button', moduleSpecifier: '@proj/react-components', kind: 'typeof' as const },
+        ],
+      },
+    );
+
+    const result = collectUsageReportData('/mock/root', parser);
+
+    const pkg = result.packages['@proj/react-components'];
+    expect(pkg.types.Button).toBeDefined();
+    expect(pkg.types.Button.count).toBe(1);
+    expect(pkg.types.Button.typeofCount).toBe(1);
+    expect(pkg.types.Button.props).toEqual({});
+  });
+
+  it('should track component value references', () => {
+    const parser = createMockParser(
+      {
+        '/mock/root/src/App.tsx': [
+          {
+            moduleSpecifier: '@proj/react-components',
+            namedImports: ['Button'],
+            isTypeOnly: false,
+          },
+        ],
+      },
+      {},
+      {},
+      { Button: 'component' },
+      {},
+      {
+        '/mock/root/src/App.tsx': [{ symbolName: 'Button', moduleSpecifier: '@proj/react-components' }],
+      },
+    );
+
+    const result = collectUsageReportData('/mock/root', parser);
+
+    const pkg = result.packages['@proj/react-components'];
+    expect(pkg.components.Button.count).toBe(1);
+  });
+
+  it('should capture generic type arguments as props', () => {
+    const parser = createMockParser(
+      {
+        '/mock/root/src/App.tsx': [
+          {
+            moduleSpecifier: '@proj/react-components',
+            namedImports: ['ColumnDef'],
+            isTypeOnly: true,
+          },
+        ],
+      },
+      {},
+      {},
+      { ColumnDef: 'type' },
+      {
+        '/mock/root/src/App.tsx': [
+          {
+            symbolName: 'ColumnDef',
+            moduleSpecifier: '@proj/react-components',
+            kind: 'generic' as const,
+            typeArgs: ['{ name: string; age: number }'],
+          },
+          {
+            symbolName: 'ColumnDef',
+            moduleSpecifier: '@proj/react-components',
+            kind: 'generic' as const,
+            typeArgs: ['{ id: number; price: number }'],
+          },
+        ],
+      },
+    );
+
+    const result = collectUsageReportData('/mock/root', parser);
+
+    const pkg = result.packages['@proj/react-components'];
+    expect(pkg.types.ColumnDef).toBeDefined();
+    expect(pkg.types.ColumnDef.count).toBe(3); // 1 from import type + 2 from generic usages
+    expect(pkg.types.ColumnDef.typeofCount).toBe(0);
+    expect(pkg.types.ColumnDef.props.typeArg0).toBeDefined();
+    expect(pkg.types.ColumnDef.props.typeArg0.count).toBe(2);
+    expect(pkg.types.ColumnDef.props.typeArg0.values).toEqual([
+      '{ name: string; age: number }',
+      '{ id: number; price: number }',
+    ]);
+  });
+
+  it('should deduplicate symbols in both components and others', () => {
+    const parser = createMockParser(
+      {
+        '/mock/root/src/App.tsx': [
+          {
+            moduleSpecifier: '@proj/react-components',
+            namedImports: ['Button'],
+            isTypeOnly: false,
+          },
+        ],
+        '/mock/root/src/types.ts': [
+          {
+            moduleSpecifier: '@proj/react-components',
+            namedImports: ['Button'],
+            isTypeOnly: false,
+          },
+        ],
+      },
+      {
+        '/mock/root/src/App.tsx': [
+          {
+            componentName: 'Button',
+            props: {},
+            moduleSpecifier: '@proj/react-components',
+          },
+        ],
+      },
+      {},
+      {},
+    );
+
+    // Manually simulate what happens when classifySymbol returns 'component' in one file and 'other' in another
+    let callCount = 0;
+    (parser.classifySymbol as jest.Mock).mockImplementation((_fp: string, name: string) => {
+      if (name === 'Button') {
+        callCount++;
+        return callCount === 1 ? 'component' : 'other';
+      }
+      return 'other';
+    });
+
+    const result = collectUsageReportData('/mock/root', parser);
+
+    const pkg = result.packages['@proj/react-components'];
+    // Button has JSX usage (count > 0) so should be in components, NOT in others
+    expect(pkg.components.Button).toBeDefined();
+    expect(pkg.components.Button.count).toBe(1);
+    expect(pkg.others.Button).toBeUndefined();
+  });
+
+  it('should track unknown symbols with descriptions', () => {
+    const parser = createMockParser(
+      {
+        '/mock/root/src/App.tsx': [
+          {
+            moduleSpecifier: '@proj/react-components',
+            namedImports: ['SomeConstant', 'CustomProps'],
+            isTypeOnly: false,
+          },
+        ],
+      },
+      {},
+      {},
+      { SomeConstant: 'unknown', CustomProps: 'unknown' },
+    );
+
+    const result = collectUsageReportData('/mock/root', parser);
+
+    const pkg = result.packages['@proj/react-components'];
+    expect(pkg.unknowns.SomeConstant).toBeDefined();
+    expect(pkg.unknowns.SomeConstant.count).toBe(1);
+    expect(pkg.unknowns.SomeConstant.description).toBe('PascalCase symbol — could be a component, constant, or type');
+    expect(pkg.unknowns.CustomProps).toBeDefined();
+    expect(pkg.unknowns.CustomProps.description).toBe('Likely a type/interface (*Props naming convention)');
+  });
+
+  it('should deduplicate unknowns when symbol is also categorized elsewhere', () => {
+    const parser = createMockParser(
+      {
+        '/mock/root/src/App.tsx': [
+          {
+            moduleSpecifier: '@proj/react-components',
+            namedImports: ['Button'],
+            isTypeOnly: false,
+          },
+        ],
+      },
+      {
+        '/mock/root/src/App.tsx': [
+          {
+            componentName: 'Button',
+            props: {},
+            moduleSpecifier: '@proj/react-components',
+          },
+        ],
+      },
+      {},
+      { Button: 'unknown' },
+    );
+
+    const result = collectUsageReportData('/mock/root', parser);
+
+    const pkg = result.packages['@proj/react-components'];
+    // Button has JSX usage, so it should be in components and removed from unknowns
+    expect(pkg.components.Button).toBeDefined();
+    expect(pkg.components.Button.count).toBe(1);
+    expect(pkg.unknowns.Button).toBeUndefined();
+  });
+
+  it('should include fileMap with relative paths', () => {
+    const parser = createMockParser(
+      {
+        '/mock/root/src/App.tsx': [
+          {
+            moduleSpecifier: '@proj/react-components',
+            namedImports: ['Button'],
+            isTypeOnly: false,
+          },
+        ],
+      },
+      {},
+      {},
+    );
+
+    const result = collectUsageReportData('/mock/root', parser);
+
+    expect(result.fileMap).toEqual(['src/App.tsx', 'src/types.ts']);
+  });
+});
diff --git a/tools/cli/src/commands/report/impl/usage-report.ts b/tools/cli/src/commands/report/impl/usage-report.ts
new file mode 100644
index 0000000000000..d990aab26424f
--- /dev/null
+++ b/tools/cli/src/commands/report/impl/usage-report.ts
@@ -0,0 +1,390 @@
+import type { Metadata, PackageUsageData, AstParser, UsageReportOutput, TypeUsage, CategoryLegendEntry } from './types';
+import { isReportablePackageForLong, getGitRoot } from './package-resolver';
+import { discoverSourceFiles, filterSourceFiles } from './file-discovery';
+import { TsMorphAstParser } from './ast-parser';
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+/** tsconfig file names to probe, in priority order. */
+const TSCONFIG_CANDIDATES = ['tsconfig.json', 'tsconfig.base.json'];
+
+/** Category legend included in every long report output. */
+const CATEGORY_LEGEND: Record<string, CategoryLegendEntry> = {
+  components: {
+    name: 'Components',
+    description: 'React components (JSX elements). Tracks per-component prop usage with values.',
+  },
+  hooks: {
+    name: 'Hooks',
+    description: 'React hooks (use* naming convention). Tracks call-site argument usage with values.',
+  },
+  types: {
+    name: 'Types',
+    description:
+      'TypeScript interfaces, type aliases, and enums. Distinguishes typeof references from standard annotations and captures generic type arguments.',
+  },
+  others: {
+    name: 'Other Exports',
+    description:
+      'Value exports that are not components or hooks (constants, utility functions, theme objects). Tracks call-site argument usage when invoked.',
+  },
+  unknowns: {
+    name: 'Unknowns',
+    description:
+      'Symbols whose .d.ts declarations could not be resolved. Install types or add declarations to improve classification.',
+  },
+};
+
+/**
+ * Create an empty PackageUsageData entry.
+ */
+function createEmptyPackageUsageData(): PackageUsageData {
+  return {
+    components: {},
+    hooks: {},
+    types: {},
+    others: {},
+    unknowns: {},
+    count: 0,
+  };
+}
+
+/**
+ * Collect the long report output by analyzing source files.
+ *
+ * @param rootPath - Root directory for file traversal.
+ * @param parser - AST parser implementation (defaults to TsMorphAstParser).
+ * @param include - Glob patterns to include.
+ * @param exclude - Glob patterns to exclude.
+ */
+export function collectUsageReportData(
+  rootPath?: string,
+  parser?: AstParser,
+  include?: string[],
+  exclude?: string[],
+): UsageReportOutput {
+  const resolvedRoot = rootPath ?? getGitRoot();
+  const astParser = parser ?? new TsMorphAstParser();
+
+  // Discover source files and apply include/exclude filters
+  let filePaths = discoverSourceFiles(resolvedRoot);
+  filePaths = filterSourceFiles(filePaths, resolvedRoot, include, exclude);
+  if (filePaths.length === 0) {
+    return { legend: CATEGORY_LEGEND, fileMap: [], packages: {} };
+  }
+
+  // Build relative fileMap for output
+  const fileMap = filePaths.map(fp => path.relative(resolvedRoot, fp)).sort();
+
+  // Auto-detect tsconfig for path alias resolution
+  const tsConfigPath = findTsConfig(resolvedRoot);
+
+  // Initialize the parser with discovered files + tsconfig (or rootPath fallback)
+  astParser.createProject(filePaths, tsConfigPath, resolvedRoot);
+
+  const metadata: Metadata = {};
+
+  const sourceFiles = astParser.getSourceFiles();
+
+  for (const filePath of sourceFiles) {
+    // Process imports to categorize symbols
+    const imports = astParser.getImportDeclarations(filePath);
+
+    for (const importDecl of imports) {
+      if (!isReportablePackageForLong(importDecl.moduleSpecifier)) {
+        continue;
+      }
+
+      const moduleSpec = importDecl.moduleSpecifier;
+      if (!metadata[moduleSpec]) {
+        metadata[moduleSpec] = createEmptyPackageUsageData();
+      }
+
+      const pkgData = metadata[moduleSpec];
+      pkgData.count += importDecl.namedImports.length;
+
+      // Categorize each named import
+      for (const name of importDecl.namedImports) {
+        if (importDecl.isTypeOnly) {
+          // Explicit `import type` always goes to types
+          if (!pkgData.types[name]) {
+            pkgData.types[name] = { count: 0, typeofCount: 0, props: {} };
+          }
+          pkgData.types[name].count++;
+          continue;
+        }
+
+        // Use the AST parser to classify the symbol by its actual type definition
+        const classification = astParser.classifySymbol(filePath, name, moduleSpec);
+
+        switch (classification) {
+          case 'component':
+            if (!pkgData.components[name]) {
+              pkgData.components[name] = { props: {}, count: 0 };
+            }
+            break;
+          case 'hook':
+            if (!pkgData.hooks[name]) {
+              pkgData.hooks[name] = { props: {}, count: 0 };
+            }
+            break;
+          case 'type':
+            if (!pkgData.types[name]) {
+              pkgData.types[name] = { count: 0, typeofCount: 0, props: {} };
+            }
+            pkgData.types[name].count++;
+            break;
+          case 'unknown':
+            if (!pkgData.unknowns[name]) {
+              pkgData.unknowns[name] = { props: {}, count: 0, description: astParser.describeUnknownSymbol(name) };
+            }
+            pkgData.unknowns[name].count++;
+            break;
+          default:
+            if (!pkgData.others[name]) {
+              pkgData.others[name] = { props: {}, count: 0 };
+            }
+            pkgData.others[name].count++;
+            break;
+        }
+      }
+    }
+
+    // Enrich component usage with JSX prop analysis
+    const jsxUsages = astParser.getJsxElementUsages(filePath);
+    for (const usage of jsxUsages) {
+      if (!isReportablePackageForLong(usage.moduleSpecifier)) {
+        continue;
+      }
+
+      const moduleSpec = usage.moduleSpecifier;
+      if (!metadata[moduleSpec]) {
+        metadata[moduleSpec] = createEmptyPackageUsageData();
+      }
+
+      const pkgData = metadata[moduleSpec];
+      if (!pkgData.components[usage.componentName]) {
+        pkgData.components[usage.componentName] = { props: {}, count: 0 };
+      }
+
+      const comp = pkgData.components[usage.componentName];
+      comp.count++;
+
+      // Track prop usage
+      for (const [propName, propValue] of Object.entries(usage.props)) {
+        if (!comp.props[propName]) {
+          comp.props[propName] = { values: [], count: 0 };
+        }
+        comp.props[propName].count++;
+        if (propValue !== undefined && !comp.props[propName].values.includes(propValue)) {
+          comp.props[propName].values.push(propValue);
+        }
+      }
+    }
+
+    // Enrich hook, function, and unknown symbol usage with call expression analysis
+    const callUsages = astParser.getCallExpressionUsages(filePath);
+    for (const usage of callUsages) {
+      if (!isReportablePackageForLong(usage.moduleSpecifier)) {
+        continue;
+      }
+
+      const callClassification = astParser.classifySymbol(filePath, usage.functionName, usage.moduleSpecifier);
+
+      // Determine target category
+      let targetCategory: 'hooks' | 'others' | 'unknowns' | null = null;
+      if (callClassification === 'hook' || (callClassification === 'unknown' && /^use[A-Z]/.test(usage.functionName))) {
+        targetCategory = 'hooks';
+      } else if (callClassification === 'other') {
+        targetCategory = 'others';
+      } else if (callClassification === 'unknown') {
+        targetCategory = 'unknowns';
+      }
+
+      if (!targetCategory) {
+        continue;
+      }
+
+      const moduleSpec = usage.moduleSpecifier;
+      if (!metadata[moduleSpec]) {
+        metadata[moduleSpec] = createEmptyPackageUsageData();
+      }
+
+      const pkgData = metadata[moduleSpec];
+      const category = pkgData[targetCategory] as Record<
+        string,
+        { props: Record<string, { values: string[]; count: number }>; count: number }
+      >;
+      if (!category[usage.functionName]) {
+        if (targetCategory === 'unknowns') {
+          (pkgData.unknowns as Record<string, { props: Record<string, never>; count: number; description: string }>)[
+            usage.functionName
+          ] = {
+            props: {},
+            count: 0,
+            description: astParser.describeUnknownSymbol(usage.functionName),
+          };
+        } else {
+          category[usage.functionName] = { props: {}, count: 0 };
+        }
+      }
+
+      const entry = category[usage.functionName];
+      entry.count++;
+
+      // Track argument usage
+      for (const [argName, argValue] of Object.entries(usage.args)) {
+        if (!entry.props[argName]) {
+          entry.props[argName] = { values: [], count: 0 };
+        }
+        entry.props[argName].count++;
+        if (argValue !== undefined && !entry.props[argName].values.includes(argValue)) {
+          entry.props[argName].values.push(argValue);
+        }
+      }
+    }
+
+    // Track typeof usages and generic type parameters
+    const typeRefUsages = astParser.getTypeReferenceUsages(filePath);
+    for (const usage of typeRefUsages) {
+      if (!isReportablePackageForLong(usage.moduleSpecifier)) {
+        continue;
+      }
+
+      const moduleSpec = usage.moduleSpecifier;
+      if (!metadata[moduleSpec]) {
+        metadata[moduleSpec] = createEmptyPackageUsageData();
+      }
+
+      const pkgData = metadata[moduleSpec];
+
+      if (usage.kind === 'typeof') {
+        // typeof references go to types with typeofCount tracking
+        if (!pkgData.types[usage.symbolName]) {
+          pkgData.types[usage.symbolName] = { count: 0, typeofCount: 0, props: {} };
+        }
+        pkgData.types[usage.symbolName].count++;
+        pkgData.types[usage.symbolName].typeofCount++;
+      } else if (usage.kind === 'generic' && usage.typeArgs) {
+        // Generic type params — ensure the type exists and capture args as props
+        if (!pkgData.types[usage.symbolName]) {
+          pkgData.types[usage.symbolName] = { count: 0, typeofCount: 0, props: {} };
+        }
+
+        const typeEntry: TypeUsage = pkgData.types[usage.symbolName];
+        typeEntry.count++;
+        for (let i = 0; i < usage.typeArgs.length; i++) {
+          const propName = `typeArg${i}`;
+          if (!typeEntry.props[propName]) {
+            typeEntry.props[propName] = { values: [], count: 0 };
+          }
+          typeEntry.props[propName].count++;
+          const argValue = usage.typeArgs[i];
+          if (!typeEntry.props[propName].values.includes(argValue)) {
+            typeEntry.props[propName].values.push(argValue);
+          }
+        }
+      }
+    }
+
+    // Track component value references (non-JSX usage like `component: Button`)
+    const valueRefs = astParser.getValueReferenceUsages(filePath);
+    for (const ref of valueRefs) {
+      if (!isReportablePackageForLong(ref.moduleSpecifier)) {
+        continue;
+      }
+
+      const moduleSpec = ref.moduleSpecifier;
+      if (!metadata[moduleSpec]) {
+        metadata[moduleSpec] = createEmptyPackageUsageData();
+      }
+
+      const pkgData = metadata[moduleSpec];
+      const classification = astParser.classifySymbol(filePath, ref.symbolName, moduleSpec);
+
+      if (classification === 'component') {
+        // Component used as a value reference — count as component usage
+        if (!pkgData.components[ref.symbolName]) {
+          pkgData.components[ref.symbolName] = { props: {}, count: 0 };
+        }
+        pkgData.components[ref.symbolName].count++;
+      }
+    }
+  }
+
+  // Post-process: deduplicate symbols across categories
+  for (const pkgData of Object.values(metadata)) {
+    for (const name of Object.keys(pkgData.others)) {
+      if (pkgData.components[name] && pkgData.components[name].count > 0) {
+        delete pkgData.others[name];
+      }
+    }
+    // If an unknown symbol was also categorized elsewhere (e.g., as component via JSX), remove from unknowns
+    for (const name of Object.keys(pkgData.unknowns)) {
+      if (
+        (pkgData.components[name] && pkgData.components[name].count > 0) ||
+        pkgData.hooks[name] ||
+        pkgData.types[name] ||
+        pkgData.others[name]
+      ) {
+        delete pkgData.unknowns[name];
+      }
+    }
+  }
+
+  return { legend: CATEGORY_LEGEND, fileMap, packages: metadata };
+}
+
+/**
+ * Find a tsconfig file in the given directory.
+ * Probes common names in priority order: tsconfig.json, tsconfig.base.json.
+ */
+function findTsConfig(rootPath: string): string | undefined {
+  for (const candidate of TSCONFIG_CANDIDATES) {
+    const fullPath = path.join(rootPath, candidate);
+    if (fs.existsSync(fullPath)) {
+      return fullPath;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Run the long report: collect data and output in the requested format.
+ *
+ * @param rootPath - Root directory for file traversal.
+ * @param reporter - Output format: 'json' (default), 'markdown', or 'html'.
+ * @param include - Glob patterns to include.
+ * @param exclude - Glob patterns to exclude.
+ * @param output - Output file path. When provided, writes to file instead of stdout.
+ */
+export async function runUsageReport(
+  rootPath?: string,
+  reporter: 'json' | 'markdown' | 'html' = 'json',
+  include?: string[],
+  exclude?: string[],
+  output?: string,
+): Promise<void> {
+  const reportData = collectUsageReportData(rootPath, undefined, include, exclude);
+
+  let formatted: string;
+  if (reporter === 'markdown') {
+    const { formatMetadataAsMarkdown } = await import('./markdown-reporter');
+    formatted = formatMetadataAsMarkdown(reportData);
+  } else if (reporter === 'html') {
+    const { formatMetadataAsHtml } = await import('./html-reporter');
+    formatted = formatMetadataAsHtml(reportData);
+  } else {
+    formatted = JSON.stringify(reportData, null, 2);
+  }
+
+  if (output) {
+    const outputPath = path.resolve(output);
+    fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+    fs.writeFileSync(outputPath, formatted, 'utf-8');
+    console.log(`Report written to ${outputPath}`);
+  } else {
+    console.log(formatted);
+  }
+}
diff --git a/tools/cli/src/commands/report/index.ts b/tools/cli/src/commands/report/index.ts
index 2724afd935957..ee2501ee9ae83 100644
--- a/tools/cli/src/commands/report/index.ts
+++ b/tools/cli/src/commands/report/index.ts
@@ -1,12 +1,19 @@
 import type { CommandModule } from 'yargs';
+import infoCommand from './commands/info';
+import usageCommand from './commands/usage';
 
 const command: CommandModule = {
   command: 'report',
-  describe: 'Generate reports',
-  builder: yargs => yargs.version(false).help(),
-  handler: async argv => {
-    const { handler } = await import('./handler');
-    return handler(argv);
+  describe: 'Generate reports (info for issue reporting, usage for codebase analysis)',
+  builder: yargs =>
+    yargs
+      .command(infoCommand)
+      .command(usageCommand)
+      .demandCommand(1, 'Please specify a subcommand: info or usage')
+      .version(false)
+      .help(),
+  handler: () => {
+    // yargs handles routing to subcommands; this is never reached due to demandCommand
   },
 };
 
diff --git a/tools/cli/tsconfig.lib.json b/tools/cli/tsconfig.lib.json
index 6b3ebc893a00e..78b4f1c5221d7 100644
--- a/tools/cli/tsconfig.lib.json
+++ b/tools/cli/tsconfig.lib.json
@@ -8,5 +8,5 @@
     "types": ["node"]
   },
   "include": ["src/**/*.ts"],
-  "exclude": ["jest.config.ts", "src/**/*.spec.ts", "src/**/*.test.ts"]
+  "exclude": ["jest.config.ts", "src/**/*.spec.ts", "src/**/*.test.ts", "**/__fixtures__/**"]
 }

From cb61c8e1a8ab4d204261b1320ee0c00d7b52a6a2 Mon Sep 17 00:00:00 2001
From: Martin Hochel <martinhochel@microsoft.com>
Date: Tue, 7 Apr 2026 15:12:18 +0200
Subject: [PATCH 09/14] feat(cli): implement `metadata` command for API surface
 extraction (#35843)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 tools/cli/src/cli.ts                          |   2 +
 tools/cli/src/commands/metadata/README.md     | 146 ++++
 .../metadata/__fixtures__/package.json        |   5 +
 .../metadata/__fixtures__/sample-button.d.ts  | 144 ++++
 .../cli/src/commands/metadata/handler.spec.ts |  97 +++
 tools/cli/src/commands/metadata/handler.ts    | 216 ++++++
 .../metadata/impl/annotation-groups.spec.ts   |  51 ++
 .../metadata/impl/annotation-groups.ts        |  52 ++
 .../impl/cross-package-resolver.spec.ts       |  60 ++
 .../metadata/impl/cross-package-resolver.ts   |  69 ++
 .../commands/metadata/impl/dts-parser.spec.ts | 245 ++++++
 .../src/commands/metadata/impl/dts-parser.ts  | 720 ++++++++++++++++++
 .../metadata/impl/entry-resolver.spec.ts      |  52 ++
 .../commands/metadata/impl/entry-resolver.ts  |  93 +++
 .../commands/metadata/impl/html-formatter.ts  | 370 +++++++++
 .../metadata/impl/markdown-formatter.ts       | 299 ++++++++
 tools/cli/src/commands/metadata/impl/types.ts | 143 ++++
 tools/cli/src/commands/metadata/index.ts      |  35 +
 18 files changed, 2799 insertions(+)
 create mode 100644 tools/cli/src/commands/metadata/README.md
 create mode 100644 tools/cli/src/commands/metadata/__fixtures__/package.json
 create mode 100644 tools/cli/src/commands/metadata/__fixtures__/sample-button.d.ts
 create mode 100644 tools/cli/src/commands/metadata/handler.spec.ts
 create mode 100644 tools/cli/src/commands/metadata/handler.ts
 create mode 100644 tools/cli/src/commands/metadata/impl/annotation-groups.spec.ts
 create mode 100644 tools/cli/src/commands/metadata/impl/annotation-groups.ts
 create mode 100644 tools/cli/src/commands/metadata/impl/cross-package-resolver.spec.ts
 create mode 100644 tools/cli/src/commands/metadata/impl/cross-package-resolver.ts
 create mode 100644 tools/cli/src/commands/metadata/impl/dts-parser.spec.ts
 create mode 100644 tools/cli/src/commands/metadata/impl/dts-parser.ts
 create mode 100644 tools/cli/src/commands/metadata/impl/entry-resolver.spec.ts
 create mode 100644 tools/cli/src/commands/metadata/impl/entry-resolver.ts
 create mode 100644 tools/cli/src/commands/metadata/impl/html-formatter.ts
 create mode 100644 tools/cli/src/commands/metadata/impl/markdown-formatter.ts
 create mode 100644 tools/cli/src/commands/metadata/impl/types.ts
 create mode 100644 tools/cli/src/commands/metadata/index.ts

diff --git a/tools/cli/src/cli.ts b/tools/cli/src/cli.ts
index ffd1f035dc883..66c1b0bd2c274 100644
--- a/tools/cli/src/cli.ts
+++ b/tools/cli/src/cli.ts
@@ -2,6 +2,7 @@ import yargs from 'yargs';
 
 import migrateCommand from './commands/migrate';
 import reportCommand from './commands/report';
+import metadataCommand from './commands/metadata';
 
 const BANNER = `
   ███████╗██╗     ██╗   ██╗███████╗███╗   ██╗████████╗  ██╗   ██╗██╗
@@ -19,6 +20,7 @@ export async function main(argv: string[]): Promise<void> {
     .usage(`${BANNER}\n  $0 <command> [options]`)
     .command(migrateCommand)
     .command(reportCommand)
+    .command(metadataCommand)
     .demandCommand(1, 'You need to specify a command to run.')
     .help()
     .strict()
diff --git a/tools/cli/src/commands/metadata/README.md b/tools/cli/src/commands/metadata/README.md
new file mode 100644
index 0000000000000..dab24ce98964a
--- /dev/null
+++ b/tools/cli/src/commands/metadata/README.md
@@ -0,0 +1,146 @@
+# `metadata` command
+
+The `metadata` command extracts the full public API surface from a Fluent UI package's `.d.ts` build output and produces structured metadata. It is similar in spirit to [react-docgen-typescript](https://github.com/styleguidist/react-docgen-typescript) but covers **all exports** — components, hooks, types, and utilities — with full type signatures and JSDoc documentation.
+
+## Usage
+
+```bash
+fluentui metadata [--entry <path>] [--reporter json|markdown|html] [--output <path>]
+```
+
+| Flag         | Alias | Default                      | Description                                     |
+| ------------ | ----- | ---------------------------- | ----------------------------------------------- |
+| `--entry`    | `-e`  | resolved from `package.json` | Path to `.d.ts` entry file or package directory |
+| `--reporter` | `-r`  | `json`                       | Output format: `json`, `markdown`, or `html`    |
+| `--output`   | `-o`  | stdout                       | Output file path                                |
+
+### Entry resolution
+
+By default the command reads the closest `package.json`, looks for the `"types"` (or `"typings"`) field, and resolves the `.d.ts` entry file. The `--entry` flag accepts either:
+
+- A direct path to an `index.d.ts` file
+- A directory containing a `package.json` (the types field is read from it)
+
+> **Prerequisite**: The package must be built first (`yarn nx run <pkg>:build`) so that `.d.ts` output exists.
+
+## Categories
+
+Every exported symbol is classified into one of four categories:
+
+| Category       | Criteria                                                                                |
+| -------------- | --------------------------------------------------------------------------------------- |
+| **Components** | `ForwardRefComponent<>`, `React.FC<>`, functions returning JSX, PascalCase + JSX return |
+| **Hooks**      | `use*` naming convention (functions starting with `use` + uppercase letter)             |
+| **Types**      | Interfaces, type aliases, enums                                                         |
+| **Others**     | Constants, render functions, utility functions, class-name objects                      |
+
+Within each category, symbols are further grouped by annotation:
+
+| Group          | JSDoc tags         |
+| -------------- | ------------------ |
+| **Stable**     | _(no special tag)_ |
+| **Deprecated** | `@deprecated`      |
+| **Internal**   | `@internal`        |
+| **Preview**    | `@alpha`, `@beta`  |
+
+## Output formats
+
+- **JSON** — machine-readable metadata with `package`, `legend`, `categories`, and `externalReferences`. Default.
+- **Markdown** — collapsible sections per category with summary tables, annotation sub-groups, and clickable `$ref` links.
+- **HTML** — self-contained report with collapsible categories, annotation sub-groups with colored borders, clickable anchor links, and dark-mode support.
+
+### JSON schema overview
+
+```jsonc
+{
+  "package": { "name": "@fluentui/react-button", "version": "9.8.2" },
+  "legend": {
+    /* category descriptions */
+  },
+  "categories": {
+    "components": {
+      "Button": {
+        "name": "Button",
+        "description": "Buttons give people a way to trigger an action.",
+        "typeSignature": "ForwardRefComponent<ButtonProps>",
+        "tags": {},
+        "propsType": { "$ref": "#/categories/types/ButtonProps" }
+      }
+    },
+    "hooks": {
+      /* ... */
+    },
+    "types": {
+      /* ... */
+    },
+    "others": {
+      /* ... */
+    }
+  },
+  "externalReferences": {
+    "@fluentui/react-utilities": {
+      "metadataRef": "@fluentui/react-utilities/metadata.json",
+      "symbols": {
+        "ForwardRefComponent": { "$ref": "@fluentui/react-utilities#/categories/types/ForwardRefComponent" },
+        "Slot": { "$ref": "@fluentui/react-utilities#/categories/types/Slot" }
+      }
+    }
+  }
+}
+```
+
+### Cross-package references (`$ref`)
+
+- **Within the same package**: JSON Pointer — `{ "$ref": "#/categories/types/ButtonSlots" }`
+- **Across packages**: URI-style — `{ "$ref": "@fluentui/react-utilities#/categories/types/ComponentProps" }`
+
+When a dependency does not have a `metadata.json`, the symbol falls back to `{ "inline": "SymbolName" }`.
+
+## Architecture
+
+```
+metadata/
+├── index.ts                        # Yargs command definition (--entry, --reporter, --output)
+├── handler.ts                      # Main handler — orchestrates resolve → parse → refs → format → output
+├── handler.spec.ts                 # Integration tests
+├── impl/
+│   ├── types.ts                    # All TypeScript interfaces (MetadataOutput, *Doc, ExternalPackageRef)
+│   ├── entry-resolver.ts           # Resolves .d.ts from package.json or --entry flag
+│   ├── entry-resolver.spec.ts      # Entry resolution tests
+│   ├── dts-parser.ts               # ts-morph parser — extracts all exports with full type signatures
+│   ├── dts-parser.spec.ts          # Parser tests (classification, JSDoc, members, params)
+│   ├── cross-package-resolver.ts   # Loads dependency metadata.json and builds $ref URIs
+│   ├── cross-package-resolver.spec.ts
+│   ├── annotation-groups.ts        # Groups symbols by @deprecated, @internal, @alpha, @beta
+│   ├── annotation-groups.spec.ts
+│   ├── markdown-formatter.ts       # Markdown output with collapsible sections and ref links
+│   └── html-formatter.ts           # Self-contained HTML output with dark mode
+└── __fixtures__/                   # Test fixtures (.d.ts, package.json)
+```
+
+### How it works
+
+1. **Entry resolution** — finds the `.d.ts` entry file from `package.json` types/typings field or `--entry` flag
+2. **Parsing** — ts-morph loads the `.d.ts`, iterates `getExportedDeclarations()`, classifies each symbol, extracts JSDoc, type signatures, members, parameters, and return types
+3. **Cross-package resolution** — for each imported external package, checks for `metadata.json` and builds `$ref` pointers; scans exported type signatures to determine which external symbols are actually used in the public API
+4. **Annotation grouping** — symbols within each category are bucketed by `@deprecated` / `@internal` / `@alpha` / `@beta` tags
+5. **Formatting** — routes to JSON, markdown, or HTML formatter
+6. **Output** — prints to stdout or writes to file via `--output`
+
+### Key implementation details
+
+- **JSDoc on `declare const`**: In `.d.ts` files, JSDoc lives on the parent `VariableStatement`, not the `VariableDeclaration` node. The parser's `getJsDocTarget()` helper walks up to find it.
+- **Function-typed variables**: `declare const renderButton: (state: S) => JSX.Element` is classified as `kind: 'function'` (not `'variable'`) by checking for call signatures on the type.
+- **Props type extraction**: `ForwardRefExoticComponent<ButtonProps & RefAttributes<...>>` is parsed with a regex to extract the first type argument as the props type reference.
+
+## Testing
+
+```bash
+# Run all metadata tests
+yarn nx run cli:test -- --testPathPatterns=metadata
+
+# Run full CLI test suite
+yarn nx run cli:test
+```
+
+Tests use a fixture-based approach with `__fixtures__/sample-button.d.ts` containing components, hooks, types, enums, and external imports to exercise all classification paths and formatter output.
diff --git a/tools/cli/src/commands/metadata/__fixtures__/package.json b/tools/cli/src/commands/metadata/__fixtures__/package.json
new file mode 100644
index 0000000000000..c8104e7482b30
--- /dev/null
+++ b/tools/cli/src/commands/metadata/__fixtures__/package.json
@@ -0,0 +1,5 @@
+{
+  "name": "@fluentui/sample-button",
+  "version": "1.0.0",
+  "types": "./sample-button.d.ts"
+}
diff --git a/tools/cli/src/commands/metadata/__fixtures__/sample-button.d.ts b/tools/cli/src/commands/metadata/__fixtures__/sample-button.d.ts
new file mode 100644
index 0000000000000..e1760e71d8433
--- /dev/null
+++ b/tools/cli/src/commands/metadata/__fixtures__/sample-button.d.ts
@@ -0,0 +1,144 @@
+import * as React from 'react';
+import type { Slot } from '@sample/utilities';
+import type { SlotClassNames } from '@sample/utilities';
+
+/**
+ * Props for the SampleButton component.
+ */
+export declare interface SampleButtonProps {
+  /**
+   * The visual style of the button.
+   *
+   * @default 'secondary'
+   */
+  appearance?: 'primary' | 'secondary' | 'outline';
+  /**
+   * Whether the button is disabled.
+   *
+   * @default false
+   */
+  disabled?: boolean;
+  /** The size of the button. */
+  size?: 'small' | 'medium' | 'large';
+}
+
+/**
+ * State for the SampleButton component.
+ */
+export declare interface SampleButtonState {
+  appearance: 'primary' | 'secondary' | 'outline';
+  disabled: boolean;
+}
+
+/**
+ * Slots for the SampleButton component.
+ */
+export declare type SampleButtonSlots = {
+  /** Root element of the button. */
+  root: Slot<HTMLButtonElement>;
+  /** Optional icon slot. */
+  icon?: Slot<HTMLSpanElement>;
+};
+
+/**
+ * SampleButton gives people a way to trigger an action.
+ */
+export declare const SampleButton: React.ForwardRefExoticComponent<
+  SampleButtonProps & React.RefAttributes<HTMLButtonElement>
+>;
+
+export declare const sampleButtonClassNames: SlotClassNames<SampleButtonSlots>;
+
+export declare const getPartitionedProps: ({
+  props,
+  excluded,
+}: {
+  props: SampleButtonProps;
+  excluded?: string[];
+}) => Record<string, unknown>;
+
+/**
+ * Hook to create SampleButton state.
+ * @param props - User provided props to the SampleButton component.
+ * @param ref - User provided ref.
+ */
+export declare const useSampleButton_unstable: (
+  props: SampleButtonProps,
+  ref: React.Ref<HTMLButtonElement>,
+) => SampleButtonState;
+
+export declare const useSampleButtonStyles_unstable: (state: SampleButtonState) => SampleButtonState;
+
+/**
+ * Renders SampleButton from state.
+ */
+export declare const renderSampleButton_unstable: (state: SampleButtonState) => JSX.Element;
+
+/**
+ * @internal
+ * Internal context value.
+ */
+export declare interface SampleButtonContextValue {
+  size?: 'small' | 'medium' | 'large';
+}
+
+/**
+ * Selection methods interface with method signatures.
+ */
+export declare interface SampleSelectionMethods {
+  selectItem(id: string): void;
+  isSelected(id: string): boolean;
+}
+
+/**
+ * Size options for the button.
+ */
+export declare type SampleButtonSize = 'small' | 'medium' | 'large';
+
+/**
+ * Options for controllable state.
+ */
+export declare type SampleStateOptions = {
+  /**
+   * User-provided default state.
+   */
+  defaultState?: string;
+  /** Current state value. */
+  state: string | undefined;
+};
+
+/**
+ * @deprecated Use SampleButtonSize instead.
+ */
+export declare enum ButtonVariant {
+  Primary = 'primary',
+  Secondary = 'secondary',
+}
+
+export declare function useToggleState(props: SampleButtonProps): SampleButtonState;
+
+/**
+ * Gets the trigger child from children.
+ * @internal
+ */
+export declare function getTriggerChild(children: React.ReactNode): React.ReactElement | null;
+
+/**
+ * A PascalCase function component declared with `function` keyword.
+ */
+export declare function PascalCaseComponent(props: { label: string }): JSX.Element;
+
+/**
+ * Checks if an element is an HTML element.
+ */
+export declare function isHTMLElement(
+  element?: unknown,
+  options?: {
+    /**
+     * Can be used to provide a custom constructor name.
+     */
+    constructorName?: string;
+  },
+): boolean;
+
+export {};
diff --git a/tools/cli/src/commands/metadata/handler.spec.ts b/tools/cli/src/commands/metadata/handler.spec.ts
new file mode 100644
index 0000000000000..a9fe83b3dbe0c
--- /dev/null
+++ b/tools/cli/src/commands/metadata/handler.spec.ts
@@ -0,0 +1,97 @@
+import * as path from 'node:path';
+import * as fs from 'node:fs';
+
+import { handler } from './handler';
+
+const FIXTURES_DIR = path.resolve(__dirname, '__fixtures__');
+const SAMPLE_DTS = path.join(FIXTURES_DIR, 'sample-button.d.ts');
+
+describe('metadata handler', () => {
+  let logSpy: jest.SpyInstance;
+
+  beforeEach(() => {
+    logSpy = jest.spyOn(console, 'log').mockImplementation();
+  });
+
+  afterEach(() => {
+    logSpy.mockRestore();
+  });
+
+  it('should output JSON metadata for a .d.ts entry file', async () => {
+    await handler({ _: ['metadata'], $0: 'fluentui-cli', entry: SAMPLE_DTS, reporter: 'json' });
+
+    expect(logSpy).toHaveBeenCalledTimes(1);
+    const output = JSON.parse(logSpy.mock.calls[0][0]);
+
+    expect(output.package.name).toBe('@fluentui/sample-button');
+    expect(output.categories.components).toHaveProperty('SampleButton');
+    expect(output.categories.hooks).toHaveProperty('useSampleButton_unstable');
+    expect(output.categories.types).toHaveProperty('SampleButtonProps');
+    expect(output.categories.others).toHaveProperty('sampleButtonClassNames');
+  });
+
+  it('should output markdown when reporter=markdown', async () => {
+    await handler({ _: ['metadata'], $0: 'fluentui-cli', entry: SAMPLE_DTS, reporter: 'markdown' });
+
+    const output: string = logSpy.mock.calls[0][0];
+    expect(output).toContain('# API Metadata:');
+    expect(output).toContain('Components (');
+    expect(output).toContain('SampleButton');
+  });
+
+  it('should output HTML when reporter=html', async () => {
+    await handler({ _: ['metadata'], $0: 'fluentui-cli', entry: SAMPLE_DTS, reporter: 'html' });
+
+    const output: string = logSpy.mock.calls[0][0];
+    expect(output).toContain('<!DOCTYPE html>');
+    expect(output).toContain('SampleButton');
+  });
+
+  it('should include externalReferences for named imports used in API surface', async () => {
+    await handler({ _: ['metadata'], $0: 'fluentui-cli', entry: SAMPLE_DTS, reporter: 'json' });
+
+    const output = JSON.parse(logSpy.mock.calls[0][0]);
+
+    // The fixture imports Slot and SlotClassNames from @sample/utilities
+    // Both are used in type signatures (SampleButtonSlots uses Slot, sampleButtonClassNames uses SlotClassNames)
+    expect(output.externalReferences).toBeDefined();
+    expect(output.externalReferences['@sample/utilities']).toBeDefined();
+
+    const utilsRef = output.externalReferences['@sample/utilities'];
+    expect(utilsRef.metadataRef).toBe('@sample/utilities/metadata.json');
+    expect(utilsRef.symbols).toHaveProperty('Slot');
+    expect(utilsRef.symbols).toHaveProperty('SlotClassNames');
+  });
+
+  it('should include external references in markdown output', async () => {
+    await handler({ _: ['metadata'], $0: 'fluentui-cli', entry: SAMPLE_DTS, reporter: 'markdown' });
+
+    const output: string = logSpy.mock.calls[0][0];
+    expect(output).toContain('External References');
+    expect(output).toContain('@sample/utilities');
+  });
+
+  it('should include external references in HTML output', async () => {
+    await handler({ _: ['metadata'], $0: 'fluentui-cli', entry: SAMPLE_DTS, reporter: 'html' });
+
+    const output: string = logSpy.mock.calls[0][0];
+    expect(output).toContain('External References');
+    expect(output).toContain('@sample/utilities');
+  });
+
+  it('should write to file when --output is specified', async () => {
+    const tmpOutput = path.join(FIXTURES_DIR, '__test-output__.json');
+
+    try {
+      await handler({ _: ['metadata'], $0: 'fluentui-cli', entry: SAMPLE_DTS, reporter: 'json', output: tmpOutput });
+
+      expect(fs.existsSync(tmpOutput)).toBe(true);
+      const content = JSON.parse(fs.readFileSync(tmpOutput, 'utf-8'));
+      expect(content.package.name).toBe('@fluentui/sample-button');
+    } finally {
+      if (fs.existsSync(tmpOutput)) {
+        fs.unlinkSync(tmpOutput);
+      }
+    }
+  });
+});
diff --git a/tools/cli/src/commands/metadata/handler.ts b/tools/cli/src/commands/metadata/handler.ts
new file mode 100644
index 0000000000000..a90f2449602ad
--- /dev/null
+++ b/tools/cli/src/commands/metadata/handler.ts
@@ -0,0 +1,216 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import type { CommandHandler } from '../../utils/types';
+import type { MetadataArgs, MetadataOutput, ExternalPackageRef, RefOrInline } from './impl/types';
+import type { ParseResult } from './impl/dts-parser';
+import { resolveEntry, readPackageInfo } from './impl/entry-resolver';
+import { parseDtsEntry } from './impl/dts-parser';
+import { loadDependencyMetadata, buildCrossPackageRef } from './impl/cross-package-resolver';
+import { formatMetadataAsMarkdown } from './impl/markdown-formatter';
+import { formatMetadataAsHtml } from './impl/html-formatter';
+
+const LEGEND = {
+  components: { name: 'Components', description: 'React components (ForwardRef, FC, class)' },
+  hooks: { name: 'Hooks', description: 'React hooks (use* convention)' },
+  types: { name: 'Types', description: 'Interfaces, type aliases, and enums' },
+  others: { name: 'Others', description: 'Constants, render functions, and utilities' },
+};
+
+export const handler: CommandHandler<MetadataArgs> = async argv => {
+  const { entry, reporter = 'json', output } = argv;
+
+  // 1. Resolve entry .d.ts
+  const entryPath = resolveEntry(entry);
+  const packageInfo = readPackageInfo(path.dirname(entryPath));
+
+  // 2. Parse the .d.ts
+  const parseResult = parseDtsEntry(entryPath);
+
+  // 3. Resolve cross-package $refs
+  const cwd = process.cwd();
+  const depMetadataCache = new Map<string, MetadataOutput | null>();
+
+  for (const pkgSpec of parseResult.importedPackages) {
+    if (!depMetadataCache.has(pkgSpec)) {
+      depMetadataCache.set(pkgSpec, loadDependencyMetadata(pkgSpec, cwd));
+    }
+  }
+
+  // Enhance component propsType refs with cross-package resolution
+  for (const comp of Object.values(parseResult.components)) {
+    if (comp.propsType && '$ref' in comp.propsType) {
+      const localRef = comp.propsType.$ref;
+      const symbolName = localRef.split('/').pop()!;
+
+      // If the type isn't in our own types, check dependencies
+      if (!(symbolName in parseResult.types)) {
+        for (const [pkgSpec, depMetadata] of depMetadataCache) {
+          if (depMetadata) {
+            const crossRef = buildCrossPackageRef(pkgSpec, symbolName, depMetadata);
+            if (crossRef) {
+              comp.propsType = crossRef;
+              break;
+            }
+          }
+        }
+      }
+    }
+  }
+
+  // 4. Build external references
+  const externalReferences = buildExternalReferences(parseResult, depMetadataCache);
+
+  // 5. Assemble output
+  const metadataOutput: MetadataOutput = {
+    package: packageInfo,
+    legend: LEGEND,
+    categories: {
+      components: parseResult.components,
+      hooks: parseResult.hooks,
+      types: parseResult.types,
+      others: parseResult.others,
+    },
+  };
+
+  if (Object.keys(externalReferences).length > 0) {
+    metadataOutput.externalReferences = externalReferences;
+  }
+
+  // 6. Format
+  let formatted: string;
+  switch (reporter) {
+    case 'markdown':
+      formatted = formatMetadataAsMarkdown(metadataOutput);
+      break;
+    case 'html':
+      formatted = formatMetadataAsHtml(metadataOutput);
+      break;
+    case 'json':
+    default:
+      formatted = JSON.stringify(metadataOutput, null, 2);
+      break;
+  }
+
+  // 7. Output
+  if (output) {
+    const outputPath = path.resolve(cwd, output);
+    fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+    fs.writeFileSync(outputPath, formatted, 'utf-8');
+    console.log(`Metadata written to ${outputPath}`);
+  } else {
+    console.log(formatted);
+  }
+};
+
+// ---------------------------------------------------------------------------
+// External references
+// ---------------------------------------------------------------------------
+
+/**
+ * Collect all type strings from the parsed API surface.
+ */
+function collectAllTypeStrings(parseResult: ParseResult): string[] {
+  const strings: string[] = [];
+
+  for (const comp of Object.values(parseResult.components)) {
+    strings.push(comp.typeSignature);
+  }
+
+  for (const hook of Object.values(parseResult.hooks)) {
+    strings.push(hook.typeSignature, hook.returnType);
+    for (const p of hook.parameters) {
+      strings.push(p.type);
+    }
+  }
+
+  for (const type of Object.values(parseResult.types)) {
+    strings.push(type.typeSignature);
+    for (const m of Object.values(type.members)) {
+      strings.push(m.type);
+    }
+  }
+
+  for (const other of Object.values(parseResult.others)) {
+    strings.push(other.typeSignature);
+    if (other.parameters) {
+      for (const p of other.parameters) {
+        strings.push(p.type);
+      }
+    }
+    if (other.returnType) {
+      strings.push(other.returnType);
+    }
+  }
+
+  return strings;
+}
+
+/**
+ * Determine which imported external symbols are actually referenced
+ * in the public API surface, and build the externalReferences map.
+ */
+function buildExternalReferences(
+  parseResult: ParseResult,
+  depMetadataCache: Map<string, MetadataOutput | null>,
+): Record<string, ExternalPackageRef> {
+  const allTypeStrings = collectAllTypeStrings(parseResult);
+  const joinedTypes = allTypeStrings.join('\n');
+
+  // Collect all locally-defined symbol names to exclude from external detection
+  const localSymbols = new Set<string>([
+    ...Object.keys(parseResult.components),
+    ...Object.keys(parseResult.hooks),
+    ...Object.keys(parseResult.types),
+    ...Object.keys(parseResult.others),
+  ]);
+
+  const result: Record<string, ExternalPackageRef> = {};
+
+  for (const [pkgSpec, importedNames] of parseResult.importedSymbols) {
+    const usedSymbols: Record<string, RefOrInline> = {};
+    const depMetadata = depMetadataCache.get(pkgSpec) ?? null;
+
+    for (const symbolName of importedNames) {
+      // Skip symbols that are defined locally (re-declared in this package)
+      if (localSymbols.has(symbolName)) {
+        continue;
+      }
+
+      // Check if this symbol name appears in any type signature
+      if (!isSymbolReferenced(symbolName, joinedTypes)) {
+        continue;
+      }
+
+      // Build ref or inline fallback
+      if (depMetadata) {
+        const ref = buildCrossPackageRef(pkgSpec, symbolName, depMetadata);
+        if (ref) {
+          usedSymbols[symbolName] = ref;
+          continue;
+        }
+      }
+
+      usedSymbols[symbolName] = { inline: symbolName };
+    }
+
+    if (Object.keys(usedSymbols).length > 0) {
+      result[pkgSpec] = {
+        metadataRef: `${pkgSpec}/metadata.json`,
+        symbols: usedSymbols,
+      };
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Check if a symbol name is referenced in the joined type strings.
+ * Uses word-boundary matching to avoid false positives from substrings.
+ */
+function isSymbolReferenced(symbolName: string, joinedTypes: string): boolean {
+  const escaped = symbolName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const pattern = new RegExp(`(?<![a-zA-Z0-9_])${escaped}(?![a-zA-Z0-9_])`);
+  return pattern.test(joinedTypes);
+}
diff --git a/tools/cli/src/commands/metadata/impl/annotation-groups.spec.ts b/tools/cli/src/commands/metadata/impl/annotation-groups.spec.ts
new file mode 100644
index 0000000000000..0e3e047f2ead3
--- /dev/null
+++ b/tools/cli/src/commands/metadata/impl/annotation-groups.spec.ts
@@ -0,0 +1,51 @@
+import { groupByAnnotation } from './annotation-groups';
+import type { BaseSymbolDoc } from './types';
+
+function sym(name: string, tags: Record<string, string> = {}): BaseSymbolDoc {
+  return { name, description: '', typeSignature: '', tags };
+}
+
+describe('groupByAnnotation', () => {
+  it('should place symbols without special tags into stable', () => {
+    const result = groupByAnnotation([sym('Foo'), sym('Bar')]);
+    expect(result).toHaveLength(1);
+    expect(result[0].key).toBe('stable');
+    expect(result[0].items.map(i => i.name)).toEqual(['Bar', 'Foo']);
+  });
+
+  it('should group @deprecated symbols separately', () => {
+    const result = groupByAnnotation([sym('A'), sym('B', { deprecated: 'use C' }), sym('C')]);
+    expect(result).toHaveLength(2);
+    expect(result[0].key).toBe('stable');
+    expect(result[0].items.map(i => i.name)).toEqual(['A', 'C']);
+    expect(result[1].key).toBe('deprecated');
+    expect(result[1].items.map(i => i.name)).toEqual(['B']);
+  });
+
+  it('should group @internal symbols separately', () => {
+    const result = groupByAnnotation([sym('Public'), sym('Secret', { internal: '' })]);
+    expect(result).toHaveLength(2);
+    expect(result[0].key).toBe('stable');
+    expect(result[1].key).toBe('internal');
+    expect(result[1].items[0].name).toBe('Secret');
+  });
+
+  it('should group @alpha and @beta into preview', () => {
+    const result = groupByAnnotation([sym('A', { alpha: '' }), sym('B', { beta: '' }), sym('C')]);
+    expect(result.find(g => g.key === 'preview')!.items).toHaveLength(2);
+    expect(result.find(g => g.key === 'stable')!.items).toHaveLength(1);
+  });
+
+  it('should use first matching group for symbols with multiple tags', () => {
+    const result = groupByAnnotation([sym('X', { deprecated: '', internal: '' })]);
+    expect(result).toHaveLength(1);
+    // deprecated comes before internal in ANNOTATION_GROUPS
+    expect(result[0].key).toBe('deprecated');
+  });
+
+  it('should omit empty groups', () => {
+    const result = groupByAnnotation([sym('A', { internal: '' })]);
+    expect(result).toHaveLength(1);
+    expect(result[0].key).toBe('internal');
+  });
+});
diff --git a/tools/cli/src/commands/metadata/impl/annotation-groups.ts b/tools/cli/src/commands/metadata/impl/annotation-groups.ts
new file mode 100644
index 0000000000000..ceee361ab86ed
--- /dev/null
+++ b/tools/cli/src/commands/metadata/impl/annotation-groups.ts
@@ -0,0 +1,52 @@
+import type { BaseSymbolDoc } from './types';
+
+/**
+ * Known annotation groups in display order.
+ * Symbols are bucketed into the first matching group.
+ */
+export const ANNOTATION_GROUPS = [
+  { key: 'stable', label: 'Stable', tags: [] as string[] },
+  { key: 'deprecated', label: 'Deprecated', tags: ['deprecated'] },
+  { key: 'internal', label: 'Internal', tags: ['internal'] },
+  { key: 'preview', label: 'Preview', tags: ['alpha', 'beta'] },
+] as const;
+
+export type AnnotationGroupKey = (typeof ANNOTATION_GROUPS)[number]['key'];
+
+export interface AnnotationGroup<T> {
+  key: AnnotationGroupKey;
+  label: string;
+  items: T[];
+}
+
+/**
+ * Group an array of symbol docs by their annotation tags.
+ * Returns only non-empty groups in display order.
+ */
+export function groupByAnnotation<T extends BaseSymbolDoc>(symbols: T[]): AnnotationGroup<T>[] {
+  const buckets = new Map<AnnotationGroupKey, T[]>(ANNOTATION_GROUPS.map(g => [g.key, []]));
+
+  for (const sym of symbols) {
+    const group = resolveGroup(sym.tags);
+    buckets.get(group)!.push(sym);
+  }
+
+  return ANNOTATION_GROUPS.filter(g => buckets.get(g.key)!.length > 0).map(g => ({
+    key: g.key,
+    label: g.label,
+    items: buckets.get(g.key)!.sort((a, b) => a.name.localeCompare(b.name)),
+  }));
+}
+
+function resolveGroup(tags: Record<string, string>): AnnotationGroupKey {
+  // Check non-stable groups in order; first match wins
+  for (const group of ANNOTATION_GROUPS) {
+    if (group.key === 'stable') {
+      continue;
+    }
+    if (group.tags.some(t => t in tags)) {
+      return group.key;
+    }
+  }
+  return 'stable';
+}
diff --git a/tools/cli/src/commands/metadata/impl/cross-package-resolver.spec.ts b/tools/cli/src/commands/metadata/impl/cross-package-resolver.spec.ts
new file mode 100644
index 0000000000000..0c4a97924860c
--- /dev/null
+++ b/tools/cli/src/commands/metadata/impl/cross-package-resolver.spec.ts
@@ -0,0 +1,60 @@
+import type { MetadataOutput } from './types';
+import { loadDependencyMetadata, buildCrossPackageRef } from './cross-package-resolver';
+
+describe('cross-package-resolver', () => {
+  const mockMetadata: MetadataOutput = {
+    package: { name: '@fluentui/react-utilities', version: '1.0.0' },
+    legend: {},
+    categories: {
+      components: {},
+      hooks: {},
+      types: {
+        ComponentProps: {
+          name: 'ComponentProps',
+          description: 'Base component props type.',
+          typeSignature: '...',
+          tags: {},
+          kind: 'type-alias',
+          members: {},
+        },
+      },
+      others: {
+        slot: {
+          name: 'slot',
+          description: 'Slot utility.',
+          typeSignature: '...',
+          tags: {},
+          kind: 'function',
+        },
+      },
+    },
+  };
+
+  describe('buildCrossPackageRef', () => {
+    it('should return a $ref when the symbol exists in types', () => {
+      const result = buildCrossPackageRef('@fluentui/react-utilities', 'ComponentProps', mockMetadata);
+
+      expect(result).toEqual({ $ref: '@fluentui/react-utilities#/categories/types/ComponentProps' });
+    });
+
+    it('should return a $ref when the symbol exists in others', () => {
+      const result = buildCrossPackageRef('@fluentui/react-utilities', 'slot', mockMetadata);
+
+      expect(result).toEqual({ $ref: '@fluentui/react-utilities#/categories/others/slot' });
+    });
+
+    it('should return null when the symbol does not exist', () => {
+      const result = buildCrossPackageRef('@fluentui/react-utilities', 'NonExistent', mockMetadata);
+
+      expect(result).toBeNull();
+    });
+  });
+
+  describe('loadDependencyMetadata', () => {
+    it('should return null for a non-existent package', () => {
+      const result = loadDependencyMetadata('__non_existent_package__', '/');
+
+      expect(result).toBeNull();
+    });
+  });
+});
diff --git a/tools/cli/src/commands/metadata/impl/cross-package-resolver.ts b/tools/cli/src/commands/metadata/impl/cross-package-resolver.ts
new file mode 100644
index 0000000000000..df4b15d5b21d6
--- /dev/null
+++ b/tools/cli/src/commands/metadata/impl/cross-package-resolver.ts
@@ -0,0 +1,69 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import type { MetadataOutput, RefOrInline } from './types';
+
+/**
+ * Attempt to load a pre-existing metadata.json for a given package.
+ * Looks in the package's root directory (resolved from node_modules).
+ *
+ * @returns The parsed MetadataOutput, or null if not found.
+ */
+export function loadDependencyMetadata(packageSpecifier: string, cwd: string = process.cwd()): MetadataOutput | null {
+  const packageDir = resolvePackageDir(packageSpecifier, cwd);
+  if (!packageDir) {
+    return null;
+  }
+
+  const metadataPath = path.join(packageDir, 'metadata.json');
+  if (!fs.existsSync(metadataPath)) {
+    return null;
+  }
+
+  try {
+    return JSON.parse(fs.readFileSync(metadataPath, 'utf-8')) as MetadataOutput;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Build a cross-package `$ref` for a symbol in a dependency that has metadata.json.
+ *
+ * @returns A $ref like `"@fluentui/react-utilities#/categories/types/ComponentProps"`, or null.
+ */
+export function buildCrossPackageRef(
+  packageSpecifier: string,
+  symbolName: string,
+  dependencyMetadata: MetadataOutput,
+): RefOrInline | null {
+  // Search all categories for the symbol
+  const categories = ['components', 'hooks', 'types', 'others'] as const;
+  for (const category of categories) {
+    const symbolsMap = dependencyMetadata.categories[category];
+    if (symbolName in symbolsMap) {
+      return { $ref: `${packageSpecifier}#/categories/${category}/${symbolName}` };
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Resolve the directory of an npm package from node_modules.
+ */
+function resolvePackageDir(packageSpecifier: string, cwd: string): string | null {
+  // Walk up to find node_modules containing this package
+  let dir = path.resolve(cwd);
+  const root = path.parse(dir).root;
+
+  while (dir !== root) {
+    const candidate = path.join(dir, 'node_modules', packageSpecifier);
+    if (fs.existsSync(candidate)) {
+      return candidate;
+    }
+    dir = path.dirname(dir);
+  }
+
+  return null;
+}
diff --git a/tools/cli/src/commands/metadata/impl/dts-parser.spec.ts b/tools/cli/src/commands/metadata/impl/dts-parser.spec.ts
new file mode 100644
index 0000000000000..5f0f04514dc29
--- /dev/null
+++ b/tools/cli/src/commands/metadata/impl/dts-parser.spec.ts
@@ -0,0 +1,245 @@
+import * as path from 'node:path';
+
+import { parseDtsEntry, type ParseResult } from './dts-parser';
+
+const FIXTURES_DIR = path.resolve(__dirname, '../__fixtures__');
+const SAMPLE_DTS = path.join(FIXTURES_DIR, 'sample-button.d.ts');
+
+describe('parseDtsEntry', () => {
+  let result: ParseResult;
+
+  beforeAll(() => {
+    result = parseDtsEntry(SAMPLE_DTS);
+  });
+
+  describe('components', () => {
+    it('should detect SampleButton as a component', () => {
+      expect(result.components).toHaveProperty('SampleButton');
+    });
+
+    it('should extract component description', () => {
+      expect(result.components.SampleButton.description).toContain(
+        'SampleButton gives people a way to trigger an action',
+      );
+    });
+
+    it('should extract component type signature', () => {
+      expect(result.components.SampleButton.typeSignature).toContain('ForwardRefExoticComponent');
+    });
+
+    it('should extract propsType reference', () => {
+      const propsType = result.components.SampleButton.propsType;
+      expect(propsType).toBeDefined();
+      expect(propsType).toHaveProperty('$ref');
+      expect((propsType as { $ref: string }).$ref).toBe('#/categories/types/SampleButtonProps');
+    });
+  });
+
+  describe('hooks', () => {
+    it('should detect useSampleButton_unstable as a hook', () => {
+      expect(result.hooks).toHaveProperty('useSampleButton_unstable');
+    });
+
+    it('should detect useSampleButtonStyles_unstable as a hook', () => {
+      expect(result.hooks).toHaveProperty('useSampleButtonStyles_unstable');
+    });
+
+    it('should detect useToggleState as a hook', () => {
+      expect(result.hooks).toHaveProperty('useToggleState');
+    });
+
+    it('should extract hook parameters', () => {
+      const hook = result.hooks.useSampleButton_unstable;
+      expect(hook.parameters).toHaveLength(2);
+      expect(hook.parameters[0].name).toBe('props');
+      expect(hook.parameters[1].name).toBe('ref');
+    });
+
+    it('should extract @param descriptions', () => {
+      const hook = result.hooks.useSampleButton_unstable;
+      expect(hook.parameters[0].description).toContain('User provided props');
+    });
+
+    it('should extract hook return type', () => {
+      const hook = result.hooks.useSampleButton_unstable;
+      expect(hook.returnType).toContain('SampleButtonState');
+    });
+  });
+
+  describe('types', () => {
+    it('should detect SampleButtonProps as a type (interface)', () => {
+      expect(result.types).toHaveProperty('SampleButtonProps');
+      expect(result.types.SampleButtonProps.kind).toBe('interface');
+    });
+
+    it('should detect SampleButtonSlots as a type (type-alias)', () => {
+      expect(result.types).toHaveProperty('SampleButtonSlots');
+      expect(result.types.SampleButtonSlots.kind).toBe('type-alias');
+    });
+
+    it('should detect SampleButtonSize as a type (type-alias)', () => {
+      expect(result.types).toHaveProperty('SampleButtonSize');
+    });
+
+    it('should not extract string prototype members for string literal union types', () => {
+      const type = result.types.SampleButtonSize;
+      expect(Object.keys(type.members)).toHaveLength(0);
+    });
+
+    it('should strip inline JSDoc from type alias type signatures', () => {
+      const type = result.types.SampleStateOptions;
+      expect(type).toBeDefined();
+      expect(type.typeSignature).not.toContain('/**');
+      expect(type.typeSignature).not.toContain('*/');
+      expect(type.typeSignature).toContain('defaultState');
+      expect(type.typeSignature).toContain('state');
+    });
+
+    it('should detect ButtonVariant as an enum', () => {
+      expect(result.types).toHaveProperty('ButtonVariant');
+      expect(result.types.ButtonVariant.kind).toBe('enum');
+    });
+
+    it('should extract interface members', () => {
+      const props = result.types.SampleButtonProps;
+      expect(props.members).toHaveProperty('appearance');
+      expect(props.members).toHaveProperty('disabled');
+      expect(props.members).toHaveProperty('size');
+    });
+
+    it('should extract interface method signatures as members', () => {
+      const methods = result.types.SampleSelectionMethods;
+      expect(methods).toBeDefined();
+      expect(methods.members).toHaveProperty('selectItem');
+      expect(methods.members).toHaveProperty('isSelected');
+      expect(methods.members.selectItem.type).toContain('void');
+      expect(methods.members.isSelected.type).toContain('boolean');
+    });
+
+    it('should extract member types', () => {
+      const appearance = result.types.SampleButtonProps.members.appearance;
+      expect(appearance.type).toContain('primary');
+      expect(appearance.required).toBe(false);
+    });
+
+    it('should extract @default values', () => {
+      const appearance = result.types.SampleButtonProps.members.appearance;
+      expect(appearance.defaultValue).toBe("'secondary'");
+    });
+
+    it('should extract member descriptions', () => {
+      const appearance = result.types.SampleButtonProps.members.appearance;
+      expect(appearance.description).toContain('visual style');
+    });
+
+    it('should extract @deprecated tag', () => {
+      const variant = result.types.ButtonVariant;
+      expect(variant.tags).toHaveProperty('deprecated');
+    });
+
+    it('should extract enum members', () => {
+      const variant = result.types.ButtonVariant;
+      expect(variant.members).toHaveProperty('Primary');
+      expect(variant.members).toHaveProperty('Secondary');
+      expect(variant.members.Primary.defaultValue).toBe('primary');
+    });
+  });
+
+  describe('others', () => {
+    it('should detect sampleButtonClassNames as other (variable)', () => {
+      expect(result.others).toHaveProperty('sampleButtonClassNames');
+      expect(result.others.sampleButtonClassNames.kind).toBe('variable');
+    });
+
+    it('should detect renderSampleButton_unstable as other (function)', () => {
+      expect(result.others).toHaveProperty('renderSampleButton_unstable');
+      expect(result.others.renderSampleButton_unstable.kind).toBe('function');
+      expect(result.others.renderSampleButton_unstable.parameters).toBeDefined();
+      expect(result.others.renderSampleButton_unstable.parameters!.length).toBeGreaterThan(0);
+      expect(result.others.renderSampleButton_unstable.returnType).toBeDefined();
+    });
+
+    it('should rename __0 destructured params to arg0', () => {
+      const fn = result.others.getPartitionedProps;
+      expect(fn).toBeDefined();
+      expect(fn.kind).toBe('function');
+      expect(fn.parameters).toBeDefined();
+      expect(fn.parameters![0].name).toBe('arg0');
+      expect(fn.parameters![0].name).not.toContain('__');
+    });
+
+    it('should extract render function description', () => {
+      expect(result.others.renderSampleButton_unstable.description).toContain('Renders SampleButton');
+    });
+
+    it('should extract @internal tag', () => {
+      expect(result.types.SampleButtonContextValue.tags).toHaveProperty('internal');
+    });
+  });
+
+  describe('importedPackages', () => {
+    it('should track imported package specifiers', () => {
+      expect(result.importedPackages.has('react')).toBe(true);
+      expect(result.importedPackages.has('@sample/utilities')).toBe(true);
+    });
+  });
+
+  describe('importedSymbols', () => {
+    it('should track named imports per package', () => {
+      expect(result.importedSymbols.has('@sample/utilities')).toBe(true);
+      const symbols = result.importedSymbols.get('@sample/utilities')!;
+      expect(symbols.has('Slot')).toBe(true);
+      expect(symbols.has('SlotClassNames')).toBe(true);
+    });
+
+    it('should not track namespace imports as named symbols', () => {
+      // `import * as React from 'react'` should not produce named import entries
+      expect(result.importedSymbols.has('react')).toBe(false);
+    });
+  });
+
+  describe('classification boundaries', () => {
+    it('should not misclassify hooks as others', () => {
+      for (const name of Object.keys(result.others)) {
+        expect(name).not.toMatch(/^use[A-Z]/);
+      }
+    });
+
+    it('should not misclassify types as others', () => {
+      for (const name of Object.keys(result.others)) {
+        expect(result.types).not.toHaveProperty(name);
+      }
+    });
+
+    it('should classify camelCase function returning ReactElement as other, not component', () => {
+      expect(result.others).toHaveProperty('getTriggerChild');
+      expect(result.others.getTriggerChild.kind).toBe('function');
+      expect(result.components).not.toHaveProperty('getTriggerChild');
+    });
+
+    it('should classify PascalCase function returning JSX as component', () => {
+      expect(result.components).toHaveProperty('PascalCaseComponent');
+      expect(result.others).not.toHaveProperty('PascalCaseComponent');
+    });
+
+    it('should produce full type signature for function declarations, not typeof', () => {
+      const hook = result.hooks.useToggleState;
+      expect(hook.typeSignature).not.toContain('typeof');
+      expect(hook.typeSignature).toContain('function useToggleState');
+    });
+
+    it('should produce full type signature for other function declarations', () => {
+      const fn = result.others.getTriggerChild;
+      expect(fn.typeSignature).not.toContain('typeof');
+      expect(fn.typeSignature).toContain('function getTriggerChild');
+    });
+
+    it('should strip inline JSDoc from function declaration type signatures', () => {
+      const fn = result.others.isHTMLElement;
+      expect(fn).toBeDefined();
+      expect(fn.typeSignature).not.toContain('/**');
+      expect(fn.typeSignature).not.toContain('*/');
+      expect(fn.typeSignature).toContain('constructorName');
+    });
+  });
+});
diff --git a/tools/cli/src/commands/metadata/impl/dts-parser.ts b/tools/cli/src/commands/metadata/impl/dts-parser.ts
new file mode 100644
index 0000000000000..fd08939b10a88
--- /dev/null
+++ b/tools/cli/src/commands/metadata/impl/dts-parser.ts
@@ -0,0 +1,720 @@
+import {
+  Project,
+  Node,
+  SyntaxKind,
+  type SourceFile,
+  type ExportedDeclarations,
+  type TypeAliasDeclaration,
+  type InterfaceDeclaration,
+  type FunctionDeclaration,
+  type VariableDeclaration,
+  type EnumDeclaration,
+  type ClassDeclaration,
+  type Symbol as TsMorphSymbol,
+} from 'ts-morph';
+
+import type {
+  SymbolClassification,
+  ComponentDoc,
+  HookDoc,
+  TypeDoc,
+  OtherDoc,
+  ParameterDoc,
+  MemberDoc,
+  RefOrInline,
+} from './types';
+
+/** Type patterns that indicate a React component. */
+const COMPONENT_TYPE_PATTERNS = [
+  'ForwardRefComponent',
+  'React.FC',
+  'React.FunctionComponent',
+  'React.ForwardRefExoticComponent',
+  'FC<',
+  'FunctionComponent<',
+  'ForwardRefExoticComponent<',
+];
+
+/** JSX return type names. */
+const JSX_TYPE_NAMES = new Set([
+  'Element',
+  'ReactElement',
+  'ReactNode',
+  'JSX.Element',
+  'React.ReactElement',
+  'React.ReactNode',
+  'JSXElement',
+]);
+
+/**
+ * Result of parsing a .d.ts entry file.
+ */
+export interface ParseResult {
+  components: Record<string, ComponentDoc>;
+  hooks: Record<string, HookDoc>;
+  types: Record<string, TypeDoc>;
+  others: Record<string, OtherDoc>;
+  /** Package specifiers imported by this .d.ts (for cross-package resolution). */
+  importedPackages: Set<string>;
+  /** Named imports grouped by package specifier (e.g. `'@fluentui/react-utilities' → Set('Slot', 'ComponentProps')`). */
+  importedSymbols: Map<string, Set<string>>;
+}
+
+/**
+ * Parse a .d.ts entry file and extract all exported API symbols.
+ */
+export function parseDtsEntry(entryPath: string): ParseResult {
+  const project = new Project({
+    compilerOptions: {
+      declaration: true,
+      // Allow following imports into node_modules .d.ts
+      moduleResolution: 2 /* NodeJs */,
+    },
+    skipAddingFilesFromTsConfig: true,
+  });
+
+  const sourceFile = project.addSourceFileAtPath(entryPath);
+  project.resolveSourceFileDependencies();
+
+  const result: ParseResult = {
+    components: {},
+    hooks: {},
+    types: {},
+    others: {},
+    importedPackages: new Set(),
+    importedSymbols: new Map(),
+  };
+
+  // Collect imported package specifiers and named imports
+  for (const imp of sourceFile.getImportDeclarations()) {
+    const specifier = imp.getModuleSpecifierValue();
+    if (specifier.startsWith('.') || specifier.startsWith('/')) {
+      continue;
+    }
+
+    result.importedPackages.add(specifier);
+
+    // Track individual named imports
+    const namedImports = imp.getNamedImports();
+    if (namedImports.length > 0) {
+      if (!result.importedSymbols.has(specifier)) {
+        result.importedSymbols.set(specifier, new Set());
+      }
+      const symbolSet = result.importedSymbols.get(specifier)!;
+      for (const named of namedImports) {
+        // Use the alias if present, otherwise the original name
+        symbolSet.add(named.getAliasNode()?.getText() ?? named.getName());
+      }
+    }
+
+    // Track default imports
+    const defaultImport = imp.getDefaultImport();
+    if (defaultImport) {
+      if (!result.importedSymbols.has(specifier)) {
+        result.importedSymbols.set(specifier, new Set());
+      }
+      result.importedSymbols.get(specifier)!.add(defaultImport.getText());
+    }
+  }
+
+  // Process all exports
+  const exportedDecls = sourceFile.getExportedDeclarations();
+
+  for (const [name, declarations] of exportedDecls) {
+    // Skip the empty re-export `export { }`
+    if (name === '') {
+      continue;
+    }
+
+    const decl = declarations[0];
+    if (!decl) {
+      continue;
+    }
+
+    const classification = classifyDeclaration(name, decl);
+    const description = extractJsDoc(decl);
+    const tags = extractJsDocTags(decl);
+
+    switch (classification) {
+      case 'component':
+        result.components[name] = buildComponentDoc(name, decl, description, tags);
+        break;
+      case 'hook':
+        result.hooks[name] = buildHookDoc(name, decl, description, tags);
+        break;
+      case 'type':
+        result.types[name] = buildTypeDoc(name, decl, description, tags);
+        break;
+      case 'other':
+        result.others[name] = buildOtherDoc(name, decl, description, tags);
+        break;
+    }
+  }
+
+  return result;
+}
+
+// ============================================================================
+// Classification
+// ============================================================================
+
+function classifyDeclaration(name: string, decl: ExportedDeclarations): SymbolClassification {
+  // Hook: use* naming convention
+  if (/^use[A-Z]/.test(name)) {
+    return 'hook';
+  }
+
+  // Type: interface, type alias, or enum
+  if (Node.isInterfaceDeclaration(decl) || Node.isTypeAliasDeclaration(decl) || Node.isEnumDeclaration(decl)) {
+    return 'type';
+  }
+
+  // Component detection
+  if (Node.isVariableDeclaration(decl)) {
+    const typeText = getTypeText(decl);
+    if (isReactComponentType(typeText)) {
+      return 'component';
+    }
+  }
+
+  // PascalCase function/variable returning JSX → component
+  // camelCase functions returning ReactElement (e.g. getTriggerChild) are utilities, not components
+  if (/^[A-Z]/.test(name)) {
+    if (Node.isFunctionDeclaration(decl)) {
+      const returnType = safeGetReturnTypeText(decl);
+      if (returnsJsx(returnType)) {
+        return 'component';
+      }
+    }
+
+    if (Node.isVariableDeclaration(decl)) {
+      const typeText = getTypeText(decl);
+      if (returnsJsx(typeText)) {
+        return 'component';
+      }
+    }
+  }
+
+  return 'other';
+}
+
+function isReactComponentType(typeText: string): boolean {
+  return COMPONENT_TYPE_PATTERNS.some(p => typeText.includes(p));
+}
+
+function returnsJsx(typeText: string): boolean {
+  for (const jsxType of JSX_TYPE_NAMES) {
+    if (typeText.includes(jsxType)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+// ============================================================================
+// Builders
+// ============================================================================
+
+function buildComponentDoc(
+  name: string,
+  decl: ExportedDeclarations,
+  description: string,
+  tags: Record<string, string>,
+): ComponentDoc {
+  const typeSignature = getTypeText(decl);
+  const propsType = extractPropsTypeRef(typeSignature);
+
+  return { name, description, typeSignature, tags, propsType };
+}
+
+function buildHookDoc(
+  name: string,
+  decl: ExportedDeclarations,
+  description: string,
+  tags: Record<string, string>,
+): HookDoc {
+  const typeSignature = getTypeText(decl);
+  const parameters = extractParameters(decl, tags);
+  const returnType = extractReturnType(decl);
+
+  return { name, description, typeSignature, tags, parameters, returnType };
+}
+
+function buildTypeDoc(
+  name: string,
+  decl: ExportedDeclarations,
+  description: string,
+  tags: Record<string, string>,
+): TypeDoc {
+  let kind: TypeDoc['kind'] = 'type-alias';
+  if (Node.isInterfaceDeclaration(decl)) {
+    kind = 'interface';
+  } else if (Node.isEnumDeclaration(decl)) {
+    kind = 'enum';
+  }
+
+  const typeSignature = getTypeText(decl);
+  const members = extractMembers(decl);
+
+  return { name, description, typeSignature, tags, kind, members };
+}
+
+function buildOtherDoc(
+  name: string,
+  decl: ExportedDeclarations,
+  description: string,
+  tags: Record<string, string>,
+): OtherDoc {
+  let kind: OtherDoc['kind'] = 'unknown';
+  if (Node.isVariableDeclaration(decl)) {
+    kind = isFunctionTypedVariable(decl) ? 'function' : 'variable';
+  } else if (Node.isFunctionDeclaration(decl)) {
+    kind = 'function';
+  } else if (Node.isClassDeclaration(decl)) {
+    kind = 'class';
+  }
+
+  const typeSignature = getTypeText(decl);
+  const doc: OtherDoc = { name, description, typeSignature, tags, kind };
+
+  if (kind === 'function') {
+    doc.parameters = extractParameters(decl, tags);
+    doc.returnType = extractReturnType(decl);
+  }
+
+  return doc;
+}
+
+/**
+ * Checks whether a VariableDeclaration holds a function-typed value
+ * by inspecting its type for call signatures.
+ */
+function isFunctionTypedVariable(decl: VariableDeclaration): boolean {
+  try {
+    const type = decl.getType();
+    return type.getCallSignatures().length > 0;
+  } catch {
+    return false;
+  }
+}
+
+// ============================================================================
+// JSDoc extraction
+// ============================================================================
+
+function extractJsDoc(decl: ExportedDeclarations): string {
+  // For VariableDeclarations, JSDoc sits on the parent VariableStatement
+  const target = getJsDocTarget(decl);
+
+  if (!('getJsDocs' in target)) {
+    return '';
+  }
+
+  try {
+    const jsDocs = (target as unknown as { getJsDocs(): Array<{ getDescription(): string }> }).getJsDocs();
+    if (jsDocs.length === 0) {
+      return '';
+    }
+    return jsDocs
+      .map(doc => doc.getDescription().trim())
+      .filter(Boolean)
+      .join('\n');
+  } catch {
+    return '';
+  }
+}
+
+function extractJsDocTags(decl: ExportedDeclarations): Record<string, string> {
+  const target = getJsDocTarget(decl);
+
+  if (!('getJsDocs' in target)) {
+    return {};
+  }
+
+  const tags: Record<string, string> = {};
+  try {
+    const jsDocs = (
+      target as unknown as {
+        getJsDocs(): Array<{ getTags(): Array<{ getTagName(): string; getCommentText(): string | undefined }> }>;
+      }
+    ).getJsDocs();
+    for (const doc of jsDocs) {
+      for (const tag of doc.getTags()) {
+        const tagName = tag.getTagName();
+        const tagValue = tag.getCommentText() ?? '';
+        // Skip @param tags — they are handled separately
+        if (tagName !== 'param') {
+          tags[tagName] = tagValue.trim();
+        }
+      }
+    }
+  } catch {
+    // Swallow — tags are best-effort
+  }
+
+  return tags;
+}
+
+/**
+ * Extract @param descriptions from JSDoc tags.
+ */
+function extractParamDescriptions(decl: ExportedDeclarations): Map<string, string> {
+  const target = getJsDocTarget(decl);
+  const map = new Map<string, string>();
+  if (!('getJsDocs' in target)) {
+    return map;
+  }
+
+  try {
+    const jsDocs = (
+      target as unknown as {
+        getJsDocs(): Array<{
+          getTags(): Array<{ getTagName(): string; getCommentText(): string | undefined; getName?(): string }>;
+        }>;
+      }
+    ).getJsDocs();
+    for (const doc of jsDocs) {
+      for (const tag of doc.getTags()) {
+        if (tag.getTagName() === 'param' && tag.getName) {
+          map.set(tag.getName!(), (tag.getCommentText() ?? '').trim());
+        }
+      }
+    }
+  } catch {
+    // best-effort
+  }
+
+  return map;
+}
+
+/**
+ * Get the node that carries JSDoc comments.
+ * For VariableDeclarations, JSDoc is on the parent VariableStatement.
+ */
+function getJsDocTarget(decl: ExportedDeclarations): Node {
+  if (Node.isVariableDeclaration(decl)) {
+    const varDeclList = decl.getParent();
+    if (varDeclList) {
+      const varStatement = varDeclList.getParent();
+      if (varStatement && 'getJsDocs' in varStatement) {
+        return varStatement as Node;
+      }
+    }
+  }
+  return decl;
+}
+
+// ============================================================================
+// Type extraction helpers
+// ============================================================================
+
+function getTypeText(decl: ExportedDeclarations): string {
+  try {
+    let text = '';
+
+    if (Node.isVariableDeclaration(decl)) {
+      // Prefer the explicit type annotation (e.g. `unique symbol`, `typeof React.useEffect`)
+      // over the resolved type which often produces unhelpful `typeof varName`.
+      text = decl.getTypeNode()?.getText() ?? decl.getType().getText(decl);
+    } else if (Node.isFunctionDeclaration(decl)) {
+      // decl.getType().getText() returns "typeof funcName" for function declarations.
+      // Use the declaration text stripped of 'export'/'declare' keywords for a full signature.
+      text = decl.getText().trim();
+      text = text.replace(/^export\s+/, '').replace(/^declare\s+/, '');
+    } else if (Node.isTypeAliasDeclaration(decl)) {
+      text = decl.getTypeNode()?.getText() ?? decl.getType().getText(decl);
+    } else if (Node.isInterfaceDeclaration(decl)) {
+      // For interfaces, show the heritage and structure
+      const heritageText = decl
+        .getExtends()
+        .map(e => e.getText())
+        .join(' & ');
+      const membersPreview = decl.getMembers().length > 0 ? '{ ... }' : '{}';
+      text = heritageText ? `${heritageText} & ${membersPreview}` : membersPreview;
+    } else if (Node.isEnumDeclaration(decl)) {
+      const members = decl.getMembers().map(m => m.getName());
+      text = `enum { ${members.join(', ')} }`;
+    } else {
+      text = decl.getType().getText(decl);
+    }
+
+    return stripJsDocComments(text);
+  } catch {
+    return '';
+  }
+}
+
+/**
+ * Strip block comments (including JSDoc) from type text and normalize whitespace.
+ * Type annotations in .d.ts files can contain inline JSDoc on object members.
+ */
+function stripJsDocComments(text: string): string {
+  text = text.replace(/\/\*[\s\S]*?\*\//g, '');
+  text = text.replace(/\s+/g, ' ').trim();
+  return text;
+}
+
+function safeGetReturnTypeText(decl: FunctionDeclaration): string {
+  try {
+    return decl.getReturnType().getText(decl);
+  } catch {
+    return '';
+  }
+}
+
+function extractReturnType(decl: ExportedDeclarations): string {
+  try {
+    if (Node.isFunctionDeclaration(decl)) {
+      const rtNode = decl.getReturnTypeNode();
+      return rtNode?.getText() ?? decl.getReturnType().getText(decl);
+    }
+    if (Node.isVariableDeclaration(decl)) {
+      // For arrow function variables, try to get the call signatures
+      const type = decl.getType();
+      const callSigs = type.getCallSignatures();
+      if (callSigs.length > 0) {
+        return callSigs[0].getReturnType().getText(decl);
+      }
+    }
+  } catch {
+    // fall through
+  }
+  return '';
+}
+
+function extractParameters(decl: ExportedDeclarations, jsdocTags: Record<string, string>): ParameterDoc[] {
+  const paramDescriptions = extractParamDescriptions(decl);
+  const params: ParameterDoc[] = [];
+
+  try {
+    if (Node.isFunctionDeclaration(decl)) {
+      for (const param of decl.getParameters()) {
+        const name = param.getName();
+        params.push({
+          name,
+          type: param.getTypeNode()?.getText() ?? param.getType().getText(decl),
+          required: !param.isOptional(),
+          description: paramDescriptions.get(name) ?? '',
+        });
+      }
+    } else if (Node.isVariableDeclaration(decl)) {
+      // Arrow function variable — parse call signatures
+      const type = decl.getType();
+      const callSigs = type.getCallSignatures();
+      if (callSigs.length > 0) {
+        for (let i = 0; i < callSigs[0].getParameters().length; i++) {
+          const param = callSigs[0].getParameters()[i];
+          const paramDecl = param.getDeclarations()[0];
+          const rawName = param.getName();
+          // TypeScript uses __0, __1 etc. for destructured parameters; use arg0, arg1 instead
+          const name = /^__\d+$/.test(rawName) ? `arg${rawName.slice(2)}` : rawName;
+          params.push({
+            name,
+            type: paramDecl ? paramDecl.getType().getText(paramDecl) : param.getDeclaredType().getText(),
+            required: paramDecl ? !Node.isParameterDeclaration(paramDecl) || !paramDecl.isOptional() : true,
+            description: paramDescriptions.get(rawName) ?? paramDescriptions.get(name) ?? '',
+          });
+        }
+      }
+    }
+  } catch {
+    // best-effort
+  }
+
+  return params;
+}
+
+// ============================================================================
+// Member extraction (for interfaces and type aliases)
+// ============================================================================
+
+function extractMembers(decl: ExportedDeclarations): Record<string, MemberDoc> {
+  const members: Record<string, MemberDoc> = {};
+
+  try {
+    if (Node.isInterfaceDeclaration(decl)) {
+      extractInterfaceMembers(decl, members);
+    } else if (Node.isTypeAliasDeclaration(decl)) {
+      extractTypeAliasMembers(decl, members);
+    } else if (Node.isEnumDeclaration(decl)) {
+      extractEnumMembers(decl, members);
+    }
+  } catch {
+    // best-effort
+  }
+
+  return members;
+}
+
+function extractInterfaceMembers(decl: InterfaceDeclaration, members: Record<string, MemberDoc>): void {
+  for (const prop of decl.getProperties()) {
+    const name = prop.getName();
+    const jsDocDescription = extractPropertyJsDoc(prop);
+    const defaultValue = extractDefaultTag(prop);
+
+    members[name] = {
+      name,
+      type: prop.getTypeNode()?.getText() ?? prop.getType().getText(prop),
+      required: !prop.hasQuestionToken(),
+      description: jsDocDescription,
+      ...(defaultValue !== undefined ? { defaultValue } : {}),
+    };
+  }
+
+  for (const method of decl.getMethods()) {
+    const name = method.getName();
+    const jsDocDescription = extractPropertyJsDoc(method);
+    const params = method
+      .getParameters()
+      .map(p => p.getText())
+      .join(', ');
+    const returnType = method.getReturnTypeNode()?.getText() ?? '';
+    const typeSignature = `(${params}) => ${returnType}`;
+
+    members[name] = {
+      name,
+      type: stripJsDocComments(typeSignature),
+      required: !method.hasQuestionToken(),
+      description: jsDocDescription,
+    };
+  }
+}
+
+function extractTypeAliasMembers(decl: TypeAliasDeclaration, members: Record<string, MemberDoc>): void {
+  const type = decl.getType();
+
+  // Skip member extraction for primitive, literal, and non-object types.
+  // e.g. `type SelectionMode = 'single' | 'multiselect'` would incorrectly
+  // yield String.prototype members (toString, charAt, …) via getProperties().
+  if (type.isUnion()) {
+    const allPrimitive = type
+      .getUnionTypes()
+      .every(
+        t =>
+          t.isStringLiteral() ||
+          t.isNumberLiteral() ||
+          t.isBooleanLiteral() ||
+          t.isString() ||
+          t.isNumber() ||
+          t.isBoolean() ||
+          t.isUndefined() ||
+          t.isNull(),
+      );
+    if (allPrimitive) {
+      return;
+    }
+  }
+  if (
+    type.isStringLiteral() ||
+    type.isNumberLiteral() ||
+    type.isBooleanLiteral() ||
+    type.isString() ||
+    type.isNumber() ||
+    type.isBoolean() ||
+    type.isUndefined() ||
+    type.isNull()
+  ) {
+    return;
+  }
+
+  for (const prop of type.getProperties()) {
+    const propDecl = prop.getDeclarations()[0];
+    if (!propDecl) {
+      continue;
+    }
+
+    const name = prop.getName();
+    const jsDocDescription = extractPropertyJsDoc(propDecl);
+    const defaultValue = extractDefaultTag(propDecl);
+
+    members[name] = {
+      name,
+      type: propDecl.getType().getText(propDecl),
+      required: !(
+        'hasQuestionToken' in propDecl &&
+        typeof propDecl.hasQuestionToken === 'function' &&
+        propDecl.hasQuestionToken()
+      ),
+      description: jsDocDescription,
+      ...(defaultValue !== undefined ? { defaultValue } : {}),
+    };
+  }
+}
+
+function extractEnumMembers(decl: EnumDeclaration, members: Record<string, MemberDoc>): void {
+  for (const member of decl.getMembers()) {
+    const name = member.getName();
+    const value = member.getValue();
+    members[name] = {
+      name,
+      type: typeof value === 'string' ? 'string' : 'number',
+      required: true,
+      description: extractPropertyJsDoc(member),
+      ...(value !== undefined ? { defaultValue: String(value) } : {}),
+    };
+  }
+}
+
+// ============================================================================
+// Property-level JSDoc helpers
+// ============================================================================
+
+function extractPropertyJsDoc(node: Node): string {
+  try {
+    if ('getJsDocs' in node) {
+      const jsDocs = (node as unknown as { getJsDocs(): Array<{ getDescription(): string }> }).getJsDocs();
+      return jsDocs
+        .map(doc => doc.getDescription().trim())
+        .filter(Boolean)
+        .join('\n');
+    }
+  } catch {
+    // fall through
+  }
+  return '';
+}
+
+function extractDefaultTag(node: Node): string | undefined {
+  try {
+    if ('getJsDocs' in node) {
+      const jsDocs = (
+        node as unknown as {
+          getJsDocs(): Array<{ getTags(): Array<{ getTagName(): string; getCommentText(): string | undefined }> }>;
+        }
+      ).getJsDocs();
+      for (const doc of jsDocs) {
+        for (const tag of doc.getTags()) {
+          if (tag.getTagName() === 'default') {
+            return (tag.getCommentText() ?? '').trim();
+          }
+        }
+      }
+    }
+  } catch {
+    // fall through
+  }
+  return undefined;
+}
+
+// ============================================================================
+// Props type reference extraction
+// ============================================================================
+
+/**
+ * Extract a `$ref` to the props type from a component's type signature.
+ * e.g. `ForwardRefExoticComponent<ButtonProps & RefAttributes<...>>` → `{ "$ref": "#/categories/types/ButtonProps" }`
+ */
+function extractPropsTypeRef(typeSignature: string): RefOrInline | undefined {
+  // Match patterns like ForwardRefComponent<XxxProps>, React.FC<XxxProps>, etc.
+  // The props type is the first type argument before any `&` or `>`
+  const match = typeSignature.match(
+    /(?:ForwardRefComponent|ForwardRefExoticComponent|React\.FC|React\.FunctionComponent|FC|FunctionComponent)<\s*([A-Z][A-Za-z0-9_]*)/,
+  );
+
+  if (match) {
+    const propsTypeName = match[1];
+    return { $ref: `#/categories/types/${propsTypeName}` };
+  }
+
+  return undefined;
+}
diff --git a/tools/cli/src/commands/metadata/impl/entry-resolver.spec.ts b/tools/cli/src/commands/metadata/impl/entry-resolver.spec.ts
new file mode 100644
index 0000000000000..85a39081fa75c
--- /dev/null
+++ b/tools/cli/src/commands/metadata/impl/entry-resolver.spec.ts
@@ -0,0 +1,52 @@
+import * as path from 'node:path';
+import * as fs from 'node:fs';
+
+import { resolveEntry, readPackageInfo } from './entry-resolver';
+
+const FIXTURES_DIR = path.resolve(__dirname, '../__fixtures__');
+
+describe('resolveEntry', () => {
+  it('should resolve from package.json "types" field', () => {
+    const result = resolveEntry(undefined, FIXTURES_DIR);
+
+    expect(result).toBe(path.join(FIXTURES_DIR, 'sample-button.d.ts'));
+    expect(fs.existsSync(result)).toBe(true);
+  });
+
+  it('should accept an explicit entry override', () => {
+    const entryPath = path.join(FIXTURES_DIR, 'sample-button.d.ts');
+    const result = resolveEntry(entryPath);
+
+    expect(result).toBe(entryPath);
+  });
+
+  it('should resolve from package.json when entry override is a directory', () => {
+    const result = resolveEntry(FIXTURES_DIR);
+
+    expect(result).toBe(path.join(FIXTURES_DIR, 'sample-button.d.ts'));
+  });
+
+  it('should throw when explicit entry does not exist', () => {
+    expect(() => resolveEntry('/nonexistent/file.d.ts')).toThrow('Entry file not found');
+  });
+
+  it('should throw when no package.json is found', () => {
+    expect(() => resolveEntry(undefined, '/')).toThrow('Could not find package.json');
+  });
+});
+
+describe('readPackageInfo', () => {
+  it('should read name and version from package.json', () => {
+    const info = readPackageInfo(FIXTURES_DIR);
+
+    expect(info.name).toBe('@fluentui/sample-button');
+    expect(info.version).toBe('1.0.0');
+  });
+
+  it('should return defaults when no package.json found', () => {
+    const info = readPackageInfo('/');
+
+    expect(info.name).toBe('unknown');
+    expect(info.version).toBe('0.0.0');
+  });
+});
diff --git a/tools/cli/src/commands/metadata/impl/entry-resolver.ts b/tools/cli/src/commands/metadata/impl/entry-resolver.ts
new file mode 100644
index 0000000000000..31f3b65355cde
--- /dev/null
+++ b/tools/cli/src/commands/metadata/impl/entry-resolver.ts
@@ -0,0 +1,93 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+/**
+ * Resolve the .d.ts entry file for metadata extraction.
+ *
+ * Resolution order:
+ * 1. If `entryOverride` is provided, use it directly.
+ * 2. Otherwise, find the closest package.json and read the "types" or "typings" field.
+ *
+ * @returns Absolute path to the .d.ts entry file.
+ * @throws If no entry can be resolved or the file does not exist.
+ */
+export function resolveEntry(entryOverride?: string, cwd: string = process.cwd()): string {
+  if (entryOverride) {
+    const resolved = path.resolve(cwd, entryOverride);
+    if (!fs.existsSync(resolved)) {
+      throw new Error(`Entry file not found: ${resolved}`);
+    }
+
+    // If the override points to a directory, resolve its package.json types field
+    if (fs.statSync(resolved).isDirectory()) {
+      return resolveFromPackageJson(resolved);
+    }
+
+    return resolved;
+  }
+
+  return resolveFromPackageJson(cwd);
+}
+
+/**
+ * Read package name and version from the closest package.json.
+ */
+export function readPackageInfo(cwd: string = process.cwd()): { name: string; version: string } {
+  const packageJsonPath = findClosestPackageJson(cwd);
+  if (!packageJsonPath) {
+    return { name: 'unknown', version: '0.0.0' };
+  }
+
+  const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf-8'));
+  return {
+    name: packageJson.name ?? 'unknown',
+    version: packageJson.version ?? '0.0.0',
+  };
+}
+
+/**
+ * Resolve the .d.ts entry from the closest package.json in `startDir`.
+ */
+function resolveFromPackageJson(startDir: string): string {
+  const packageJsonPath = findClosestPackageJson(startDir);
+  if (!packageJsonPath) {
+    throw new Error(`Could not find package.json from ${startDir}`);
+  }
+
+  const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf-8'));
+  const typesField: string | undefined = packageJson.types ?? packageJson.typings;
+
+  if (!typesField) {
+    throw new Error(
+      `No "types" or "typings" field found in ${packageJsonPath}. ` + 'Use --entry to specify the .d.ts file manually.',
+    );
+  }
+
+  const resolved = path.resolve(path.dirname(packageJsonPath), typesField);
+  if (!fs.existsSync(resolved)) {
+    throw new Error(
+      `Types entry "${typesField}" resolved to ${resolved} but the file does not exist. ` +
+        'Has the package been built?',
+    );
+  }
+
+  return resolved;
+}
+
+/**
+ * Walk up from `startDir` looking for a package.json.
+ */
+function findClosestPackageJson(startDir: string): string | null {
+  let dir = path.resolve(startDir);
+  const root = path.parse(dir).root;
+
+  while (dir !== root) {
+    const candidate = path.join(dir, 'package.json');
+    if (fs.existsSync(candidate)) {
+      return candidate;
+    }
+    dir = path.dirname(dir);
+  }
+
+  return null;
+}
diff --git a/tools/cli/src/commands/metadata/impl/html-formatter.ts b/tools/cli/src/commands/metadata/impl/html-formatter.ts
new file mode 100644
index 0000000000000..db77cf021900c
--- /dev/null
+++ b/tools/cli/src/commands/metadata/impl/html-formatter.ts
@@ -0,0 +1,370 @@
+import type {
+  MetadataOutput,
+  ComponentDoc,
+  HookDoc,
+  TypeDoc,
+  OtherDoc,
+  MemberDoc,
+  ParameterDoc,
+  BaseSymbolDoc,
+  ExternalPackageRef,
+} from './types';
+import { groupByAnnotation, type AnnotationGroup } from './annotation-groups';
+
+/**
+ * Format MetadataOutput as a self-contained HTML document.
+ */
+export function formatMetadataAsHtml(data: MetadataOutput): string {
+  const { package: pkg, legend, categories, externalReferences } = data;
+
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<title>API Metadata: ${esc(pkg.name)}</title>
+${renderStyles()}
+</head>
+<body>
+<main>
+<h1>API Metadata: <code>${esc(pkg.name)}</code> v${esc(pkg.version)}</h1>
+${renderLegend(legend)}
+${renderSummary(categories)}
+${renderComponents(categories.components)}
+${renderHooks(categories.hooks)}
+${renderTypes(categories.types)}
+${renderOthers(categories.others)}
+${renderExternalReferences(externalReferences)}
+</main>
+</body>
+</html>`;
+}
+
+// ---------------------------------------------------------------------------
+// Sections
+// ---------------------------------------------------------------------------
+
+function renderLegend(legend: MetadataOutput['legend']): string {
+  const rows = Object.values(legend)
+    .map(e => `<tr><td><strong>${esc(e.name)}</strong></td><td>${esc(e.description)}</td></tr>`)
+    .join('\n');
+
+  return `<section class="legend">
+<h2>Legend</h2>
+<table><thead><tr><th>Category</th><th>Description</th></tr></thead>
+<tbody>${rows}</tbody></table>
+</section>`;
+}
+
+function renderSummary(categories: MetadataOutput['categories']): string {
+  const counts = [
+    ['Components', 'cat-components', Object.keys(categories.components).length],
+    ['Hooks', 'cat-hooks', Object.keys(categories.hooks).length],
+    ['Types', 'cat-types', Object.keys(categories.types).length],
+    ['Others', 'cat-others', Object.keys(categories.others).length],
+  ] as const;
+
+  const rows = counts
+    .map(([name, anchor, count]) => `<tr><td><a href="#${anchor}">${name}</a></td><td>${count}</td></tr>`)
+    .join('\n');
+
+  return `<section class="summary">
+<h2>Summary</h2>
+<table><thead><tr><th>Category</th><th>Count</th></tr></thead>
+<tbody>${rows}</tbody></table>
+</section>`;
+}
+
+function renderComponents(components: Record<string, ComponentDoc>): string {
+  const all = Object.values(components);
+  if (all.length === 0) {
+    return '';
+  }
+
+  const groups = groupByAnnotation(all);
+
+  return `<section id="cat-components">
+<details><summary><h2 style="display:inline">Components</h2> <span class="count">(${all.length})</span></summary>
+${renderAnnotationGroups(groups, renderComponentItem)}
+</details></section>`;
+}
+
+function renderComponentItem(comp: ComponentDoc): string {
+  const propsRef = comp.propsType ? `<p><strong>Props:</strong> ${renderRef(comp.propsType)}</p>` : '';
+
+  return `<div class="symbol" id="${toAnchor(comp.name)}">
+<h3><code>${esc(comp.name)}</code></h3>
+${comp.description ? `<p>${esc(comp.description)}</p>` : ''}
+<p><strong>Type:</strong> <code>${esc(comp.typeSignature)}</code></p>
+${propsRef}
+${renderTagsBadges(comp.tags)}
+</div>`;
+}
+
+function renderHooks(hooks: Record<string, HookDoc>): string {
+  const all = Object.values(hooks);
+  if (all.length === 0) {
+    return '';
+  }
+
+  const groups = groupByAnnotation(all);
+
+  return `<section id="cat-hooks">
+<details><summary><h2 style="display:inline">Hooks</h2> <span class="count">(${all.length})</span></summary>
+${renderAnnotationGroups(groups, renderHookItem)}
+</details></section>`;
+}
+
+function renderHookItem(hook: HookDoc): string {
+  return `<div class="symbol" id="${toAnchor(hook.name)}">
+<h3><code>${esc(hook.name)}</code></h3>
+${hook.description ? `<p>${esc(hook.description)}</p>` : ''}
+<p><strong>Signature:</strong> <code>${esc(hook.typeSignature)}</code></p>
+${hook.parameters.length > 0 ? renderParametersTable(hook.parameters, 'Arguments') : ''}
+<p><strong>Returns:</strong> <code>${esc(hook.returnType)}</code></p>
+${renderTagsBadges(hook.tags)}
+</div>`;
+}
+
+function renderTypes(types: Record<string, TypeDoc>): string {
+  const all = Object.values(types);
+  if (all.length === 0) {
+    return '';
+  }
+
+  const groups = groupByAnnotation(all);
+
+  return `<section id="cat-types">
+<details><summary><h2 style="display:inline">Types</h2> <span class="count">(${all.length})</span></summary>
+${renderAnnotationGroups(groups, renderTypeItem)}
+</details></section>`;
+}
+
+function renderTypeItem(type: TypeDoc): string {
+  const memberEntries = Object.values(type.members);
+  return `<div class="symbol" id="${toAnchor(type.name)}">
+<h3><code>${esc(type.name)}</code> <span class="kind">${esc(type.kind)}</span></h3>
+${type.description ? `<p>${esc(type.description)}</p>` : ''}
+<p><strong>Type:</strong> <code>${esc(type.typeSignature)}</code></p>
+${memberEntries.length > 0 ? renderMembersTable(memberEntries) : ''}
+${renderTagsBadges(type.tags)}
+</div>`;
+}
+
+function renderOthers(others: Record<string, OtherDoc>): string {
+  const all = Object.values(others);
+  if (all.length === 0) {
+    return '';
+  }
+
+  const groups = groupByAnnotation(all);
+
+  return `<section id="cat-others">
+<details><summary><h2 style="display:inline">Others</h2> <span class="count">(${all.length})</span></summary>
+${renderAnnotationGroups(groups, renderOtherItem)}
+</details></section>`;
+}
+
+function renderOtherItem(other: OtherDoc): string {
+  return `<div class="symbol" id="${toAnchor(other.name)}">
+<h3><code>${esc(other.name)}</code> <span class="kind">${esc(other.kind)}</span></h3>
+${other.description ? `<p>${esc(other.description)}</p>` : ''}
+<p><strong>Type:</strong> <code>${esc(other.typeSignature)}</code></p>
+${other.parameters && other.parameters.length > 0 ? renderParametersTable(other.parameters, 'Arguments') : ''}
+${other.returnType ? `<p><strong>Returns:</strong> <code>${esc(other.returnType)}</code></p>` : ''}
+${renderTagsBadges(other.tags)}
+</div>`;
+}
+
+function renderExternalReferences(externalReferences?: Record<string, ExternalPackageRef>): string {
+  if (!externalReferences || Object.keys(externalReferences).length === 0) {
+    return '';
+  }
+
+  const totalSymbols = Object.values(externalReferences).reduce((sum, pkg) => sum + Object.keys(pkg.symbols).length, 0);
+
+  const packages = Object.entries(externalReferences)
+    .sort(([a], [b]) => a.localeCompare(b))
+    .map(([pkgSpec, pkgRef]) => {
+      const symbolRows = Object.entries(pkgRef.symbols)
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([name, ref]) => {
+          const refDisplay =
+            '$ref' in ref
+              ? `<code class="cross-ref" title="${esc(ref.$ref)}">${esc(ref.$ref)}</code>`
+              : `<code>${esc(ref.inline)}</code>`;
+          return `<tr><td><code>${esc(name)}</code></td><td>${refDisplay}</td></tr>`;
+        })
+        .join('\n');
+
+      return `<div class="ext-package">
+<h4><code>${esc(pkgSpec)}</code> <span class="count">(${Object.keys(pkgRef.symbols).length} symbols)</span></h4>
+<p class="metadata-ref">metadata: <code>${esc(pkgRef.metadataRef)}</code></p>
+<table>
+<thead><tr><th>Symbol</th><th>Reference</th></tr></thead>
+<tbody>${symbolRows}</tbody>
+</table>
+</div>`;
+    })
+    .join('\n');
+
+  return `<section id="cat-external-refs">
+<details><summary><h2 style="display:inline">External References</h2> <span class="count">(${totalSymbols} symbols from ${
+    Object.keys(externalReferences).length
+  } packages)</span></summary>
+${packages}
+</details></section>`;
+}
+
+// ---------------------------------------------------------------------------
+// Annotation sub-group renderer
+// ---------------------------------------------------------------------------
+
+function renderAnnotationGroups<T extends BaseSymbolDoc>(
+  groups: AnnotationGroup<T>[],
+  renderItem: (item: T) => string,
+): string {
+  // When there's only one group (all stable), skip the sub-group wrapper
+  if (groups.length === 1 && groups[0].key === 'stable') {
+    return groups[0].items.map(renderItem).join('\n');
+  }
+
+  return groups
+    .map(g => {
+      const items = g.items.map(renderItem).join('\n');
+      return `<div class="annotation-group annotation-${g.key}">
+<h4 class="annotation-heading">${esc(g.label)} <span class="count">(${g.items.length})</span></h4>
+${items}
+</div>`;
+    })
+    .join('\n');
+}
+
+// ---------------------------------------------------------------------------
+// Shared renderers
+// ---------------------------------------------------------------------------
+
+function renderParametersTable(params: ParameterDoc[], title: string): string {
+  const rows = params
+    .map(
+      p =>
+        `<tr><td><code>${esc(p.name)}</code></td><td><code>${esc(p.type)}</code></td><td>${
+          p.required ? 'Yes' : 'No'
+        }</td><td>${esc(p.description)}</td></tr>`,
+    )
+    .join('\n');
+
+  return `<p><strong>${esc(title)}:</strong></p>
+<table class="params">
+<thead><tr><th>Name</th><th>Type</th><th>Required</th><th>Description</th></tr></thead>
+<tbody>${rows}</tbody></table>`;
+}
+
+function renderMembersTable(members: MemberDoc[]): string {
+  const rows = members
+    .map(
+      m =>
+        `<tr><td><code>${esc(m.name)}</code></td><td><code>${esc(m.type)}</code></td><td>${
+          m.required ? 'Yes' : 'No'
+        }</td><td>${m.defaultValue ? `<code>${esc(m.defaultValue)}</code>` : '—'}</td><td>${esc(
+          m.description,
+        )}</td></tr>`,
+    )
+    .join('\n');
+
+  return `<details><summary><strong>Members</strong> (${members.length})</summary>
+<table class="members">
+<thead><tr><th>Name</th><th>Type</th><th>Required</th><th>Default</th><th>Description</th></tr></thead>
+<tbody>${rows}</tbody></table></details>`;
+}
+
+function renderTagsBadges(tags: Record<string, string>): string {
+  const entries = Object.entries(tags);
+  if (entries.length === 0) {
+    return '';
+  }
+  const badges = entries.map(([key, val]) => `<span class="tag">@${esc(key)}${val ? ` ${esc(val)}` : ''}</span>`);
+  return `<div class="tags">${badges.join(' ')}</div>`;
+}
+
+/**
+ * Render a $ref or inline type as HTML.
+ * Local refs (e.g. `#/categories/types/ButtonProps`) become clickable anchor links.
+ * Cross-package refs (e.g. `@fluentui/react-utilities#/...`) are shown as non-linked code.
+ */
+function renderRef(ref: { $ref: string } | { inline: string }): string {
+  if ('inline' in ref) {
+    return `<code>${esc(ref.inline)}</code>`;
+  }
+
+  const refValue = ref.$ref;
+  // Local ref: #/categories/<category>/<symbolName>
+  if (refValue.startsWith('#/')) {
+    const symbolName = refValue.split('/').pop()!;
+    return `<a href="#${toAnchor(symbolName)}" class="ref-link"><code>${esc(symbolName)}</code></a>`;
+  }
+
+  // Cross-package ref: @scope/pkg#/categories/<category>/<symbolName>
+  const hashIdx = refValue.indexOf('#/');
+  if (hashIdx > 0) {
+    const pkgName = refValue.substring(0, hashIdx);
+    const symbolName = refValue.split('/').pop()!;
+    return `<code class="cross-ref" title="${esc(refValue)}">${esc(pkgName)} → ${esc(symbolName)}</code>`;
+  }
+
+  return `<code>${esc(refValue)}</code>`;
+}
+
+// ---------------------------------------------------------------------------
+// Utilities
+// ---------------------------------------------------------------------------
+
+function esc(text: string): string {
+  return text.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+}
+
+function toAnchor(name: string): string {
+  return 'sym-' + name.replace(/[^a-zA-Z0-9_-]/g, '-');
+}
+
+function renderStyles(): string {
+  return `<style>
+:root { --bg: #fff; --fg: #1a1a1a; --muted: #6b7280; --border: #e5e7eb; --accent: #0078d4; --accent-light: #e8f4fd; --code-bg: #f3f4f6; --section-bg: #fafafa; }
+@media (prefers-color-scheme: dark) {
+  :root { --bg: #1e1e1e; --fg: #d4d4d4; --muted: #9ca3af; --border: #374151; --accent: #4fc3f7; --accent-light: #1e3a4d; --code-bg: #2d2d2d; --section-bg: #252525; }
+}
+*, *::before, *::after { box-sizing: border-box; }
+html { scroll-behavior: smooth; }
+body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; background: var(--bg); color: var(--fg); line-height: 1.6; margin: 0; padding: 2rem; }
+main { max-width: 960px; margin: 0 auto; }
+h1 { border-bottom: 2px solid var(--accent); padding-bottom: .5rem; }
+h2 { margin-top: 2rem; color: var(--accent); }
+h3 { margin-top: 1rem; }
+code { background: var(--code-bg); padding: .15em .35em; border-radius: 3px; font-size: .9em; }
+table { width: 100%; border-collapse: collapse; margin: .5rem 0 1rem; font-size: .9rem; }
+th, td { text-align: left; padding: .45rem .75rem; border: 1px solid var(--border); }
+th { background: var(--section-bg); font-weight: 600; }
+.symbol { border-top: 1px solid var(--border); padding: .75rem 0; }
+.kind { font-size: .8em; color: var(--muted); font-style: italic; }
+.tags { margin-top: .5rem; }
+.tag { display: inline-block; background: var(--accent-light); border: 1px solid var(--border); border-radius: 10px; padding: .1em .6em; font-size: .8em; margin-right: .3rem; }
+.count { font-size: .85em; color: var(--muted); font-weight: normal; }
+.summary a { color: var(--accent); text-decoration: none; }
+.summary a:hover { text-decoration: underline; }
+a.ref-link { color: var(--accent); text-decoration: none; }
+a.ref-link:hover { text-decoration: underline; }
+a.ref-link code { background: var(--accent-light); border: 1px solid var(--border); }
+.cross-ref { border: 1px dashed var(--border); font-style: italic; }
+details > summary { cursor: pointer; padding: .3rem 0; }
+details > summary:hover { opacity: .8; }
+details.symbol-props summary { font-weight: 600; }
+.annotation-group { margin: .75rem 0; padding-left: .5rem; border-left: 3px solid var(--border); }
+.annotation-group.annotation-deprecated { border-left-color: #d97706; }
+.annotation-group.annotation-internal { border-left-color: #7c3aed; }
+.annotation-group.annotation-preview { border-left-color: #2563eb; }
+.annotation-heading { font-size: .95em; color: var(--muted); margin: .5rem 0; }
+.ext-package { margin: .75rem 0; }
+.ext-package h4 { margin: .5rem 0; }
+.metadata-ref { font-size: .85em; color: var(--muted); margin: .25rem 0; }
+</style>`;
+}
diff --git a/tools/cli/src/commands/metadata/impl/markdown-formatter.ts b/tools/cli/src/commands/metadata/impl/markdown-formatter.ts
new file mode 100644
index 0000000000000..fe387eef86e85
--- /dev/null
+++ b/tools/cli/src/commands/metadata/impl/markdown-formatter.ts
@@ -0,0 +1,299 @@
+import type {
+  MetadataOutput,
+  ComponentDoc,
+  HookDoc,
+  TypeDoc,
+  OtherDoc,
+  MemberDoc,
+  ParameterDoc,
+  RefOrInline,
+  BaseSymbolDoc,
+  ExternalPackageRef,
+} from './types';
+import { groupByAnnotation, type AnnotationGroup } from './annotation-groups';
+
+/**
+ * Format MetadataOutput as a structured Markdown document.
+ */
+export function formatMetadataAsMarkdown(data: MetadataOutput): string {
+  const { package: pkg, legend, categories, externalReferences } = data;
+  const lines: string[] = [];
+
+  lines.push(`# API Metadata: \`${pkg.name}\` v${pkg.version}`);
+  lines.push('');
+
+  // Legend
+  lines.push('## Legend');
+  lines.push('');
+  lines.push('| Category | Description |');
+  lines.push('| -------- | ----------- |');
+  for (const entry of Object.values(legend)) {
+    lines.push(`| **${entry.name}** | ${entry.description} |`);
+  }
+  lines.push('');
+
+  // Summary
+  lines.push('## Summary');
+  lines.push('');
+  lines.push(`| Category | Count |`);
+  lines.push(`| -------- | ----- |`);
+  lines.push(`| Components | ${Object.keys(categories.components).length} |`);
+  lines.push(`| Hooks | ${Object.keys(categories.hooks).length} |`);
+  lines.push(`| Types | ${Object.keys(categories.types).length} |`);
+  lines.push(`| Others | ${Object.keys(categories.others).length} |`);
+  lines.push('');
+
+  // Components
+  if (Object.keys(categories.components).length > 0) {
+    const groups = groupByAnnotation(Object.values(categories.components));
+    lines.push('<details>');
+    lines.push(`<summary><h2>Components (${Object.keys(categories.components).length})</h2></summary>`);
+    lines.push('');
+    lines.push(...formatAnnotationGroups(groups, formatComponent));
+    lines.push('</details>');
+    lines.push('');
+  }
+
+  // Hooks
+  if (Object.keys(categories.hooks).length > 0) {
+    const groups = groupByAnnotation(Object.values(categories.hooks));
+    lines.push('<details>');
+    lines.push(`<summary><h2>Hooks (${Object.keys(categories.hooks).length})</h2></summary>`);
+    lines.push('');
+    lines.push(...formatAnnotationGroups(groups, formatHook));
+    lines.push('</details>');
+    lines.push('');
+  }
+
+  // Types
+  if (Object.keys(categories.types).length > 0) {
+    const groups = groupByAnnotation(Object.values(categories.types));
+    lines.push('<details>');
+    lines.push(`<summary><h2>Types (${Object.keys(categories.types).length})</h2></summary>`);
+    lines.push('');
+    lines.push(...formatAnnotationGroups(groups, formatType));
+    lines.push('</details>');
+    lines.push('');
+  }
+
+  // Others
+  if (Object.keys(categories.others).length > 0) {
+    const groups = groupByAnnotation(Object.values(categories.others));
+    lines.push('<details>');
+    lines.push(`<summary><h2>Others (${Object.keys(categories.others).length})</h2></summary>`);
+    lines.push('');
+    lines.push(...formatAnnotationGroups(groups, formatOther));
+    lines.push('</details>');
+    lines.push('');
+  }
+
+  // External References
+  if (externalReferences && Object.keys(externalReferences).length > 0) {
+    const totalSymbols = Object.values(externalReferences).reduce(
+      (sum, extPkg) => sum + Object.keys(extPkg.symbols).length,
+      0,
+    );
+
+    lines.push('<details>');
+    lines.push(
+      `<summary><h2>External References (${totalSymbols} symbols from ${
+        Object.keys(externalReferences).length
+      } packages)</h2></summary>`,
+    );
+    lines.push('');
+
+    for (const [pkgSpec, pkgRef] of Object.entries(externalReferences).sort(([a], [b]) => a.localeCompare(b))) {
+      lines.push(`### \`${pkgSpec}\``);
+      lines.push('');
+      lines.push(`*metadata:* \`${pkgRef.metadataRef}\``);
+      lines.push('');
+      lines.push('| Symbol | Reference |');
+      lines.push('| ------ | --------- |');
+      for (const [name, ref] of Object.entries(pkgRef.symbols).sort(([a], [b]) => a.localeCompare(b))) {
+        const refDisplay = '$ref' in ref ? `\`${ref.$ref}\`` : `\`${ref.inline}\``;
+        lines.push(`| \`${name}\` | ${refDisplay} |`);
+      }
+      lines.push('');
+    }
+
+    lines.push('</details>');
+    lines.push('');
+  }
+
+  return lines.join('\n');
+}
+
+// ---------------------------------------------------------------------------
+// Section formatters
+// ---------------------------------------------------------------------------
+
+/**
+ * Render annotation sub-groups within a category.
+ * When there's only one group (all stable), no sub-heading is emitted.
+ */
+function formatAnnotationGroups<T extends BaseSymbolDoc>(
+  groups: AnnotationGroup<T>[],
+  renderItem: (item: T) => string[],
+): string[] {
+  if (groups.length === 1 && groups[0].key === 'stable') {
+    return groups[0].items.flatMap(renderItem);
+  }
+
+  const lines: string[] = [];
+  for (const g of groups) {
+    lines.push(`#### ${g.label} (${g.items.length})`);
+    lines.push('');
+    for (const item of g.items) {
+      lines.push(...renderItem(item));
+    }
+  }
+  return lines;
+}
+
+function formatComponent(comp: ComponentDoc): string[] {
+  const lines: string[] = [];
+  lines.push(`### \`${comp.name}\``);
+  lines.push('');
+  if (comp.description) {
+    lines.push(comp.description);
+    lines.push('');
+  }
+  lines.push(`**Type:** \`${comp.typeSignature}\``);
+  if (comp.propsType) {
+    lines.push(`**Props:** ${formatRef(comp.propsType)}`);
+  }
+  lines.push(...formatTags(comp.tags));
+  lines.push('');
+  return lines;
+}
+
+function formatHook(hook: HookDoc): string[] {
+  const lines: string[] = [];
+  lines.push(`### \`${hook.name}\``);
+  lines.push('');
+  if (hook.description) {
+    lines.push(hook.description);
+    lines.push('');
+  }
+  lines.push(`**Signature:** \`${hook.typeSignature}\``);
+  if (hook.parameters.length > 0) {
+    lines.push('');
+    lines.push(...formatParametersTable(hook.parameters));
+  }
+  lines.push(`**Returns:** \`${hook.returnType}\``);
+  lines.push(...formatTags(hook.tags));
+  lines.push('');
+  return lines;
+}
+
+function formatType(type: TypeDoc): string[] {
+  const lines: string[] = [];
+  lines.push(`### \`${type.name}\` *(${type.kind})*`);
+  lines.push('');
+  if (type.description) {
+    lines.push(type.description);
+    lines.push('');
+  }
+  lines.push(`**Type:** \`${type.typeSignature}\``);
+  lines.push(...formatTags(type.tags));
+
+  const memberList = Object.values(type.members);
+  if (memberList.length > 0) {
+    lines.push('');
+    lines.push(...formatMembersTable(memberList));
+  }
+  lines.push('');
+  return lines;
+}
+
+function formatOther(other: OtherDoc): string[] {
+  const lines: string[] = [];
+  lines.push(`### \`${other.name}\` *(${other.kind})*`);
+  lines.push('');
+  if (other.description) {
+    lines.push(other.description);
+    lines.push('');
+  }
+  lines.push(`**Type:** \`${other.typeSignature}\``);
+  if (other.parameters && other.parameters.length > 0) {
+    lines.push('');
+    lines.push(...formatParametersTable(other.parameters));
+  }
+  if (other.returnType) {
+    lines.push(`**Returns:** \`${other.returnType}\``);
+  }
+  lines.push(...formatTags(other.tags));
+  lines.push('');
+  return lines;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function formatParametersTable(params: ParameterDoc[], title: string = 'Arguments'): string[] {
+  const lines: string[] = [];
+  lines.push(`**${title}:**`);
+  lines.push('');
+  lines.push('| Name | Type | Required | Description |');
+  lines.push('| ---- | ---- | -------- | ----------- |');
+  for (const p of params) {
+    lines.push(`| \`${p.name}\` | \`${p.type}\` | ${p.required ? 'Yes' : 'No'} | ${p.description} |`);
+  }
+  lines.push('');
+  return lines;
+}
+
+function formatMembersTable(members: MemberDoc[]): string[] {
+  const lines: string[] = [];
+  lines.push('**Members:**');
+  lines.push('');
+  lines.push('| Name | Type | Required | Default | Description |');
+  lines.push('| ---- | ---- | -------- | ------- | ----------- |');
+  for (const m of members) {
+    lines.push(
+      `| \`${m.name}\` | \`${m.type}\` | ${m.required ? 'Yes' : 'No'} | ${
+        m.defaultValue ? `\`${m.defaultValue}\`` : '—'
+      } | ${m.description} |`,
+    );
+  }
+  lines.push('');
+  return lines;
+}
+
+function formatTags(tags: Record<string, string>): string[] {
+  const entries = Object.entries(tags);
+  if (entries.length === 0) {
+    return [];
+  }
+  return ['', ...entries.map(([key, val]) => `> @${key}${val ? ` ${val}` : ''}`)];
+}
+
+/**
+ * Format a $ref or inline type for Markdown.
+ * Local refs become anchor links; cross-package refs are shown as code.
+ */
+function formatRef(ref: RefOrInline): string {
+  if ('inline' in ref) {
+    return `\`${ref.inline}\``;
+  }
+
+  const refValue = ref.$ref;
+  // Local ref: #/categories/<category>/<symbolName> → link to heading anchor
+  if (refValue.startsWith('#/')) {
+    const symbolName = refValue.split('/').pop()!;
+    // GitHub-style heading anchor: lowercase, spaces→hyphens
+    const anchor = symbolName.toLowerCase().replace(/[^a-z0-9_-]/g, '-');
+    return `[\`${symbolName}\`](#${anchor})`;
+  }
+
+  // Cross-package ref
+  const hashIdx = refValue.indexOf('#/');
+  if (hashIdx > 0) {
+    const pkgName = refValue.substring(0, hashIdx);
+    const symbolName = refValue.split('/').pop()!;
+    return `\`${pkgName}\` → \`${symbolName}\``;
+  }
+
+  return `\`${refValue}\``;
+}
diff --git a/tools/cli/src/commands/metadata/impl/types.ts b/tools/cli/src/commands/metadata/impl/types.ts
new file mode 100644
index 0000000000000..eb8fca9a98cbc
--- /dev/null
+++ b/tools/cli/src/commands/metadata/impl/types.ts
@@ -0,0 +1,143 @@
+// ============================================================================
+// Metadata command types
+// ============================================================================
+
+/**
+ * Parsed CLI arguments for the `metadata` command.
+ */
+export interface MetadataArgs {
+  /** Path to the .d.ts entry file. When omitted, resolved from package.json "types" field. */
+  entry?: string;
+  /** Output format. Defaults to 'json'. */
+  reporter?: 'json' | 'markdown' | 'html';
+  /** Output file path. Defaults to stdout. */
+  output?: string;
+}
+
+// ============================================================================
+// Metadata output schema
+// ============================================================================
+
+/**
+ * Root metadata output structure written as JSON.
+ */
+export interface MetadataOutput {
+  /** Package identity. */
+  package: PackageInfo;
+  /** Describes each category used in the output. */
+  legend: Record<string, CategoryLegendEntry>;
+  /** Categorised API symbols. */
+  categories: {
+    components: Record<string, ComponentDoc>;
+    hooks: Record<string, HookDoc>;
+    types: Record<string, TypeDoc>;
+    others: Record<string, OtherDoc>;
+  };
+  /** External symbols referenced in this package's public API, grouped by source package. */
+  externalReferences?: Record<string, ExternalPackageRef>;
+}
+
+export interface PackageInfo {
+  name: string;
+  version: string;
+}
+
+/** References to external symbols from a single dependency package. */
+export interface ExternalPackageRef {
+  /** Logical path to the dependency's metadata file (e.g. `@fluentui/react-utilities/metadata.json`). */
+  metadataRef: string;
+  /** Map of symbol name → $ref pointer or inline type fallback. */
+  symbols: Record<string, RefOrInline>;
+}
+
+export interface CategoryLegendEntry {
+  name: string;
+  description: string;
+}
+
+// ============================================================================
+// Symbol documentation types
+// ============================================================================
+
+/** Base fields shared by every documented symbol. */
+export interface BaseSymbolDoc {
+  /** Export name as it appears in the .d.ts. */
+  name: string;
+  /** JSDoc description (first line / summary). */
+  description: string;
+  /** Full type signature text. */
+  typeSignature: string;
+  /** JSDoc tags extracted from the declaration (e.g. internal, deprecated). */
+  tags: Record<string, string>;
+}
+
+/** A React component export. */
+export interface ComponentDoc extends BaseSymbolDoc {
+  /** Reference to the props type, e.g. `{ "$ref": "#/categories/types/ButtonProps" }`. */
+  propsType?: RefOrInline;
+}
+
+/** A React hook export. */
+export interface HookDoc extends BaseSymbolDoc {
+  parameters: ParameterDoc[];
+  returnType: string;
+}
+
+/** A type alias, interface, or enum export. */
+export interface TypeDoc extends BaseSymbolDoc {
+  /** 'interface' | 'type-alias' | 'enum'. */
+  kind: TypeKind;
+  /** Resolved members for interfaces / type aliases with object shapes. */
+  members: Record<string, MemberDoc>;
+}
+
+/** Any other export (constants, render functions, utility functions). */
+export interface OtherDoc extends BaseSymbolDoc {
+  /** 'variable' | 'function' | 'class' | 'unknown'. */
+  kind: OtherKind;
+  /** Function parameters (when kind is 'function'). */
+  parameters?: ParameterDoc[];
+  /** Function return type (when kind is 'function'). */
+  returnType?: string;
+}
+
+// ============================================================================
+// Supporting types
+// ============================================================================
+
+export type TypeKind = 'interface' | 'type-alias' | 'enum';
+export type OtherKind = 'variable' | 'function' | 'class' | 'unknown';
+
+/** A function or hook parameter. */
+export interface ParameterDoc {
+  name: string;
+  type: string;
+  required: boolean;
+  description: string;
+}
+
+/** A member of an interface or type alias. */
+export interface MemberDoc {
+  name: string;
+  type: string;
+  required: boolean;
+  description: string;
+  /** Extracted from @default JSDoc tag. */
+  defaultValue?: string;
+}
+
+/**
+ * Either a JSON `$ref` pointer or an inline type string.
+ * When the referenced package has metadata.json, `$ref` is used.
+ * Otherwise `inline` contains the raw type signature.
+ */
+export type RefOrInline = { $ref: string } | { inline: string };
+
+// ============================================================================
+// Classification
+// ============================================================================
+
+/**
+ * Classification of an exported symbol.
+ */
+export type SymbolClassification = 'component' | 'hook' | 'type' | 'other';
diff --git a/tools/cli/src/commands/metadata/index.ts b/tools/cli/src/commands/metadata/index.ts
new file mode 100644
index 0000000000000..d8bab26d3db03
--- /dev/null
+++ b/tools/cli/src/commands/metadata/index.ts
@@ -0,0 +1,35 @@
+import type { CommandModule } from 'yargs';
+
+import type { MetadataArgs } from './impl/types';
+
+const command: CommandModule<{}, MetadataArgs> = {
+  command: 'metadata',
+  describe: 'Extract API metadata from package .d.ts build output',
+  builder: yargs =>
+    yargs
+      .option('entry', {
+        alias: 'e',
+        type: 'string',
+        describe: 'Path to index.d.ts entry file (default: resolved from package.json "types" field)',
+      })
+      .option('reporter', {
+        alias: 'r',
+        type: 'string',
+        choices: ['json', 'markdown', 'html'] as const,
+        default: 'json' as const,
+        describe: 'Output format',
+      })
+      .option('output', {
+        alias: 'o',
+        type: 'string',
+        describe: 'Output file path (default: stdout)',
+      })
+      .version(false)
+      .help(),
+  handler: async argv => {
+    const { handler } = await import('./handler');
+    return handler(argv);
+  },
+};
+
+export default command;

From b4afd69901b36dd91857a28ff5bac574142af26c Mon Sep 17 00:00:00 2001
From: Martin Hochel <martinhochel@microsoft.com>
Date: Tue, 7 Apr 2026 17:15:01 +0200
Subject: [PATCH 10/14] feat(cli): add skill instalation hint/detection to
 migrate cmd (#35957)

---
 skills/README.md                              |  57 ++++
 tools/cli/src/commands/migrate/README.md      | 272 ++++++++++++++++++
 .../v8-to-v9/__tests__/handler.spec.ts        |  37 +++
 .../v8-to-v9/__tests__/skill-check.spec.ts    |  55 ++++
 .../src/commands/migrate/v8-to-v9/handler.ts  |   9 +
 .../migrate/v8-to-v9/utils/skill-check.ts     |  26 ++
 6 files changed, 456 insertions(+)
 create mode 100644 skills/README.md
 create mode 100644 tools/cli/src/commands/migrate/README.md
 create mode 100644 tools/cli/src/commands/migrate/v8-to-v9/__tests__/skill-check.spec.ts
 create mode 100644 tools/cli/src/commands/migrate/v8-to-v9/utils/skill-check.ts

diff --git a/skills/README.md b/skills/README.md
new file mode 100644
index 0000000000000..0311b024e2f72
--- /dev/null
+++ b/skills/README.md
@@ -0,0 +1,57 @@
+# Fluent UI Agent Skills
+
+This directory contains [agent skills](https://agentskills.io) — reusable instruction sets that extend AI coding agents with Fluent UI-specific capabilities. Skills are installed into your project (or globally) and automatically loaded by supported agents.
+
+## Available skills
+
+| Skill                                                               | Description                                                                                                                    |
+| ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| [`fluentui-migrate-v8-to-v9`](./fluentui-migrate-v8-to-v9/SKILL.md) | Guides AI agents through migrating a codebase from Fluent UI React v8 (`@fluentui/react`) to v9 (`@fluentui/react-components`) |
+
+## Installation
+
+Skills are installed via the [`npx skills`](https://github.com/vercel-labs/skills) CLI, which supports 40+ coding agents including Claude Code, GitHub Copilot, Cursor, Codex, and more.
+
+### Install the migration skill
+
+```bash
+# Interactive — choose which agents and skills to install
+npx skills add microsoft/fluentui
+
+# Install a specific skill
+npx skills add microsoft/fluentui --skill fluentui-migrate-v8-to-v9
+
+# Install to a specific agent
+npx skills add microsoft/fluentui --skill fluentui-migrate-v8-to-v9 -a claude-code
+
+# Install globally (available across all projects)
+npx skills add microsoft/fluentui --skill fluentui-migrate-v8-to-v9 -g
+```
+
+### List available skills
+
+```bash
+npx skills add microsoft/fluentui --list
+```
+
+## Managing installed skills
+
+```bash
+# List installed skills
+npx skills list
+
+# Check for updates
+npx skills check
+
+# Update to latest
+npx skills update
+
+# Remove a skill
+npx skills remove fluentui-migrate-v8-to-v9
+```
+
+## Further reading
+
+- [Agent Skills specification](https://agentskills.io)
+- [Skills directory](https://skills.sh)
+- [`@fluentui/cli` migrate command](../tools/cli/src/commands/migrate/README.md)
diff --git a/tools/cli/src/commands/migrate/README.md b/tools/cli/src/commands/migrate/README.md
new file mode 100644
index 0000000000000..e798a57aa3941
--- /dev/null
+++ b/tools/cli/src/commands/migrate/README.md
@@ -0,0 +1,272 @@
+# `migrate` command
+
+The `migrate` command performs static analysis on a codebase and inserts structured migration annotations into source files. These annotations serve as a deterministic work queue for human developers or AI agents to execute the actual migration.
+
+## Usage
+
+```bash
+fluentui migrate [migration] [--list]
+```
+
+| Flag     | Alias | Description                   |
+| -------- | ----- | ----------------------------- |
+| `--list` | `-l`  | List all available migrations |
+
+### `migrate v8-to-v9`
+
+Analyzes a directory for Fluent UI v8 (`@fluentui/react`) usage and annotates each migration site with the appropriate action and target.
+
+```bash
+fluentui migrate v8-to-v9 --path <dir> [--dryRun]
+```
+
+| Flag       | Default | Description                                   |
+| ---------- | ------- | --------------------------------------------- |
+| `--path`   | —       | **Required.** Source root to analyze          |
+| `--dryRun` | `false` | Preview annotations without writing any files |
+
+> **Note**: The package must have a `package.json` reachable from `--path` so the analyzer can determine which v9 dependencies are already installed.
+
+## Two-phase migration model
+
+The command implements **phase 1** of a two-phase migration:
+
+1. **Annotate** (this command) — statically detects v8 usage, classifies each finding, and inserts `@fluent-migrate:` comments into source files.
+2. **Execute** (human or AI agent) — consumes annotations as a work queue, applies changes in priority order, removes comments after each fix, and validates the result.
+
+The companion skill at `skills/fluentui-migrate-v8-to-v9/SKILL.md` defines the agent workflow for phase 2.
+
+### Installing the migration skill
+
+After running annotations, install the companion AI agent skill to guide phase 2:
+
+```bash
+npx skills add microsoft/fluentui --skill fluentui-migrate-v8-to-v9
+```
+
+The CLI automatically checks whether the skill is installed and prints this hint when it is missing. See [`skills/README.md`](../../../../../skills/README.md) for full installation options and the supported agent list.
+
+## Annotation format
+
+Annotations are inserted as comments directly above the detected usage site:
+
+```ts
+// @fluent-migrate:<action> | <codemod> | <payload> | <note>
+```
+
+Inside JSX children, block comments are used instead:
+
+```tsx
+{
+  /* @fluent-migrate:<action> | <codemod> | <payload> | <note> */
+}
+```
+
+### Actions
+
+| Action          | Meaning                                                           |
+| --------------- | ----------------------------------------------------------------- |
+| `auto`          | Safe to apply mechanically — a 1:1 rename or straightforward swap |
+| `scaffold`      | Boilerplate structure needed — e.g. wrapping in `<Field>`         |
+| `manual`        | Requires human judgment — multiple valid approaches exist         |
+| `no-equivalent` | No v9 replacement — requires a custom solution or removal         |
+
+## Rules
+
+The analyzer applies a set of rules to each source file. A rule detects a specific v8 pattern and emits one or more annotations.
+
+### `import-paths`
+
+Rewrites `@fluentui/react` imports to their v9 targets.
+
+- Standard specifiers → `auto` to `@fluentui/react-components`
+- Compat components (`Calendar`, `DatePicker`, `TimePicker`) → `manual` to their compat packages
+- Deprecated components with no equivalent → `no-equivalent`
+- Side-effect imports → `auto`
+
+### `component-rename`
+
+Maps v8 component names to their v9 equivalents. Covers three tiers:
+
+- **Auto 1:1 renames** — `Separator→Divider`, `Toggle→Switch`, `Shimmer→Skeleton`, `Fabric→FluentProvider`, `Layer→Portal`, `ProgressIndicator→ProgressBar`, `ChoiceGroup→RadioGroup`, and others
+- **Structural renames** (`manual`) — `Panel→OverlayDrawer`, `Callout→Popover`, `ContextualMenu→Menu`, `Pivot→TabList`, `Modal→Dialog`, and others requiring API restructuring
+- **No equivalent** — handled by the `no-equivalent` rule instead
+
+### `button-variants`
+
+Maps v8 button types to v9 `Button` with the appropriate `appearance`:
+
+| v8               | v9                                                  | Action |
+| ---------------- | --------------------------------------------------- | ------ |
+| `PrimaryButton`  | `Button appearance="primary"`                       | `auto` |
+| `DefaultButton`  | `Button`                                            | `auto` |
+| `ActionButton`   | `Button appearance="transparent"`                   | `auto` |
+| `IconButton`     | `Button` (icon-only, ensure `aria-label`)           | `auto` |
+| `CompoundButton` | `CompoundButton` (`secondaryText→secondaryContent`) | `auto` |
+
+### `prop-rename`
+
+Renames props mechanically:
+
+| v8 prop           | v9 prop            |
+| ----------------- | ------------------ |
+| `ariaLabel`       | `aria-label`       |
+| `ariaHidden`      | `aria-hidden`      |
+| `ariaDescribedBy` | `aria-describedby` |
+| `ariaLabelledBy`  | `aria-labelledby`  |
+| `componentRef`    | `ref`              |
+
+### `icon-props`
+
+Converts `iconProps={{ iconName: 'X' }}` to `icon={<XRegular />}`.
+
+- Known icon names → `auto` (requires `@fluentui/react-icons`)
+- Unknown or dynamic icon names → `manual`
+
+### `dialog-props`
+
+Maps `Dialog`/`Modal` props:
+
+- `hidden` → `open={!expr}` (`auto`)
+- `isOpen` → `open` (`auto`)
+- `onDismiss` → `onOpenChange` (`auto`)
+- `isBlocking` → `modalType="alert"` (`auto`)
+- `dialogContentProps` → `DialogTitle + DialogBody` structure (`scaffold`)
+
+### `enum-to-string`
+
+Replaces v8 enum members with v9 string literals for `MessageBarType`, `SpinnerSize`, `DialogType`, and `CheckboxVisibility`.
+
+### `toggle-props`
+
+Maps `Toggle`-specific props: `inlineLabel→labelPosition`, `onChange` signature rewrite, and marks `onText`/`offText` as `no-equivalent`.
+
+### `progress-bar-props`
+
+Maps `ProgressIndicator` props: `percentComplete→value`, `label→Field wrapper`.
+
+### `label-extraction`
+
+For components whose `label` prop moves to a `<Field>` wrapper (`TextField`, `SpinButton`, `Slider`, `ChoiceGroup`, `Spinner`, `ProgressIndicator`):
+
+- `label` → `scaffold` (wrap in `<Field label="...">`)
+- `onRenderLabel` → `manual`
+
+### `styles-prop`
+
+Detects any `styles` prop on Fluent components and emits `scaffold` — suggests replacing with `makeStyles` and design tokens.
+
+### `remove-theme-prop`
+
+Detects `theme` prop usage and emits `auto`. Adds a note about nested `FluentProvider` if the value is non-trivial.
+
+### `use-boolean`
+
+Detects `useBoolean` from v8 and suggests replacing with `useState`. Emits `auto` inside function components, `manual` otherwise.
+
+### `keycodes`
+
+Detects `KeyCodes` enum usage and maps known members to `event.key` string values (e.g. `KeyCodes.enter→'Enter'`). Unknown members are `manual`.
+
+### `get-id`
+
+Detects `getId` from v8 and suggests replacing with `useId` from v9. Emits `auto` inside function components, `manual` otherwise.
+
+### `no-equivalent`
+
+Flags deprecated components with no v9 replacement: `ActivityItem`, `MarqueeSelection`, `HoverCard`, `ResizeGroup`, `ScrollablePane`, `Announced`, `Stack`, `StackItem`. Each annotation includes a recommended alternative in the note.
+
+## Output
+
+### Summary (write mode)
+
+After annotating, the command prints:
+
+```
+Annotated 12 files
+  auto             34  (safe to apply mechanically)
+  scaffold          8  (boilerplate needed)
+  manual            5  (requires judgment)
+  no-equivalent     2  (no v9 replacement)
+
+Required packages (not in package.json):
+  @fluentui/react-components          — v9 component library
+  @fluentui/react-icons               — icon replacements
+```
+
+### Dry-run mode
+
+With `--dryRun`, no files are modified. The command prints the same counts plus a list of files that would be annotated.
+
+### Metadata file
+
+After writing annotations, the command creates `.fluent-migrate/metadata.json` in the project root:
+
+```json
+{
+  "version": 1,
+  "annotatedFiles": ["src/App.tsx", "src/components/Header.tsx"]
+}
+```
+
+This file is consumed by the migration skill as the deterministic work queue.
+
+## Architecture
+
+```
+migrate/
+├── index.ts                          # Parent command — registers subcommands, --list flag
+├── v8-to-v9/
+│   ├── index.ts                      # Yargs subcommand definition (--path, --dryRun)
+│   ├── handler.ts                    # Orchestrates analyze → write → summary
+│   ├── utils/annotator/
+│   │   ├── index.ts                  # Public API (analyzeFiles, writeAnnotations)
+│   │   ├── types.ts                  # AnnotationAction, Annotation, FileAnalysis types
+│   │   ├── analyzer.ts              # File discovery, ts-morph parsing, rule execution
+│   │   ├── writer.ts                # Comment insertion, idempotency, metadata.json output
+│   │   └── rules/
+│   │       ├── utils.ts             # Shared helpers (getFluentImportNames, isJsxChild)
+│   │       ├── import-paths.ts
+│   │       ├── component-rename.ts
+│   │       ├── button-variants.ts
+│   │       ├── prop-rename.ts
+│   │       ├── icon-props.ts
+│   │       ├── dialog-props.ts
+│   │       ├── enum-to-string.ts
+│   │       ├── toggle-props.ts
+│   │       ├── progress-bar-props.ts
+│   │       ├── label-extraction.ts
+│   │       ├── styles-prop.ts
+│   │       ├── remove-theme-prop.ts
+│   │       ├── use-boolean.ts
+│   │       ├── keycodes.ts
+│   │       ├── get-id.ts
+│   │       └── no-equivalent.ts
+│   └── __tests__/
+│       ├── handler.spec.ts           # Unit tests (mocked analyzer/writer)
+│       ├── handler.integration.spec.ts # Integration tests (real files + temp dirs)
+│       └── fixtures/                 # Sample .tsx files exercising each rule
+└── README.md                         # This file
+```
+
+### How it works
+
+1. **Package detection** — walks up from `--path` to find the nearest `package.json` and reads installed dependencies
+2. **File discovery** — scans `**/*.ts` and `**/*.tsx` under `--path`, skipping `node_modules` and `.d.ts` files
+3. **Import extraction** — uses ts-morph to find all names imported from `@fluentui/react`
+4. **Rule execution** — each rule inspects the AST for specific v8 patterns and emits typed annotations with line numbers
+5. **Annotation writing** — inserts comments above each target node, preserving indentation and handling JSX context; sorts annotations by line descending to avoid offset drift
+6. **Idempotency** — re-running the command on already-annotated files skips duplicate annotations
+7. **Metadata output** — writes `.fluent-migrate/metadata.json` listing all annotated files
+
+## Testing
+
+```bash
+# Run all migrate tests
+yarn nx run cli:test -- --testPathPatterns=migrate
+
+# Run full CLI test suite
+yarn nx run cli:test
+```
+
+Tests use a fixture-based approach with sample `.tsx` files in `__tests__/fixtures/` covering each rule. Integration tests create temporary directories, run the real analyzer and writer, and verify annotation content, idempotency, indentation, and metadata output.
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 532cd6086e6c1..a91b5b548504e 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,13 +1,17 @@
 import { handler } from '../handler';
 import * as annotator from '../utils/annotator';
+import * as skillCheck from '../utils/skill-check';
 import * as fs from 'fs/promises';
 
 jest.mock('../utils/annotator');
+jest.mock('../utils/skill-check');
 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>;
+const mockIsSkillInstalled = skillCheck.isSkillInstalled as jest.MockedFunction<typeof skillCheck.isSkillInstalled>;
+const mockPrintSkillHint = skillCheck.printSkillHint as jest.MockedFunction<typeof skillCheck.printSkillHint>;
 
 describe('migrate v8-to-v9 handler', () => {
   let logSpy: jest.SpyInstance;
@@ -17,6 +21,8 @@ describe('migrate v8-to-v9 handler', () => {
     logSpy = jest.spyOn(console, 'log').mockImplementation();
     // Default: path exists and is a directory
     mockStat.mockResolvedValue({ isDirectory: () => true } as Awaited<ReturnType<typeof fs.stat>>);
+    // Default: skill is installed (suppress hint)
+    mockIsSkillInstalled.mockReturnValue(true);
   });
 
   afterEach(() => {
@@ -98,4 +104,35 @@ describe('migrate v8-to-v9 handler', () => {
 
     expect(mockAnalyzeFiles).not.toHaveBeenCalled();
   });
+
+  it('prints skill install hint when skill is not found', async () => {
+    mockAnalyzeFiles.mockResolvedValue([]);
+    mockWriteAnnotations.mockResolvedValue({ filesChanged: 0 });
+    mockIsSkillInstalled.mockReturnValue(false);
+
+    await handler({ path: 'src/', dryRun: false, _: [], $0: 'fluentui-cli' });
+
+    expect(mockIsSkillInstalled).toHaveBeenCalled();
+    expect(mockPrintSkillHint).toHaveBeenCalled();
+  });
+
+  it('does not print skill hint when skill is already installed', async () => {
+    mockAnalyzeFiles.mockResolvedValue([]);
+    mockWriteAnnotations.mockResolvedValue({ filesChanged: 0 });
+    mockIsSkillInstalled.mockReturnValue(true);
+
+    await handler({ path: 'src/', dryRun: false, _: [], $0: 'fluentui-cli' });
+
+    expect(mockPrintSkillHint).not.toHaveBeenCalled();
+  });
+
+  it('prints skill install hint in dryRun mode when skill is not found', async () => {
+    mockAnalyzeFiles.mockResolvedValue([]);
+    mockIsSkillInstalled.mockReturnValue(false);
+
+    await handler({ path: 'src/', dryRun: true, _: [], $0: 'fluentui-cli' });
+
+    expect(mockPrintSkillHint).toHaveBeenCalled();
+    expect(mockWriteAnnotations).not.toHaveBeenCalled();
+  });
 });
diff --git a/tools/cli/src/commands/migrate/v8-to-v9/__tests__/skill-check.spec.ts b/tools/cli/src/commands/migrate/v8-to-v9/__tests__/skill-check.spec.ts
new file mode 100644
index 0000000000000..5c578756036b9
--- /dev/null
+++ b/tools/cli/src/commands/migrate/v8-to-v9/__tests__/skill-check.spec.ts
@@ -0,0 +1,55 @@
+import { execFileSync } from 'child_process';
+import { isSkillInstalled, printSkillHint } from '../utils/skill-check';
+
+jest.mock('child_process');
+
+const mockExecFileSync = execFileSync as jest.MockedFunction<typeof execFileSync>;
+
+describe('skill-check', () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+  });
+
+  describe('isSkillInstalled', () => {
+    it('returns true when skills list output contains the skill name', () => {
+      mockExecFileSync.mockReturnValue(
+        'Project Skills\n\nfluentui-migrate-v8-to-v9 ~/project/skills/fluentui-migrate-v8-to-v9\n  Agents: Claude Code\n',
+      );
+
+      expect(isSkillInstalled()).toBe(true);
+    });
+
+    it('returns false when skills list output does not contain the skill name', () => {
+      mockExecFileSync.mockReturnValue('No project skills found.\nTry listing global skills with -g\n');
+
+      expect(isSkillInstalled()).toBe(false);
+    });
+
+    it('returns false when npx skills command fails', () => {
+      mockExecFileSync.mockImplementation(() => {
+        throw new Error('command not found');
+      });
+
+      expect(isSkillInstalled()).toBe(false);
+    });
+  });
+
+  describe('printSkillHint', () => {
+    let logSpy: jest.SpyInstance;
+
+    beforeEach(() => {
+      logSpy = jest.spyOn(console, 'log').mockImplementation();
+    });
+
+    afterEach(() => {
+      logSpy.mockRestore();
+    });
+
+    it('prints npx skills add command', () => {
+      printSkillHint();
+
+      const output = logSpy.mock.calls.map((args: unknown[]) => args[0]).join('\n');
+      expect(output).toContain('npx skills add microsoft/fluentui --skill fluentui-migrate-v8-to-v9');
+    });
+  });
+});
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 9fcd93e802df7..a565846e03005 100644
--- a/tools/cli/src/commands/migrate/v8-to-v9/handler.ts
+++ b/tools/cli/src/commands/migrate/v8-to-v9/handler.ts
@@ -2,6 +2,7 @@ import * as fs from 'fs/promises';
 import type { CommandHandler } from '../../../utils/types';
 import { analyzeFiles, writeAnnotations } from './utils/annotator';
 import type { FileAnalysis } from './utils/annotator';
+import { isSkillInstalled, printSkillHint } from './utils/skill-check';
 
 interface V8ToV9Args {
   path: string;
@@ -24,11 +25,13 @@ export const handler: CommandHandler<V8ToV9Args> = async argv => {
 
   if (argv.dryRun) {
     printDryRunReport(results);
+    printSkillHintIfNeeded();
     return;
   }
 
   const { filesChanged } = await writeAnnotations(results, argv.path);
   printSummary(results, filesChanged);
+  printSkillHintIfNeeded();
 };
 
 function countByAction(results: FileAnalysis[]) {
@@ -106,3 +109,9 @@ function printDryRunReport(results: FileAnalysis[]): void {
     }
   }
 }
+
+function printSkillHintIfNeeded(): void {
+  if (!isSkillInstalled()) {
+    printSkillHint();
+  }
+}
diff --git a/tools/cli/src/commands/migrate/v8-to-v9/utils/skill-check.ts b/tools/cli/src/commands/migrate/v8-to-v9/utils/skill-check.ts
new file mode 100644
index 0000000000000..a909bd6b828da
--- /dev/null
+++ b/tools/cli/src/commands/migrate/v8-to-v9/utils/skill-check.ts
@@ -0,0 +1,26 @@
+import { execFileSync } from 'child_process';
+
+const SKILL_NAME = 'fluentui-migrate-v8-to-v9';
+
+/**
+ * Check whether the `fluentui-migrate-v8-to-v9` skill is installed
+ * by delegating to `npx skills list`.
+ */
+export function isSkillInstalled(): boolean {
+  try {
+    const output = execFileSync('npx', ['--no-install', 'skills', 'list'], {
+      timeout: 15_000,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    return output.includes(SKILL_NAME);
+  } catch {
+    return false;
+  }
+}
+
+export function printSkillHint(): void {
+  console.log('\nNext step — install the migration skill for your coding agent:');
+  console.log('  npx skills add microsoft/fluentui --skill fluentui-migrate-v8-to-v9');
+  console.log('\nThe skill guides AI agents through the annotation-driven migration process.');
+}

From f43f5e2315bb7bec26d31fc0725c9a135010b95e Mon Sep 17 00:00:00 2001
From: Martin Hochel <martinhochel@microsoft.com>
Date: Wed, 8 Apr 2026 12:31:42 +0200
Subject: [PATCH 11/14] feat(cli): expand binary alias so npx @fluentui/cli
 works by default and prepare for initial release (#35958)

---
 ...-1d82ac6b-1cef-4156-892b-832d275398da.json |  7 +++
 tools/cli/README.md                           | 61 +++++++++++++++++--
 tools/cli/package.json                        |  4 +-
 3 files changed, 64 insertions(+), 8 deletions(-)
 create mode 100644 change/@fluentui-cli-1d82ac6b-1cef-4156-892b-832d275398da.json

diff --git a/change/@fluentui-cli-1d82ac6b-1cef-4156-892b-832d275398da.json b/change/@fluentui-cli-1d82ac6b-1cef-4156-892b-832d275398da.json
new file mode 100644
index 0000000000000..c16d1efd738bd
--- /dev/null
+++ b/change/@fluentui-cli-1d82ac6b-1cef-4156-892b-832d275398da.json
@@ -0,0 +1,7 @@
+{
+  "type": "patch",
+  "comment": "initial release",
+  "packageName": "@fluentui/cli",
+  "email": "martinhochel@microsoft.com",
+  "dependentChangeType": "patch"
+}
diff --git a/tools/cli/README.md b/tools/cli/README.md
index f7abc84a489a8..29faef280fa36 100644
--- a/tools/cli/README.md
+++ b/tools/cli/README.md
@@ -1,11 +1,60 @@
-# cli
+# @fluentui/cli
 
-This library was generated with [Nx](https://nx.dev).
+Command-line tool for Fluent UI — migration analysis, usage reporting, and API metadata extraction.
 
-## Building
+> **⚠️ Experimental** — This package is published under the `experimental` npm tag. APIs and commands may change without notice.
 
-Run `nx build cli` to build the library.
+## Usage
 
-## Running unit tests
+```sh
+npx @fluentui/cli@experimental <command> [options]
+```
 
-Run `nx test cli` to execute the unit tests via [Jest](https://jestjs.io).
+> Run any command with `--help` for detailed options.
+
+## Commands
+
+### `migrate`
+
+Run migration analysis and annotation.
+
+```sh
+# List available migrations
+npx @fluentui/cli migrate --list
+
+# Analyze v8 → v9 migration (dry run)
+npx @fluentui/cli migrate v8-to-v9 --path src/ --dryRun
+
+# Annotate source files with migration hints
+npx @fluentui/cli migrate v8-to-v9 --path src/
+```
+
+### `report`
+
+Generate reports for issue filing or codebase analysis.
+
+```sh
+# Quick environment/package summary for issue reporting
+npx @fluentui/cli report info
+
+# Deep codebase usage analysis of Fluent UI APIs
+npx @fluentui/cli report usage --path ./src --reporter markdown --output report.md
+```
+
+### `metadata`
+
+Extract API metadata from package `.d.ts` build output.
+
+```sh
+npx @fluentui/cli metadata --entry dist/index.d.ts --reporter json
+```
+
+## Development
+
+```sh
+# Build
+yarn nx run cli:build
+
+# Test
+yarn nx run cli:test
+```
diff --git a/tools/cli/package.json b/tools/cli/package.json
index 3dee465b40571..de51e6bdf5b3b 100644
--- a/tools/cli/package.json
+++ b/tools/cli/package.json
@@ -1,12 +1,12 @@
 {
   "name": "@fluentui/cli",
   "version": "0.0.1",
-  "private": true,
   "type": "commonjs",
   "main": "./src/index.js",
   "types": "./src/index.d.ts",
   "bin": {
-    "fluentui-cli": "./bin/fluentui-cli.js"
+    "fluentui-cli": "./bin/fluentui-cli.js",
+    "cli": "./bin/fluentui-cli.js"
   },
   "files": [
     "*.md",

From 0db9dd943a5b7c3a6ca0cabcd42c8b36498bf39c Mon Sep 17 00:00:00 2001
From: Martin Hochel <martinhochel@microsoft.com>
Date: Wed, 8 Apr 2026 19:46:55 +0200
Subject: [PATCH 12/14] test(cli): mock skill-check in integration tests to
 prevent CI timeout (#35964)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 .../v8-to-v9/__tests__/handler.integration.spec.ts       | 9 +++++++++
 1 file changed, 9 insertions(+)

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 77bb122631860..14105269b3367 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
@@ -5,6 +5,15 @@ import { analyzeFiles } from '../utils/annotator';
 import { writeAnnotations } from '../utils/annotator';
 import { handler } from '../handler';
 
+// Mock the skill-check module to avoid spawning `npx` in every handler test.
+// The `isSkillInstalled` function calls `execFileSync('npx', …)` which takes ~3s
+// per invocation and causes CI timeouts on slower runners.
+// skill-check logic is independently covered by skill-check.spec.ts.
+jest.mock('../utils/skill-check', () => ({
+  isSkillInstalled: jest.fn().mockReturnValue(true),
+  printSkillHint: jest.fn(),
+}));
+
 const FIXTURES_DIR = path.join(__dirname, 'fixtures');
 
 async function mkTmpDir(): Promise<string> {

From ee684e7d965f4beba874f83a9b946b46aa8894a2 Mon Sep 17 00:00:00 2001
From: Martin Hochel <martinhochel@microsoft.com>
Date: Mon, 14 Sep 2026 17:56:27 +0200
Subject: [PATCH 13/14] chore(cli): normalize package bin order

---
 tools/cli/package.json | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/tools/cli/package.json b/tools/cli/package.json
index de51e6bdf5b3b..539cf8db40baa 100644
--- a/tools/cli/package.json
+++ b/tools/cli/package.json
@@ -5,8 +5,8 @@
   "main": "./src/index.js",
   "types": "./src/index.d.ts",
   "bin": {
-    "fluentui-cli": "./bin/fluentui-cli.js",
-    "cli": "./bin/fluentui-cli.js"
+    "cli": "./bin/fluentui-cli.js",
+    "fluentui-cli": "./bin/fluentui-cli.js"
   },
   "files": [
     "*.md",

From 928ba32ba5afd986661d3d99f0afaf105a281848 Mon Sep 17 00:00:00 2001
From: Martin Hochel <martinhochel@microsoft.com>
Date: Mon, 14 Sep 2026 18:41:49 +0200
Subject: [PATCH 14/14] chore(cli): remove experimental migration tooling

---
 .github/skills/fluentui-cli/SKILL.md          |  26 +-
 .../verify-v8-v9-migration-docs/SKILL.md      | 403 -----------
 docs/plans/fluent-cli.md                      | 472 ++----------
 skills/README.md                              |  57 --
 skills/fluentui-migrate-v8-to-v9/SKILL.md     | 683 ------------------
 .../references/avatargroup.md                 |  92 ---
 .../references/breadcrumb.md                  |  96 ---
 .../references/button.md                      | 217 ------
 .../references/callout.md                     | 171 -----
 .../references/card.md                        |  83 ---
 .../references/charts.md                      |  49 --
 .../references/checkbox.md                    | 114 ---
 .../references/colorpicker.md                 |  63 --
 .../references/datagrid.md                    | 238 ------
 .../references/dialog.md                      | 215 ------
 .../references/drawer.md                      | 159 ----
 .../references/dropdown.md                    | 246 -------
 .../references/icons.md                       | 114 ---
 .../references/image.md                       |  71 --
 .../references/input.md                       | 135 ----
 .../references/keytips.md                     |  80 --
 .../references/label.md                       |  45 --
 .../references/link.md                        |  85 ---
 .../references/list.md                        |  96 ---
 .../references/menu.md                        | 146 ----
 .../references/messagebar.md                  | 137 ----
 .../references/nav.md                         | 116 ---
 .../references/overflow.md                    | 121 ----
 .../references/persona.md                     |  85 ---
 .../references/progressbar.md                 | 104 ---
 .../references/radiogroup.md                  | 144 ----
 .../references/rating.md                      |  92 ---
 .../references/searchbox.md                   |  72 --
 .../references/separator.md                   |  48 --
 .../references/skeleton.md                    |  80 --
 .../references/slider.md                      | 134 ----
 .../references/spinbutton.md                  | 137 ----
 .../references/spinner.md                     |  71 --
 .../references/stack.md                       | 153 ----
 .../references/swatchpicker.md                | 105 ---
 .../references/switch.md                      |  53 --
 .../references/tabs.md                        | 105 ---
 .../references/tagpicker.md                   | 107 ---
 .../references/teachingpopover.md             | 121 ----
 .../references/text.md                        |  86 ---
 .../references/textarea.md                    |  59 --
 .../references/theme.md                       | 230 ------
 .../references/toolbar.md                     | 263 -------
 .../references/tooltip.md                     | 132 ----
 .../references/tree.md                        | 101 ---
 tools/cli/README.md                           |  17 +-
 tools/cli/eslint.config.cjs                   |   2 +-
 tools/cli/src/cli.ts                          |   2 -
 tools/cli/src/commands/migrate/README.md      | 272 -------
 tools/cli/src/commands/migrate/index.ts       |  29 -
 .../__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     | 355 ---------
 .../v8-to-v9/__tests__/handler.spec.ts        | 138 ----
 .../v8-to-v9/__tests__/skill-check.spec.ts    |  55 --
 .../src/commands/migrate/v8-to-v9/handler.ts  | 117 ---
 .../src/commands/migrate/v8-to-v9/index.ts    |  31 -
 .../v8-to-v9/utils/annotator/analyzer.ts      | 135 ----
 .../migrate/v8-to-v9/utils/annotator/index.ts |   3 -
 .../utils/annotator/rules/button-variants.ts  |  59 --
 .../utils/annotator/rules/component-rename.ts | 238 ------
 .../utils/annotator/rules/dialog-props.ts     |  62 --
 .../utils/annotator/rules/enum-to-string.ts   |  70 --
 .../v8-to-v9/utils/annotator/rules/get-id.ts  |  45 --
 .../utils/annotator/rules/icon-props.ts       | 199 -----
 .../utils/annotator/rules/import-paths.ts     |  74 --
 .../utils/annotator/rules/keycodes.ts         |  74 --
 .../utils/annotator/rules/label-extraction.ts |  54 --
 .../utils/annotator/rules/no-equivalent.ts    |  44 --
 .../annotator/rules/progress-bar-props.ts     |  40 -
 .../utils/annotator/rules/prop-rename.ts      |  42 --
 .../annotator/rules/remove-theme-prop.ts      |  41 --
 .../utils/annotator/rules/styles-prop.ts      |  35 -
 .../utils/annotator/rules/toggle-props.ts     |  54 --
 .../utils/annotator/rules/use-boolean.ts      |  66 --
 .../v8-to-v9/utils/annotator/rules/utils.ts   |  36 -
 .../migrate/v8-to-v9/utils/annotator/types.ts |  27 -
 .../v8-to-v9/utils/annotator/writer.ts        | 110 ---
 .../migrate/v8-to-v9/utils/skill-check.ts     |  26 -
 93 files changed, 94 insertions(+), 9532 deletions(-)
 delete mode 100644 .github/skills/verify-v8-v9-migration-docs/SKILL.md
 delete mode 100644 skills/README.md
 delete mode 100644 skills/fluentui-migrate-v8-to-v9/SKILL.md
 delete mode 100644 skills/fluentui-migrate-v8-to-v9/references/avatargroup.md
 delete mode 100644 skills/fluentui-migrate-v8-to-v9/references/breadcrumb.md
 delete mode 100644 skills/fluentui-migrate-v8-to-v9/references/button.md
 delete mode 100644 skills/fluentui-migrate-v8-to-v9/references/callout.md
 delete mode 100644 skills/fluentui-migrate-v8-to-v9/references/card.md
 delete mode 100644 skills/fluentui-migrate-v8-to-v9/references/charts.md
 delete mode 100644 skills/fluentui-migrate-v8-to-v9/references/checkbox.md
 delete mode 100644 skills/fluentui-migrate-v8-to-v9/references/colorpicker.md
 delete mode 100644 skills/fluentui-migrate-v8-to-v9/references/datagrid.md
 delete mode 100644 skills/fluentui-migrate-v8-to-v9/references/dialog.md
 delete mode 100644 skills/fluentui-migrate-v8-to-v9/references/drawer.md
 delete mode 100644 skills/fluentui-migrate-v8-to-v9/references/dropdown.md
 delete mode 100644 skills/fluentui-migrate-v8-to-v9/references/icons.md
 delete mode 100644 skills/fluentui-migrate-v8-to-v9/references/image.md
 delete mode 100644 skills/fluentui-migrate-v8-to-v9/references/input.md
 delete mode 100644 skills/fluentui-migrate-v8-to-v9/references/keytips.md
 delete mode 100644 skills/fluentui-migrate-v8-to-v9/references/label.md
 delete mode 100644 skills/fluentui-migrate-v8-to-v9/references/link.md
 delete mode 100644 skills/fluentui-migrate-v8-to-v9/references/list.md
 delete mode 100644 skills/fluentui-migrate-v8-to-v9/references/menu.md
 delete mode 100644 skills/fluentui-migrate-v8-to-v9/references/messagebar.md
 delete mode 100644 skills/fluentui-migrate-v8-to-v9/references/nav.md
 delete mode 100644 skills/fluentui-migrate-v8-to-v9/references/overflow.md
 delete mode 100644 skills/fluentui-migrate-v8-to-v9/references/persona.md
 delete mode 100644 skills/fluentui-migrate-v8-to-v9/references/progressbar.md
 delete mode 100644 skills/fluentui-migrate-v8-to-v9/references/radiogroup.md
 delete mode 100644 skills/fluentui-migrate-v8-to-v9/references/rating.md
 delete mode 100644 skills/fluentui-migrate-v8-to-v9/references/searchbox.md
 delete mode 100644 skills/fluentui-migrate-v8-to-v9/references/separator.md
 delete mode 100644 skills/fluentui-migrate-v8-to-v9/references/skeleton.md
 delete mode 100644 skills/fluentui-migrate-v8-to-v9/references/slider.md
 delete mode 100644 skills/fluentui-migrate-v8-to-v9/references/spinbutton.md
 delete mode 100644 skills/fluentui-migrate-v8-to-v9/references/spinner.md
 delete mode 100644 skills/fluentui-migrate-v8-to-v9/references/stack.md
 delete mode 100644 skills/fluentui-migrate-v8-to-v9/references/swatchpicker.md
 delete mode 100644 skills/fluentui-migrate-v8-to-v9/references/switch.md
 delete mode 100644 skills/fluentui-migrate-v8-to-v9/references/tabs.md
 delete mode 100644 skills/fluentui-migrate-v8-to-v9/references/tagpicker.md
 delete mode 100644 skills/fluentui-migrate-v8-to-v9/references/teachingpopover.md
 delete mode 100644 skills/fluentui-migrate-v8-to-v9/references/text.md
 delete mode 100644 skills/fluentui-migrate-v8-to-v9/references/textarea.md
 delete mode 100644 skills/fluentui-migrate-v8-to-v9/references/theme.md
 delete mode 100644 skills/fluentui-migrate-v8-to-v9/references/toolbar.md
 delete mode 100644 skills/fluentui-migrate-v8-to-v9/references/tooltip.md
 delete mode 100644 skills/fluentui-migrate-v8-to-v9/references/tree.md
 delete mode 100644 tools/cli/src/commands/migrate/README.md
 delete mode 100644 tools/cli/src/commands/migrate/index.ts
 delete mode 100644 tools/cli/src/commands/migrate/v8-to-v9/__tests__/fixtures/button-variants.tsx
 delete mode 100644 tools/cli/src/commands/migrate/v8-to-v9/__tests__/fixtures/icon-known.tsx
 delete mode 100644 tools/cli/src/commands/migrate/v8-to-v9/__tests__/fixtures/icon-unknown.tsx
 delete mode 100644 tools/cli/src/commands/migrate/v8-to-v9/__tests__/fixtures/import-paths.tsx
 delete mode 100644 tools/cli/src/commands/migrate/v8-to-v9/__tests__/fixtures/indented.tsx
 delete mode 100644 tools/cli/src/commands/migrate/v8-to-v9/__tests__/fixtures/multi-annotation.tsx
 delete mode 100644 tools/cli/src/commands/migrate/v8-to-v9/__tests__/fixtures/multi-import.tsx
 delete mode 100644 tools/cli/src/commands/migrate/v8-to-v9/__tests__/fixtures/no-equivalent.tsx
 delete mode 100644 tools/cli/src/commands/migrate/v8-to-v9/__tests__/fixtures/prop-rename.tsx
 delete mode 100644 tools/cli/src/commands/migrate/v8-to-v9/__tests__/fixtures/styles-prop.tsx
 delete mode 100644 tools/cli/src/commands/migrate/v8-to-v9/__tests__/fixtures/unrelated.tsx
 delete mode 100644 tools/cli/src/commands/migrate/v8-to-v9/__tests__/handler.integration.spec.ts
 delete mode 100644 tools/cli/src/commands/migrate/v8-to-v9/__tests__/handler.spec.ts
 delete mode 100644 tools/cli/src/commands/migrate/v8-to-v9/__tests__/skill-check.spec.ts
 delete mode 100644 tools/cli/src/commands/migrate/v8-to-v9/handler.ts
 delete mode 100644 tools/cli/src/commands/migrate/v8-to-v9/index.ts
 delete mode 100644 tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/analyzer.ts
 delete mode 100644 tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/index.ts
 delete mode 100644 tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/button-variants.ts
 delete mode 100644 tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/component-rename.ts
 delete mode 100644 tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/dialog-props.ts
 delete mode 100644 tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/enum-to-string.ts
 delete mode 100644 tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/get-id.ts
 delete mode 100644 tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/icon-props.ts
 delete mode 100644 tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/import-paths.ts
 delete mode 100644 tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/keycodes.ts
 delete mode 100644 tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/label-extraction.ts
 delete mode 100644 tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/no-equivalent.ts
 delete mode 100644 tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/progress-bar-props.ts
 delete mode 100644 tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/prop-rename.ts
 delete mode 100644 tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/remove-theme-prop.ts
 delete mode 100644 tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/styles-prop.ts
 delete mode 100644 tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/toggle-props.ts
 delete mode 100644 tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/use-boolean.ts
 delete mode 100644 tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/utils.ts
 delete mode 100644 tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/types.ts
 delete mode 100644 tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/writer.ts
 delete mode 100644 tools/cli/src/commands/migrate/v8-to-v9/utils/skill-check.ts

diff --git a/.github/skills/fluentui-cli/SKILL.md b/.github/skills/fluentui-cli/SKILL.md
index a5e52373e8976..2d26ca3571926 100644
--- a/.github/skills/fluentui-cli/SKILL.md
+++ b/.github/skills/fluentui-cli/SKILL.md
@@ -21,14 +21,14 @@ tools/cli/
 │   │   ├── index.ts                 # Barrel exports
 │   │   └── types.ts                 # Shared CommandHandler type
 │   └── commands/
-│       ├── migrate/                 # Command module
-│       │   ├── index.ts             # CommandModule definition (eagerly loaded)
-│       │   ├── handler.ts           # Handler implementation (lazy-loaded)
-│       │   └── handler.spec.ts      # Tests
-│       └── report/                  # Command module
-│           ├── index.ts
-│           ├── handler.ts
-│           └── handler.spec.ts
+│       ├── metadata/                # API metadata command
+│       │   ├── index.ts             # CommandModule definition
+│       │   ├── handler.ts           # Lazy-loaded handler
+│       │   └── impl/                # Parsing and formatting
+│       └── report/                  # Reporting command group
+│           ├── index.ts             # Registers report subcommands
+│           ├── commands/            # info and usage definitions
+│           └── impl/                # Lazy-loaded report implementations
 ```
 
 ### Lazy Loading Pattern
@@ -44,7 +44,7 @@ handler: async argv => {
 },
 ```
 
-This means running `fluentui-cli migrate` will never load the code for `report` or any other command.
+This keeps command implementations out of the startup path until the selected command runs.
 
 ### CommandHandler Type
 
@@ -62,15 +62,15 @@ Each command is imported and registered in `tools/cli/src/cli.ts`:
 
 ```typescript
 import yargs from 'yargs';
-import migrateCommand from './commands/migrate';
 import reportCommand from './commands/report';
+import metadataCommand from './commands/metadata';
 
 export async function main(argv: string[]): Promise<void> {
   await yargs(argv)
     .scriptName('fluentui-cli')
     .usage('$0 <command> [options]')
-    .command(migrateCommand)
     .command(reportCommand)
+    .command(metadataCommand)
     .demandCommand(1, 'You need to specify a command to run.')
     .help()
     .strict()
@@ -109,8 +109,8 @@ If a command needs subcommands, use yargs nested command pattern in the builder:
 ```typescript
 builder: yargs =>
   yargs
-    .command('run', 'Run migrations', subBuilder => subBuilder, subHandler)
-    .command('list', 'List available migrations', subBuilder => subBuilder, subHandler)
+    .command('summary', 'Generate a summary', subBuilder => subBuilder, summaryHandler)
+    .command('details', 'Generate detailed output', subBuilder => subBuilder, detailsHandler)
     .demandCommand(1)
     .help(),
 ```
diff --git a/.github/skills/verify-v8-v9-migration-docs/SKILL.md b/.github/skills/verify-v8-v9-migration-docs/SKILL.md
deleted file mode 100644
index 52ceed33ae31b..0000000000000
--- a/.github/skills/verify-v8-v9-migration-docs/SKILL.md
+++ /dev/null
@@ -1,403 +0,0 @@
----
-name: verify-v8-v9-migration-docs
-description: >-
-  Generate, audit, and verify Fluent UI v8-to-v9 component migration guides.
-  Use when asked to inventory v8 components, inspect their v8 and v9 source,
-  produce missing per-component documentation, prove the guides are accurate
-  or exhaustive with sealed migrations, classify documentation gaps versus
-  agent mistakes, or publish a verification matrix.
----
-
-# Generate and verify v8-to-v9 migration documentation
-
-Build and prove the documentation in three stages:
-
-1. Inventory every public v8 component and determine its v9 destination.
-2. Inspect authoritative v8 and v9 source, then create or correct the
-   per-component migration guide.
-3. Give a migration agent only one v8 microcase and its relevant guide, then
-   evaluate the generated v9 code against a hidden source-derived checklist.
-
-Keep manifests, generated migrations, evaluation ledgers, and runner artifacts
-outside the Fluent UI checkout. Only documentation and skill corrections belong
-in the documentation pull request.
-
-## Completion standard
-
-Do not describe the documentation as exhaustive until:
-
-- every public v8 component has a reviewed migration disposition;
-- every supported mapping has a guide, or a deliberate umbrella-guide entry;
-- generated guides are indexed and structurally consistent;
-- every component guide has exactly one focused scenario;
-- every focused run launches, builds, lints, and passes the isolation audit;
-- every documentation-attributable finding has been corrected and rerun;
-- the final ledger has zero `DOC_GAP`;
-- structural documentation tests and `git diff --check` pass;
-- existing multi-component scenarios still provide integration coverage.
-
-An `AGENT_MISS` does not by itself make a guide incomplete. Report it
-transparently, but change the guide only when its instruction is missing,
-incorrect, or materially ambiguous.
-
-## 1. Establish scope
-
-Identify:
-
-- the documentation checkout and pull-request branch;
-- the directory containing the v8-to-v9 component guides;
-- authoritative v8 and v9 implementation and type sources;
-- the standard v9 application template used for generated code;
-- existing multi-component migration scenarios;
-- the targeted guide test command;
-- the fork remote and pull request.
-
-Enumerate guide paths dynamically. Compare the mapping or index document with
-the guide files on disk, and fail on missing, duplicate, or unindexed guides.
-The first complete verification used 53 focused guides and 14 integration
-scenarios, but do not hardcode those counts after the guide set changes.
-
-Record the initial worktree status. Never use broad restore or checkout
-commands while an audit contains intentional uncommitted corrections.
-
-## 2. Inventory v8 components and map destinations
-
-Build a coverage ledger from public exports, not from the existing guide list.
-The ledger must contain one row per public v8 component with:
-
-- v8 component and package/import path;
-- v8 source, type, style, test, and story locations;
-- v9 replacement component or composition;
-- destination package and import path;
-- mapping kind;
-- guide path;
-- evidence and review status.
-
-Use these mapping kinds:
-
-| Kind            | Meaning                                                                        |
-| --------------- | ------------------------------------------------------------------------------ |
-| `direct`        | The component and core behavior have a v9 replacement.                         |
-| `renamed`       | The destination component has a different name.                                |
-| `decomposed`    | One v8 component becomes several v9 primitives.                                |
-| `composed`      | Product-owned composition is required to preserve behavior.                    |
-| `compat`        | The supported destination is a v9 compatibility package.                       |
-| `shim`          | A migration shim is intentionally recommended as an intermediate step.         |
-| `no-equivalent` | V9 has no supported equivalent; document alternatives and limitations.         |
-| `umbrella`      | The component is fully covered by another guide; record that guide explicitly. |
-
-Do not silently omit deprecated, specialized, or package-specific components.
-Give each one a disposition, even when the result is `no-equivalent` or
-`umbrella`. Keep internal implementation helpers out of the public inventory.
-
-Cross-check the ledger against:
-
-- v8 package barrel exports and component directories;
-- existing component mapping/index documents;
-- v9 root exports, subpackages, compat packages, and migration shims;
-- all migration guide files.
-
-Fail coverage validation on duplicate components, missing dispositions, broken
-guide paths, or guides that have no inventory row.
-
-## 3. Research each v8/v9 component pair
-
-For the v8 side, inspect:
-
-- public prop and enum types;
-- default values in base/state hooks and tests;
-- callback argument shapes and controlled-state behavior;
-- rendered markup, roles, focus zones, keyboard handlers, and announcements;
-- style functions, size tables, breakpoints, and visual-state defaults;
-- stories and tests that demonstrate supported behavior;
-- imperative refs and helper utilities.
-
-For the v9 side, inspect:
-
-- the actual exported package and component API;
-- slot structure and declarative composition;
-- default props, state hooks, event-data types, and controlled patterns;
-- keyboard, Tabster, focus restoration, positioning, and dismissal contracts;
-- ARIA behavior and native element semantics;
-- design-token, `makeStyles`, size, layout, and responsive behavior;
-- compat or shim behavior and known limitations;
-- stories and tests for the proposed replacement.
-
-Trace behavior to implementation source when types or stories are ambiguous.
-Do not infer defaults from naming, and do not treat an existing migration guide
-as authoritative evidence for itself.
-
-For every v8 prop or behavior, record one outcome:
-
-- direct prop or slot mapping;
-- renamed value or callback-data mapping;
-- changed default that must be set explicitly;
-- manual composition with enough implementation guidance;
-- unsupported behavior with a clear limitation;
-- intentionally dropped behavior with rationale.
-
-## 4. Produce or update the documentation
-
-Create a guide for every uncovered supported mapping. Update an existing guide
-when research proves it incomplete or inconsistent. If multiple v8 components
-belong in one umbrella guide, make every covered component discoverable from
-the mapping index and from the guide itself.
-
-Follow the neighboring FromV8 MDX structure exactly. A complete guide normally
-contains:
-
-1. Storybook `Meta`, component migration title, and the standard title divider.
-2. A concise destination decision, including the exact v9 package.
-3. Import and composition changes.
-4. A self-contained v8 example and behavior-equivalent v9 example.
-5. A prop, enum, callback, and slot mapping table.
-6. Changed defaults and behavioral differences.
-7. Controlled/uncontrolled state and event-data guidance.
-8. Accessibility, keyboard, focus, and dismissal guidance.
-9. Styling, sizing, tokens, layout, and responsive differences.
-10. Removed features, manual replacements, compat/shim limits, and
-    no-equivalent cases.
-
-The guide must be actionable without dependency source access. Include enough
-per-component instruction for an isolated agent to implement the migration,
-but do not paste entire source files or duplicate generic v9 documentation.
-
-Examples must:
-
-- use valid public imports;
-- compile as TSX after normal surrounding declarations are supplied;
-- preserve v8 observable behavior, not merely render a similar component;
-- use `(event, data)` callback values when required by v9;
-- preserve accessible naming, descriptions, roles, and focus behavior;
-- distinguish source-faithful behavior from a documented product decision.
-
-Update the component mapping/index and structural regression tests whenever a
-new guide or umbrella mapping is added. Structural tests should detect missing
-titles or dividers, duplicate registrations, broken paths, malformed fences,
-and invalid TSX snippets.
-
-## 5. Source-audit every guide
-
-For each guide, verify claims against source rather than other prose:
-
-- v8 prop defaults and callback signatures;
-- v9 replacement components, packages, props, and callback data;
-- controlled and uncontrolled state behavior;
-- keyboard, focus, dismissal, and selection behavior;
-- accessible names, descriptions, roles, and announcements;
-- sizing, truncation, overflow, layout, and visual defaults;
-- removed behavior that requires application-owned composition;
-- shim and compatibility-package limitations;
-- valid imports and compilable TSX examples.
-
-Correct factual errors before running a focused scenario when source already
-proves them. Keep style homogeneous with neighboring migration guides:
-
-- use consistent headings, dividers, terminology, tables, and code fences;
-- distinguish exact mappings, approximations, and manual composition;
-- do not present semantic presets as pixel-exact aliases;
-- state important omitted-prop defaults explicitly.
-
-## 6. Create one reviewed scenario per guide
-
-Author scenarios deliberately; do not extract code fences automatically when a
-guide interleaves v8 and v9 examples.
-
-Use this logical manifest schema:
-
-```json
-{
-  "id": "component-example",
-  "guide_path": "Example.mdx",
-  "title": "Focused v8 behavior under test",
-  "source": "Complete self-contained v8 TSX",
-  "requirements": ["Hidden source-grounded behavior or accessibility requirement"]
-}
-```
-
-Each source must:
-
-- be a complete v8 function component with a default export;
-- use only React and legitimate v8-era Fluent packages;
-- include local data and state instead of product dependencies;
-- exercise the riskiest documented defaults or behavioral mappings;
-- contain no v9 implementation or hidden answer.
-
-Each hidden requirement must be observable from the source or established by
-an authoritative v8 default. Cover behavior, API mapping, accessibility, and
-visual semantics where relevant.
-
-Validate before running:
-
-- entry count equals guide count;
-- IDs and guide paths are unique;
-- every guide path exists;
-- manifest and guide inventories have no missing or extra paths;
-- every source has a default export and no destination imports;
-- every checklist is non-empty.
-
-## 7. Prepare destination dependencies
-
-Start from a normal v9 application template and its installed dependencies.
-Add every destination package referenced by the guides, including compat,
-charting, color-picker, migration-shim, and contrib packages.
-
-Generated builds may resolve installed packages, but the migration agent must
-not inspect dependency source or type declarations. Validate the untouched
-template with its existing build and lint commands before launching agents.
-
-## 8. Seal each migration workspace
-
-Create a fresh workspace per scenario containing only:
-
-- the v9 template, excluding generated output;
-- a reference to installed dependencies;
-- `INPUT.md` with the source-only v8 microcase;
-- `GUIDE.mdx` with exactly the target guide;
-- a placeholder `src/<scenario-id>/index.tsx`;
-- a short isolation notice.
-
-Do not expose:
-
-- hidden requirements, expected output, or ground truth;
-- benchmark specifications;
-- other guides or mapping documents;
-- repository history or previous iterations;
-- network access or MCP servers;
-- external filesystem paths;
-- dependency source or type declarations;
-- subagents, ambient skills, or configuration discovery.
-
-Allow read, search, and edit tools inside the workspace plus the existing build
-and lint commands. Permit compilers to resolve dependencies without granting
-the agent direct reads of `node_modules`.
-
-Require the agent to read `INPUT.md` and `GUIDE.mdx`, preserve observable v8
-behavior, edit only the target file, migrate to the documented v9 destination,
-and finish only after build and lint pass.
-
-Capture a trajectory log. Reject runs that use a non-allowlisted tool, cross
-the workspace boundary, read dependencies directly, or receive hidden
-evaluation material.
-
-## 9. Run focused and integration matrices
-
-Run focused scenarios in bounded parallel batches. Keep every iteration in a
-new output directory so corrective runs remain auditable.
-
-Record for each scenario:
-
-- launcher, build, and lint exit codes;
-- tools used and permission rejections;
-- isolation eligibility;
-- generated source path.
-
-Retain multi-component scenarios as an integration layer. Focused scenarios
-prove one guide at a time; integration scenarios prove that mappings compose
-in realistic workflows.
-
-## 10. Hidden-evaluate source fidelity
-
-The migration agent must never see this step's requirements.
-
-For every checklist item, inspect generated source for:
-
-- destination imports and component mappings;
-- state and callback-data handling;
-- keyboard and focus logic;
-- dismissal, selection, overflow, and virtualization behavior;
-- accessibility semantics and labeling;
-- sizing, layout, and visual defaults represented by the source.
-
-Classify each finding exactly:
-
-| Classification  | Meaning                                                  | Action                               |
-| --------------- | -------------------------------------------------------- | ------------------------------------ |
-| `DOC_GAP`       | The guide is missing, wrong, or materially ambiguous.    | Correct the guide and rerun.         |
-| `AGENT_MISS`    | The guide clearly covered behavior that the code missed. | Record it; optionally rerun cleanly. |
-| `VALID_VARIANT` | The code differs but is source-equivalent.               | Count as a pass.                     |
-| `ORACLE_DEFECT` | The checklist conflicts with authoritative source.       | Correct the scenario, not the guide. |
-
-Judge from source unless runtime inspection is explicitly part of the oracle.
-Do not turn every generated-code defect into more documentation; overfitting a
-guide to one agent output makes it noisy and less authoritative.
-
-## 11. Correct and rerun narrowly
-
-For every `DOC_GAP`:
-
-1. Reconfirm behavior in authoritative source.
-2. Make the smallest complete guide correction.
-3. Run structural guide tests.
-4. Launch a clean workspace for only the affected scenario.
-5. Rebuild, relint, and repeat hidden evaluation.
-6. Continue until the rerun has no `DOC_GAP`.
-
-If a rerun produces an `AGENT_MISS`, verify that the guide is explicit before
-keeping the classification. Preserve all iterations in the ledger.
-
-## 12. Perform a senior review
-
-After the matrix reaches zero documentation gaps, review the complete diff
-against source and neighboring guide style. Look specifically for:
-
-- examples whose visible result works but accessibility semantics do not;
-- invalid HTML composition hidden by permissive component types;
-- focus restoration omitted from externally controlled overlays;
-- responsive defaults presented as legacy fixed defaults;
-- examples that preserve data but lose grouping or widget semantics;
-- virtualizer wrapper and ref contracts;
-- exact values hidden behind semantic-size approximations.
-
-Fix high-confidence findings and rerun the affected focused scenarios.
-
-## 13. Publish evidence
-
-Before committing:
-
-- rerun the targeted structural suite;
-- run `git diff --check`;
-- confirm only intended guide and skill files changed;
-- confirm the latest ledger has zero `DOC_GAP`;
-- obtain a final senior review with no unresolved high-confidence findings.
-
-Push only to the pull request's fork and branch. Never force-push unless
-explicitly authorized.
-
-The pull-request comment must include:
-
-- isolation contract;
-- focused launcher, build, lint, and isolation counts;
-- exact or valid-variant count;
-- remaining `AGENT_MISS` descriptions;
-- zero remaining `DOC_GAP` and `ORACLE_DEFECT`, when true;
-- corrected findings and rerun outcomes;
-- structural test result;
-- focused plus integration totals;
-- commit SHA;
-- one row per guide.
-
-Do not claim every generated migration matched ground truth when agent misses
-remain. The defensible conclusion is that the documentation has zero remaining
-documentation-attributable defects under the verified scenarios.
-
-## Expected artifacts
-
-Keep an auditable external structure such as:
-
-```text
-migration-verification/
-  component-coverage-ledger.csv
-  focused-component-scenarios.json
-  runs/
-    iteration-1/scenarios/<id>/
-    iteration-2/scenarios/<id>/
-  evaluations/
-    iteration-1/*.json
-    iteration-2/*.json
-  summary.md
-  pr-comment.md
-```
-
-Preserve earlier iterations so reviewers can see which defects were found,
-what changed, and whether the corrective rerun removed them.
diff --git a/docs/plans/fluent-cli.md b/docs/plans/fluent-cli.md
index 6daf71ef2396d..103eea40e7b30 100644
--- a/docs/plans/fluent-cli.md
+++ b/docs/plans/fluent-cli.md
@@ -1,439 +1,125 @@
-# Fluent UI v9 Agentic Migration — Project Spec
+# Fluent UI CLI Project Spec
 
-## 1) Objective
+## Objective
 
-Build an **agentic migration solution** for Fluent UI React v9 that consists of exactly two products:
+`@fluentui/cli` provides focused diagnostics for Fluent UI maintainers and consumers. It exposes two command surfaces:
 
-1. **Agent Skills** — deterministic instructions/workflows AI coding agents can follow for complex migrations.
-2. **CLI** — executable migration engine that performs Nx-style migrations and AST transformations.
+1. `report` generates environment, package, and source-usage reports.
+2. `metadata` extracts structured API metadata from TypeScript declaration output.
 
-The skills are the **primary source of migration logic and sequencing**; the CLI is a **supportive execution utility** for codemods, reporting, and deterministic automation steps.
+The package is published under the `experimental` npm tag while these contracts evolve.
 
----
+## Scope
 
-## 2) Problem Statement
+### Included
 
-Current migrations (v8 → v9 and v9 minor upgrades) are inconsistent and largely manual:
+- Environment and installed-package summaries for issue reports.
+- Static analysis of Fluent UI imports and component usage.
+- API metadata extraction from package `.d.ts` entry points.
+- JSON, Markdown, and HTML output where supported.
+- File output or standard output for scripting and local inspection.
 
-- no official migration skill system that encodes migration strategy,
-- no stable bridge between agent workflow decisions and codemod execution,
-- no repeatable agent workflows tied to deterministic transform tooling.
+### Excluded
 
-Result: high migration cost, inconsistent outcomes, and low confidence for large codebases.
+- Source-code transformations.
+- Automated source edits.
+- Interactive or graphical interfaces.
+- Runtime component behavior.
 
----
+## Architecture
 
-## 3) Scope
+The CLI is a Node.js library under `tools/cli/`, built with Nx and SWC. Yargs owns argument parsing, help output, strict command validation, and subcommand routing.
 
-### In scope (MVP)
+Command definitions are lightweight and registered in `src/cli.ts`. Implementations are loaded with dynamic `import()` only after yargs selects a command. Shared command types live in `src/utils/`.
 
-- Define and version **agent skills** for v8 → v9 migration.
-- Publish a CLI package (`@fluentui/cli`) as a support tool with:
-  - codemod execution (`migrate`) for skill-selected steps,
-  - AST-based transforms (jscodeshift initially),
-  - migration diagnostics/reporting (`report`),
-  - dry-run support and machine-readable output for agents.
-- Ensure skills invoke CLI only for deterministic/mechanical edits and analysis.
-- Implement and ship the two required MVP codemods: `deprecated-packages`, `deprecated-props`.
-
-### Out of scope (MVP)
-
-- Full auto-migration for every v8 component.
-- IDE plugin UI.
-- New runtime shim framework.
-- Cross-framework migrations beyond React/TS.
-- Migration recommendation hints in `report` output (Phase 2).
-
----
-
-## 4) Success Criteria
-
-- Agent can execute end-to-end migration workflow on a sample app with no custom prompts.
-- Skills own migration planning decisions; CLI only executes requested codemods reliably.
-- CLI provides deterministic output (`dry-run` + applied mode) and idempotent transforms.
-- For MVP migrations, at least 80% of targeted mechanical edits are automated.
-- Type-check/test failure count after migration is lower than baseline manual approach.
-
----
-
-## 5) Architecture
-
-### 5.1 Agent Skills Layer
-
-Skills are the migration control plane and contain:
-
-- decision trees (when to run which migration),
-- sequencing rules (report → dry-run → apply → verify),
-- stop conditions (unsafe diff size, parser failures, unresolved imports),
-- escalation rules (manual review checkpoints).
-
-Skills select migration steps, call CLI commands, and evaluate outcomes before proceeding.
-
-### 5.2 CLI Layer
-
-CLI is an execution/data plane and contains:
-
-- transform runner,
-- reporting/analysis commands,
-- structured result output for agent consumption.
-
-Primary transform engine for MVP: **jscodeshift** (TS/TSX parser defaults). CLI does not own migration strategy.
-
----
-
-## 6) CLI Spec
-
-CLI command behavior is intentionally minimal and execution-focused; migration strategy remains in skills.
+```text
+tools/cli/
+├── bin/fluentui-cli.js
+├── src/
+│   ├── cli.ts
+│   ├── index.ts
+│   ├── commands/
+│   │   ├── metadata/
+│   │   │   ├── index.ts
+│   │   │   ├── handler.ts
+│   │   │   └── impl/
+│   │   └── report/
+│   │       ├── index.ts
+│   │       ├── commands/
+│   │       └── impl/
+│   └── utils/
+├── package.json
+└── project.json
+```
 
-### 6.1 Commands
+## Commands
 
-#### `migrate`
+### `report info`
 
-Run codemods selected by skills (from `migrations.json` or by migration name).
+Produces a compact environment and Fluent UI package summary suitable for issue reports.
 
 ```sh
-npx @fluentui/cli migrate [migration-name] [path] [options]
-
-# Registry-driven run (Nx-style):
-npx @fluentui/cli migrate --run-migrations=migrations.json src/
-
-# Direct migration run:
-npx @fluentui/cli migrate deprecated-packages src/
-
-# Semver-filtered run (typically skill-driven):
-npx @fluentui/cli migrate src/ --from 8 --to 9
+npx @fluentui/cli@experimental report info [--output <file>]
 ```
 
 Options:
 
-- `--run-migrations <path>` — registry file path
-- `--from <semver>` — lower bound
-- `--to <semver>` — upper bound
-- `-d, --dry-run` — preview without writing
-- `-l, --list` — list known migrations
-- `--cpus <n>` — worker count
-- `--parser <tsx|ts|babel|babel-ts>` — default: `tsx`
-- `--json` — emit machine-readable result summary to stdout
+- `-o, --output <file>` writes the report to a file instead of standard output.
 
-#### `report`
+### `report usage`
 
-Produce diagnostics data for agents to decide migration steps. Writes structured JSON to a file by default (output can be large).
+Analyzes TypeScript and TSX sources for Fluent UI imports, components, hooks, and API usage.
 
 ```sh
-npx @fluentui/cli report [path] [options]
+npx @fluentui/cli@experimental report usage [options]
 ```
 
 Options:
 
-- `--output <file>` — default: `./fluent-report.json`
-- `--print` — print compact summary to stdout instead of writing file
-- `--json` — emit full JSON to stdout (for agent piping)
-
-Output sections:
+- `-p, --path <directory>` selects the traversal root; the git root is used by default.
+- `-r, --reporter <json|markdown|html>` selects the output format; JSON is the default.
+- `--include <glob...>` limits analysis to matching files.
+- `--exclude <glob...>` excludes matching files.
+- `-o, --output <file>` writes the report to a file instead of standard output.
 
-1. **Environment** — Node, OS, npm versions (always included).
-2. **Installed packages** — all `@fluentui/*` and `@fluentui-contrib/*` versions (always included).
-3. **Usage inventory** — imports + JSX props per component across scanned path (only when `[path]` is provided).
+### `metadata`
 
-Terminal summary always printed after file write:
+Parses a package declaration entry point and emits structured API metadata.
 
 ```sh
-Report written to fluent-report.json
-
-Node: 22.21.1  |  OS: darwin-arm64  |  npm: 10.9.4
-Installed:  @fluentui/react-components@9.73.1  @fluentui/react@8.125.5  (+1 more)
-Usage:      312 usages across 14 components in src/
-```
-
-JSON schema (`fluent-report.json`):
-
-```json
-{
-  "generatedAt": "2026-03-02T10:00:00.000Z",
-  "env": { "node": "22.21.1", "os": "darwin-arm64", "npm": "10.9.4" },
-  "packages": {
-    "@fluentui/react-components": "9.73.1",
-    "@fluentui/react": "8.125.5"
-  },
-  "usage": {
-    "scannedPath": "src/",
-    "totalUsages": 312,
-    "components": [
-      { "name": "Button", "package": "@fluentui/react-components", "usages": 142, "props": ["appearance", "icon"] },
-      { "name": "DefaultButton", "package": "@fluentui/react", "usages": 37, "props": ["text", "onClick"] }
-    ]
-  }
-}
-```
-
-`usage` is `null` when no path is provided.
-
-Migration recommendation hints are **Phase 2** — MVP `report` is data-only.
-
----
-
-### 6.2 Migration Registry Contract (`migrations.json`)
-
-`migrations.json` is an execution catalog consumed by CLI; it is not the migration strategy source.
-
-```json
-{
-  "version": "1",
-  "migrations": [
-    {
-      "name": "deprecated-packages",
-      "version": "9.0.0",
-      "fromVersion": "8.0.0",
-      "description": "Replace deprecated @fluentui package imports with supported equivalents",
-      "package": "@fluentui/react-components",
-      "kind": "ast",
-      "implementation": "./dist/transforms/v9/deprecated-packages.js",
-      "idempotent": true
-    },
-    {
-      "name": "deprecated-props",
-      "version": "9.0.0",
-      "fromVersion": "8.0.0",
-      "description": "Replace @deprecated props across v9 components with their supported replacements",
-      "package": "@fluentui/react-components",
-      "kind": "ast",
-      "implementation": "./dist/transforms/v9/deprecated-props.js",
-      "idempotent": true
-    }
-  ]
-}
+npx @fluentui/cli@experimental metadata [options]
 ```
 
-Fields:
-
-- `kind`: `ast` | `nx-generator` | `composite`
-- `implementation`: path to compiled entrypoint, resolved from package root
-- `idempotent`: required declaration — transforms that cannot guarantee idempotency are not permitted in MVP
-
----
-
-### 6.3 Migration Types
-
-1. **AST transform** (default): codemods for imports, props, JSX shape. Implemented as standard jscodeshift transforms.
-2. **Nx-style migration wrapper**: invokes migration-style scripts through the unified CLI contract.
-3. **Composite migration**: ordered list of atomic migrations with shared context.
-
----
-
-## 7) Agent Skills Spec
-
-Skills are the authoritative migration source for this project.
-
-### 7.1 Location
-
-`skills/<skill-name>/SKILL.md` at the **repo root**. Versioned with the codebase. Distributed via the `npx skills add` tooling (external).
-
-### 7.2 Skill Inventory (MVP)
-
-| Skill file                            | Purpose                               |
-| ------------------------------------- | ------------------------------------- |
-| `skills/fluentui-migrate-v8-to-v9.md` | End-to-end v8 → v9 migration workflow |
-
-### 7.3 Skill Workflow Contract
-
-Every skill must follow this baseline sequence:
-
-1. Run `@fluentui/cli report [path] --json` and parse the JSON output.
-2. Determine applicable migration plan from skill rules.
-3. Resolve needed codemod steps against CLI migration list (`migrate --list --json`).
-4. Run `migrate --dry-run --json` and evaluate risk signals against safety thresholds.
-5. Run `migrate --json` (apply step) if safe; confirm with user if large-diff gate triggers.
-6. Run verification (`npx nx run-many -t type-check` on touched projects).
-7. Produce final summary: migrations run, files changed, remaining manual follow-ups.
-
-### 7.4 Skill Safety Thresholds
-
-Defined as named constants in the skill file (hardcoded defaults, documented for review):
-
-| Constant                  | Default | Meaning                                               |
-| ------------------------- | ------- | ----------------------------------------------------- |
-| `PARSE_ERROR_RATE_LIMIT`  | `0.05`  | Stop if >5% of files fail to parse                    |
-| `LARGE_DIFF_FILE_COUNT`   | `100`   | Require human confirmation if >100 files changed      |
-| `UNRESOLVED_IMPORT_LIMIT` | `0`     | Stop if any unresolved imports remain after transform |
-
-### 7.5 Safety Rules
-
-- Never run apply step before dry-run succeeds.
-- Stop if parser error rate exceeds `PARSE_ERROR_RATE_LIMIT`.
-- Stop if transform claims success but outputs unresolved imports.
-- Require human confirmation when changed file count exceeds `LARGE_DIFF_FILE_COUNT`.
-
----
-
-## 8) Required Codemods (MVP)
-
-### `deprecated-packages`
-
-Rewrites imports from deprecated `@fluentui` packages to their current equivalents.
-
-Deprecated packages (source: `packages/react-components/deprecated/`):
-
-| Deprecated import             | Replacement                           | Note                                                                |
-| ----------------------------- | ------------------------------------- | ------------------------------------------------------------------- |
-| `@fluentui/react-alert`       | `@fluentui/react-toast`               | Insert `// TODO: also consider @fluentui/react-message-bar` comment |
-| `@fluentui/react-infobutton`  | `@fluentui/react-infolabel`           | Rename component `InfoButton` → `InfoLabel`                         |
-| `@fluentui/react-virtualizer` | `@fluentui-contrib/react-virtualizer` | Package moved to contrib                                            |
-
-**Source of truth**: read `packages/react-components/deprecated/*/README.md` before implementing.
-
-### `deprecated-props`
-
-Renames (or removes) deprecated component props to their supported replacements.
-
-Known deprecated props (source: `@deprecated` JSDoc tags in `packages/react-components/`):
-
-| Component            | Deprecated prop       | Replacement                          |
-| -------------------- | --------------------- | ------------------------------------ |
-| `TableSelectionCell` | `hidden`              | `invisible`                          |
-| `Popover`            | `legacyTrapFocus`     | `inertTrapFocus`                     |
-| `Calendar` (compat)  | `overlayedWithButton` | `overlaidWithButton`                 |
-| `PositioningOptions` | `positionFixed`       | `strategy="fixed"` (value transform) |
-| `TagPickerList`      | `disableAutoFocus`    | _(remove — prop has no effect)_      |
-
-**Source of truth**: search `@deprecated` across `packages/react-components/` before implementing to catch any additions.
+Options:
 
-### Transform conventions
+- `-e, --entry <file>` selects an `index.d.ts` entry; the package `types` field is resolved by default.
+- `-r, --reporter <json|markdown|html>` selects the output format; JSON is the default.
+- `-o, --output <file>` writes the result to a file instead of standard output.
 
-```typescript
-import type { Transform, API, FileInfo } from 'jscodeshift';
-const transform: Transform = (file: FileInfo, api: API): string | void => { ... };
-export default transform;
-// Return undefined → nochange (no write). Must be idempotent.
-```
+## Output Requirements
 
----
+- Standard output remains usable in scripts when no output file is provided.
+- Errors are written to standard error and result in a nonzero exit code.
+- JSON output remains machine-readable and deterministic for the same inputs.
+- Markdown and HTML output escape source content appropriately.
+- Source analysis does not modify consumer files.
 
-## 9) Package Layout
+## Quality Requirements
 
-```sh
-packages/cli/
-├── bin/fluentui.js              # #!/usr/bin/env node shebang
-├── migrations.json              # execution catalog (ships in npm package)
-├── src/
-│   ├── index.ts                 # yargs root — registers migrate + report
-│   ├── types.ts                 # MigrationEntry, RunnerOptions, ReportOutput, ...
-│   ├── commands/
-│   │   ├── migrate.ts
-│   │   └── report.ts
-│   ├── runner/
-│   │   ├── MigrationRunner.ts   # loads registry, filters, invokes jscodeshift Runner API
-│   │   └── semverFilter.ts      # normaliseVersion(), filterMigrationsByRange()
-│   ├── report/
-│   │   ├── packageScanner.ts    # globs node_modules for @fluentui/* versions
-│   │   └── UsageCollector.ts    # jscodeshift read-only visitor for imports + JSX props
-│   ├── transforms/
-│   │   └── v9/
-│   │       ├── deprecated-packages.ts
-│   │       └── deprecated-props.ts
-│   └── __tests__/
-│       ├── semverFilter.test.ts
-│       ├── MigrationRunner.test.ts
-│       ├── report/packageScanner.test.ts
-│       └── transforms/
-│           ├── deprecated-packages/   # golden input/output fixtures
-│           └── deprecated-props/      # golden input/output fixtures
-├── package.json
-├── project.json                 # @nx/js:swc build target, platform:node tag
-├── .swcrc                       # copy from tools/visual-regression-assert/.swcrc
-├── tsconfig.json
-├── tsconfig.lib.json
-├── tsconfig.spec.json
-├── jest.config.ts
-└── eslint.config.js
-```
+- Every command and formatter has focused Jest coverage.
+- File traversal respects include and exclude patterns.
+- Declaration parsing resolves cross-package references without requiring runtime package imports.
+- Root and command-level `--help` output accurately reflects the supported surface.
+- Build and validation tasks leave the tracked worktree unchanged.
 
-Skills (repo root, versioned with code):
+## Development Workflow
 
 ```sh
-skills/
-└── fluentui-migrate-v8-to-v9.md
+yarn nx run cli:test
+yarn nx run cli:lint
+yarn nx run cli:type-check
+yarn nx run cli:build
+node tools/cli/bin/fluentui-cli.js --help
 ```
 
----
-
-## 10) Build Tooling
-
-Mirrors `tools/visual-regression-assert/` — the canonical modern Node CLI package in the repo.
-
-| Concern        | Tool                                                                          |
-| -------------- | ----------------------------------------------------------------------------- |
-| Build executor | `@nx/js:swc` — output to `packages/cli/dist/`                                 |
-| SWC config     | `.swcrc` — copy from `tools/visual-regression-assert/.swcrc`                  |
-| Tests          | `@swc/jest` reading `.swcrc`, `testEnvironment: node`                         |
-| TypeScript     | Solution config: `tsconfig.json` → `tsconfig.lib.json` + `tsconfig.spec.json` |
-| Lint           | ESLint flat config, `@fluentui/eslint-plugin` `flat/node` base                |
-
-Workspace changes required:
-
-| File                 | Change                                                      |
-| -------------------- | ----------------------------------------------------------- |
-| `nx.json`            | Add `"packages/cli/**"` to workspace plugin `include` array |
-| `tsconfig.base.json` | Add `"@fluentui/cli": ["packages/cli/src/index.ts"]`        |
-
----
-
-## 11) Implementation Phases
-
-### Phase 0 — Scaffold
-
-- Create `packages/cli/` with all config files (build, test, lint, TypeScript).
-- Update `nx.json` + `tsconfig.base.json`.
-- Verify `nx build cli` and `nx test cli` pass on empty stubs.
-
-### Phase 1 — Core Engine
-
-- Implement `types.ts`, `semverFilter.ts`, `MigrationRunner.ts` with tests.
-- Implement `migrate` command shell + `--list`, `--dry-run`, `--json` modes.
-- Create `migrations.json` with two entries (stubs, implementations not yet wired).
-- Verify CLI responds correctly to all flags against stub transforms.
-
-### Phase 2 — Codemods
-
-- Implement `deprecated-packages.ts` with golden tests + idempotency test.
-- Implement `deprecated-props.ts` with golden tests + idempotency test.
-- Wire transforms into `migrations.json`.
-
-### Phase 3 — Report Command
-
-- Implement `packageScanner.ts` + tests.
-- Implement `UsageCollector.ts` + tests.
-- Implement `report.ts` command (file write, `--print`, `--json`).
-
-### Phase 4 — Agent Skill
-
-- Author `skills/fluentui-migrate-v8-to-v9/SKILL.md` with safety thresholds, 7-step workflow, CLI invocations.
-- Validate workflow against real CLI output on a sample v8 codebase.
-
----
-
-## 12) Verification Strategy
-
-- **Unit tests**: runner, semver filter, registry parsing.
-- **Golden tests**: each transform has `*.input.tsx` / `*.output.tsx` fixture pairs.
-- **Idempotency test**: run each transform twice — second run must return `undefined` (no change).
-- **Integration test**: sample v8 app → CLI migrate → typecheck passes.
-- **Skill E2E**: simulated agent execution path using real CLI `--json` outputs.
-
----
-
-## 13) Risks and Mitigations
-
-- **API drift**: registry versioning + semver gates.
-- **False-positive transforms**: conservative AST matching + dry-run diff review.
-- **Agent overreach**: enforce skills-first policy; CLI is execution-only.
-- **Large monorepo runtime cost**: path scoping + `--cpus` worker control + incremental runs.
-
----
-
-## 14) Open Decisions — Resolved
-
-| Decision                       | Resolution                                                                                             |
-| ------------------------------ | ------------------------------------------------------------------------------------------------------ |
-| Skills packaging location      | `skills/<name>.md` at repo root. `react-components-agent-skills/` placeholder not used.                |
-| Report migration hints in MVP  | Phase 2 only. MVP `report` is data-only.                                                               |
-| Safety gate threshold defaults | Hardcoded named constants in skill file: parse error 5%, diff gate 100 files, zero unresolved imports. |
+New commands should be scaffolded with the workspace CLI-command generator and follow the existing command-definition plus lazy-implementation pattern.
diff --git a/skills/README.md b/skills/README.md
deleted file mode 100644
index 0311b024e2f72..0000000000000
--- a/skills/README.md
+++ /dev/null
@@ -1,57 +0,0 @@
-# Fluent UI Agent Skills
-
-This directory contains [agent skills](https://agentskills.io) — reusable instruction sets that extend AI coding agents with Fluent UI-specific capabilities. Skills are installed into your project (or globally) and automatically loaded by supported agents.
-
-## Available skills
-
-| Skill                                                               | Description                                                                                                                    |
-| ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
-| [`fluentui-migrate-v8-to-v9`](./fluentui-migrate-v8-to-v9/SKILL.md) | Guides AI agents through migrating a codebase from Fluent UI React v8 (`@fluentui/react`) to v9 (`@fluentui/react-components`) |
-
-## Installation
-
-Skills are installed via the [`npx skills`](https://github.com/vercel-labs/skills) CLI, which supports 40+ coding agents including Claude Code, GitHub Copilot, Cursor, Codex, and more.
-
-### Install the migration skill
-
-```bash
-# Interactive — choose which agents and skills to install
-npx skills add microsoft/fluentui
-
-# Install a specific skill
-npx skills add microsoft/fluentui --skill fluentui-migrate-v8-to-v9
-
-# Install to a specific agent
-npx skills add microsoft/fluentui --skill fluentui-migrate-v8-to-v9 -a claude-code
-
-# Install globally (available across all projects)
-npx skills add microsoft/fluentui --skill fluentui-migrate-v8-to-v9 -g
-```
-
-### List available skills
-
-```bash
-npx skills add microsoft/fluentui --list
-```
-
-## Managing installed skills
-
-```bash
-# List installed skills
-npx skills list
-
-# Check for updates
-npx skills check
-
-# Update to latest
-npx skills update
-
-# Remove a skill
-npx skills remove fluentui-migrate-v8-to-v9
-```
-
-## Further reading
-
-- [Agent Skills specification](https://agentskills.io)
-- [Skills directory](https://skills.sh)
-- [`@fluentui/cli` migrate command](../tools/cli/src/commands/migrate/README.md)
diff --git a/skills/fluentui-migrate-v8-to-v9/SKILL.md b/skills/fluentui-migrate-v8-to-v9/SKILL.md
deleted file mode 100644
index bdfed67332f77..0000000000000
--- a/skills/fluentui-migrate-v8-to-v9/SKILL.md
+++ /dev/null
@@ -1,683 +0,0 @@
----
-name: fluentui-migrate-v8-to-v9
-description: 'Guides migration from Fluent UI React v8 (@fluentui/react) to v9 (@fluentui/react-components). Use when asked to migrate a component or codebase, explain what replaces a v8 component, compare v8 and v9 APIs, or troubleshoot visual/styling issues after migration. Covers: component mapping, prop changes, architectural shifts (FluentProvider, Griffel makeStyles, slots, declarative children), and common troubleshooting.'
----
-
-# Fluent UI v8 → v9 Migration
-
-## Agent Output Template
-
-After completing a migration session, report using this structure:
-
-```
-### Migration Report
-
-**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 (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)
-```
-
----
-
-## Migration Workflow
-
-### Step 1 — Assess
-
-**Determine project root and source directory:**
-
-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.
-
-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. The CLI writes it to the same directory passed as `--path`, so look in `<SOURCE_ROOT>`:
-
-```sh
-cat <SOURCE_ROOT>/.fluent-migrate/metadata.json
-```
-
-- 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
-grep -rl "@fluent-migrate:" <SOURCE_ROOT> --include="*.ts" --include="*.tsx"
-```
-
-- 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."
-  >
-  > 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.
-
-### 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.
-
-### 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
-# If running v8 + v9 side-by-side:
-npm install @fluentui/react-portal-compat
-# Shim package for incremental migration (optional — see below):
-npm install @fluentui/react-migration-v8-v9
-```
-
-Wrap the app root (or each subtree using v9 components):
-
-```tsx
-import { FluentProvider, webLightTheme } from '@fluentui/react-components';
-// If v9 inside v8 Callout/Panel:
-import { PortalCompatProvider } from '@fluentui/react-portal-compat';
-
-<FluentProvider theme={webLightTheme}>
-  <PortalCompatProvider>
-    {' '}
-    {/* only if needed */}
-    <App />
-  </PortalCompatProvider>
-</FluentProvider>;
-```
-
-### Step 3 — Migrate (annotation-driven)
-
-**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.
-
-#### 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
-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"
-```
-
-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
-
-```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. 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
-
-```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.
-
-#### 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.
-
-**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`
-- **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
-
----
-
-## Key Architectural Shifts
-
-| Area             | v8                                             | v9                                                               |
-| ---------------- | ---------------------------------------------- | ---------------------------------------------------------------- |
-| Styling          | Runtime CSS-in-JS via `mergeStyles`            | Build-time atomic CSS via Griffel `makeStyles`                   |
-| Theme            | `ThemeProvider` + JS theme object on context   | `FluentProvider` + CSS variables                                 |
-| Theme tokens     | Component-specific (`buttonBackgroundHovered`) | Semantic design tokens (`colorNeutralBackground1Hover`)          |
-| Style override   | `styles` prop on every component               | `className` prop + `makeStyles`                                  |
-| Menu / pickers   | Data-driven (items array)                      | Declarative JSX children                                         |
-| Render callbacks | `onRender*` props                              | Slots (accept JSX, shorthand, or render fn)                      |
-| Ref              | `componentRef`                                 | `ref` (standard React ref)                                       |
-| Aria props       | camelCase (`ariaLabel`)                        | Native HTML (`aria-label`)                                       |
-| Icons            | `iconProps={{ iconName: 'Add' }}`              | `icon={<AddRegular />}` from `@fluentui/react-icons`             |
-| Form labels      | `label` prop on the control                    | `<Field label="...">` wrapping the control                       |
-| Polymorphism     | No `as` prop; use `href` on Button             | `as` prop changes rendered element: `<Button as="a" href="...">` |
-
-## Slot System (v9 Core Concept)
-
-v9 components expose named **slots** instead of `onRender*` callbacks. Every slot prop accepts:
-
-1. **JSX element** — `icon={<AddRegular />}`
-2. **Shorthand object** — `label={{ children: 'Name', style: { fontWeight: 'bold' } }}`
-3. **`null`** — removes the slot entirely: `icon={null}`
-4. **Render function** (advanced) — `icon={(props) => <span {...props} className="my-icon" />}`
-
-```tsx
-// v8 — render callback
-<Button onRenderIcon={() => <MyIcon />} onRenderText={() => <b>Bold text</b>} />
-
-// v9 — slots
-<Button icon={<MyIcon />}>
-  <b>Bold text</b>
-</Button>
-
-// v9 — shorthand object for extra props
-<Button icon={{ children: <MyIcon />, style: { color: 'red' } }}>Label</Button>
-
-// v9 — remove a default slot
-<Button icon={null} />  // hides the default icon
-```
-
-## `disableButtonEnhancement` on Trigger Components
-
-`MenuTrigger`, `PopoverTrigger`, and `DialogTrigger` automatically wrap their child in a `<button>` unless the child is already interactive. When using FluentUI button components (`Button`, `ToolbarButton`, `SplitButton`, etc.) as a trigger, always add `disableButtonEnhancement` to prevent nested `<button>` in the DOM:
-
-```tsx
-// WRONG — Button is already a <button>; without disableButtonEnhancement
-// FluentUI wraps it in another <button> → invalid HTML
-<MenuTrigger>
-  <Button>Open menu</Button>  // ❌ nested <button><button>
-</MenuTrigger>
-
-// CORRECT — disableButtonEnhancement tells the trigger not to wrap
-<MenuTrigger disableButtonEnhancement>
-  <Button>Open menu</Button>  // ✅ single <button>
-</MenuTrigger>
-
-// OK — non-button trigger (e.g., custom div) does NOT need it
-<PopoverTrigger>
-  <div role="button" tabIndex={0}>Click me</div>  // ✅ wrapped in <button> → valid
-</PopoverTrigger>
-```
-
-Rule of thumb: add `disableButtonEnhancement` when the trigger child is a FluentUI `Button`, `ToolbarButton`, `MenuItem`, `Tab`, or any component that already renders `<button>`.
-
-## Component Mapping
-
-| 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`                                                 | `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)                                                                              |
-| `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`, `Toast` / `Toaster`, `TabList`
-
-#### Toast / Toaster (quick start)
-
-v9 provides a first-class toast system. If the v8 codebase used a third-party library (react-toastify, etc.) or custom toast state, migrate to `Toaster`:
-
-```tsx
-import { useToastController, Toaster, Toast, ToastTitle, ToastBody } from '@fluentui/react-components';
-
-// 1. Mount <Toaster> once near the root (inside FluentProvider):
-<Toaster toasterId="main" />;
-
-// 2. Dispatch toasts from anywhere using the controller hook:
-const { dispatchToast } = useToastController('main');
-
-dispatchToast(
-  <Toast>
-    <ToastTitle>Upload complete</ToastTitle>
-    <ToastBody>Your file has been saved.</ToastBody>
-  </Toast>,
-  { intent: 'success' },
-);
-```
-
-`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
-
-| 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                                                           |
-
----
-
-## Common Troubleshooting
-
-**Components render with no styles**
-Wrap the app (or subtree) with `FluentProvider`:
-
-```tsx
-import { FluentProvider, webLightTheme } from '@fluentui/react-components';
-<FluentProvider theme={webLightTheme}>
-  <App />
-</FluentProvider>;
-```
-
-**v9 components inside v8 `Callout` / `Panel` have no styles**
-v8 portals render their children outside the `FluentProvider` DOM subtree, so v9 CSS variable injection doesn't reach them. Fix: add `PortalCompatProvider` inside `FluentProvider` — it makes v8 portals inherit the v9 theme context.
-
-```tsx
-import { PortalCompatProvider } from '@fluentui/react-portal-compat';
-<FluentProvider>
-  <PortalCompatProvider>{/* app */}</PortalCompatProvider>
-</FluentProvider>;
-```
-
-**v8 `Callout` appears beneath a v9 `Dialog` (z-index stacking)**
-v9 portals render to `document.body` by default, appearing above the v8 layer host even when they shouldn't. Fix: tell v9 portals to mount inside the same v8 layer host so both share the same stacking context.
-
-```tsx
-import { PortalMountNodeProvider } from '@fluentui/react-components';
-const mountNode = document.getElementById('fluent-default-layer-host');
-<FluentProvider>
-  <PortalMountNodeProvider mountNode={mountNode}>{/* app */}</PortalMountNodeProvider>
-</FluentProvider>;
-```
-
-**When to use which:**
-
-- `PortalCompatProvider` — v9 components _inside_ a v8 portal have no styles (theme context problem)
-- `PortalMountNodeProvider` — v9 and v8 portals have wrong z-order relative to each other (stacking problem)
-
-**`styles` prop no longer exists**
-Replace with `makeStyles` + `className`:
-
-```tsx
-// v8
-<Button styles={{ root: { color: 'red' } }} />;
-
-// v9
-const useStyles = makeStyles({ btn: { color: 'red' } });
-const s = useStyles();
-<Button className={s.btn} />;
-```
-
----
-
-## Shim Package — Incremental Migration
-
-`@fluentui/react-migration-v8-v9` provides shim components that **accept v8 props but render v9 components**. Use them to unblock the build during incremental migration, then replace shims with native v9 components file-by-file.
-
-**Strategy:** swap the import path + add `Shim` suffix → build passes → migrate to native v9 → remove shim.
-
-### Available shims
-
-| Shim                 | Replaces                          | Import                            |
-| -------------------- | --------------------------------- | --------------------------------- |
-| `DefaultButtonShim`  | `DefaultButton`                   | `@fluentui/react-migration-v8-v9` |
-| `PrimaryButtonShim`  | `PrimaryButton`                   | `@fluentui/react-migration-v8-v9` |
-| `ActionButtonShim`   | `ActionButton`                    | `@fluentui/react-migration-v8-v9` |
-| `CommandButtonShim`  | `CommandButton`                   | `@fluentui/react-migration-v8-v9` |
-| `CompoundButtonShim` | `CompoundButton`                  | `@fluentui/react-migration-v8-v9` |
-| `MenuButtonShim`     | `MenuButton` (v8)                 | `@fluentui/react-migration-v8-v9` |
-| `ToggleButtonShim`   | `ToggleButton` (v8)               | `@fluentui/react-migration-v8-v9` |
-| `CheckboxShim`       | `Checkbox`                        | `@fluentui/react-migration-v8-v9` |
-| `MenuItemShim`       | `ContextualMenuItem` item objects | `@fluentui/react-migration-v8-v9` |
-| `StackShim`          | `Stack`                           | `@fluentui/react-migration-v8-v9` |
-| `StackItemShim`      | `Stack.Item`                      | `@fluentui/react-migration-v8-v9` |
-
-### Usage pattern
-
-```tsx
-// Step 1 — swap import to shim (v8 props still work, component now renders v9)
-import { PrimaryButtonShim as PrimaryButton } from '@fluentui/react-migration-v8-v9';
-
-// No other changes needed — v8 props are accepted as-is:
-<PrimaryButton text="Submit" onClick={handleSubmit} />;
-
-// Step 2 — later, replace with native v9
-import { Button } from '@fluentui/react-components';
-<Button appearance="primary" onClick={handleSubmit}>
-  Submit
-</Button>;
-```
-
-### Theme helpers
-
-```ts
-import { createV8Theme, createV9Theme, createBrandVariants } from '@fluentui/react-migration-v8-v9';
-
-// Make v8 components match your v9 theme during side-by-side migration:
-const v8CompatTheme = createV8Theme(myV9Theme, myBrandVariants);
-
-// Make v9 components match your existing v8 theme:
-const v9CompatTheme = createV9Theme(myV8Theme);
-
-// Derive a v9 BrandVariants ramp from a v8 IPalette:
-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)
-- **Button** (all variants, full prop table) → [references/button.md](references/button.md)
-- **Checkbox** (`indeterminate` → `checked="mixed"`, CheckboxShim) → [references/checkbox.md](references/checkbox.md)
-- **ChoiceGroup / RadioGroup** (`options` array → `Radio` children) → [references/radiogroup.md](references/radiogroup.md)
-- **Facepile / AvatarGroup** (`personas` array → children) → [references/avatargroup.md](references/avatargroup.md)
-- **Menu / ContextualMenu** (data-driven → JSX) → [references/menu.md](references/menu.md)
-- **TextField / Input / Textarea** → [references/input.md](references/input.md)
-- **Pivot / TabList** (content separation) → [references/tabs.md](references/tabs.md)
-- **SpinButton** (label extraction, `onChange` signature change) → [references/spinbutton.md](references/spinbutton.md)
-- **Slider** (label extraction, `onChange` signature change, `showValue` removed) → [references/slider.md](references/slider.md)
-- **Stack → makeStyles flexbox** → [references/stack.md](references/stack.md)
-- **Theme / FluentProvider / makeStyles** → [references/theme.md](references/theme.md)
-- **Dialog / Modal** (composable structure, `hidden` inversion, `modalType`) → [references/dialog.md](references/dialog.md)
-- **Dropdown / Combobox** (options array → `Option` children, `onOptionSelect`) → [references/dropdown.md](references/dropdown.md)
-- **DetailsList / DataGrid** (column definitions, selection Set, sort) → [references/datagrid.md](references/datagrid.md)
-- **Panel / Drawer** (`PanelType` → position + size, `DrawerHeader`, `DrawerBody`) → [references/drawer.md](references/drawer.md)
-- **Tooltip** (`directionalHint` → `positioning`, `relationship` prop, forwardRef trigger) → [references/tooltip.md](references/tooltip.md)
-- **MessageBar** (`messageBarType` → `intent`, composable body/actions) → [references/messagebar.md](references/messagebar.md)
-- **Spinner** (`SpinnerSize` enum → string `size`, `labelPosition` renames) → [references/spinner.md](references/spinner.md)
-- **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/avatargroup.md b/skills/fluentui-migrate-v8-to-v9/references/avatargroup.md
deleted file mode 100644
index 5a7ac29a037e9..0000000000000
--- a/skills/fluentui-migrate-v8-to-v9/references/avatargroup.md
+++ /dev/null
@@ -1,92 +0,0 @@
-# Facepile → AvatarGroup Migration
-
-## Architecture Change
-
-v8 `Facepile` accepts a `personas` array prop and an `overflowPersonas` array.
-
-v9 `AvatarGroup` uses three components:
-
-- `AvatarGroup` — main container (inline items)
-- `AvatarGroupItem` — replaces individual `Persona` items
-- `AvatarGroupPopover` — renders the overflow button + popover with overflow items
-
-Use `partitionAvatarGroupItems` to split a list into inline vs overflow items based on layout.
-
-## Before / After Example
-
-### Before
-
-```tsx
-import { Facepile, IFacepilePersona } from '@fluentui/react';
-import { facepilePersonas } from '@fluentui/example-data';
-import { PersonaSize } from '@fluentui/react/lib/Persona';
-
-const personas: IFacepilePersona[] = facepilePersonas.slice(0, 3);
-const overflowPersonas = facepilePersonas.slice(3);
-
-<Facepile personaSize={PersonaSize.size32} personas={personas} overflowPersonas={overflowPersonas} />;
-```
-
-### After
-
-```tsx
-import {
-  AvatarGroup,
-  AvatarGroupItem,
-  AvatarGroupPopover,
-  partitionAvatarGroupItems,
-} from '@fluentui/react-components';
-
-const names = [
-  'Johnie McConnell',
-  'Allan Munger',
-  'Erik Nason',
-  'Kristin Patterson',
-  'Daisy Phillips',
-  'Carole Poland',
-];
-
-const { inlineItems, overflowItems } = partitionAvatarGroupItems({ items: names });
-
-<AvatarGroup size={32}>
-  {inlineItems.map(name => (
-    <AvatarGroupItem name={name} key={name} />
-  ))}
-  {overflowItems.length > 0 && (
-    <AvatarGroupPopover>
-      {overflowItems.map(name => (
-        <AvatarGroupItem name={name} key={name} />
-      ))}
-    </AvatarGroupPopover>
-  )}
-</AvatarGroup>;
-```
-
-## partitionAvatarGroupItems Options
-
-```ts
-const { inlineItems, overflowItems } = partitionAvatarGroupItems({
-  items: names,
-  layout: 'spread', // 'spread' | 'stack' | 'pie' — controls overflow behavior
-  maxInlineItems: 5, // override max inline count (default depends on layout)
-});
-```
-
-## Facepile → AvatarGroup Prop Mapping
-
-| v8 `IFacepileProps`      | v9                                          | Notes                                          |
-| ------------------------ | ------------------------------------------- | ---------------------------------------------- |
-| `personas`               | `children` (`AvatarGroupItem` elements)     | Use `partitionAvatarGroupItems` to split items |
-| `overflowPersonas`       | `AvatarGroupPopover` children               |                                                |
-| `personaSize`            | `size` on `AvatarGroup`                     | Numeric pixel value                            |
-| `maxDisplayablePersonas` | `maxAvatars` in `partitionAvatarGroupItems` |                                                |
-| `getPersonaProps`        | `AvatarGroupItem` props                     | Pass props directly to each `AvatarGroupItem`  |
-| `onRenderPersona`        | Render custom `AvatarGroupItem`             |                                                |
-| `onRenderPersonaCoin`    | `avatar` slot on `AvatarGroupItem`          |                                                |
-| `overflowButtonProps`    | `AvatarGroupPopover` props                  |                                                |
-| `overflowButtonType`     | `indicator` prop on `AvatarGroupPopover`    |                                                |
-| `addButtonProps`         | —                                           | Not available in v9                            |
-| `showAddButton`          | —                                           | Not available in v9                            |
-| `showTooltip`            | —                                           | Tooltips handled differently in v9             |
-| `className`              | `className`                                 |                                                |
-| `styles`                 | `className`                                 |                                                |
diff --git a/skills/fluentui-migrate-v8-to-v9/references/breadcrumb.md b/skills/fluentui-migrate-v8-to-v9/references/breadcrumb.md
deleted file mode 100644
index 8a06e34d71ba1..0000000000000
--- a/skills/fluentui-migrate-v8-to-v9/references/breadcrumb.md
+++ /dev/null
@@ -1,96 +0,0 @@
-# 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
-
-### Before
-
-```tsx
-import { Breadcrumb } from '@fluentui/react';
-<Breadcrumb
-  items={[
-    { text: 'Home', key: 'home', href: '/' },
-    { text: 'Docs', key: 'docs', href: '/docs' },
-    { text: 'Components', key: 'components', isCurrentItem: true },
-  ]}
-/>;
-```
-
-### After
-
-```tsx
-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
deleted file mode 100644
index 554b3df5e7ef2..0000000000000
--- a/skills/fluentui-migrate-v8-to-v9/references/button.md
+++ /dev/null
@@ -1,217 +0,0 @@
-# Button Migration
-
-## Variant Mapping
-
-| v8                     | v9                                | Notes                                     |
-| ---------------------- | --------------------------------- | ----------------------------------------- |
-| `DefaultButton`        | `Button`                          |                                           |
-| `PrimaryButton`        | `Button appearance="primary"`     |                                           |
-| `ActionButton`         | `Button appearance="transparent"` |                                           |
-| `CommandButton`        | `MenuButton`                      | Use when triggering a menu                |
-| `CommandBarButton`     | `ToolbarButton`                   | Inside a `Toolbar`; standalone → `Button` |
-| `CompoundButton`       | `CompoundButton`                  | Same name, new package                    |
-| `ContextualMenuButton` | `Menu` / `MenuButton`             |                                           |
-| `Button split`         | `SplitButton`                     |                                           |
-| `Button toggle`        | `ToggleButton`                    | Same name, new package                    |
-
-## Before / After Examples
-
-### PrimaryButton
-
-**Before:**
-
-```tsx
-import { PrimaryButton } from '@fluentui/react';
-<PrimaryButton text="Submit" onClick={handleSubmit} />;
-```
-
-**After:**
-
-```tsx
-import { Button } from '@fluentui/react-components';
-<Button appearance="primary" onClick={handleSubmit}>
-  Submit
-</Button>;
-```
-
-### ActionButton with icon
-
-**Before:**
-
-```tsx
-import { ActionButton } from '@fluentui/react';
-<ActionButton iconProps={{ iconName: 'Add' }}>Add item</ActionButton>;
-```
-
-**After:**
-
-```tsx
-import { Button } from '@fluentui/react-components';
-import { AddRegular } from '@fluentui/react-icons';
-<Button appearance="transparent" icon={<AddRegular />}>
-  Add item
-</Button>;
-```
-
-### IconButton
-
-**Before:**
-
-```tsx
-import { IconButton } from '@fluentui/react';
-<IconButton iconProps={{ iconName: 'Settings' }} title="Settings" />;
-```
-
-**After:**
-
-```tsx
-import { Button } from '@fluentui/react-components';
-import { SettingsRegular } from '@fluentui/react-icons';
-<Button icon={<SettingsRegular />} aria-label="Settings" />;
-```
-
-### Button with href (navigation)
-
-**Before:**
-
-```tsx
-import { DefaultButton, PrimaryButton } from '@fluentui/react';
-<DefaultButton href="/dashboard" target="_blank">
-  Go to dashboard
-</DefaultButton>;
-```
-
-**After:**
-
-```tsx
-import { Link } from '@fluentui/react-components';
-<Link href="/dashboard" target="_blank">
-  Go to dashboard
-</Link>;
-
-// v9 option B — use Button rendered as <a> to keep button appearance
-import { Button } from '@fluentui/react-components';
-<Button as="a" href="/dashboard" target="_blank" appearance="primary">
-  Go to dashboard
-</Button>;
-```
-
-`Button as="a"` renders the full button affordance as an anchor element (correct `<a>` in the DOM,
-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`)
-
-**Before:**
-
-```tsx
-import { DefaultButton } from '@fluentui/react';
-<DefaultButton
-  text="Options"
-  menuProps={{
-    items: [
-      { key: 'edit', text: 'Edit', onClick: handleEdit },
-      { key: 'delete', text: 'Delete', onClick: handleDelete },
-    ],
-  }}
-/>;
-```
-
-**After:**
-
-```tsx
-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
-
-**Before:**
-
-```tsx
-import { DefaultButton } from '@fluentui/react';
-<DefaultButton split menuProps={{ items: [...] }}>Action</DefaultButton>
-```
-
-**After:**
-
-```tsx
-import { SplitButton, Menu, MenuItem, MenuList, MenuPopover, MenuTrigger } from '@fluentui/react-components';
-<Menu positioning="below-end">
-  <MenuTrigger>{triggerProps => <SplitButton menuButton={triggerProps}>Action</SplitButton>}</MenuTrigger>
-  <MenuPopover>
-    <MenuList>
-      <MenuItem>Option 1</MenuItem>
-    </MenuList>
-  </MenuPopover>
-</Menu>;
-```
-
-## Button Shims (Incremental Migration)
-
-All button variants have a shim in `@fluentui/react-migration-v8-v9` that accepts v8 props:
-
-```tsx
-// Swap the import — no other code changes needed
-import {
-  DefaultButtonShim as DefaultButton,
-  PrimaryButtonShim as PrimaryButton,
-  ActionButtonShim as ActionButton,
-  CommandButtonShim as CommandButton,
-  CompoundButtonShim as CompoundButton,
-  MenuButtonShim as MenuButton,
-  ToggleButtonShim as ToggleButton,
-} from '@fluentui/react-migration-v8-v9';
-
-// v8 props still work:
-<PrimaryButton text="Submit" iconProps={{ iconName: 'Add' }} onClick={handler} />;
-```
-
-Replace shims with native v9 components (see examples above) when ready.
-
-## Prop Mapping
-
-| v8 `IButtonProps`     | v9 `ButtonProps`                         | Notes                                                     |
-| --------------------- | ---------------------------------------- | --------------------------------------------------------- |
-| `allowDisabledFocus`  | `disabledFocusable`                      |                                                           |
-| `ariaLabel`           | `aria-label`                             | Native HTML                                               |
-| `ariaDescription`     | —                                        | Removed                                                   |
-| `ariaHidden`          | `aria-hidden`                            | Native HTML                                               |
-| `checked`             | `checked` (ToggleButton)                 |                                                           |
-| `className`           | `className`                              |                                                           |
-| `children`            | `children`                               |                                                           |
-| `componentRef`        | `ref`                                    |                                                           |
-| `data`                | —                                        | Removed                                                   |
-| `disabled`            | `disabled`                               |                                                           |
-| `href`                | `as="a"` + `href`                        | `<Button as="a" href="...">` or use `Link` for text links |
-| `iconProps`           | `icon` (slot)                            | Pass `<IconComponent />`                                  |
-| `menuAs`              | —                                        | Use `Menu` + HTML `as`                                    |
-| `menuIconProps`       | `menuIcon` slot (MenuButton)             |                                                           |
-| `menuProps`           | —                                        | Use `Menu` + `MenuButton`                                 |
-| `onMenuClick`         | `onClick`                                | Native HTML                                               |
-| `onRenderChildren`    | `children`                               |                                                           |
-| `onRenderDescription` | `secondaryContent` slot (CompoundButton) |                                                           |
-| `onRenderIcon`        | `icon` slot                              |                                                           |
-| `onRenderMenuIcon`    | `icon` (MenuButton)                      |                                                           |
-| `onRenderText`        | `children`                               |                                                           |
-| `primary`             | `appearance="primary"`                   |                                                           |
-| `primaryDisabled`     | —                                        | Use SplitButton                                           |
-| `secondaryText`       | `secondaryContent` slot (CompoundButton) |                                                           |
-| `split`               | —                                        | Use `SplitButton`                                         |
-| `styles`              | `className` + `makeStyles`               |                                                           |
-| `text`                | `children`                               | Move to JSX children                                      |
-| `theme`               | —                                        | Use `FluentProvider`                                      |
-| `toggle`              | —                                        | Use `ToggleButton`                                        |
-| `uniqueId`            | `key`                                    | React key                                                 |
diff --git a/skills/fluentui-migrate-v8-to-v9/references/callout.md b/skills/fluentui-migrate-v8-to-v9/references/callout.md
deleted file mode 100644
index 6ddee51e43889..0000000000000
--- a/skills/fluentui-migrate-v8-to-v9/references/callout.md
+++ /dev/null
@@ -1,171 +0,0 @@
-# Callout → Popover Migration
-
-## Architecture Change
-
-v8 `Callout` is a standalone component positioned next to a `target` element (ref or DOM node)
-and configured via flat props (`directionalHint`, `isBeakVisible`, `gapSpace`).
-
-v9 `Popover` is **composable**: `PopoverTrigger` wraps the element that opens the popover,
-and `PopoverSurface` contains the floating content. This eliminates the need for a `target` ref
-entirely — the trigger/surface relationship is established by co-location in JSX.
-
-## Before / After Example
-
-### Before
-
-```tsx
-import { Callout, DirectionalHint } from '@fluentui/react';
-
-const targetRef = React.useRef<HTMLButtonElement>(null);
-const [isVisible, setIsVisible] = React.useState(false);
-
-<>
-  <button ref={targetRef} onClick={() => setIsVisible(true)}>
-    Open
-  </button>
-  {isVisible && (
-    <Callout
-      target={targetRef}
-      onDismiss={() => setIsVisible(false)}
-      directionalHint={DirectionalHint.bottomLeftEdge}
-      isBeakVisible
-      gapSpace={8}
-    >
-      <p style={{ padding: 16 }}>Callout content</p>
-    </Callout>
-  )}
-</>;
-```
-
-### After
-
-```tsx
-import { Popover, PopoverTrigger, PopoverSurface, Button } from '@fluentui/react-components';
-
-<Popover withArrow positioning="below-start">
-  <PopoverTrigger disableButtonEnhancement>
-    <Button>Open</Button>
-  </PopoverTrigger>
-  <PopoverSurface style={{ padding: 16 }}>
-    <p>Popover content</p>
-  </PopoverSurface>
-</Popover>;
-```
-
-## Controlled Popover
-
-```tsx
-// v9 — controlled open state (equivalent to Callout hidden={!isVisible})
-const [open, setOpen] = React.useState(false);
-
-<Popover open={open} onOpenChange={(_, data) => setOpen(data.open)} positioning="below-start">
-  <PopoverTrigger disableButtonEnhancement>
-    <Button onClick={() => setOpen(true)}>Open</Button>
-  </PopoverTrigger>
-  <PopoverSurface style={{ padding: 16 }}>
-    <p>Content</p>
-    <Button onClick={() => setOpen(false)}>Close</Button>
-  </PopoverSurface>
-</Popover>;
-```
-
-**Critical:** `hidden={false}` (visible) in v8 → `open={true}` in v9. The logic is inverted.
-
-## Focus Trap (`setInitialFocus` → `trapFocus`)
-
-```tsx
-// v8 — setInitialFocus moves focus into Callout on open
-<Callout target={targetRef} setInitialFocus onDismiss={handleClose}>
-  <FocusTrapZone>
-    <button>Focusable</button>
-  </FocusTrapZone>
-</Callout>
-
-// v9 — trapFocus moves focus in AND traps it; Escape still dismisses
-<Popover trapFocus>
-  <PopoverTrigger disableButtonEnhancement>
-    <Button>Open</Button>
-  </PopoverTrigger>
-  <PopoverSurface>
-    <button>Focusable</button>
-    <Button onClick={() => setOpen(false)}>Close</Button>
-  </PopoverSurface>
-</Popover>
-```
-
-Use `inertTrapFocus` instead of `trapFocus` for a softer accessibility trap (marks background content
-with the `inert` attribute but doesn't require an explicit close button for keyboard users):
-
-```tsx
-<Popover inertTrapFocus>
-```
-
-## Custom Trigger (non-button element)
-
-If the trigger is a custom component, it must forward its `ref` — the same requirement as `Tooltip`.
-
-```tsx
-// v9 — custom trigger must forward ref
-const MyTrigger = React.forwardRef<HTMLDivElement, React.HTMLAttributes<HTMLDivElement>>((props, ref) => (
-  <div ref={ref} role="button" tabIndex={0} {...props} />
-));
-
-<Popover>
-  <PopoverTrigger disableButtonEnhancement>
-    <MyTrigger>Click me</MyTrigger>
-  </PopoverTrigger>
-  <PopoverSurface>Content</PopoverSurface>
-</Popover>;
-```
-
-## DirectionalHint → positioning
-
-| v8 `DirectionalHint` | v9 `positioning`  |
-| -------------------- | ----------------- |
-| `topCenter`          | `"above"`         |
-| `topLeftEdge`        | `"above-start"`   |
-| `topRightEdge`       | `"above-end"`     |
-| `topAutoEdge`        | `"above"`         |
-| `bottomCenter`       | `"below"`         |
-| `bottomLeftEdge`     | `"below-start"`   |
-| `bottomRightEdge`    | `"below-end"`     |
-| `bottomAutoEdge`     | `"below"`         |
-| `leftCenter`         | `"before"`        |
-| `leftTopEdge`        | `"before-top"`    |
-| `leftBottomEdge`     | `"before-bottom"` |
-| `rightCenter`        | `"after"`         |
-| `rightTopEdge`       | `"after-top"`     |
-| `rightBottomEdge`    | `"after-bottom"`  |
-
-For `gapSpace`, pass positioning as an object:
-
-```tsx
-// v8
-<Callout directionalHint={DirectionalHint.bottomLeftEdge} gapSpace={8} />
-
-// v9
-<Popover positioning={{ position: 'below', align: 'start', offset: { mainAxis: 8 } }}>
-```
-
-## ICalloutProps → PopoverProps
-
-| v8                       | v9                                       | Notes                                                          |
-| ------------------------ | ---------------------------------------- | -------------------------------------------------------------- |
-| `target`                 | `<PopoverTrigger>` child                 | Replaces ref-based targeting; trigger is co-located in JSX     |
-| `hidden`                 | `open` (inverted)                        | `hidden={false}` = `open={true}`                               |
-| `onDismiss`              | `onOpenChange`                           | `(ev, data) => data.open === false` on close                   |
-| `directionalHint`        | `positioning`                            | String or object; see table above                              |
-| `gapSpace`               | `positioning={{ offset: { mainAxis } }}` | Pass positioning as object with `offset`                       |
-| `isBeakVisible`          | `withArrow`                              |                                                                |
-| `beakWidth`              | —                                        | Removed                                                        |
-| `setInitialFocus`        | `trapFocus`                              | Also traps focus; use `inertTrapFocus` for softer trap         |
-| `calloutMaxHeight`       | `style` on `<PopoverSurface>`            | `<PopoverSurface style={{ maxHeight: '...' }}>`                |
-| `calloutMaxWidth`        | `style` on `<PopoverSurface>`            | `<PopoverSurface style={{ maxWidth: '...' }}>`                 |
-| `preventDismissOnScroll` | `closeOnScroll={false}`                  | Inverted logic — v9 default is `closeOnScroll={false}`         |
-| `coverTarget`            | —                                        | No direct equivalent                                           |
-| `doNotLayer`             | `mountNode` prop                         | Pass a DOM node to render outside the default portal container |
-| `styles`                 | `className` on `<PopoverSurface>`        |                                                                |
-| `theme`                  | `FluentProvider`                         |                                                                |
-| `componentRef`           | `ref` on `<PopoverSurface>`              |                                                                |
-| —                        | `trapFocus`                              | New — moves focus in and traps it                              |
-| —                        | `inertTrapFocus`                         | New — softer focus trap via `inert` attribute                  |
diff --git a/skills/fluentui-migrate-v8-to-v9/references/card.md b/skills/fluentui-migrate-v8-to-v9/references/card.md
deleted file mode 100644
index 8b4cd2e02b54c..0000000000000
--- a/skills/fluentui-migrate-v8-to-v9/references/card.md
+++ /dev/null
@@ -1,83 +0,0 @@
-# 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
-
-### Before
-
-```tsx
-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>;
-```
-
-### After
-
-```tsx
-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
deleted file mode 100644
index 52c6ba902a05c..0000000000000
--- a/skills/fluentui-migrate-v8-to-v9/references/charts.md
+++ /dev/null
@@ -1,49 +0,0 @@
-# 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/checkbox.md b/skills/fluentui-migrate-v8-to-v9/references/checkbox.md
deleted file mode 100644
index a7ce2ae20625a..0000000000000
--- a/skills/fluentui-migrate-v8-to-v9/references/checkbox.md
+++ /dev/null
@@ -1,114 +0,0 @@
-# Checkbox Migration
-
-## Key Changes
-
-- `indeterminate={true}` → `checked="mixed"`
-- `defaultIndeterminate` → `defaultChecked="mixed"`
-- `boxSide` → `labelPosition`
-- `checkmarkIconProps` → `indicator` slot
-- `componentRef` → `ref`
-
-## Before / After Examples
-
-### Basic Migration
-
-```tsx
-// v8
-import { Checkbox } from '@fluentui/react';
-
-<Checkbox checked label="Checked" />
-<Checkbox disabled label="Disabled" />
-<Checkbox indeterminate={true} label="Indeterminate" />
-```
-
-```tsx
-// v9
-import { Checkbox } from '@fluentui/react-components';
-
-<Checkbox checked label="Checked" />
-<Checkbox disabled label="Disabled" />
-<Checkbox checked="mixed" label="Mixed" />
-```
-
-### Controlled Indeterminate
-
-**Before:**
-
-```tsx
-const [checked, setChecked] = React.useState(false);
-const [indeterminate, setIndeterminate] = React.useState(true);
-
-<Checkbox
-  indeterminate={indeterminate}
-  checked={checked}
-  onChange={(_, data) => {
-    setIndeterminate(false);
-    setChecked(data.checked);
-  }}
-/>;
-```
-
-**After:**
-
-```tsx
-const [checked, setChecked] = React.useState<boolean | 'mixed'>('mixed');
-
-<Checkbox checked={checked} onChange={(_, data) => setChecked(data.checked)} />;
-```
-
-### Label Position
-
-**Before:**
-
-```tsx
-<Checkbox label="Label on left" boxSide="end" />
-```
-
-**After:**
-
-```tsx
-<Checkbox label="Label on left" labelPosition="before" />
-```
-
-### Circular Variant (new in v9)
-
-```tsx
-<Checkbox shape="circular" label="Circular checkbox" />
-```
-
-## CheckboxShim (Interim Bridge)
-
-`CheckboxShim` accepts v8 props and renders a v9 `Checkbox`. Use only for temporary migration — migrate to `Checkbox` directly for new code.
-
-```tsx
-import { CheckboxShim as Checkbox } from '@fluentui/react-migration-v8-v9';
-
-// Keep using v8 props:
-<Checkbox indeterminate={true} label="Still using v8 API" />;
-```
-
-## Prop Mapping
-
-| v8                     | v9                       | CheckboxShim      | Notes                                           |
-| ---------------------- | ------------------------ | ----------------- | ----------------------------------------------- |
-| `componentRef`         | `ref`                    | `componentRef`    |                                                 |
-| `checked`              | `checked`                | `checked`         | Mutually exclusive with `defaultChecked`        |
-| `defaultChecked`       | `defaultChecked`         | `defaultChecked`  | Mutually exclusive with `checked`               |
-| `indeterminate`        | `checked="mixed"`        | `indeterminate`   | v9 merges indeterminate into `checked`          |
-| `defaultIndeterminate` | `defaultChecked="mixed"` | —                 |                                                 |
-| `label`                | `label`                  | `label`           | Slot — accepts string or JSX                    |
-| `boxSide`              | `labelPosition`          | —                 | `'end'` → `'before'` (label before = box after) |
-| `checkmarkIconProps`   | `indicator` slot         | —                 |                                                 |
-| `disabled`             | `disabled`               | `disabled`        |                                                 |
-| `required`             | `required`               | `required`        |                                                 |
-| `onChange`             | `onChange`               | `onChange`        | TypeScript types changed                        |
-| `className`            | `className`              | `className`       |                                                 |
-| `ariaLabel`            | `aria-label`             | `ariaLabel`       |                                                 |
-| `ariaLabelledBy`       | `aria-labelledby`        | `ariaLabelledBy`  |                                                 |
-| `ariaDescribedBy`      | `aria-describedby`       | `ariaDescribedBy` |                                                 |
-| `id`                   | `id`                     | `id`              |                                                 |
-| `name`                 | `name`                   | `name`            |                                                 |
-| `inputProps`           | —                        | —                 | Pass props directly to the `input` slot         |
-| `onRenderLabel`        | —                        | `onRenderLabel`   | Use `label` slot in v9                          |
-| `styles`               | `className`              | `className`       |                                                 |
-| `theme`                | —                        | `theme`           | Use `FluentProvider`                            |
diff --git a/skills/fluentui-migrate-v8-to-v9/references/colorpicker.md b/skills/fluentui-migrate-v8-to-v9/references/colorpicker.md
deleted file mode 100644
index adfb0106269e7..0000000000000
--- a/skills/fluentui-migrate-v8-to-v9/references/colorpicker.md
+++ /dev/null
@@ -1,63 +0,0 @@
-# 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
-
-### Before
-
-```tsx
-import { ColorPicker } from '@fluentui/react';
-<ColorPicker color={color} onChange={(_, c) => setColor(c)} />;
-```
-
-### 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
deleted file mode 100644
index 1ba78d0243d79..0000000000000
--- a/skills/fluentui-migrate-v8-to-v9/references/datagrid.md
+++ /dev/null
@@ -1,238 +0,0 @@
-# DetailsList / DataGrid Migration
-
-## Architecture Change
-
-v8 `DetailsList` and v9 `DataGrid` share the same `items` + `columns` concept, but the column definitions
-and rendering are completely restructured.
-
-Key shifts:
-
-- Columns are defined with `createTableColumn()` factory, which takes typed render functions instead of string `fieldName` + `onRenderColumn` callbacks
-- The grid body uses a **render-props pattern** — `DataGridBody` / `DataGridRow` children are functions, not arrays
-- Selection uses a `Set` of item keys, not a `Selection` class
-- Sorting is declarative (`sortable` prop + `sortState`) instead of per-column `isSorted` flags
-- `getRowId` prop specifies which field to use as the row key
-
-## Before / After Example
-
-### Before
-
-```tsx
-import { DetailsList, IColumn, SelectionMode, Selection } from '@fluentui/react';
-
-interface Item {
-  id: string;
-  name: string;
-  age: number;
-}
-
-const columns: IColumn[] = [
-  {
-    key: 'name',
-    name: 'Name',
-    fieldName: 'name',
-    minWidth: 100,
-    maxWidth: 200,
-    isSortable: true,
-    onRender: (item: Item) => <strong>{item.name}</strong>,
-  },
-  {
-    key: 'age',
-    name: 'Age',
-    fieldName: 'age',
-    minWidth: 50,
-    maxWidth: 100,
-  },
-];
-
-const selection = new Selection();
-
-<DetailsList
-  items={items}
-  columns={columns}
-  selectionMode={SelectionMode.single}
-  selection={selection}
-  onItemInvoked={handleItemInvoked}
-/>;
-```
-
-### After
-
-```tsx
-import {
-  DataGrid,
-  DataGridHeader,
-  DataGridRow,
-  DataGridHeaderCell,
-  DataGridBody,
-  DataGridCell,
-  TableColumnDefinition,
-  TableCellLayout,
-  createTableColumn,
-} from '@fluentui/react-components';
-
-interface Item {
-  id: string;
-  name: string;
-  age: number;
-}
-
-const columns: TableColumnDefinition<Item>[] = [
-  createTableColumn<Item>({
-    columnId: 'name',
-    compare: (a, b) => a.name.localeCompare(b.name),
-    renderHeaderCell: () => 'Name',
-    renderCell: item => (
-      <TableCellLayout>
-        <strong>{item.name}</strong>
-      </TableCellLayout>
-    ),
-  }),
-  createTableColumn<Item>({
-    columnId: 'age',
-    compare: (a, b) => a.age - b.age,
-    renderHeaderCell: () => 'Age',
-    renderCell: item => <TableCellLayout>{item.age}</TableCellLayout>,
-  }),
-];
-
-<DataGrid
-  items={items}
-  columns={columns}
-  getRowId={item => item.id}
-  selectionMode="single"
-  onSelectionChange={(_, data) => console.log([...data.selectedItems])}
-  sortable
->
-  <DataGridHeader>
-    <DataGridRow>{({ renderHeaderCell }) => <DataGridHeaderCell>{renderHeaderCell()}</DataGridHeaderCell>}</DataGridRow>
-  </DataGridHeader>
-  <DataGridBody<Item>>
-    {({ item, rowId }) => (
-      <DataGridRow<Item> key={rowId} onClick={() => handleItemInvoked(item)}>
-        {({ renderCell }) => <DataGridCell>{renderCell(item)}</DataGridCell>}
-      </DataGridRow>
-    )}
-  </DataGridBody>
-</DataGrid>;
-```
-
-## Sorting
-
-```tsx
-// v9 — controlled sort state
-const [sortState, setSortState] = React.useState<{ sortColumn?: string; sortDirection?: 'ascending' | 'descending' }>(
-  {},
-);
-
-<DataGrid
-  items={items}
-  columns={columns}
-  sortable
-  sortState={sortState}
-  onSortChange={(_, nextSort) => setSortState(nextSort)}
->
-  ...
-</DataGrid>;
-```
-
-With sort, `compare` on each `createTableColumn` handles the ordering. `DataGridHeaderCell` renders a sort indicator automatically when `sortable` is set.
-
-## Multi-select
-
-```tsx
-// v9 — controlled multi-select with a Set of row IDs
-const [selectedRows, setSelectedRows] = React.useState(new Set<string>());
-
-<DataGrid
-  items={items}
-  columns={columns}
-  getRowId={item => item.id}
-  selectionMode="multiselect"
-  selectedItems={selectedRows}
-  onSelectionChange={(_, data) => setSelectedRows(new Set(data.selectedItems as string[]))}
->
-  ...
-</DataGrid>;
-```
-
-## Column Resizing
-
-```tsx
-// v9 — column resizing (no v8 equivalent built-in)
-import { DataGridProps } from '@fluentui/react-components';
-
-const columnSizingOptions: DataGridProps['columnSizingOptions'] = {
-  name: { minWidth: 100, defaultWidth: 200 },
-  age: { minWidth: 50, defaultWidth: 100 },
-};
-
-<DataGrid items={items} columns={columns} resizableColumns columnSizingOptions={columnSizingOptions}>
-  ...
-</DataGrid>;
-```
-
-## IColumn → TableColumnDefinition
-
-| v8 `IColumn`           | v9 `createTableColumn` option      | Notes                                       |
-| ---------------------- | ---------------------------------- | ------------------------------------------- |
-| `key`                  | `columnId`                         |                                             |
-| `name`                 | `renderHeaderCell`                 | Return a string or JSX                      |
-| `fieldName`            | `renderCell`                       | Access `item.fieldName` inside `renderCell` |
-| `onRender`             | `renderCell`                       |                                             |
-| `onRenderHeader`       | `renderHeaderCell`                 |                                             |
-| `isSortable` + sort cb | `compare` + `sortable` prop        | `compare` is a typed comparator             |
-| `isSorted`             | `sortState.sortColumn`             | Set via `sortState` prop on `DataGrid`      |
-| `isSortedDescending`   | `sortState.sortDirection`          |                                             |
-| `minWidth`             | `columnSizingOptions[id].minWidth` |                                             |
-| `maxWidth`             | `columnSizingOptions[id].maxWidth` |                                             |
-| `isResizable`          | `resizableColumns` on `DataGrid`   |                                             |
-
-## IDetailsListProps → DataGridProps
-
-| v8                    | v9                                    | Notes                                     |
-| --------------------- | ------------------------------------- | ----------------------------------------- |
-| `items`               | `items`                               |                                           |
-| `columns`             | `columns`                             | Different shape — use `createTableColumn` |
-| `selectionMode`       | `selectionMode`                       | `"single"` \| `"multiselect"` (string)    |
-| `selection`           | `selectedItems` + `onSelectionChange` | `Set` of row IDs, not `Selection` class   |
-| `getKey`              | `getRowId`                            |                                           |
-| `onItemInvoked`       | `onClick` on `<DataGridRow>`          |                                           |
-| `onActiveItemChanged` | `onClick` on `<DataGridRow>`          |                                           |
-| `onRenderRow`         | Children function of `<DataGridBody>` |                                           |
-| `onRenderItemColumn`  | `renderCell` in `createTableColumn`   |                                           |
-| `checkboxVisibility`  | `selectionAppearance`                 | `"checkbox"` \| `"brand"` \| `"none"`     |
-| `groups`              | —                                     | Use `Tree` for grouped/hierarchical data  |
-| `compact`             | `size="small"`                        |                                           |
-| `styles`              | `className` + `makeStyles`            |                                           |
-| `theme`               | `FluentProvider`                      |                                           |
-
-## Selection class → Set
-
-```tsx
-// v8 — Selection class
-import { Selection } from '@fluentui/react';
-
-const selection = new Selection({
-  onSelectionChanged: () => {
-    const selected = selection.getSelection() as Item[];
-    console.log(selected);
-  },
-});
-
-<DetailsList selection={selection} selectionMode={SelectionMode.multiple} />;
-```
-
-```tsx
-// v9 — Set of row IDs
-const [selectedItems, setSelectedItems] = React.useState(new Set<string>());
-
-<DataGrid
-  selectionMode="multiselect"
-  selectedItems={selectedItems}
-  onSelectionChange={(_, data) => setSelectedItems(new Set(data.selectedItems as string[]))}
-  getRowId={item => item.id}
->
-  ...
-</DataGrid>;
-```
diff --git a/skills/fluentui-migrate-v8-to-v9/references/dialog.md b/skills/fluentui-migrate-v8-to-v9/references/dialog.md
deleted file mode 100644
index 7b6733a2e1c1e..0000000000000
--- a/skills/fluentui-migrate-v8-to-v9/references/dialog.md
+++ /dev/null
@@ -1,215 +0,0 @@
-# Dialog / Modal Migration
-
-## Architecture Change
-
-In v8, `Dialog` is controlled via `hidden` prop (inverted logic) and composed via a `dialogContentProps` object.
-`Modal` is a separate component with `isOpen`.
-
-In v9, both map to a single `Dialog` that uses declarative JSX children and `open` / `onOpenChange`.
-The structure is: `Dialog` → `DialogSurface` → `DialogBody` → `DialogTitle` + `DialogContent` + `DialogActions`.
-
-**Critical:** v8 `hidden={false}` means visible — v9 `open={true}` means visible. The logic is inverted.
-
-## Before / After Example — Dialog
-
-```tsx
-// v8
-import { Dialog, DialogFooter, DialogType, PrimaryButton, DefaultButton } from '@fluentui/react';
-
-<Dialog
-  hidden={!isOpen}
-  onDismiss={handleClose}
-  dialogContentProps={{
-    type: DialogType.normal,
-    title: 'Delete item',
-    subText: 'Are you sure you want to delete this item?',
-  }}
-  modalProps={{ isBlocking: true }}
->
-  <DialogFooter>
-    <PrimaryButton onClick={handleConfirm} text="Delete" />
-    <DefaultButton onClick={handleClose} text="Cancel" />
-  </DialogFooter>
-</Dialog>;
-```
-
-```tsx
-// v9
-import {
-  Dialog,
-  DialogSurface,
-  DialogBody,
-  DialogTitle,
-  DialogContent,
-  DialogActions,
-  Button,
-} from '@fluentui/react-components';
-
-<Dialog
-  open={isOpen}
-  onOpenChange={(_, data) => setIsOpen(data.open)}
-  // modalType="modal" is the default — blocks backdrop dismiss
->
-  <DialogSurface>
-    <DialogBody>
-      <DialogTitle>Delete item</DialogTitle>
-      <DialogContent>Are you sure you want to delete this item?</DialogContent>
-      <DialogActions>
-        <Button appearance="primary" onClick={handleConfirm}>
-          Delete
-        </Button>
-        <Button onClick={handleClose}>Cancel</Button>
-      </DialogActions>
-    </DialogBody>
-  </DialogSurface>
-</Dialog>;
-```
-
-## With a trigger button (uncontrolled)
-
-```tsx
-// v9 — uncontrolled via DialogTrigger (no isOpen state needed)
-import {
-  Dialog,
-  DialogTrigger,
-  DialogSurface,
-  DialogBody,
-  DialogTitle,
-  DialogContent,
-  DialogActions,
-  Button,
-} from '@fluentui/react-components';
-
-<Dialog>
-  <DialogTrigger disableButtonEnhancement>
-    <Button>Open dialog</Button>
-  </DialogTrigger>
-  <DialogSurface>
-    <DialogBody>
-      <DialogTitle>Confirm</DialogTitle>
-      <DialogContent>Are you sure?</DialogContent>
-      <DialogActions>
-        <DialogTrigger disableButtonEnhancement>
-          <Button appearance="primary">Yes</Button>
-        </DialogTrigger>
-        <DialogTrigger disableButtonEnhancement>
-          <Button>Cancel</Button>
-        </DialogTrigger>
-      </DialogActions>
-    </DialogBody>
-  </DialogSurface>
-</Dialog>;
-```
-
-## Before / After Example — Modal → Dialog
-
-```tsx
-// v8 Modal
-import { Modal } from '@fluentui/react';
-
-<Modal isOpen={isOpen} onDismiss={handleClose} isBlocking={false}>
-  <div>
-    <h2>Modal heading</h2>
-    <p>Modal body content</p>
-    <button onClick={handleClose}>Close</button>
-  </div>
-</Modal>;
-```
-
-```tsx
-// v9 — Dialog with modalType="non-modal" (light dismiss, no blocking overlay)
-import {
-  Dialog,
-  DialogSurface,
-  DialogBody,
-  DialogTitle,
-  DialogContent,
-  DialogActions,
-  Button,
-} from '@fluentui/react-components';
-
-<Dialog open={isOpen} onOpenChange={(_, data) => setIsOpen(data.open)} modalType="non-modal">
-  <DialogSurface>
-    <DialogBody>
-      <DialogTitle>Modal heading</DialogTitle>
-      <DialogContent>Modal body content</DialogContent>
-      <DialogActions>
-        <Button onClick={handleClose}>Close</Button>
-      </DialogActions>
-    </DialogBody>
-  </DialogSurface>
-</Dialog>;
-```
-
-## modalType Values
-
-| v9 `modalType` | Behavior                                                                 | v8 equivalent                        |
-| -------------- | ------------------------------------------------------------------------ | ------------------------------------ |
-| `"modal"`      | Default. Has backdrop overlay; Escape or click outside dismisses.        | `isBlocking={false}` (v8 default)    |
-| `"non-modal"`  | No backdrop; content behind is interactive; Escape still dismisses.      | `isBlocking={false}` without overlay |
-| `"alert"`      | Blocks everything including Escape; user must choose an explicit action. | `isBlocking={true}` + focus trap     |
-
-## IDialogProps → DialogProps
-
-| v8                              | v9                                          | Notes                                        |
-| ------------------------------- | ------------------------------------------- | -------------------------------------------- |
-| `hidden`                        | `open` (inverted)                           | `hidden={false}` = `open={true}`             |
-| `onDismiss`                     | `onOpenChange`                              | `(ev, data) => data.open === false` on close |
-| `dialogContentProps.title`      | `<DialogTitle>`                             | JSX child                                    |
-| `dialogContentProps.subText`    | `<DialogContent>`                           | JSX child                                    |
-| `dialogContentProps.type`       | `modalType` on `<Dialog>`                   | See table above                              |
-| `dialogContentProps.titleProps` | Props on `<DialogTitle>`                    |                                              |
-| `dialogContentProps.styles`     | `className` + `makeStyles`                  |                                              |
-| `modalProps.isBlocking`         | `modalType="alert"`                         |                                              |
-| `modalProps.layerProps`         | —                                           | Not supported                                |
-| `minWidth` / `maxWidth`         | `style` or `className` on `<DialogSurface>` |                                              |
-| `styles`                        | `className` + `makeStyles`                  |                                              |
-| `theme`                         | `FluentProvider`                            |                                              |
-
-## IModalProps → DialogProps
-
-| v8                           | v9                               | Notes                              |
-| ---------------------------- | -------------------------------- | ---------------------------------- |
-| `isOpen`                     | `open`                           |                                    |
-| `onDismiss`                  | `onOpenChange`                   |                                    |
-| `isBlocking`                 | `modalType="alert"`              | Prevents Escape + backdrop dismiss |
-| `isDarkOverlay`              | CSS on `DialogSurface` backdrop  |                                    |
-| `scrollableContentClassName` | `className` on `<DialogSurface>` |                                    |
-| `containerClassName`         | `className` on `<DialogSurface>` |                                    |
-| `layerProps`                 | —                                | Not supported                      |
-| `styles`                     | `className` + `makeStyles`       |                                    |
-| `theme`                      | `FluentProvider`                 |                                    |
-
-## v8 DialogFooter → DialogActions
-
-**Before:**
-
-```tsx
-import { DialogFooter } from '@fluentui/react';
-<DialogFooter>
-  <PrimaryButton text="OK" />
-  <DefaultButton text="Cancel" />
-</DialogFooter>;
-```
-
-**After:**
-
-```tsx
-import { DialogActions } from '@fluentui/react-components';
-<DialogActions>
-  <Button appearance="primary">OK</Button>
-  <Button>Cancel</Button>
-</DialogActions>;
-```
-
-## Custom close button in title
-
-```tsx
-// v9 — add a close button to the title area via the action slot
-import { DialogTitle, Button } from '@fluentui/react-components';
-import { DismissRegular } from '@fluentui/react-icons';
-
-<DialogTitle action={<Button appearance="subtle" icon={<DismissRegular />} onClick={handleClose} aria-label="Close" />}>
-  Dialog title
-</DialogTitle>;
-```
diff --git a/skills/fluentui-migrate-v8-to-v9/references/drawer.md b/skills/fluentui-migrate-v8-to-v9/references/drawer.md
deleted file mode 100644
index 4c508dbd4f75b..0000000000000
--- a/skills/fluentui-migrate-v8-to-v9/references/drawer.md
+++ /dev/null
@@ -1,159 +0,0 @@
-# Panel / Drawer Migration
-
-## Architecture Change
-
-v8 `Panel` is controlled via `isOpen` and configured through flat props (`headerText`, `type`, `onRenderFooterContent`).
-
-v9 `Drawer` is composable: content is structured via `DrawerHeader`, `DrawerBody`, and `DrawerFooter` children.
-The v9 package exports two variants:
-
-- **`OverlayDrawer`** — floats over content with a backdrop (equivalent to v8 Panel)
-- **`InlineDrawer`** — embedded in the layout and pushes content (no v8 equivalent)
-
-## Before / After Example
-
-### Before
-
-```tsx
-import { Panel, PanelType, PrimaryButton, DefaultButton } from '@fluentui/react';
-
-<Panel
-  isOpen={isOpen}
-  onDismiss={handleClose}
-  type={PanelType.medium}
-  headerText="Settings"
-  isBlocking={false}
-  hasCloseButton
-  onRenderFooterContent={() => (
-    <>
-      <PrimaryButton onClick={handleSave} styles={{ root: { marginRight: 8 } }}>
-        Save
-      </PrimaryButton>
-      <DefaultButton onClick={handleClose}>Cancel</DefaultButton>
-    </>
-  )}
->
-  <p>Panel body content</p>
-</Panel>;
-```
-
-### After
-
-```tsx
-import {
-  OverlayDrawer,
-  DrawerHeader,
-  DrawerHeaderTitle,
-  DrawerBody,
-  DrawerFooter,
-  Button,
-} from '@fluentui/react-components';
-import { DismissRegular } from '@fluentui/react-icons';
-
-<OverlayDrawer
-  open={isOpen}
-  onOpenChange={(_, data) => setIsOpen(data.open)}
-  position="end"
-  size="medium"
-  modalType="non-modal" // isBlocking={false} equivalent
->
-  <DrawerHeader>
-    <DrawerHeaderTitle
-      action={<Button appearance="subtle" icon={<DismissRegular />} onClick={handleClose} aria-label="Close" />}
-    >
-      Settings
-    </DrawerHeaderTitle>
-  </DrawerHeader>
-
-  <DrawerBody>
-    <p>Panel body content</p>
-  </DrawerBody>
-
-  <DrawerFooter>
-    <Button appearance="primary" onClick={handleSave}>
-      Save
-    </Button>
-    <Button onClick={handleClose}>Cancel</Button>
-  </DrawerFooter>
-</OverlayDrawer>;
-```
-
-## PanelType → position + size
-
-| v8 `PanelType`   | v9 `position` | v9 `size`  | Notes                                         |
-| ---------------- | ------------- | ---------- | --------------------------------------------- |
-| `SmallFixedFar`  | `"end"`       | `"small"`  |                                               |
-| `SmallFixedNear` | `"start"`     | `"small"`  |                                               |
-| `SmallFluid`     | `"end"`       | `"small"`  | Full height; custom width via CSS             |
-| `Medium`         | `"end"`       | `"medium"` | Default                                       |
-| `Large`          | `"end"`       | `"large"`  |                                               |
-| `LargeFixed`     | `"end"`       | `"large"`  |                                               |
-| `ExtraLarge`     | `"end"`       | `"full"`   |                                               |
-| `Custom`         | `"end"`       | custom CSS | `style={{ width: '...' }}` on `DrawerSurface` |
-| `CustomNear`     | `"start"`     | custom CSS |                                               |
-
-## modalType Values
-
-| v9 `modalType` | v8 equivalent                        | Behavior                                    |
-| -------------- | ------------------------------------ | ------------------------------------------- |
-| `"modal"`      | `isBlocking={false}` (v8 default)    | Backdrop present; Escape + click-away close |
-| `"non-modal"`  | `isBlocking={false}` + light dismiss | No backdrop; content behind is interactive  |
-| `"alert"`      | `isBlocking={true}`                  | No dismiss on Escape or click-away          |
-
-> Note: v8 Panel default `isBlocking={false}` (click-away dismisses) is equivalent to v9 `modalType="modal"` (backdrop present, click-away dismisses). The defaults match — no explicit `modalType` is needed when migrating a Panel that used its defaults. Only set `modalType="alert"` if the Panel used `isBlocking={true}`.
-
-## IPanelProps → OverlayDrawerProps
-
-| v8                      | v9                                            | Notes                                        |
-| ----------------------- | --------------------------------------------- | -------------------------------------------- |
-| `isOpen`                | `open`                                        |                                              |
-| `onDismiss`             | `onOpenChange`                                | `(ev, data) => data.open === false` on close |
-| `type`                  | `position` + `size`                           | See table above                              |
-| `headerText`            | `<DrawerHeaderTitle>` children                |                                              |
-| `onRenderHeader`        | `<DrawerHeader>` children                     |                                              |
-| `hasCloseButton`        | Button in `DrawerHeaderTitle` `action` slot   | See example above                            |
-| `isBlocking`            | `modalType`                                   |                                              |
-| `isLightDismiss`        | `modalType="non-modal"`                       |                                              |
-| `onRenderFooterContent` | `<DrawerFooter>` children                     |                                              |
-| `onRenderBody`          | `<DrawerBody>` children                       |                                              |
-| `onRenderNavigation`    | `<DrawerHeaderNavigation>` children           |                                              |
-| `customWidth`           | `style={{ width: '...' }}` on `DrawerSurface` |                                              |
-| `styles`                | `className` + `makeStyles`                    |                                              |
-| `theme`                 | `FluentProvider`                              |                                              |
-| `layerProps`            | —                                             | Not supported                                |
-| `componentRef`          | `ref`                                         |                                              |
-
-## InlineDrawer (no v8 equivalent)
-
-Use when the drawer should push page content rather than overlay it:
-
-```tsx
-import { InlineDrawer, DrawerHeader, DrawerHeaderTitle, DrawerBody } from '@fluentui/react-components';
-import { makeStyles } from '@fluentui/react-components';
-
-const useStyles = makeStyles({
-  root: { display: 'flex', height: '480px' },
-  content: { flex: 1, padding: '16px' },
-});
-
-function App() {
-  const s = useStyles();
-  const [open, setOpen] = React.useState(false);
-  return (
-    <div className={s.root}>
-      <InlineDrawer open={open} position="start" separator>
-        <DrawerHeader>
-          <DrawerHeaderTitle>Navigation</DrawerHeaderTitle>
-        </DrawerHeader>
-        <DrawerBody>
-          <p>Side nav content</p>
-        </DrawerBody>
-      </InlineDrawer>
-      <div className={s.content}>
-        <Button onClick={() => setOpen(o => !o)}>Toggle</Button>
-        <p>Main content</p>
-      </div>
-    </div>
-  );
-}
-```
diff --git a/skills/fluentui-migrate-v8-to-v9/references/dropdown.md b/skills/fluentui-migrate-v8-to-v9/references/dropdown.md
deleted file mode 100644
index 7afd16fa5c489..0000000000000
--- a/skills/fluentui-migrate-v8-to-v9/references/dropdown.md
+++ /dev/null
@@ -1,246 +0,0 @@
-# Dropdown / Combobox Migration
-
-## Architecture Change
-
-In v8, both components are **data-driven**: pass an `options` array of `IDropdownOption` / `IComboBoxOption` objects.
-
-In v9, both are **declarative**: compose `<Option>` (and `<OptionGroup>`) as JSX children. This is the same pattern shift as `ContextualMenu` → `Menu`.
-
-The `onChange` callback is also renamed to `onOptionSelect` with a different signature.
-
-## Dropdown
-
-### Before / After — basic
-
-```tsx
-// v8
-import { Dropdown, IDropdownOption } from '@fluentui/react';
-
-const options: IDropdownOption[] = [
-  { key: 'apple', text: 'Apple' },
-  { key: 'banana', text: 'Banana' },
-  { key: 'cherry', text: 'Cherry', disabled: true },
-];
-
-<Dropdown
-  label="Fruit"
-  placeholder="Select an option"
-  options={options}
-  selectedKey={selectedKey}
-  onChange={(_, option) => setSelectedKey(option?.key as string)}
-/>;
-```
-
-```tsx
-// v9
-import { Dropdown, Option, Field } from '@fluentui/react-components';
-
-// Track both the display value (text) and the key (value)
-const [selectedKey, setSelectedKey] = React.useState('');
-const [selectedValue, setSelectedValue] = React.useState('');
-
-<Field label="Fruit">
-  <Dropdown
-    placeholder="Select an option"
-    value={selectedValue}
-    selectedOptions={[selectedKey]}
-    onOptionSelect={(_, data) => {
-      setSelectedKey(data.optionValue ?? '');
-      setSelectedValue(data.optionText ?? '');
-    }}
-  >
-    <Option value="apple">Apple</Option>
-    <Option value="banana">Banana</Option>
-    <Option disabled value="cherry">
-      Cherry
-    </Option>
-  </Dropdown>
-</Field>;
-```
-
-### Before / After — multi-select
-
-```tsx
-// v8
-<Dropdown
-  multiSelect
-  options={options}
-  selectedKeys={selectedKeys}
-  onChange={(_, option) => {
-    if (option?.selected) {
-      setSelectedKeys(prev => [...prev, option.key as string]);
-    } else {
-      setSelectedKeys(prev => prev.filter(k => k !== option?.key));
-    }
-  }}
-/>
-```
-
-```tsx
-// v9
-<Dropdown
-  multiselect
-  selectedOptions={selectedKeys}
-  value={selectedKeys.join(', ')}
-  onOptionSelect={(_, data) => setSelectedKeys(data.selectedOptions)}
->
-  <Option value="apple">Apple</Option>
-  <Option value="banana">Banana</Option>
-  <Option value="cherry">Cherry</Option>
-</Dropdown>
-```
-
-### Before / After — grouped options
-
-```tsx
-// v8
-import { DropdownMenuItemType } from '@fluentui/react';
-
-const options: IDropdownOption[] = [
-  { key: 'fruitsHeader', text: 'Fruits', itemType: DropdownMenuItemType.Header },
-  { key: 'apple', text: 'Apple' },
-  { key: 'banana', text: 'Banana' },
-  { key: 'divider', text: '-', itemType: DropdownMenuItemType.Divider },
-  { key: 'vegsHeader', text: 'Vegetables', itemType: DropdownMenuItemType.Header },
-  { key: 'carrot', text: 'Carrot' },
-];
-```
-
-```tsx
-// v9
-import { Dropdown, Option, OptionGroup } from '@fluentui/react-components';
-
-<Dropdown>
-  <OptionGroup label="Fruits">
-    <Option value="apple">Apple</Option>
-    <Option value="banana">Banana</Option>
-  </OptionGroup>
-  <OptionGroup label="Vegetables">
-    <Option value="carrot">Carrot</Option>
-  </OptionGroup>
-</Dropdown>;
-```
-
-## IDropdownProps → DropdownProps
-
-| v8                   | v9                               | Notes                                                                         |
-| -------------------- | -------------------------------- | ----------------------------------------------------------------------------- |
-| `options`            | `<Option>` children              | Each `IDropdownOption` → `<Option>`                                           |
-| `selectedKey`        | `selectedOptions={[key]}`        | v9 takes an array even for single select                                      |
-| `selectedKeys`       | `selectedOptions={keys}`         | Multi-select                                                                  |
-| `defaultSelectedKey` | `defaultSelectedOptions={[key]}` |                                                                               |
-| `onChange`           | `onOptionSelect`                 | `(ev, data) => void`; data has `optionValue`, `optionText`, `selectedOptions` |
-| `placeholder`        | `placeholder`                    |                                                                               |
-| `label`              | `<Field label="...">` wrapper    | Same as other form controls                                                   |
-| `disabled`           | `disabled`                       |                                                                               |
-| `required`           | `required` on `<Field>`          |                                                                               |
-| `errorMessage`       | `validationMessage` on `<Field>` |                                                                               |
-| `multiSelect`        | `multiselect`                    | Casing change                                                                 |
-| `calloutProps`       | `Listbox` props / `positioning`  |                                                                               |
-| `styles`             | `className` + `makeStyles`       |                                                                               |
-| `theme`              | `FluentProvider`                 |                                                                               |
-| `componentRef`       | `ref`                            |                                                                               |
-
-## IDropdownOption → Option
-
-| v8 `IDropdownOption` | v9 `Option`            | Notes                                                           |
-| -------------------- | ---------------------- | --------------------------------------------------------------- |
-| `key`                | `value`                | `<Option value="apple">`                                        |
-| `text`               | `children`             | `<Option>Apple</Option>`                                        |
-| `disabled`           | `disabled`             |                                                                 |
-| `hidden`             | —                      | Remove from the list instead                                    |
-| `title`              | `title`                |                                                                 |
-| `itemType: Header`   | `OptionGroup` label    | See grouped options example above                               |
-| `itemType: Divider`  | `OptionGroup` boundary | No `OptionDivider` in v9; use separate `<OptionGroup>` elements |
-
----
-
-## Combobox
-
-### Before / After — Combobox basic
-
-```tsx
-// v8
-import { ComboBox, IComboBoxOption } from '@fluentui/react';
-
-const options: IComboBoxOption[] = [
-  { key: 'apple', text: 'Apple' },
-  { key: 'banana', text: 'Banana' },
-];
-
-<ComboBox
-  label="Fruit"
-  placeholder="Select or type"
-  options={options}
-  selectedKey={selectedKey}
-  onChange={(_, option, __, value) => {
-    if (option) setSelectedKey(option.key as string);
-    else setInputValue(value ?? '');
-  }}
-  allowFreeInput
-/>;
-```
-
-```tsx
-// v9
-import { Combobox, Option, Field } from '@fluentui/react-components';
-
-const [selectedKey, setSelectedKey] = React.useState('');
-const [inputValue, setInputValue] = React.useState('');
-
-<Field label="Fruit">
-  <Combobox
-    placeholder="Select or type"
-    value={inputValue}
-    selectedOptions={[selectedKey]}
-    onOptionSelect={(_, data) => {
-      setSelectedKey(data.optionValue ?? '');
-      setInputValue(data.optionText ?? '');
-    }}
-    onChange={e => setInputValue(e.target.value)} // freeform typing
-    freeform // allow values not in the list
-  >
-    <Option value="apple">Apple</Option>
-    <Option value="banana">Banana</Option>
-  </Combobox>
-</Field>;
-```
-
-### Filtering (autocomplete)
-
-```tsx
-// v9 — filter options based on input value
-const [query, setQuery] = React.useState('');
-const matches = options.filter(o => o.toLowerCase().includes(query.toLowerCase()));
-
-<Combobox
-  value={query}
-  onChange={e => setQuery(e.target.value)}
-  onOptionSelect={(_, data) => setQuery(data.optionText ?? '')}
->
-  {matches.map(o => (
-    <Option key={o} value={o}>
-      {o}
-    </Option>
-  ))}
-</Combobox>;
-```
-
-## IComboBoxProps → ComboboxProps
-
-| v8                   | v9                               | Notes                                                       |
-| -------------------- | -------------------------------- | ----------------------------------------------------------- |
-| `options`            | `<Option>` children              |                                                             |
-| `selectedKey`        | `selectedOptions={[key]}`        |                                                             |
-| `onChange`           | `onOptionSelect` + `onChange`    | `onOptionSelect` for list picks; `onChange` for typed input |
-| `allowFreeInput`     | `freeform`                       |                                                             |
-| `autoComplete`       | `autoComplete`                   | `"on"` or `"off"`                                           |
-| `label`              | `<Field label="...">` wrapper    |                                                             |
-| `placeholder`        | `placeholder`                    |                                                             |
-| `disabled`           | `disabled`                       |                                                             |
-| `multiSelect`        | `multiselect`                    |                                                             |
-| `text` (display val) | `value`                          | The text shown in the input                                 |
-| `errorMessage`       | `validationMessage` on `<Field>` |                                                             |
-| `styles`             | `className` + `makeStyles`       |                                                             |
-| `theme`              | `FluentProvider`                 |                                                             |
-| `componentRef`       | `ref`                            |                                                             |
diff --git a/skills/fluentui-migrate-v8-to-v9/references/icons.md b/skills/fluentui-migrate-v8-to-v9/references/icons.md
deleted file mode 100644
index e780c25c1cda5..0000000000000
--- a/skills/fluentui-migrate-v8-to-v9/references/icons.md
+++ /dev/null
@@ -1,114 +0,0 @@
-# Icon Migration
-
-## Naming Convention
-
-v8 uses string icon names via `iconProps={{ iconName: 'Add' }}`.
-v9 uses SVG React components from `@fluentui/react-icons`:
-
-```tsx
-// v8
-import { DefaultButton } from '@fluentui/react';
-<DefaultButton iconProps={{ iconName: 'Add' }} text="Add item" />;
-
-// v9
-import { Button } from '@fluentui/react-components';
-import { AddRegular } from '@fluentui/react-icons';
-<Button icon={<AddRegular />}>Add item</Button>;
-```
-
-## Regular vs Filled
-
-- Use `Regular` (outline) by default
-- Use `Filled` for selected, active, or toggled states
-
-```tsx
-import { StarRegular, StarFilled } from '@fluentui/react-icons';
-<Button icon={isStarred ? <StarFilled /> : <StarRegular />} />;
-```
-
-## Common v8 iconName → v9 Component
-
-| v8 `iconName`     | v9 Component            | Notes                   |
-| ----------------- | ----------------------- | ----------------------- |
-| `Add`             | `AddRegular`            |                         |
-| `AddFriend`       | `PersonAddRegular`      |                         |
-| `ArrowDown`       | `ArrowDownRegular`      |                         |
-| `ArrowLeft`       | `ArrowLeftRegular`      |                         |
-| `ArrowRight`      | `ArrowRightRegular`     |                         |
-| `ArrowUp`         | `ArrowUpRegular`        |                         |
-| `Attach`          | `AttachRegular`         |                         |
-| `Back`            | `ArrowLeftRegular`      |                         |
-| `Cancel`          | `DismissRegular`        | Renamed                 |
-| `CheckMark`       | `CheckmarkRegular`      | Renamed (lowercase 'm') |
-| `ChevronDown`     | `ChevronDownRegular`    |                         |
-| `ChevronLeft`     | `ChevronLeftRegular`    |                         |
-| `ChevronRight`    | `ChevronRightRegular`   |                         |
-| `ChevronUp`       | `ChevronUpRegular`      |                         |
-| `CircleRing`      | `CircleRegular`         | Renamed                 |
-| `Clear`           | `DismissRegular`        | Renamed                 |
-| `Close`           | `DismissRegular`        | Renamed                 |
-| `Copy`            | `CopyRegular`           |                         |
-| `Delete`          | `DeleteRegular`         |                         |
-| `Download`        | `ArrowDownloadRegular`  | Renamed                 |
-| `Edit`            | `EditRegular`           |                         |
-| `Error`           | `ErrorCircleRegular`    | Renamed                 |
-| `Filter`          | `FilterRegular`         |                         |
-| `Forward`         | `ArrowRightRegular`     |                         |
-| `Globe`           | `GlobeRegular`          |                         |
-| `Home`            | `HomeRegular`           |                         |
-| `Info`            | `InfoRegular`           |                         |
-| `Link`            | `LinkRegular`           |                         |
-| `List`            | `ListRegular`           |                         |
-| `Mail`            | `MailRegular`           |                         |
-| `More`            | `MoreHorizontalRegular` | Renamed                 |
-| `MoreVertical`    | `MoreVerticalRegular`   |                         |
-| `OpenInNewWindow` | `OpenRegular`           | Renamed                 |
-| `People`          | `PeopleRegular`         |                         |
-| `Pin`             | `PinRegular`            |                         |
-| `Print`           | `PrintRegular`          |                         |
-| `Refresh`         | `ArrowClockwiseRegular` | Renamed                 |
-| `Save`            | `SaveRegular`           |                         |
-| `Search`          | `SearchRegular`         |                         |
-| `Send`            | `SendRegular`           |                         |
-| `Settings`        | `SettingsRegular`       |                         |
-| `Share`           | `ShareRegular`          |                         |
-| `Star`            | `StarRegular`           |                         |
-| `Tag`             | `TagRegular`            |                         |
-| `Unknown`         | `QuestionCircleRegular` | Renamed                 |
-| `Upload`          | `ArrowUploadRegular`    | Renamed                 |
-| `User`            | `PersonRegular`         | Renamed                 |
-| `Warning`         | `WarningRegular`        |                         |
-
-## Finding Icon Names
-
-If an icon name isn't in the table above, the pattern is usually:
-
-1. Convert `PascalCase` iconName to the same name + `Regular` suffix
-2. Check [Fluent UI Icons](https://react.fluentui.dev/?path=/story/icons-catalog--docs) for the full catalog
-
-Search the icons package:
-
-```sh
-# Find icons matching a keyword (grep the type declarations)
-grep -r "export.*Regular" node_modules/@fluentui/react-icons/lib/components/ 2>/dev/null | grep -i "dismiss" | head -10
-
-# Alternative: search the index type file
-grep "Dismiss" node_modules/@fluentui/react-icons/lib/index.d.ts 2>/dev/null | head -10
-```
-
-The online catalog is authoritative: https://react.fluentui.dev/?path=/story/icons-catalog--docs
-
-## Standalone Icon Usage
-
-```tsx
-// v8
-import { Icon } from '@fluentui/react';
-<Icon iconName="Add" />
-
-// v9
-import { AddRegular } from '@fluentui/react-icons';
-<AddRegular />
-
-// With custom size/color
-<AddRegular fontSize={24} style={{ color: 'blue' }} />
-```
diff --git a/skills/fluentui-migrate-v8-to-v9/references/image.md b/skills/fluentui-migrate-v8-to-v9/references/image.md
deleted file mode 100644
index f8ba5f8c16f5e..0000000000000
--- a/skills/fluentui-migrate-v8-to-v9/references/image.md
+++ /dev/null
@@ -1,71 +0,0 @@
-# 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
-
-### Before
-
-```tsx
-import { Image, ImageFit } from '@fluentui/react';
-<Image src={imgSrc} imageFit={ImageFit.cover} width={200} height={150} shouldFadeIn />;
-```
-
-### After
-
-```tsx
-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/input.md b/skills/fluentui-migrate-v8-to-v9/references/input.md
deleted file mode 100644
index 7865dbc03d68e..0000000000000
--- a/skills/fluentui-migrate-v8-to-v9/references/input.md
+++ /dev/null
@@ -1,135 +0,0 @@
-# Input / Textarea Migration
-
-## Overview
-
-| v8                        | v9         | When                             |
-| ------------------------- | ---------- | -------------------------------- |
-| `TextField` (single-line) | `Input`    | Default                          |
-| `TextField multiline`     | `Textarea` | When `multiline` prop is present |
-
-## Before / After Examples
-
-### Basic TextField → Input (preferred: Field wrapper)
-
-```tsx
-// v8
-import { TextField } from '@fluentui/react';
-<TextField label="Email" required errorMessage="Required" />;
-```
-
-```tsx
-// v9 — preferred: use Field to wrap Input (handles label, required, validation automatically)
-import { Field, Input } from '@fluentui/react-components';
-
-<Field label="Email" required validationState="error" validationMessage="Required">
-  <Input />
-</Field>;
-```
-
-```tsx
-// v9 — alternative: manual wiring with useId
-import { Input, Label, Text, useId } from '@fluentui/react-components';
-
-const emailId = useId('email');
-const errorId = useId('email-error');
-
-<div>
-  <Label htmlFor={emailId} required>
-    Email
-  </Label>
-  <Input id={emailId} required aria-invalid aria-describedby={errorId} />
-  <Text id={errorId}>Required</Text>
-</div>;
-```
-
-### Multiline TextField → Textarea
-
-**Before:**
-
-```tsx
-<TextField multiline rows={4} label="Description" />
-```
-
-**After:**
-
-```tsx
-import { Field, Textarea } from '@fluentui/react-components';
-
-<Field label="Description">
-  <Textarea rows={4} />
-</Field>;
-```
-
-### Prefix / Suffix
-
-**Before:**
-
-```tsx
-<TextField prefix="https://" suffix=".com" />
-```
-
-**After:**
-
-```tsx
-import { Input } from '@fluentui/react-components';
-<Input contentBefore="https://" contentAfter=".com" />;
-// Note: contentBefore/contentAfter accept ReactNode (slot), not just strings
-```
-
-### Underlined / Borderless appearance
-
-**Before:**
-
-```tsx
-<TextField underlined />
-<TextField borderless />
-```
-
-**After:**
-
-```tsx
-<Input appearance="underline" />
-<Input appearance="filled-lighter" />
-```
-
-## Prop Mapping
-
-| v8 `TextField`             | v9 `Input`                               | Notes                                                      |
-| -------------------------- | ---------------------------------------- | ---------------------------------------------------------- |
-| `componentRef`             | `ref`                                    | Returns DOM node, not ITextField                           |
-| `elementRef`               | `ref`                                    |                                                            |
-| `multiline`                | —                                        | Use `Textarea` instead                                     |
-| `resizable`                | —                                        | Textarea only                                              |
-| `autoAdjustHeight`         | —                                        | See Textarea docs                                          |
-| `underlined`               | `appearance="underline"`                 |                                                            |
-| `borderless`               | `appearance="filled-lighter"`            |                                                            |
-| `label`                    | `<Field label="...">` wrapping `<Input>` | Preferred; or manual `<Label>` + `useId`                   |
-| `required`                 | `required` on `<Field>`                  | Field propagates to input via context                      |
-| `onRenderLabel`            | —                                        | Use slots                                                  |
-| `description`              | `hint` slot on `<Field>`                 | `<Field hint="...">`                                       |
-| `onRenderDescription`      | —                                        |                                                            |
-| `onRenderInput`            | —                                        | Use slots                                                  |
-| `prefix`                   | `contentBefore` slot                     | Accepts ReactNode                                          |
-| `suffix`                   | `contentAfter` slot                      | Accepts ReactNode                                          |
-| `iconProps`                | `contentBefore` or `contentAfter` slot   |                                                            |
-| `defaultValue`             | `defaultValue`                           | Mutually exclusive with `value`                            |
-| `value`                    | `value`                                  | Mutually exclusive with `defaultValue`                     |
-| `disabled`                 | `disabled`                               |                                                            |
-| `readOnly`                 | `readOnly`                               | Native HTML prop                                           |
-| `invalid`                  | `validationState="error"` on `<Field>`   | Use `Field` wrapper; or `aria-invalid` on `Input` directly |
-| `errorMessage`             | `validationMessage` on `<Field>`         | `<Field validationState="error" validationMessage="...">`  |
-| `onChange`                 | `onChange`                               | TypeScript types changed                                   |
-| `onNotifyValidationResult` | —                                        |                                                            |
-| `onGetErrorMessage`        | —                                        |                                                            |
-| `deferredValidationTime`   | —                                        |                                                            |
-| `className`                | `className`                              |                                                            |
-| `inputClassName`           | `input` slot                             |                                                            |
-| `ariaLabel`                | `aria-label`                             |                                                            |
-| `validateOnFocusIn`        | —                                        |                                                            |
-| `validateOnFocusOut`       | —                                        |                                                            |
-| `validateOnLoad`           | —                                        |                                                            |
-| `theme`                    | —                                        | Use `FluentProvider`                                       |
-| `styles`                   | `className` + `makeStyles`               |                                                            |
-| `autoComplete`             | `autoComplete`                           | Native HTML prop                                           |
-| `canRevealPassword`        | —                                        | Not built-in                                               |
-| `revealPasswordAriaLabel`  | —                                        | Not built-in                                               |
diff --git a/skills/fluentui-migrate-v8-to-v9/references/keytips.md b/skills/fluentui-migrate-v8-to-v9/references/keytips.md
deleted file mode 100644
index 1d65c17f371b2..0000000000000
--- a/skills/fluentui-migrate-v8-to-v9/references/keytips.md
+++ /dev/null
@@ -1,80 +0,0 @@
-# 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
-
-### Before
-
-```tsx
-import { DefaultButton } from '@fluentui/react';
-<DefaultButton keytipProps={{ content: 'B', keySequences: ['b'] }}>Action</DefaultButton>;
-```
-
-### After
-
-```tsx
-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
deleted file mode 100644
index 11550e5485242..0000000000000
--- a/skills/fluentui-migrate-v8-to-v9/references/label.md
+++ /dev/null
@@ -1,45 +0,0 @@
-# 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
-
-### Before
-
-```tsx
-import { Label } from '@fluentui/react';
-<Label required>Email</Label>;
-```
-
-### After
-
-```tsx
-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
deleted file mode 100644
index f48b8db8bcd19..0000000000000
--- a/skills/fluentui-migrate-v8-to-v9/references/link.md
+++ /dev/null
@@ -1,85 +0,0 @@
-# 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
-
-### Before
-
-```tsx
-import { Link } from '@fluentui/react';
-<Link href="/docs">Read the docs</Link>;
-<Link onClick={handleClick}>Click me</Link>;
-```
-
-### After
-
-```tsx
-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
deleted file mode 100644
index 4ce177ebbfa10..0000000000000
--- a/skills/fluentui-migrate-v8-to-v9/references/list.md
+++ /dev/null
@@ -1,96 +0,0 @@
-# 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
-
-### Before
-
-```tsx
-import { List } from '@fluentui/react';
-<List items={contacts} onRenderCell={item => <div onClick={() => openContact(item)}>{item?.name}</div>} />;
-```
-
-### After
-
-```tsx
-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/menu.md b/skills/fluentui-migrate-v8-to-v9/references/menu.md
deleted file mode 100644
index 75898286a7bdf..0000000000000
--- a/skills/fluentui-migrate-v8-to-v9/references/menu.md
+++ /dev/null
@@ -1,146 +0,0 @@
-# Menu Migration
-
-## Architecture Change
-
-In v8 menus are **data-driven**: pass an `items` array to `ContextualMenu` or `menuProps` on a button.
-
-In v9 menus are **declarative**: compose JSX children under `Menu`.
-
-## Before / After Example
-
-### Before
-
-```tsx
-import { ContextualMenu, ContextualMenuItemType } from '@fluentui/react';
-
-<ContextualMenu
-  target={targetRef}
-  items={[
-    { key: 'new', text: 'New', onClick: handleNew },
-    { key: 'div1', itemType: ContextualMenuItemType.Divider },
-    { key: 'open', text: 'Open', iconProps: { iconName: 'FolderOpen' } },
-    {
-      key: 'recent',
-      text: 'Recent',
-      subMenuProps: {
-        items: [{ key: 'file1', text: 'file1.txt' }],
-      },
-    },
-  ]}
-  onDismiss={handleDismiss}
-/>;
-```
-
-### After
-
-```tsx
-import {
-  Menu,
-  MenuTrigger,
-  MenuPopover,
-  MenuList,
-  MenuItem,
-  MenuDivider,
-  MenuButton,
-} from '@fluentui/react-components';
-import { FolderOpenRegular } from '@fluentui/react-icons';
-
-<Menu>
-  <MenuTrigger disableButtonEnhancement>
-    <MenuButton>Open menu</MenuButton>
-  </MenuTrigger>
-  <MenuPopover>
-    <MenuList>
-      <MenuItem onClick={handleNew}>New</MenuItem>
-      <MenuDivider />
-      <MenuItem icon={<FolderOpenRegular />}>Open</MenuItem>
-      <Menu>
-        <MenuTrigger disableButtonEnhancement>
-          <MenuItem hasSubmenu>Recent</MenuItem>
-        </MenuTrigger>
-        <MenuPopover>
-          <MenuList>
-            <MenuItem>file1.txt</MenuItem>
-          </MenuList>
-        </MenuPopover>
-      </Menu>
-    </MenuList>
-  </MenuPopover>
-</Menu>;
-```
-
-## itemType Enum → Component Mapping
-
-| v8 `ContextualMenuItemType` | v9 component                           |
-| --------------------------- | -------------------------------------- |
-| `Normal`                    | `MenuItem`                             |
-| `Divider`                   | `MenuDivider`                          |
-| `Header`                    | `MenuGroupHeader` (inside `MenuGroup`) |
-| `Section`                   | `MenuGroup`                            |
-| Checkable item (`canCheck`) | `MenuItemCheckbox`                     |
-| Radio item                  | `MenuItemRadio`                        |
-| Split item (`split`)        | `MenuSplitGroup`                       |
-
-## IContextualMenuProps → MenuProps
-
-| v8                | v9                           | Notes                                        |
-| ----------------- | ---------------------------- | -------------------------------------------- |
-| `items`           | children                     | JSX `MenuItem`, etc.                         |
-| `hidden`          | `open` / `onOpenChange`      | Controlled via `MenuTrigger` / `MenuPopover` |
-| `directionalHint` | `positioning`                |                                              |
-| `onDismiss`       | `onOpenChange`               |                                              |
-| `onItemClick`     | `onClick` on each `MenuItem` |                                              |
-| `calloutProps`    | `MenuPopover` props          |                                              |
-| `styles`          | `className` + `makeStyles`   |                                              |
-| `theme`           | `FluentProvider`             |                                              |
-
-## IContextualMenuItem → MenuItemProps
-
-| v8                     | v9                                          | Notes                    |
-| ---------------------- | ------------------------------------------- | ------------------------ |
-| `text`                 | `children`                                  |                          |
-| `key`                  | `key`                                       | React key                |
-| `onClick`              | `onClick`                                   |                          |
-| `disabled`             | `disabled`                                  |                          |
-| `iconProps`            | `icon` slot                                 | Pass `<IconComponent />` |
-| `secondaryText`        | `secondaryContent` slot                     |                          |
-| `ariaLabel`            | `aria-label`                                |                          |
-| `componentRef`         | `ref`                                       |                          |
-| `items` (submenu)      | `children` inside nested `<Menu>`           |                          |
-| `itemType`             | Use appropriate component (see table above) |                          |
-| `canCheck` / `checked` | `MenuItemCheckbox` / `MenuItemRadio`        |                          |
-| `split`                | `MenuSplitGroup`                            |                          |
-| `style` / `styles`     | `className` + `makeStyles`                  |                          |
-| `role`                 | —                                           | Set by component         |
-| `inactive`             | —                                           | Removed                  |
-
-## IContextualMenuSection → MenuGroup
-
-| v8                             | v9                                    |
-| ------------------------------ | ------------------------------------- |
-| `title`                        | `MenuGroupHeader` children            |
-| `items`                        | `MenuGroup` children                  |
-| `topDivider` / `bottomDivider` | — Removed; add `MenuDivider` manually |
-
-## MenuItemShim (Incremental Migration)
-
-`MenuItemShim` accepts a v8 `IContextualMenuItem` object and renders a v9 `MenuItem`. Use it to keep existing `items` arrays working while the rest of the component migrates.
-
-```tsx
-import { MenuItemShim } from '@fluentui/react-migration-v8-v9';
-
-// v8 items array can stay unchanged:
-const items: IContextualMenuItem[] = [
-  { key: 'new', text: 'New', onClick: handleNew },
-  { key: 'open', text: 'Open', iconProps: { iconName: 'FolderOpen' } },
-];
-
-// Render inside v9 MenuList:
-<MenuList>
-  {items.map(item => (
-    <MenuItemShim key={item.key} item={item} />
-  ))}
-</MenuList>;
-```
-
-Replace with native `MenuItem` JSX (see example above) when ready.
diff --git a/skills/fluentui-migrate-v8-to-v9/references/messagebar.md b/skills/fluentui-migrate-v8-to-v9/references/messagebar.md
deleted file mode 100644
index c5c38715c214c..0000000000000
--- a/skills/fluentui-migrate-v8-to-v9/references/messagebar.md
+++ /dev/null
@@ -1,137 +0,0 @@
-# MessageBar Migration
-
-## Architecture Change
-
-v8 `MessageBar` is a flat component: all configuration (type, dismiss, actions) is passed as props.
-
-v9 `MessageBar` is **composable**: content is structured via `MessageBarBody`, `MessageBarTitle`, and `MessageBarActions` children. Dismiss is a button in `MessageBarActions`'s `containerAction` slot.
-
-## Before / After Example
-
-### Before
-
-```tsx
-import { MessageBar, MessageBarType, MessageBarButton } from '@fluentui/react';
-
-<MessageBar
-  messageBarType={MessageBarType.error}
-  isMultiline={false}
-  onDismiss={() => setVisible(false)}
-  dismissButtonAriaLabel="Close"
-  actions={
-    <div>
-      <MessageBarButton onClick={handleAction}>Retry</MessageBarButton>
-    </div>
-  }
->
-  Upload failed. Please try again.
-</MessageBar>;
-```
-
-### After
-
-```tsx
-import { MessageBar, MessageBarBody, MessageBarTitle, MessageBarActions, Button } from '@fluentui/react-components';
-import { DismissRegular } from '@fluentui/react-icons';
-
-<MessageBar intent="error">
-  <MessageBarBody>
-    <MessageBarTitle>Upload failed</MessageBarTitle>
-    Please try again.
-  </MessageBarBody>
-  <MessageBarActions
-    containerAction={
-      <Button
-        appearance="transparent"
-        icon={<DismissRegular />}
-        onClick={() => setVisible(false)}
-        aria-label="Dismiss"
-      />
-    }
-  >
-    <Button onClick={handleAction}>Retry</Button>
-  </MessageBarActions>
-</MessageBar>;
-```
-
-## MessageBarType → intent
-
-| v8 `MessageBarType`            | v9 `intent` | Notes                                      |
-| ------------------------------ | ----------- | ------------------------------------------ |
-| `MessageBarType.info`          | `"info"`    | Default                                    |
-| `MessageBarType.success`       | `"success"` |                                            |
-| `MessageBarType.warning`       | `"warning"` |                                            |
-| `MessageBarType.severeWarning` | `"warning"` | No separate "severe" in v9                 |
-| `MessageBarType.error`         | `"error"`   |                                            |
-| `MessageBarType.blocked`       | `"error"`   | No direct equivalent; use `"error"` intent |
-
-## Simple (no actions, no dismiss)
-
-```tsx
-// v8
-<MessageBar>This is an informational message.</MessageBar>;
-
-// v9
-import { MessageBar, MessageBarBody } from '@fluentui/react-components';
-
-<MessageBar>
-  <MessageBarBody>This is an informational message.</MessageBarBody>
-</MessageBar>;
-```
-
-## Multiline
-
-```tsx
-// v8
-<MessageBar isMultiline={true}>
-  Long message that wraps to multiple lines.
-</MessageBar>
-
-// v9 — multiline is the default; use layout="multiline" explicitly if needed
-<MessageBar layout="multiline">
-  <MessageBarBody>Long message that wraps to multiple lines.</MessageBarBody>
-</MessageBar>
-```
-
-## Controlled Visibility Pattern
-
-```tsx
-// v9 — render the MessageBar conditionally (no built-in open/close)
-const [visible, setVisible] = React.useState(true);
-
-{
-  visible && (
-    <MessageBar intent="warning">
-      <MessageBarBody>Warning: your session will expire soon.</MessageBarBody>
-      <MessageBarActions
-        containerAction={
-          <Button
-            appearance="transparent"
-            icon={<DismissRegular />}
-            onClick={() => setVisible(false)}
-            aria-label="Dismiss"
-          />
-        }
-      />
-    </MessageBar>
-  );
-}
-```
-
-## IMessageBarProps → MessageBarProps
-
-| v8                        | v9                                   | Notes                                                 |
-| ------------------------- | ------------------------------------ | ----------------------------------------------------- |
-| `messageBarType`          | `intent`                             | See table above                                       |
-| `isMultiline`             | `layout`                             | `"singleline"` \| `"multiline"` \| `"auto"` (default) |
-| `onDismiss`               | Button in `containerAction` slot     | Provide `<Button onClick={...}>` explicitly           |
-| `dismissButtonAriaLabel`  | `aria-label` on the dismiss `Button` |                                                       |
-| `actions`                 | `<MessageBarActions>` children       |                                                       |
-| `isBlocking`              | —                                    | Removed; v9 MessageBar never blocks the page          |
-| `overflowButtonAriaLabel` | —                                    | Removed                                               |
-| `truncated`               | —                                    | Removed; handled via `layout`                         |
-| `expandButtonProps`       | —                                    | Removed                                               |
-| `messageBarIconProps`     | `icon` slot on `<MessageBar>`        | Pass `<IconComponent />` to `icon` slot               |
-| `className`               | `className`                          |                                                       |
-| `styles`                  | `className` + `makeStyles`           |                                                       |
-| `theme`                   | `FluentProvider`                     |                                                       |
diff --git a/skills/fluentui-migrate-v8-to-v9/references/nav.md b/skills/fluentui-migrate-v8-to-v9/references/nav.md
deleted file mode 100644
index c228dc6aa3dad..0000000000000
--- a/skills/fluentui-migrate-v8-to-v9/references/nav.md
+++ /dev/null
@@ -1,116 +0,0 @@
-# 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
-
-### Before
-
-```tsx
-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' }],
-        },
-      ],
-    },
-  ]}
-/>;
-```
-
-### After
-
-```tsx
-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
deleted file mode 100644
index 638a60943215a..0000000000000
--- a/skills/fluentui-migrate-v8-to-v9/references/overflow.md
+++ /dev/null
@@ -1,121 +0,0 @@
-# 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
-
-### Before
-
-```tsx
-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="..." />}
-/>;
-```
-
-### After
-
-```tsx
-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
deleted file mode 100644
index c4bb11cdd3f85..0000000000000
--- a/skills/fluentui-migrate-v8-to-v9/references/persona.md
+++ /dev/null
@@ -1,85 +0,0 @@
-# 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
-
-### Before
-
-```tsx
-import { Persona, PersonaSize, PersonaPresence } from '@fluentui/react';
-<Persona
-  text="Alice Northwood"
-  secondaryText="Software Engineer"
-  imageUrl={avatarSrc}
-  size={PersonaSize.size48}
-  presence={PersonaPresence.online}
-/>;
-```
-
-### After
-
-```tsx
-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/progressbar.md b/skills/fluentui-migrate-v8-to-v9/references/progressbar.md
deleted file mode 100644
index 35c1b2c6dd634..0000000000000
--- a/skills/fluentui-migrate-v8-to-v9/references/progressbar.md
+++ /dev/null
@@ -1,104 +0,0 @@
-# ProgressIndicator → ProgressBar Migration
-
-## Key Changes
-
-- Component renamed: `ProgressIndicator` → `ProgressBar`
-- `percentComplete` prop renamed to `value` (same 0–1 range, `max` defaults to `1`)
-- `label` prop removed → wrap `ProgressBar` in `<Field label="...">`
-- `description` prop removed → use `<Field hint="...">`
-- Indeterminate state: v8 omits `percentComplete`; v9 omits `value`
-- `barHeight` removed → use `thickness` prop
-
-## Before / After Example
-
-### Determinate progress
-
-```tsx
-// v8
-import { ProgressIndicator } from '@fluentui/react';
-
-<ProgressIndicator label="Uploading files" description="12 of 100 files" percentComplete={0.12} />;
-```
-
-```tsx
-// v9
-import { Field, ProgressBar } from '@fluentui/react-components';
-
-<Field label="Uploading files" hint="12 of 100 files">
-  <ProgressBar value={0.12} />
-</Field>;
-```
-
-### Indeterminate progress
-
-**Before:**
-
-```tsx
-<ProgressIndicator label="Loading" />
-```
-
-**After:**
-
-```tsx
-import { Field, ProgressBar } from '@fluentui/react-components';
-
-<Field label="Loading">
-  <ProgressBar />
-</Field>;
-```
-
-### Without label (aria-label only)
-
-**Before:**
-
-```tsx
-<ProgressIndicator percentComplete={0.5} ariaLabel="Upload progress" />
-```
-
-**After:**
-
-```tsx
-import { ProgressBar } from '@fluentui/react-components';
-
-<ProgressBar value={0.5} aria-label="Upload progress" />;
-```
-
-## Custom max value
-
-```tsx
-// v9 — use max prop when your value range is not 0–1
-import { Field, ProgressBar } from '@fluentui/react-components';
-
-const filesUploaded = 42;
-const totalFiles = 100;
-
-<Field label="Uploading files" hint={`${filesUploaded} of ${totalFiles}`}>
-  <ProgressBar value={filesUploaded} max={totalFiles} />
-</Field>;
-```
-
-## Thickness
-
-```tsx
-// v9 — thin or medium bar
-<ProgressBar value={0.5} thickness="large" />
-// thickness: "medium" (default) | "large"
-```
-
-## IProgressIndicatorProps → ProgressBarProps
-
-| v8                | v9                         | Notes                                                                |
-| ----------------- | -------------------------- | -------------------------------------------------------------------- |
-| `percentComplete` | `value`                    | Same 0–1 range; `max` defaults to `1`                                |
-| `label`           | `<Field label="...">`      | Wrap `ProgressBar` in `Field`                                        |
-| `description`     | `<Field hint="...">`       | `hint` slot on `Field`                                               |
-| `ariaLabel`       | `aria-label`               | Native HTML prop                                                     |
-| `ariaValueText`   | `aria-valuetext`           | Native HTML prop                                                     |
-| `barHeight`       | `thickness`                | `"medium"` \| `"large"`                                              |
-| `progressHidden`  | —                          | Conditionally render the component instead                           |
-| `className`       | `className`                |                                                                      |
-| `styles`          | `className` + `makeStyles` |                                                                      |
-| `theme`           | `FluentProvider`           |                                                                      |
-| `componentRef`    | `ref`                      |                                                                      |
-| —                 | `max`                      | New — custom maximum value (default `1`)                             |
-| —                 | `color`                    | New — `"brand"` (default) \| `"success"` \| `"warning"` \| `"error"` |
diff --git a/skills/fluentui-migrate-v8-to-v9/references/radiogroup.md b/skills/fluentui-migrate-v8-to-v9/references/radiogroup.md
deleted file mode 100644
index d13f5195922a7..0000000000000
--- a/skills/fluentui-migrate-v8-to-v9/references/radiogroup.md
+++ /dev/null
@@ -1,144 +0,0 @@
-# ChoiceGroup → RadioGroup Migration
-
-## Architecture Change
-
-In v8, `ChoiceGroup` accepts options via an `options` array prop.
-In v9, `RadioGroup` accepts `Radio` elements as JSX children.
-
-The `label` prop is removed. Two options:
-
-- **Preferred:** wrap `RadioGroup` in `<Field label="...">` — Field renders the label and wires accessibility via context.
-- **Alternative:** separate `<Label id={labelId}>` + `aria-labelledby={labelId}` on `RadioGroup`.
-
-## Before / After Examples
-
-### Basic Migration
-
-```tsx
-// v8
-import { ChoiceGroup, IChoiceGroupOption } from '@fluentui/react';
-
-const options: IChoiceGroupOption[] = [
-  { key: 'A', text: 'Option A' },
-  { key: 'B', text: 'Option B' },
-  { key: 'C', text: 'Option C', disabled: true },
-];
-
-<ChoiceGroup defaultSelectedKey="B" options={options} label="Pick one" required />;
-```
-
-```tsx
-// v9 — preferred: Field wrapper
-import { Field, Radio, RadioGroup } from '@fluentui/react-components';
-
-<Field label="Pick one" required>
-  <RadioGroup defaultValue="B">
-    <Radio value="A" label="Option A" />
-    <Radio value="B" label="Option B" />
-    <Radio value="C" label="Option C" disabled />
-  </RadioGroup>
-</Field>;
-```
-
-```tsx
-// v9 — alternative: manual label wiring
-import { Label, Radio, RadioGroup, useId } from '@fluentui/react-components';
-
-const labelId = useId('label');
-
-<>
-  <Label id={labelId} required>
-    Pick one
-  </Label>
-  <RadioGroup aria-labelledby={labelId} defaultValue="B">
-    <Radio value="A" label="Option A" />
-    <Radio value="B" label="Option B" />
-    <Radio value="C" label="Option C" disabled />
-  </RadioGroup>
-</>;
-```
-
-### Controlled (selectedKey → value)
-
-**Before:**
-
-```tsx
-const [selected, setSelected] = React.useState('A');
-<ChoiceGroup selectedKey={selected} options={options} onChange={(_, option) => option && setSelected(option.key)} />;
-```
-
-**After:**
-
-```tsx
-const [selected, setSelected] = React.useState('A');
-<RadioGroup value={selected} onChange={(_, data) => setSelected(data.value)}>
-  <Radio value="A" label="Option A" />
-  <Radio value="B" label="Option B" />
-</RadioGroup>;
-```
-
-### Custom Option Rendering
-
-v9 accepts direct JSX instead of `onRenderField` callbacks:
-
-**Before:**
-
-```tsx
-{ key: 'A', text: 'With icon', onRenderField: (props, render) => (
-  <div style={{ display: 'flex', gap: 5 }}>
-    {render!(props)}
-    <CatIcon />
-  </div>
-)}
-```
-
-**After:**
-
-```tsx
-import { AnimalCat24Regular } from '@fluentui/react-icons';
-
-<Radio
-  value="A"
-  label={{
-    children: (
-      <>
-        <AnimalCat24Regular /> With icon
-      </>
-    ),
-  }}
-/>;
-```
-
-## ChoiceGroup → RadioGroup Prop Mapping
-
-| v8 `IChoiceGroupProps` | v9 `RadioGroupProps`    | Notes                                       |
-| ---------------------- | ----------------------- | ------------------------------------------- |
-| `componentRef`         | `ref`                   |                                             |
-| `options`              | `children`              | Use `<Radio>` children instead of array     |
-| `defaultSelectedKey`   | `defaultValue`          | Mutually exclusive with `value`             |
-| `selectedKey`          | `value`                 | Mutually exclusive with `defaultValue`      |
-| `onChange`             | `onChange`              | TypeScript types changed                    |
-| `label`                | `<Field label="...">`   | Preferred; or `<Label>` + `aria-labelledby` |
-| `ariaLabelledBy`       | `aria-labelledby`       | Native HTML prop in v9                      |
-| `required`             | `required` on `<Field>` | Or on `<Label>` when using manual wiring    |
-| `styles`               | `className`             |                                             |
-| `theme`                | —                       | Use `FluentProvider`                        |
-
-## IChoiceGroupOption → Radio Prop Mapping
-
-| v8 `IChoiceGroupOption` | v9 `RadioProps` | Notes                                             |
-| ----------------------- | --------------- | ------------------------------------------------- |
-| `key`                   | `key`           | Only needed when `.map()`-ing an array            |
-| `text`                  | `label`         | Slot — accepts string, JSX, or shorthand object   |
-| `disabled`              | `disabled`      |                                                   |
-| `ariaLabel`             | `aria-label`    | Native HTML prop                                  |
-| `onRenderField`         | —               | Provide custom JSX child to `RadioGroup` instead  |
-| `onRenderLabel`         | `label` slot    | Pass custom component to `label` slot             |
-| `iconProps`             | —               | Use slots to customize `Radio`                    |
-| `imageSrc`              | —               | Use slots to customize `Radio`                    |
-| `styles`                | `className`     |                                                   |
-| `theme`                 | —               | Use `FluentProvider`                              |
-| `checked`               | `checked`       | Prefer `value` on `RadioGroup` for controlled use |
-| `onChange`              | `onChange`      | TypeScript types changed                          |
-| `name`                  | `name`          | Inherited from `RadioGroup` by default            |
-| `required`              | `required`      |                                                   |
diff --git a/skills/fluentui-migrate-v8-to-v9/references/rating.md b/skills/fluentui-migrate-v8-to-v9/references/rating.md
deleted file mode 100644
index 25d182f993d22..0000000000000
--- a/skills/fluentui-migrate-v8-to-v9/references/rating.md
+++ /dev/null
@@ -1,92 +0,0 @@
-# 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
-
-### Before
-
-```tsx
-import { Rating, RatingSize } from '@fluentui/react';
-<Rating
-  rating={value}
-  max={5}
-  size={RatingSize.Large}
-  onChange={(_, v) => setValue(v ?? 0)}
-  ariaLabelFormat="{0} of {1} stars"
-/>;
-```
-
-### After
-
-```tsx
-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
deleted file mode 100644
index 64a6d75a40f6c..0000000000000
--- a/skills/fluentui-migrate-v8-to-v9/references/searchbox.md
+++ /dev/null
@@ -1,72 +0,0 @@
-# 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
-
-### Before
-
-```tsx
-import { SearchBox } from '@fluentui/react';
-<SearchBox
-  placeholder="Search"
-  value={query}
-  onChange={(_, v) => setQuery(v ?? '')}
-  onSearch={v => doSearch(v)}
-  onClear={() => setQuery('')}
-/>;
-```
-
-### After
-
-```tsx
-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
deleted file mode 100644
index d8eda7dff2a90..0000000000000
--- a/skills/fluentui-migrate-v8-to-v9/references/separator.md
+++ /dev/null
@@ -1,48 +0,0 @@
-# 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
-
-### Before
-
-```tsx
-import { Separator } from '@fluentui/react';
-<Separator vertical alignContent="end">
-  Label
-</Separator>;
-```
-
-### After
-
-```tsx
-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
deleted file mode 100644
index a3d4c9dafa940..0000000000000
--- a/skills/fluentui-migrate-v8-to-v9/references/skeleton.md
+++ /dev/null
@@ -1,80 +0,0 @@
-# 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
-
-### Before
-
-```tsx
-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>;
-```
-
-### After
-
-```tsx
-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/slider.md b/skills/fluentui-migrate-v8-to-v9/references/slider.md
deleted file mode 100644
index 510a469542b44..0000000000000
--- a/skills/fluentui-migrate-v8-to-v9/references/slider.md
+++ /dev/null
@@ -1,134 +0,0 @@
-# Slider Migration
-
-## Key Changes
-
-- `label` prop removed → wrap in `<Field label="...">` (same pattern as SpinButton, Input)
-- `onChange` signature changed: `(event, value: number)` → `(event, data: { value: number })`
-- `showValue` removed — no built-in value display; render the value in JSX manually
-- `originFromZero` removed — no v9 equivalent
-- `snapToStep` removed — v9 always snaps to `step` increments automatically
-- `size` prop added: `"small"` | `"medium"` (new in v9)
-
-## Before / After Examples
-
-### Basic Migration
-
-```tsx
-// v8
-import { Slider } from '@fluentui/react';
-
-<Slider label="Volume" min={0} max={100} defaultValue={20} />;
-```
-
-```tsx
-// v9 — wrap in Field for label
-import { Field, Slider } from '@fluentui/react-components';
-
-<Field label="Volume">
-  <Slider min={0} max={100} defaultValue={20} />
-</Field>;
-```
-
-### Controlled
-
-```tsx
-// v8
-const [value, setValue] = React.useState(20);
-
-<Slider label="Volume" min={0} max={100} value={value} onChange={(_, newValue) => setValue(newValue)} />;
-```
-
-```tsx
-// v9
-import { Field, Slider } from '@fluentui/react-components';
-import type { SliderOnChangeData } from '@fluentui/react-components';
-
-const [value, setValue] = React.useState(20);
-
-const onChange = (_: React.ChangeEvent<HTMLInputElement>, data: SliderOnChangeData) => {
-  setValue(data.value);
-};
-
-<Field label="Volume">
-  <Slider min={0} max={100} value={value} onChange={onChange} />
-</Field>;
-```
-
-### Displaying the Current Value
-
-v8 had a `showValue` prop. In v9, render the value yourself:
-
-**Before:**
-
-```tsx
-<Slider label="Volume" showValue value={value} min={0} max={100} />
-```
-
-**After:**
-
-```tsx
-import { Field, Slider } from '@fluentui/react-components';
-
-const [value, setValue] = React.useState(20);
-
-<Field label={`Volume: ${value}`}>
-  <Slider min={0} max={100} value={value} onChange={(_, data) => setValue(data.value)} />
-</Field>;
-```
-
-### With Step
-
-**Before:**
-
-```tsx
-<Slider min={0} max={100} step={10} snapToStep />
-```
-
-**After:**
-
-```tsx
-<Slider min={0} max={100} step={10} />
-```
-
-### Vertical Slider
-
-**Before:**
-
-```tsx
-<Slider vertical label="Height" min={0} max={100} />
-```
-
-**After:**
-
-```tsx
-import { Field, Slider } from '@fluentui/react-components';
-
-<Field label="Height">
-  <Slider vertical min={0} max={100} />
-</Field>;
-```
-
-## Prop Mapping
-
-| v8 `ISliderProps` | v9 `SliderProps`           | Notes                                                        |
-| ----------------- | -------------------------- | ------------------------------------------------------------ |
-| `componentRef`    | `ref`                      |                                                              |
-| `value`           | `value`                    | Mutually exclusive with `defaultValue`                       |
-| `defaultValue`    | `defaultValue`             | Mutually exclusive with `value`                              |
-| `min`             | `min`                      |                                                              |
-| `max`             | `max`                      |                                                              |
-| `step`            | `step`                     |                                                              |
-| `vertical`        | `vertical`                 |                                                              |
-| `disabled`        | `disabled`                 |                                                              |
-| `label`           | `<Field label="...">`      | Preferred; or `<Label htmlFor={id}>` + `useId`               |
-| `showValue`       | —                          | Removed; render value in JSX (e.g. in `<Field label={...}>`) |
-| `valueFormat`     | —                          | Removed; format the value in JSX manually                    |
-| `snapToStep`      | —                          | Removed; v9 always snaps to `step`                           |
-| `originFromZero`  | —                          | Removed; no v9 equivalent                                    |
-| `onChange`        | `onChange`                 | `(event, data) => void` where `data.value` is `number`       |
-| `ariaLabel`       | `aria-label`               | Native HTML prop                                             |
-| `ariaValueText`   | `aria-valuetext`           | Native HTML prop                                             |
-| `className`       | `className`                |                                                              |
-| `styles`          | `className` + `makeStyles` |                                                              |
-| `theme`           | —                          | Use `FluentProvider`                                         |
-| —                 | `size`                     | New: `"small"` \| `"medium"` (default)                       |
diff --git a/skills/fluentui-migrate-v8-to-v9/references/spinbutton.md b/skills/fluentui-migrate-v8-to-v9/references/spinbutton.md
deleted file mode 100644
index 0d0d80908ee83..0000000000000
--- a/skills/fluentui-migrate-v8-to-v9/references/spinbutton.md
+++ /dev/null
@@ -1,137 +0,0 @@
-# SpinButton Migration
-
-## Key Changes
-
-- `label` prop removed → preferred: wrap in `<Field label="...">`, or manual `<Label htmlFor={id}>` with `useId`
-- `value` / `defaultValue` type changed: `string` → `number`
-- `onIncrement` / `onDecrement` / `onValidate` removed → use `onChange` with `data.value` / `data.displayValue`
-- New `displayValue` prop for formatted display (e.g., with units)
-
-## Before / After Examples
-
-### Basic Migration
-
-```tsx
-// v8
-import { SpinButton } from '@fluentui/react';
-
-const [value, setValue] = React.useState('5');
-
-<SpinButton
-  label="Quantity"
-  value={value}
-  onChange={(_, newValue) => newValue !== undefined && setValue(newValue)}
-  incrementButtonAriaLabel="Increment"
-  decrementButtonAriaLabel="Decrement"
-  styles={{ spinButtonWrapper: { width: 300 } }}
-/>;
-```
-
-```tsx
-// v9 — preferred: Field wrapper handles label wiring automatically
-import { Field, SpinButton } from '@fluentui/react-components';
-import type { SpinButtonChangeEvent, SpinButtonOnChangeData } from '@fluentui/react-components';
-
-const [value, setValue] = React.useState(5); // number, not string
-
-const onChange = (e: SpinButtonChangeEvent, data: SpinButtonOnChangeData) => {
-  if (data.value !== undefined) {
-    setValue(data.value); // stepped via buttons/hotkeys
-  } else if (data.displayValue !== undefined) {
-    const n = Number(data.displayValue);
-    if (!isNaN(n)) setValue(n); // typed manually
-  }
-};
-
-<Field label="Quantity">
-  <SpinButton value={value} min={0} max={100} onChange={onChange} />
-</Field>;
-```
-
-```tsx
-// v9 — alternative: manual label wiring with useId + makeStyles for sizing
-import { makeStyles, Label, SpinButton, useId } from '@fluentui/react-components';
-import type { SpinButtonChangeEvent, SpinButtonOnChangeData } from '@fluentui/react-components';
-
-const useStyles = makeStyles({
-  layout: { display: 'flex', flexDirection: 'column', maxWidth: '300px' },
-});
-
-const spinButtonId = useId('spinbutton');
-const s = useStyles();
-const [value, setValue] = React.useState(5);
-
-<div className={s.layout}>
-  <Label htmlFor={spinButtonId}>Quantity</Label>
-  <SpinButton id={spinButtonId} value={value} min={0} max={100} onChange={onChange} />
-</div>;
-```
-
-### Custom Suffix (onIncrement/onDecrement → displayValue)
-
-```tsx
-// v8 — separate onIncrement / onDecrement / onValidate callbacks
-<SpinButton
-  defaultValue="7 cm"
-  onIncrement={value => String(Math.min(getNum(value) + 2, 100)) + ' cm'}
-  onDecrement={value => String(Math.max(getNum(value) - 2, 0)) + ' cm'}
-  onValidate={value => String(clamp(getNum(value))) + ' cm'}
-/>
-```
-
-```tsx
-// v9 — use displayValue prop + handle data.displayValue in onChange
-const [value, setValue] = React.useState(7);
-const [displayValue, setDisplayValue] = React.useState('7 cm');
-
-const onChange = (e: SpinButtonChangeEvent, data: SpinButtonOnChangeData) => {
-  if (data.value !== undefined) {
-    setValue(data.value);
-    setDisplayValue(`${data.value} cm`);
-  } else if (data.displayValue !== undefined) {
-    const n = getNumericPart(data.displayValue);
-    if (n !== undefined) {
-      setValue(n);
-      setDisplayValue(`${n} cm`);
-    }
-  }
-};
-
-<SpinButton
-  id={spinButtonId}
-  value={value}
-  displayValue={displayValue}
-  step={2}
-  min={0}
-  max={100}
-  onChange={onChange}
-/>;
-```
-
-## Prop Mapping
-
-| v8 `ISpinButtonProps`      | v9 `SpinButtonProps`     | Notes                                                                                                          |
-| -------------------------- | ------------------------ | -------------------------------------------------------------------------------------------------------------- |
-| `componentRef`             | `ref`                    |                                                                                                                |
-| `value`                    | `value`                  | Type changed `string` → `number`; mutually exclusive with `defaultValue`                                       |
-| `defaultValue`             | `defaultValue`           | Type changed `string` → `number`; mutually exclusive with `value`                                              |
-| `min`                      | `min`                    |                                                                                                                |
-| `max`                      | `max`                    |                                                                                                                |
-| `step`                     | `step`                   |                                                                                                                |
-| `precision`                | `precision`              |                                                                                                                |
-| `onChange`                 | `onChange`               | TypeScript types changed; now receives `(e, data)` with `data.value` (number) and `data.displayValue` (string) |
-| `onIncrement`              | `onChange`               | Handle `data.value` in `onChange`                                                                              |
-| `onDecrement`              | `onChange`               | Handle `data.value` in `onChange`                                                                              |
-| `onValidate`               | —                        | Removed; validate in `onChange`                                                                                |
-| `label`                    | `<Field label="...">`    | Preferred; or manual `<Label htmlFor={useId()}>` + `id`                                                        |
-| `labelPosition`            | `orientation` on `Field` | `"horizontal"` for side-by-side                                                                                |
-| `ariaLabel`                | `aria-label`             |                                                                                                                |
-| `ariaDescribedBy`          | `aria-describedby`       |                                                                                                                |
-| `ariaValueText`            | `aria-valuetext`         | Set internally by SpinButton; can be overridden                                                                |
-| `iconProps`                | —                        | Use `<Icon>` component separately                                                                              |
-| `incrementButtonAriaLabel` | —                        | Set internally; use `aria-label` if needed                                                                     |
-| `decrementButtonAriaLabel` | —                        | Set internally; use `aria-label` if needed                                                                     |
-| `className`                | `className`              |                                                                                                                |
-| `styles`                   | `className`              |                                                                                                                |
-| `theme`                    | —                        | Use `FluentProvider`                                                                                           |
-| —                          | `displayValue`           | New in v9 — formatted display string (separate from `value`)                                                   |
diff --git a/skills/fluentui-migrate-v8-to-v9/references/spinner.md b/skills/fluentui-migrate-v8-to-v9/references/spinner.md
deleted file mode 100644
index 1ae550a112220..0000000000000
--- a/skills/fluentui-migrate-v8-to-v9/references/spinner.md
+++ /dev/null
@@ -1,71 +0,0 @@
-# Spinner Migration
-
-## Key Changes
-
-- `size` prop changes from `SpinnerSize` enum to a string literal
-- `labelPosition` values renamed (`"right"` → `"after"`, `"left"` → `"before"`, `"top"` → `"above"`, `"bottom"` → `"below"`)
-- No structural API change — Spinner remains a single self-contained component
-
-## Before / After Example
-
-### Before
-
-```tsx
-import { Spinner, SpinnerSize } from '@fluentui/react';
-
-<Spinner size={SpinnerSize.large} label="Loading..." labelPosition="right" />;
-```
-
-### After
-
-```tsx
-import { Spinner } from '@fluentui/react-components';
-
-<Spinner size="large" label="Loading..." labelPosition="after" />;
-```
-
-## SpinnerSize Enum → size String
-
-| v8 `SpinnerSize`     | v9 `size`       |
-| -------------------- | --------------- |
-| `SpinnerSize.xSmall` | `"extra-small"` |
-| `SpinnerSize.small`  | `"small"`       |
-| `SpinnerSize.medium` | `"medium"`      |
-| `SpinnerSize.large`  | `"large"`       |
-
-v9 also adds `"tiny"`, `"extra-large"`, and `"huge"` sizes with no v8 equivalent.
-
-## labelPosition Values
-
-| v8         | v9         |
-| ---------- | ---------- |
-| `"right"`  | `"after"`  |
-| `"left"`   | `"before"` |
-| `"top"`    | `"above"`  |
-| `"bottom"` | `"below"`  |
-
-Default in both v8 and v9: label appears below the spinner.
-
-## Appearance Variants (new in v9)
-
-```tsx
-// v9 — inverted appearance for dark backgrounds
-<Spinner appearance="inverted" label="Loading..." />
-// v9 — primary appearance
-<Spinner appearance="primary" label="Loading..." />
-```
-
-## ISpinnerProps → SpinnerProps
-
-| v8              | v9                         | Notes                                  |
-| --------------- | -------------------------- | -------------------------------------- |
-| `size`          | `size`                     | Enum → string literal; see table above |
-| `label`         | `label`                    | Slot — accepts string or JSX           |
-| `labelPosition` | `labelPosition`            | Renamed values; see table above        |
-| `ariaLabel`     | `aria-label`               | Native HTML prop                       |
-| `ariaLive`      | `aria-live`                | Native HTML prop                       |
-| `className`     | `className`                |                                        |
-| `styles`        | `className` + `makeStyles` |                                        |
-| `theme`         | `FluentProvider`           |                                        |
-| `componentRef`  | `ref`                      |                                        |
-| —               | `appearance`               | New: `"primary"` \| `"inverted"`       |
diff --git a/skills/fluentui-migrate-v8-to-v9/references/stack.md b/skills/fluentui-migrate-v8-to-v9/references/stack.md
deleted file mode 100644
index 4ba34a11171a3..0000000000000
--- a/skills/fluentui-migrate-v8-to-v9/references/stack.md
+++ /dev/null
@@ -1,153 +0,0 @@
-# Stack Migration
-
-## Overview
-
-v9 has no `Stack` component. Replace it with a plain `div` styled using `makeStyles` and CSS flexbox.
-
-As an interim bridge, `StackShim` is available:
-
-```tsx
-import { StackShim } from '@fluentui/react-migration-v8-v9';
-```
-
-## Default Stack (column layout)
-
-```tsx
-// v8
-<Stack>{children}</Stack>;
-
-// v9
-const useStyles = makeStyles({
-  root: {
-    display: 'flex',
-    flexDirection: 'column',
-    flexWrap: 'nowrap',
-    width: 'auto',
-    height: 'auto',
-    boxSizing: 'border-box',
-  },
-});
-const s = useStyles();
-<div className={s.root}>{children}</div>;
-```
-
-## Prop → CSS Reference
-
-### `horizontal`
-
-```ts
-// Stack horizontal
-flexDirection: 'row';
-// default (vertical)
-flexDirection: 'column';
-```
-
-### `reversed`
-
-```ts
-// horizontal + reversed
-flexDirection: 'row-reverse';
-// vertical + reversed
-flexDirection: 'column-reverse';
-```
-
-### `tokens.childrenGap` (spacing between items)
-
-```ts
-// Preferred: CSS gap (v9 dropped IE11 support)
-gap: '10px'
-
-// Alternative: margin on children (use when gap is insufficient)
-'> :not(:last-child)': { marginBottom: '10px' } // vertical
-'> :not(:last-child)': { marginRight: '10px' }  // horizontal
-```
-
-### `tokens.padding`
-
-```ts
-padding: '10px';
-```
-
-### `tokens.maxWidth` / `tokens.maxHeight`
-
-```ts
-maxWidth: '400px';
-maxHeight: '200px';
-```
-
-### `grow`
-
-```ts
-'> *': { flexGrow: 1 }
-```
-
-### `disableShrink`
-
-```ts
-'> *': { flexShrink: 0 }
-```
-
-### `wrap`
-
-```ts
-// Adds a wrapping inner div
-// outer
-flexWrap: 'wrap',
-overflow: 'visible',
-height: '100%',
-
-// inner wrapper div
-display: 'flex',
-flexWrap: 'wrap',
-overflow: 'visible',
-boxSizing: 'border-box',
-width: '100%',
-maxWidth: '100vw',
-```
-
-### `verticalFill`
-
-```ts
-height: '100%';
-```
-
-### `horizontalAlign` / `verticalAlign`
-
-Alignment depends on `flex-direction`:
-
-| Direction          | Horizontal →      | Vertical ↓        |
-| ------------------ | ----------------- | ----------------- |
-| `column` (default) | `align-items`     | `justify-content` |
-| `row` (horizontal) | `justify-content` | `align-items`     |
-
-Value mapping: `start` → `flex-start`, `end` → `flex-end`, `center` → `center`, `space-between` → `space-between`
-
-## StackItem → makeStyles
-
-```tsx
-// v8
-<Stack.Item grow align="center">
-  {child}
-</Stack.Item>;
-
-// v9
-const useStyles = makeStyles({
-  item: {
-    flexGrow: 1,
-    alignSelf: 'center',
-  },
-});
-const s = useStyles();
-<div className={s.item}>{child}</div>;
-```
-
-### StackItem prop → CSS
-
-| v8 `IStackItemProps` | CSS                               |
-| -------------------- | --------------------------------- |
-| `grow`               | `flex-grow: 1` (or numeric value) |
-| `shrink`             | `flex-shrink: 1`                  |
-| `disableShrink`      | `flex-shrink: 0`                  |
-| `align`              | `align-self`                      |
-| `verticalFill`       | `height: 100%`                    |
-| `order`              | `order`                           |
diff --git a/skills/fluentui-migrate-v8-to-v9/references/swatchpicker.md b/skills/fluentui-migrate-v8-to-v9/references/swatchpicker.md
deleted file mode 100644
index 61feab6a1a154..0000000000000
--- a/skills/fluentui-migrate-v8-to-v9/references/swatchpicker.md
+++ /dev/null
@@ -1,105 +0,0 @@
-# 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
-
-### Before
-
-```tsx
-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' },
-  ]}
-/>;
-```
-
-### After
-
-```tsx
-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
deleted file mode 100644
index ce2c48865cda7..0000000000000
--- a/skills/fluentui-migrate-v8-to-v9/references/switch.md
+++ /dev/null
@@ -1,53 +0,0 @@
-# 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
-
-### Before
-
-```tsx
-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)} />;
-```
-
-### After
-
-```tsx
-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/tabs.md b/skills/fluentui-migrate-v8-to-v9/references/tabs.md
deleted file mode 100644
index f034fa0eaa546..0000000000000
--- a/skills/fluentui-migrate-v8-to-v9/references/tabs.md
+++ /dev/null
@@ -1,105 +0,0 @@
-# Tabs Migration (Pivot → TabList)
-
-## Architecture Change
-
-In v8 (`Pivot`), tab labels and tab content are co-located inside `PivotItem` children.
-
-In v9 (`TabList`), `Tab` children are the **label only**. Tab content lives **outside** `TabList` and is shown/hidden by state.
-
-## Before / After Example
-
-### Before
-
-```tsx
-import { Pivot, PivotItem } from '@fluentui/react';
-
-<Pivot>
-  <PivotItem headerText="First Tab">
-    <p>Content for first tab</p>
-  </PivotItem>
-  <PivotItem headerText="Second Tab">
-    <p>Content for second tab</p>
-  </PivotItem>
-  <PivotItem headerText="Third Tab">
-    <p>Content for third tab</p>
-  </PivotItem>
-</Pivot>;
-```
-
-### After
-
-```tsx
-import * as React from 'react';
-import { TabList, Tab } from '@fluentui/react-components';
-import type { SelectTabData, SelectTabEvent, TabValue } from '@fluentui/react-components';
-
-const [selectedValue, setSelectedValue] = React.useState<TabValue>('tab1');
-
-const onTabSelect = (_event: SelectTabEvent, data: SelectTabData) => {
-  setSelectedValue(data.value);
-};
-
-<>
-  <TabList selectedValue={selectedValue} onTabSelect={onTabSelect}>
-    <Tab value="tab1">First Tab</Tab>
-    <Tab value="tab2">Second Tab</Tab>
-    <Tab value="tab3">Third Tab</Tab>
-  </TabList>
-
-  <div>
-    {selectedValue === 'tab1' && <p>Content for first tab</p>}
-    {selectedValue === 'tab2' && <p>Content for second tab</p>}
-    {selectedValue === 'tab3' && <p>Content for third tab</p>}
-  </div>
-</>;
-```
-
-## Tab with Icon
-
-```tsx
-// v8
-<PivotItem headerText="Files" itemIcon="Folder" />;
-
-// v9
-import { FolderRegular } from '@fluentui/react-icons';
-<Tab value="files" icon={<FolderRegular />}>
-  Files
-</Tab>;
-```
-
-## Pivot → TabList Prop Mapping
-
-| v8 `Pivot`           | v9 `TabList`               | Notes                |
-| -------------------- | -------------------------- | -------------------- |
-| `componentRef`       | `ref`                      |                      |
-| `className`          | `className`                |                      |
-| `defaultSelectedKey` | `defaultSelectedValue`     |                      |
-| `selectedKey`        | `selectedValue`            |                      |
-| `onLinkClick`        | `onTabSelect`              | New event signature  |
-| `linkSize`           | `size`                     |                      |
-| `focusZoneProps`     | —                          | Removed              |
-| `getTabId`           | —                          | Removed              |
-| `headersOnly`        | —                          | Removed              |
-| `linkFormat`         | —                          | Removed              |
-| `overflowAriaLabel`  | —                          | Removed              |
-| `overflowBehavior`   | —                          | Removed              |
-| `styles`             | `className` + `makeStyles` |                      |
-| `theme`              | —                          | Use `FluentProvider` |
-| —                    | `appearance`               | New in v9            |
-| —                    | `vertical`                 | New in v9            |
-
-## PivotItem → Tab Prop Mapping
-
-| v8 `PivotItem`      | v9 `Tab`     | Notes                                     |
-| ------------------- | ------------ | ----------------------------------------- |
-| `componentRef`      | `ref`        |                                           |
-| `headerText`        | `children`   | Move text to JSX children                 |
-| `itemKey`           | `value`      |                                           |
-| `itemIcon`          | `icon` slot  | Pass `<IconComponent />`                  |
-| `ariaLabel`         | `aria-label` |                                           |
-| `linkText`          | —            | Removed                                   |
-| `headerButtonProps` | —            | Removed                                   |
-| `itemCount`         | —            | Removed                                   |
-| `onRenderItemLink`  | —            | Removed                                   |
-| `keytipProps`       | —            | Removed                                   |
-| `alwaysRender`      | —            | Removed; manage rendering in content area |
diff --git a/skills/fluentui-migrate-v8-to-v9/references/tagpicker.md b/skills/fluentui-migrate-v8-to-v9/references/tagpicker.md
deleted file mode 100644
index 7b0f8cf590bd6..0000000000000
--- a/skills/fluentui-migrate-v8-to-v9/references/tagpicker.md
+++ /dev/null
@@ -1,107 +0,0 @@
-# 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
deleted file mode 100644
index badac6d8c0126..0000000000000
--- a/skills/fluentui-migrate-v8-to-v9/references/teachingpopover.md
+++ /dev/null
@@ -1,121 +0,0 @@
-# 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
-
-### Before
-
-```tsx
-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>;
-```
-
-### After
-
-```tsx
-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
deleted file mode 100644
index 7f9d3ae4cde8c..0000000000000
--- a/skills/fluentui-migrate-v8-to-v9/references/text.md
+++ /dev/null
@@ -1,86 +0,0 @@
-# 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
-
-### Before
-
-```tsx
-import { Text } from '@fluentui/react';
-<Text variant="xxLarge" block nowrap>
-  Heading
-</Text>;
-```
-
-### After
-
-```tsx
-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
deleted file mode 100644
index c137511a14096..0000000000000
--- a/skills/fluentui-migrate-v8-to-v9/references/textarea.md
+++ /dev/null
@@ -1,59 +0,0 @@
-# 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
-
-### Before
-
-```tsx
-import { TextField } from '@fluentui/react';
-<TextField
-  label="Comments"
-  multiline
-  required
-  errorMessage={error}
-  value={value}
-  onChange={(_, v) => setValue(v ?? '')}
-/>;
-```
-
-### 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" />
-</Field>;
-```
diff --git a/skills/fluentui-migrate-v8-to-v9/references/theme.md b/skills/fluentui-migrate-v8-to-v9/references/theme.md
deleted file mode 100644
index 5d09d3c259f0b..0000000000000
--- a/skills/fluentui-migrate-v8-to-v9/references/theme.md
+++ /dev/null
@@ -1,230 +0,0 @@
-# Theme Migration
-
-## Provider
-
-```tsx
-// v8
-import { ThemeProvider } from '@fluentui/react';
-<ThemeProvider theme={myTheme}>
-  <App />
-</ThemeProvider>;
-
-// v9
-import { FluentProvider, webLightTheme } from '@fluentui/react-components';
-<FluentProvider theme={webLightTheme}>
-  <App />
-</FluentProvider>;
-```
-
-v8 applies theme values as a JS object on React context. v9 applies theme values as **CSS variables** in the DOM.
-
-## Default Themes
-
-| v8            | v9                       |
-| ------------- | ------------------------ |
-| Default light | `webLightTheme`          |
-| Default dark  | `webDarkTheme`           |
-| High contrast | `teamsHighContrastTheme` |
-| Teams light   | `teamsLightTheme`        |
-| Teams dark    | `teamsDarkTheme`         |
-
-All built-in themes are exported from `@fluentui/react-components`.
-
-## Side-by-Side (v8 + v9)
-
-When running both versions simultaneously, add a `FluentProvider` at every point where you use v9 components:
-
-```tsx
-import { ThemeProvider } from '@fluentui/react';
-import { FluentProvider, webLightTheme } from '@fluentui/react-components';
-
-<ThemeProvider theme={v8Theme}>
-  <FluentProvider theme={webLightTheme}>{/* v9 components here */}</FluentProvider>
-</ThemeProvider>;
-```
-
-## Token Naming
-
-v8 tokens are component-scoped:
-
-```ts
-theme.semanticColors.buttonBackground;
-theme.semanticColors.buttonBackgroundHovered;
-```
-
-v9 tokens are purpose-scoped (neutral/brand + usage + state):
-
-```ts
-tokens.colorNeutralBackground1;
-tokens.colorNeutralBackground1Hover;
-tokens.colorBrandBackground;
-```
-
-Use v9 tokens in `makeStyles`:
-
-```ts
-import { makeStyles, tokens } from '@fluentui/react-components';
-
-const useStyles = makeStyles({
-  root: {
-    backgroundColor: tokens.colorNeutralBackground1,
-    ':hover': { backgroundColor: tokens.colorNeutralBackground1Hover },
-  },
-});
-```
-
-## Styling: mergeStyles → makeStyles
-
-```tsx
-// v8
-import { mergeStyles, mergeStyleSets } from '@fluentui/react';
-
-const containerClass = mergeStyles({ display: 'flex', gap: '8px' });
-const styles = mergeStyleSets({
-  root: { padding: '16px' },
-  title: { fontWeight: 'bold' },
-});
-
-// v9
-import { makeStyles, mergeClasses } from '@fluentui/react-components';
-
-const useStyles = makeStyles({
-  container: { display: 'flex', gap: '8px' },
-  root: { padding: '16px' },
-  title: { fontWeight: 'bold' },
-});
-
-function MyComponent({ extra }: { extra?: string }) {
-  const s = useStyles();
-  return <div className={mergeClasses(s.root, extra)}>{...}</div>;
-}
-```
-
-Key differences:
-
-- `makeStyles` returns a **hook** — call it inside the component
-- `mergeClasses` replaces `mergeStyles` for combining class names
-- Styles are **static** (no function-in-styles) — use component state passed to the hook via parameters if needed
-
-## Dynamic Styles
-
-`makeStyles` is **static** — the style object cannot contain runtime expressions or variables. Use multiple named rules combined with `mergeClasses` instead:
-
-```tsx
-// WRONG — makeStyles does not accept runtime expressions
-const useStyles = makeStyles({
-  root: { color: isError ? 'red' : 'black' }, // ❌ will not work
-});
-
-// CORRECT — define separate rules, merge conditionally
-const useStyles = makeStyles({
-  root: { color: tokens.colorNeutralForeground1 },
-  error: { color: tokens.colorPaletteRedForeground1 },
-  small: { fontSize: '12px' },
-});
-
-function MyComponent({ isError, isSmall }: { isError: boolean; isSmall: boolean }) {
-  const s = useStyles();
-  return <span className={mergeClasses(s.root, isError && s.error, isSmall && s.small)}>text</span>;
-}
-```
-
-For styles that depend on **numeric or string values** (e.g., dynamic width), use inline `style` for the dynamic part and `makeStyles` for the static shell:
-
-```tsx
-// OK — inline style for truly dynamic values
-const useStyles = makeStyles({ root: { display: 'flex' } });
-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
-// v8 — styles prop
-<Button styles={{ root: { color: 'red' }, label: { fontWeight: 'bold' } }} />;
-
-// v9 — className only; no per-slot styles prop
-const useStyles = makeStyles({
-  btn: { color: 'red', fontWeight: 'bold' },
-});
-const s = useStyles();
-<Button className={s.btn} />;
-```
-
-## Custom Theme Migration
-
-### IPalette → BrandVariants
-
-v8 uses `IPalette` (12 neutral + 9 theme colors). v9 uses `BrandVariants` (16-step ramp).
-
-```ts
-// v9 BrandVariants shape — 16 steps from darkest (10) to lightest (160)
-const myBrand: BrandVariants = {
-  10: '#020305',
-  20: '#111723',
-  30: '#16263D',
-  40: '#193253',
-  50: '#1B3F6A',
-  60: '#1B4D83',
-  70: '#1B5C9E',
-  80: '#1A6CB9',
-  90: '#1471BE',
-  100: '#2079C7',
-  110: '#3086CF',
-  120: '#4F9AD6',
-  130: '#6DAEDE',
-  140: '#91C5E8',
-  150: '#B9D9F2',
-  160: '#E0EEF9',
-};
-
-import { createLightTheme, createDarkTheme } from '@fluentui/react-components';
-
-const myLightTheme = createLightTheme(myBrand);
-const myDarkTheme = createDarkTheme(myBrand);
-
-// Usage — dark theme with CSS variable injection:
-<FluentProvider theme={myDarkTheme}>
-  <App />
-</FluentProvider>;
-```
-
-### Theme Shim Utilities
-
-These helpers are published in `@fluentui/react-migration-v8-v9`:
-
-```ts
-import { createV8Theme, createV9Theme, createBrandVariants } from '@fluentui/react-migration-v8-v9';
-```
-
-| Function              | Input                    | Output        | Use case                             |
-| --------------------- | ------------------------ | ------------- | ------------------------------------ |
-| `createV8Theme`       | v9 theme + BrandVariants | v8 theme      | Make v8 components look like v9      |
-| `createV9Theme`       | v8 theme                 | v9 theme      | Keep v9 components looking like v8   |
-| `createBrandVariants` | v8 IPalette              | BrandVariants | Derive v9 brand ramp from v8 palette |
diff --git a/skills/fluentui-migrate-v8-to-v9/references/toolbar.md b/skills/fluentui-migrate-v8-to-v9/references/toolbar.md
deleted file mode 100644
index 284c2c91b3294..0000000000000
--- a/skills/fluentui-migrate-v8-to-v9/references/toolbar.md
+++ /dev/null
@@ -1,263 +0,0 @@
-# Toolbar Migration (CommandBar → Toolbar)
-
-## Architecture Change
-
-v8 `CommandBar` is **data-driven**: items are passed as `ICommandBarItemProps[]` arrays —
-one for primary items, one for overflow items, one for far-right items.
-
-v9 `Toolbar` is **declarative**: items are JSX children using `ToolbarButton`,
-`ToolbarToggleButton`, `ToolbarDivider`, etc. Overflow requires the `Overflow` + `OverflowItem`
-pattern from `@fluentui/react-components`.
-
-## Before / After Example
-
-### Before
-
-```tsx
-import { CommandBar, ICommandBarItemProps } from '@fluentui/react';
-
-const items: ICommandBarItemProps[] = [
-  { key: 'new', text: 'New', iconProps: { iconName: 'Add' }, onClick: handleNew },
-  { key: 'edit', text: 'Edit', iconProps: { iconName: 'Edit' }, onClick: handleEdit },
-  { key: 'delete', text: 'Delete', iconProps: { iconName: 'Delete' }, disabled: true },
-];
-
-const farItems: ICommandBarItemProps[] = [
-  { key: 'info', text: 'Info', iconProps: { iconName: 'Info' }, onClick: handleInfo },
-];
-
-<CommandBar items={items} farItems={farItems} />;
-```
-
-### After
-
-```tsx
-import { Toolbar, ToolbarButton, ToolbarDivider } from '@fluentui/react-components';
-import { AddRegular, EditRegular, DeleteRegular, InfoRegular } from '@fluentui/react-icons';
-import { makeStyles } from '@fluentui/react-components';
-
-const useStyles = makeStyles({ spacer: { marginLeft: 'auto' } });
-
-function MyToolbar() {
-  const s = useStyles();
-  return (
-    <Toolbar>
-      <ToolbarButton icon={<AddRegular />} onClick={handleNew}>
-        New
-      </ToolbarButton>
-      <ToolbarButton icon={<EditRegular />} onClick={handleEdit}>
-        Edit
-      </ToolbarButton>
-      <ToolbarButton icon={<DeleteRegular />} disabled>
-        Delete
-      </ToolbarButton>
-      {/* farItems equivalent: push to far end with marginLeft: auto */}
-      <ToolbarDivider className={s.spacer} />
-      <ToolbarButton icon={<InfoRegular />} onClick={handleInfo}>
-        Info
-      </ToolbarButton>
-    </Toolbar>
-  );
-}
-```
-
-## CommandBarButton → ToolbarButton
-
-`CommandBarButton` maps to `ToolbarButton` when used inside a `CommandBar` / `Toolbar`.
-When used standalone (outside a CommandBar), replace with `Button`.
-
-```tsx
-// v8
-import { CommandBarButton } from '@fluentui/react';
-<CommandBarButton iconProps={{ iconName: 'Add' }}>New</CommandBarButton>;
-
-// v9 — inside Toolbar
-import { ToolbarButton } from '@fluentui/react-components';
-import { AddRegular } from '@fluentui/react-icons';
-<ToolbarButton icon={<AddRegular />}>New</ToolbarButton>;
-```
-
-## Toggle Items
-
-```tsx
-// v8 — checked CommandBar item
-const items: ICommandBarItemProps[] = [
-  { key: 'bold', text: 'Bold', iconProps: { iconName: 'Bold' }, checked: isBold, onClick: toggleBold },
-];
-
-// v9 — ToolbarToggleButton
-import { ToolbarToggleButton } from '@fluentui/react-components';
-import { TextBoldRegular } from '@fluentui/react-icons';
-
-<ToolbarToggleButton icon={<TextBoldRegular />} checked={isBold} onClick={toggleBold}>
-  Bold
-</ToolbarToggleButton>;
-```
-
-## SubMenu Items
-
-```tsx
-// v8 — subMenuProps on a CommandBar item
-const items: ICommandBarItemProps[] = [
-  {
-    key: 'export',
-    text: 'Export',
-    iconProps: { iconName: 'Export' },
-    subMenuProps: {
-      items: [
-        { key: 'csv', text: 'Export as CSV', onClick: exportCsv },
-        { key: 'pdf', text: 'Export as PDF', onClick: exportPdf },
-      ],
-    },
-  },
-];
-
-// v9 — wrap ToolbarButton in Menu as the trigger
-import { Menu, MenuTrigger, MenuPopover, MenuList, MenuItem, ToolbarButton } from '@fluentui/react-components';
-import { ExportRegular } from '@fluentui/react-icons';
-
-<Menu>
-  <MenuTrigger disableButtonEnhancement>
-    <ToolbarButton icon={<ExportRegular />}>Export</ToolbarButton>
-  </MenuTrigger>
-  <MenuPopover>
-    <MenuList>
-      <MenuItem onClick={exportCsv}>Export as CSV</MenuItem>
-      <MenuItem onClick={exportPdf}>Export as PDF</MenuItem>
-    </MenuList>
-  </MenuPopover>
-</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.
-v9 requires the `Overflow` + `OverflowItem` pattern:
-
-```tsx
-import {
-  Toolbar,
-  ToolbarButton,
-  ToolbarDivider,
-  Overflow,
-  OverflowItem,
-  Menu,
-  MenuTrigger,
-  MenuPopover,
-  MenuList,
-  MenuItem,
-  useOverflowMenu,
-  useIsOverflowItemVisible,
-} from '@fluentui/react-components';
-import { AddRegular, EditRegular, DeleteRegular, MoreHorizontalRegular } from '@fluentui/react-icons';
-
-// Overflow menu — shows only items currently hidden by Overflow
-const OverflowMenuItems = () => {
-  const isNew = useIsOverflowItemVisible('new');
-  const isEdit = useIsOverflowItemVisible('edit');
-  const isDelete = useIsOverflowItemVisible('delete');
-  return (
-    <>
-      {!isNew && <MenuItem onClick={handleNew}>New</MenuItem>}
-      {!isEdit && <MenuItem onClick={handleEdit}>Edit</MenuItem>}
-      {!isDelete && <MenuItem disabled>Delete</MenuItem>}
-    </>
-  );
-};
-
-const OverflowMenuButton = () => {
-  const { ref, isOverflowing } = useOverflowMenu<HTMLButtonElement>();
-  if (!isOverflowing) return null;
-  return (
-    <Menu>
-      <MenuTrigger disableButtonEnhancement>
-        <ToolbarButton ref={ref} icon={<MoreHorizontalRegular />} aria-label="More actions" />
-      </MenuTrigger>
-      <MenuPopover>
-        <MenuList>
-          <OverflowMenuItems />
-        </MenuList>
-      </MenuPopover>
-    </Menu>
-  );
-};
-
-function ToolbarWithOverflow() {
-  return (
-    <Overflow>
-      <Toolbar>
-        <OverflowItem id="new">
-          <ToolbarButton icon={<AddRegular />} onClick={handleNew}>
-            New
-          </ToolbarButton>
-        </OverflowItem>
-        <OverflowItem id="edit">
-          <ToolbarButton icon={<EditRegular />} onClick={handleEdit}>
-            Edit
-          </ToolbarButton>
-        </OverflowItem>
-        <OverflowItem id="delete">
-          <ToolbarButton icon={<DeleteRegular />} disabled>
-            Delete
-          </ToolbarButton>
-        </OverflowItem>
-        <OverflowMenuButton />
-      </Toolbar>
-    </Overflow>
-  );
-}
-```
-
-## ICommandBarProps → ToolbarProps
-
-| v8                 | v9                                      | Notes                                                     |
-| ------------------ | --------------------------------------- | --------------------------------------------------------- |
-| `items`            | `children` (`ToolbarButton`, etc.)      | JSX children replace the items array                      |
-| `overflowItems`    | `Overflow` + `OverflowItem` pattern     | See overflow example above                                |
-| `farItems`         | `ToolbarDivider` + `marginLeft: 'auto'` | Push items to the far end with a styled divider or spacer |
-| `buttonAs`         | —                                       | Wrap in `ToolbarButton` directly                          |
-| `overflowButtonAs` | Custom `ToolbarButton` in overflow menu | See overflow example above                                |
-| `className`        | `className`                             |                                                           |
-| `styles`           | `className` + `makeStyles`              |                                                           |
-| `theme`            | `FluentProvider`                        |                                                           |
-
-## ICommandBarItemProps → ToolbarButton Props
-
-| v8 item prop   | v9                                 | Notes                                 |
-| -------------- | ---------------------------------- | ------------------------------------- |
-| `text`         | `children`                         | Move to JSX children                  |
-| `key`          | `key`                              | React key on the JSX element          |
-| `iconProps`    | `icon` slot                        | Pass `<IconComponent />`              |
-| `onClick`      | `onClick`                          |                                       |
-| `disabled`     | `disabled`                         |                                       |
-| `checked`      | `checked` on `ToolbarToggleButton` | Use `ToolbarToggleButton`             |
-| `subMenuProps` | Wrap in `Menu` + `MenuTrigger`     | See subMenu example above             |
-| `split`        | `SplitButton`                      | See button.md for SplitButton pattern |
-| `iconOnly`     | No `children`, add `aria-label`    | Keep `icon` slot, omit text children  |
-| `ariaLabel`    | `aria-label`                       |                                       |
-| `styles`       | `className` + `makeStyles`         |                                       |
diff --git a/skills/fluentui-migrate-v8-to-v9/references/tooltip.md b/skills/fluentui-migrate-v8-to-v9/references/tooltip.md
deleted file mode 100644
index a7615307248ed..0000000000000
--- a/skills/fluentui-migrate-v8-to-v9/references/tooltip.md
+++ /dev/null
@@ -1,132 +0,0 @@
-# Tooltip Migration
-
-## Architecture Change
-
-In v8, `Tooltip` wraps its trigger child and the child does **not** need to be a `forwardRef` component.
-
-In v9, the child of `Tooltip` **is** the trigger and **must** be able to accept a `ref` — meaning it must be either a native DOM element or a component wrapped with `React.forwardRef`. The trigger child automatically receives the necessary ARIA attributes.
-
-## Before / After Example
-
-### Before
-
-```tsx
-import { Tooltip, DirectionalHint } from '@fluentui/react';
-import { DefaultButton } from '@fluentui/react';
-
-<Tooltip content="This button deletes the item" directionalHint={DirectionalHint.bottomCenter}>
-  <DefaultButton text="Delete" />
-</Tooltip>;
-```
-
-### After
-
-```tsx
-import { Tooltip, Button } from '@fluentui/react-components';
-
-<Tooltip content="This button deletes the item" relationship="description" positioning="below">
-  <Button>Delete</Button>
-</Tooltip>;
-```
-
-## `relationship` Prop (required — no v8 equivalent)
-
-The `relationship` prop controls the ARIA semantics of the tooltip:
-
-| `relationship`   | Effect                                          | When to use                                         |
-| ---------------- | ----------------------------------------------- | --------------------------------------------------- |
-| `"description"`  | Adds `aria-describedby` pointing to the tooltip | Tooltip adds context to an already-labelled element |
-| `"label"`        | Adds `aria-labelledby` pointing to the tooltip  | Tooltip IS the accessible name (icon-only buttons)  |
-| `"inaccessible"` | No ARIA wiring                                  | Purely decorative tooltips                          |
-
-**Important:** For icon-only buttons where the tooltip is the accessible name, use `relationship="label"` and remove `aria-label` from the button.
-
-## DirectionalHint → positioning
-
-| v8 `DirectionalHint` | v9 `positioning`  |
-| -------------------- | ----------------- |
-| `topCenter`          | `"above"`         |
-| `topLeftEdge`        | `"above-start"`   |
-| `topRightEdge`       | `"above-end"`     |
-| `topAutoEdge`        | `"above"`         |
-| `bottomCenter`       | `"below"`         |
-| `bottomLeftEdge`     | `"below-start"`   |
-| `bottomRightEdge`    | `"below-end"`     |
-| `bottomAutoEdge`     | `"below"`         |
-| `leftCenter`         | `"before"`        |
-| `leftTopEdge`        | `"before-top"`    |
-| `leftBottomEdge`     | `"before-bottom"` |
-| `rightCenter`        | `"after"`         |
-| `rightTopEdge`       | `"after-top"`     |
-| `rightBottomEdge`    | `"after-bottom"`  |
-
-## Icon-only Button Tooltip
-
-```tsx
-// v8 — title prop or Tooltip wrapping
-import { IconButton } from '@fluentui/react';
-<IconButton iconProps={{ iconName: 'Delete' }} title="Delete item" />;
-
-// v9 — use Tooltip with relationship="label"
-import { Tooltip, Button } from '@fluentui/react-components';
-import { DeleteRegular } from '@fluentui/react-icons';
-
-<Tooltip content="Delete item" relationship="label">
-  <Button icon={<DeleteRegular />} />
-</Tooltip>;
-```
-
-**Do not** add both `aria-label` and `relationship="label"` — that creates duplicate labelling.
-
-## Tooltip on a Custom Component
-
-If wrapping a custom component that does not forward `ref`, use `React.forwardRef`:
-
-```tsx
-// v9 — custom trigger component must forward ref
-const MyTrigger = React.forwardRef<HTMLButtonElement, React.HTMLAttributes<HTMLButtonElement>>((props, ref) => (
-  <button ref={ref} {...props} />
-));
-
-<Tooltip content="Tooltip on custom component" relationship="description">
-  <MyTrigger>Custom trigger</MyTrigger>
-</Tooltip>;
-```
-
-## Controlled Visible State
-
-```tsx
-// v9 — show/hide programmatically
-const [visible, setVisible] = React.useState(false);
-
-<Tooltip
-  content="Programmatic tooltip"
-  relationship="description"
-  visible={visible}
-  onVisibleChange={(_, data) => setVisible(data.visible)}
->
-  <Button onFocus={() => setVisible(true)} onBlur={() => setVisible(false)}>
-    Focus me
-  </Button>
-</Tooltip>;
-```
-
-## ITooltipProps → TooltipProps
-
-| v8                     | v9                         | Notes                                                 |
-| ---------------------- | -------------------------- | ----------------------------------------------------- |
-| `content`              | `content`                  | ReactNode in both                                     |
-| `directionalHint`      | `positioning`              | See table above                                       |
-| `delay`                | `showDelay` / `hideDelay`  | Separate delays in v9; milliseconds                   |
-| `id`                   | —                          | ID is auto-managed via `relationship` ARIA wiring     |
-| `calloutProps`         | —                          | No direct equivalent; use `positioning` for placement |
-| `hostClassName`        | —                          | Removed                                               |
-| `directionalHintFixed` | —                          | Use `positioning` with an offset                      |
-| `isBeakVisible`        | `withArrow`                | `withArrow={true}` shows the arrow                    |
-| `beakWidth`            | —                          | Removed                                               |
-| `onRenderContent`      | `content` slot             | Pass ReactNode to `content`                           |
-| `styles`               | `className` + `makeStyles` |                                                       |
-| `theme`                | `FluentProvider`           |                                                       |
-| —                      | `relationship`             | **Required** — controls ARIA semantics                |
-| —                      | `visible`                  | New — controlled visibility                           |
-| —                      | `onVisibleChange`          | New — `(ev, data) => data.visible`                    |
diff --git a/skills/fluentui-migrate-v8-to-v9/references/tree.md b/skills/fluentui-migrate-v8-to-v9/references/tree.md
deleted file mode 100644
index 25ba1879a3c65..0000000000000
--- a/skills/fluentui-migrate-v8-to-v9/references/tree.md
+++ /dev/null
@@ -1,101 +0,0 @@
-# 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>;
-```
diff --git a/tools/cli/README.md b/tools/cli/README.md
index 29faef280fa36..9307bac1cf43a 100644
--- a/tools/cli/README.md
+++ b/tools/cli/README.md
@@ -1,6 +1,6 @@
 # @fluentui/cli
 
-Command-line tool for Fluent UI — migration analysis, usage reporting, and API metadata extraction.
+Command-line tool for Fluent UI usage reporting and API metadata extraction.
 
 > **⚠️ Experimental** — This package is published under the `experimental` npm tag. APIs and commands may change without notice.
 
@@ -14,21 +14,6 @@ npx @fluentui/cli@experimental <command> [options]
 
 ## Commands
 
-### `migrate`
-
-Run migration analysis and annotation.
-
-```sh
-# List available migrations
-npx @fluentui/cli migrate --list
-
-# Analyze v8 → v9 migration (dry run)
-npx @fluentui/cli migrate v8-to-v9 --path src/ --dryRun
-
-# Annotate source files with migration hints
-npx @fluentui/cli migrate v8-to-v9 --path src/
-```
-
 ### `report`
 
 Generate reports for issue filing or codebase analysis.
diff --git a/tools/cli/eslint.config.cjs b/tools/cli/eslint.config.cjs
index 3d8d982fe7c2e..30f116f219537 100644
--- a/tools/cli/eslint.config.cjs
+++ b/tools/cli/eslint.config.cjs
@@ -5,7 +5,7 @@ const nodeConfig = fluentPlugin.configs['flat/node'];
 /** @type {import("eslint").Linter.Config[]} */
 module.exports = [
   {
-    ignores: ['src/commands/migrate/v8-to-v9/__tests__/fixtures/**', 'src/**/__fixtures__/**'],
+    ignores: ['src/**/__fixtures__/**'],
   },
   ...(Array.isArray(nodeConfig) ? nodeConfig : [nodeConfig]),
 ];
diff --git a/tools/cli/src/cli.ts b/tools/cli/src/cli.ts
index 66c1b0bd2c274..a34461adb521c 100644
--- a/tools/cli/src/cli.ts
+++ b/tools/cli/src/cli.ts
@@ -1,6 +1,5 @@
 import yargs from 'yargs';
 
-import migrateCommand from './commands/migrate';
 import reportCommand from './commands/report';
 import metadataCommand from './commands/metadata';
 
@@ -18,7 +17,6 @@ export async function main(argv: string[]): Promise<void> {
   await yargs(argv)
     .scriptName('fluentui-cli')
     .usage(`${BANNER}\n  $0 <command> [options]`)
-    .command(migrateCommand)
     .command(reportCommand)
     .command(metadataCommand)
     .demandCommand(1, 'You need to specify a command to run.')
diff --git a/tools/cli/src/commands/migrate/README.md b/tools/cli/src/commands/migrate/README.md
deleted file mode 100644
index e798a57aa3941..0000000000000
--- a/tools/cli/src/commands/migrate/README.md
+++ /dev/null
@@ -1,272 +0,0 @@
-# `migrate` command
-
-The `migrate` command performs static analysis on a codebase and inserts structured migration annotations into source files. These annotations serve as a deterministic work queue for human developers or AI agents to execute the actual migration.
-
-## Usage
-
-```bash
-fluentui migrate [migration] [--list]
-```
-
-| Flag     | Alias | Description                   |
-| -------- | ----- | ----------------------------- |
-| `--list` | `-l`  | List all available migrations |
-
-### `migrate v8-to-v9`
-
-Analyzes a directory for Fluent UI v8 (`@fluentui/react`) usage and annotates each migration site with the appropriate action and target.
-
-```bash
-fluentui migrate v8-to-v9 --path <dir> [--dryRun]
-```
-
-| Flag       | Default | Description                                   |
-| ---------- | ------- | --------------------------------------------- |
-| `--path`   | —       | **Required.** Source root to analyze          |
-| `--dryRun` | `false` | Preview annotations without writing any files |
-
-> **Note**: The package must have a `package.json` reachable from `--path` so the analyzer can determine which v9 dependencies are already installed.
-
-## Two-phase migration model
-
-The command implements **phase 1** of a two-phase migration:
-
-1. **Annotate** (this command) — statically detects v8 usage, classifies each finding, and inserts `@fluent-migrate:` comments into source files.
-2. **Execute** (human or AI agent) — consumes annotations as a work queue, applies changes in priority order, removes comments after each fix, and validates the result.
-
-The companion skill at `skills/fluentui-migrate-v8-to-v9/SKILL.md` defines the agent workflow for phase 2.
-
-### Installing the migration skill
-
-After running annotations, install the companion AI agent skill to guide phase 2:
-
-```bash
-npx skills add microsoft/fluentui --skill fluentui-migrate-v8-to-v9
-```
-
-The CLI automatically checks whether the skill is installed and prints this hint when it is missing. See [`skills/README.md`](../../../../../skills/README.md) for full installation options and the supported agent list.
-
-## Annotation format
-
-Annotations are inserted as comments directly above the detected usage site:
-
-```ts
-// @fluent-migrate:<action> | <codemod> | <payload> | <note>
-```
-
-Inside JSX children, block comments are used instead:
-
-```tsx
-{
-  /* @fluent-migrate:<action> | <codemod> | <payload> | <note> */
-}
-```
-
-### Actions
-
-| Action          | Meaning                                                           |
-| --------------- | ----------------------------------------------------------------- |
-| `auto`          | Safe to apply mechanically — a 1:1 rename or straightforward swap |
-| `scaffold`      | Boilerplate structure needed — e.g. wrapping in `<Field>`         |
-| `manual`        | Requires human judgment — multiple valid approaches exist         |
-| `no-equivalent` | No v9 replacement — requires a custom solution or removal         |
-
-## Rules
-
-The analyzer applies a set of rules to each source file. A rule detects a specific v8 pattern and emits one or more annotations.
-
-### `import-paths`
-
-Rewrites `@fluentui/react` imports to their v9 targets.
-
-- Standard specifiers → `auto` to `@fluentui/react-components`
-- Compat components (`Calendar`, `DatePicker`, `TimePicker`) → `manual` to their compat packages
-- Deprecated components with no equivalent → `no-equivalent`
-- Side-effect imports → `auto`
-
-### `component-rename`
-
-Maps v8 component names to their v9 equivalents. Covers three tiers:
-
-- **Auto 1:1 renames** — `Separator→Divider`, `Toggle→Switch`, `Shimmer→Skeleton`, `Fabric→FluentProvider`, `Layer→Portal`, `ProgressIndicator→ProgressBar`, `ChoiceGroup→RadioGroup`, and others
-- **Structural renames** (`manual`) — `Panel→OverlayDrawer`, `Callout→Popover`, `ContextualMenu→Menu`, `Pivot→TabList`, `Modal→Dialog`, and others requiring API restructuring
-- **No equivalent** — handled by the `no-equivalent` rule instead
-
-### `button-variants`
-
-Maps v8 button types to v9 `Button` with the appropriate `appearance`:
-
-| v8               | v9                                                  | Action |
-| ---------------- | --------------------------------------------------- | ------ |
-| `PrimaryButton`  | `Button appearance="primary"`                       | `auto` |
-| `DefaultButton`  | `Button`                                            | `auto` |
-| `ActionButton`   | `Button appearance="transparent"`                   | `auto` |
-| `IconButton`     | `Button` (icon-only, ensure `aria-label`)           | `auto` |
-| `CompoundButton` | `CompoundButton` (`secondaryText→secondaryContent`) | `auto` |
-
-### `prop-rename`
-
-Renames props mechanically:
-
-| v8 prop           | v9 prop            |
-| ----------------- | ------------------ |
-| `ariaLabel`       | `aria-label`       |
-| `ariaHidden`      | `aria-hidden`      |
-| `ariaDescribedBy` | `aria-describedby` |
-| `ariaLabelledBy`  | `aria-labelledby`  |
-| `componentRef`    | `ref`              |
-
-### `icon-props`
-
-Converts `iconProps={{ iconName: 'X' }}` to `icon={<XRegular />}`.
-
-- Known icon names → `auto` (requires `@fluentui/react-icons`)
-- Unknown or dynamic icon names → `manual`
-
-### `dialog-props`
-
-Maps `Dialog`/`Modal` props:
-
-- `hidden` → `open={!expr}` (`auto`)
-- `isOpen` → `open` (`auto`)
-- `onDismiss` → `onOpenChange` (`auto`)
-- `isBlocking` → `modalType="alert"` (`auto`)
-- `dialogContentProps` → `DialogTitle + DialogBody` structure (`scaffold`)
-
-### `enum-to-string`
-
-Replaces v8 enum members with v9 string literals for `MessageBarType`, `SpinnerSize`, `DialogType`, and `CheckboxVisibility`.
-
-### `toggle-props`
-
-Maps `Toggle`-specific props: `inlineLabel→labelPosition`, `onChange` signature rewrite, and marks `onText`/`offText` as `no-equivalent`.
-
-### `progress-bar-props`
-
-Maps `ProgressIndicator` props: `percentComplete→value`, `label→Field wrapper`.
-
-### `label-extraction`
-
-For components whose `label` prop moves to a `<Field>` wrapper (`TextField`, `SpinButton`, `Slider`, `ChoiceGroup`, `Spinner`, `ProgressIndicator`):
-
-- `label` → `scaffold` (wrap in `<Field label="...">`)
-- `onRenderLabel` → `manual`
-
-### `styles-prop`
-
-Detects any `styles` prop on Fluent components and emits `scaffold` — suggests replacing with `makeStyles` and design tokens.
-
-### `remove-theme-prop`
-
-Detects `theme` prop usage and emits `auto`. Adds a note about nested `FluentProvider` if the value is non-trivial.
-
-### `use-boolean`
-
-Detects `useBoolean` from v8 and suggests replacing with `useState`. Emits `auto` inside function components, `manual` otherwise.
-
-### `keycodes`
-
-Detects `KeyCodes` enum usage and maps known members to `event.key` string values (e.g. `KeyCodes.enter→'Enter'`). Unknown members are `manual`.
-
-### `get-id`
-
-Detects `getId` from v8 and suggests replacing with `useId` from v9. Emits `auto` inside function components, `manual` otherwise.
-
-### `no-equivalent`
-
-Flags deprecated components with no v9 replacement: `ActivityItem`, `MarqueeSelection`, `HoverCard`, `ResizeGroup`, `ScrollablePane`, `Announced`, `Stack`, `StackItem`. Each annotation includes a recommended alternative in the note.
-
-## Output
-
-### Summary (write mode)
-
-After annotating, the command prints:
-
-```
-Annotated 12 files
-  auto             34  (safe to apply mechanically)
-  scaffold          8  (boilerplate needed)
-  manual            5  (requires judgment)
-  no-equivalent     2  (no v9 replacement)
-
-Required packages (not in package.json):
-  @fluentui/react-components          — v9 component library
-  @fluentui/react-icons               — icon replacements
-```
-
-### Dry-run mode
-
-With `--dryRun`, no files are modified. The command prints the same counts plus a list of files that would be annotated.
-
-### Metadata file
-
-After writing annotations, the command creates `.fluent-migrate/metadata.json` in the project root:
-
-```json
-{
-  "version": 1,
-  "annotatedFiles": ["src/App.tsx", "src/components/Header.tsx"]
-}
-```
-
-This file is consumed by the migration skill as the deterministic work queue.
-
-## Architecture
-
-```
-migrate/
-├── index.ts                          # Parent command — registers subcommands, --list flag
-├── v8-to-v9/
-│   ├── index.ts                      # Yargs subcommand definition (--path, --dryRun)
-│   ├── handler.ts                    # Orchestrates analyze → write → summary
-│   ├── utils/annotator/
-│   │   ├── index.ts                  # Public API (analyzeFiles, writeAnnotations)
-│   │   ├── types.ts                  # AnnotationAction, Annotation, FileAnalysis types
-│   │   ├── analyzer.ts              # File discovery, ts-morph parsing, rule execution
-│   │   ├── writer.ts                # Comment insertion, idempotency, metadata.json output
-│   │   └── rules/
-│   │       ├── utils.ts             # Shared helpers (getFluentImportNames, isJsxChild)
-│   │       ├── import-paths.ts
-│   │       ├── component-rename.ts
-│   │       ├── button-variants.ts
-│   │       ├── prop-rename.ts
-│   │       ├── icon-props.ts
-│   │       ├── dialog-props.ts
-│   │       ├── enum-to-string.ts
-│   │       ├── toggle-props.ts
-│   │       ├── progress-bar-props.ts
-│   │       ├── label-extraction.ts
-│   │       ├── styles-prop.ts
-│   │       ├── remove-theme-prop.ts
-│   │       ├── use-boolean.ts
-│   │       ├── keycodes.ts
-│   │       ├── get-id.ts
-│   │       └── no-equivalent.ts
-│   └── __tests__/
-│       ├── handler.spec.ts           # Unit tests (mocked analyzer/writer)
-│       ├── handler.integration.spec.ts # Integration tests (real files + temp dirs)
-│       └── fixtures/                 # Sample .tsx files exercising each rule
-└── README.md                         # This file
-```
-
-### How it works
-
-1. **Package detection** — walks up from `--path` to find the nearest `package.json` and reads installed dependencies
-2. **File discovery** — scans `**/*.ts` and `**/*.tsx` under `--path`, skipping `node_modules` and `.d.ts` files
-3. **Import extraction** — uses ts-morph to find all names imported from `@fluentui/react`
-4. **Rule execution** — each rule inspects the AST for specific v8 patterns and emits typed annotations with line numbers
-5. **Annotation writing** — inserts comments above each target node, preserving indentation and handling JSX context; sorts annotations by line descending to avoid offset drift
-6. **Idempotency** — re-running the command on already-annotated files skips duplicate annotations
-7. **Metadata output** — writes `.fluent-migrate/metadata.json` listing all annotated files
-
-## Testing
-
-```bash
-# Run all migrate tests
-yarn nx run cli:test -- --testPathPatterns=migrate
-
-# Run full CLI test suite
-yarn nx run cli:test
-```
-
-Tests use a fixture-based approach with sample `.tsx` files in `__tests__/fixtures/` covering each rule. Integration tests create temporary directories, run the real analyzer and writer, and verify annotation content, idempotency, indentation, and metadata output.
diff --git a/tools/cli/src/commands/migrate/index.ts b/tools/cli/src/commands/migrate/index.ts
deleted file mode 100644
index 51599bd1bac4a..0000000000000
--- a/tools/cli/src/commands/migrate/index.ts
+++ /dev/null
@@ -1,29 +0,0 @@
-import type { CommandModule } from 'yargs';
-import v8ToV9Command from './v8-to-v9';
-
-const AVAILABLE_MIGRATIONS = ['v8-to-v9'];
-
-const command: CommandModule = {
-  command: 'migrate [migration]',
-  describe: 'Run migration analysis and annotation',
-  builder: yargs =>
-    yargs
-      .command(v8ToV9Command)
-      .option('list', {
-        alias: 'l',
-        type: 'boolean',
-        description: 'List all available migrations',
-      })
-      .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__/fixtures/button-variants.tsx b/tools/cli/src/commands/migrate/v8-to-v9/__tests__/fixtures/button-variants.tsx
deleted file mode 100644
index 235a77770f2b6..0000000000000
--- a/tools/cli/src/commands/migrate/v8-to-v9/__tests__/fixtures/button-variants.tsx
+++ /dev/null
@@ -1,10 +0,0 @@
-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
deleted file mode 100644
index c2795a30e8fc3..0000000000000
--- a/tools/cli/src/commands/migrate/v8-to-v9/__tests__/fixtures/icon-known.tsx
+++ /dev/null
@@ -1,3 +0,0 @@
-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
deleted file mode 100644
index 323d0c4c62914..0000000000000
--- a/tools/cli/src/commands/migrate/v8-to-v9/__tests__/fixtures/icon-unknown.tsx
+++ /dev/null
@@ -1,3 +0,0 @@
-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
deleted file mode 100644
index 3550c4730fe93..0000000000000
--- a/tools/cli/src/commands/migrate/v8-to-v9/__tests__/fixtures/import-paths.tsx
+++ /dev/null
@@ -1,3 +0,0 @@
-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
deleted file mode 100644
index 26fe7c2284e3a..0000000000000
--- a/tools/cli/src/commands/migrate/v8-to-v9/__tests__/fixtures/indented.tsx
+++ /dev/null
@@ -1,7 +0,0 @@
-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
deleted file mode 100644
index 7b958ff6167e8..0000000000000
--- a/tools/cli/src/commands/migrate/v8-to-v9/__tests__/fixtures/multi-annotation.tsx
+++ /dev/null
@@ -1,8 +0,0 @@
-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
deleted file mode 100644
index ba5509b6ab8b5..0000000000000
--- a/tools/cli/src/commands/migrate/v8-to-v9/__tests__/fixtures/multi-import.tsx
+++ /dev/null
@@ -1,8 +0,0 @@
-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
deleted file mode 100644
index 2bc6e1ed08fd5..0000000000000
--- a/tools/cli/src/commands/migrate/v8-to-v9/__tests__/fixtures/no-equivalent.tsx
+++ /dev/null
@@ -1,8 +0,0 @@
-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
deleted file mode 100644
index 90adb1d0b0b3d..0000000000000
--- a/tools/cli/src/commands/migrate/v8-to-v9/__tests__/fixtures/prop-rename.tsx
+++ /dev/null
@@ -1,5 +0,0 @@
-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
deleted file mode 100644
index 289b784a4921b..0000000000000
--- a/tools/cli/src/commands/migrate/v8-to-v9/__tests__/fixtures/styles-prop.tsx
+++ /dev/null
@@ -1,3 +0,0 @@
-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
deleted file mode 100644
index ee538844d2f6e..0000000000000
--- a/tools/cli/src/commands/migrate/v8-to-v9/__tests__/fixtures/unrelated.tsx
+++ /dev/null
@@ -1,4 +0,0 @@
-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
deleted file mode 100644
index 14105269b3367..0000000000000
--- a/tools/cli/src/commands/migrate/v8-to-v9/__tests__/handler.integration.spec.ts
+++ /dev/null
@@ -1,355 +0,0 @@
-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';
-import { handler } from '../handler';
-
-// Mock the skill-check module to avoid spawning `npx` in every handler test.
-// The `isSkillInstalled` function calls `execFileSync('npx', …)` which takes ~3s
-// per invocation and causes CI timeouts on slower runners.
-// skill-check logic is independently covered by skill-check.spec.ts.
-jest.mock('../utils/skill-check', () => ({
-  isSkillInstalled: jest.fn().mockReturnValue(true),
-  printSkillHint: jest.fn(),
-}));
-
-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);
-      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');
-      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.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);
-    });
-
-    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.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 () => {
-      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 === '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 () => {
-      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>
-        );
-        "
-      `);
-    });
-
-    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 ───────────────────────────────────────────────────────
-
-  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('dryRun 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('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('[dryRun]'))).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:auto | import-paths |');
-      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);
-    });
-
-    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
deleted file mode 100644
index a91b5b548504e..0000000000000
--- a/tools/cli/src/commands/migrate/v8-to-v9/__tests__/handler.spec.ts
+++ /dev/null
@@ -1,138 +0,0 @@
-import { handler } from '../handler';
-import * as annotator from '../utils/annotator';
-import * as skillCheck from '../utils/skill-check';
-import * as fs from 'fs/promises';
-
-jest.mock('../utils/annotator');
-jest.mock('../utils/skill-check');
-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>;
-const mockIsSkillInstalled = skillCheck.isSkillInstalled as jest.MockedFunction<typeof skillCheck.isSkillInstalled>;
-const mockPrintSkillHint = skillCheck.printSkillHint as jest.MockedFunction<typeof skillCheck.printSkillHint>;
-
-describe('migrate v8-to-v9 handler', () => {
-  let logSpy: jest.SpyInstance;
-
-  beforeEach(() => {
-    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>>);
-    // Default: skill is installed (suppress hint)
-    mockIsSkillInstalled.mockReturnValue(true);
-  });
-
-  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).toHaveBeenCalledWith(expect.any(Array), 'src/');
-  });
-
-  it('skips writeAnnotations in dryRun 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 file'));
-    expect(logSpy).toHaveBeenCalledWith(expect.stringContaining('auto'));
-    expect(logSpy).toHaveBeenCalledWith(expect.stringContaining('manual'));
-  });
-
-  it('prints [dryRun] 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('[dryRun]'));
-    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();
-  });
-
-  it('prints skill install hint when skill is not found', async () => {
-    mockAnalyzeFiles.mockResolvedValue([]);
-    mockWriteAnnotations.mockResolvedValue({ filesChanged: 0 });
-    mockIsSkillInstalled.mockReturnValue(false);
-
-    await handler({ path: 'src/', dryRun: false, _: [], $0: 'fluentui-cli' });
-
-    expect(mockIsSkillInstalled).toHaveBeenCalled();
-    expect(mockPrintSkillHint).toHaveBeenCalled();
-  });
-
-  it('does not print skill hint when skill is already installed', async () => {
-    mockAnalyzeFiles.mockResolvedValue([]);
-    mockWriteAnnotations.mockResolvedValue({ filesChanged: 0 });
-    mockIsSkillInstalled.mockReturnValue(true);
-
-    await handler({ path: 'src/', dryRun: false, _: [], $0: 'fluentui-cli' });
-
-    expect(mockPrintSkillHint).not.toHaveBeenCalled();
-  });
-
-  it('prints skill install hint in dryRun mode when skill is not found', async () => {
-    mockAnalyzeFiles.mockResolvedValue([]);
-    mockIsSkillInstalled.mockReturnValue(false);
-
-    await handler({ path: 'src/', dryRun: true, _: [], $0: 'fluentui-cli' });
-
-    expect(mockPrintSkillHint).toHaveBeenCalled();
-    expect(mockWriteAnnotations).not.toHaveBeenCalled();
-  });
-});
diff --git a/tools/cli/src/commands/migrate/v8-to-v9/__tests__/skill-check.spec.ts b/tools/cli/src/commands/migrate/v8-to-v9/__tests__/skill-check.spec.ts
deleted file mode 100644
index 5c578756036b9..0000000000000
--- a/tools/cli/src/commands/migrate/v8-to-v9/__tests__/skill-check.spec.ts
+++ /dev/null
@@ -1,55 +0,0 @@
-import { execFileSync } from 'child_process';
-import { isSkillInstalled, printSkillHint } from '../utils/skill-check';
-
-jest.mock('child_process');
-
-const mockExecFileSync = execFileSync as jest.MockedFunction<typeof execFileSync>;
-
-describe('skill-check', () => {
-  beforeEach(() => {
-    jest.clearAllMocks();
-  });
-
-  describe('isSkillInstalled', () => {
-    it('returns true when skills list output contains the skill name', () => {
-      mockExecFileSync.mockReturnValue(
-        'Project Skills\n\nfluentui-migrate-v8-to-v9 ~/project/skills/fluentui-migrate-v8-to-v9\n  Agents: Claude Code\n',
-      );
-
-      expect(isSkillInstalled()).toBe(true);
-    });
-
-    it('returns false when skills list output does not contain the skill name', () => {
-      mockExecFileSync.mockReturnValue('No project skills found.\nTry listing global skills with -g\n');
-
-      expect(isSkillInstalled()).toBe(false);
-    });
-
-    it('returns false when npx skills command fails', () => {
-      mockExecFileSync.mockImplementation(() => {
-        throw new Error('command not found');
-      });
-
-      expect(isSkillInstalled()).toBe(false);
-    });
-  });
-
-  describe('printSkillHint', () => {
-    let logSpy: jest.SpyInstance;
-
-    beforeEach(() => {
-      logSpy = jest.spyOn(console, 'log').mockImplementation();
-    });
-
-    afterEach(() => {
-      logSpy.mockRestore();
-    });
-
-    it('prints npx skills add command', () => {
-      printSkillHint();
-
-      const output = logSpy.mock.calls.map((args: unknown[]) => args[0]).join('\n');
-      expect(output).toContain('npx skills add microsoft/fluentui --skill fluentui-migrate-v8-to-v9');
-    });
-  });
-});
diff --git a/tools/cli/src/commands/migrate/v8-to-v9/handler.ts b/tools/cli/src/commands/migrate/v8-to-v9/handler.ts
deleted file mode 100644
index a565846e03005..0000000000000
--- a/tools/cli/src/commands/migrate/v8-to-v9/handler.ts
+++ /dev/null
@@ -1,117 +0,0 @@
-import * as fs from 'fs/promises';
-import type { CommandHandler } from '../../../utils/types';
-import { analyzeFiles, writeAnnotations } from './utils/annotator';
-import type { FileAnalysis } from './utils/annotator';
-import { isSkillInstalled, printSkillHint } from './utils/skill-check';
-
-interface V8ToV9Args {
-  path: string;
-  dryRun: boolean;
-}
-
-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) {
-    printDryRunReport(results);
-    printSkillHintIfNeeded();
-    return;
-  }
-
-  const { filesChanged } = await writeAnnotations(results, argv.path);
-  printSummary(results, filesChanged);
-  printSkillHintIfNeeded();
-};
-
-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} ${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)`);
-  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[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)`);
-  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)`);
-    }
-  }
-}
-
-function printSkillHintIfNeeded(): void {
-  if (!isSkillInstalled()) {
-    printSkillHint();
-  }
-}
diff --git a/tools/cli/src/commands/migrate/v8-to-v9/index.ts b/tools/cli/src/commands/migrate/v8-to-v9/index.ts
deleted file mode 100644
index a4424b73432b0..0000000000000
--- a/tools/cli/src/commands/migrate/v8-to-v9/index.ts
+++ /dev/null
@@ -1,31 +0,0 @@
-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('dryRun', {
-        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/analyzer.ts b/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/analyzer.ts
deleted file mode 100644
index cdd0da59728ff..0000000000000
--- a/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/analyzer.ts
+++ /dev/null
@@ -1,135 +0,0 @@
-import * as fs from 'fs/promises';
-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',
-  },
-];
-
-/**
- * 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,
-    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, 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) && !installedPackages.has(dep.name),
-    ).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
deleted file mode 100644
index 3fd2ac563b183..0000000000000
--- a/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/index.ts
+++ /dev/null
@@ -1,3 +0,0 @@
-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
deleted file mode 100644
index 2e8cf8dec2d03..0000000000000
--- a/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/button-variants.ts
+++ /dev/null
@@ -1,59 +0,0 @@
-import type { SourceFile, Node } from 'ts-morph';
-import { SyntaxKind } from 'ts-morph';
-import type { AnnotationResult } from '../types';
-import { 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, fluentNames: Set<string>): AnnotationResult[] {
-  const results: AnnotationResult[] = [];
-
-  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
deleted file mode 100644
index 900c20c57ccba..0000000000000
--- a/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/component-rename.ts
+++ /dev/null
@@ -1,238 +0,0 @@
-import type { SourceFile, Node } from 'ts-morph';
-import { SyntaxKind } from 'ts-morph';
-import type { AnnotationResult } from '../types';
-import { 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',
-  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. */
-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',
-  },
-  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[] {
-  const results: AnnotationResult[] = [];
-
-  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);
-    const line = node.getStartLineNumber();
-
-    if (AUTO_RENAMES[tagName]) {
-      results.push({
-        action: 'auto',
-        codemod: 'component-rename',
-        payload: `${tagName} → ${AUTO_RENAMES[tagName]}`,
-        line,
-        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,
-        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,
-      });
-    }
-  });
-
-  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
deleted file mode 100644
index 2523e6b2a59e4..0000000000000
--- a/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/dialog-props.ts
+++ /dev/null
@@ -1,62 +0,0 @@
-import type { SourceFile, Node } from 'ts-morph';
-import { SyntaxKind } from 'ts-morph';
-import type { AnnotationResult } from '../types';
-
-const DIALOG_COMPONENTS = new Set(['Dialog', 'Modal']);
-
-export function detectDialogProps(sourceFile: SourceFile, fluentNames: Set<string>): AnnotationResult[] {
-  const results: AnnotationResult[] = [];
-
-  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
deleted file mode 100644
index 84309b6f3ce25..0000000000000
--- a/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/enum-to-string.ts
+++ /dev/null
@@ -1,70 +0,0 @@
-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
deleted file mode 100644
index dd5fd95622fb9..0000000000000
--- a/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/get-id.ts
+++ /dev/null
@@ -1,45 +0,0 @@
-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
deleted file mode 100644
index 9c82a357ddf2c..0000000000000
--- a/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/icon-props.ts
+++ /dev/null
@@ -1,199 +0,0 @@
-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.
-// The v9 icon name is the v8 name + "Regular" suffix (e.g. Add → AddRegular).
-const KNOWN_ICONS = new Set([
-  // Navigation & actions
-  'Add',
-  'AddCircle',
-  'ArrowClockwise',
-  'ArrowCounterclockwise',
-  'ArrowDown',
-  'ArrowDownload',
-  'ArrowLeft',
-  'ArrowRight',
-  'ArrowUp',
-  'ArrowUpload',
-  'Attach',
-  'Backspace',
-  'Bookmark',
-  'BookmarkAdd',
-  'Calendar',
-  'CalendarAdd',
-  'Call',
-  'Camera',
-  'Cancel',
-  'CheckMark',
-  'ChevronDown',
-  'ChevronLeft',
-  'ChevronRight',
-  'ChevronUp',
-  'CircleSmall',
-  'ClipboardPaste',
-  'Clock',
-  'Close',
-  'Cloud',
-  'CloudArrowUp',
-  'Code',
-  'Color',
-  'Comment',
-  'CommentAdd',
-  'Copy',
-  'Cut',
-  'DataBar',
-  'Delete',
-  'Dismiss',
-  'Document',
-  'DocumentAdd',
-  'DocumentCopy',
-  'DocumentEdit',
-  'Download',
-  'Edit',
-  'Emoji',
-  'Error',
-  'Eye',
-  'EyeOff',
-  'Filter',
-  'Flag',
-  'Folder',
-  'FolderAdd',
-  'FolderOpen',
-  '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',
-  'Video',
-  'VideoOff',
-  'Warning',
-  'Wrench',
-  'ZoomIn',
-  'ZoomOut',
-]);
-
-export function detectIconProps(sourceFile: SourceFile, fluentNames: Set<string>): AnnotationResult[] {
-  const results: AnnotationResult[] = [];
-
-  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
deleted file mode 100644
index 915f67b29e77a..0000000000000
--- a/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/import-paths.ts
+++ /dev/null
@@ -1,74 +0,0 @@
-import type { SourceFile } from 'ts-morph';
-import type { AnnotationResult } from '../types';
-import { DEPRECATED_COMPONENT_NAMES } from './no-equivalent';
-
-/** 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()) {
-    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 => 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()} → ${pkg}`,
-        note: `split import; move specifier to a separate "import { ... } from '${pkg}'"`,
-        line,
-      });
-    }
-
-    const hasEquivSpecifiers = namedImports.some(
-      s => !DEPRECATED_COMPONENT_NAMES.has(s.getName()) && !COMPAT_PACKAGES[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
deleted file mode 100644
index 692189af1e876..0000000000000
--- a/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/keycodes.ts
+++ /dev/null
@@ -1,74 +0,0 @@
-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
deleted file mode 100644
index ede5e1d50f9ae..0000000000000
--- a/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/label-extraction.ts
+++ /dev/null
@@ -1,54 +0,0 @@
-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', '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[] = [];
-
-  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="..."><${V9_NAME[tagName] ?? 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
deleted file mode 100644
index 7889d9decfedf..0000000000000
--- a/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/no-equivalent.ts
+++ /dev/null
@@ -1,44 +0,0 @@
-import type { SourceFile, Node } from 'ts-morph';
-import { SyntaxKind } from 'ts-morph';
-import type { AnnotationResult } from '../types';
-import { 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">',
-  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[] = [];
-
-  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,
-      note: 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
deleted file mode 100644
index bf7a43a8cfc96..0000000000000
--- a/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/progress-bar-props.ts
+++ /dev/null
@@ -1,40 +0,0 @@
-import type { SourceFile, Node } from 'ts-morph';
-import { SyntaxKind } from 'ts-morph';
-import type { AnnotationResult } from '../types';
-
-export function detectProgressBarProps(sourceFile: SourceFile, fluentNames: Set<string>): AnnotationResult[] {
-  const results: AnnotationResult[] = [];
-
-  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
deleted file mode 100644
index 66f526c292fcd..0000000000000
--- a/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/prop-rename.ts
+++ /dev/null
@@ -1,42 +0,0 @@
-import type { SourceFile, Node } from 'ts-morph';
-import { SyntaxKind } from 'ts-morph';
-import type { AnnotationResult } from '../types';
-
-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, fluentNames: Set<string>): AnnotationResult[] {
-  const results: AnnotationResult[] = [];
-
-  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
deleted file mode 100644
index d2ef452458c47..0000000000000
--- a/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/remove-theme-prop.ts
+++ /dev/null
@@ -1,41 +0,0 @@
-import type { SourceFile, Node } from 'ts-morph';
-import { SyntaxKind } from 'ts-morph';
-import type { AnnotationResult } from '../types';
-
-export function detectRemoveThemeProp(sourceFile: SourceFile, fluentNames: Set<string>): AnnotationResult[] {
-  const results: AnnotationResult[] = [];
-
-  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
deleted file mode 100644
index 2bc2e9ecee0d8..0000000000000
--- a/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/styles-prop.ts
+++ /dev/null
@@ -1,35 +0,0 @@
-import type { SourceFile, Node } from 'ts-morph';
-import { SyntaxKind } from 'ts-morph';
-import type { AnnotationResult } from '../types';
-
-export function detectStylesProp(sourceFile: SourceFile, fluentNames: Set<string>): AnnotationResult[] {
-  const results: AnnotationResult[] = [];
-
-  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
deleted file mode 100644
index 675af0c04404a..0000000000000
--- a/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/toggle-props.ts
+++ /dev/null
@@ -1,54 +0,0 @@
-import type { SourceFile, Node } from 'ts-morph';
-import { SyntaxKind } from 'ts-morph';
-import type { AnnotationResult } from '../types';
-
-export function detectToggleProps(sourceFile: SourceFile, fluentNames: Set<string>): AnnotationResult[] {
-  const results: AnnotationResult[] = [];
-
-  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: 'no-equivalent',
-            payload: propName,
-            note: 'v9 Switch has no on/off labels — remove the prop or build a 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
deleted file mode 100644
index 1668716c36155..0000000000000
--- a/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/use-boolean.ts
+++ /dev/null
@@ -1,66 +0,0 @@
-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
deleted file mode 100644
index 0d302c503eab5..0000000000000
--- a/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/rules/utils.ts
+++ /dev/null
@@ -1,36 +0,0 @@
-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
deleted file mode 100644
index d86d7d8b60a9e..0000000000000
--- a/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/types.ts
+++ /dev/null
@@ -1,27 +0,0 @@
-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 }>;
-}
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
deleted file mode 100644
index 9d78062efb5d1..0000000000000
--- a/tools/cli/src/commands/migrate/v8-to-v9/utils/annotator/writer.ts
+++ /dev/null
@@ -1,110 +0,0 @@
-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';
-
-/**
- * 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) {
-    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 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.
- */
-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;
-    }
-
-    const content = await fs.readFile(file.filePath, 'utf8');
-    const lines = content.split('\n');
-
-    // 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 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);
-
-      // Search backward through the annotation block above the target for an identical comment
-      if (annotationAlreadyPresent(lines, targetLine, comment)) {
-        continue;
-      }
-
-      // Determine indentation from the target line
-      const indent = lines[targetLine]?.match(/^(\s*)/)?.[1] ?? '';
-
-      lines.splice(targetLine, 0, `${indent}${comment}`);
-      sameLineInsertions.set(annotation.line, existingInsertions + 1);
-      changed = true;
-    }
-
-    if (changed) {
-      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 };
-}
diff --git a/tools/cli/src/commands/migrate/v8-to-v9/utils/skill-check.ts b/tools/cli/src/commands/migrate/v8-to-v9/utils/skill-check.ts
deleted file mode 100644
index a909bd6b828da..0000000000000
--- a/tools/cli/src/commands/migrate/v8-to-v9/utils/skill-check.ts
+++ /dev/null
@@ -1,26 +0,0 @@
-import { execFileSync } from 'child_process';
-
-const SKILL_NAME = 'fluentui-migrate-v8-to-v9';
-
-/**
- * Check whether the `fluentui-migrate-v8-to-v9` skill is installed
- * by delegating to `npx skills list`.
- */
-export function isSkillInstalled(): boolean {
-  try {
-    const output = execFileSync('npx', ['--no-install', 'skills', 'list'], {
-      timeout: 15_000,
-      encoding: 'utf8',
-      stdio: ['ignore', 'pipe', 'ignore'],
-    });
-    return output.includes(SKILL_NAME);
-  } catch {
-    return false;
-  }
-}
-
-export function printSkillHint(): void {
-  console.log('\nNext step — install the migration skill for your coding agent:');
-  console.log('  npx skills add microsoft/fluentui --skill fluentui-migrate-v8-to-v9');
-  console.log('\nThe skill guides AI agents through the annotation-driven migration process.');
-}