From 66d437ba1809032765dd0cd0ce63f8ac3f2c4c18 Mon Sep 17 00:00:00 2001
From: Adrien Zheng <adrien.zheng@coinbase.com>
Date: Wed, 11 Feb 2026 11:47:02 -0500
Subject: [PATCH 1/5] infra

---
 packages/migrator/.gitignore                  |  14 +
 packages/migrator/.npmignore                  |  12 +
 packages/migrator/README.md                   | 176 +++++
 packages/migrator/babel.config.cjs            |  22 +
 packages/migrator/docs/CLI_REFERENCE.md       | 558 ++++++++++++++++
 packages/migrator/docs/CONFIGURATION.md       | 614 ++++++++++++++++++
 packages/migrator/docs/HISTORY.md             | 432 ++++++++++++
 packages/migrator/docs/QUICK_START.md         | 371 +++++++++++
 packages/migrator/docs/UTILITIES.md           | 520 +++++++++++++++
 packages/migrator/docs/WRITING_TRANSFORMS.md  | 431 ++++++++++++
 packages/migrator/package.json                |  47 ++
 packages/migrator/project.json                |  38 ++
 packages/migrator/src/cli-args.ts             |  82 +++
 packages/migrator/src/cli.ts                  | 455 +++++++++++++
 packages/migrator/src/index.ts                |   9 +
 packages/migrator/src/runner.ts               | 124 ++++
 packages/migrator/src/types.ts                | 118 ++++
 packages/migrator/src/utils/config-loader.ts  | 155 +++++
 packages/migrator/src/utils/constants.ts      |   6 +
 packages/migrator/src/utils/index.ts          |   9 +
 packages/migrator/src/utils/insert-todo.ts    | 135 ++++
 packages/migrator/src/utils/logger.ts         | 200 ++++++
 .../migrator/src/utils/migration-history.ts   | 204 ++++++
 packages/migrator/src/v8-to-v9/config.json    |  65 ++
 packages/migrator/src/v8-to-v9/index.ts       |  35 +
 .../migrator/src/v8-to-v9/transforms/.gitkeep |   2 +
 .../v8-to-v9/transforms/example-transform.ts  |  90 +++
 packages/migrator/tsconfig.build.json         |  19 +
 packages/migrator/tsconfig.json               |  12 +
 yarn.lock                                     | 273 +++++++-
 30 files changed, 5205 insertions(+), 23 deletions(-)
 create mode 100644 packages/migrator/.gitignore
 create mode 100644 packages/migrator/.npmignore
 create mode 100644 packages/migrator/README.md
 create mode 100644 packages/migrator/babel.config.cjs
 create mode 100644 packages/migrator/docs/CLI_REFERENCE.md
 create mode 100644 packages/migrator/docs/CONFIGURATION.md
 create mode 100644 packages/migrator/docs/HISTORY.md
 create mode 100644 packages/migrator/docs/QUICK_START.md
 create mode 100644 packages/migrator/docs/UTILITIES.md
 create mode 100644 packages/migrator/docs/WRITING_TRANSFORMS.md
 create mode 100644 packages/migrator/package.json
 create mode 100644 packages/migrator/project.json
 create mode 100644 packages/migrator/src/cli-args.ts
 create mode 100644 packages/migrator/src/cli.ts
 create mode 100644 packages/migrator/src/index.ts
 create mode 100644 packages/migrator/src/runner.ts
 create mode 100644 packages/migrator/src/types.ts
 create mode 100644 packages/migrator/src/utils/config-loader.ts
 create mode 100644 packages/migrator/src/utils/constants.ts
 create mode 100644 packages/migrator/src/utils/index.ts
 create mode 100644 packages/migrator/src/utils/insert-todo.ts
 create mode 100644 packages/migrator/src/utils/logger.ts
 create mode 100644 packages/migrator/src/utils/migration-history.ts
 create mode 100644 packages/migrator/src/v8-to-v9/config.json
 create mode 100644 packages/migrator/src/v8-to-v9/index.ts
 create mode 100644 packages/migrator/src/v8-to-v9/transforms/.gitkeep
 create mode 100644 packages/migrator/src/v8-to-v9/transforms/example-transform.ts
 create mode 100644 packages/migrator/tsconfig.build.json
 create mode 100644 packages/migrator/tsconfig.json

diff --git a/packages/migrator/.gitignore b/packages/migrator/.gitignore
new file mode 100644
index 000000000..42ff955ac
--- /dev/null
+++ b/packages/migrator/.gitignore
@@ -0,0 +1,14 @@
+# Build outputs
+esm/
+dts/
+*.tsbuildinfo
+
+# Node modules
+node_modules/
+
+# Migration history files (user-specific)
+.cds-migration-history.json
+
+# Logs
+*.log
+migration.log
diff --git a/packages/migrator/.npmignore b/packages/migrator/.npmignore
new file mode 100644
index 000000000..a0af7f8f7
--- /dev/null
+++ b/packages/migrator/.npmignore
@@ -0,0 +1,12 @@
+src/
+tsconfig.json
+tsconfig.build.json
+babel.config.cjs
+project.json
+__tests__/
+__stories__/
+__mocks__/
+__fixtures__/
+*.test.*
+*.spec.*
+*.stories.*
diff --git a/packages/migrator/README.md b/packages/migrator/README.md
new file mode 100644
index 000000000..bf24ea244
--- /dev/null
+++ b/packages/migrator/README.md
@@ -0,0 +1,176 @@
+# @coinbase/cds-migrator
+
+Code migration tools for the Coinbase Design System.
+
+## Quick Start
+
+```bash
+# Interactive mode (recommended)
+npx @coinbase/cds-migrator
+
+# Non-interactive mode
+npx @coinbase/cds-migrator -m v8-to-v9 -p ./src --all --dry-run
+```
+
+**→ See [Quick Start Guide](./docs/QUICK_START.md) for complete walkthrough.**
+
+## Features
+
+- 🎯 **Granular Selection** - Migrate everything or choose specific components/hooks/utilities
+- 📝 **History Tracking** - Automatically prevents duplicate migrations
+- 🔍 **Dry-Run Mode** - Preview all changes before applying
+- 📊 **Comprehensive Logging** - Track successes, warnings, and manual TODOs
+- 💬 **TODO Comments** - Automatically marks code that needs manual review
+- 🌳 **Configuration-Based** - Three-level structure (categories → variables → transforms)
+
+## Supported Migrations
+
+| Version     | Description                                          | Status       |
+| ----------- | ---------------------------------------------------- | ------------ |
+| **v8 → v9** | Component API updates, hook changes, utility updates | ✅ Available |
+
+## Documentation
+
+### 📘 For Users
+
+Start here if you're using the migrator to upgrade your codebase:
+
+1. **[Quick Start Guide](./docs/QUICK_START.md)** ⭐
+   - Get up and running in 5 minutes
+   - Your first migration walkthrough
+   - Common workflows and troubleshooting
+
+2. **[CLI Reference](./docs/CLI_REFERENCE.md)** ⭐
+   - Interactive and non-interactive modes
+   - Selection options and "All" shortcuts
+   - CLI flags reference
+   - CI/CD integration examples
+
+3. **[Migration History](./docs/HISTORY.md)**
+   - How duplicate prevention works
+   - Understanding the history file
+   - Clearing history
+   - Team collaboration guidelines
+
+### 🔧 For Contributors
+
+Read these if you're adding new migrations or transforms:
+
+4. **[Configuration Guide](./docs/CONFIGURATION.md)** ⭐
+   - Three-level structure explained
+   - Adding new migration versions
+   - Adding transforms to existing migrations
+   - Configuration best practices
+
+5. **[Writing Transforms](./docs/WRITING_TRANSFORMS.md)** ⭐
+   - Creating jscodeshift codemods
+   - Common transformation patterns
+   - Testing transforms
+   - Best practices and anti-patterns
+
+6. **[Utilities API](./docs/UTILITIES.md)**
+   - Complete API reference
+   - TODO insertion functions
+   - Logging utilities
+   - Type definitions
+
+## Example Session
+
+```
+🚀 CDS Migrator
+
+? Which major version migration do you need?
+  ❯ v8 to v9 - Migrate from CDS v8 to v9
+
+? Enter the path to your codebase: ./src
+
+? What would you like to migrate?
+  ❯ Everything (all changes)
+    By category (components, hooks, etc.)
+    By item (specific component/hook/utility)
+    By specific transform
+
+Migration Plan:
+================
+📦 components: Component API changes
+  └─ Button (@coinbase/cds-web)
+     • Rename 'variant' prop to 'appearance'
+
+Total transforms: 1
+
+? Run in dry-run mode? Yes
+
+  → Running transform: components.Button.button-variant-to-appearance
+  ✓ Transform completed
+
+✅ Migration completed successfully!
+📝 Migration log written to: migration.log
+```
+
+## Project Structure
+
+```
+packages/migrator/
+├── docs/                   # Documentation
+│   ├── QUICK_START.md      # Getting started guide
+│   ├── CLI_REFERENCE.md            # Interactive & non-interactive modes
+│   ├── CONFIGURATION.md    # Config structure and setup
+│   ├── WRITING_TRANSFORMS.md # Transform development
+│   ├── UTILITIES.md        # Utils API reference
+│   └── HISTORY.md          # History tracking guide
+├── src/
+│   ├── cli.ts              # Interactive CLI
+│   ├── runner.ts           # Migration executor
+│   ├── types.ts            # TypeScript types
+│   ├── utils/              # Shared utilities
+│   └── v8-to-v9/           # Version-specific migrations
+│       ├── config.json     # Migration configuration
+│       └── transforms/     # jscodeshift codemods
+└── package.json
+```
+
+## Development
+
+### Build & Test
+
+```bash
+# Build the package
+yarn nx run migrator:build
+
+# Type check
+yarn nx run migrator:typecheck
+
+# Lint
+yarn nx run migrator:lint
+
+# Test the CLI
+cd packages/migrator
+node esm/cli.js
+```
+
+### Adding New Migrations
+
+See [docs/CONFIGURATION.md](./docs/CONFIGURATION.md) for complete instructions.
+
+Quick steps:
+
+1. Create `src/v9-to-v10/` directory
+2. Add `config.json` with three-level structure
+3. Create transforms in `transforms/` directory
+4. Update `SUPPORTED_MIGRATIONS` in `src/cli.ts`
+
+## Contributing
+
+When creating transforms:
+
+- ✅ Write idempotent transforms (safe to run multiple times)
+- ✅ Use the logging utilities to track changes
+- ✅ Add TODO comments for complex cases
+- ✅ Test in dry-run mode first
+- ✅ Update the config.json
+
+See [docs/WRITING_TRANSFORMS.md](./docs/WRITING_TRANSFORMS.md) for detailed guide.
+
+## License
+
+See LICENSE in the root of the repository.
diff --git a/packages/migrator/babel.config.cjs b/packages/migrator/babel.config.cjs
new file mode 100644
index 000000000..bd2fee9a4
--- /dev/null
+++ b/packages/migrator/babel.config.cjs
@@ -0,0 +1,22 @@
+// @ts-check
+const isTestEnv = process.env.NODE_ENV === 'test';
+
+/** @type {import('@babel/core').TransformOptions} */
+module.exports = {
+  presets: [
+    ['@babel/preset-env', { modules: isTestEnv ? 'commonjs' : false }],
+    ['@babel/preset-react', { runtime: 'automatic' }],
+    '@babel/preset-typescript',
+  ],
+  ignore: isTestEnv
+    ? []
+    : [
+        '**/__stories__/**',
+        '**/__tests__/**',
+        '**/__mocks__/**',
+        '**/__fixtures__/**',
+        '**/*.stories.*',
+        '**/*.test.*',
+        '**/*.spec.*',
+      ],
+};
diff --git a/packages/migrator/docs/CLI_REFERENCE.md b/packages/migrator/docs/CLI_REFERENCE.md
new file mode 100644
index 000000000..9bd94b58c
--- /dev/null
+++ b/packages/migrator/docs/CLI_REFERENCE.md
@@ -0,0 +1,558 @@
+# CLI Reference
+
+Complete guide for using the CDS Migrator in both interactive and non-interactive modes.
+
+## Quick Reference
+
+### Interactive Mode
+
+```bash
+npx @coinbase/cds-migrator
+# Follow prompts to select what to migrate
+```
+
+### Non-Interactive Mode (CLI Flags)
+
+```bash
+# Migrate everything
+npx @coinbase/cds-migrator -m v8-to-v9 -p ./src --all
+
+# Migrate specific category
+npx @coinbase/cds-migrator -m v8-to-v9 -p ./src --category components
+
+# Migrate specific items
+npx @coinbase/cds-migrator -m v8-to-v9 -p ./src --item components.Button
+
+# Clear history
+npx @coinbase/cds-migrator --clear-history -p ./src
+```
+
+---
+
+## Part 1: Interactive Mode
+
+### Selection Hierarchy
+
+The migrator offers four levels of selection granularity:
+
+```
+1. Everything          → Migrate all categories, items, and transforms
+   ↓
+2. By Category        → Select one or more categories (or all)
+   ↓
+3. By Item            → Select specific components/hooks/utilities (or all)
+   ↓
+4. By Transform       → Select individual transforms (or all)
+```
+
+### Selection Flow
+
+```
+? Which version migration? → v8 to v9
+? Enter path → ./src
+[Shows history if exists]
+? What would you like to migrate?
+  ❯ Everything (all changes)
+    By category (components, hooks, etc.)
+    By item (specific component/hook/utility)
+    By specific transform
+```
+
+### 1. Everything
+
+Fastest path - migrate all changes at once.
+
+**When to use:**
+
+- First-time migration
+- Small codebase
+- Want everything done quickly
+
+```
+? What would you like to migrate?
+  ❯ Everything (all changes)
+
+✓ Runs all transforms immediately
+```
+
+### 2. By Category
+
+Select categories of changes with "All" option.
+
+**When to use:**
+
+- Focus on one type (components, hooks, utilities)
+- Phased migration strategy
+
+```
+? Select categories to migrate:
+  ◯ 🔘 All categories          ← Migrates everything
+  ◯ components - Component API changes
+  ◯ hooks - Hook API changes
+  ◯ utilities - Utility function changes
+```
+
+### 3. By Item
+
+Select specific components/hooks/utilities with "All" option.
+
+**When to use:**
+
+- Test one component at a time
+- Different PRs for different components
+
+```
+? Select items to migrate:
+  ◯ 🔘 All items               ← Migrates everything
+  ◯ components.Button - Button changes (@coinbase/cds-web)
+  ◯ components.Input - Input changes (@coinbase/cds-web)
+  ◯ hooks.useTheme - useTheme changes (@coinbase/cds-common)
+```
+
+### 4. By Transform
+
+Select individual transforms with "All" option.
+
+**When to use:**
+
+- Maximum control
+- Debugging issues
+- Review each change carefully
+
+```
+? Select transforms to run:
+  ◯ 🔘 All transforms          ← Migrates everything
+  ◯ components.Button.button-variant-to-appearance - Rename 'variant' prop
+  ◯ components.Input.input-size-values - Update size values
+  ◯ hooks.useTheme.use-theme-return-type - Update return type
+```
+
+### Multiple Paths to "Migrate Everything"
+
+All of these produce the same result:
+
+| Path                             | When to Use                      |
+| -------------------------------- | -------------------------------- |
+| Everything (all changes)         | Fastest - just go!               |
+| By category → 🔘 All categories  | Want to see categories first     |
+| By item → 🔘 All items           | Want to see all items first      |
+| By transform → 🔘 All transforms | Want to review each change first |
+
+**Choose based on how much you want to explore before committing!**
+
+### Decision Tree
+
+```
+Do you want to migrate everything?
+│
+├─ YES, fast → "Everything (all changes)"
+├─ YES, see categories first → "By category" → "🔘 All categories"
+├─ YES, see items first → "By item" → "🔘 All items"
+├─ YES, review changes first → "By transform" → "🔘 All transforms"
+│
+└─ NO, be selective
+   ├─ By category → Select specific ones
+   ├─ By item → Select specific ones
+   └─ By transform → Select specific ones
+```
+
+---
+
+## Part 2: Non-Interactive Mode (CLI Flags)
+
+Use CLI flags to run without prompts - perfect for CI/CD and automation.
+
+### Required Flags
+
+For non-interactive mode, you must provide:
+
+- `-m, --migration <version>` - Migration version (e.g., v8-to-v9)
+- `-p, --path <path>` - Target path (default: ./src)
+- One selection: `--all`, `--category`, `--item`, or `--transform`
+
+### Selection Flags
+
+#### `--all`
+
+Migrate everything.
+
+```bash
+npx @coinbase/cds-migrator -m v8-to-v9 -p ./src --all
+```
+
+#### `--category <categories...>`
+
+Migrate specific categories (can specify multiple).
+
+```bash
+# Single category
+npx @coinbase/cds-migrator -m v8-to-v9 -p ./src --category components
+
+# Multiple categories
+npx @coinbase/cds-migrator -m v8-to-v9 -p ./src --category components hooks
+```
+
+#### `--item <items...>`
+
+Migrate specific items (format: `category.item`).
+
+```bash
+# Single item
+npx @coinbase/cds-migrator -m v8-to-v9 -p ./src --item components.Button
+
+# Multiple items
+npx @coinbase/cds-migrator -m v8-to-v9 -p ./src --item components.Button components.Input hooks.useTheme
+```
+
+#### `--transform <transforms...>`
+
+Migrate specific transforms (format: `category.item.transform-name`).
+
+```bash
+# Single transform
+npx @coinbase/cds-migrator -m v8-to-v9 -p ./src --transform components.Button.button-variant-to-appearance
+
+# Multiple transforms
+npx @coinbase/cds-migrator -m v8-to-v9 -p ./src \
+  --transform components.Button.button-variant-to-appearance \
+  --transform components.Input.input-size-values
+```
+
+### Mode Flags
+
+#### `-d, --dry-run`
+
+Preview changes without modifying files.
+
+```bash
+# Dry-run (safe to test)
+npx @coinbase/cds-migrator -m v8-to-v9 -p ./src --all --dry-run
+
+# Apply changes (no flag)
+npx @coinbase/cds-migrator -m v8-to-v9 -p ./src --all
+```
+
+#### `--skip-confirmation`
+
+Skip confirmation prompts (useful for automation).
+
+```bash
+# For CI/CD
+npx @coinbase/cds-migrator -m v8-to-v9 -p ./src --all --skip-confirmation
+```
+
+**⚠️ Use with caution** - bypasses all safety prompts!
+
+### Utility Flags
+
+#### `--clear-history`
+
+Clear migration history for a path.
+
+```bash
+# With confirmation
+npx @coinbase/cds-migrator --clear-history -p ./src
+
+# Skip confirmation
+npx @coinbase/cds-migrator --clear-history -p ./src --skip-confirmation
+```
+
+**Note:** Only requires `--path`, no migration version needed.
+
+#### `-h, --help`
+
+Show help message with all flags.
+
+```bash
+npx @coinbase/cds-migrator --help
+```
+
+#### `-V, --version`
+
+Show package version.
+
+```bash
+npx @coinbase/cds-migrator --version
+```
+
+### Flags Summary Table
+
+| Flag                  | Short | Description         | Example                                        |
+| --------------------- | ----- | ------------------- | ---------------------------------------------- |
+| `--migration`         | `-m`  | Migration version   | `-m v8-to-v9`                                  |
+| `--path`              | `-p`  | Target path         | `-p ./src`                                     |
+| `--dry-run`           | `-d`  | Preview mode        | `-d`                                           |
+| `--skip-confirmation` |       | Skip prompts        | `--skip-confirmation`                          |
+| `--clear-history`     |       | Clear history       | `--clear-history`                              |
+| `--all`               |       | Migrate everything  | `--all`                                        |
+| `--category`          |       | Specific categories | `--category components`                        |
+| `--item`              |       | Specific items      | `--item components.Button`                     |
+| `--transform`         |       | Specific transforms | `--transform components.Button.button-variant` |
+| `--help`              | `-h`  | Show help           | `-h`                                           |
+| `--version`           | `-V`  | Show version        | `-V`                                           |
+
+---
+
+## Part 3: Common Workflows
+
+### Local Development
+
+```bash
+# Interactive (recommended)
+npx @coinbase/cds-migrator
+
+# Quick dry-run
+npx @coinbase/cds-migrator -m v8-to-v9 -p ./src --all --dry-run
+```
+
+### CI/CD Pipeline
+
+```bash
+#!/bin/bash
+# migrate.sh
+
+# Preview first
+npx @coinbase/cds-migrator -m v8-to-v9 -p ./src --all --dry-run --skip-confirmation
+
+# Apply if preview succeeded
+if [ $? -eq 0 ]; then
+  npx @coinbase/cds-migrator -m v8-to-v9 -p ./src --all --skip-confirmation
+fi
+```
+
+### GitHub Actions
+
+```yaml
+name: CDS Migration
+on: workflow_dispatch
+
+jobs:
+  migrate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Setup Node
+        uses: actions/setup-node@v3
+        with:
+          node-version: '20'
+
+      - name: Run migration
+        run: |
+          npx @coinbase/cds-migrator \
+            --migration v8-to-v9 \
+            --path ./src \
+            --all \
+            --skip-confirmation
+
+      - name: Upload log
+        uses: actions/upload-artifact@v3
+        with:
+          name: migration-log
+          path: migration.log
+```
+
+### Incremental Migration
+
+```bash
+# Day 1: Components
+npx @coinbase/cds-migrator -m v8-to-v9 -p ./src --category components
+
+# Day 2: Hooks
+npx @coinbase/cds-migrator -m v8-to-v9 -p ./src --category hooks
+
+# Day 3: Everything else
+npx @coinbase/cds-migrator -m v8-to-v9 -p ./src --all
+```
+
+History tracking ensures no duplicates across runs.
+
+### Package.json Scripts
+
+```json
+{
+  "scripts": {
+    "migrate:dry": "cds-migrate -m v8-to-v9 -p ./src --all --dry-run",
+    "migrate:apply": "cds-migrate -m v8-to-v9 -p ./src --all --skip-confirmation",
+    "migrate:components": "cds-migrate -m v8-to-v9 -p ./src --category components",
+    "migrate:reset": "cds-migrate --clear-history -p ./src --skip-confirmation"
+  }
+}
+```
+
+---
+
+## Part 4: Interactive vs Non-Interactive
+
+### When to Use Interactive Mode
+
+✅ **Use interactive when:**
+
+- First-time migration
+- Want to explore options
+- Not sure what to migrate
+- Manual review needed
+
+```bash
+npx @coinbase/cds-migrator
+# Prompts guide you through
+```
+
+### When to Use Non-Interactive Mode
+
+✅ **Use non-interactive when:**
+
+- CI/CD pipelines
+- Automated scripts
+- You know exactly what to migrate
+- Repeated operations
+
+```bash
+npx @coinbase/cds-migrator -m v8-to-v9 -p ./src --all --skip-confirmation
+```
+
+### Switching Between Modes
+
+The tool automatically detects which mode based on provided flags:
+
+**Triggers Interactive:**
+
+```bash
+npx @coinbase/cds-migrator                    # No flags
+npx @coinbase/cds-migrator -m v8-to-v9       # Missing selection
+npx @coinbase/cds-migrator -p ./src --all    # Missing version
+```
+
+**Triggers Non-Interactive:**
+
+```bash
+npx @coinbase/cds-migrator -m v8-to-v9 -p ./src --all  # All required flags
+```
+
+---
+
+## Part 5: Examples by Use Case
+
+### Complete Migration
+
+```bash
+# Step 1: Preview everything
+npx @coinbase/cds-migrator -m v8-to-v9 -p ./src --all --dry-run
+
+# Step 2: Review migration.log
+cat migration.log
+
+# Step 3: Apply changes
+npx @coinbase/cds-migrator -m v8-to-v9 -p ./src --all
+```
+
+### Selective Migration
+
+```bash
+# Just Button component
+npx @coinbase/cds-migrator -m v8-to-v9 -p ./src --item components.Button
+
+# Just one transform
+npx @coinbase/cds-migrator -m v8-to-v9 -p ./src \
+  --transform components.Button.button-variant-to-appearance
+```
+
+### Testing During Development
+
+```bash
+# Test on sample directory
+npx @coinbase/cds-migrator -m v8-to-v9 -p ./test-samples --all
+
+# Clear and re-test
+npx @coinbase/cds-migrator --clear-history -p ./test-samples --skip-confirmation
+npx @coinbase/cds-migrator -m v8-to-v9 -p ./test-samples --all
+```
+
+### Automated Daily Migration
+
+```bash
+#!/bin/bash
+# daily-migrate.sh
+
+DATE=$(date +%Y-%m-%d)
+LOG_DIR="./migration-logs"
+
+mkdir -p "$LOG_DIR"
+
+npx @coinbase/cds-migrator \
+  -m v8-to-v9 \
+  -p ./src \
+  --all \
+  --skip-confirmation \
+  && mv migration.log "$LOG_DIR/migration-$DATE.log"
+```
+
+---
+
+## Troubleshooting
+
+### "Error: Must specify --all, --category, --item, or --transform"
+
+You need to specify what to migrate:
+
+```bash
+# ❌ Missing selection
+npx @coinbase/cds-migrator -m v8-to-v9 -p ./src
+
+# ✅ With selection
+npx @coinbase/cds-migrator -m v8-to-v9 -p ./src --all
+```
+
+### "Warning: Some transforms have already been run"
+
+Options:
+
+1. Use `--skip-confirmation` (automatically skips duplicates)
+2. Use `--clear-history` first to reset
+3. Switch to interactive mode to choose options
+
+```bash
+# Skip duplicate warning
+npx @coinbase/cds-migrator -m v8-to-v9 -p ./src --all --skip-confirmation
+```
+
+### Invalid Migration Version
+
+Check available versions:
+
+```bash
+npx @coinbase/cds-migrator --help
+```
+
+Currently available: `v8-to-v9`
+
+---
+
+## Exit Codes
+
+| Code | Meaning                                                        |
+| ---- | -------------------------------------------------------------- |
+| `0`  | Success                                                        |
+| `1`  | Error (migration failed, validation failed, or user cancelled) |
+
+**Example:**
+
+```bash
+npx @coinbase/cds-migrator -m v8-to-v9 -p ./src --all --skip-confirmation
+if [ $? -eq 0 ]; then
+  echo "✅ Migration succeeded"
+else
+  echo "❌ Migration failed"
+  exit 1
+fi
+```
+
+---
+
+## See Also
+
+- [Quick Start](./QUICK_START.md) - Your first migration
+- [Configuration](./CONFIGURATION.md) - Understanding the structure
+- [History](./HISTORY.md) - How tracking works
+- [Writing Transforms](./WRITING_TRANSFORMS.md) - Creating codemods
+- [Utilities API](./UTILITIES.md) - Helper functions
diff --git a/packages/migrator/docs/CONFIGURATION.md b/packages/migrator/docs/CONFIGURATION.md
new file mode 100644
index 000000000..615af4d13
--- /dev/null
+++ b/packages/migrator/docs/CONFIGURATION.md
@@ -0,0 +1,614 @@
+# Migration Configuration Guide
+
+How to structure and configure migrations using the three-level hierarchy.
+
+## Overview
+
+Each major version migration (e.g., v8-to-v9) has a `config.json` file that defines:
+
+1. **Categories** - High-level groupings (components, hooks, utilities)
+2. **Variables** - Specific exports (Button, useTheme, formatCurrency)
+3. **Transforms** - Individual codemods to run
+
+This structure allows users to migrate everything at once or pick exactly what they need.
+
+## Configuration Structure
+
+```
+Categories (components, hooks, utilities)
+  └─ Variables (Button, Input, useTheme, etc.)
+      └─ Transforms (specific codemods)
+```
+
+### Complete Example
+
+```json
+{
+  "version": "v8-to-v9",
+  "description": "Migration from CDS v8 to v9",
+  "categories": {
+    "components": {
+      "description": "Component API changes",
+      "variables": {
+        "Button": {
+          "description": "Button component prop changes",
+          "package": "@coinbase/cds-web",
+          "transforms": [
+            {
+              "name": "button-variant-to-appearance",
+              "description": "Rename 'variant' prop to 'appearance'",
+              "file": "transforms/button-variant-to-appearance.ts"
+            },
+            {
+              "name": "button-remove-deprecated-sizes",
+              "description": "Remove deprecated size values",
+              "file": "transforms/button-remove-deprecated-sizes.ts"
+            }
+          ]
+        },
+        "Input": {
+          "description": "Input component prop changes",
+          "package": "@coinbase/cds-web",
+          "transforms": [
+            {
+              "name": "input-size-values",
+              "description": "Update size prop values",
+              "file": "transforms/input-size-values.ts"
+            }
+          ]
+        }
+      }
+    },
+    "hooks": {
+      "description": "Hook API changes",
+      "variables": {
+        "useTheme": {
+          "description": "useTheme hook signature changes",
+          "package": "@coinbase/cds-common",
+          "transforms": [
+            {
+              "name": "use-theme-return-type",
+              "description": "Update destructured return values",
+              "file": "transforms/use-theme-return-type.ts"
+            }
+          ]
+        }
+      }
+    }
+  }
+}
+```
+
+## Level Definitions
+
+### Level 1: Categories
+
+Organize changes by type:
+
+| Category     | Description              | Examples                       |
+| ------------ | ------------------------ | ------------------------------ |
+| `components` | React component changes  | Button, Input, Modal           |
+| `hooks`      | Hook API changes         | useTheme, useMediaQuery        |
+| `utilities`  | Utility function changes | formatCurrency, parseDate      |
+| `types`      | TypeScript type changes  | Props interfaces, type aliases |
+| `constants`  | Constant value changes   | Theme tokens, breakpoints      |
+| `styles`     | Style/CSS changes        | Class names, CSS variables     |
+
+**Category Schema:**
+
+```typescript
+{
+  description: string;  // Human-readable explanation
+  variables: {          // Map of exported symbols
+    [name: string]: MigrationVariable;
+  }
+}
+```
+
+### Level 2: Variables
+
+Specific exports from CDS packages:
+
+**Variable Schema:**
+
+```typescript
+{
+  description: string;  // What changed about this export
+  package: string;      // Which package exports it
+  transforms: Transform[]; // Array of codemods
+}
+```
+
+**Examples:**
+
+- `Button` from `@coinbase/cds-web`
+- `useTheme` from `@coinbase/cds-common`
+- `formatCurrency` from `@coinbase/cds-utils`
+
+**Naming conventions:**
+
+- Use the actual export name (PascalCase for components/types, camelCase for functions/hooks)
+- Match what users import: `import { Button } from '@coinbase/cds-web'`
+
+### Level 3: Transforms
+
+Individual jscodeshift codemods:
+
+**Transform Schema:**
+
+```typescript
+{
+  name: string;        // Unique identifier (kebab-case)
+  description: string; // What this transform does
+  file: string;        // Path relative to version directory
+  extensions?: string; // Optional: "tsx,ts,jsx,js" (default)
+}
+```
+
+**Naming conventions:**
+
+- Use kebab-case: `button-variant-to-appearance`
+- Be descriptive: `{component}-{what-it-does}`
+- Examples: `input-size-values`, `use-theme-return-type`
+
+## Adding a New Migration Version
+
+### 1. Create Directory Structure
+
+```bash
+mkdir -p packages/migrator/src/v9-to-v10/transforms
+```
+
+### 2. Create config.json
+
+```json
+{
+  "version": "v9-to-v10",
+  "description": "Migration from CDS v9 to v10",
+  "categories": {
+    "components": {
+      "description": "Component API changes",
+      "variables": {}
+    }
+  }
+}
+```
+
+### 3. Create index.ts
+
+```typescript
+/**
+ * v9 to v10 Migration
+ */
+
+export const description = `
+CDS v9 to v10 Migration
+======================
+
+Breaking changes in v10:
+- [List breaking changes here]
+
+Please review the changes carefully before committing.
+`;
+```
+
+### 4. Update CLI
+
+In `src/cli.ts`, add to `SUPPORTED_MIGRATIONS`:
+
+```typescript
+const SUPPORTED_MIGRATIONS = [
+  {
+    name: 'v8 to v9',
+    value: 'v8-to-v9',
+    description: 'Migrate from CDS v8 to v9',
+  },
+  {
+    name: 'v9 to v10', // Add this
+    value: 'v9-to-v10',
+    description: 'Migrate from CDS v9 to v10',
+  },
+] as const;
+```
+
+## Adding Transforms to Existing Migration
+
+### 1. Create the Transform File
+
+```typescript
+// src/v8-to-v9/transforms/button-variant-to-appearance.ts
+import type { API, FileInfo } from 'jscodeshift';
+import { getLogger } from '../../utils';
+
+export default function transformer(file: FileInfo, api: API) {
+  const j = api.jscodeshift;
+  const root = j(file.source);
+  const logger = getLogger();
+
+  let hasChanges = false;
+
+  // Transform logic here
+  root
+    .find(j.JSXAttribute, { name: { name: 'variant' } })
+    .filter((path) => {
+      const jsxElement = path.parent.value;
+      return (
+        j.JSXIdentifier.check(jsxElement.openingElement.name) &&
+        jsxElement.openingElement.name.name === 'Button'
+      );
+    })
+    .forEach((path) => {
+      if (j.JSXIdentifier.check(path.value.name)) {
+        path.value.name.name = 'appearance';
+        hasChanges = true;
+        logger?.success('Renamed variant to appearance', file.path, path.value.loc?.start.line);
+      }
+    });
+
+  return hasChanges ? root.toSource() : null;
+}
+```
+
+### 2. Add to config.json
+
+```json
+{
+  "categories": {
+    "components": {
+      "variables": {
+        "Button": {
+          "description": "Button component prop changes",
+          "package": "@coinbase/cds-web",
+          "transforms": [
+            {
+              "name": "button-variant-to-appearance",
+              "description": "Rename 'variant' prop to 'appearance'",
+              "file": "transforms/button-variant-to-appearance.ts"
+            }
+          ]
+        }
+      }
+    }
+  }
+}
+```
+
+### 3. Test
+
+```bash
+# Build
+yarn nx run migrator:build
+
+# Test in dry-run
+cd packages/migrator
+node esm/cli.js
+# Select: By specific transform → components.Button.button-variant-to-appearance
+```
+
+## Configuration Best Practices
+
+### 1. Granular Transforms
+
+One transform should do one thing:
+
+✅ **Good:**
+
+```json
+{
+  "transforms": [
+    {
+      "name": "button-variant-to-appearance",
+      "description": "Rename 'variant' prop to 'appearance'"
+    },
+    {
+      "name": "button-remove-deprecated-sizes",
+      "description": "Remove deprecated size values"
+    }
+  ]
+}
+```
+
+❌ **Bad:**
+
+```json
+{
+  "transforms": [
+    {
+      "name": "button-all-changes",
+      "description": "Update all Button props"
+    }
+  ]
+}
+```
+
+**Why:** Granular transforms give users more control and make debugging easier.
+
+### 2. Clear Descriptions
+
+Descriptions should explain what changes, not implementation details:
+
+✅ **Good:**
+
+```json
+"description": "Rename 'variant' prop to 'appearance'"
+```
+
+❌ **Bad:**
+
+```json
+"description": "Run jscodeshift transform to update JSX attributes"
+```
+
+### 3. Logical Grouping
+
+Group related transforms under the same variable:
+
+✅ **Good:**
+
+```json
+"Button": {
+  "transforms": [
+    { "name": "button-variant-to-appearance" },
+    { "name": "button-size-values" },
+    { "name": "button-remove-deprecated-props" }
+  ]
+}
+```
+
+❌ **Bad:**
+
+```json
+"Button": {
+  "transforms": [{ "name": "button-variant-to-appearance" }]
+},
+"ButtonSize": {
+  "transforms": [{ "name": "button-size-values" }]
+}
+```
+
+### 4. Package Attribution
+
+Always specify which package exports the variable:
+
+```json
+{
+  "Button": {
+    "package": "@coinbase/cds-web",  // ← Required!
+    "transforms": [...]
+  }
+}
+```
+
+This helps users understand where imports come from.
+
+### 5. Meaningful Categories
+
+Use categories that match how developers think:
+
+✅ **Good Categories:**
+
+- `components` - React components
+- `hooks` - React hooks
+- `utilities` - Helper functions
+- `types` - TypeScript types
+
+❌ **Avoid:**
+
+- `breaking-changes` - Too vague
+- `misc` - Not organized
+- `v9-updates` - Redundant with version
+
+## Migration Execution Flow
+
+Understanding how the config is used:
+
+```
+1. User selects migration version (v8-to-v9)
+   ↓
+2. Load config.json from src/v8-to-v9/
+   ↓
+3. User chooses scope (all, category, variable, or transform)
+   ↓
+4. Build list of transforms based on selection
+   ↓
+5. Show migration plan
+   ↓
+6. Execute transforms in order
+   ↓
+7. Record in migration history
+```
+
+## Example Migration Plans
+
+### Selecting "Everything"
+
+```
+Migration Plan:
+================
+
+📦 components: Component API changes
+  └─ Button (@coinbase/cds-web)
+     • Rename 'variant' prop to 'appearance'
+     • Remove deprecated size values
+  └─ Input (@coinbase/cds-web)
+     • Update size prop values
+
+📦 hooks: Hook API changes
+  └─ useTheme (@coinbase/cds-common)
+     • Update destructured return values
+
+Total transforms: 4
+```
+
+### Selecting "By Variable"
+
+```
+? Select items to migrate:
+  ◉ components.Button
+  ◯ components.Input
+  ◉ hooks.useTheme
+
+Migration Plan:
+================
+
+📦 components: Component API changes
+  └─ Button (@coinbase/cds-web)
+     • Rename 'variant' prop to 'appearance'
+     • Remove deprecated size values
+
+📦 hooks: Hook API changes
+  └─ useTheme (@coinbase/cds-common)
+     • Update destructured return values
+
+Total transforms: 3
+```
+
+## Advanced Configuration
+
+### Custom File Extensions
+
+For transforms that should only run on specific file types:
+
+```json
+{
+  "name": "style-object-to-stylesheet",
+  "description": "Convert inline styles to StyleSheet",
+  "file": "transforms/style-object-to-stylesheet.ts",
+  "extensions": "tsx,jsx" // Only run on TSX/JSX files
+}
+```
+
+### Transform Ordering
+
+Transforms run in the order they appear in the config:
+
+```json
+{
+  "transforms": [
+    {
+      "name": "remove-old-imports",
+      "description": "Remove old imports"
+    },
+    {
+      "name": "add-new-imports",
+      "description": "Add new imports"
+    }
+  ]
+}
+```
+
+**Important:** The order matters if transforms depend on each other!
+
+## Schema Reference
+
+### MigrationConfig
+
+```typescript
+interface MigrationConfig {
+  version: string; // "v8-to-v9"
+  description: string; // Overall description
+  categories: Record<string, MigrationCategory>; // Category map
+}
+```
+
+### MigrationCategory
+
+```typescript
+interface MigrationCategory {
+  description: string; // Category description
+  variables: Record<string, MigrationVariable>; // Variable map
+}
+```
+
+### MigrationVariable
+
+```typescript
+interface MigrationVariable {
+  description: string; // What changed
+  package: string; // Source package
+  transforms: Transform[]; // List of transforms
+}
+```
+
+### Transform
+
+```typescript
+interface Transform {
+  name: string; // Unique ID (kebab-case)
+  description: string; // Human-readable explanation
+  file: string; // Path relative to version dir
+  extensions?: string; // Optional: file extensions
+}
+```
+
+## Validation
+
+The config loader will validate:
+
+✅ config.json exists
+✅ Valid JSON format
+✅ All referenced transform files exist
+✅ No duplicate transform names within a variable
+
+## Tips for Large Migrations
+
+### Split by Package
+
+Organize by which CDS package is affected:
+
+```json
+{
+  "categories": {
+    "cds-web": {
+      "description": "@coinbase/cds-web changes",
+      "variables": {
+        /* web components */
+      }
+    },
+    "cds-mobile": {
+      "description": "@coinbase/cds-mobile changes",
+      "variables": {
+        /* mobile components */
+      }
+    },
+    "cds-common": {
+      "description": "@coinbase/cds-common changes",
+      "variables": {
+        /* hooks, utilities */
+      }
+    }
+  }
+}
+```
+
+### Use Descriptive Transform Names
+
+Make it easy to understand what each transform does:
+
+✅ Good:
+
+- `button-variant-to-appearance`
+- `input-remove-error-text-prop`
+- `modal-overlay-click-behavior`
+
+❌ Avoid:
+
+- `transform1`
+- `fix-button`
+- `update`
+
+### Document Breaking Changes
+
+Use the description field effectively:
+
+```json
+{
+  "description": "Migration from CDS v8 to v9\n\nBreaking changes:\n- Button 'variant' prop renamed to 'appearance'\n- Input 'errorText' prop removed\n- useTheme returns new structure"
+}
+```
+
+## See Also
+
+- [Writing Transforms](./WRITING_TRANSFORMS.md) - Create the transform files
+- [Utilities](./UTILITIES.md) - Use shared utilities in transforms
+- [Quick Start](./QUICK_START.md) - Run your first migration
diff --git a/packages/migrator/docs/HISTORY.md b/packages/migrator/docs/HISTORY.md
new file mode 100644
index 000000000..3c4aa720e
--- /dev/null
+++ b/packages/migrator/docs/HISTORY.md
@@ -0,0 +1,432 @@
+# Migration History Tracking
+
+The CDS Migrator automatically tracks which transforms have been run on each directory to prevent accidental duplicate migrations.
+
+## How It Works
+
+### Automatic Tracking
+
+When you run a migration (in non-dry-run mode), the migrator:
+
+1. **Records the transform** - Saves which transform was run, when, and for which version
+2. **Creates a history file** - Stores this in `.cds-migration-history.json` in the target directory
+3. **Checks before running** - Before executing any transform, checks if it's already been run
+
+### History File
+
+The `.cds-migration-history.json` file is created in your target directory:
+
+```json
+{
+  "targetPath": "./src",
+  "entries": [
+    {
+      "transformId": "components.Button.button-variant-to-appearance",
+      "timestamp": "2026-02-11T12:00:00.000Z",
+      "version": "v8-to-v9",
+      "dryRun": false
+    }
+  ],
+  "lastUpdated": "2026-02-11T12:00:00.000Z"
+}
+```
+
+**Important Notes:**
+
+- This file should be **committed to version control**
+- It helps team members avoid re-running the same migrations
+- Dry-run mode does NOT create or update the history file
+
+## User Experience
+
+### First Run
+
+When running a migration for the first time:
+
+```bash
+? What would you like to migrate?
+  ❯ Everything (all changes)
+
+Migration Plan:
+================
+📦 components: Component API changes
+  └─ Button (@coinbase/cds-web)
+     • Rename 'variant' prop to 'appearance'
+
+Total transforms: 1
+
+? Enter the path to your codebase: ./src
+? Run in dry-run mode? No
+
+  → Running transform: components.Button.button-variant-to-appearance
+    Rename 'variant' prop to 'appearance'
+
+  ✓ Transform completed: button-variant-to-appearance
+
+✅ Migration completed successfully!
+```
+
+### Attempting to Re-run
+
+If you try to run the same migration again:
+
+```bash
+Migration Plan:
+================
+📦 components: Component API changes
+  └─ Button (@coinbase/cds-web)
+     • Rename 'variant' prop to 'appearance'
+
+Total transforms: 1
+
+? Enter the path to your codebase: ./src
+? Run in dry-run mode? No
+
+⚠️  Warning: Some transforms have already been run on this path:
+
+  • components.Button.button-variant-to-appearance
+
+📜 Migration History
+==================
+
+v8-to-v9:
+  • components.Button.button-variant-to-appearance (2/11/2026)
+
+Last updated: 2/11/2026, 12:00:00 PM
+
+? How would you like to proceed?
+  ❯ Skip already-run transforms (recommended)
+    Re-run all transforms (may cause issues)
+    Cancel migration
+```
+
+### Options When Duplicate Detected
+
+1. **Skip already-run transforms (recommended)**
+   - Only runs transforms that haven't been executed before
+   - Safest option to prevent issues
+   - The runner will automatically skip completed transforms
+
+2. **Re-run all transforms (may cause issues)**
+   - Forces re-execution of all selected transforms
+   - May cause problems if transforms aren't idempotent
+   - Use with caution
+
+3. **Cancel migration**
+   - Exits without making any changes
+
+### During Execution
+
+When transforms are skipped:
+
+```bash
+  → Running transform: components.Input.input-size-values
+    Update size prop values (sm/md/lg to small/medium/large)
+
+  ✓ Transform completed: input-size-values
+
+  ⊘ Skipping (already run): components.Button.button-variant-to-appearance
+
+⊘ Skipped 1 transform(s) that were already run.
+
+✅ Migration completed successfully!
+```
+
+## API for Programmatic Use
+
+### Load History
+
+```typescript
+import { loadMigrationHistory } from '@coinbase/cds-migrator';
+
+const history = loadMigrationHistory('./src');
+if (history) {
+  console.log(`Last updated: ${history.lastUpdated}`);
+  console.log(`Total migrations: ${history.entries.length}`);
+}
+```
+
+### Check if Transform Was Run
+
+```typescript
+import { hasTransformBeenRun } from '@coinbase/cds-migrator';
+
+const wasRun = hasTransformBeenRun('./src', 'components.Button.button-variant-to-appearance');
+
+if (wasRun) {
+  console.log('This transform has already been applied');
+}
+```
+
+### Get Already-Run Transforms
+
+```typescript
+import { getAlreadyRunTransforms } from '@coinbase/cds-migrator';
+
+const transformsToRun = [
+  'components.Button.button-variant-to-appearance',
+  'components.Input.input-size-values',
+];
+
+const alreadyRun = getAlreadyRunTransforms('./src', transformsToRun);
+console.log('Already run:', alreadyRun);
+```
+
+### View History Summary
+
+```typescript
+import { buildHistorySummary } from '@coinbase/cds-migrator';
+
+const summary = buildHistorySummary('./src');
+console.log(summary);
+// Outputs a formatted summary of all migrations
+```
+
+### Clear History
+
+**CLI (recommended):**
+
+```bash
+# Clear history for a path
+npx @coinbase/cds-migrator --clear-history -p ./src
+
+# Skip confirmation prompt
+npx @coinbase/cds-migrator --clear-history -p ./src --skip-confirmation
+```
+
+**Programmatically:**
+
+```typescript
+import { clearMigrationHistory } from '@coinbase/cds-migrator';
+
+// Use with caution - this removes all migration tracking
+clearMigrationHistory('./src');
+```
+
+## Best Practices
+
+### ✅ Do
+
+- **Commit the history file** to version control
+- **Review the history** before running migrations
+- **Use dry-run mode** first to preview changes
+- **Skip already-run transforms** when prompted (recommended option)
+
+### ❌ Don't
+
+- Don't delete `.cds-migration-history.json` without good reason
+- Don't re-run transforms unless absolutely necessary
+- Don't ignore warnings about duplicate runs
+- Don't add `.cds-migration-history.json` to `.gitignore`
+
+## Team Collaboration
+
+### Scenario: Multiple Team Members
+
+1. **Developer A** runs migration and commits the history file:
+
+   ```bash
+   git add .cds-migration-history.json
+   git commit -m "Run v8-to-v9 Button migration"
+   ```
+
+2. **Developer B** pulls the changes:
+
+   ```bash
+   git pull
+   ```
+
+3. **Developer B** tries to run the same migration:
+   - Migrator detects it was already run
+   - Shows warning with history
+   - Recommends skipping
+
+### Scenario: Different Directories
+
+If your codebase has multiple directories with different migration states:
+
+```
+project/
+├── src/
+│   └── .cds-migration-history.json  # Migrations complete
+└── legacy/
+    └── .cds-migration-history.json  # Partial migrations
+```
+
+Each directory tracks its own history independently.
+
+## Troubleshooting
+
+### "I need to re-run a transform"
+
+If a transform failed or needs to be re-run:
+
+1. **Option 1:** Choose "Re-run all transforms" when prompted by the migrator
+2. **Option 2:** Clear history and start fresh:
+   ```bash
+   npx @coinbase/cds-migrator --clear-history -p ./src
+   ```
+3. **Option 3:** Manually edit `.cds-migration-history.json` and remove specific entries
+
+### "History file is out of sync"
+
+If team members have conflicting history files:
+
+1. Review both history files
+2. Merge the entries manually in JSON
+3. Keep the most complete history
+4. Resolve conflicts through code review
+
+### "Transform was run but not recorded"
+
+This can happen if:
+
+- The migration was run in dry-run mode (by design)
+- The migrator crashed before saving history
+- File permissions prevented writing the history file
+
+Solution: Manually add the entry to `.cds-migration-history.json`
+
+## Clearing Migration History
+
+### Quick Command
+
+```bash
+# Clear history with confirmation
+npx @coinbase/cds-migrator --clear-history -p ./src
+
+# Skip confirmation (be careful!)
+npx @coinbase/cds-migrator --clear-history -p ./src --skip-confirmation
+```
+
+### When to Clear History
+
+#### Failed Migration
+
+If a migration failed partway through:
+
+```bash
+# Migration failed
+npx @coinbase/cds-migrator -m v8-to-v9 -p ./src --all
+# Error occurred, some transforms completed but others didn't
+
+# Clear history to start fresh
+npx @coinbase/cds-migrator --clear-history -p ./src
+
+# Run migration again
+npx @coinbase/cds-migrator -m v8-to-v9 -p ./src --all
+```
+
+#### Testing Migrations
+
+During development or testing:
+
+```bash
+# Test a migration
+npx @coinbase/cds-migrator -m v8-to-v9 -p ./test-dir --all
+
+# Clear to test again
+npx @coinbase/cds-migrator --clear-history -p ./test-dir --skip-confirmation
+
+# Re-run with changes
+npx @coinbase/cds-migrator -m v8-to-v9 -p ./test-dir --all
+```
+
+#### Corrupted History File
+
+If the history file is corrupted or invalid:
+
+```bash
+# Clear the corrupted history
+npx @coinbase/cds-migrator --clear-history -p ./src --skip-confirmation
+
+# Start fresh
+npx @coinbase/cds-migrator -m v8-to-v9 -p ./src --all
+```
+
+#### Reset After Rollback
+
+If you rolled back code changes via git:
+
+```bash
+# Rolled back code
+git reset --hard HEAD~1
+
+# Clear history to match code state
+npx @coinbase/cds-migrator --clear-history -p ./src --skip-confirmation
+```
+
+### What Gets Deleted
+
+The command removes:
+
+- `.cds-migration-history.json` in the specified path
+
+It does NOT delete:
+
+- Your code changes
+- The `migration.log` file
+- Any other files
+
+### Bulk Clear
+
+To clear history for multiple directories:
+
+```bash
+#!/bin/bash
+# clear-all-history.sh
+
+DIRS=("./src" "./lib" "./packages")
+
+for dir in "${DIRS[@]}"; do
+  echo "Clearing history for: $dir"
+  npx @coinbase/cds-migrator --clear-history -p "$dir" --skip-confirmation
+done
+
+echo "✅ All history cleared"
+```
+
+### Alternative: Manual Deletion
+
+You can also delete the file directly:
+
+```bash
+# Delete history file
+rm ./src/.cds-migration-history.json
+
+# Verify it's gone
+ls -la ./src/.cds-migration-history.json
+```
+
+This is equivalent to `--clear-history` but skips all checks.
+
+### Best Practices
+
+**✅ Do:**
+
+- Clear history after failed migrations
+- Clear during testing/development
+- Use `--skip-confirmation` in scripts
+
+**❌ Don't:**
+
+- Clear history just to re-run transforms (use "Re-run" option instead)
+- Clear history without good reason in production
+- Clear history if team members are mid-migration
+
+## Configuration
+
+### Disable History Tracking
+
+Currently, history tracking is always enabled for non-dry-run migrations. If you need to disable it:
+
+1. Use dry-run mode (doesn't record history)
+2. Or delete the history file after each run (not recommended)
+
+### Custom History Location
+
+The history file is always created in the target directory. This ensures:
+
+- Each directory can be migrated independently
+- History travels with the code
+- No global state to manage
diff --git a/packages/migrator/docs/QUICK_START.md b/packages/migrator/docs/QUICK_START.md
new file mode 100644
index 000000000..0f3a74728
--- /dev/null
+++ b/packages/migrator/docs/QUICK_START.md
@@ -0,0 +1,371 @@
+# Quick Start Guide
+
+Get started with CDS Migrator in 5 minutes.
+
+## Installation
+
+```bash
+# Option 1: Run directly with npx (recommended)
+npx @coinbase/cds-migrator
+
+# Option 2: Install as dev dependency
+yarn add -D @coinbase/cds-migrator
+```
+
+## Your First Migration
+
+### 1. Run the CLI
+
+```bash
+cd your-project
+npx @coinbase/cds-migrator
+```
+
+### 2. Follow the Prompts
+
+**Choose migration version:**
+
+```
+? Which major version migration do you need?
+  ❯ v8 to v9 - Migrate from CDS v8 to v9
+```
+
+**Choose scope:**
+
+```
+? What would you like to migrate?
+  ❯ Everything (all changes)
+    By category (components, hooks, etc.)
+    By item (specific component/hook/utility)
+    By specific transform
+```
+
+**Choose path and mode:**
+
+```
+? Enter the path to your codebase: ./src
+? Run in dry-run mode? (Y/n) Y
+```
+
+### 3. Review Changes
+
+The migrator will:
+
+- Show a migration plan
+- Run transforms and display progress
+- Create a `migration.log` file with details
+- Add TODO comments where manual work is needed
+
+### 4. Apply Changes
+
+Once you're satisfied with the dry-run:
+
+1. Run the migrator again
+2. Choose **No** for dry-run mode
+3. Review and commit changes
+
+## Migration Modes
+
+### Dry-Run Mode (Recommended First)
+
+Preview changes without modifying files:
+
+- ✅ Safe to run anytime
+- ✅ See what would change
+- ✅ Review migration.log
+- ✅ No history recorded
+
+```bash
+? Run in dry-run mode? Yes
+```
+
+### Apply Mode
+
+Apply changes to your files:
+
+- ⚠️ Modifies your files
+- ⚠️ Records migration history
+- ⚠️ Can't easily undo (use git!)
+- ✅ Prevents duplicate runs
+
+```bash
+? Run in dry-run mode? No
+⚠️  This will modify your files. Continue? (y/N)
+```
+
+## What Gets Created
+
+After running a migration:
+
+```
+your-project/
+├── src/
+│   ├── .cds-migration-history.json  # ← Tracks applied migrations
+│   └── ... (your modified files)
+└── migration.log                    # ← Detailed log of changes
+```
+
+**Important:**
+
+- ✅ Commit `.cds-migration-history.json` to git
+- ❌ Don't commit `migration.log` (review then delete)
+
+## Selection Strategies
+
+The migrator offers **four ways to select** what to migrate, with each level offering an "All" option.
+
+### 1. Everything - Fastest Path
+
+**Best for:** Initial migration, small codebase, want it done quickly
+
+```
+? What would you like to migrate?
+  ❯ Everything (all changes)
+```
+
+**What happens:** Runs all transforms immediately - no further selections needed.
+
+### 2. By Category
+
+**Best for:** Focus on specific types of changes, or see categories before migrating all
+
+```
+? What would you like to migrate?
+  ❯ By category (components, hooks, etc.)
+
+? Select categories to migrate:
+  ◯ 🔘 All categories          ← Migrates everything
+  ◯ components - Component API changes
+  ◯ hooks - Hook API changes
+  ◯ utilities - Utility function changes
+```
+
+Select "🔘 All categories" to migrate everything, or pick specific ones for phased migration.
+
+### 3. By Item
+
+**Best for:** Migrate specific components/hooks, or see full list before migrating all
+
+```
+? What would you like to migrate?
+  ❯ By item (specific component/hook/utility)
+
+? Select items to migrate:
+  ◯ 🔘 All items               ← Migrates everything
+  ◯ components.Button - Button component changes (@coinbase/cds-web)
+  ◯ components.Input - Input component changes (@coinbase/cds-web)
+  ◯ hooks.useTheme - useTheme hook changes (@coinbase/cds-common)
+  ◯ utilities.formatCurrency - formatCurrency changes (@coinbase/cds-utils)
+```
+
+Select "🔘 All items" to migrate everything, or pick specific items to test one at a time.
+
+### 4. By Transform
+
+**Best for:** Maximum control, or review each change before migrating all
+
+```
+? What would you like to migrate?
+  ❯ By specific transform
+
+? Select transforms to run:
+  ◯ 🔘 All transforms          ← Migrates everything
+  ◯ components.Button.button-variant-to-appearance - Rename 'variant' prop
+  ◯ components.Input.input-size-values - Update size values
+  ◯ hooks.useTheme.use-theme-return-type - Update return type
+  ◯ utilities.formatCurrency.format-currency-options - Update options
+```
+
+Select "🔘 All transforms" to migrate everything after reviewing details, or pick specific ones for surgical changes.
+
+## Understanding the Output
+
+### Console Output
+
+```
+🔄 Running v8-to-v9 migration...
+
+  → Running transform: components.Button.button-variant-to-appearance
+    Rename 'variant' prop to 'appearance'
+
+    Command: npx jscodeshift --dry --parser=tsx ...
+
+    Processing 25 files...
+    Transforming src/Button.tsx...
+    Transforming src/App.tsx...
+
+  ✓ Transform completed: button-variant-to-appearance
+
+✅ Migration completed successfully!
+📝 Migration log written to: migration.log
+```
+
+### Migration Log (`migration.log`)
+
+```
+CDS Migration Log
+Generated: 2026-02-11T12:00:00.000Z
+========================================
+
+[2026-02-11T12:00:01.000Z] INFO: Starting v8-to-v9 migration
+[2026-02-11T12:00:02.000Z] SUCCESS [src/Button.tsx:15]: Renamed prop
+[2026-02-11T12:00:03.000Z] TODO [src/Complex.tsx:45]: Manual migration required
+  This component needs manual review
+
+========================================
+Migration Summary
+========================================
+
+Total Entries: 3
+- INFO: 1
+- SUCCESS: 1
+- TODO: 1
+
+Manual Migration Required (1 items):
+  - src/Complex.tsx: Manual migration required
+```
+
+### TODO Comments in Code
+
+When automatic migration isn't possible:
+
+```tsx
+// Before migration
+<Button complexProp={{ old: 'api' }} />
+
+// After migration
+// TODO(cds-migration): complexProp API has changed significantly
+// Please review the new API at https://docs.coinbase.com/cds/...
+<Button complexProp={{ old: 'api' }} />
+```
+
+## Next Steps
+
+After your first migration:
+
+1. **Review the changes** - Check modified files
+2. **Review migration.log** - Look for TODO items
+3. **Test your app** - Ensure everything works
+4. **Fix TODOs** - Address manual migration items
+5. **Commit** - Save changes and migration history
+
+```bash
+git add .
+git commit -m "Migrate from CDS v8 to v9"
+```
+
+## Decision Guide
+
+### Quick Decision Tree
+
+```
+Do you want to migrate everything?
+│
+├─ YES, and I want it done fast
+│  └─> Choose: "Everything (all changes)"
+│
+├─ YES, but I want to see categories first
+│  └─> Choose: "By category" → "🔘 All categories"
+│
+├─ YES, but I want to see all items first
+│  └─> Choose: "By item" → "🔘 All items"
+│
+├─ YES, but I want to review each transform
+│  └─> Choose: "By transform" → "🔘 All transforms"
+│
+└─ NO, I want to be selective
+   ├─> By category → Select specific ones
+   ├─> By item → Select specific ones
+   └─> By transform → Select specific ones
+```
+
+## Common Workflows
+
+### Quick & Complete Migration
+
+```bash
+npx @coinbase/cds-migrator
+# Select: Everything → Dry-run: Yes → Review → Apply
+```
+
+### Explore Before Committing
+
+```bash
+npx @coinbase/cds-migrator
+# Select: By item → See full list → Check "🔘 All items" → Apply
+```
+
+### Incremental Migration
+
+For large codebases, migrate in stages:
+
+```bash
+# Day 1: Migrate Button components
+npx @coinbase/cds-migrator
+# Choose: By item → components.Button
+
+# Day 2: Migrate Input components
+npx @coinbase/cds-migrator
+# Choose: By item → components.Input
+
+# Day 3: Migrate remaining items
+npx @coinbase/cds-migrator
+# Choose: By item → 🔘 All items (skips already-done Button/Input)
+```
+
+The history tracking ensures no duplicates across runs.
+
+### Team Migration
+
+**Developer A:**
+
+```bash
+npx @coinbase/cds-migrator
+# Migrates components
+git add . && git commit -m "Migrate components"
+git push
+```
+
+**Developer B:**
+
+```bash
+git pull
+npx @coinbase/cds-migrator
+# Migrates hooks (history prevents re-doing components)
+```
+
+## Troubleshooting
+
+### "Transform already run" warning
+
+This is normal! The migrator detected you've already applied this transform.
+
+**Options:**
+
+- Skip (recommended) - Only run new transforms
+- Re-run - Apply again (may cause issues)
+- Cancel - Exit without changes
+
+### Migration log shows errors
+
+Check `migration.log` for details:
+
+- **ERROR** entries - Transform failed
+- **TODO** entries - Need manual fixes
+- **WARN** entries - Review recommended
+
+### Need to re-run a transform
+
+Three options:
+
+1. Choose "Re-run all transforms" when prompted
+2. Clear history: `npx @coinbase/cds-migrator --clear-history -p ./src`
+3. Manually edit `.cds-migration-history.json`
+
+## Get Help
+
+- **Configuration questions** → See [CONFIGURATION.md](./CONFIGURATION.md)
+- **Writing transforms** → See [WRITING_TRANSFORMS.md](./WRITING_TRANSFORMS.md)
+- **Using utilities** → See [UTILITIES.md](./UTILITIES.md)
+- **History tracking** → See [HISTORY.md](./HISTORY.md)
+- **CLI flags and selection** → See [CLI_REFERENCE.md](./CLI_REFERENCE.md)
diff --git a/packages/migrator/docs/UTILITIES.md b/packages/migrator/docs/UTILITIES.md
new file mode 100644
index 000000000..eac5b2aae
--- /dev/null
+++ b/packages/migrator/docs/UTILITIES.md
@@ -0,0 +1,520 @@
+# Utilities API Reference
+
+Shared utility functions available in all CDS migration transforms.
+
+## Overview
+
+The utils directory provides:
+
+- **TODO insertion** - Mark code that needs manual migration
+- **Logging** - Track all migration activities to a file
+- **Config loading** - Load and process migration configurations
+- **History tracking** - Prevent duplicate migrations
+
+## Quick Reference
+
+```typescript
+// Import in your transform
+import {
+  // TODO utilities
+  addTodoToAttribute,
+  addTodoToImport,
+  hasMigrationTodo,
+
+  // Logging
+  getLogger,
+
+  // Config (used by CLI/runner, rarely needed in transforms)
+  loadMigrationConfig,
+  getSelectedTransforms,
+
+  // History (used by CLI/runner, rarely needed in transforms)
+  hasTransformBeenRun,
+} from '../../utils';
+```
+
+## TODO Utilities
+
+### addTodoToAttribute()
+
+Add a TODO comment to a JSX attribute when automatic migration isn't possible.
+
+**Signature:**
+
+```typescript
+function addTodoToAttribute(
+  j: API['jscodeshift'],
+  attributePath: any,
+  options: InsertTodoOptions,
+): void;
+```
+
+**Options:**
+
+```typescript
+interface InsertTodoOptions {
+  message: string; // Main TODO message
+  context?: string; // Additional context/instructions
+  position?: 'before' | 'after'; // Where to place comment
+}
+```
+
+**Example:**
+
+```typescript
+root.find(j.JSXAttribute, { name: { name: 'deprecatedProp' } }).forEach((path) => {
+  addTodoToAttribute(j, path, {
+    message: 'deprecatedProp has been removed',
+    context: 'Use newProp instead. See: https://...',
+  });
+});
+```
+
+**Output:**
+
+```tsx
+// TODO(cds-migration): deprecatedProp has been removed
+// Use newProp instead. See: https://...
+<Button deprecatedProp="value" />
+```
+
+### addTodoToImport()
+
+Add a TODO comment to an import statement.
+
+**Example:**
+
+```typescript
+root
+  .find(j.ImportDeclaration)
+  .filter((path) => /* condition */)
+  .forEach((path) => {
+    addTodoToImport(j, path, {
+      message: 'This import needs updating',
+      context: 'The API has changed significantly',
+    });
+  });
+```
+
+**Output:**
+
+```typescript
+// TODO(cds-migration): This import needs updating
+// The API has changed significantly
+import { OldComponent } from '@coinbase/cds-web';
+```
+
+### hasMigrationTodo()
+
+Check if a node already has a migration TODO to prevent duplicates.
+
+**Example:**
+
+```typescript
+root.find(j.JSXAttribute, { name: { name: 'prop' } }).forEach((path) => {
+  if (!hasMigrationTodo(path.parent)) {
+    addTodoToAttribute(j, path, { message: '...' });
+  }
+});
+```
+
+### insertTodoComment()
+
+Lower-level function to insert TODO near any AST node.
+
+**Example:**
+
+```typescript
+root.find(j.VariableDeclaration).forEach((path) => {
+  insertTodoComment(j, path, {
+    message: 'This variable needs updating',
+    position: 'before',
+  });
+});
+```
+
+### createTodoBlock()
+
+Create a standalone TODO comment block as a string.
+
+**Example:**
+
+```typescript
+const todoBlock = createTodoBlock({
+  message: 'Manual migration required',
+  context: 'Complex API changes need review',
+});
+// Returns: "// TODO(cds-migration): Manual migration required\n// Complex API changes need review\n"
+```
+
+## Logging
+
+### getLogger()
+
+Get the current logger instance (created automatically by the runner).
+
+**Example:**
+
+```typescript
+export default function transformer(file: FileInfo, api: API) {
+  const logger = getLogger();
+
+  // Use throughout your transform
+  logger?.success('Operation completed', file.path, 10);
+}
+```
+
+### Log Levels
+
+#### logger.info()
+
+General informational messages:
+
+```typescript
+logger?.info('Starting transformation', file.path);
+```
+
+#### logger.success()
+
+Successful transformations:
+
+```typescript
+logger?.success('Renamed prop', file.path, lineNumber);
+```
+
+#### logger.warn()
+
+Warnings about potential issues:
+
+```typescript
+logger?.warn(
+  'Could not auto-migrate complex case',
+  file.path,
+  lineNumber,
+  'This pattern is too complex for automatic migration',
+);
+```
+
+#### logger.error()
+
+Transform errors:
+
+```typescript
+logger?.error('Transform failed', file.path, lineNumber, error.message);
+```
+
+#### logger.todo()
+
+Mark items that need manual migration:
+
+```typescript
+logger?.todo(
+  'Manual migration required',
+  file.path,
+  lineNumber,
+  'This component uses deprecated APIs that need manual review',
+);
+```
+
+### Log Output Format
+
+```
+[2026-02-11T12:00:00.000Z] INFO: Starting migration
+[2026-02-11T12:00:01.000Z] SUCCESS [src/App.tsx:15]: Renamed prop
+[2026-02-11T12:00:02.000Z] WARN [src/Button.tsx:23]: Could not auto-migrate
+[2026-02-11T12:00:03.000Z] TODO [src/Complex.tsx:45]: Manual migration required
+  Additional context here
+[2026-02-11T12:00:04.000Z] ERROR [src/Error.tsx:10]: Transform failed
+  Error details
+```
+
+## Complete Transform Example
+
+```typescript
+import type { API, FileInfo } from 'jscodeshift';
+import { addTodoToAttribute, getLogger, hasMigrationTodo } from '../../utils';
+
+export default function transformer(file: FileInfo, api: API) {
+  const j = api.jscodeshift;
+  const root = j(file.source);
+  const logger = getLogger();
+
+  let hasChanges = false;
+
+  // 1. Simple rename - fully automatic
+  root
+    .find(j.JSXAttribute, { name: { name: 'variant' } })
+    .filter((path) => {
+      const element = path.parent.value.openingElement;
+      return j.JSXIdentifier.check(element.name) && element.name.name === 'Button';
+    })
+    .forEach((path) => {
+      if (j.JSXIdentifier.check(path.value.name)) {
+        path.value.name.name = 'appearance';
+        hasChanges = true;
+
+        logger?.success('Renamed variant to appearance', file.path, path.value.loc?.start.line);
+      }
+    });
+
+  // 2. Complex case - needs TODO
+  root.find(j.JSXAttribute, { name: { name: 'complexProp' } }).forEach((path) => {
+    if (!hasMigrationTodo(path.parent)) {
+      addTodoToAttribute(j, path, {
+        message: 'complexProp API has changed',
+        context: 'Review new API at https://docs.coinbase.com/cds/v9/button#complex-prop',
+      });
+
+      logger?.todo(
+        'Complex prop needs manual migration',
+        file.path,
+        path.value.loc?.start.line,
+        'The complexProp API has breaking changes that require manual review',
+      );
+
+      hasChanges = true;
+    }
+  });
+
+  // 3. Warning for edge case
+  root
+    .find(j.JSXExpressionContainer)
+    .filter((path) => {
+      const parent = path.parent.value;
+      return (
+        j.JSXAttribute.check(parent) &&
+        j.JSXIdentifier.check(parent.name) &&
+        parent.name.name === 'size'
+      );
+    })
+    .forEach((path) => {
+      logger?.warn(
+        'Size prop uses expression - verify value mapping',
+        file.path,
+        path.value.loc?.start.line,
+        'Size values changed from sm/md/lg to small/medium/large',
+      );
+    });
+
+  return hasChanges ? root.toSource() : null;
+}
+```
+
+## Constants
+
+### TODO_PREFIX
+
+The prefix used for all migration TODO comments.
+
+**Value:** `"TODO(cds-migration)"`
+
+**Usage:**
+
+```typescript
+import { TODO_PREFIX } from '../../utils';
+
+// Check if comment already exists
+if (comment.value.includes(TODO_PREFIX)) {
+  // Skip this node
+}
+```
+
+### LOG_FILE_NAME
+
+Default filename for migration logs.
+
+**Value:** `"migration.log"`
+
+## Config Loading
+
+These functions are primarily used by the CLI and runner, but are available if needed.
+
+### loadMigrationConfig()
+
+Load config.json for a migration version.
+
+```typescript
+const config = loadMigrationConfig('./src/v8-to-v9');
+console.log(config.categories);
+```
+
+### getSelectedTransforms()
+
+Get list of transforms based on user selection.
+
+```typescript
+const transforms = getSelectedTransforms(config, {
+  categories: ['components'],
+});
+```
+
+### buildMigrationSummary()
+
+Generate a formatted summary of what will be migrated.
+
+```typescript
+const summary = buildMigrationSummary(config, selection);
+console.log(summary);
+```
+
+## History Tracking
+
+These functions are used by the runner to prevent duplicate migrations.
+
+### hasTransformBeenRun()
+
+Check if a specific transform has already been applied.
+
+```typescript
+const wasRun = hasTransformBeenRun('./src', 'components.Button.button-variant-to-appearance');
+```
+
+### getAlreadyRunTransforms()
+
+Get list of transforms that have been run from a given set.
+
+```typescript
+const transformIds = [
+  'components.Button.button-variant-to-appearance',
+  'components.Input.input-size-values',
+];
+
+const alreadyRun = getAlreadyRunTransforms('./src', transformIds);
+// Returns: ['components.Button.button-variant-to-appearance']
+```
+
+### recordTransformRun()
+
+Record that a transform was executed (called automatically by runner).
+
+```typescript
+recordTransformRun(
+  './src',
+  'components.Button.button-variant-to-appearance',
+  'v8-to-v9',
+  false, // dryRun
+);
+```
+
+### loadMigrationHistory()
+
+Load the complete history for a path.
+
+```typescript
+const history = loadMigrationHistory('./src');
+if (history) {
+  console.log(`Applied ${history.entries.length} transforms`);
+}
+```
+
+### buildHistorySummary()
+
+Generate a formatted history report.
+
+```typescript
+const summary = buildHistorySummary('./src');
+console.log(summary);
+```
+
+## Type Definitions
+
+### InsertTodoOptions
+
+```typescript
+interface InsertTodoOptions {
+  message: string; // Main TODO message
+  context?: string; // Additional instructions
+  position?: 'before' | 'after'; // Placement (default: 'before')
+}
+```
+
+### MigrationHistory
+
+```typescript
+interface MigrationHistory {
+  targetPath: string; // Path that was migrated
+  entries: MigrationHistoryEntry[]; // List of transform runs
+  lastUpdated: string; // ISO timestamp
+}
+```
+
+### MigrationHistoryEntry
+
+```typescript
+interface MigrationHistoryEntry {
+  transformId: string; // e.g., "components.Button.button-variant"
+  timestamp: string; // ISO timestamp
+  version: string; // e.g., "v8-to-v9"
+  dryRun: boolean; // Whether it was a dry run
+}
+```
+
+## Best Practices
+
+### 1. Always Use getLogger()
+
+```typescript
+// ✅ Good
+const logger = getLogger();
+logger?.success('Operation completed', file.path);
+
+// ❌ Bad
+console.log('Operation completed'); // Won't be in log file
+```
+
+### 2. Check Before Adding TODOs
+
+```typescript
+// ✅ Good
+if (!hasMigrationTodo(path.parent)) {
+  addTodoToAttribute(j, path, { message: '...' });
+}
+
+// ❌ Bad
+addTodoToAttribute(j, path, { message: '...' }); // May duplicate
+```
+
+### 3. Log All Significant Operations
+
+```typescript
+// ✅ Good - Comprehensive logging
+logger?.success('Renamed prop', file.path, line);
+logger?.warn('Skipped complex case', file.path, line);
+logger?.todo('Manual work needed', file.path, line);
+
+// ❌ Bad - Silent operations
+path.value.name.name = 'newName'; // No logging
+```
+
+### 4. Provide Context in TODOs
+
+```typescript
+// ✅ Good - Actionable TODO
+addTodoToAttribute(j, path, {
+  message: 'complexProp API has changed',
+  context: 'See migration guide: https://docs.coinbase.com/cds/v9/button',
+});
+
+// ❌ Bad - Vague TODO
+addTodoToAttribute(j, path, {
+  message: 'Update this',
+});
+```
+
+### 5. Return null for Unchanged Files
+
+```typescript
+// ✅ Good
+if (!hasChanges) return null;
+return root.toSource();
+
+// ❌ Bad
+return root.toSource(); // Writes even if nothing changed
+```
+
+## See Also
+
+- [Writing Transforms](./WRITING_TRANSFORMS.md) - Transform development guide
+- [Configuration](./CONFIGURATION.md) - Config structure
+- [CLI Reference](./CLI_REFERENCE.md) - Running the migrator
+- [Quick Start](./QUICK_START.md) - Getting started
diff --git a/packages/migrator/docs/WRITING_TRANSFORMS.md b/packages/migrator/docs/WRITING_TRANSFORMS.md
new file mode 100644
index 000000000..cd23b46d6
--- /dev/null
+++ b/packages/migrator/docs/WRITING_TRANSFORMS.md
@@ -0,0 +1,431 @@
+# Writing Transforms
+
+Guide to creating jscodeshift transforms for CDS migrations.
+
+## Quick Start
+
+### 1. Create Transform File
+
+Create a file in the appropriate version's `transforms/` directory:
+
+```typescript
+// src/v8-to-v9/transforms/button-variant-to-appearance.ts
+import type { API, FileInfo } from 'jscodeshift';
+import { getLogger } from '../../utils';
+
+export default function transformer(file: FileInfo, api: API) {
+  const j = api.jscodeshift;
+  const root = j(file.source);
+  const logger = getLogger();
+
+  let hasChanges = false;
+
+  // Your transformation logic here
+
+  return hasChanges ? root.toSource() : null;
+}
+```
+
+### 2. Add to config.json
+
+```json
+{
+  "categories": {
+    "components": {
+      "variables": {
+        "Button": {
+          "transforms": [
+            {
+              "name": "button-variant-to-appearance",
+              "description": "Rename 'variant' prop to 'appearance'",
+              "file": "transforms/button-variant-to-appearance.ts"
+            }
+          ]
+        }
+      }
+    }
+  }
+}
+```
+
+### 3. Test
+
+```bash
+yarn nx run migrator:build
+node esm/cli.js
+# Select your transform in dry-run mode
+```
+
+## Transform Template
+
+```typescript
+import type { API, FileInfo } from 'jscodeshift';
+import { addTodoToAttribute, getLogger, hasMigrationTodo } from '../../utils';
+
+export default function transformer(file: FileInfo, api: API) {
+  const j = api.jscodeshift;
+  const root = j(file.source);
+  const logger = getLogger();
+
+  let hasChanges = false;
+
+  // 1. Find and transform what you can automatically
+  root.find(j.JSXAttribute, { name: { name: 'oldProp' } }).forEach((path) => {
+    if (j.JSXIdentifier.check(path.value.name)) {
+      path.value.name.name = 'newProp';
+      hasChanges = true;
+
+      logger?.success('Renamed oldProp to newProp', file.path, path.value.loc?.start.line);
+    }
+  });
+
+  // 2. Add TODOs for complex cases
+  root.find(j.JSXAttribute, { name: { name: 'complexProp' } }).forEach((path) => {
+    if (!hasMigrationTodo(path.parent)) {
+      addTodoToAttribute(j, path, {
+        message: 'complexProp needs manual migration',
+        context: 'See: https://docs.coinbase.com/cds/...',
+      });
+
+      logger?.todo('Manual migration required', file.path, path.value.loc?.start.line);
+
+      hasChanges = true;
+    }
+  });
+
+  // Return null if no changes (skip file write)
+  return hasChanges ? root.toSource() : null;
+}
+```
+
+## Common Patterns
+
+### Rename JSX Component
+
+```typescript
+root
+  .find(j.JSXElement)
+  .filter((path) => {
+    const name = path.value.openingElement.name;
+    return j.JSXIdentifier.check(name) && name.name === 'OldButton';
+  })
+  .forEach((path) => {
+    const opening = path.value.openingElement;
+    const closing = path.value.closingElement;
+
+    if (j.JSXIdentifier.check(opening.name)) {
+      opening.name.name = 'Button';
+    }
+    if (closing && j.JSXIdentifier.check(closing.name)) {
+      closing.name.name = 'Button';
+    }
+
+    logger?.success('Renamed OldButton to Button', file.path, path.value.loc?.start.line);
+  });
+```
+
+### Rename JSX Prop
+
+```typescript
+root
+  .find(j.JSXElement, {
+    openingElement: { name: { name: 'Button' } },
+  })
+  .find(j.JSXAttribute, { name: { name: 'variant' } })
+  .forEach((path) => {
+    if (j.JSXIdentifier.check(path.value.name)) {
+      path.value.name.name = 'appearance';
+
+      logger?.success(
+        'Renamed Button variant to appearance',
+        file.path,
+        path.value.loc?.start.line,
+      );
+    }
+  });
+```
+
+### Update Prop Values
+
+```typescript
+root.find(j.JSXAttribute, { name: { name: 'size' } }).forEach((path) => {
+  const value = path.value.value;
+
+  // Handle string literals
+  if (j.StringLiteral.check(value)) {
+    const mapping = { sm: 'small', md: 'medium', lg: 'large' };
+    const newValue = mapping[value.value];
+
+    if (newValue) {
+      value.value = newValue;
+      logger?.success(
+        `Updated size: ${value.value} → ${newValue}`,
+        file.path,
+        path.value.loc?.start.line,
+      );
+    }
+  }
+
+  // Handle JSX expressions: size={variable}
+  if (j.JSXExpressionContainer.check(value)) {
+    addTodoToAttribute(j, path, {
+      message: 'Size values have changed (sm/md/lg → small/medium/large)',
+      context: 'Update this variable to use new size values',
+    });
+
+    logger?.todo('Size prop needs manual update', file.path);
+  }
+});
+```
+
+### Update Imports
+
+```typescript
+root
+  .find(j.ImportDeclaration, {
+    source: { value: '@coinbase/cds-web' },
+  })
+  .forEach((path) => {
+    path.value.specifiers?.forEach((specifier) => {
+      if (j.ImportSpecifier.check(specifier) && specifier.imported.name === 'OldButton') {
+        specifier.imported.name = 'Button';
+        if (specifier.local) {
+          specifier.local.name = 'Button';
+        }
+
+        logger?.success(
+          'Updated import: OldButton → Button',
+          file.path,
+          path.value.loc?.start.line,
+        );
+      }
+    });
+  });
+```
+
+### Remove Props
+
+```typescript
+root.find(j.JSXAttribute, { name: { name: 'deprecatedProp' } }).forEach((path) => {
+  // Add TODO first
+  addTodoToAttribute(j, path, {
+    message: 'deprecatedProp has been removed',
+    context: 'This prop no longer exists. Remove or replace with alternative.',
+  });
+
+  logger?.warn('Found deprecated prop', file.path, path.value.loc?.start.line);
+
+  // Optionally remove it
+  // j(path).remove();
+});
+```
+
+### Add Imports
+
+```typescript
+// Check if import already exists
+const hasImport =
+  root
+    .find(j.ImportDeclaration, {
+      source: { value: '@coinbase/cds-web' },
+    })
+    .filter((path) =>
+      path.value.specifiers?.some(
+        (s) => j.ImportSpecifier.check(s) && s.imported.name === 'Button',
+      ),
+    ).length > 0;
+
+if (!hasImport) {
+  // Find first import from CDS
+  const firstCdsImport = root
+    .find(j.ImportDeclaration, {
+      source: { value: (v) => v.startsWith('@coinbase/cds') },
+    })
+    .at(0);
+
+  if (firstCdsImport.length > 0) {
+    // Add to existing import
+    const existingImport = firstCdsImport.get();
+    existingImport.value.specifiers?.push(j.importSpecifier(j.identifier('Button')));
+  } else {
+    // Add new import at top
+    root.find(j.Program).forEach((path) => {
+      path.value.body.unshift(
+        j.importDeclaration(
+          [j.importSpecifier(j.identifier('Button'))],
+          j.stringLiteral('@coinbase/cds-web'),
+        ),
+      );
+    });
+  }
+
+  logger?.success('Added Button import', file.path);
+}
+```
+
+## Best Practices
+
+### 1. Make Transforms Idempotent
+
+Transforms should be safe to run multiple times:
+
+```typescript
+// ✅ Good: Check before modifying
+const hasImport =
+  root.find(j.ImportDeclaration, {
+    source: { value: '@coinbase/cds' },
+  }).length > 0;
+
+if (hasImport) return null; // Already applied
+
+// ❌ Bad: Always adds import
+root.find(j.Program).forEach((path) => {
+  path.value.body.unshift(newImport);
+});
+```
+
+### 2. Always Use the Logger
+
+```typescript
+// ✅ Good: Log all operations
+logger?.success('Renamed prop', file.path, line);
+logger?.warn('Could not auto-migrate', file.path, line);
+logger?.todo('Manual work needed', file.path, line);
+
+// ❌ Bad: Silent transformations
+path.value.name.name = 'newName'; // No logging
+```
+
+### 3. Add TODOs for Complex Cases
+
+```typescript
+// ✅ Good: Mark what needs manual work
+if (!canAutoMigrate) {
+  addTodoToAttribute(j, path, {
+    message: 'This requires manual migration',
+    context: 'See documentation: ...',
+  });
+  logger?.todo('Manual migration needed', file.path, line);
+}
+
+// ❌ Bad: Skip silently
+if (!canAutoMigrate) {
+  return null; // User won't know what to fix
+}
+```
+
+### 4. Return null for Unchanged Files
+
+```typescript
+// ✅ Good: Skip write if no changes
+if (!hasChanges) {
+  return null;
+}
+return root.toSource();
+
+// ❌ Bad: Always return (writes even if nothing changed)
+return root.toSource();
+```
+
+### 5. Check for Existing TODOs
+
+```typescript
+// ✅ Good: Don't add duplicate TODOs
+if (!hasMigrationTodo(path.parent)) {
+  addTodoToAttribute(j, path, { message: '...' });
+}
+
+// ❌ Bad: Add TODO every time
+addTodoToAttribute(j, path, { message: '...' });
+```
+
+## Testing Transforms
+
+### Create Test Files
+
+```bash
+mkdir -p /tmp/migration-test/src
+```
+
+```tsx
+// /tmp/migration-test/src/Button.tsx
+import { Button } from '@coinbase/cds-web';
+
+export function MyButton() {
+  return <Button variant="primary">Click me</Button>;
+}
+```
+
+### Run in Dry-Run
+
+```bash
+cd packages/migrator
+node esm/cli.js
+# Select: By specific transform
+# Select your transform
+# Path: /tmp/migration-test/src
+# Dry-run: Yes
+```
+
+### Verify Output
+
+Check:
+
+- ✅ Correct files were modified
+- ✅ Changes are accurate
+- ✅ TODOs added where needed
+- ✅ No unintended side effects
+
+### Apply and Test
+
+```bash
+# Run without dry-run
+node esm/cli.js
+# Dry-run: No
+
+# Test the migrated code
+cd /tmp/migration-test
+yarn install
+yarn build
+yarn test
+```
+
+## Resources
+
+- [jscodeshift Documentation](https://github.com/facebook/jscodeshift)
+- [AST Explorer](https://astexplorer.net/) - Visualize JavaScript/TypeScript AST
+- [Utilities API](./UTILITIES.md) - Available helper functions
+- [Configuration Guide](./CONFIGURATION.md) - Config structure
+- [CLI Reference](./CLI_REFERENCE.md) - Running the migrator
+
+## Common Issues
+
+### "Transform not found"
+
+Error: `ENOENT: no such file or directory`
+
+**Solution:** Check the `file` path in config.json is correct relative to the version directory.
+
+### "No changes detected"
+
+The transform runs but no files are modified.
+
+**Possible causes:**
+
+- Transform logic doesn't match the code pattern
+- Files don't contain the target pattern
+- Transform is checking the wrong node type
+
+**Debug with AST Explorer:** Paste your code and see the actual AST structure.
+
+### "Transform runs on wrong files"
+
+**Solution:** Specify `extensions` in config.json:
+
+```json
+{
+  "name": "mobile-specific",
+  "file": "transforms/mobile-specific.ts",
+  "extensions": "tsx,jsx" // Only JSX files
+}
+```
diff --git a/packages/migrator/package.json b/packages/migrator/package.json
new file mode 100644
index 000000000..47335c489
--- /dev/null
+++ b/packages/migrator/package.json
@@ -0,0 +1,47 @@
+{
+  "name": "@coinbase/cds-migrator",
+  "version": "1.0.0",
+  "description": "Coinbase Design System - Code Migration Tools",
+  "repository": {
+    "type": "git",
+    "url": "git@github.com:coinbase/cds.git",
+    "directory": "packages/migrator"
+  },
+  "type": "module",
+  "main": "./esm/index.js",
+  "types": "./dts/index.d.ts",
+  "bin": {
+    "cds-migrate": "./esm/cli.js"
+  },
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./dts/index.d.ts",
+      "default": "./esm/index.js"
+    },
+    "./*": {
+      "types": "./dts/*.d.ts",
+      "default": "./esm/*.js"
+    }
+  },
+  "sideEffects": false,
+  "files": [
+    "dts",
+    "esm",
+    "CHANGELOG"
+  ],
+  "dependencies": {
+    "commander": "^11.1.0",
+    "inquirer": "^9.2.12",
+    "jscodeshift": "^0.15.1"
+  },
+  "devDependencies": {
+    "@babel/core": "^7.28.0",
+    "@babel/preset-env": "^7.28.0",
+    "@babel/preset-react": "^7.28.5",
+    "@babel/preset-typescript": "^7.27.1",
+    "@types/inquirer": "^9.0.7",
+    "@types/jscodeshift": "^0.11.10",
+    "@types/node": "^20.0.0"
+  }
+}
diff --git a/packages/migrator/project.json b/packages/migrator/project.json
new file mode 100644
index 000000000..a3ac821d0
--- /dev/null
+++ b/packages/migrator/project.json
@@ -0,0 +1,38 @@
+{
+  "name": "migrator",
+  "$schema": "../../node_modules/nx/schemas/project-schema.json",
+  "sourceRoot": "packages/migrator/src",
+  "projectType": "library",
+  "targets": {
+    "build": {
+      "executor": "nx:run-commands",
+      "defaultConfiguration": "dev",
+      "configurations": {
+        "dev": {
+          "command": "rm -rf esm && babel ./src --out-dir esm --extensions .ts,.tsx,.js,.jsx --copy-files --no-copy-ignored"
+        },
+        "prod": {
+          "commands": [
+            "rm -rf esm && babel ./src --out-dir esm --extensions .ts,.tsx,.js,.jsx --copy-files --no-copy-ignored"
+          ],
+          "parallel": false
+        }
+      }
+    },
+    "lint": {
+      "executor": "@nx/eslint:lint"
+    },
+    "typecheck": {
+      "executor": "nx:run-commands",
+      "defaultConfiguration": "dev",
+      "configurations": {
+        "dev": {
+          "command": "tsc --build --pretty --verbose"
+        },
+        "prod": {
+          "command": "tsc --build ./tsconfig.build.json --pretty --verbose"
+        }
+      }
+    }
+  }
+}
diff --git a/packages/migrator/src/cli-args.ts b/packages/migrator/src/cli-args.ts
new file mode 100644
index 000000000..dbbb1deff
--- /dev/null
+++ b/packages/migrator/src/cli-args.ts
@@ -0,0 +1,82 @@
+/**
+ * CLI argument parsing
+ */
+
+import { Command } from 'commander';
+import type { MigrationSelection } from './types.js';
+
+export interface CliArgs {
+  version?: string;
+  path?: string;
+  dryRun?: boolean;
+  skipConfirmation?: boolean;
+  clearHistory?: boolean;
+  all?: boolean;
+  category?: string[];
+  item?: string[];
+  transform?: string[];
+}
+
+export function parseCliArgs(): CliArgs {
+  const program = new Command();
+
+  program
+    .name('cds-migrate')
+    .description('CDS code migration tool')
+    .version('1.0.0')
+    .option('-m, --migration <version>', 'Migration version (e.g., v8-to-v9)')
+    .option('-p, --path <path>', 'Target path to migrate', './src')
+    .option('-d, --dry-run', 'Run in dry-run mode (preview changes)', false)
+    .option('--skip-confirmation', 'Skip confirmation prompts', false)
+    .option('--clear-history', 'Clear migration history for the specified path', false)
+    .option('--all', 'Migrate everything')
+    .option('--category <categories...>', 'Migrate specific categories')
+    .option('--item <items...>', 'Migrate specific items (components/hooks/utilities)')
+    .option('--transform <transforms...>', 'Migrate specific transforms');
+
+  program.parse();
+
+  const options = program.opts();
+
+  return {
+    version: options.migration,
+    path: options.path,
+    dryRun: options.dryRun,
+    skipConfirmation: options.skipConfirmation,
+    clearHistory: options.clearHistory,
+    all: options.all,
+    category: options.category,
+    item: options.item,
+    transform: options.transform,
+  };
+}
+
+export function buildSelectionFromArgs(args: CliArgs): MigrationSelection | null {
+  if (args.all) {
+    return { all: true };
+  }
+
+  if (args.transform && args.transform.length > 0) {
+    return { transforms: args.transform };
+  }
+
+  if (args.item && args.item.length > 0) {
+    return { items: args.item };
+  }
+
+  if (args.category && args.category.length > 0) {
+    return { categories: args.category };
+  }
+
+  return null;
+}
+
+export function hasRequiredArgs(args: CliArgs): boolean {
+  // Version and path are required for non-interactive mode
+  // Plus at least one selection method
+  return !!(
+    args.version &&
+    args.path &&
+    (args.all || args.category || args.item || args.transform)
+  );
+}
diff --git a/packages/migrator/src/cli.ts b/packages/migrator/src/cli.ts
new file mode 100644
index 000000000..dd7d9a072
--- /dev/null
+++ b/packages/migrator/src/cli.ts
@@ -0,0 +1,455 @@
+#!/usr/bin/env node
+
+/**
+ * CDS Migrator CLI
+ *
+ * Interactive tool to migrate codebases between CDS major versions
+ * Also supports non-interactive mode via CLI flags
+ */
+
+import inquirer from 'inquirer';
+import { runMigration } from './runner.js';
+import {
+  loadMigrationConfig,
+  buildMigrationSummary,
+  getSelectedTransforms,
+} from './utils/config-loader.js';
+import {
+  loadMigrationHistory,
+  getAlreadyRunTransforms,
+  buildHistorySummary,
+  clearMigrationHistory,
+} from './utils/migration-history.js';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import type { MigrationSelection } from './types.js';
+import { parseCliArgs, buildSelectionFromArgs, hasRequiredArgs, type CliArgs } from './cli-args.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const SUPPORTED_MIGRATIONS = [
+  {
+    name: 'v8 to v9',
+    value: 'v8-to-v9',
+    description: 'Migrate from CDS v8 to v9',
+  },
+] as const;
+
+async function selectMigrationScope(migrationDir: string): Promise<MigrationSelection> {
+  const config = loadMigrationConfig(migrationDir);
+
+  const { scope } = await inquirer.prompt([
+    {
+      type: 'list',
+      name: 'scope',
+      message: 'What would you like to migrate?',
+      choices: [
+        { name: 'Everything (all changes)', value: 'all' },
+        { name: 'By category (components, hooks, etc.)', value: 'category' },
+        { name: 'By item (specific component/hook/utility)', value: 'item' },
+        { name: 'By specific transform', value: 'transform' },
+      ],
+    },
+  ]);
+
+  if (scope === 'all') {
+    return { all: true };
+  }
+
+  if (scope === 'category') {
+    const categoryChoices = [
+      {
+        name: '🔘 All categories',
+        value: '__ALL__',
+        checked: false,
+      },
+      ...Object.entries(config.categories).map(([name, cat]) => ({
+        name: `${name} - ${cat.description}`,
+        value: name,
+        checked: false,
+      })),
+    ];
+
+    const { categories } = (await inquirer.prompt([
+      {
+        type: 'checkbox',
+        name: 'categories',
+        message: 'Select categories to migrate:',
+        choices: categoryChoices,
+        validate: (input: string[]) => {
+          if (input.length === 0) {
+            return 'Please select at least one category';
+          }
+          return true;
+        },
+      },
+    ] as any)) as { categories: string[] };
+
+    // If "All" is selected, return all categories
+    if (categories.includes('__ALL__')) {
+      return { all: true };
+    }
+
+    return { categories };
+  }
+
+  if (scope === 'item') {
+    // Build list of all items across categories
+    const itemChoices: Array<{ name: string; value: string; checked?: boolean }> = [
+      {
+        name: '🔘 All items',
+        value: '__ALL__',
+        checked: false,
+      },
+    ];
+
+    for (const [categoryName, category] of Object.entries(config.categories)) {
+      for (const [itemName, item] of Object.entries(category.variables)) {
+        itemChoices.push({
+          name: `${categoryName}.${itemName} - ${item.description} (${item.package})`,
+          value: `${categoryName}.${itemName}`,
+        });
+      }
+    }
+
+    const { items } = (await inquirer.prompt([
+      {
+        type: 'checkbox',
+        name: 'items',
+        message: 'Select items to migrate:',
+        choices: itemChoices,
+        validate: (input: string[]) => {
+          if (input.length === 0) {
+            return 'Please select at least one item';
+          }
+          return true;
+        },
+      },
+    ] as any)) as { items: string[] };
+
+    // If "All" is selected, return all items
+    if (items.includes('__ALL__')) {
+      return { all: true };
+    }
+
+    return { items };
+  }
+
+  if (scope === 'transform') {
+    // Build list of all transforms
+    const transformChoices: Array<{ name: string; value: string; checked?: boolean }> = [
+      {
+        name: '🔘 All transforms',
+        value: '__ALL__',
+        checked: false,
+      },
+    ];
+
+    for (const [categoryName, category] of Object.entries(config.categories)) {
+      for (const [variableName, variable] of Object.entries(category.variables)) {
+        for (const transform of variable.transforms) {
+          transformChoices.push({
+            name: `${categoryName}.${variableName}.${transform.name} - ${transform.description}`,
+            value: `${categoryName}.${variableName}.${transform.name}`,
+          });
+        }
+      }
+    }
+
+    const { transforms } = (await inquirer.prompt([
+      {
+        type: 'checkbox',
+        name: 'transforms',
+        message: 'Select transforms to run:',
+        choices: transformChoices,
+        validate: (input: string[]) => {
+          if (input.length === 0) {
+            return 'Please select at least one transform';
+          }
+          return true;
+        },
+      },
+    ] as any)) as { transforms: string[] };
+
+    // If "All" is selected, return all transforms
+    if (transforms.includes('__ALL__')) {
+      return { all: true };
+    }
+
+    return { transforms };
+  }
+
+  return { all: true };
+}
+
+async function runInteractiveMode() {
+  // Step 1: Select migration version
+  const answers = await inquirer.prompt([
+    {
+      type: 'list',
+      name: 'migration',
+      message: 'Which major version migration do you need?',
+      choices: SUPPORTED_MIGRATIONS.map((m) => ({
+        name: `${m.name} - ${m.description}`,
+        value: m.value,
+      })),
+    },
+  ]);
+
+  // Step 2: Ask for target path
+  const pathAnswer = await inquirer.prompt([
+    {
+      type: 'input',
+      name: 'path',
+      message: 'Enter the path to your codebase (relative or absolute):',
+      default: './src',
+      validate: (input: string) => {
+        if (!input || input.trim() === '') {
+          return 'Please provide a valid path';
+        }
+        return true;
+      },
+    },
+  ]);
+
+  const targetPath = pathAnswer.path;
+
+  // Step 3: Check and display migration history
+  const history = loadMigrationHistory(targetPath);
+  if (history && history.entries.length > 0) {
+    const historySummary = buildHistorySummary(targetPath);
+    console.log(historySummary);
+  }
+
+  // Step 4: Load config and let user select scope
+  const migrationDir = path.join(__dirname, answers.migration);
+  const selection = await selectMigrationScope(migrationDir);
+
+  // Step 5: Show what will be migrated
+  const config = loadMigrationConfig(migrationDir);
+  const summary = buildMigrationSummary(config, selection);
+  console.log(summary);
+
+  // Step 6: Ask for dry-run mode
+  const modeAnswer = await inquirer.prompt([
+    {
+      type: 'confirm',
+      name: 'dryRun',
+      message: 'Run in dry-run mode? (preview changes without modifying files)',
+      default: true,
+    },
+  ]);
+
+  // Check for migration history and warn about duplicate runs
+  const selectedTransforms = getSelectedTransforms(config, selection);
+  const transformIds = selectedTransforms.map((t) => `${t.category}.${t.variable}.${t.name}`);
+  const alreadyRun = getAlreadyRunTransforms(targetPath, transformIds);
+
+  if (alreadyRun.length > 0 && !modeAnswer.dryRun) {
+    console.log('\n⚠️  Warning: Some transforms have already been run on this path:\n');
+    for (const transformId of alreadyRun) {
+      console.log(`  • ${transformId}`);
+    }
+    console.log('');
+
+    const { action } = await inquirer.prompt([
+      {
+        type: 'list',
+        name: 'action',
+        message: 'How would you like to proceed?',
+        choices: [
+          {
+            name: 'Skip already-run transforms (recommended)',
+            value: 'skip',
+          },
+          {
+            name: 'Re-run all transforms (may cause issues)',
+            value: 'rerun',
+          },
+          {
+            name: 'Cancel migration',
+            value: 'cancel',
+          },
+        ],
+        default: 'skip',
+      },
+    ]);
+
+    if (action === 'cancel') {
+      console.log('\n❌ Migration cancelled.\n');
+      return;
+    }
+
+    if (action === 'skip') {
+      // Filter out already-run transforms
+      if (selection.transforms) {
+        selection.transforms = selection.transforms.filter((t) => !alreadyRun.includes(t));
+      } else if (selection.items) {
+        // For item selection, we need to filter at the item level
+        // This is complex, so we'll just warn the user
+        console.log('\n⚠️  Note: Skipping at the item level may leave some transforms incomplete.');
+        console.log('Consider using transform-level selection for more control.\n');
+      }
+      // For category or all selection, we can't easily filter, so just warn
+      if (selection.all || selection.categories) {
+        console.log(
+          '\n⚠️  Note: Cannot skip at category level. Some transforms may be skipped during execution.\n',
+        );
+      }
+    }
+  }
+
+  console.log('\n📋 Migration Summary:');
+  console.log(`  Version: ${answers.migration}`);
+  console.log(`  Path: ${targetPath}`);
+  console.log(`  Mode: ${modeAnswer.dryRun ? 'Dry Run' : 'Apply Changes'}\n`);
+
+  if (!modeAnswer.dryRun) {
+    const { confirm } = await inquirer.prompt([
+      {
+        type: 'confirm',
+        name: 'confirm',
+        message: '⚠️  This will modify your files. Continue?',
+        default: false,
+      },
+    ]);
+
+    if (!confirm) {
+      console.log('\n❌ Migration cancelled.\n');
+      return;
+    }
+  }
+
+  return {
+    migration: answers.migration,
+    path: targetPath,
+    dryRun: modeAnswer.dryRun,
+    selection,
+  };
+}
+
+async function runNonInteractiveMode(args: CliArgs) {
+  const migration = args.version!;
+  const targetPath = args.path!;
+  const dryRun = args.dryRun || false;
+  const selection = buildSelectionFromArgs(args);
+
+  if (!selection) {
+    console.error('Error: Must specify --all, --category, --item, or --transform');
+    process.exit(1);
+  }
+
+  // Validate migration version
+  const isValidMigration = SUPPORTED_MIGRATIONS.some((m) => m.value === migration);
+  if (!isValidMigration) {
+    console.error(`Error: Invalid migration version '${migration}'`);
+    console.error(`Available versions: ${SUPPORTED_MIGRATIONS.map((m) => m.value).join(', ')}`);
+    process.exit(1);
+  }
+
+  // Load config
+  const migrationDir = path.join(__dirname, migration);
+  const config = loadMigrationConfig(migrationDir);
+
+  // Show migration plan
+  const summary = buildMigrationSummary(config, selection);
+  console.log(summary);
+
+  // Check for duplicates
+  const selectedTransforms = getSelectedTransforms(config, selection);
+  const transformIds = selectedTransforms.map((t) => `${t.category}.${t.variable}.${t.name}`);
+  const alreadyRun = getAlreadyRunTransforms(targetPath, transformIds);
+
+  if (alreadyRun.length > 0 && !dryRun && !args.skipConfirmation) {
+    console.log('\n⚠️  Warning: Some transforms have already been run on this path:\n');
+    for (const transformId of alreadyRun) {
+      console.log(`  • ${transformId}`);
+    }
+    console.log('\nUse --skip-confirmation to bypass this check or run with --dry-run first.\n');
+    process.exit(1);
+  }
+
+  console.log('\n📋 Migration Summary:');
+  console.log(`  Version: ${migration}`);
+  console.log(`  Path: ${targetPath}`);
+  console.log(`  Mode: ${dryRun ? 'Dry Run' : 'Apply Changes'}`);
+  console.log(`  Transforms: ${selectedTransforms.length}\n`);
+
+  return {
+    migration,
+    path: targetPath,
+    dryRun,
+    selection,
+  };
+}
+
+async function main() {
+  console.log('\n🚀 CDS Migrator\n');
+
+  // Parse CLI arguments
+  const args = parseCliArgs();
+
+  // Handle clear-history command
+  if (args.clearHistory) {
+    if (!args.path) {
+      console.error('Error: --path is required when using --clear-history');
+      process.exit(1);
+    }
+
+    const history = loadMigrationHistory(args.path);
+    if (!history) {
+      console.log(`No migration history found at: ${args.path}`);
+      return;
+    }
+
+    const { confirm } = await inquirer.prompt([
+      {
+        type: 'confirm',
+        name: 'confirm',
+        message: `⚠️  Clear migration history for ${args.path}?`,
+        default: false,
+      },
+    ]);
+
+    if (confirm) {
+      clearMigrationHistory(args.path);
+      console.log(`✅ Migration history cleared for: ${args.path}\n`);
+    } else {
+      console.log('❌ Cancelled.\n');
+    }
+    return;
+  }
+
+  // Determine if running in interactive or non-interactive mode
+  const isNonInteractive = hasRequiredArgs(args);
+
+  let migrationOptions;
+
+  if (isNonInteractive) {
+    // Non-interactive mode with CLI flags
+    migrationOptions = await runNonInteractiveMode(args);
+  } else {
+    // Interactive mode with prompts
+    console.log('This tool will help you migrate your codebase between CDS major versions.\n');
+    migrationOptions = await runInteractiveMode();
+  }
+
+  if (!migrationOptions) {
+    console.error('\n❌ Migration setup failed.\n');
+    process.exit(1);
+  }
+
+  try {
+    await runMigration(migrationOptions);
+    console.log('\n✅ Migration completed successfully!\n');
+  } catch (error) {
+    console.error('\n❌ Migration failed:', error);
+    process.exit(1);
+  }
+}
+
+main().catch((error) => {
+  console.error('Unexpected error:', error);
+  process.exit(1);
+});
diff --git a/packages/migrator/src/index.ts b/packages/migrator/src/index.ts
new file mode 100644
index 000000000..815468540
--- /dev/null
+++ b/packages/migrator/src/index.ts
@@ -0,0 +1,9 @@
+/**
+ * @coinbase/cds-migrator
+ *
+ * Code migration tools for the Coinbase Design System
+ */
+
+export * from './types.js';
+export { runMigration } from './runner.js';
+export * from './utils/index.js';
diff --git a/packages/migrator/src/runner.ts b/packages/migrator/src/runner.ts
new file mode 100644
index 000000000..28b5bdba5
--- /dev/null
+++ b/packages/migrator/src/runner.ts
@@ -0,0 +1,124 @@
+/**
+ * Migration runner
+ *
+ * Coordinates the execution of version-specific migrations
+ */
+
+import { execSync } from 'child_process';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import {
+  createLogger,
+  loadMigrationConfig,
+  getSelectedTransforms,
+  hasTransformBeenRun,
+  recordTransformRun,
+} from './utils/index.js';
+import type { MigrationSelection } from './types.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+interface RunMigrationOptions {
+  migration: string;
+  path: string;
+  dryRun: boolean;
+  selection?: MigrationSelection;
+}
+
+export async function runMigration(options: RunMigrationOptions): Promise<void> {
+  const { migration, path: targetPath, dryRun, selection = { all: true } } = options;
+
+  console.log(`\n🔄 Running ${migration} migration...\n`);
+
+  // Create logger for this migration run
+  const logger = createLogger(process.cwd());
+  logger.info(`Starting ${migration} migration`);
+  logger.info(`Target path: ${targetPath}`);
+  logger.info(`Mode: ${dryRun ? 'Dry Run' : 'Apply Changes'}`);
+
+  // Load config and get selected transforms
+  const migrationDir = path.join(__dirname, migration);
+  const config = loadMigrationConfig(migrationDir);
+  const transforms = getSelectedTransforms(config, selection);
+
+  if (transforms.length === 0) {
+    console.log('ℹ️  No transforms selected for this migration.');
+    logger.warn('No transforms selected');
+    return;
+  }
+
+  logger.info(`Selected ${transforms.length} transforms to run`);
+
+  // Run each transform using jscodeshift
+  let skippedCount = 0;
+
+  for (const transform of transforms) {
+    const transformId = `${transform.category}.${transform.variable}.${transform.name}`;
+
+    // Check if this transform has already been run
+    if (!dryRun && hasTransformBeenRun(targetPath, transformId)) {
+      console.log(`\n  ⊘ Skipping (already run): ${transformId}`);
+      logger.info(`Skipped transform (already run): ${transformId}`);
+      skippedCount++;
+      continue;
+    }
+
+    console.log(`\n  → Running transform: ${transformId}`);
+    console.log(`    ${transform.description}`);
+    logger.info(
+      `Running transform: ${transform.name} (${transform.category}.${transform.variable})`,
+    );
+
+    const transformPath = path.join(migrationDir, transform.file);
+    const extensions = transform.extensions || 'tsx,ts,jsx,js';
+
+    try {
+      const jscodeshiftCmd = [
+        'npx',
+        'jscodeshift',
+        dryRun ? '--dry' : '',
+        '--parser=tsx',
+        `--extensions=${extensions}`,
+        '--ignore-pattern="**/node_modules/**"',
+        '--ignore-pattern="**/.next/**"',
+        '--ignore-pattern="**/dist/**"',
+        '--ignore-pattern="**/build/**"',
+        `--transform=${transformPath}`,
+        targetPath,
+      ]
+        .filter(Boolean)
+        .join(' ');
+
+      console.log(`    Command: ${jscodeshiftCmd}\n`);
+
+      execSync(jscodeshiftCmd, {
+        stdio: 'inherit',
+        cwd: process.cwd(),
+      });
+
+      console.log(`\n  ✓ Transform completed: ${transform.name}`);
+      logger.success(`Transform completed: ${transform.name}`);
+
+      // Record this transform run in history (only for non-dry-runs)
+      recordTransformRun(targetPath, transformId, migration, dryRun);
+    } catch (error) {
+      console.error(`\n  ✗ Transform failed: ${transform.name}`);
+      logger.error(
+        `Transform failed: ${transform.name}`,
+        undefined,
+        undefined,
+        error instanceof Error ? error.message : String(error),
+      );
+      throw error;
+    }
+  }
+
+  if (skippedCount > 0) {
+    console.log(`\n⊘ Skipped ${skippedCount} transform(s) that were already run.\n`);
+    logger.info(`Skipped ${skippedCount} transforms that were already run`);
+  }
+
+  // Write summary and close logger
+  logger.writeSummary();
+}
diff --git a/packages/migrator/src/types.ts b/packages/migrator/src/types.ts
new file mode 100644
index 000000000..bcebef7d2
--- /dev/null
+++ b/packages/migrator/src/types.ts
@@ -0,0 +1,118 @@
+/**
+ * Types for CDS migration tools
+ */
+
+export interface MigrationOptions {
+  /**
+   * Paths to files or directories to migrate
+   */
+  paths: string[];
+  /**
+   * Whether to perform a dry run without modifying files
+   */
+  dryRun?: boolean;
+}
+
+export interface Transform {
+  /**
+   * Name of the transform
+   */
+  name: string;
+  /**
+   * Description of what the transform does
+   */
+  description: string;
+  /**
+   * Path to the transform file (relative to migration directory)
+   */
+  file: string;
+  /**
+   * File extensions to process (comma-separated)
+   * @default "tsx,ts,jsx,js"
+   */
+  extensions?: string;
+}
+
+export interface MigrationModule {
+  /**
+   * List of transforms to run for this migration
+   */
+  transforms: Transform[];
+  /**
+   * Description of the migration and breaking changes
+   */
+  description: string;
+}
+
+/**
+ * Configuration for a migration variable (component, hook, utility, etc.)
+ */
+export interface MigrationVariable {
+  /**
+   * Human-readable description of the changes
+   */
+  description: string;
+  /**
+   * Package name where this variable is exported from
+   */
+  package: string;
+  /**
+   * List of transforms to apply for this variable
+   */
+  transforms: Transform[];
+}
+
+/**
+ * Configuration for a migration category
+ */
+export interface MigrationCategory {
+  /**
+   * Human-readable description of the category
+   */
+  description: string;
+  /**
+   * Variables (components, hooks, utilities, etc.) in this category
+   */
+  variables: Record<string, MigrationVariable>;
+}
+
+/**
+ * Main migration configuration structure
+ */
+export interface MigrationConfig {
+  /**
+   * Version identifier (e.g., "v8-to-v9")
+   */
+  version: string;
+  /**
+   * Overall description of the migration
+   */
+  description: string;
+  /**
+   * Categories of changes organized by type
+   */
+  categories: Record<string, MigrationCategory>;
+}
+
+/**
+ * Selection for what to migrate
+ */
+export interface MigrationSelection {
+  /**
+   * If true, migrate everything
+   */
+  all?: boolean;
+  /**
+   * Specific categories to migrate
+   */
+  categories?: string[];
+  /**
+   * Specific items to migrate (format: "category.item")
+   * Items are components, hooks, utilities, etc.
+   */
+  items?: string[];
+  /**
+   * Specific transforms to migrate (format: "category.item.transform")
+   */
+  transforms?: string[];
+}
diff --git a/packages/migrator/src/utils/config-loader.ts b/packages/migrator/src/utils/config-loader.ts
new file mode 100644
index 000000000..ab00c8749
--- /dev/null
+++ b/packages/migrator/src/utils/config-loader.ts
@@ -0,0 +1,155 @@
+/**
+ * Configuration loader utilities
+ */
+
+import fs from 'fs';
+import path from 'path';
+import type { MigrationConfig, Transform, MigrationSelection } from '../types.js';
+
+/**
+ * Load migration configuration from config.json
+ */
+export function loadMigrationConfig(migrationDir: string): MigrationConfig {
+  const configPath = path.join(migrationDir, 'config.json');
+
+  if (!fs.existsSync(configPath)) {
+    throw new Error(`Migration config not found: ${configPath}`);
+  }
+
+  const configContent = fs.readFileSync(configPath, 'utf-8');
+  return JSON.parse(configContent) as MigrationConfig;
+}
+
+/**
+ * Get all transforms from config based on selection
+ */
+export function getSelectedTransforms(
+  config: MigrationConfig,
+  selection: MigrationSelection,
+): Array<Transform & { category: string; variable: string }> {
+  const transforms: Array<Transform & { category: string; variable: string }> = [];
+
+  // If migrate all, collect everything
+  if (selection.all) {
+    for (const [categoryName, category] of Object.entries(config.categories)) {
+      for (const [variableName, variable] of Object.entries(category.variables)) {
+        for (const transform of variable.transforms) {
+          transforms.push({
+            ...transform,
+            category: categoryName,
+            variable: variableName,
+          });
+        }
+      }
+    }
+    return transforms;
+  }
+
+  // Collect by specific transforms
+  if (selection.transforms && selection.transforms.length > 0) {
+    for (const transformPath of selection.transforms) {
+      const [categoryName, variableName, transformName] = transformPath.split('.');
+      const transform = config.categories[categoryName]?.variables[variableName]?.transforms.find(
+        (t) => t.name === transformName,
+      );
+      if (transform) {
+        transforms.push({
+          ...transform,
+          category: categoryName,
+          variable: variableName,
+        });
+      }
+    }
+    return transforms;
+  }
+
+  // Collect by specific items
+  if (selection.items && selection.items.length > 0) {
+    for (const itemPath of selection.items) {
+      const [categoryName, itemName] = itemPath.split('.');
+      const item = config.categories[categoryName]?.variables[itemName];
+      if (item) {
+        for (const transform of item.transforms) {
+          transforms.push({
+            ...transform,
+            category: categoryName,
+            variable: itemName,
+          });
+        }
+      }
+    }
+    return transforms;
+  }
+
+  // Collect by specific categories
+  if (selection.categories && selection.categories.length > 0) {
+    for (const categoryName of selection.categories) {
+      const category = config.categories[categoryName];
+      if (category) {
+        for (const [variableName, variable] of Object.entries(category.variables)) {
+          for (const transform of variable.transforms) {
+            transforms.push({
+              ...transform,
+              category: categoryName,
+              variable: variableName,
+            });
+          }
+        }
+      }
+    }
+    return transforms;
+  }
+
+  return transforms;
+}
+
+/**
+ * Build a summary of what will be migrated
+ */
+export function buildMigrationSummary(
+  config: MigrationConfig,
+  selection: MigrationSelection,
+): string {
+  const transforms = getSelectedTransforms(config, selection);
+  const byCategory: Record<string, Array<{ variable: string; transform: string }>> = {};
+
+  for (const transform of transforms) {
+    if (!byCategory[transform.category]) {
+      byCategory[transform.category] = [];
+    }
+    byCategory[transform.category].push({
+      variable: transform.variable,
+      transform: transform.name,
+    });
+  }
+
+  let summary = '\nMigration Plan:\n';
+  summary += '================\n\n';
+
+  for (const [category, items] of Object.entries(byCategory)) {
+    const categoryInfo = config.categories[category];
+    summary += `📦 ${category}: ${categoryInfo.description}\n`;
+
+    const byVariable: Record<string, string[]> = {};
+    for (const item of items) {
+      if (!byVariable[item.variable]) {
+        byVariable[item.variable] = [];
+      }
+      byVariable[item.variable].push(item.transform);
+    }
+
+    for (const [variable, transformNames] of Object.entries(byVariable)) {
+      const variableInfo = categoryInfo.variables[variable];
+      summary += `  └─ ${variable} (${variableInfo.package})\n`;
+      for (const transformName of transformNames) {
+        const transform = variableInfo.transforms.find((t) => t.name === transformName);
+        summary += `     • ${transform?.description || transformName}\n`;
+      }
+    }
+    summary += '\n';
+  }
+
+  summary += `Total transforms: ${transforms.length}\n`;
+
+  return summary;
+}
diff --git a/packages/migrator/src/utils/constants.ts b/packages/migrator/src/utils/constants.ts
new file mode 100644
index 000000000..9a3ecd411
--- /dev/null
+++ b/packages/migrator/src/utils/constants.ts
@@ -0,0 +1,6 @@
+/**
+ * Constants used across migration utilities
+ */
+
+export const TODO_PREFIX = 'TODO(cds-migration)';
+export const LOG_FILE_NAME = 'migration.log';
diff --git a/packages/migrator/src/utils/index.ts b/packages/migrator/src/utils/index.ts
new file mode 100644
index 000000000..bf9a6d841
--- /dev/null
+++ b/packages/migrator/src/utils/index.ts
@@ -0,0 +1,9 @@
+/**
+ * Shared utility functions for CDS migrations
+ */
+
+export * from './insert-todo.js';
+export * from './logger.js';
+export * from './constants.js';
+export * from './config-loader.js';
+export * from './migration-history.js';
diff --git a/packages/migrator/src/utils/insert-todo.ts b/packages/migrator/src/utils/insert-todo.ts
new file mode 100644
index 000000000..aa7ffdeeb
--- /dev/null
+++ b/packages/migrator/src/utils/insert-todo.ts
@@ -0,0 +1,135 @@
+/**
+ * Utilities for inserting TODO comments when automatic migration is not possible
+ */
+
+import type { API, Collection } from 'jscodeshift';
+import { TODO_PREFIX } from './constants.js';
+
+export interface InsertTodoOptions {
+  /**
+   * The message to include in the TODO comment
+   */
+  message: string;
+  /**
+   * Additional context or instructions
+   */
+  context?: string;
+  /**
+   * Whether to insert before or after the node
+   */
+  position?: 'before' | 'after';
+}
+
+/**
+ * Insert a TODO comment near a JSX element
+ *
+ * @example
+ * // Before
+ * <Button variant="old" />
+ *
+ * // After
+ * // TODO(cds-migration): The 'variant' prop has been removed. Use 'appearance' instead.
+ * // See: https://docs.coinbase.com/cds/migration-guide
+ * <Button variant="old" />
+ */
+export function insertTodoComment(
+  j: API['jscodeshift'],
+  path: any,
+  options: InsertTodoOptions,
+): void {
+  const { message, context, position = 'before' } = options;
+
+  // Build the comment text
+  let commentText = `${TODO_PREFIX}: ${message}`;
+  if (context) {
+    commentText += `\n${context}`;
+  }
+
+  // Create comment nodes
+  const comment = j.commentLine(` ${TODO_PREFIX}: ${message}`, true, false);
+
+  // Add context as a separate comment if provided
+  const comments = [comment];
+  if (context) {
+    const contextComment = j.commentLine(` ${context}`, true, false);
+    comments.push(contextComment);
+  }
+
+  // Insert comments
+  if (position === 'before') {
+    path.value.comments = [...comments, ...(path.value.comments || [])];
+  } else {
+    path.value.comments = [...(path.value.comments || []), ...comments];
+  }
+}
+
+/**
+ * Add a TODO comment to a JSX attribute when it cannot be automatically migrated
+ *
+ * @example
+ * j(file.source)
+ *   .find(j.JSXAttribute, { name: { name: 'oldProp' } })
+ *   .forEach((path) => {
+ *     addTodoToAttribute(j, path, {
+ *       message: 'This prop needs manual migration',
+ *       context: 'See migration guide: https://...'
+ *     });
+ *   });
+ */
+export function addTodoToAttribute(
+  j: API['jscodeshift'],
+  attributePath: any,
+  options: InsertTodoOptions,
+): void {
+  const jsxElement = attributePath.parent;
+  if (jsxElement) {
+    insertTodoComment(j, jsxElement, options);
+  }
+}
+
+/**
+ * Add a TODO comment to an import statement
+ *
+ * @example
+ * j(file.source)
+ *   .find(j.ImportDeclaration)
+ *   .forEach((path) => {
+ *     addTodoToImport(j, path, {
+ *       message: 'This import needs to be updated manually'
+ *     });
+ *   });
+ */
+export function addTodoToImport(
+  j: API['jscodeshift'],
+  importPath: any,
+  options: InsertTodoOptions,
+): void {
+  insertTodoComment(j, importPath, options);
+}
+
+/**
+ * Create a standalone TODO comment block
+ *
+ * @example
+ * const todoBlock = createTodoBlock({
+ *   message: 'Manual migration required',
+ *   context: 'This component uses deprecated APIs that cannot be automatically migrated.'
+ * });
+ * // Returns formatted comment block as string
+ */
+export function createTodoBlock(options: InsertTodoOptions): string {
+  const { message, context } = options;
+  let block = `// ${TODO_PREFIX}: ${message}\n`;
+  if (context) {
+    block += `// ${context}\n`;
+  }
+  return block;
+}
+
+/**
+ * Check if a node already has a migration TODO comment
+ */
+export function hasMigrationTodo(path: any): boolean {
+  const comments = path.value.comments || [];
+  return comments.some((comment: any) => comment.value && comment.value.includes(TODO_PREFIX));
+}
diff --git a/packages/migrator/src/utils/logger.ts b/packages/migrator/src/utils/logger.ts
new file mode 100644
index 000000000..c3e43745f
--- /dev/null
+++ b/packages/migrator/src/utils/logger.ts
@@ -0,0 +1,200 @@
+/**
+ * Logging utilities for tracking migration progress and issues
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { LOG_FILE_NAME } from './constants.js';
+
+export const LogLevel = {
+  INFO: 'INFO',
+  WARN: 'WARN',
+  ERROR: 'ERROR',
+  SUCCESS: 'SUCCESS',
+  TODO: 'TODO',
+} as const;
+
+export type LogLevel = (typeof LogLevel)[keyof typeof LogLevel];
+
+export interface LogEntry {
+  timestamp: string;
+  level: LogLevel;
+  file?: string;
+  line?: number;
+  message: string;
+  details?: string;
+}
+
+/**
+ * Migration logger for tracking changes and issues
+ */
+export class MigrationLogger {
+  private logPath: string;
+  private entries: LogEntry[] = [];
+
+  constructor(outputDir: string = process.cwd()) {
+    this.logPath = path.join(outputDir, LOG_FILE_NAME);
+    this.initializeLog();
+  }
+
+  private initializeLog(): void {
+    const header = `CDS Migration Log
+Generated: ${new Date().toISOString()}
+========================================\n\n`;
+
+    fs.writeFileSync(this.logPath, header, 'utf-8');
+  }
+
+  /**
+   * Add a log entry
+   */
+  private addEntry(entry: LogEntry): void {
+    this.entries.push(entry);
+    this.writeEntry(entry);
+  }
+
+  private writeEntry(entry: LogEntry): void {
+    const location = entry.file ? ` [${entry.file}${entry.line ? `:${entry.line}` : ''}]` : '';
+    const details = entry.details ? `\n  ${entry.details}` : '';
+
+    const line = `[${entry.timestamp}] ${entry.level}${location}: ${entry.message}${details}\n`;
+    fs.appendFileSync(this.logPath, line, 'utf-8');
+  }
+
+  /**
+   * Log an informational message
+   */
+  info(message: string, file?: string, line?: number): void {
+    this.addEntry({
+      timestamp: new Date().toISOString(),
+      level: LogLevel.INFO,
+      file,
+      line,
+      message,
+    });
+  }
+
+  /**
+   * Log a warning
+   */
+  warn(message: string, file?: string, line?: number, details?: string): void {
+    this.addEntry({
+      timestamp: new Date().toISOString(),
+      level: LogLevel.WARN,
+      file,
+      line,
+      message,
+      details,
+    });
+  }
+
+  /**
+   * Log an error
+   */
+  error(message: string, file?: string, line?: number, details?: string): void {
+    this.addEntry({
+      timestamp: new Date().toISOString(),
+      level: LogLevel.ERROR,
+      file,
+      line,
+      message,
+      details,
+    });
+  }
+
+  /**
+   * Log a successful transformation
+   */
+  success(message: string, file?: string, line?: number): void {
+    this.addEntry({
+      timestamp: new Date().toISOString(),
+      level: LogLevel.SUCCESS,
+      file,
+      line,
+      message,
+    });
+  }
+
+  /**
+   * Log a TODO item (manual migration required)
+   */
+  todo(message: string, file?: string, line?: number, details?: string): void {
+    this.addEntry({
+      timestamp: new Date().toISOString(),
+      level: LogLevel.TODO,
+      file,
+      line,
+      message,
+      details,
+    });
+  }
+
+  /**
+   * Generate a summary of the migration
+   */
+  writeSummary(): void {
+    const summary = `
+========================================
+Migration Summary
+========================================
+
+Total Entries: ${this.entries.length}
+- INFO: ${this.entries.filter((e) => e.level === LogLevel.INFO).length}
+- SUCCESS: ${this.entries.filter((e) => e.level === LogLevel.SUCCESS).length}
+- WARN: ${this.entries.filter((e) => e.level === LogLevel.WARN).length}
+- ERROR: ${this.entries.filter((e) => e.level === LogLevel.ERROR).length}
+- TODO: ${this.entries.filter((e) => e.level === LogLevel.TODO).length}
+
+`;
+
+    fs.appendFileSync(this.logPath, summary, 'utf-8');
+
+    // List all TODO items
+    const todos = this.entries.filter((e) => e.level === LogLevel.TODO);
+    if (todos.length > 0) {
+      const todoList = `
+Manual Migration Required (${todos.length} items):
+${todos.map((t) => `  - ${t.file || 'Unknown file'}: ${t.message}`).join('\n')}
+
+`;
+      fs.appendFileSync(this.logPath, todoList, 'utf-8');
+    }
+
+    console.log(`\n📝 Migration log written to: ${this.logPath}`);
+  }
+
+  /**
+   * Get the log file path
+   */
+  getLogPath(): string {
+    return this.logPath;
+  }
+
+  /**
+   * Get all log entries
+   */
+  getEntries(): LogEntry[] {
+    return [...this.entries];
+  }
+
+  /**
+   * Get entries by level
+   */
+  getEntriesByLevel(level: LogLevel): LogEntry[] {
+    return this.entries.filter((e) => e.level === level);
+  }
+}
+
+/**
+ * Create a global logger instance
+ */
+let globalLogger: MigrationLogger | null = null;
+
+export function createLogger(outputDir?: string): MigrationLogger {
+  globalLogger = new MigrationLogger(outputDir);
+  return globalLogger;
+}
+
+export function getLogger(): MigrationLogger | null {
+  return globalLogger;
+}
diff --git a/packages/migrator/src/utils/migration-history.ts b/packages/migrator/src/utils/migration-history.ts
new file mode 100644
index 000000000..4f47ab6c2
--- /dev/null
+++ b/packages/migrator/src/utils/migration-history.ts
@@ -0,0 +1,204 @@
+/**
+ * Migration history tracking
+ *
+ * Keeps track of which transforms have been run on a given path
+ */
+
+import fs from 'fs';
+import path from 'path';
+import type { Transform } from '../types.js';
+
+const HISTORY_FILE_NAME = '.cds-migration-history.json';
+
+export interface MigrationHistoryEntry {
+  /**
+   * Transform identifier (e.g., "components.Button.button-variant-to-appearance")
+   */
+  transformId: string;
+  /**
+   * When the transform was run
+   */
+  timestamp: string;
+  /**
+   * Version migration (e.g., "v8-to-v9")
+   */
+  version: string;
+  /**
+   * Whether it was a dry run
+   */
+  dryRun: boolean;
+}
+
+export interface MigrationHistory {
+  /**
+   * Target path that was migrated
+   */
+  targetPath: string;
+  /**
+   * List of all transform runs
+   */
+  entries: MigrationHistoryEntry[];
+  /**
+   * Last update timestamp
+   */
+  lastUpdated: string;
+}
+
+/**
+ * Get the history file path for a target directory
+ */
+function getHistoryFilePath(targetPath: string): string {
+  // If targetPath is a file, use its directory
+  const stats = fs.existsSync(targetPath) ? fs.statSync(targetPath) : null;
+  const dir = stats?.isDirectory() ? targetPath : path.dirname(targetPath);
+
+  return path.join(dir, HISTORY_FILE_NAME);
+}
+
+/**
+ * Load migration history for a target path
+ */
+export function loadMigrationHistory(targetPath: string): MigrationHistory | null {
+  const historyPath = getHistoryFilePath(targetPath);
+
+  if (!fs.existsSync(historyPath)) {
+    return null;
+  }
+
+  try {
+    const content = fs.readFileSync(historyPath, 'utf-8');
+    return JSON.parse(content) as MigrationHistory;
+  } catch (error) {
+    console.warn(`Warning: Could not load migration history from ${historyPath}`);
+    return null;
+  }
+}
+
+/**
+ * Save migration history for a target path
+ */
+export function saveMigrationHistory(targetPath: string, history: MigrationHistory): void {
+  const historyPath = getHistoryFilePath(targetPath);
+
+  try {
+    fs.writeFileSync(historyPath, JSON.stringify(history, null, 2), 'utf-8');
+  } catch (error) {
+    console.warn(`Warning: Could not save migration history to ${historyPath}`);
+  }
+}
+
+/**
+ * Record a transform run in the history
+ */
+export function recordTransformRun(
+  targetPath: string,
+  transformId: string,
+  version: string,
+  dryRun: boolean,
+): void {
+  let history = loadMigrationHistory(targetPath);
+
+  if (!history) {
+    history = {
+      targetPath,
+      entries: [],
+      lastUpdated: new Date().toISOString(),
+    };
+  }
+
+  // Add new entry
+  history.entries.push({
+    transformId,
+    timestamp: new Date().toISOString(),
+    version,
+    dryRun,
+  });
+
+  history.lastUpdated = new Date().toISOString();
+
+  // Don't save history for dry runs (they don't modify files)
+  if (!dryRun) {
+    saveMigrationHistory(targetPath, history);
+  }
+}
+
+/**
+ * Check if a transform has already been run (non-dry-run)
+ */
+export function hasTransformBeenRun(targetPath: string, transformId: string): boolean {
+  const history = loadMigrationHistory(targetPath);
+
+  if (!history) {
+    return false;
+  }
+
+  // Check if this transform was run in a non-dry-run mode
+  return history.entries.some((entry) => entry.transformId === transformId && !entry.dryRun);
+}
+
+/**
+ * Get list of transforms that have already been run
+ */
+export function getAlreadyRunTransforms(targetPath: string, transformIds: string[]): string[] {
+  const history = loadMigrationHistory(targetPath);
+
+  if (!history) {
+    return [];
+  }
+
+  const runTransformIds = new Set(
+    history.entries.filter((entry) => !entry.dryRun).map((entry) => entry.transformId),
+  );
+
+  return transformIds.filter((id) => runTransformIds.has(id));
+}
+
+/**
+ * Build a summary of migration history
+ */
+export function buildHistorySummary(targetPath: string): string {
+  const history = loadMigrationHistory(targetPath);
+
+  if (!history || history.entries.length === 0) {
+    return 'No migration history found for this path.';
+  }
+
+  // Group entries by version
+  const byVersion: Record<string, MigrationHistoryEntry[]> = {};
+  for (const entry of history.entries) {
+    if (!entry.dryRun) {
+      // Only show non-dry-run entries
+      if (!byVersion[entry.version]) {
+        byVersion[entry.version] = [];
+      }
+      byVersion[entry.version].push(entry);
+    }
+  }
+
+  let summary = '\n📜 Migration History\n';
+  summary += '==================\n\n';
+
+  for (const [version, entries] of Object.entries(byVersion)) {
+    summary += `${version}:\n`;
+    for (const entry of entries) {
+      const date = new Date(entry.timestamp).toLocaleDateString();
+      summary += `  • ${entry.transformId} (${date})\n`;
+    }
+    summary += '\n';
+  }
+
+  summary += `Last updated: ${new Date(history.lastUpdated).toLocaleString()}\n`;
+
+  return summary;
+}
+
+/**
+ * Clear migration history for a target path
+ */
+export function clearMigrationHistory(targetPath: string): void {
+  const historyPath = getHistoryFilePath(targetPath);
+
+  if (fs.existsSync(historyPath)) {
+    fs.unlinkSync(historyPath);
+  }
+}
diff --git a/packages/migrator/src/v8-to-v9/config.json b/packages/migrator/src/v8-to-v9/config.json
new file mode 100644
index 000000000..6218f956d
--- /dev/null
+++ b/packages/migrator/src/v8-to-v9/config.json
@@ -0,0 +1,65 @@
+{
+  "version": "v8-to-v9",
+  "description": "Migration from CDS v8 to v9",
+  "categories": {
+    "components": {
+      "description": "Component API changes",
+      "variables": {
+        "Button": {
+          "description": "Button component prop changes",
+          "package": "@coinbase/cds-web",
+          "transforms": [
+            {
+              "name": "button-variant-to-appearance",
+              "description": "Rename 'variant' prop to 'appearance'",
+              "file": "transforms/button-variant-to-appearance.ts"
+            }
+          ]
+        },
+        "Input": {
+          "description": "Input component prop changes",
+          "package": "@coinbase/cds-web",
+          "transforms": [
+            {
+              "name": "input-size-values",
+              "description": "Update size prop values (sm/md/lg to small/medium/large)",
+              "file": "transforms/input-size-values.ts"
+            }
+          ]
+        }
+      }
+    },
+    "hooks": {
+      "description": "Hook API changes",
+      "variables": {
+        "useTheme": {
+          "description": "useTheme hook signature changes",
+          "package": "@coinbase/cds-common",
+          "transforms": [
+            {
+              "name": "use-theme-return-type",
+              "description": "Update destructured return values from useTheme",
+              "file": "transforms/use-theme-return-type.ts"
+            }
+          ]
+        }
+      }
+    },
+    "utilities": {
+      "description": "Utility function changes",
+      "variables": {
+        "formatCurrency": {
+          "description": "formatCurrency function signature changes",
+          "package": "@coinbase/cds-utils",
+          "transforms": [
+            {
+              "name": "format-currency-options",
+              "description": "Update formatCurrency options parameter",
+              "file": "transforms/format-currency-options.ts"
+            }
+          ]
+        }
+      }
+    }
+  }
+}
diff --git a/packages/migrator/src/v8-to-v9/index.ts b/packages/migrator/src/v8-to-v9/index.ts
new file mode 100644
index 000000000..397ddfad5
--- /dev/null
+++ b/packages/migrator/src/v8-to-v9/index.ts
@@ -0,0 +1,35 @@
+/**
+ * v8 to v9 Migration
+ *
+ * This module defines all transforms needed to migrate from CDS v8 to v9
+ */
+
+export interface Transform {
+  name: string;
+  description: string;
+  file: string;
+  extensions?: string;
+}
+
+export const transforms: Transform[] = [
+  // Add transforms here as they are created
+  // Example:
+  // {
+  //   name: 'update-button-props',
+  //   description: 'Update Button component props',
+  //   file: 'transforms/update-button-props.ts',
+  // },
+];
+
+export const description = `
+CDS v8 to v9 Migration
+======================
+
+This migration includes the following transforms:
+${transforms.map((t) => `  - ${t.name}: ${t.description}`).join('\n')}
+
+Breaking changes in v9:
+- [Add breaking changes here as they are identified]
+
+Please review the changes carefully before committing.
+`;
diff --git a/packages/migrator/src/v8-to-v9/transforms/.gitkeep b/packages/migrator/src/v8-to-v9/transforms/.gitkeep
new file mode 100644
index 000000000..dd4cf7bd9
--- /dev/null
+++ b/packages/migrator/src/v8-to-v9/transforms/.gitkeep
@@ -0,0 +1,2 @@
+# Transforms directory
+# Add jscodeshift transform files here
diff --git a/packages/migrator/src/v8-to-v9/transforms/example-transform.ts b/packages/migrator/src/v8-to-v9/transforms/example-transform.ts
new file mode 100644
index 000000000..2efff738b
--- /dev/null
+++ b/packages/migrator/src/v8-to-v9/transforms/example-transform.ts
@@ -0,0 +1,90 @@
+/**
+ * Example Transform
+ *
+ * This is a template/example transform showing how to write codemods for CDS migrations.
+ * You can use this as a starting point for creating actual migration transforms.
+ */
+
+import type { API, FileInfo, Options } from 'jscodeshift';
+import { addTodoToAttribute, getLogger, hasMigrationTodo } from '../../utils/index.js';
+
+export default function transformer(file: FileInfo, api: API, options: Options) {
+  const j = api.jscodeshift;
+  const root = j(file.source);
+  const logger = getLogger();
+
+  let hasChanges = false;
+
+  // Example 1: Rename a component
+  root
+    .find(j.JSXElement)
+    .filter((path) => {
+      const openingElement = path.value.openingElement;
+      return j.JSXIdentifier.check(openingElement.name) && openingElement.name.name === 'OldButton';
+    })
+    .forEach((path) => {
+      // Rename component
+      const openingElement = path.value.openingElement;
+      const closingElement = path.value.closingElement;
+
+      if (j.JSXIdentifier.check(openingElement.name)) {
+        openingElement.name.name = 'Button';
+        hasChanges = true;
+
+        logger?.success('Renamed OldButton to Button', file.path, path.value.loc?.start.line);
+      }
+
+      if (closingElement && j.JSXIdentifier.check(closingElement.name)) {
+        closingElement.name.name = 'Button';
+      }
+    });
+
+  // Example 2: Add TODO for complex migrations
+  root.find(j.JSXAttribute, { name: { name: 'deprecatedProp' } }).forEach((path) => {
+    if (!hasMigrationTodo(path.parent)) {
+      addTodoToAttribute(j, path, {
+        message: "The 'deprecatedProp' has been removed in v9",
+        context:
+          'Please migrate to the new API. See: https://docs.coinbase.com/cds/migration-guide',
+      });
+
+      logger?.todo(
+        'Manual migration required for deprecatedProp',
+        file.path,
+        path.value.loc?.start.line,
+        'This prop has breaking changes that need manual review',
+      );
+
+      hasChanges = true;
+    }
+  });
+
+  // Example 3: Update import statements
+  root
+    .find(j.ImportDeclaration)
+    .filter((path) => path.value.source.value === '@coinbase/cds-web')
+    .forEach((path) => {
+      path.value.specifiers?.forEach((specifier) => {
+        if (j.ImportSpecifier.check(specifier) && specifier.imported.name === 'OldButton') {
+          specifier.imported.name = 'Button';
+          if (specifier.local) {
+            specifier.local.name = 'Button';
+          }
+          hasChanges = true;
+
+          logger?.success(
+            'Updated import: OldButton → Button',
+            file.path,
+            path.value.loc?.start.line,
+          );
+        }
+      });
+    });
+
+  // Return null if no changes to skip writing the file
+  if (!hasChanges) {
+    return null;
+  }
+
+  return root.toSource();
+}
diff --git a/packages/migrator/tsconfig.build.json b/packages/migrator/tsconfig.build.json
new file mode 100644
index 000000000..a227a333b
--- /dev/null
+++ b/packages/migrator/tsconfig.build.json
@@ -0,0 +1,19 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "sourceMap": false
+  },
+  "include": [
+    "src/**/*"
+  ],
+  "exclude": [
+    "**/__stories__/**",
+    "**/__tests__/**",
+    "**/__mocks__/**",
+    "**/__fixtures__/**",
+    "**/*.stories.*",
+    "**/*.test.*",
+    "**/*.spec.*"
+  ],
+  "references": []
+}
diff --git a/packages/migrator/tsconfig.json b/packages/migrator/tsconfig.json
new file mode 100644
index 000000000..25b1d4a17
--- /dev/null
+++ b/packages/migrator/tsconfig.json
@@ -0,0 +1,12 @@
+{
+  "extends": "../../tsconfig.project.json",
+  "compilerOptions": {
+    "declarationDir": "dts",
+    "rootDir": "src"
+  },
+  "include": [
+    "src/**/*"
+  ],
+  "exclude": [],
+  "references": []
+}
diff --git a/yarn.lock b/yarn.lock
index 571fc098f..ef657514e 100644
--- a/yarn.lock
+++ b/yarn.lock
@@ -281,7 +281,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"@babel/core@npm:^7.11.6, @babel/core@npm:^7.12.3, @babel/core@npm:^7.15.5, @babel/core@npm:^7.18.2, @babel/core@npm:^7.18.5, @babel/core@npm:^7.20.0, @babel/core@npm:^7.21.3, @babel/core@npm:^7.23.2, @babel/core@npm:^7.24.4, @babel/core@npm:^7.25.2, @babel/core@npm:^7.25.9, @babel/core@npm:^7.28.0, @babel/core@npm:^7.29.0":
+"@babel/core@npm:^7.11.6, @babel/core@npm:^7.12.3, @babel/core@npm:^7.15.5, @babel/core@npm:^7.18.2, @babel/core@npm:^7.18.5, @babel/core@npm:^7.20.0, @babel/core@npm:^7.21.3, @babel/core@npm:^7.23.0, @babel/core@npm:^7.23.2, @babel/core@npm:^7.24.4, @babel/core@npm:^7.25.2, @babel/core@npm:^7.25.9, @babel/core@npm:^7.28.0, @babel/core@npm:^7.29.0":
   version: 7.29.0
   resolution: "@babel/core@npm:7.29.0"
   dependencies:
@@ -1165,7 +1165,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"@babel/plugin-transform-flow-strip-types@npm:^7.25.2":
+"@babel/plugin-transform-flow-strip-types@npm:^7.25.2, @babel/plugin-transform-flow-strip-types@npm:^7.27.1":
   version: 7.27.1
   resolution: "@babel/plugin-transform-flow-strip-types@npm:7.27.1"
   dependencies:
@@ -1258,7 +1258,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"@babel/plugin-transform-modules-commonjs@npm:^7.12.13, @babel/plugin-transform-modules-commonjs@npm:^7.18.2, @babel/plugin-transform-modules-commonjs@npm:^7.24.8, @babel/plugin-transform-modules-commonjs@npm:^7.27.1":
+"@babel/plugin-transform-modules-commonjs@npm:^7.12.13, @babel/plugin-transform-modules-commonjs@npm:^7.18.2, @babel/plugin-transform-modules-commonjs@npm:^7.23.0, @babel/plugin-transform-modules-commonjs@npm:^7.24.8, @babel/plugin-transform-modules-commonjs@npm:^7.27.1":
   version: 7.28.6
   resolution: "@babel/plugin-transform-modules-commonjs@npm:7.28.6"
   dependencies:
@@ -1319,7 +1319,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"@babel/plugin-transform-nullish-coalescing-operator@npm:^7.0.0-0, @babel/plugin-transform-nullish-coalescing-operator@npm:^7.24.7, @babel/plugin-transform-nullish-coalescing-operator@npm:^7.27.1":
+"@babel/plugin-transform-nullish-coalescing-operator@npm:^7.0.0-0, @babel/plugin-transform-nullish-coalescing-operator@npm:^7.22.11, @babel/plugin-transform-nullish-coalescing-operator@npm:^7.24.7, @babel/plugin-transform-nullish-coalescing-operator@npm:^7.27.1":
   version: 7.28.6
   resolution: "@babel/plugin-transform-nullish-coalescing-operator@npm:7.28.6"
   dependencies:
@@ -1379,7 +1379,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"@babel/plugin-transform-optional-chaining@npm:^7.0.0-0, @babel/plugin-transform-optional-chaining@npm:^7.24.8, @babel/plugin-transform-optional-chaining@npm:^7.27.1":
+"@babel/plugin-transform-optional-chaining@npm:^7.0.0-0, @babel/plugin-transform-optional-chaining@npm:^7.23.0, @babel/plugin-transform-optional-chaining@npm:^7.24.8, @babel/plugin-transform-optional-chaining@npm:^7.27.1":
   version: 7.28.6
   resolution: "@babel/plugin-transform-optional-chaining@npm:7.28.6"
   dependencies:
@@ -1402,7 +1402,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"@babel/plugin-transform-private-methods@npm:^7.24.7, @babel/plugin-transform-private-methods@npm:^7.27.1":
+"@babel/plugin-transform-private-methods@npm:^7.22.5, @babel/plugin-transform-private-methods@npm:^7.24.7, @babel/plugin-transform-private-methods@npm:^7.27.1":
   version: 7.28.6
   resolution: "@babel/plugin-transform-private-methods@npm:7.28.6"
   dependencies:
@@ -1768,6 +1768,19 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@babel/preset-flow@npm:^7.22.15":
+  version: 7.27.1
+  resolution: "@babel/preset-flow@npm:7.27.1"
+  dependencies:
+    "@babel/helper-plugin-utils": "npm:^7.27.1"
+    "@babel/helper-validator-option": "npm:^7.27.1"
+    "@babel/plugin-transform-flow-strip-types": "npm:^7.27.1"
+  peerDependencies:
+    "@babel/core": ^7.0.0-0
+  checksum: 10c0/252216c91ba3cc126f10c81c1df495ef2c622687d17373bc619354a7fb7280ea83f434ed1e7149dbddd712790d16ab60f5b864d007edd153931d780f834e52c1
+  languageName: node
+  linkType: hard
+
 "@babel/preset-modules@npm:0.1.6-no-external-plugins":
   version: 0.1.6-no-external-plugins
   resolution: "@babel/preset-modules@npm:0.1.6-no-external-plugins"
@@ -1827,6 +1840,21 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@babel/register@npm:^7.22.15":
+  version: 7.28.6
+  resolution: "@babel/register@npm:7.28.6"
+  dependencies:
+    clone-deep: "npm:^4.0.1"
+    find-cache-dir: "npm:^2.0.0"
+    make-dir: "npm:^2.1.0"
+    pirates: "npm:^4.0.6"
+    source-map-support: "npm:^0.5.16"
+  peerDependencies:
+    "@babel/core": ^7.0.0-0
+  checksum: 10c0/372380504970cf7654c2d65e09c34ed0b3217da64cb0edb6376a89eba7b603c8bdaba666eead7dcd6ed21badd52d396c2c0d6f914ae4dc6c9009e3d03d260e98
+  languageName: node
+  linkType: hard
+
 "@babel/runtime-corejs3@npm:^7.10.2, @babel/runtime-corejs3@npm:^7.25.9":
   version: 7.26.0
   resolution: "@babel/runtime-corejs3@npm:7.26.0"
@@ -2188,6 +2216,25 @@ __metadata:
   languageName: unknown
   linkType: soft
 
+"@coinbase/cds-migrator@workspace:packages/migrator":
+  version: 0.0.0-use.local
+  resolution: "@coinbase/cds-migrator@workspace:packages/migrator"
+  dependencies:
+    "@babel/core": "npm:^7.28.0"
+    "@babel/preset-env": "npm:^7.28.0"
+    "@babel/preset-react": "npm:^7.28.5"
+    "@babel/preset-typescript": "npm:^7.27.1"
+    "@types/inquirer": "npm:^9.0.7"
+    "@types/jscodeshift": "npm:^0.11.10"
+    "@types/node": "npm:^20.0.0"
+    commander: "npm:^11.1.0"
+    inquirer: "npm:^9.2.12"
+    jscodeshift: "npm:^0.15.1"
+  bin:
+    cds-migrate: ./esm/cli.js
+  languageName: unknown
+  linkType: soft
+
 "@coinbase/cds-mobile-visualization@workspace:^, @coinbase/cds-mobile-visualization@workspace:packages/mobile-visualization":
   version: 0.0.0-use.local
   resolution: "@coinbase/cds-mobile-visualization@workspace:packages/mobile-visualization"
@@ -5446,18 +5493,18 @@ __metadata:
   languageName: node
   linkType: hard
 
-"@inquirer/external-editor@npm:^1.0.1":
-  version: 1.0.1
-  resolution: "@inquirer/external-editor@npm:1.0.1"
+"@inquirer/external-editor@npm:^1.0.1, @inquirer/external-editor@npm:^1.0.2":
+  version: 1.0.3
+  resolution: "@inquirer/external-editor@npm:1.0.3"
   dependencies:
-    chardet: "npm:^2.1.0"
-    iconv-lite: "npm:^0.6.3"
+    chardet: "npm:^2.1.1"
+    iconv-lite: "npm:^0.7.0"
   peerDependencies:
     "@types/node": ">=18"
   peerDependenciesMeta:
     "@types/node":
       optional: true
-  checksum: 10c0/bdac4395e0bba7065d39b141d618bfc06369f246c402c511396a5238baf2657f3038ccba8438521a49e5cb602f4302b9d1f46b52b647b27af2c9911720022118
+  checksum: 10c0/82951cb7f3762dd78cca2ea291396841e3f4adfe26004b5badfed1cec4b6a04bb567dff94d0e41b35c61bdd7957317c64c22f58074d14b238d44e44d9e420019
   languageName: node
   linkType: hard
 
@@ -5468,6 +5515,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@inquirer/figures@npm:^1.0.3":
+  version: 1.0.15
+  resolution: "@inquirer/figures@npm:1.0.15"
+  checksum: 10c0/6e39a040d260ae234ae220180b7994ff852673e20be925f8aa95e78c7934d732b018cbb4d0ec39e600a410461bcb93dca771e7de23caa10630d255692e440f69
+  languageName: node
+  linkType: hard
+
 "@inquirer/input@npm:^4.2.2":
   version: 4.2.2
   resolution: "@inquirer/input@npm:4.2.2"
@@ -9680,6 +9734,16 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@types/inquirer@npm:^9.0.7":
+  version: 9.0.9
+  resolution: "@types/inquirer@npm:9.0.9"
+  dependencies:
+    "@types/through": "npm:*"
+    rxjs: "npm:^7.2.0"
+  checksum: 10c0/235a02a3afa5b238ca9093ef7064e17d763ba134b1afd5a263ffc363ccdb6d1f7d64aa3866ca93e7ad52be4ff21324368a983d20d35caf21c16475cfb32db8c8
+  languageName: node
+  linkType: hard
+
 "@types/intl@npm:^1.2.0":
   version: 1.2.0
   resolution: "@types/intl@npm:1.2.0"
@@ -9766,6 +9830,16 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@types/jscodeshift@npm:^0.11.10":
+  version: 0.11.11
+  resolution: "@types/jscodeshift@npm:0.11.11"
+  dependencies:
+    ast-types: "npm:^0.14.1"
+    recast: "npm:^0.20.3"
+  checksum: 10c0/b3d2be46d523ae679a2c986d7f98232aabaa761c960423105286bfd682fb57f9366f6afed1e1d6b35e4923b7e038c0aa539032d7e7fd430754683078032cd578
+  languageName: node
+  linkType: hard
+
 "@types/jsdom@npm:^20.0.0":
   version: 20.0.0
   resolution: "@types/jsdom@npm:20.0.0"
@@ -10162,6 +10236,15 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@types/through@npm:*":
+  version: 0.0.33
+  resolution: "@types/through@npm:0.0.33"
+  dependencies:
+    "@types/node": "npm:*"
+  checksum: 10c0/6a8edd7f40cd7e197318e86310a40e568cddd380609dde59b30d5cc6c5f8276ddc698905eac4b3b429eb39f2e8ee326bc20dc6e95a2cdc41c4d3fc9a1ebd4929
+  languageName: node
+  linkType: hard
+
 "@types/tough-cookie@npm:*":
   version: 4.0.2
   resolution: "@types/tough-cookie@npm:4.0.2"
@@ -11776,6 +11859,15 @@ __metadata:
   languageName: node
   linkType: hard
 
+"ast-types@npm:0.14.2, ast-types@npm:^0.14.1":
+  version: 0.14.2
+  resolution: "ast-types@npm:0.14.2"
+  dependencies:
+    tslib: "npm:^2.0.1"
+  checksum: 10c0/5d66d89b6c07fe092087454b6042dbaf81f2882b176db93861e2b986aafe0bce49e1f1ff59aac775d451c1426ad1e967d250e9e3548f5166ea8a3475e66c169d
+  languageName: node
+  linkType: hard
+
 "ast-types@npm:^0.13.4":
   version: 0.13.4
   resolution: "ast-types@npm:0.13.4"
@@ -11914,6 +12006,15 @@ __metadata:
   languageName: node
   linkType: hard
 
+"babel-core@npm:^7.0.0-bridge.0":
+  version: 7.0.0-bridge.0
+  resolution: "babel-core@npm:7.0.0-bridge.0"
+  peerDependencies:
+    "@babel/core": ^7.0.0-0
+  checksum: 10c0/f57576e30267be4607d163b7288031d332cf9200ea35efe9fb33c97f834e304376774c28c1f9d6928d6733fcde7041e4010f1248a0519e7730c590d4b07b9608
+  languageName: node
+  linkType: hard
+
 "babel-jest@npm:^29.7.0":
   version: 29.7.0
   resolution: "babel-jest@npm:29.7.0"
@@ -13061,10 +13162,10 @@ __metadata:
   languageName: node
   linkType: hard
 
-"chardet@npm:^2.1.0":
-  version: 2.1.0
-  resolution: "chardet@npm:2.1.0"
-  checksum: 10c0/d1b03e47371851ed72741a898281d58f8a9b577aeea6fdfa75a86832898b36c550b3ad057e66d50d774a9cebd9f56c66b6880e4fe75e387794538ba7565b0b6f
+"chardet@npm:^2.1.1":
+  version: 2.1.1
+  resolution: "chardet@npm:2.1.1"
+  checksum: 10c0/d8391dd412338442b3de0d3a488aa9327f8bcf74b62b8723d6bd0b85c4084d50b731320e0a7c710edb1d44de75969995d2784b80e4c13b004a6c7a0db4c6e793
   languageName: node
   linkType: hard
 
@@ -14367,9 +14468,9 @@ __metadata:
   linkType: hard
 
 "csstype@npm:^3.0.2, csstype@npm:^3.1.3":
-  version: 3.1.3
-  resolution: "csstype@npm:3.1.3"
-  checksum: 10c0/80c089d6f7e0c5b2bd83cf0539ab41474198579584fa10d86d0cafe0642202343cbc119e076a0b1aece191989477081415d66c9fefbf3c957fc2fc4b7009f248
+  version: 3.2.3
+  resolution: "csstype@npm:3.2.3"
+  checksum: 10c0/cd29c51e70fa822f1cecd8641a1445bed7063697469d35633b516e60fe8c1bde04b08f6c5b6022136bb669b64c63d4173af54864510fbb4ee23281801841a3ce
   languageName: node
   linkType: hard
 
@@ -17945,6 +18046,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"flow-parser@npm:0.*":
+  version: 0.300.0
+  resolution: "flow-parser@npm:0.300.0"
+  checksum: 10c0/c95b39dfbbfed8fc2e09363e895e7d01f453f08a891c057cf74826f33dc7a7ab731b99065216f9c2324df03de88a824f5c382881a8da93bbed1249a15d2bed83
+  languageName: node
+  linkType: hard
+
 "follow-redirects@npm:1.5.10":
   version: 1.5.10
   resolution: "follow-redirects@npm:1.5.10"
@@ -19581,6 +19689,15 @@ __metadata:
   languageName: node
   linkType: hard
 
+"iconv-lite@npm:^0.7.0":
+  version: 0.7.2
+  resolution: "iconv-lite@npm:0.7.2"
+  dependencies:
+    safer-buffer: "npm:>= 2.1.2 < 3.0.0"
+  checksum: 10c0/3c228920f3bd307f56bf8363706a776f4a060eb042f131cd23855ceca962951b264d0997ab38a1ad340e1c5df8499ed26e1f4f0db6b2a2ad9befaff22f14b722
+  languageName: node
+  linkType: hard
+
 "icss-utils@npm:^5.0.0, icss-utils@npm:^5.1.0":
   version: 5.1.0
   resolution: "icss-utils@npm:5.1.0"
@@ -19800,6 +19917,26 @@ __metadata:
   languageName: node
   linkType: hard
 
+"inquirer@npm:^9.2.12":
+  version: 9.3.8
+  resolution: "inquirer@npm:9.3.8"
+  dependencies:
+    "@inquirer/external-editor": "npm:^1.0.2"
+    "@inquirer/figures": "npm:^1.0.3"
+    ansi-escapes: "npm:^4.3.2"
+    cli-width: "npm:^4.1.0"
+    mute-stream: "npm:1.0.0"
+    ora: "npm:^5.4.1"
+    run-async: "npm:^3.0.0"
+    rxjs: "npm:^7.8.1"
+    string-width: "npm:^4.2.3"
+    strip-ansi: "npm:^6.0.1"
+    wrap-ansi: "npm:^6.2.0"
+    yoctocolors-cjs: "npm:^2.1.2"
+  checksum: 10c0/f9e64487413816460d2eb04520cd0898b8d488533bba93dfb432013383fe7bab5ddffd9ecfe5d5e2d96aaac86086bfa13c0a397a75083896693ab9d36177197b
+  languageName: node
+  linkType: hard
+
 "internal-slot@npm:^1.1.0":
   version: 1.1.0
   resolution: "internal-slot@npm:1.1.0"
@@ -21486,6 +21623,41 @@ __metadata:
   languageName: node
   linkType: hard
 
+"jscodeshift@npm:^0.15.1":
+  version: 0.15.2
+  resolution: "jscodeshift@npm:0.15.2"
+  dependencies:
+    "@babel/core": "npm:^7.23.0"
+    "@babel/parser": "npm:^7.23.0"
+    "@babel/plugin-transform-class-properties": "npm:^7.22.5"
+    "@babel/plugin-transform-modules-commonjs": "npm:^7.23.0"
+    "@babel/plugin-transform-nullish-coalescing-operator": "npm:^7.22.11"
+    "@babel/plugin-transform-optional-chaining": "npm:^7.23.0"
+    "@babel/plugin-transform-private-methods": "npm:^7.22.5"
+    "@babel/preset-flow": "npm:^7.22.15"
+    "@babel/preset-typescript": "npm:^7.23.0"
+    "@babel/register": "npm:^7.22.15"
+    babel-core: "npm:^7.0.0-bridge.0"
+    chalk: "npm:^4.1.2"
+    flow-parser: "npm:0.*"
+    graceful-fs: "npm:^4.2.4"
+    micromatch: "npm:^4.0.4"
+    neo-async: "npm:^2.5.0"
+    node-dir: "npm:^0.1.17"
+    recast: "npm:^0.23.3"
+    temp: "npm:^0.8.4"
+    write-file-atomic: "npm:^2.3.0"
+  peerDependencies:
+    "@babel/preset-env": ^7.1.6
+  peerDependenciesMeta:
+    "@babel/preset-env":
+      optional: true
+  bin:
+    jscodeshift: bin/jscodeshift.js
+  checksum: 10c0/79afb059b9ca92712af02bdc8d6ff144de7aaf5e2cdcc6f6534e7a86a7347b0a278d9f4884f2c78dac424162a353aafff183a60e868f71132be2c5b5304aeeb8
+  languageName: node
+  linkType: hard
+
 "jsdom@npm:^20.0.0":
   version: 20.0.0
   resolution: "jsdom@npm:20.0.0"
@@ -23820,7 +23992,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"minimatch@npm:2 || 3, minimatch@npm:3.1.2, minimatch@npm:^3.0.4, minimatch@npm:^3.1.1, minimatch@npm:^3.1.2":
+"minimatch@npm:2 || 3, minimatch@npm:3.1.2, minimatch@npm:^3.0.2, minimatch@npm:^3.0.4, minimatch@npm:^3.1.1, minimatch@npm:^3.1.2":
   version: 3.1.2
   resolution: "minimatch@npm:3.1.2"
   dependencies:
@@ -24175,6 +24347,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"mute-stream@npm:1.0.0":
+  version: 1.0.0
+  resolution: "mute-stream@npm:1.0.0"
+  checksum: 10c0/dce2a9ccda171ec979a3b4f869a102b1343dee35e920146776780de182f16eae459644d187e38d59a3d37adf85685e1c17c38cf7bfda7e39a9880f7a1d10a74c
+  languageName: node
+  linkType: hard
+
 "mute-stream@npm:^2.0.0":
   version: 2.0.0
   resolution: "mute-stream@npm:2.0.0"
@@ -24261,7 +24440,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"neo-async@npm:^2.6.2":
+"neo-async@npm:^2.5.0, neo-async@npm:^2.6.2":
   version: 2.6.2
   resolution: "neo-async@npm:2.6.2"
   checksum: 10c0/c2f5a604a54a8ec5438a342e1f356dff4bc33ccccdb6dc668d94fe8e5eccfc9d2c2eea6064b0967a767ba63b33763f51ccf2cd2441b461a7322656c1f06b3f5d
@@ -24308,6 +24487,15 @@ __metadata:
   languageName: node
   linkType: hard
 
+"node-dir@npm:^0.1.17":
+  version: 0.1.17
+  resolution: "node-dir@npm:0.1.17"
+  dependencies:
+    minimatch: "npm:^3.0.2"
+  checksum: 10c0/16222e871708c405079ff8122d4a7e1d522c5b90fc8f12b3112140af871cfc70128c376e845dcd0044c625db0d2efebd2d852414599d240564db61d53402b4c1
+  languageName: node
+  linkType: hard
+
 "node-emoji@npm:^2.1.0":
   version: 2.2.0
   resolution: "node-emoji@npm:2.2.0"
@@ -27792,7 +27980,19 @@ __metadata:
   languageName: node
   linkType: hard
 
-"recast@npm:^0.23.5":
+"recast@npm:^0.20.3":
+  version: 0.20.5
+  resolution: "recast@npm:0.20.5"
+  dependencies:
+    ast-types: "npm:0.14.2"
+    esprima: "npm:~4.0.0"
+    source-map: "npm:~0.6.1"
+    tslib: "npm:^2.0.1"
+  checksum: 10c0/7810216ff36c7376eddd66d3ce6b2df421305fdc983f2122711837911712177d52d804419655e1f29d4bb93016c178cffe442af410bdcf726050ca19af6fed32
+  languageName: node
+  linkType: hard
+
+"recast@npm:^0.23.3, recast@npm:^0.23.5":
   version: 0.23.11
   resolution: "recast@npm:0.23.11"
   dependencies:
@@ -28626,6 +28826,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"run-async@npm:^3.0.0":
+  version: 3.0.0
+  resolution: "run-async@npm:3.0.0"
+  checksum: 10c0/b18b562ae37c3020083dcaae29642e4cc360c824fbfb6b7d50d809a9d5227bb986152d09310255842c8dce40526e82ca768f02f00806c91ba92a8dfa6159cb85
+  languageName: node
+  linkType: hard
+
 "run-async@npm:^4.0.5":
   version: 4.0.6
   resolution: "run-async@npm:4.0.6"
@@ -28651,7 +28858,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"rxjs@npm:^7.8.2":
+"rxjs@npm:^7.2.0, rxjs@npm:^7.8.1, rxjs@npm:^7.8.2":
   version: 7.8.2
   resolution: "rxjs@npm:7.8.2"
   dependencies:
@@ -30664,6 +30871,15 @@ __metadata:
   languageName: node
   linkType: hard
 
+"temp@npm:^0.8.4":
+  version: 0.8.4
+  resolution: "temp@npm:0.8.4"
+  dependencies:
+    rimraf: "npm:~2.6.2"
+  checksum: 10c0/7f071c963031bfece37e13c5da11e9bb451e4ddfc4653e23e327a2f91594102dc826ef6a693648e09a6e0eb856f507967ec759ae55635e0878091eccf411db37
+  languageName: node
+  linkType: hard
+
 "temp@npm:^0.9.4":
   version: 0.9.4
   resolution: "temp@npm:0.9.4"
@@ -32835,6 +33051,17 @@ __metadata:
   languageName: node
   linkType: hard
 
+"write-file-atomic@npm:^2.3.0":
+  version: 2.4.3
+  resolution: "write-file-atomic@npm:2.4.3"
+  dependencies:
+    graceful-fs: "npm:^4.1.11"
+    imurmurhash: "npm:^0.1.4"
+    signal-exit: "npm:^3.0.2"
+  checksum: 10c0/8cb4bba0c1ab814a9b127844da0db4fb8c5e06ddbe6317b8b319377c73b283673036c8b9360120062898508b9428d81611cf7fa97584504a00bc179b2a580b92
+  languageName: node
+  linkType: hard
+
 "write-file-atomic@npm:^3.0.3":
   version: 3.0.3
   resolution: "write-file-atomic@npm:3.0.3"

From 26cb4a0529773e5d842876a919db1a5999dd661a Mon Sep 17 00:00:00 2001
From: Adrien Zheng <adrien.zheng@coinbase.com>
Date: Thu, 26 Feb 2026 15:53:27 -0500
Subject: [PATCH 2/5] updates: 1. use presets instead of major version
 transform 2. adjusted prompting pattern 3. added the package to vite-app to
 test

---
 apps/vite-app/package.json                    |   1 +
 packages/migrator/README.md                   |  14 +-
 packages/migrator/docs/CLI_REFERENCE.md       | 371 ++++++++++--------
 packages/migrator/docs/CONFIGURATION.md       |   2 +-
 packages/migrator/docs/HISTORY.md             |  10 +-
 packages/migrator/docs/QUICK_START.md         |   2 +-
 packages/migrator/package.json                |   4 +-
 packages/migrator/src/bin/clear-history.ts    |  55 +++
 packages/migrator/src/bin/migrate-all.ts      |  43 ++
 packages/migrator/src/cli-args.ts             |  21 +-
 packages/migrator/src/cli.ts                  | 237 ++++-------
 packages/migrator/src/index.ts                |   2 +-
 packages/migrator/src/runner.ts               |  25 +-
 packages/migrator/src/types.ts                |  32 +-
 packages/migrator/src/utils/config-loader.ts  |   3 +-
 packages/migrator/src/utils/index.ts          |   4 +-
 packages/migrator/src/utils/insert-todo.ts    |   5 +-
 packages/migrator/src/utils/logger.ts         |   5 +-
 .../migrator/src/utils/migration-history.ts   |  31 +-
 packages/migrator/src/v8-to-v9/config.json    |  10 +-
 packages/migrator/src/v8-to-v9/index.ts       |   4 +-
 .../v8-to-v9/transforms/example-transform.ts  |   2 +
 yarn.lock                                     |   5 +-
 23 files changed, 482 insertions(+), 406 deletions(-)
 create mode 100644 packages/migrator/src/bin/clear-history.ts
 create mode 100644 packages/migrator/src/bin/migrate-all.ts

diff --git a/apps/vite-app/package.json b/apps/vite-app/package.json
index 53b8ecbb5..cc9c5f37c 100644
--- a/apps/vite-app/package.json
+++ b/apps/vite-app/package.json
@@ -19,6 +19,7 @@
     "react-dom": "19.1.2"
   },
   "devDependencies": {
+    "@coinbase/cds-migrator": "workspace:^",
     "@types/react": "19.1.2",
     "@types/react-dom": "19.1.2",
     "@vitejs/plugin-react": "^5.1.2",
diff --git a/packages/migrator/README.md b/packages/migrator/README.md
index bf24ea244..555778783 100644
--- a/packages/migrator/README.md
+++ b/packages/migrator/README.md
@@ -9,7 +9,7 @@ Code migration tools for the Coinbase Design System.
 npx @coinbase/cds-migrator
 
 # Non-interactive mode
-npx @coinbase/cds-migrator -m v8-to-v9 -p ./src --all --dry-run
+npx @coinbase/cds-migrator -p v8-to-v9 --path ./src --all --dry-run
 ```
 
 **→ See [Quick Start Guide](./docs/QUICK_START.md) for complete walkthrough.**
@@ -23,11 +23,13 @@ npx @coinbase/cds-migrator -m v8-to-v9 -p ./src --all --dry-run
 - 💬 **TODO Comments** - Automatically marks code that needs manual review
 - 🌳 **Configuration-Based** - Three-level structure (categories → variables → transforms)
 
-## Supported Migrations
+## Available Presets
 
-| Version     | Description                                          | Status       |
-| ----------- | ---------------------------------------------------- | ------------ |
-| **v8 → v9** | Component API updates, hook changes, utility updates | ✅ Available |
+| Preset       | Description                                          | Status       |
+| ------------ | ---------------------------------------------------- | ------------ |
+| **v8-to-v9** | Component API updates, hook changes, utility updates | ✅ Available |
+
+**Note:** Presets aren't just for version migrations - you can create presets for any collection of code transforms (deprecations, refactors, style updates, etc.).
 
 ## Documentation
 
@@ -79,7 +81,7 @@ Read these if you're adding new migrations or transforms:
 ```
 🚀 CDS Migrator
 
-? Which major version migration do you need?
+? Which migration preset do you need?
   ❯ v8 to v9 - Migrate from CDS v8 to v9
 
 ? Enter the path to your codebase: ./src
diff --git a/packages/migrator/docs/CLI_REFERENCE.md b/packages/migrator/docs/CLI_REFERENCE.md
index 9bd94b58c..11e083897 100644
--- a/packages/migrator/docs/CLI_REFERENCE.md
+++ b/packages/migrator/docs/CLI_REFERENCE.md
@@ -1,161 +1,167 @@
 # CLI Reference
 
-Complete guide for using the CDS Migrator in both interactive and non-interactive modes.
+Complete reference for using the CDS Migrator in both interactive and non-interactive modes.
+
+## Installation
+
+```bash
+# Install as dev dependency (recommended)
+yarn add -D @coinbase/cds-migrator
+
+# Or use npx without installing
+npx @coinbase/cds-migrator
+```
 
 ## Quick Reference
 
 ### Interactive Mode
 
 ```bash
+# Using npx (no installation needed)
 npx @coinbase/cds-migrator
-# Follow prompts to select what to migrate
+
+# Or if installed locally
+yarn cds-migrate
 ```
 
-### Non-Interactive Mode (CLI Flags)
+### Convenience Commands (after installation)
+
+Quick commands for common operations:
+
+```bash
+# Migrate everything (shortcut)
+yarn cds-migrate:all -p v8-to-v9 --path ./src --dry-run
+
+# Clear history (shortcut)
+yarn cds-migrate:clear-history --path ./src
+```
+
+### Full CLI Flags
 
 ```bash
 # Migrate everything
-npx @coinbase/cds-migrator -m v8-to-v9 -p ./src --all
+npx @coinbase/cds-migrator -p v8-to-v9 --path ./src --all
+
+# Dry-run (preview changes)
+npx @coinbase/cds-migrator -p v8-to-v9 --path ./src --all --dry-run
 
 # Migrate specific category
-npx @coinbase/cds-migrator -m v8-to-v9 -p ./src --category components
+npx @coinbase/cds-migrator -p v8-to-v9 --path ./src --category components
 
 # Migrate specific items
-npx @coinbase/cds-migrator -m v8-to-v9 -p ./src --item components.Button
+npx @coinbase/cds-migrator -p v8-to-v9 --path ./src --item components.Button
+
+# Migrate specific transform
+npx @coinbase/cds-migrator -p v8-to-v9 --path ./src --transform components.Button.button-variant-to-appearance
 
 # Clear history
-npx @coinbase/cds-migrator --clear-history -p ./src
+npx @coinbase/cds-migrator --clear-history --path ./src
 ```
 
----
-
-## Part 1: Interactive Mode
-
-### Selection Hierarchy
+### Optional: Add Scripts to package.json
 
-The migrator offers four levels of selection granularity:
+For convenience, add these to your project's package.json:
 
-```
-1. Everything          → Migrate all categories, items, and transforms
-   ↓
-2. By Category        → Select one or more categories (or all)
-   ↓
-3. By Item            → Select specific components/hooks/utilities (or all)
-   ↓
-4. By Transform       → Select individual transforms (or all)
+```json
+{
+  "scripts": {
+    "migrate": "cds-migrate",
+    "migrate:dry": "cds-migrate -p v8-to-v9 --path ./src --all --dry-run",
+    "migrate:apply": "cds-migrate -p v8-to-v9 --path ./src --all"
+  }
+}
 ```
 
-### Selection Flow
+Then run:
 
-```
-? Which version migration? → v8 to v9
-? Enter path → ./src
-[Shows history if exists]
-? What would you like to migrate?
-  ❯ Everything (all changes)
-    By category (components, hooks, etc.)
-    By item (specific component/hook/utility)
-    By specific transform
+```bash
+yarn migrate        # Interactive
+yarn migrate:dry    # Preview changes
+yarn migrate:apply  # Apply changes
 ```
 
-### 1. Everything
+---
 
-Fastest path - migrate all changes at once.
+## Part 1: Interactive Mode
 
-**When to use:**
+### Selection Flow
 
-- First-time migration
-- Small codebase
-- Want everything done quickly
+The migrator uses a **hierarchical selection** where you choose categories first, then transforms within each category:
 
 ```
-? What would you like to migrate?
-  ❯ Everything (all changes)
+Step 1: Which preset?
+   → v8-to-v9
 
-✓ Runs all transforms immediately
-```
+Step 2: Enter path
+   → ./src
 
-### 2. By Category
+Step 3: [Shows history if exists]
 
-Select categories of changes with "All" option.
+Step 4: Which categories?
+   ├─ 🔘 All categories → DONE (runs everything)
+   └─ Select specific → Continue to Step 5
 
-**When to use:**
+Step 5: For EACH selected category, which transforms?
+   ├─ 🔘 All transforms in [category] → Runs all in that category
+   └─ Select specific → Runs only those selected
 
-- Focus on one type (components, hooks, utilities)
-- Phased migration strategy
+Step 6: Dry-run mode?
 
+Step 7: Execute
 ```
-? Select categories to migrate:
-  ◯ 🔘 All categories          ← Migrates everything
-  ◯ components - Component API changes
-  ◯ hooks - Hook API changes
-  ◯ utilities - Utility function changes
-```
-
-### 3. By Item
 
-Select specific components/hooks/utilities with "All" option.
+### Example Flows
 
-**When to use:**
-
-- Test one component at a time
-- Different PRs for different components
+**Flow 1: Migrate Everything**
 
 ```
-? Select items to migrate:
-  ◯ 🔘 All items               ← Migrates everything
-  ◯ components.Button - Button changes (@coinbase/cds-web)
-  ◯ components.Input - Input changes (@coinbase/cds-web)
-  ◯ hooks.useTheme - useTheme changes (@coinbase/cds-common)
+? Which categories? → 🔘 All categories
+✓ Done! Runs all 4 transforms
 ```
 
-### 4. By Transform
-
-Select individual transforms with "All" option.
-
-**When to use:**
-
-- Maximum control
-- Debugging issues
-- Review each change carefully
+**Flow 2: All Components**
 
 ```
-? Select transforms to run:
-  ◯ 🔘 All transforms          ← Migrates everything
-  ◯ components.Button.button-variant-to-appearance - Rename 'variant' prop
-  ◯ components.Input.input-size-values - Update size values
-  ◯ hooks.useTheme.use-theme-return-type - Update return type
+? Which categories? → components
+? Transforms in components? → 🔘 All transforms in components
+✓ Runs all component transforms (Button + Input)
 ```
 
-### Multiple Paths to "Migrate Everything"
+**Flow 3: Just One Transform**
 
-All of these produce the same result:
+```
+? Which categories? → components
+? Transforms in components? → Button.button-variant-to-appearance
+✓ Runs only that one transform
+```
 
-| Path                             | When to Use                      |
-| -------------------------------- | -------------------------------- |
-| Everything (all changes)         | Fastest - just go!               |
-| By category → 🔘 All categories  | Want to see categories first     |
-| By item → 🔘 All items           | Want to see all items first      |
-| By transform → 🔘 All transforms | Want to review each change first |
+**Flow 4: Multiple Categories, All Transforms**
 
-**Choose based on how much you want to explore before committing!**
+```
+? Which categories? → components, hooks
+? Transforms in components? → 🔘 All transforms in components
+? Transforms in hooks? → 🔘 All transforms in hooks
+✓ Runs all transforms in both categories (3 transforms)
+```
 
-### Decision Tree
+**Flow 5: Cherry-Pick from Multiple Categories**
 
 ```
-Do you want to migrate everything?
-│
-├─ YES, fast → "Everything (all changes)"
-├─ YES, see categories first → "By category" → "🔘 All categories"
-├─ YES, see items first → "By item" → "🔘 All items"
-├─ YES, review changes first → "By transform" → "🔘 All transforms"
-│
-└─ NO, be selective
-   ├─ By category → Select specific ones
-   ├─ By item → Select specific ones
-   └─ By transform → Select specific ones
+? Which categories? → components, hooks
+? Transforms in components? → Button.button-variant-to-appearance
+? Transforms in hooks? → useTheme.use-theme-return-type
+✓ Runs 2 specific transforms
 ```
 
+### What Gets Run
+
+| Selection                                     | Result                             |
+| --------------------------------------------- | ---------------------------------- |
+| 🔘 All categories                             | All transforms from all categories |
+| categories: [components] + 🔘 All transforms  | All transforms in components       |
+| categories: [components] + specific           | Only selected component transforms |
+| categories: [components, hooks] + all in each | All transforms in both categories  |
+
 ---
 
 ## Part 2: Non-Interactive Mode (CLI Flags)
@@ -166,58 +172,77 @@ Use CLI flags to run without prompts - perfect for CI/CD and automation.
 
 For non-interactive mode, you must provide:
 
-- `-m, --migration <version>` - Migration version (e.g., v8-to-v9)
-- `-p, --path <path>` - Target path (default: ./src)
+- `-p, --preset <name>` - Migration preset (e.g., v8-to-v9)
+- `--path <path>` - Target path (default: ./src)
 - One selection: `--all`, `--category`, `--item`, or `--transform`
 
 ### Selection Flags
 
+Each selection level runs progressively more transforms:
+
+| Flag          | What It Runs            | Example                                      |
+| ------------- | ----------------------- | -------------------------------------------- |
+| `--all`       | Everything              | All categories → all items → all transforms  |
+| `--category`  | All items in category   | All transforms for selected category's items |
+| `--item`      | All transforms for item | All transforms for the selected item         |
+| `--transform` | Specific transform only | Just that one transform                      |
+
 #### `--all`
 
-Migrate everything.
+Migrate everything (all categories, items, and transforms).
 
 ```bash
-npx @coinbase/cds-migrator -m v8-to-v9 -p ./src --all
+npx @coinbase/cds-migrator -p v8-to-v9 --path ./src --all
 ```
 
 #### `--category <categories...>`
 
 Migrate specific categories (can specify multiple).
 
+**This runs ALL items and transforms in the selected categories.**
+
 ```bash
-# Single category
-npx @coinbase/cds-migrator -m v8-to-v9 -p ./src --category components
+# Single category (runs all items and transforms in components)
+npx @coinbase/cds-migrator -p v8-to-v9 --path ./src --category components
 
 # Multiple categories
-npx @coinbase/cds-migrator -m v8-to-v9 -p ./src --category components hooks
+npx @coinbase/cds-migrator -p v8-to-v9 --path ./src --category components hooks
 ```
 
+**Example:** `--category components` will run all transforms for Button, Input, and any other components.
+
 #### `--item <items...>`
 
-Migrate specific items (format: `category.item`).
+Migrate specific items using dot notation: `category.item`
+
+**This runs ALL transforms for the selected items.**
 
 ```bash
-# Single item
-npx @coinbase/cds-migrator -m v8-to-v9 -p ./src --item components.Button
+# Single item (runs all transforms for Button)
+npx @coinbase/cds-migrator -p v8-to-v9 --path ./src --item components.Button
 
 # Multiple items
-npx @coinbase/cds-migrator -m v8-to-v9 -p ./src --item components.Button components.Input hooks.useTheme
+npx @coinbase/cds-migrator -p v8-to-v9 --path ./src --item components.Button components.Input hooks.useTheme
 ```
 
+**Why dot notation?** Items can have the same name in different categories, so `category.item` ensures we select the right one.
+
 #### `--transform <transforms...>`
 
-Migrate specific transforms (format: `category.item.transform-name`).
+Migrate specific transforms using full dot notation: `category.item.transform-name`
 
 ```bash
-# Single transform
-npx @coinbase/cds-migrator -m v8-to-v9 -p ./src --transform components.Button.button-variant-to-appearance
+# Single transform (most granular control)
+npx @coinbase/cds-migrator -p v8-to-v9 --path ./src --transform components.Button.button-variant-to-appearance
 
 # Multiple transforms
-npx @coinbase/cds-migrator -m v8-to-v9 -p ./src \
+npx @coinbase/cds-migrator -p v8-to-v9 --path ./src \
   --transform components.Button.button-variant-to-appearance \
   --transform components.Input.input-size-values
 ```
 
+**Why full path?** Transform names might be reused across items, so `category.item.transform` is the unique identifier.
+
 ### Mode Flags
 
 #### `-d, --dry-run`
@@ -226,10 +251,10 @@ Preview changes without modifying files.
 
 ```bash
 # Dry-run (safe to test)
-npx @coinbase/cds-migrator -m v8-to-v9 -p ./src --all --dry-run
+npx @coinbase/cds-migrator -p v8-to-v9 --path ./src --all --dry-run
 
 # Apply changes (no flag)
-npx @coinbase/cds-migrator -m v8-to-v9 -p ./src --all
+npx @coinbase/cds-migrator -p v8-to-v9 --path ./src --all
 ```
 
 #### `--skip-confirmation`
@@ -238,7 +263,7 @@ Skip confirmation prompts (useful for automation).
 
 ```bash
 # For CI/CD
-npx @coinbase/cds-migrator -m v8-to-v9 -p ./src --all --skip-confirmation
+npx @coinbase/cds-migrator -p v8-to-v9 --path ./src --all --skip-confirmation
 ```
 
 **⚠️ Use with caution** - bypasses all safety prompts!
@@ -251,13 +276,13 @@ Clear migration history for a path.
 
 ```bash
 # With confirmation
-npx @coinbase/cds-migrator --clear-history -p ./src
+npx @coinbase/cds-migrator --clear-history --path ./src
 
 # Skip confirmation
-npx @coinbase/cds-migrator --clear-history -p ./src --skip-confirmation
+npx @coinbase/cds-migrator --clear-history --path ./src --skip-confirmation
 ```
 
-**Note:** Only requires `--path`, no migration version needed.
+**Note:** Only requires `--path`, no preset needed.
 
 #### `-h, --help`
 
@@ -277,19 +302,19 @@ npx @coinbase/cds-migrator --version
 
 ### Flags Summary Table
 
-| Flag                  | Short | Description         | Example                                        |
-| --------------------- | ----- | ------------------- | ---------------------------------------------- |
-| `--migration`         | `-m`  | Migration version   | `-m v8-to-v9`                                  |
-| `--path`              | `-p`  | Target path         | `-p ./src`                                     |
-| `--dry-run`           | `-d`  | Preview mode        | `-d`                                           |
-| `--skip-confirmation` |       | Skip prompts        | `--skip-confirmation`                          |
-| `--clear-history`     |       | Clear history       | `--clear-history`                              |
-| `--all`               |       | Migrate everything  | `--all`                                        |
-| `--category`          |       | Specific categories | `--category components`                        |
-| `--item`              |       | Specific items      | `--item components.Button`                     |
-| `--transform`         |       | Specific transforms | `--transform components.Button.button-variant` |
-| `--help`              | `-h`  | Show help           | `-h`                                           |
-| `--version`           | `-V`  | Show version        | `-V`                                           |
+| Flag                  | Short | Description         | Example                                 |
+| --------------------- | ----- | ------------------- | --------------------------------------- |
+| `--preset`            | `-p`  | Migration preset    | `-p v8-to-v9`                           |
+| `--path`              |       | Target path         | `--path ./src`                          |
+| `--dry-run`           | `-d`  | Preview mode        | `-d`                                    |
+| `--skip-confirmation` |       | Skip prompts        | `--skip-confirmation`                   |
+| `--clear-history`     |       | Clear history       | `--clear-history`                       |
+| `--all`               |       | Migrate everything  | `--all`                                 |
+| `--category`          |       | Specific categories | `--category components`                 |
+| `--item`              |       | Specific items      | `--item components.Button`              |
+| `--transform`         |       | Specific transforms | `--transform components.Button.variant` |
+| `--help`              | `-h`  | Show help           | `-h`                                    |
+| `--version`           | `-V`  | Show version        | `-V`                                    |
 
 ---
 
@@ -302,7 +327,7 @@ npx @coinbase/cds-migrator --version
 npx @coinbase/cds-migrator
 
 # Quick dry-run
-npx @coinbase/cds-migrator -m v8-to-v9 -p ./src --all --dry-run
+npx @coinbase/cds-migrator -p v8-to-v9 --path ./src --all --dry-run
 ```
 
 ### CI/CD Pipeline
@@ -312,11 +337,11 @@ npx @coinbase/cds-migrator -m v8-to-v9 -p ./src --all --dry-run
 # migrate.sh
 
 # Preview first
-npx @coinbase/cds-migrator -m v8-to-v9 -p ./src --all --dry-run --skip-confirmation
+npx @coinbase/cds-migrator -p v8-to-v9 --path ./src --all --dry-run --skip-confirmation
 
 # Apply if preview succeeded
 if [ $? -eq 0 ]; then
-  npx @coinbase/cds-migrator -m v8-to-v9 -p ./src --all --skip-confirmation
+  npx @coinbase/cds-migrator -p v8-to-v9 --path ./src --all --skip-confirmation
 fi
 ```
 
@@ -340,7 +365,7 @@ jobs:
       - name: Run migration
         run: |
           npx @coinbase/cds-migrator \
-            --migration v8-to-v9 \
+            --preset v8-to-v9 \
             --path ./src \
             --all \
             --skip-confirmation
@@ -356,30 +381,41 @@ jobs:
 
 ```bash
 # Day 1: Components
-npx @coinbase/cds-migrator -m v8-to-v9 -p ./src --category components
+npx @coinbase/cds-migrator -p v8-to-v9 --path ./src --category components
 
 # Day 2: Hooks
-npx @coinbase/cds-migrator -m v8-to-v9 -p ./src --category hooks
+npx @coinbase/cds-migrator -p v8-to-v9 --path ./src --category hooks
 
 # Day 3: Everything else
-npx @coinbase/cds-migrator -m v8-to-v9 -p ./src --all
+npx @coinbase/cds-migrator -p v8-to-v9 --path ./src --all
 ```
 
 History tracking ensures no duplicates across runs.
 
 ### Package.json Scripts
 
+Add migration scripts to your project for convenience:
+
 ```json
 {
   "scripts": {
-    "migrate:dry": "cds-migrate -m v8-to-v9 -p ./src --all --dry-run",
-    "migrate:apply": "cds-migrate -m v8-to-v9 -p ./src --all --skip-confirmation",
-    "migrate:components": "cds-migrate -m v8-to-v9 -p ./src --category components",
-    "migrate:reset": "cds-migrate --clear-history -p ./src --skip-confirmation"
+    "migrate": "cds-migrate",
+    "migrate:dry": "cds-migrate -p v8-to-v9 --path ./src --all --dry-run",
+    "migrate:apply": "cds-migrate -p v8-to-v9 --path ./src --all --skip-confirmation",
+    "migrate:components": "cds-migrate -p v8-to-v9 --path ./src --category components"
   }
 }
 ```
 
+Then use them:
+
+```bash
+yarn migrate          # Interactive mode
+yarn migrate:dry      # Preview all changes
+yarn migrate:apply    # Apply all changes
+yarn migrate:components  # Migrate only components
+```
+
 ---
 
 ## Part 4: Interactive vs Non-Interactive
@@ -408,7 +444,7 @@ npx @coinbase/cds-migrator
 - Repeated operations
 
 ```bash
-npx @coinbase/cds-migrator -m v8-to-v9 -p ./src --all --skip-confirmation
+npx @coinbase/cds-migrator -p v8-to-v9 --path ./src --all --skip-confirmation
 ```
 
 ### Switching Between Modes
@@ -418,15 +454,15 @@ The tool automatically detects which mode based on provided flags:
 **Triggers Interactive:**
 
 ```bash
-npx @coinbase/cds-migrator                    # No flags
-npx @coinbase/cds-migrator -m v8-to-v9       # Missing selection
-npx @coinbase/cds-migrator -p ./src --all    # Missing version
+npx @coinbase/cds-migrator                         # No flags
+npx @coinbase/cds-migrator -p v8-to-v9            # Missing selection
+npx @coinbase/cds-migrator --path ./src --all     # Missing preset
 ```
 
 **Triggers Non-Interactive:**
 
 ```bash
-npx @coinbase/cds-migrator -m v8-to-v9 -p ./src --all  # All required flags
+npx @coinbase/cds-migrator -p v8-to-v9 --path ./src --all  # All required flags
 ```
 
 ---
@@ -437,23 +473,26 @@ npx @coinbase/cds-migrator -m v8-to-v9 -p ./src --all  # All required flags
 
 ```bash
 # Step 1: Preview everything
-npx @coinbase/cds-migrator -m v8-to-v9 -p ./src --all --dry-run
+npx @coinbase/cds-migrator -p v8-to-v9 --path ./src --all --dry-run
 
 # Step 2: Review migration.log
 cat migration.log
 
 # Step 3: Apply changes
-npx @coinbase/cds-migrator -m v8-to-v9 -p ./src --all
+npx @coinbase/cds-migrator -p v8-to-v9 --path ./src --all
 ```
 
 ### Selective Migration
 
 ```bash
-# Just Button component
-npx @coinbase/cds-migrator -m v8-to-v9 -p ./src --item components.Button
+# Just components category
+npx @coinbase/cds-migrator -p v8-to-v9 --path ./src --category components
+
+# Just Button item (all its transforms)
+npx @coinbase/cds-migrator -p v8-to-v9 --path ./src --item components.Button
 
-# Just one transform
-npx @coinbase/cds-migrator -m v8-to-v9 -p ./src \
+# Just one specific transform
+npx @coinbase/cds-migrator -p v8-to-v9 --path ./src \
   --transform components.Button.button-variant-to-appearance
 ```
 
@@ -461,11 +500,11 @@ npx @coinbase/cds-migrator -m v8-to-v9 -p ./src \
 
 ```bash
 # Test on sample directory
-npx @coinbase/cds-migrator -m v8-to-v9 -p ./test-samples --all
+npx @coinbase/cds-migrator -p v8-to-v9 --path ./test-samples --all
 
 # Clear and re-test
-npx @coinbase/cds-migrator --clear-history -p ./test-samples --skip-confirmation
-npx @coinbase/cds-migrator -m v8-to-v9 -p ./test-samples --all
+npx @coinbase/cds-migrator --clear-history --path ./test-samples --skip-confirmation
+npx @coinbase/cds-migrator -p v8-to-v9 --path ./test-samples --all
 ```
 
 ### Automated Daily Migration
@@ -480,8 +519,8 @@ LOG_DIR="./migration-logs"
 mkdir -p "$LOG_DIR"
 
 npx @coinbase/cds-migrator \
-  -m v8-to-v9 \
-  -p ./src \
+  -p v8-to-v9 \
+  --path ./src \
   --all \
   --skip-confirmation \
   && mv migration.log "$LOG_DIR/migration-$DATE.log"
@@ -497,10 +536,10 @@ You need to specify what to migrate:
 
 ```bash
 # ❌ Missing selection
-npx @coinbase/cds-migrator -m v8-to-v9 -p ./src
+npx @coinbase/cds-migrator -p v8-to-v9 --path ./src
 
 # ✅ With selection
-npx @coinbase/cds-migrator -m v8-to-v9 -p ./src --all
+npx @coinbase/cds-migrator -p v8-to-v9 --path ./src --all
 ```
 
 ### "Warning: Some transforms have already been run"
@@ -513,12 +552,12 @@ Options:
 
 ```bash
 # Skip duplicate warning
-npx @coinbase/cds-migrator -m v8-to-v9 -p ./src --all --skip-confirmation
+npx @coinbase/cds-migrator -p v8-to-v9 --path ./src --all --skip-confirmation
 ```
 
-### Invalid Migration Version
+### Invalid Preset
 
-Check available versions:
+Check available presets:
 
 ```bash
 npx @coinbase/cds-migrator --help
@@ -538,7 +577,7 @@ Currently available: `v8-to-v9`
 **Example:**
 
 ```bash
-npx @coinbase/cds-migrator -m v8-to-v9 -p ./src --all --skip-confirmation
+npx @coinbase/cds-migrator -p v8-to-v9 --path ./src --all --skip-confirmation
 if [ $? -eq 0 ]; then
   echo "✅ Migration succeeded"
 else
diff --git a/packages/migrator/docs/CONFIGURATION.md b/packages/migrator/docs/CONFIGURATION.md
index 615af4d13..eefdd8072 100644
--- a/packages/migrator/docs/CONFIGURATION.md
+++ b/packages/migrator/docs/CONFIGURATION.md
@@ -4,7 +4,7 @@ How to structure and configure migrations using the three-level hierarchy.
 
 ## Overview
 
-Each major version migration (e.g., v8-to-v9) has a `config.json` file that defines:
+Each major preset (e.g., v8-to-v9) has a `config.json` file that defines:
 
 1. **Categories** - High-level groupings (components, hooks, utilities)
 2. **Variables** - Specific exports (Button, useTheme, formatCurrency)
diff --git a/packages/migrator/docs/HISTORY.md b/packages/migrator/docs/HISTORY.md
index 3c4aa720e..4583cbd92 100644
--- a/packages/migrator/docs/HISTORY.md
+++ b/packages/migrator/docs/HISTORY.md
@@ -307,14 +307,14 @@ If a migration failed partway through:
 
 ```bash
 # Migration failed
-npx @coinbase/cds-migrator -m v8-to-v9 -p ./src --all
+npx @coinbase/cds-migrator -p v8-to-v9 -p ./src --all
 # Error occurred, some transforms completed but others didn't
 
 # Clear history to start fresh
 npx @coinbase/cds-migrator --clear-history -p ./src
 
 # Run migration again
-npx @coinbase/cds-migrator -m v8-to-v9 -p ./src --all
+npx @coinbase/cds-migrator -p v8-to-v9 -p ./src --all
 ```
 
 #### Testing Migrations
@@ -323,13 +323,13 @@ During development or testing:
 
 ```bash
 # Test a migration
-npx @coinbase/cds-migrator -m v8-to-v9 -p ./test-dir --all
+npx @coinbase/cds-migrator -p v8-to-v9 -p ./test-dir --all
 
 # Clear to test again
 npx @coinbase/cds-migrator --clear-history -p ./test-dir --skip-confirmation
 
 # Re-run with changes
-npx @coinbase/cds-migrator -m v8-to-v9 -p ./test-dir --all
+npx @coinbase/cds-migrator -p v8-to-v9 -p ./test-dir --all
 ```
 
 #### Corrupted History File
@@ -341,7 +341,7 @@ If the history file is corrupted or invalid:
 npx @coinbase/cds-migrator --clear-history -p ./src --skip-confirmation
 
 # Start fresh
-npx @coinbase/cds-migrator -m v8-to-v9 -p ./src --all
+npx @coinbase/cds-migrator -p v8-to-v9 -p ./src --all
 ```
 
 #### Reset After Rollback
diff --git a/packages/migrator/docs/QUICK_START.md b/packages/migrator/docs/QUICK_START.md
index 0f3a74728..65a1288d1 100644
--- a/packages/migrator/docs/QUICK_START.md
+++ b/packages/migrator/docs/QUICK_START.md
@@ -26,7 +26,7 @@ npx @coinbase/cds-migrator
 **Choose migration version:**
 
 ```
-? Which major version migration do you need?
+? Which migration preset do you need?
   ❯ v8 to v9 - Migrate from CDS v8 to v9
 ```
 
diff --git a/packages/migrator/package.json b/packages/migrator/package.json
index 47335c489..424b39848 100644
--- a/packages/migrator/package.json
+++ b/packages/migrator/package.json
@@ -11,7 +11,9 @@
   "main": "./esm/index.js",
   "types": "./dts/index.d.ts",
   "bin": {
-    "cds-migrate": "./esm/cli.js"
+    "cds-migrate": "./esm/cli.js",
+    "cds-migrate:all": "./esm/bin/migrate-all.js",
+    "cds-migrate:clear-history": "./esm/bin/clear-history.js"
   },
   "exports": {
     "./package.json": "./package.json",
diff --git a/packages/migrator/src/bin/clear-history.ts b/packages/migrator/src/bin/clear-history.ts
new file mode 100644
index 000000000..d73dffebd
--- /dev/null
+++ b/packages/migrator/src/bin/clear-history.ts
@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+
+/**
+ * cds-migrate:clear-history
+ * Quick command to clear migration history
+ */
+
+import { Command } from 'commander';
+import inquirer from 'inquirer';
+
+import { clearMigrationHistory, loadMigrationHistory } from '../utils/index.js';
+
+const program = new Command();
+
+program
+  .name('cds-migrate:clear-history')
+  .description('Clear CDS migration history')
+  .option('--path <path>', 'Target path', './src')
+  .option('--skip-confirmation', 'Skip confirmation prompt', false)
+  .parse();
+
+const options = program.opts();
+
+async function main() {
+  const history = loadMigrationHistory(options.path);
+
+  if (!history) {
+    console.log(`No migration history found at: ${options.path}`);
+    return;
+  }
+
+  if (!options.skipConfirmation) {
+    const { confirm } = await inquirer.prompt([
+      {
+        type: 'confirm',
+        name: 'confirm',
+        message: `⚠️  Clear migration history for ${options.path}?`,
+        default: false,
+      },
+    ]);
+
+    if (!confirm) {
+      console.log('❌ Cancelled.\n');
+      return;
+    }
+  }
+
+  clearMigrationHistory(options.path);
+  console.log(`✅ Migration history cleared for: ${options.path}\n`);
+}
+
+main().catch((error) => {
+  console.error('Error:', error);
+  process.exit(1);
+});
diff --git a/packages/migrator/src/bin/migrate-all.ts b/packages/migrator/src/bin/migrate-all.ts
new file mode 100644
index 000000000..9bb330589
--- /dev/null
+++ b/packages/migrator/src/bin/migrate-all.ts
@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+
+/**
+ * cds-migrate:all
+ * Quick command to migrate everything with a preset
+ */
+
+import { Command } from 'commander';
+
+import { runMigration } from '../runner.js';
+
+const program = new Command();
+
+program
+  .name('cds-migrate:all')
+  .description('Migrate everything with CDS migration preset')
+  .requiredOption('-p, --preset <name>', 'Migration preset (e.g., v8-to-v9)')
+  .option('--path <path>', 'Target path to migrate', './src')
+  .option('-d, --dry-run', 'Run in dry-run mode', false)
+  .parse();
+
+const options = program.opts();
+
+async function main() {
+  console.log('\n🚀 CDS Migrator - Migrate All\n');
+  console.log(`Preset: ${options.preset}`);
+  console.log(`Path: ${options.path}`);
+  console.log(`Mode: ${options.dryRun ? 'Dry Run' : 'Apply Changes'}\n`);
+
+  await runMigration({
+    preset: options.preset,
+    path: options.path,
+    dryRun: options.dryRun,
+    selection: { all: true },
+  });
+
+  console.log('\n✅ Migration completed!\n');
+}
+
+main().catch((error) => {
+  console.error('\n❌ Migration failed:', error);
+  process.exit(1);
+});
diff --git a/packages/migrator/src/cli-args.ts b/packages/migrator/src/cli-args.ts
index dbbb1deff..5ac3e3dc8 100644
--- a/packages/migrator/src/cli-args.ts
+++ b/packages/migrator/src/cli-args.ts
@@ -3,10 +3,11 @@
  */
 
 import { Command } from 'commander';
+
 import type { MigrationSelection } from './types.js';
 
-export interface CliArgs {
-  version?: string;
+export type CliArgs = {
+  preset?: string;
   path?: string;
   dryRun?: boolean;
   skipConfirmation?: boolean;
@@ -15,7 +16,7 @@ export interface CliArgs {
   category?: string[];
   item?: string[];
   transform?: string[];
-}
+};
 
 export function parseCliArgs(): CliArgs {
   const program = new Command();
@@ -24,8 +25,8 @@ export function parseCliArgs(): CliArgs {
     .name('cds-migrate')
     .description('CDS code migration tool')
     .version('1.0.0')
-    .option('-m, --migration <version>', 'Migration version (e.g., v8-to-v9)')
-    .option('-p, --path <path>', 'Target path to migrate', './src')
+    .option('-p, --preset <name>', 'Migration preset (e.g., v8-to-v9)')
+    .option('--path <path>', 'Target path to migrate', './src')
     .option('-d, --dry-run', 'Run in dry-run mode (preview changes)', false)
     .option('--skip-confirmation', 'Skip confirmation prompts', false)
     .option('--clear-history', 'Clear migration history for the specified path', false)
@@ -39,7 +40,7 @@ export function parseCliArgs(): CliArgs {
   const options = program.opts();
 
   return {
-    version: options.migration,
+    preset: options.preset,
     path: options.path,
     dryRun: options.dryRun,
     skipConfirmation: options.skipConfirmation,
@@ -72,11 +73,7 @@ export function buildSelectionFromArgs(args: CliArgs): MigrationSelection | null
 }
 
 export function hasRequiredArgs(args: CliArgs): boolean {
-  // Version and path are required for non-interactive mode
+  // Preset and path are required for non-interactive mode
   // Plus at least one selection method
-  return !!(
-    args.version &&
-    args.path &&
-    (args.all || args.category || args.item || args.transform)
-  );
+  return !!(args.preset && args.path && (args.all || args.category || args.item || args.transform));
 }
diff --git a/packages/migrator/src/cli.ts b/packages/migrator/src/cli.ts
index dd7d9a072..3c920c1c0 100644
--- a/packages/migrator/src/cli.ts
+++ b/packages/migrator/src/cli.ts
@@ -8,27 +8,28 @@
  */
 
 import inquirer from 'inquirer';
-import { runMigration } from './runner.js';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
 import {
-  loadMigrationConfig,
   buildMigrationSummary,
   getSelectedTransforms,
+  loadMigrationConfig,
 } from './utils/config-loader.js';
 import {
-  loadMigrationHistory,
-  getAlreadyRunTransforms,
   buildHistorySummary,
   clearMigrationHistory,
+  getAlreadyRunTransforms,
+  loadMigrationHistory,
 } from './utils/migration-history.js';
-import path from 'path';
-import { fileURLToPath } from 'url';
+import { buildSelectionFromArgs, type CliArgs, hasRequiredArgs, parseCliArgs } from './cli-args.js';
+import { runMigration } from './runner.js';
 import type { MigrationSelection } from './types.js';
-import { parseCliArgs, buildSelectionFromArgs, hasRequiredArgs, type CliArgs } from './cli-args.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 
-const SUPPORTED_MIGRATIONS = [
+const AVAILABLE_PRESETS = [
   {
     name: 'v8 to v9',
     value: 'v8-to-v9',
@@ -36,161 +37,84 @@ const SUPPORTED_MIGRATIONS = [
   },
 ] as const;
 
-async function selectMigrationScope(migrationDir: string): Promise<MigrationSelection> {
-  const config = loadMigrationConfig(migrationDir);
+async function selectMigrationScope(presetDir: string): Promise<MigrationSelection> {
+  const config = loadMigrationConfig(presetDir);
 
-  const { scope } = await inquirer.prompt([
+  // Step 1: Select category
+  const categoryChoices = [
+    {
+      name: '🔘 All categories',
+      value: '__ALL__',
+    },
+    ...Object.entries(config.categories).map(([name, cat]) => ({
+      name: `${name} - ${cat.description}`,
+      value: name,
+    })),
+  ];
+
+  const { selectedCategory } = await inquirer.prompt([
     {
       type: 'list',
-      name: 'scope',
-      message: 'What would you like to migrate?',
-      choices: [
-        { name: 'Everything (all changes)', value: 'all' },
-        { name: 'By category (components, hooks, etc.)', value: 'category' },
-        { name: 'By item (specific component/hook/utility)', value: 'item' },
-        { name: 'By specific transform', value: 'transform' },
-      ],
+      name: 'selectedCategory',
+      message: 'Which category of transforms do you want to run?',
+      choices: categoryChoices,
     },
   ]);
 
-  if (scope === 'all') {
+  // If "All categories" is selected, migrate everything
+  if (selectedCategory === '__ALL__') {
     return { all: true };
   }
 
-  if (scope === 'category') {
-    const categoryChoices = [
-      {
-        name: '🔘 All categories',
-        value: '__ALL__',
-        checked: false,
-      },
-      ...Object.entries(config.categories).map(([name, cat]) => ({
-        name: `${name} - ${cat.description}`,
-        value: name,
-        checked: false,
-      })),
-    ];
-
-    const { categories } = (await inquirer.prompt([
-      {
-        type: 'checkbox',
-        name: 'categories',
-        message: 'Select categories to migrate:',
-        choices: categoryChoices,
-        validate: (input: string[]) => {
-          if (input.length === 0) {
-            return 'Please select at least one category';
-          }
-          return true;
-        },
-      },
-    ] as any)) as { categories: string[] };
-
-    // If "All" is selected, return all categories
-    if (categories.includes('__ALL__')) {
-      return { all: true };
-    }
-
-    return { categories };
+  // Step 2: Select transform in the selected category
+  const category = config.categories[selectedCategory];
+  if (!category) {
+    return { all: true };
   }
 
-  if (scope === 'item') {
-    // Build list of all items across categories
-    const itemChoices: Array<{ name: string; value: string; checked?: boolean }> = [
-      {
-        name: '🔘 All items',
-        value: '__ALL__',
-        checked: false,
-      },
-    ];
-
-    for (const [categoryName, category] of Object.entries(config.categories)) {
-      for (const [itemName, item] of Object.entries(category.variables)) {
-        itemChoices.push({
-          name: `${categoryName}.${itemName} - ${item.description} (${item.package})`,
-          value: `${categoryName}.${itemName}`,
-        });
-      }
-    }
-
-    const { items } = (await inquirer.prompt([
-      {
-        type: 'checkbox',
-        name: 'items',
-        message: 'Select items to migrate:',
-        choices: itemChoices,
-        validate: (input: string[]) => {
-          if (input.length === 0) {
-            return 'Please select at least one item';
-          }
-          return true;
-        },
-      },
-    ] as any)) as { items: string[] };
-
-    // If "All" is selected, return all items
-    if (items.includes('__ALL__')) {
-      return { all: true };
+  // Build list of all transforms in this category
+  const transformChoices = [
+    {
+      name: `🔘 All transforms in ${selectedCategory}`,
+      value: '__ALL__',
+    },
+  ];
+
+  for (const [itemName, item] of Object.entries(category.variables)) {
+    for (const transform of item.transforms) {
+      transformChoices.push({
+        name: `${itemName}.${transform.name} - ${transform.description}`,
+        value: `${selectedCategory}.${itemName}.${transform.name}`,
+      });
     }
-
-    return { items };
   }
 
-  if (scope === 'transform') {
-    // Build list of all transforms
-    const transformChoices: Array<{ name: string; value: string; checked?: boolean }> = [
-      {
-        name: '🔘 All transforms',
-        value: '__ALL__',
-        checked: false,
-      },
-    ];
-
-    for (const [categoryName, category] of Object.entries(config.categories)) {
-      for (const [variableName, variable] of Object.entries(category.variables)) {
-        for (const transform of variable.transforms) {
-          transformChoices.push({
-            name: `${categoryName}.${variableName}.${transform.name} - ${transform.description}`,
-            value: `${categoryName}.${variableName}.${transform.name}`,
-          });
-        }
-      }
-    }
-
-    const { transforms } = (await inquirer.prompt([
-      {
-        type: 'checkbox',
-        name: 'transforms',
-        message: 'Select transforms to run:',
-        choices: transformChoices,
-        validate: (input: string[]) => {
-          if (input.length === 0) {
-            return 'Please select at least one transform';
-          }
-          return true;
-        },
-      },
-    ] as any)) as { transforms: string[] };
-
-    // If "All" is selected, return all transforms
-    if (transforms.includes('__ALL__')) {
-      return { all: true };
-    }
+  const { selectedTransform } = await inquirer.prompt([
+    {
+      type: 'list',
+      name: 'selectedTransform',
+      message: `Which transform in "${selectedCategory}" category?`,
+      choices: transformChoices,
+    },
+  ]);
 
-    return { transforms };
+  // If "All transforms" selected, run all in this category
+  if (selectedTransform === '__ALL__') {
+    return { categories: [selectedCategory] };
   }
 
-  return { all: true };
+  // Return the specific transform
+  return { transforms: [selectedTransform] };
 }
 
 async function runInteractiveMode() {
-  // Step 1: Select migration version
+  // Step 1: Select migration preset
   const answers = await inquirer.prompt([
     {
       type: 'list',
-      name: 'migration',
-      message: 'Which major version migration do you need?',
-      choices: SUPPORTED_MIGRATIONS.map((m) => ({
+      name: 'preset',
+      message: 'Which migration preset do you need?',
+      choices: AVAILABLE_PRESETS.map((m) => ({
         name: `${m.name} - ${m.description}`,
         value: m.value,
       })),
@@ -223,11 +147,11 @@ async function runInteractiveMode() {
   }
 
   // Step 4: Load config and let user select scope
-  const migrationDir = path.join(__dirname, answers.migration);
-  const selection = await selectMigrationScope(migrationDir);
+  const presetDir = path.join(__dirname, answers.preset);
+  const selection = await selectMigrationScope(presetDir);
 
   // Step 5: Show what will be migrated
-  const config = loadMigrationConfig(migrationDir);
+  const config = loadMigrationConfig(presetDir);
   const summary = buildMigrationSummary(config, selection);
   console.log(summary);
 
@@ -241,11 +165,12 @@ async function runInteractiveMode() {
     },
   ]);
 
-  // Check for migration history and warn about duplicate runs
+  // Check for migration history and warn about duplicate runs (skip if dry-run)
   const selectedTransforms = getSelectedTransforms(config, selection);
   const transformIds = selectedTransforms.map((t) => `${t.category}.${t.variable}.${t.name}`);
   const alreadyRun = getAlreadyRunTransforms(targetPath, transformIds);
 
+  // Only warn about duplicates if NOT in dry-run mode
   if (alreadyRun.length > 0 && !modeAnswer.dryRun) {
     console.log('\n⚠️  Warning: Some transforms have already been run on this path:\n');
     for (const transformId of alreadyRun) {
@@ -301,7 +226,7 @@ async function runInteractiveMode() {
   }
 
   console.log('\n📋 Migration Summary:');
-  console.log(`  Version: ${answers.migration}`);
+  console.log(`  Preset: ${answers.preset}`);
   console.log(`  Path: ${targetPath}`);
   console.log(`  Mode: ${modeAnswer.dryRun ? 'Dry Run' : 'Apply Changes'}\n`);
 
@@ -322,7 +247,7 @@ async function runInteractiveMode() {
   }
 
   return {
-    migration: answers.migration,
+    preset: answers.preset,
     path: targetPath,
     dryRun: modeAnswer.dryRun,
     selection,
@@ -330,7 +255,7 @@ async function runInteractiveMode() {
 }
 
 async function runNonInteractiveMode(args: CliArgs) {
-  const migration = args.version!;
+  const preset = args.preset!;
   const targetPath = args.path!;
   const dryRun = args.dryRun || false;
   const selection = buildSelectionFromArgs(args);
@@ -340,17 +265,17 @@ async function runNonInteractiveMode(args: CliArgs) {
     process.exit(1);
   }
 
-  // Validate migration version
-  const isValidMigration = SUPPORTED_MIGRATIONS.some((m) => m.value === migration);
-  if (!isValidMigration) {
-    console.error(`Error: Invalid migration version '${migration}'`);
-    console.error(`Available versions: ${SUPPORTED_MIGRATIONS.map((m) => m.value).join(', ')}`);
+  // Validate preset
+  const isValidPreset = AVAILABLE_PRESETS.some((p) => p.value === preset);
+  if (!isValidPreset) {
+    console.error(`Error: Invalid preset '${preset}'`);
+    console.error(`Available presets: ${AVAILABLE_PRESETS.map((p) => p.value).join(', ')}`);
     process.exit(1);
   }
 
   // Load config
-  const migrationDir = path.join(__dirname, migration);
-  const config = loadMigrationConfig(migrationDir);
+  const presetDir = path.join(__dirname, preset);
+  const config = loadMigrationConfig(presetDir);
 
   // Show migration plan
   const summary = buildMigrationSummary(config, selection);
@@ -371,13 +296,13 @@ async function runNonInteractiveMode(args: CliArgs) {
   }
 
   console.log('\n📋 Migration Summary:');
-  console.log(`  Version: ${migration}`);
+  console.log(`  Preset: ${preset}`);
   console.log(`  Path: ${targetPath}`);
   console.log(`  Mode: ${dryRun ? 'Dry Run' : 'Apply Changes'}`);
   console.log(`  Transforms: ${selectedTransforms.length}\n`);
 
   return {
-    migration,
+    preset: preset,
     path: targetPath,
     dryRun,
     selection,
diff --git a/packages/migrator/src/index.ts b/packages/migrator/src/index.ts
index 815468540..45ec62290 100644
--- a/packages/migrator/src/index.ts
+++ b/packages/migrator/src/index.ts
@@ -4,6 +4,6 @@
  * Code migration tools for the Coinbase Design System
  */
 
-export * from './types.js';
 export { runMigration } from './runner.js';
+export * from './types.js';
 export * from './utils/index.js';
diff --git a/packages/migrator/src/runner.ts b/packages/migrator/src/runner.ts
index 28b5bdba5..b0994bbf6 100644
--- a/packages/migrator/src/runner.ts
+++ b/packages/migrator/src/runner.ts
@@ -7,11 +7,12 @@
 import { execSync } from 'child_process';
 import path from 'path';
 import { fileURLToPath } from 'url';
+
 import {
   createLogger,
-  loadMigrationConfig,
   getSelectedTransforms,
   hasTransformBeenRun,
+  loadMigrationConfig,
   recordTransformRun,
 } from './utils/index.js';
 import type { MigrationSelection } from './types.js';
@@ -19,27 +20,27 @@ import type { MigrationSelection } from './types.js';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 
-interface RunMigrationOptions {
-  migration: string;
+type RunMigrationOptions = {
+  preset: string;
   path: string;
   dryRun: boolean;
   selection?: MigrationSelection;
-}
+};
 
 export async function runMigration(options: RunMigrationOptions): Promise<void> {
-  const { migration, path: targetPath, dryRun, selection = { all: true } } = options;
+  const { preset, path: targetPath, dryRun, selection = { all: true } } = options;
 
-  console.log(`\n🔄 Running ${migration} migration...\n`);
+  console.log(`\n🔄 Running ${preset} migration...\n`);
 
   // Create logger for this migration run
   const logger = createLogger(process.cwd());
-  logger.info(`Starting ${migration} migration`);
+  logger.info(`Starting ${preset} migration`);
   logger.info(`Target path: ${targetPath}`);
   logger.info(`Mode: ${dryRun ? 'Dry Run' : 'Apply Changes'}`);
 
   // Load config and get selected transforms
-  const migrationDir = path.join(__dirname, migration);
-  const config = loadMigrationConfig(migrationDir);
+  const presetDir = path.join(__dirname, preset);
+  const config = loadMigrationConfig(presetDir);
   const transforms = getSelectedTransforms(config, selection);
 
   if (transforms.length === 0) {
@@ -70,7 +71,9 @@ export async function runMigration(options: RunMigrationOptions): Promise<void>
       `Running transform: ${transform.name} (${transform.category}.${transform.variable})`,
     );
 
-    const transformPath = path.join(migrationDir, transform.file);
+    // Add .js extension if not present (transforms are compiled from .ts to .js)
+    const transformFile = transform.file.endsWith('.js') ? transform.file : `${transform.file}.js`;
+    const transformPath = path.join(presetDir, transformFile);
     const extensions = transform.extensions || 'tsx,ts,jsx,js';
 
     try {
@@ -101,7 +104,7 @@ export async function runMigration(options: RunMigrationOptions): Promise<void>
       logger.success(`Transform completed: ${transform.name}`);
 
       // Record this transform run in history (only for non-dry-runs)
-      recordTransformRun(targetPath, transformId, migration, dryRun);
+      recordTransformRun(targetPath, transformId, preset, dryRun);
     } catch (error) {
       console.error(`\n  ✗ Transform failed: ${transform.name}`);
       logger.error(
diff --git a/packages/migrator/src/types.ts b/packages/migrator/src/types.ts
index bcebef7d2..85172cea8 100644
--- a/packages/migrator/src/types.ts
+++ b/packages/migrator/src/types.ts
@@ -2,7 +2,7 @@
  * Types for CDS migration tools
  */
 
-export interface MigrationOptions {
+export type MigrationOptions = {
   /**
    * Paths to files or directories to migrate
    */
@@ -11,9 +11,9 @@ export interface MigrationOptions {
    * Whether to perform a dry run without modifying files
    */
   dryRun?: boolean;
-}
+};
 
-export interface Transform {
+export type Transform = {
   /**
    * Name of the transform
    */
@@ -31,9 +31,9 @@ export interface Transform {
    * @default "tsx,ts,jsx,js"
    */
   extensions?: string;
-}
+};
 
-export interface MigrationModule {
+export type MigrationModule = {
   /**
    * List of transforms to run for this migration
    */
@@ -42,12 +42,12 @@ export interface MigrationModule {
    * Description of the migration and breaking changes
    */
   description: string;
-}
+};
 
 /**
  * Configuration for a migration variable (component, hook, utility, etc.)
  */
-export interface MigrationVariable {
+export type MigrationVariable = {
   /**
    * Human-readable description of the changes
    */
@@ -60,12 +60,12 @@ export interface MigrationVariable {
    * List of transforms to apply for this variable
    */
   transforms: Transform[];
-}
+};
 
 /**
  * Configuration for a migration category
  */
-export interface MigrationCategory {
+export type MigrationCategory = {
   /**
    * Human-readable description of the category
    */
@@ -74,16 +74,16 @@ export interface MigrationCategory {
    * Variables (components, hooks, utilities, etc.) in this category
    */
   variables: Record<string, MigrationVariable>;
-}
+};
 
 /**
  * Main migration configuration structure
  */
-export interface MigrationConfig {
+export type MigrationConfig = {
   /**
-   * Version identifier (e.g., "v8-to-v9")
+   * Preset identifier (e.g., "v8-to-v9")
    */
-  version: string;
+  preset: string;
   /**
    * Overall description of the migration
    */
@@ -92,12 +92,12 @@ export interface MigrationConfig {
    * Categories of changes organized by type
    */
   categories: Record<string, MigrationCategory>;
-}
+};
 
 /**
  * Selection for what to migrate
  */
-export interface MigrationSelection {
+export type MigrationSelection = {
   /**
    * If true, migrate everything
    */
@@ -115,4 +115,4 @@ export interface MigrationSelection {
    * Specific transforms to migrate (format: "category.item.transform")
    */
   transforms?: string[];
-}
+};
diff --git a/packages/migrator/src/utils/config-loader.ts b/packages/migrator/src/utils/config-loader.ts
index ab00c8749..6a48694d2 100644
--- a/packages/migrator/src/utils/config-loader.ts
+++ b/packages/migrator/src/utils/config-loader.ts
@@ -4,7 +4,8 @@
 
 import fs from 'fs';
 import path from 'path';
-import type { MigrationConfig, Transform, MigrationSelection } from '../types.js';
+
+import type { MigrationConfig, MigrationSelection, Transform } from '../types.js';
 
 /**
  * Load migration configuration from config.json
diff --git a/packages/migrator/src/utils/index.ts b/packages/migrator/src/utils/index.ts
index bf9a6d841..3250657b8 100644
--- a/packages/migrator/src/utils/index.ts
+++ b/packages/migrator/src/utils/index.ts
@@ -2,8 +2,8 @@
  * Shared utility functions for CDS migrations
  */
 
+export * from './config-loader.js';
+export * from './constants.js';
 export * from './insert-todo.js';
 export * from './logger.js';
-export * from './constants.js';
-export * from './config-loader.js';
 export * from './migration-history.js';
diff --git a/packages/migrator/src/utils/insert-todo.ts b/packages/migrator/src/utils/insert-todo.ts
index aa7ffdeeb..8ae3635ab 100644
--- a/packages/migrator/src/utils/insert-todo.ts
+++ b/packages/migrator/src/utils/insert-todo.ts
@@ -3,9 +3,10 @@
  */
 
 import type { API, Collection } from 'jscodeshift';
+
 import { TODO_PREFIX } from './constants.js';
 
-export interface InsertTodoOptions {
+export type InsertTodoOptions = {
   /**
    * The message to include in the TODO comment
    */
@@ -18,7 +19,7 @@ export interface InsertTodoOptions {
    * Whether to insert before or after the node
    */
   position?: 'before' | 'after';
-}
+};
 
 /**
  * Insert a TODO comment near a JSX element
diff --git a/packages/migrator/src/utils/logger.ts b/packages/migrator/src/utils/logger.ts
index c3e43745f..26dc32561 100644
--- a/packages/migrator/src/utils/logger.ts
+++ b/packages/migrator/src/utils/logger.ts
@@ -4,6 +4,7 @@
 
 import fs from 'fs';
 import path from 'path';
+
 import { LOG_FILE_NAME } from './constants.js';
 
 export const LogLevel = {
@@ -16,14 +17,14 @@ export const LogLevel = {
 
 export type LogLevel = (typeof LogLevel)[keyof typeof LogLevel];
 
-export interface LogEntry {
+export type LogEntry = {
   timestamp: string;
   level: LogLevel;
   file?: string;
   line?: number;
   message: string;
   details?: string;
-}
+};
 
 /**
  * Migration logger for tracking changes and issues
diff --git a/packages/migrator/src/utils/migration-history.ts b/packages/migrator/src/utils/migration-history.ts
index 4f47ab6c2..b72fb4554 100644
--- a/packages/migrator/src/utils/migration-history.ts
+++ b/packages/migrator/src/utils/migration-history.ts
@@ -6,11 +6,12 @@
 
 import fs from 'fs';
 import path from 'path';
+
 import type { Transform } from '../types.js';
 
 const HISTORY_FILE_NAME = '.cds-migration-history.json';
 
-export interface MigrationHistoryEntry {
+export type MigrationHistoryEntry = {
   /**
    * Transform identifier (e.g., "components.Button.button-variant-to-appearance")
    */
@@ -20,16 +21,16 @@ export interface MigrationHistoryEntry {
    */
   timestamp: string;
   /**
-   * Version migration (e.g., "v8-to-v9")
+   * Preset name (e.g., "v8-to-v9")
    */
-  version: string;
+  preset: string;
   /**
    * Whether it was a dry run
    */
   dryRun: boolean;
-}
+};
 
-export interface MigrationHistory {
+export type MigrationHistory = {
   /**
    * Target path that was migrated
    */
@@ -42,7 +43,7 @@ export interface MigrationHistory {
    * Last update timestamp
    */
   lastUpdated: string;
-}
+};
 
 /**
  * Get the history file path for a target directory
@@ -93,7 +94,7 @@ export function saveMigrationHistory(targetPath: string, history: MigrationHisto
 export function recordTransformRun(
   targetPath: string,
   transformId: string,
-  version: string,
+  preset: string,
   dryRun: boolean,
 ): void {
   let history = loadMigrationHistory(targetPath);
@@ -110,7 +111,7 @@ export function recordTransformRun(
   history.entries.push({
     transformId,
     timestamp: new Date().toISOString(),
-    version,
+    preset,
     dryRun,
   });
 
@@ -163,23 +164,23 @@ export function buildHistorySummary(targetPath: string): string {
     return 'No migration history found for this path.';
   }
 
-  // Group entries by version
-  const byVersion: Record<string, MigrationHistoryEntry[]> = {};
+  // Group entries by preset
+  const byPreset: Record<string, MigrationHistoryEntry[]> = {};
   for (const entry of history.entries) {
     if (!entry.dryRun) {
       // Only show non-dry-run entries
-      if (!byVersion[entry.version]) {
-        byVersion[entry.version] = [];
+      if (!byPreset[entry.preset]) {
+        byPreset[entry.preset] = [];
       }
-      byVersion[entry.version].push(entry);
+      byPreset[entry.preset].push(entry);
     }
   }
 
   let summary = '\n📜 Migration History\n';
   summary += '==================\n\n';
 
-  for (const [version, entries] of Object.entries(byVersion)) {
-    summary += `${version}:\n`;
+  for (const [preset, entries] of Object.entries(byPreset)) {
+    summary += `${preset}:\n`;
     for (const entry of entries) {
       const date = new Date(entry.timestamp).toLocaleDateString();
       summary += `  • ${entry.transformId} (${date})\n`;
diff --git a/packages/migrator/src/v8-to-v9/config.json b/packages/migrator/src/v8-to-v9/config.json
index 6218f956d..27c2608c8 100644
--- a/packages/migrator/src/v8-to-v9/config.json
+++ b/packages/migrator/src/v8-to-v9/config.json
@@ -1,5 +1,5 @@
 {
-  "version": "v8-to-v9",
+  "preset": "v8-to-v9",
   "description": "Migration from CDS v8 to v9",
   "categories": {
     "components": {
@@ -12,7 +12,7 @@
             {
               "name": "button-variant-to-appearance",
               "description": "Rename 'variant' prop to 'appearance'",
-              "file": "transforms/button-variant-to-appearance.ts"
+              "file": "transforms/example-transform"
             }
           ]
         },
@@ -23,7 +23,7 @@
             {
               "name": "input-size-values",
               "description": "Update size prop values (sm/md/lg to small/medium/large)",
-              "file": "transforms/input-size-values.ts"
+              "file": "transforms/example-transform"
             }
           ]
         }
@@ -39,7 +39,7 @@
             {
               "name": "use-theme-return-type",
               "description": "Update destructured return values from useTheme",
-              "file": "transforms/use-theme-return-type.ts"
+              "file": "transforms/example-transform"
             }
           ]
         }
@@ -55,7 +55,7 @@
             {
               "name": "format-currency-options",
               "description": "Update formatCurrency options parameter",
-              "file": "transforms/format-currency-options.ts"
+              "file": "transforms/example-transform"
             }
           ]
         }
diff --git a/packages/migrator/src/v8-to-v9/index.ts b/packages/migrator/src/v8-to-v9/index.ts
index 397ddfad5..72d715a9c 100644
--- a/packages/migrator/src/v8-to-v9/index.ts
+++ b/packages/migrator/src/v8-to-v9/index.ts
@@ -4,12 +4,12 @@
  * This module defines all transforms needed to migrate from CDS v8 to v9
  */
 
-export interface Transform {
+export type Transform = {
   name: string;
   description: string;
   file: string;
   extensions?: string;
-}
+};
 
 export const transforms: Transform[] = [
   // Add transforms here as they are created
diff --git a/packages/migrator/src/v8-to-v9/transforms/example-transform.ts b/packages/migrator/src/v8-to-v9/transforms/example-transform.ts
index 2efff738b..706d1a089 100644
--- a/packages/migrator/src/v8-to-v9/transforms/example-transform.ts
+++ b/packages/migrator/src/v8-to-v9/transforms/example-transform.ts
@@ -6,8 +6,10 @@
  */
 
 import type { API, FileInfo, Options } from 'jscodeshift';
+
 import { addTodoToAttribute, getLogger, hasMigrationTodo } from '../../utils/index.js';
 
+// eslint-disable-next-line no-restricted-exports -- jscodeshift requires default export
 export default function transformer(file: FileInfo, api: API, options: Options) {
   const j = api.jscodeshift;
   const root = j(file.source);
diff --git a/yarn.lock b/yarn.lock
index ef657514e..b04cf66c1 100644
--- a/yarn.lock
+++ b/yarn.lock
@@ -2216,7 +2216,7 @@ __metadata:
   languageName: unknown
   linkType: soft
 
-"@coinbase/cds-migrator@workspace:packages/migrator":
+"@coinbase/cds-migrator@workspace:^, @coinbase/cds-migrator@workspace:packages/migrator":
   version: 0.0.0-use.local
   resolution: "@coinbase/cds-migrator@workspace:packages/migrator"
   dependencies:
@@ -2232,6 +2232,8 @@ __metadata:
     jscodeshift: "npm:^0.15.1"
   bin:
     cds-migrate: ./esm/cli.js
+    "cds-migrate:all": ./esm/bin/migrate-all.js
+    "cds-migrate:clear-history": ./esm/bin/clear-history.js
   languageName: unknown
   linkType: soft
 
@@ -32226,6 +32228,7 @@ __metadata:
     "@coinbase/cds-common": "workspace:^"
     "@coinbase/cds-icons": "workspace:^"
     "@coinbase/cds-illustrations": "workspace:^"
+    "@coinbase/cds-migrator": "workspace:^"
     "@coinbase/cds-web": "workspace:^"
     "@coinbase/cds-web-visualization": "workspace:^"
     "@types/react": "npm:19.1.2"

From 4a8739182be6100b3e4bacca81e058ed9b9ce25e Mon Sep 17 00:00:00 2001
From: Adrien Zheng <adrien.zheng@coinbase.com>
Date: Thu, 26 Feb 2026 16:01:44 -0500
Subject: [PATCH 3/5] update readme

---
 packages/migrator/README.md | 53 +++++++++++++++++++++++++++++--------
 1 file changed, 42 insertions(+), 11 deletions(-)

diff --git a/packages/migrator/README.md b/packages/migrator/README.md
index 555778783..4de555224 100644
--- a/packages/migrator/README.md
+++ b/packages/migrator/README.md
@@ -16,12 +16,13 @@ npx @coinbase/cds-migrator -p v8-to-v9 --path ./src --all --dry-run
 
 ## Features
 
-- 🎯 **Granular Selection** - Migrate everything or choose specific components/hooks/utilities
+- 🎯 **Hierarchical Selection** - Choose category, then drill down to specific transforms
 - 📝 **History Tracking** - Automatically prevents duplicate migrations
 - 🔍 **Dry-Run Mode** - Preview all changes before applying
 - 📊 **Comprehensive Logging** - Track successes, warnings, and manual TODOs
 - 💬 **TODO Comments** - Automatically marks code that needs manual review
-- 🌳 **Configuration-Based** - Three-level structure (categories → variables → transforms)
+- 🌳 **Configuration-Based** - Three-level structure (categories → items → transforms)
+- 🚀 **Convenience Commands** - `cds-migrate`, `cds-migrate:all`, `cds-migrate:clear-history`
 
 ## Available Presets
 
@@ -31,6 +32,24 @@ npx @coinbase/cds-migrator -p v8-to-v9 --path ./src --all --dry-run
 
 **Note:** Presets aren't just for version migrations - you can create presets for any collection of code transforms (deprecations, refactors, style updates, etc.).
 
+## How It Works
+
+The migrator uses a **simple 3-step selection**:
+
+1. **Choose a preset** (e.g., v8-to-v9)
+2. **Choose a category** (or "All categories" to migrate everything)
+3. **Choose a transform** in that category (or "All transforms" to run all)
+
+This hierarchical approach makes it easy to focus on one area at a time without being overwhelmed by choices.
+
+## Convenience Commands
+
+After installation, you get three commands:
+
+- `cds-migrate` - Full interactive CLI
+- `cds-migrate:all -p <preset>` - Quick migrate everything
+- `cds-migrate:clear-history` - Quick clear history
+
 ## Documentation
 
 ### 📘 For Users
@@ -86,25 +105,37 @@ Read these if you're adding new migrations or transforms:
 
 ? Enter the path to your codebase: ./src
 
-? What would you like to migrate?
-  ❯ Everything (all changes)
-    By category (components, hooks, etc.)
-    By item (specific component/hook/utility)
-    By specific transform
+? Which category of transforms do you want to run?
+  ❯ 🔘 All categories
+    components - Component API changes
+    hooks - Hook API changes
+    utilities - Utility function changes
 
 Migration Plan:
 ================
 📦 components: Component API changes
   └─ Button (@coinbase/cds-web)
      • Rename 'variant' prop to 'appearance'
+  └─ Input (@coinbase/cds-web)
+     • Update size prop values
+
+📦 hooks: Hook API changes
+  └─ useTheme (@coinbase/cds-common)
+     • Update destructured return values
 
-Total transforms: 1
+📦 utilities: Utility function changes
+  └─ formatCurrency (@coinbase/cds-utils)
+     • Update formatCurrency options parameter
+
+Total transforms: 4
 
 ? Run in dry-run mode? Yes
 
   → Running transform: components.Button.button-variant-to-appearance
   ✓ Transform completed
 
+  [... 3 more transforms ...]
+
 ✅ Migration completed successfully!
 📝 Migration log written to: migration.log
 ```
@@ -150,7 +181,7 @@ cd packages/migrator
 node esm/cli.js
 ```
 
-### Adding New Migrations
+### Adding New Presets
 
 See [docs/CONFIGURATION.md](./docs/CONFIGURATION.md) for complete instructions.
 
@@ -158,8 +189,8 @@ Quick steps:
 
 1. Create `src/v9-to-v10/` directory
 2. Add `config.json` with three-level structure
-3. Create transforms in `transforms/` directory
-4. Update `SUPPORTED_MIGRATIONS` in `src/cli.ts`
+3. Create transforms in `transforms/` directory (as `.ts` files)
+4. Update `AVAILABLE_PRESETS` in `src/cli.ts`
 
 ## Contributing
 

From ce2263ab60e79240359aa9bb1c3494dff421a1b8 Mon Sep 17 00:00:00 2001
From: Boba <ruikun.hao@coinbase.com>
Date: Fri, 27 Feb 2026 15:49:57 -0600
Subject: [PATCH 4/5] feat: set up Button variant migration

---
 packages/migrator/jest.config.js              |  14 +
 packages/migrator/project.json                |   7 +
 packages/migrator/src/types/jscodeshift.d.ts  |  11 +
 packages/migrator/src/v8-to-v9/config.json    |  51 +--
 .../basic-literal.input.tsx                   |  12 +
 .../basic-literal.output.tsx                  |  12 +
 .../dynamic-variant.input.tsx                 |   9 +
 .../dynamic-variant.output.tsx                |  13 +
 .../spread-props.input.tsx                    |  12 +
 .../spread-props.output.tsx                   |  16 +
 .../__tests__/button-variant-mapping.test.ts  | 141 +++++++
 .../transforms/button-variant-mapping.ts      |  16 +
 .../src/v8-to-v9/transforms/test-utils.ts     |  23 ++
 .../transforms/utils/variant-migration.ts     | 362 ++++++++++++++++++
 packages/migrator/tsconfig.json               |  10 +-
 packages/migrator/tsconfig.spec.json          |  17 +
 16 files changed, 678 insertions(+), 48 deletions(-)
 create mode 100644 packages/migrator/jest.config.js
 create mode 100644 packages/migrator/src/types/jscodeshift.d.ts
 create mode 100644 packages/migrator/src/v8-to-v9/transforms/__fixtures__/button-variant-mapping/basic-literal.input.tsx
 create mode 100644 packages/migrator/src/v8-to-v9/transforms/__fixtures__/button-variant-mapping/basic-literal.output.tsx
 create mode 100644 packages/migrator/src/v8-to-v9/transforms/__fixtures__/button-variant-mapping/dynamic-variant.input.tsx
 create mode 100644 packages/migrator/src/v8-to-v9/transforms/__fixtures__/button-variant-mapping/dynamic-variant.output.tsx
 create mode 100644 packages/migrator/src/v8-to-v9/transforms/__fixtures__/button-variant-mapping/spread-props.input.tsx
 create mode 100644 packages/migrator/src/v8-to-v9/transforms/__fixtures__/button-variant-mapping/spread-props.output.tsx
 create mode 100644 packages/migrator/src/v8-to-v9/transforms/__tests__/button-variant-mapping.test.ts
 create mode 100644 packages/migrator/src/v8-to-v9/transforms/button-variant-mapping.ts
 create mode 100644 packages/migrator/src/v8-to-v9/transforms/test-utils.ts
 create mode 100644 packages/migrator/src/v8-to-v9/transforms/utils/variant-migration.ts
 create mode 100644 packages/migrator/tsconfig.spec.json

diff --git a/packages/migrator/jest.config.js b/packages/migrator/jest.config.js
new file mode 100644
index 000000000..733749904
--- /dev/null
+++ b/packages/migrator/jest.config.js
@@ -0,0 +1,14 @@
+const config = {
+  preset: '../../jest.preset.js',
+  displayName: 'cds-migrator',
+  // Migrator tests execute codemods and filesystem helpers, so Node is the correct runtime.
+  testEnvironment: 'node',
+  coverageReporters: ['text-summary', 'text', 'json-summary'],
+  moduleNameMapper: {
+    // Transform source imports use ESM ".js" specifiers, but Jest runs TS sources in tests.
+    // Remap relative ".js" imports to extensionless paths so Jest resolves TS modules correctly.
+    '^(\\.{1,2}/.*)\\.js$': '$1',
+  },
+};
+
+export default config;
diff --git a/packages/migrator/project.json b/packages/migrator/project.json
index a3ac821d0..5025cb97b 100644
--- a/packages/migrator/project.json
+++ b/packages/migrator/project.json
@@ -22,6 +22,13 @@
     "lint": {
       "executor": "@nx/eslint:lint"
     },
+    "test": {
+      "executor": "nx:run-commands",
+      "options": {
+        "command": "jest --maxWorkers=75%",
+        "cwd": "{projectRoot}"
+      }
+    },
     "typecheck": {
       "executor": "nx:run-commands",
       "defaultConfiguration": "dev",
diff --git a/packages/migrator/src/types/jscodeshift.d.ts b/packages/migrator/src/types/jscodeshift.d.ts
new file mode 100644
index 000000000..20a339dfc
--- /dev/null
+++ b/packages/migrator/src/types/jscodeshift.d.ts
@@ -0,0 +1,11 @@
+declare module 'jscodeshift' {
+  export function withParser(parser: string): any;
+
+  export type API = any;
+  export type ASTPath<T = any> = any;
+  export type Collection<T = any> = any;
+  export type FileInfo = any;
+  export type JSXAttribute = any;
+  export type JSXOpeningElement = any;
+  export type Options = any;
+}
diff --git a/packages/migrator/src/v8-to-v9/config.json b/packages/migrator/src/v8-to-v9/config.json
index 27c2608c8..3f91170b7 100644
--- a/packages/migrator/src/v8-to-v9/config.json
+++ b/packages/migrator/src/v8-to-v9/config.json
@@ -6,56 +6,13 @@
       "description": "Component API changes",
       "variables": {
         "Button": {
-          "description": "Button component prop changes",
+          "description": "Button and IconButton variant changes",
           "package": "@coinbase/cds-web",
           "transforms": [
             {
-              "name": "button-variant-to-appearance",
-              "description": "Rename 'variant' prop to 'appearance'",
-              "file": "transforms/example-transform"
-            }
-          ]
-        },
-        "Input": {
-          "description": "Input component prop changes",
-          "package": "@coinbase/cds-web",
-          "transforms": [
-            {
-              "name": "input-size-values",
-              "description": "Update size prop values (sm/md/lg to small/medium/large)",
-              "file": "transforms/example-transform"
-            }
-          ]
-        }
-      }
-    },
-    "hooks": {
-      "description": "Hook API changes",
-      "variables": {
-        "useTheme": {
-          "description": "useTheme hook signature changes",
-          "package": "@coinbase/cds-common",
-          "transforms": [
-            {
-              "name": "use-theme-return-type",
-              "description": "Update destructured return values from useTheme",
-              "file": "transforms/example-transform"
-            }
-          ]
-        }
-      }
-    },
-    "utilities": {
-      "description": "Utility function changes",
-      "variables": {
-        "formatCurrency": {
-          "description": "formatCurrency function signature changes",
-          "package": "@coinbase/cds-utils",
-          "transforms": [
-            {
-              "name": "format-currency-options",
-              "description": "Update formatCurrency options parameter",
-              "file": "transforms/example-transform"
+              "name": "button-variant-mapping",
+              "description": "Map Button/IconButton variant values (tertiary→inverse, foregroundMuted→secondary)",
+              "file": "transforms/button-variant-mapping"
             }
           ]
         }
diff --git a/packages/migrator/src/v8-to-v9/transforms/__fixtures__/button-variant-mapping/basic-literal.input.tsx b/packages/migrator/src/v8-to-v9/transforms/__fixtures__/button-variant-mapping/basic-literal.input.tsx
new file mode 100644
index 000000000..3f549d26b
--- /dev/null
+++ b/packages/migrator/src/v8-to-v9/transforms/__fixtures__/button-variant-mapping/basic-literal.input.tsx
@@ -0,0 +1,12 @@
+import React from 'react';
+// @ts-expect-error -- Fixture intentionally imports Button/IconButton from @coinbase/cds-web to exercise codemod import matching; typings are not validated for fixture sources.
+import { Button, IconButton } from '@coinbase/cds-web';
+
+export function Example() {
+  return (
+    <>
+      <Button variant="tertiary">Save</Button>
+      <IconButton name="close" variant="foregroundMuted" />
+    </>
+  );
+}
diff --git a/packages/migrator/src/v8-to-v9/transforms/__fixtures__/button-variant-mapping/basic-literal.output.tsx b/packages/migrator/src/v8-to-v9/transforms/__fixtures__/button-variant-mapping/basic-literal.output.tsx
new file mode 100644
index 000000000..bed17c9c8
--- /dev/null
+++ b/packages/migrator/src/v8-to-v9/transforms/__fixtures__/button-variant-mapping/basic-literal.output.tsx
@@ -0,0 +1,12 @@
+import React from 'react';
+// @ts-expect-error -- Fixture intentionally imports Button/IconButton from @coinbase/cds-web to exercise codemod import matching; typings are not validated for fixture sources.
+import { Button, IconButton } from '@coinbase/cds-web';
+
+export function Example() {
+  return (
+    <>
+      <Button variant="inverse">Save</Button>
+      <IconButton name="close" variant="secondary" />
+    </>
+  );
+}
diff --git a/packages/migrator/src/v8-to-v9/transforms/__fixtures__/button-variant-mapping/dynamic-variant.input.tsx b/packages/migrator/src/v8-to-v9/transforms/__fixtures__/button-variant-mapping/dynamic-variant.input.tsx
new file mode 100644
index 000000000..909d2124c
--- /dev/null
+++ b/packages/migrator/src/v8-to-v9/transforms/__fixtures__/button-variant-mapping/dynamic-variant.input.tsx
@@ -0,0 +1,9 @@
+import React from 'react';
+// @ts-expect-error -- Fixture intentionally imports Button/IconButton from @coinbase/cds-web to exercise codemod import matching; typings are not validated for fixture sources.
+import { Button } from '@coinbase/cds-web';
+
+const variant = getVariant();
+
+export function Example() {
+  return <Button variant={variant}>Save</Button>;
+}
diff --git a/packages/migrator/src/v8-to-v9/transforms/__fixtures__/button-variant-mapping/dynamic-variant.output.tsx b/packages/migrator/src/v8-to-v9/transforms/__fixtures__/button-variant-mapping/dynamic-variant.output.tsx
new file mode 100644
index 000000000..8213ce92a
--- /dev/null
+++ b/packages/migrator/src/v8-to-v9/transforms/__fixtures__/button-variant-mapping/dynamic-variant.output.tsx
@@ -0,0 +1,13 @@
+import React from 'react';
+// @ts-expect-error -- Fixture intentionally imports Button/IconButton from @coinbase/cds-web to exercise codemod import matching; typings are not validated for fixture sources.
+import { Button } from '@coinbase/cds-web';
+
+const variant = getVariant();
+
+export function Example() {
+  return (
+    // TODO(cds-migration): Button variant requires manual migration
+    // Found dynamic or non-literal variant value. Verify mapping to v9 variants and update manually if needed.
+    <Button variant={variant}>Save</Button>
+  );
+}
diff --git a/packages/migrator/src/v8-to-v9/transforms/__fixtures__/button-variant-mapping/spread-props.input.tsx b/packages/migrator/src/v8-to-v9/transforms/__fixtures__/button-variant-mapping/spread-props.input.tsx
new file mode 100644
index 000000000..c55ff1372
--- /dev/null
+++ b/packages/migrator/src/v8-to-v9/transforms/__fixtures__/button-variant-mapping/spread-props.input.tsx
@@ -0,0 +1,12 @@
+import React from 'react';
+// @ts-expect-error -- Fixture intentionally imports Button/IconButton from @coinbase/cds-web to exercise codemod import matching; typings are not validated for fixture sources.
+import { IconButton } from '@coinbase/cds-web';
+
+const iconProps = {
+  variant: 'foregroundMuted' as const,
+  compact: true,
+};
+
+export function Example() {
+  return <IconButton {...iconProps} name="close" />;
+}
diff --git a/packages/migrator/src/v8-to-v9/transforms/__fixtures__/button-variant-mapping/spread-props.output.tsx b/packages/migrator/src/v8-to-v9/transforms/__fixtures__/button-variant-mapping/spread-props.output.tsx
new file mode 100644
index 000000000..b500561ce
--- /dev/null
+++ b/packages/migrator/src/v8-to-v9/transforms/__fixtures__/button-variant-mapping/spread-props.output.tsx
@@ -0,0 +1,16 @@
+import React from 'react';
+// @ts-expect-error -- Fixture intentionally imports Button/IconButton from @coinbase/cds-web to exercise codemod import matching; typings are not validated for fixture sources.
+import { IconButton } from '@coinbase/cds-web';
+
+const iconProps = {
+  variant: 'secondary' as const,
+  compact: true,
+};
+
+export function Example() {
+  return (
+    // TODO(cds-migration): IconButton spread props need manual review
+    // Found spread props on IconButton. Spread values may still contain legacy variant values. Review spread source and flatten/update variant explicitly. An obvious local object-literal variant was auto-updated, but full spread safety still requires manual verification.
+    <IconButton {...iconProps} name="close" />
+  );
+}
diff --git a/packages/migrator/src/v8-to-v9/transforms/__tests__/button-variant-mapping.test.ts b/packages/migrator/src/v8-to-v9/transforms/__tests__/button-variant-mapping.test.ts
new file mode 100644
index 000000000..81e75bfab
--- /dev/null
+++ b/packages/migrator/src/v8-to-v9/transforms/__tests__/button-variant-mapping.test.ts
@@ -0,0 +1,141 @@
+import fs from 'fs';
+import path from 'path';
+
+import { TODO_PREFIX } from '../../../utils/constants';
+import transformer from '../button-variant-mapping';
+import { runTransform } from '../test-utils';
+
+function readFixtureFile(fileName: string): string {
+  const fixturePath = path.resolve(
+    process.cwd(),
+    'src/v8-to-v9/transforms/__fixtures__/button-variant-mapping',
+    fileName,
+  );
+  return fs.readFileSync(fixturePath, 'utf8');
+}
+
+function normalizeCode(code: string): string {
+  return code.replace(/\s+/g, '').replace(/"/g, "'");
+}
+
+describe('button-variant-mapping', () => {
+  it('maps static literal variants for Button and IconButton', () => {
+    const source = `
+      import { Button, IconButton } from '@coinbase/cds-web';
+
+      export function Example() {
+        return (
+          <>
+            <Button variant="tertiary">Save</Button>
+            <IconButton variant="foregroundMuted" name="close" />
+            <Button variant={'foregroundMuted'}>Dismiss</Button>
+            <IconButton variant={"tertiary"} name="backArrow" />
+          </>
+        );
+      }
+    `;
+
+    const { output, entries } = runTransform(transformer, source);
+
+    expect(output).toContain('variant="inverse"');
+    expect(output).toContain('variant="secondary"');
+    expect(entries.some((entry) => entry.level === 'SUCCESS')).toBe(true);
+  });
+
+  it('supports imported aliases', () => {
+    const source = `
+      import { Button as CdsButton, IconButton as CdsIconButton } from '@coinbase/cds-web';
+
+      export const Example = () => (
+        <>
+          <CdsButton variant="tertiary">Save</CdsButton>
+          <CdsIconButton variant="foregroundMuted" name="close" />
+        </>
+      );
+    `;
+
+    const { output } = runTransform(transformer, source);
+
+    expect(output).toContain('<CdsButton variant="inverse">');
+    expect(output).toContain('<CdsIconButton variant="secondary" name="close" />');
+  });
+
+  it('adds TODO for dynamic variants and spread props', () => {
+    const source = `
+      import { Button, IconButton } from '@coinbase/cds-web';
+
+      const variant = shouldInvert() ? 'tertiary' : getVariant();
+      const iconProps = { variant: 'foregroundMuted' as const, compact: true };
+
+      export function Example() {
+        return (
+          <>
+            <Button variant={variant}>Save</Button>
+            <IconButton {...iconProps} name="close" />
+          </>
+        );
+      }
+    `;
+
+    const { output, entries } = runTransform(transformer, source);
+
+    expect(output).toContain(TODO_PREFIX);
+    expect(output).toMatch(/variant:\s*["']secondary["']/);
+    expect(entries.filter((entry) => entry.level === 'TODO').length).toBeGreaterThanOrEqual(2);
+  });
+
+  it('is idempotent for TODO insertion', () => {
+    const source = `
+      import { Button } from '@coinbase/cds-web';
+
+      export function Example({ variant, props }: { variant: string; props: Record<string, unknown> }) {
+        return <Button variant={variant} {...props}>Save</Button>;
+      }
+    `;
+
+    const first = runTransform(transformer, source).output;
+    const second = runTransform(transformer, first).output;
+
+    const firstTodoCount = first.split(TODO_PREFIX).length - 1;
+    const secondTodoCount = second.split(TODO_PREFIX).length - 1;
+    expect(secondTodoCount).toBe(firstTodoCount);
+  });
+
+  it('does not change non-target components', () => {
+    const source = `
+      import { Button as NotCdsButton } from './local';
+
+      export const Example = () => <NotCdsButton variant="tertiary">Save</NotCdsButton>;
+    `;
+
+    const { output, entries } = runTransform(transformer, source);
+    expect(output).toBe(source);
+    expect(entries.length).toBe(0);
+  });
+
+  it('matches basic-literal fixture output', () => {
+    const input = readFixtureFile('basic-literal.input.tsx');
+    const expected = readFixtureFile('basic-literal.output.tsx');
+
+    const { output } = runTransform(transformer, input);
+    expect(normalizeCode(output)).toBe(normalizeCode(expected));
+  });
+
+  it('matches dynamic-variant fixture output', () => {
+    const input = readFixtureFile('dynamic-variant.input.tsx');
+    const expected = readFixtureFile('dynamic-variant.output.tsx');
+
+    const { output, entries } = runTransform(transformer, input);
+    expect(normalizeCode(output)).toBe(normalizeCode(expected));
+    expect(entries.some((entry) => entry.level === 'TODO')).toBe(true);
+  });
+
+  it('matches spread-props fixture output', () => {
+    const input = readFixtureFile('spread-props.input.tsx');
+    const expected = readFixtureFile('spread-props.output.tsx');
+
+    const { output, entries } = runTransform(transformer, input);
+    expect(normalizeCode(output)).toBe(normalizeCode(expected));
+    expect(entries.some((entry) => entry.level === 'TODO')).toBe(true);
+  });
+});
diff --git a/packages/migrator/src/v8-to-v9/transforms/button-variant-mapping.ts b/packages/migrator/src/v8-to-v9/transforms/button-variant-mapping.ts
new file mode 100644
index 000000000..019acf613
--- /dev/null
+++ b/packages/migrator/src/v8-to-v9/transforms/button-variant-mapping.ts
@@ -0,0 +1,16 @@
+import type { API, FileInfo, Options } from 'jscodeshift';
+
+import { migrateVariantProps } from './utils/variant-migration.js';
+
+// eslint-disable-next-line no-restricted-exports -- jscodeshift requires default export
+export default function transformer(file: FileInfo, api: API, options: Options) {
+  return migrateVariantProps(file, api, options, {
+    componentNames: ['Button', 'IconButton'],
+    variantMapping: {
+      tertiary: 'inverse',
+      foregroundMuted: 'secondary',
+    },
+    transformLabel: 'button-variant-mapping',
+    includesTertiarySemanticWarning: true,
+  });
+}
diff --git a/packages/migrator/src/v8-to-v9/transforms/test-utils.ts b/packages/migrator/src/v8-to-v9/transforms/test-utils.ts
new file mode 100644
index 000000000..768c145c4
--- /dev/null
+++ b/packages/migrator/src/v8-to-v9/transforms/test-utils.ts
@@ -0,0 +1,23 @@
+import fs from 'fs';
+import type { API, FileInfo, Options } from 'jscodeshift';
+import { withParser } from 'jscodeshift';
+import os from 'os';
+import path from 'path';
+
+import type { LogEntry } from '../../utils/logger.js';
+import { createLogger } from '../../utils/logger.js';
+
+export function runTransform(
+  transform: (file: FileInfo, api: API, options: Options) => string | null,
+  source: string,
+): { output: string; entries: LogEntry[] } {
+  const outputDir = fs.mkdtempSync(path.join(os.tmpdir(), 'cds-migrator-test-'));
+  const logger = createLogger(outputDir);
+  const api = { jscodeshift: withParser('tsx') } as API;
+
+  const result = transform({ path: '/tmp/example.tsx', source }, api, {});
+  return {
+    output: result ?? source,
+    entries: logger.getEntries(),
+  };
+}
diff --git a/packages/migrator/src/v8-to-v9/transforms/utils/variant-migration.ts b/packages/migrator/src/v8-to-v9/transforms/utils/variant-migration.ts
new file mode 100644
index 000000000..84b08e1ab
--- /dev/null
+++ b/packages/migrator/src/v8-to-v9/transforms/utils/variant-migration.ts
@@ -0,0 +1,362 @@
+import type {
+  API,
+  ASTPath,
+  Collection,
+  FileInfo,
+  JSXAttribute,
+  JSXOpeningElement,
+  Options,
+} from 'jscodeshift';
+
+import {
+  addTodoToAttribute,
+  getLogger,
+  hasMigrationTodo,
+  insertTodoComment,
+} from '../../../utils/index.js';
+
+type VariantMigrationOptions = {
+  componentNames: string[];
+  variantMapping: Record<string, string>;
+  transformLabel: string;
+  includesTertiarySemanticWarning?: boolean;
+};
+
+type ComponentImports = {
+  localToImported: Map<string, string>;
+  localNames: Set<string>;
+};
+
+function toSourceValue(source: string | null | undefined): string {
+  return typeof source === 'string' ? source : '';
+}
+
+function collectComponentImports(
+  root: Collection<any>,
+  j: API['jscodeshift'],
+  componentNames: string[],
+): ComponentImports {
+  const targetNames = new Set(componentNames);
+  const localToImported = new Map<string, string>();
+  const localNames = new Set<string>();
+
+  root
+    .find(j.ImportDeclaration)
+    .filter((path: any) => toSourceValue(path.value.source.value).startsWith('@coinbase/cds'))
+    .forEach((path: any) => {
+      path.value.specifiers?.forEach((specifier: any) => {
+        if (!j.ImportSpecifier.check(specifier)) {
+          return;
+        }
+
+        const importedName = specifier.imported.name;
+        if (!targetNames.has(importedName)) {
+          return;
+        }
+
+        const localName = specifier.local?.name ?? importedName;
+        localToImported.set(localName, importedName);
+        localNames.add(localName);
+      });
+    });
+
+  return { localToImported, localNames };
+}
+
+function getOpeningElementName(
+  j: API['jscodeshift'],
+  openingElement: JSXOpeningElement,
+): string | null {
+  if (j.JSXIdentifier.check(openingElement.name)) {
+    return openingElement.name.name;
+  }
+
+  return null;
+}
+
+function getAttributeName(j: API['jscodeshift'], attribute: any): string | null {
+  if (!j.JSXAttribute.check(attribute) || !j.JSXIdentifier.check(attribute.name)) {
+    return null;
+  }
+
+  return attribute.name.name;
+}
+
+function createTodoReporter(
+  j: API['jscodeshift'],
+  file: FileInfo,
+  label: string,
+  openingPath: ASTPath<JSXOpeningElement>,
+  fallbackLine?: number,
+) {
+  const logger = getLogger();
+  const openingName = getOpeningElementName(j, openingPath.value) ?? 'Component';
+
+  const hasExistingTodo = () => {
+    if (hasMigrationTodo(openingPath)) {
+      return true;
+    }
+
+    const parentPath = openingPath.parent;
+    if (parentPath && hasMigrationTodo(parentPath as any)) {
+      return true;
+    }
+
+    return false;
+  };
+
+  return (attributePath: ASTPath<JSXAttribute> | null, message: string, details: string) => {
+    if (!hasExistingTodo()) {
+      if (attributePath) {
+        addTodoToAttribute(j, attributePath, { message, context: details });
+      } else {
+        insertTodoComment(j, openingPath, { message, context: details });
+      }
+    }
+
+    logger?.todo(`[${label}] ${message}`, file.path, fallbackLine, `${openingName}: ${details}`);
+  };
+}
+
+function unwrapObjectExpression(j: API['jscodeshift'], value: any): any | null {
+  if (!value) {
+    return null;
+  }
+
+  if (j.ObjectExpression.check(value)) {
+    return value;
+  }
+
+  if (
+    (j.TSAsExpression.check(value) || j.TSTypeAssertion.check(value)) &&
+    j.ObjectExpression.check(value.expression)
+  ) {
+    return value.expression;
+  }
+
+  return null;
+}
+
+function getObjectVariantProperty(j: API['jscodeshift'], objectExpression: any): any | null {
+  const properties = objectExpression.properties ?? [];
+  for (const property of properties) {
+    const isProperty = j.Property.check(property);
+    const isObjectProperty = 'ObjectProperty' in j && (j as any).ObjectProperty.check(property);
+    if (!isProperty && !isObjectProperty) {
+      continue;
+    }
+
+    if (j.Identifier.check(property.key) && property.key.name === 'variant') {
+      return property;
+    }
+
+    if (
+      (j.StringLiteral.check(property.key) || j.Literal.check(property.key)) &&
+      property.key.value === 'variant'
+    ) {
+      return property;
+    }
+  }
+
+  return null;
+}
+
+function remapStringVariantValue(
+  j: API['jscodeshift'],
+  value: any,
+  variantMapping: Record<string, string>,
+): { didChange: boolean; previous?: string; next?: string } {
+  if (!value) {
+    return { didChange: false };
+  }
+
+  if ((j.TSAsExpression.check(value) || j.TSTypeAssertion.check(value)) && value.expression) {
+    const expressionResult = remapStringVariantValue(j, value.expression, variantMapping);
+    if (expressionResult.didChange) {
+      return expressionResult;
+    }
+  }
+
+  if (j.StringLiteral.check(value) || j.Literal.check(value)) {
+    const previous = String(value.value);
+    const next = variantMapping[previous];
+    if (next) {
+      value.value = next;
+      return { didChange: true, previous, next };
+    }
+    return { didChange: false };
+  }
+
+  if (j.JSXExpressionContainer.check(value)) {
+    const expression = value.expression;
+    if (j.StringLiteral.check(expression) || j.Literal.check(expression)) {
+      const previous = String(expression.value);
+      const next = variantMapping[previous];
+      if (next) {
+        expression.value = next;
+        return { didChange: true, previous, next };
+      }
+    }
+  }
+
+  return { didChange: false };
+}
+
+function expressionMentionsVariant(expression: any, variant: string): boolean {
+  const visited = new WeakSet<object>();
+  const stack: any[] = [expression];
+
+  while (stack.length > 0) {
+    const current = stack.pop();
+    if (!current || typeof current !== 'object') {
+      continue;
+    }
+    if (visited.has(current)) {
+      continue;
+    }
+    visited.add(current);
+
+    if ('value' in current && current.value === variant) {
+      return true;
+    }
+
+    for (const child of Object.values(current)) {
+      if (child && typeof child === 'object') {
+        stack.push(child);
+      }
+    }
+  }
+
+  return false;
+}
+
+export function migrateVariantProps(
+  file: FileInfo,
+  api: API,
+  options: Options,
+  migrationOptions: VariantMigrationOptions,
+): string | null {
+  const {
+    componentNames,
+    variantMapping,
+    transformLabel,
+    includesTertiarySemanticWarning = false,
+  } = migrationOptions;
+  const j = api.jscodeshift;
+  const root = j(file.source);
+  const logger = getLogger();
+
+  const imports = collectComponentImports(root, j, componentNames);
+  if (imports.localNames.size === 0) {
+    return null;
+  }
+
+  let hasChanges = false;
+
+  const variableDeclaratorsByName = new Map<string, any>();
+  root.find(j.VariableDeclarator).forEach((path: any) => {
+    if (j.Identifier.check(path.value.id)) {
+      variableDeclaratorsByName.set(path.value.id.name, path.value);
+    }
+  });
+
+  root
+    .find(j.JSXOpeningElement)
+    .filter((path: any) => {
+      const localName = getOpeningElementName(j, path.value);
+      return localName ? imports.localNames.has(localName) : false;
+    })
+    .forEach((openingPath: any) => {
+      const localName = getOpeningElementName(j, openingPath.value);
+      if (!localName) {
+        return;
+      }
+
+      const importedName = imports.localToImported.get(localName) ?? localName;
+      const fallbackLine = openingPath.value.loc?.start.line;
+      const reportTodo = createTodoReporter(j, file, transformLabel, openingPath, fallbackLine);
+
+      openingPath.value.attributes.forEach((attribute: any) => {
+        if (j.JSXAttribute.check(attribute) && getAttributeName(j, attribute) === 'variant') {
+          const attributePath = j(openingPath)
+            .find(j.JSXAttribute, { name: { name: 'variant' } })
+            .at(0)
+            .paths()[0];
+          if (!attributePath) {
+            return;
+          }
+
+          const remapResult = remapStringVariantValue(j, attribute.value, variantMapping);
+          if (remapResult.didChange) {
+            hasChanges = true;
+            logger?.success(
+              `[${transformLabel}] Updated ${importedName} variant: ${remapResult.previous} -> ${remapResult.next}`,
+              file.path,
+              attribute.loc?.start.line,
+            );
+            return;
+          }
+
+          if (!attribute.value || j.JSXExpressionContainer.check(attribute.value)) {
+            const expression = j.JSXExpressionContainer.check(attribute.value)
+              ? attribute.value.expression
+              : null;
+            const containsTertiary = expression
+              ? expressionMentionsVariant(expression, 'tertiary')
+              : false;
+            const tertiaryContext =
+              containsTertiary && includesTertiarySemanticWarning
+                ? ' Dynamic tertiary values need intent review: v9 tertiary no longer matches v8 tertiary visuals; use inverse if old v8 look is intended.'
+                : '';
+
+            reportTodo(
+              attributePath,
+              `${importedName} variant requires manual migration`,
+              `Found dynamic or non-literal variant value.${tertiaryContext} Verify mapping to v9 variants and update manually if needed.`,
+            );
+            hasChanges = true;
+          }
+        }
+
+        if (!j.JSXSpreadAttribute.check(attribute)) {
+          return;
+        }
+
+        const spreadArgument = attribute.argument;
+        let didRewriteObjectVariant = false;
+
+        if (j.Identifier.check(spreadArgument)) {
+          const declarator = variableDeclaratorsByName.get(spreadArgument.name);
+          const objectExpression = unwrapObjectExpression(j, declarator?.init);
+          if (objectExpression) {
+            const variantProperty = getObjectVariantProperty(j, objectExpression);
+            if (variantProperty) {
+              const remapResult = remapStringVariantValue(j, variantProperty.value, variantMapping);
+              if (remapResult.didChange) {
+                didRewriteObjectVariant = true;
+                hasChanges = true;
+                logger?.success(
+                  `[${transformLabel}] Updated spread object variant for ${importedName}: ${remapResult.previous} -> ${remapResult.next}`,
+                  file.path,
+                  variantProperty.loc?.start.line ?? attribute.loc?.start.line,
+                );
+              }
+            }
+          }
+        }
+
+        reportTodo(
+          null,
+          `${importedName} spread props need manual review`,
+          `Found spread props on ${importedName}. Spread values may still contain legacy variant values. Review spread source and flatten/update variant explicitly.${didRewriteObjectVariant ? ' An obvious local object-literal variant was auto-updated, but full spread safety still requires manual verification.' : ''}`,
+        );
+        hasChanges = true;
+      });
+    });
+
+  if (!hasChanges) {
+    return null;
+  }
+
+  return root.toSource(options);
+}
diff --git a/packages/migrator/tsconfig.json b/packages/migrator/tsconfig.json
index 25b1d4a17..53e3c6f11 100644
--- a/packages/migrator/tsconfig.json
+++ b/packages/migrator/tsconfig.json
@@ -7,6 +7,14 @@
   "include": [
     "src/**/*"
   ],
-  "exclude": [],
+  "exclude": [
+    // Keep migrator package typecheck focused on implementation source only.
+    // Transform fixtures intentionally contain example app code patterns that
+    // are validated by Jest transform tests, not by tsc project compilation.
+    "**/__tests__/**",
+    "**/__fixtures__/**",
+    "**/*.test.*",
+    "**/*.spec.*"
+  ],
   "references": []
 }
diff --git a/packages/migrator/tsconfig.spec.json b/packages/migrator/tsconfig.spec.json
new file mode 100644
index 000000000..0a6eba130
--- /dev/null
+++ b/packages/migrator/tsconfig.spec.json
@@ -0,0 +1,17 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "types": [
+      "jest",
+      "node"
+    ]
+  },
+  "include": [
+    "src/**/*.test.ts",
+    "src/**/*.test.tsx",
+    "src/**/*.spec.ts",
+    "src/**/*.spec.tsx",
+    "src/**/__tests__/**/*.ts",
+    "src/**/__tests__/**/*.tsx"
+  ]
+}

From 10dc34cad2dc02a1ddebba7955291719b6c19558 Mon Sep 17 00:00:00 2001
From: Boba <ruikun.hao@coinbase.com>
Date: Fri, 27 Feb 2026 16:02:17 -0600
Subject: [PATCH 5/5] chore: update examples

---
 .../button-variant-mapping/basic-literal.input.tsx             | 2 +-
 .../button-variant-mapping/basic-literal.output.tsx            | 2 +-
 .../button-variant-mapping/dynamic-variant.input.tsx           | 3 ++-
 .../button-variant-mapping/dynamic-variant.output.tsx          | 3 ++-
 .../__fixtures__/button-variant-mapping/spread-props.input.tsx | 2 +-
 .../button-variant-mapping/spread-props.output.tsx             | 2 +-
 6 files changed, 8 insertions(+), 6 deletions(-)

diff --git a/packages/migrator/src/v8-to-v9/transforms/__fixtures__/button-variant-mapping/basic-literal.input.tsx b/packages/migrator/src/v8-to-v9/transforms/__fixtures__/button-variant-mapping/basic-literal.input.tsx
index 3f549d26b..08d5964f3 100644
--- a/packages/migrator/src/v8-to-v9/transforms/__fixtures__/button-variant-mapping/basic-literal.input.tsx
+++ b/packages/migrator/src/v8-to-v9/transforms/__fixtures__/button-variant-mapping/basic-literal.input.tsx
@@ -1,5 +1,5 @@
 import React from 'react';
-// @ts-expect-error -- Fixture intentionally imports Button/IconButton from @coinbase/cds-web to exercise codemod import matching; typings are not validated for fixture sources.
+// @ts-expect-error -- Fixture import mirrors codemod target imports; fixture files are not validating package export typings.
 import { Button, IconButton } from '@coinbase/cds-web';
 
 export function Example() {
diff --git a/packages/migrator/src/v8-to-v9/transforms/__fixtures__/button-variant-mapping/basic-literal.output.tsx b/packages/migrator/src/v8-to-v9/transforms/__fixtures__/button-variant-mapping/basic-literal.output.tsx
index bed17c9c8..d5a77e5a7 100644
--- a/packages/migrator/src/v8-to-v9/transforms/__fixtures__/button-variant-mapping/basic-literal.output.tsx
+++ b/packages/migrator/src/v8-to-v9/transforms/__fixtures__/button-variant-mapping/basic-literal.output.tsx
@@ -1,5 +1,5 @@
 import React from 'react';
-// @ts-expect-error -- Fixture intentionally imports Button/IconButton from @coinbase/cds-web to exercise codemod import matching; typings are not validated for fixture sources.
+// @ts-expect-error -- Fixture import mirrors codemod target imports; fixture files are not validating package export typings.
 import { Button, IconButton } from '@coinbase/cds-web';
 
 export function Example() {
diff --git a/packages/migrator/src/v8-to-v9/transforms/__fixtures__/button-variant-mapping/dynamic-variant.input.tsx b/packages/migrator/src/v8-to-v9/transforms/__fixtures__/button-variant-mapping/dynamic-variant.input.tsx
index 909d2124c..b20450bd2 100644
--- a/packages/migrator/src/v8-to-v9/transforms/__fixtures__/button-variant-mapping/dynamic-variant.input.tsx
+++ b/packages/migrator/src/v8-to-v9/transforms/__fixtures__/button-variant-mapping/dynamic-variant.input.tsx
@@ -1,7 +1,8 @@
 import React from 'react';
-// @ts-expect-error -- Fixture intentionally imports Button/IconButton from @coinbase/cds-web to exercise codemod import matching; typings are not validated for fixture sources.
+// @ts-expect-error -- Fixture import mirrors codemod target imports; fixture files are not validating package export typings.
 import { Button } from '@coinbase/cds-web';
 
+// @ts-expect-error -- Fixture uses unresolved helper to represent a dynamic runtime variant source.
 const variant = getVariant();
 
 export function Example() {
diff --git a/packages/migrator/src/v8-to-v9/transforms/__fixtures__/button-variant-mapping/dynamic-variant.output.tsx b/packages/migrator/src/v8-to-v9/transforms/__fixtures__/button-variant-mapping/dynamic-variant.output.tsx
index 8213ce92a..0b0e9b06d 100644
--- a/packages/migrator/src/v8-to-v9/transforms/__fixtures__/button-variant-mapping/dynamic-variant.output.tsx
+++ b/packages/migrator/src/v8-to-v9/transforms/__fixtures__/button-variant-mapping/dynamic-variant.output.tsx
@@ -1,7 +1,8 @@
 import React from 'react';
-// @ts-expect-error -- Fixture intentionally imports Button/IconButton from @coinbase/cds-web to exercise codemod import matching; typings are not validated for fixture sources.
+// @ts-expect-error -- Fixture import mirrors codemod target imports; fixture files are not validating package export typings.
 import { Button } from '@coinbase/cds-web';
 
+// @ts-expect-error -- Fixture uses unresolved helper to represent a dynamic runtime variant source.
 const variant = getVariant();
 
 export function Example() {
diff --git a/packages/migrator/src/v8-to-v9/transforms/__fixtures__/button-variant-mapping/spread-props.input.tsx b/packages/migrator/src/v8-to-v9/transforms/__fixtures__/button-variant-mapping/spread-props.input.tsx
index c55ff1372..d463cc5a2 100644
--- a/packages/migrator/src/v8-to-v9/transforms/__fixtures__/button-variant-mapping/spread-props.input.tsx
+++ b/packages/migrator/src/v8-to-v9/transforms/__fixtures__/button-variant-mapping/spread-props.input.tsx
@@ -1,5 +1,5 @@
 import React from 'react';
-// @ts-expect-error -- Fixture intentionally imports Button/IconButton from @coinbase/cds-web to exercise codemod import matching; typings are not validated for fixture sources.
+// @ts-expect-error -- Fixture import mirrors codemod target imports; fixture files are not validating package export typings.
 import { IconButton } from '@coinbase/cds-web';
 
 const iconProps = {
diff --git a/packages/migrator/src/v8-to-v9/transforms/__fixtures__/button-variant-mapping/spread-props.output.tsx b/packages/migrator/src/v8-to-v9/transforms/__fixtures__/button-variant-mapping/spread-props.output.tsx
index b500561ce..c2b03a7ca 100644
--- a/packages/migrator/src/v8-to-v9/transforms/__fixtures__/button-variant-mapping/spread-props.output.tsx
+++ b/packages/migrator/src/v8-to-v9/transforms/__fixtures__/button-variant-mapping/spread-props.output.tsx
@@ -1,5 +1,5 @@
 import React from 'react';
-// @ts-expect-error -- Fixture intentionally imports Button/IconButton from @coinbase/cds-web to exercise codemod import matching; typings are not validated for fixture sources.
+// @ts-expect-error -- Fixture import mirrors codemod target imports; fixture files are not validating package export typings.
 import { IconButton } from '@coinbase/cds-web';
 
 const iconProps = {