@db-ux/mcp-server 4.7.0-mcp-server-migrate-tool-test-2-0cf8204 → 4.7.0

package/README.md

@@ -91,53 +91,22 @@ This will copy the correct rules for DB UX component usage and design token refe
 - **Check Status:** Look for a green indicator or "db-ux" in your IDE's MCP server list.
 - **Check Logs:** If it doesn't appear, check the MCP output logs in your IDE (e.g., in VS Code: _Output Panel_ → _MCP_ or _MCP Servers_).
 
-### 5. Optimize Amazon Q for this Project (Recommended)
-
-Amazon Q can automatically load the project's `CONTEXT.md` as a persistent system prompt ("Rules") for every session. This means the agent **already knows** the MCP server architecture, all available tools, design token sources, migration workflows, and the v3 component API — without any manual onboarding or repeated context-setting by the developer.
-
-**Why this matters:**
-
-- ✅ Eliminates hallucinations about component names, prop signatures, and token values
-- ✅ The agent follows the correct 6-step migration workflow from the first message
-- ✅ New team members get a fully context-aware AI assistant on day one
-
-**Setup:**
-
-1. Open (or create) the file `~/.aws/amazonq/agents/default.json`
-2. Add the following configuration:
-
-```json
-{
-	"agentInstruction": {
-		"paths": ["CONTEXT.md"]
-	}
-}
-```
-
-3. Place the `CONTEXT.md` file in your project root (it ships with `@db-ux/mcp-server` and is copied by `npx @db-ux/agent-cli`)
-
-> **Note:** The path is resolved relative to the workspace root. Amazon Q / Kiro will read this file at the start of every session and inject it as system-level context for the agent.
-
 ---
 
 ## 🛠 Available AI Tools (Skills)
 
-| Tool                           | Description                                                                                                                                                                                                                                                                                                              |
-| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `list_components`              | Returns all available DB UX component names (e.g. `button`, `input`, `tag`). Call this first to confirm a component exists before using it.                                                                                                                                                                              |
-| `get_component_props`          | Returns the raw TypeScript `model.ts` for a component — all interfaces, prop types, and JSDoc comments.                                                                                                                                                                                                                  |
-| `get_component_details`        | Returns the list of available example names for a component (e.g. `"Variant"`, `"Show Icon Leading"`).                                                                                                                                                                                                                   |
-| `get_example_code`             | Fetches the exact generated source code for a component example in a specific framework (`react`, `angular`, `vue`, `web-components`, or `html`). This is the code the AI adapts — not invents.                                                                                                                          |
-| `get_design_tokens`            | Returns CSS custom properties (`--db-*`) for a token category (`colors`, `spacing`, `typography`, `elevation`, `density`, …). For spacing, elevation, and density, returns **compiled primitive values** (e.g. `0.75rem`, box-shadow strings) instead of raw SCSS. Prevents hardcoded hex values and magic numbers.      |
-| `list_design_token_categories` | Lists all available token categories to pass to `get_design_tokens`.                                                                                                                                                                                                                                                     |
-| `list_icons`                   | Returns all valid DB UX icon names (e.g. `arrow_down`, `chevron_right`, `x_placeholder`). Always call this before using any `icon` prop — never guess a name.                                                                                                                                                            |
-| `docs_search`                  | Searches the DB UX conceptual documentation (guidelines, A11y, migration, ADRs) or component-specific markdown docs. Acts as our Retrieval-Augmented Generation (RAG) engine.                                                                                                                                            |
-| `list_migration_guides`        | Returns all available migration guide names (e.g. `color-migration`, `component-migration`). Call this first before any migration task.                                                                                                                                                                                  |
-| `get_migration_guide`          | Returns the full markdown content of a specific migration guide. Use this to load official package renames, prop changes, and component workarounds before refactoring legacy code.                                                                                                                                      |
-| `verify_migrated_code`         | Saves generated code to a temp file and runs a compiler check (`tsc --noEmit`). Must be called after code generation and before showing code to the user. Returns diagnostics on failure so the AI can self-correct (max 3 attempts).                                                                                    |
-| `get_component_visual`         | Returns a downsampled screenshot (max 800×800 px, JPEG q75, bilinear interpolation) of a DB UX component or page layout as a Base64-encoded image. Use sparingly — only when visual context is needed for complex layouts, z-index dependencies, or visual hierarchies.                                                  |
-| `analyze_v2_migration`         | **Call FIRST when migrating a file.** Scans a source file for DB UI v2 patterns (`<cmp-*>`, `<elm-*>`, `<rea-*>` tags, `db-color-*` tokens, legacy icon names) and returns a JSON report with exact line numbers and deterministic migration suggestions from the official guides. No LLM guessing needed.               |
-| `scaffold_component`           | Generates a DB UX-conformant component skeleton for a specified framework (`react`, `angular`, `vue`, `web-components`, or `html`). Creates all boilerplate files (component, template, SCSS) with correct `@db-ux/*` imports and SCSS foundation `@use` directives. The developer only needs to fill in business logic. |
+| Tool                           | Description                                                                                                                                                                                     |
+| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `list_components`              | Returns all available DB UX component names (e.g. `button`, `input`, `tag`). Call this first to confirm a component exists before using it.                                                     |
+| `get_component_props`          | Returns the raw TypeScript `model.ts` for a component — all interfaces, prop types, and JSDoc comments.                                                                                         |
+| `get_component_details`        | Returns the list of available example names for a component (e.g. `"Variant"`, `"Show Icon Leading"`).                                                                                          |
+| `get_example_code`             | Fetches the exact generated source code for a component example in a specific framework (`react`, `angular`, `vue`, `web-components`, or `html`). This is the code the AI adapts — not invents. |
+| `get_design_tokens`            | Returns CSS custom properties (`--db-*`) and SCSS variables (`$db-*`) for a token category (`colors`, `spacing`, `typography`, …). Prevents hardcoded hex values and magic numbers.             |
+| `list_design_token_categories` | Lists all available token categories to pass to `get_design_tokens`.                                                                                                                            |
+| `list_icons`                   | Returns all valid DB UX icon names (e.g. `arrow_down`, `chevron_right`, `x_placeholder`). Always call this before using any `icon` prop — never guess a name.                                   |
+| `docs_search`                  | Searches the DB UX conceptual documentation (guidelines, A11y, migration, ADRs) or component-specific markdown docs. Acts as our Retrieval-Augmented Generation (RAG) engine.                   |
+| `list_migration_guides`        | Returns all available migration guide names (e.g. `db-ui-color-migration`, `db-ui-component-migration`). Call this first before any migration task.                                             |
+| `get_migration_guide`          | Returns the full markdown content of a specific migration guide. Use this to load official package renames, prop changes, and component workarounds before refactoring legacy code.             |
 
 ### Example: fetching a React button example
 
@@ -148,8 +117,6 @@ get_component_details    → lists ["Density", "Variant", "Show Icon Leading", .
 get_example_code         → returns show-icon-leading.example.tsx source
 list_icons               → confirms "arrow_right" is a valid icon name
 get_design_tokens        → returns --db-spacing-fixed-md for layout
-get_component_visual     → (optional) returns a downsampled screenshot for visual reference
-verify_migrated_code     → runs tsc --noEmit on generated code, returns ✅ or diagnostics
 ```
 
 ---
@@ -174,78 +141,10 @@ Performs a strict multi-layered QA, accessibility, and DB UX compliance audit on
 
 ### `migrate_component` (Legacy Refactoring)
 
-Transforms legacy UI code (e.g., Bootstrap, native HTML, DB UI v1/v2) into the modern DB UX v3 architecture. This is the most complex prompt — it orchestrates **12 different MCP tools** across 5 mandatory steps, including a compiler-verified self-correction loop.
-
-**Parameters:**
-
-| Parameter          | Required | Description                                                                                                            |
-| ------------------ | -------- | ---------------------------------------------------------------------------------------------------------------------- |
-| `legacy_code`      | Yes      | The outdated source code to migrate (DB UI, Bootstrap, raw HTML/CSS). Max 10,000 chars                                 |
-| `source_context`   | Yes      | Origin of the legacy code: `db-ui-v1`, `db-ui-v2`, `db-ux-v1`, `db-ux-v2`, `db-ux-v3`, `bootstrap-4`, or `native-html` |
-| `target_framework` | Yes      | Target framework: `react`, `angular`, `vue`, `web-components`, or `html`                                               |
-
-**Full workflow (5 mandatory steps):**
-
-```text
-┌──────────────────────────────────────────────────────────────────┐
-│ STEP 0: FILE SCAN (NEW — deterministic, no guessing)             │
-│  analyze_v2_migration → JSON report with line numbers,           │
-│  v2 patterns, and migration suggestions                          │
-├──────────────────────────────────────────────────────────────────┤
-│ STEP 1: MIGRATION ANALYSIS                                       │
-│  list_migration_guides → get_migration_guide → docs_search       │
-│  Output: Legacy Element → DB UX v3 Component mapping table       │
-├──────────────────────────────────────────────────────────────────┤
-│ STEP 2: COMPONENT DISCOVERY & PROPS RETRIEVAL                    │
-│  list_components → get_component_props → get_component_details   │
-│  → get_example_code → get_design_tokens → list_icons             │
-│  → get_component_visual (optional, for layout uncertainty)       │
-├──────────────────────────────────────────────────────────────────┤
-│ STEP 3: CODE GENERATION                                          │
-│  Generates complete migrated code (NOT shown to user yet)        │
-├──────────────────────────────────────────────────────────────────┤
-│ STEP 4: CODE VERIFICATION & SELF-CORRECTION (mandatory)          │
-│  verify_migrated_code → fix errors → retry (max 3 attempts)     │
-│  ⚠️ Only for react, angular, vue — skipped for html/wc          │
-├──────────────────────────────────────────────────────────────────┤
-│ STEP 5: FINAL OUTPUT                                             │
-│  ✅ VERIFIED or ⚠️ WARNING with remaining diagnostics            │
-└──────────────────────────────────────────────────────────────────┘
-```
-
-**Step-by-step details:**
-
-1. **Migration Analysis** — Calls `list_migration_guides` then `get_migration_guide` to load official migration rules (package renames, prop changes, removed components). Calls `docs_search` for component-specific migration docs. Produces a mapping table: Legacy Element → DB UX v3 Component → Rationale.
-2. **Component Discovery & Props Retrieval** — Calls `list_components` to verify every mapped component exists. For each: `get_component_props` (TypeScript API), `get_component_details` (examples), `get_example_code` (canonical source to adapt). Calls `get_design_tokens` to replace hardcoded colors/spacing. Calls `list_icons` to verify icon names. Optionally calls `get_component_visual` when uncertain about layout structures.
-3. **Code Generation** — Generates the complete migrated code with correct `@db-ux/*` imports, verified design tokens, and verified icon names. **Does NOT output this to the user yet.**
-4. **Code Verification & Self-Correction** — Passes the generated code to `verify_migrated_code` which runs `tsc --noEmit`. If compiler errors are returned, the AI analyzes diagnostics, fixes the code, and retries — up to **3 attempts maximum**. This step only applies to `react`, `angular`, and `vue` targets. For `web-components` and `html`, it is skipped.
-5. **Final Output** — Presents the result in three sections: "Migration Analysis" (mapping table + guide references), "Migrated Code" (marked ✅ VERIFIED on success, or ⚠️ WARNING with remaining diagnostics), and "Accessibility Statement" (WCAG 2.2 AA compliance confirmation).
-
-**Available migration guides:**
-
-| Guide                 | Covers                                                             |
-| --------------------- | ------------------------------------------------------------------ |
-| `component-migration` | Component renames, prop changes, removed/planned components        |
-| `color-migration`     | Full color token mapping (old → new `--db-*` tokens)               |
-| `icon-migration`      | Icon name mapping (e.g. `account` → `person`, `delete` → `bin`)    |
-| `general-migration`   | Typography tokens, spacing tokens, elevation, inline style removal |
-
-**Example: migrating a DB UI v2 React component**
-
-Trigger the prompt with these parameters:
-
-- `legacy_code`: your old React component source code
-- `source_context`: `db-ui-v2`
-- `target_framework`: `react`
+Transforms legacy UI code (e.g., Bootstrap, native HTML, DB UI v1/v2) into the modern DB UX v3/v4 architecture.
 
-The AI will then autonomously:
-
-1. Load `component-migration`, `color-migration`, `icon-migration`, and `general-migration`
-2. Map every legacy element (e.g. `variant="brand-primary"` → `variant="brand"`, `icon="search"` → `icon="magnifying_glass"`)
-3. Fetch the exact generated React example code for each component and adapt it
-4. Replace all hardcoded `#ec0016` / `margin: 15px` values with `--db-*` design tokens
-5. Compile the result via `verify_migrated_code` and self-correct up to 3 times
-6. Present the verified code with a migration analysis and accessibility statement
+- **Parameters:** `legacy_code`, `source_context`, `target_framework`.
+- **Behavior:** Calls `list_migration_guides` and `get_migration_guide` to dynamically load the relevant migration docs before mapping any component. This ensures all package renames, prop changes, and missing-component workarounds are sourced from the official guides rather than hardcoded knowledge.
 
 ### `audit_accessibility` (Deep A11y Scan)
 
@@ -271,7 +170,7 @@ Because `model.ts`, showcase files, and framework example source files are **not
 ```text
 manifest.json
 ├── icons[]                          — icon names from packages/foundations/src/all-icons.ts
-├── tokens{}                         — SCSS design tokens mapped by category (colors, typography, animation, transitions)
+├── tokens{}                         — raw SCSS design tokens mapped by category
 ├── docs{}                           — conceptual markdown documentation
 └── components{}
     └── {componentName}
@@ -304,16 +203,10 @@ This means the same binary works for:
 - **Design system developers** working inside the monorepo (always up-to-date, live files)
 - **Consumer teams** running `npx @db-ux/mcp-server` (self-contained, no monorepo needed)
 
-> **Note on compiled tokens:** For `spacing`, `elevation`, and `density`, the tool reads compiled CSS/SCSS files with concrete primitive values (not raw SCSS with `@each` loops). In the monorepo it reads directly from `packages/foundations/`; in standalone mode it falls back to `assets/tokens/` (populated by the `prebuild` step).
-
 ### Directory structure
 
 ```text
 packages/mcp-server/
-├── assets/
-│   ├── migration/          # Migration guides (copied from docs/migration/db-ui/ by prebuild)
-│   ├── tokens/             # Compiled token files (copied from foundations by prebuild)
-│   └── visuals/            # Curated reference images (shipped with npm package)
 ├── src/
 │   ├── index.ts            # Bootstrap — connects transport, registers tools/prompts
 │   ├── server.ts           # McpServer singleton and lifecycle handlers
@@ -333,6 +226,67 @@ packages/mcp-server/
 
 ---
 
+## ⚠️ Defensive Rules for AI
+
+These are the **Golden Rules** the AI agent must follow when using this server. They are enforced by the workflow rules file and should be treated as hard constraints, not suggestions.
+
+### NEVER use native HTML elements when a DB UX component exists
+
+```tsx
+// ❌ WRONG
+<button style="background: #d40000; padding: 8px 16px">Save</button>
+<input type="text" placeholder="Search..." />
+<div style="display: flex; gap: 16px">...</div>
+
+// ✅ CORRECT
+<DBButton variant="brand">Save</DBButton>
+<DBInput placeholder="Search..." />
+<DBStack>...</DBStack>
+```
+
+| Native element   | DB UX replacement                |
+| ---------------- | -------------------------------- |
+| `<button>`       | `DBButton`                       |
+| `<input>`        | `DBInput`                        |
+| `<select>`       | `DBSelect`                       |
+| `<a>`            | `DBLink`                         |
+| `<textarea>`     | `DBTextarea`                     |
+| `<div>` (layout) | `DBStack`, `DBSection`, `DBCard` |
+
+### NEVER use hardcoded colors or magic spacing values
+
+```scss
+// ❌ WRONG
+.my-element {
+	color: #ec0016;
+	margin: 15px;
+	gap: 8px;
+}
+
+// ✅ CORRECT — values retrieved via get_design_tokens
+.my-element {
+	color: var(--db-color-red-500);
+	margin: var(--db-spacing-fixed-sm);
+	gap: var(--db-spacing-fixed-xs);
+}
+```
+
+### ALWAYS verify props and icon names via MCP tools
+
+```tsx
+// ❌ WRONG — icon name invented, prop API assumed
+<DBButton icon="chevronRight" size="large">Next</DBButton>
+
+// ✅ CORRECT — icon name from list_icons, props from get_component_props
+<DBButton icon="chevron_right" size="small">Next</DBButton>
+```
+
+### ALWAYS call get_example_code before writing component usage
+
+The generated examples are the canonical reference. Adapt them — do not rewrite component usage from scratch.
+
+---
+
 ## 📦 Build Command
 
 The server is built as part of the `@db-ux/mcp-server` package:
@@ -358,17 +312,42 @@ npm run dev     # runs src/index.ts directly via tsx (monorepo mode, live files)
 
 ---
 
+## ❓ Troubleshooting
+
+### "Unknown Configuration Setting" in VS Code
+
+If you see a yellow squiggle/warning in your `settings.json`, this is expected. Standard VS Code does not natively recognize the `mcp` key yet. As long as your MCP client (like the Claude extension or Cursor) is active, the server will work perfectly.
+
+### Server fails to start from the monorepo root (Local Development)
+
+If you are developing or testing the MCP server directly from within the DB UX monorepo, the global `npx` command might fail due to npm workspace resolution. In this case, bypass `npx` and point your IDE directly to the local built file.
+
+**Fallback IDE Configuration (VS Code/IntelliJ):**
+Instead of using `npx`, use `node` and point it to the local build path (ensure you have run `npm run build` in the `mcp-server` directory first):
+
+```json
+"db-ux": {
+	"command": "node",
+	"disabled": false,
+	"timeout": 60000,
+	"args": ["packages/mcp-server/dist/index.js"]
+}
+```
+
+_Alternatively, you can change your IDE's working directory for the MCP server to `packages/mcp-server`._
+
+---
+
 ## 🛡️ Security & Compliance
 
 This MCP server operates under a strict, zero-trust security model to prevent malicious AI behavior or accidental system damage.
 
-- **Strict Read-Only Sandbox:** The server has zero write-permissions for design system files. All imports from `node:fs` for component data are strictly read-only (`readFile`, `readdir`). The only exception is the `verify_migrated_code` tool, which writes a temporary file under the current working directory (`process.cwd()`, typically the repo/workspace root) and deletes it in a `finally` block after the check completes. Shell execution via `child_process.exec` is scoped exclusively to this tool and limited to running `tsc --noEmit` on the temporary file with a 30-second timeout.
+- **Strict Read-Only Sandbox:** The server has zero write-permissions. All imports from `node:fs` are strictly read-only (`readFile`, `readdir`). Modules like `child_process` (for shell execution) or file mutation methods (`writeFile`, `unlink`) are completely banned.
 - **Path Traversal Protection (Jailbreak Prevention):** All file and directory accesses (e.g., resolving component names) pass through a cryptographic-style path resolver. The server mathematically guarantees that no file reads can escape the allowed `REPO_ROOT` or `COMPONENTS_DIR` (blocking `../../etc/passwd` attacks).
 - **DoS & Context Window Protection:** To prevent LLMs from crashing or generating massive API billing spikes due to context window overflows, strict token limiters are enforced:
     - File reads are truncated at **20,000 characters**.
     - JSON arrays (like component or icon lists) are truncated at **20,000 characters**.
     - Directory scans are hard-limited to a maximum of **10 files**.
-- **Image Downsampling (Token Optimization):** The `get_component_visual` tool downsamples images to a maximum of **800×800 px** and encodes them as **JPEG at quality 75** before Base64 encoding. This keeps the payload well under the 100 000-character MCP client limit. Images are served exclusively from the curated `assets/visuals/` directory — path traversal protection applies here as well.
 
 ---
 
@@ -389,52 +368,18 @@ npm run build
 
 Run the following command from the `packages/mcp-server/` directory:
 
-> **Note:** The Inspector UI runs on **port 6274**, the proxy on **port 6277**. If either port is already in use, free it first: `lsof -ti :6274 -ti :6277 | xargs kill -9`
+> **Note:** Port 5173 is the default for Vite and Playwright. To avoid conflicts if those are already running, you can specify a different port using the `--port` flag.
 
 ```bash
-npx @modelcontextprotocol/inspector --transport stdio node dist/index.js
-```
-
-The Inspector prints a URL with a session token to the terminal, e.g.:
-
-```text
-🔍 MCP Inspector is up and running at http://localhost:6274/?MCP_PROXY_AUTH_TOKEN=<token>
+npx @modelcontextprotocol/inspector --port 5178 node build/index.js
 ```
 
-Open that **full URL including the token** in your browser — the token is required for authentication.
-
 ### Step-by-step workflow
 
 1. Run the command above — the Inspector starts a local web server
-2. Open the **full URL with token** printed in the terminal (e.g. `http://localhost:6274/?MCP_PROXY_AUTH_TOKEN=...`)
-3. Click **"Connect"** to establish the stdio connection to the server
-4. Navigate to the **"Tools"** tab to call individual tools (e.g. `list_components`, `get_component_visual`) and inspect their responses
-5. Navigate to the **"Prompts"** tab to browse and execute interactive prompts like `scaffold_page`
+2. Open the browser tab it prints (e.g., **<http://localhost:5178>**)
+3. Navigate to the **"Prompts"** tab to browse and execute interactive prompts like `scaffold_page`
+4. Navigate to the **"Tools"** tab to call individual tools (e.g. `list_components`, `get_example_code`) and inspect their responses
+5. Use the **"Resources"** tab to verify any static resources exposed by the server
 
 > **Tip:** The Inspector is framework- and IDE-agnostic. It communicates with the server over stdio exactly as a real MCP client would, making it the most reliable way to catch issues before they surface in an AI agent session.
-
----
-
-## ❓ Troubleshooting
-
-### "Unknown Configuration Setting" in VS Code
-
-If you see a yellow squiggle/warning in your `settings.json`, this is expected. Standard VS Code does not natively recognize the `mcp` key yet. As long as your MCP client (like the Claude extension or Cursor) is active, the server will work perfectly.
-
-### Server fails to start from the monorepo root (Local Development)
-
-If you are developing or testing the MCP server directly from within the DB UX monorepo, the global `npx` command might fail due to npm workspace resolution. In this case, bypass `npx` and point your IDE directly to the local built file.
-
-**Fallback IDE Configuration (VS Code/IntelliJ):**
-Instead of using `npx`, use `node` and point it to the local build path (ensure you have run `npm run build` in the `mcp-server` directory first):
-
-```json
-"db-ux": {
-	"command": "node",
-	"disabled": false,
-	"timeout": 60000,
-	"args": ["packages/mcp-server/dist/index.js"]
-}
-```
-
-_Alternatively, you can change your IDE's working directory for the MCP server to `packages/mcp-server`._

package/agent/_instructions.md

@@ -29,14 +29,10 @@ Or add it to your MCP client config:
 4. `docs_search` — search guidelines, accessibility docs, or component-specific documentation if needed
 5. `get_example_code` — fetch the real generated code for the target framework
 6. `list_design_token_categories` — get available token categories if unsure which to query
-7. `get_design_tokens` — retrieve spacing, elevation, density, color, and typography tokens
+7. `get_design_tokens` — retrieve spacing, color, and typography tokens
 8. `list_icons` — look up the exact icon name before using any icon prop
 9. `list_migration_guides` — list all available migration guides before any migration task
 10. `get_migration_guide` — load the full content of a specific migration guide
-11. `verify_migrated_code` — after generating migrated code, pass the full code string and framework to this tool for a compiler check. Fix errors and retry (max 3 attempts) before presenting code to the user
-12. `get_component_visual` — _(optional, use sparingly)_ if you need visual context for complex layouts, z-index dependencies, or visual hierarchies, call this tool with the component or layout name to receive a downsampled screenshot
-13. `analyze_v2_migration` — **call FIRST when migrating a file.** Scans a source file for v2 patterns (`<cmp-*>`, `<elm-*>`, `db-color-*`, legacy icons) and returns a JSON report with line numbers and deterministic suggestions. Use this before any code generation.
-14. `scaffold_component` — generates a DB UX-conformant component skeleton for a specified framework. Creates all boilerplate files with correct `@db-ux/*` imports and SCSS foundation `@use` directives.
 
 ### DON'Ts — these are hard violations:
 
@@ -45,8 +41,6 @@ Or add it to your MCP client config:
 - **NEVER** hardcode color values (`#d40000`, `rgb(...)`) — use design tokens exclusively
 - **NEVER** write inline styles (`style="margin: 15px"`)
 - **NEVER** invent or guess icon names — always call `list_icons` first
-- **NEVER** output migrated code to the user without calling `verify_migrated_code` first — the self-correction loop (max 3 attempts) is mandatory
-- **NEVER** use `// @ts-nocheck`, `// @ts-ignore`, `// @ts-expect-error`, `eslint-disable`, or any other compiler/linter bypass directive to "fix" errors — solve the underlying issue instead
 
 ### DOs:
 
@@ -59,17 +53,6 @@ Or add it to your MCP client config:
 </div>
 ```
 
-### Migration workflow (MANDATORY when the user asks to migrate, refactor, or upgrade legacy code):
-
-When the user asks you to migrate, refactor, or upgrade code from DB UI, Bootstrap, native HTML, or any older version to DB UX v3, you **MUST** follow this exact 5-step workflow — do NOT skip any step:
-
-1. **File Scan** — Call `analyze_v2_migration` with the file path. This returns a deterministic JSON report of all v2 patterns (components, colors, icons) with line numbers and suggestions. Use this as your migration checklist.
-2. **Migration Analysis** — Call `list_migration_guides`, then `get_migration_guide` for each relevant guide. Call `docs_search` for component-specific migration docs. Produce a mapping table: Legacy Element → DB UX v3 Component → Rationale.
-3. **Component Discovery & Props Retrieval** — Call `list_components` to verify every mapped component. For each: `get_component_props`, `get_component_details`, `get_example_code`. Call `get_design_tokens` to replace hardcoded values. Call `list_icons` to verify icon names. Optionally call `get_component_visual` for layout uncertainty.
-4. **Code Generation** — Generate the complete migrated code. Do **NOT** show it to the user yet.
-5. **Code Verification (MANDATORY for react/angular/vue)** — Call `verify_migrated_code`. If errors are returned, fix and retry (max 3 attempts). For `web-components` and `html` targets, skip this step.
-6. **Final Output** — Present: "Migration Analysis" (mapping table), "Migrated Code" (✅ VERIFIED or ⚠️ WARNING with diagnostics), "Accessibility Statement".
-
 ---
 
 ## Available AI Workflows (Prompts)
@@ -94,7 +77,6 @@ Generates the initial structure of a complete web page or complex module. Enforc
 2. **Component Discovery** — Calls `list_components` to verify every planned block maps to a DB UX component. Reports missing components instead of falling back to native HTML
 3. **Props & Examples** — For each component: `get_component_props` → `get_component_details` → `get_example_code` with the target framework
 4. **Token & Asset Validation** — `list_design_token_categories` → `get_design_tokens` for needed categories, `list_icons` for any icon props
-5. **Visual Validation (optional)** — If uncertain about layout structure or visual hierarchy, call `get_component_visual` for a reference screenshot
 
 **Output structure:**
 
@@ -131,7 +113,7 @@ Performs a strict multi-layered QA, accessibility, and DB UX compliance audit on
 
 ### `migrate_component` — Legacy Refactoring
 
-Transforms legacy UI code (e.g. Bootstrap, native HTML, DB UI) into the modern DB UX architecture. Includes a **mandatory code verification step** before presenting results.
+Transforms legacy UI code (e.g. Bootstrap, native HTML, DB UI) into the modern DB UX architecture.
 
 **Parameters:**
 
@@ -143,17 +125,16 @@ Transforms legacy UI code (e.g. Bootstrap, native HTML, DB UI) into the modern D
 
 **Workflow:**
 
-1. **Migration Analysis** — Calls `list_migration_guides` then `get_migration_guide` for relevant versions. Studies package renames, missing components, prop changes
-2. **Component Discovery & Props Retrieval** — Calls `list_components`, `get_component_props`, `get_component_details`, and `get_example_code` to verify modern equivalents. Calls `get_design_tokens` to replace legacy CSS variables or hardcoded values. Calls `list_icons` for any icon references. Optionally calls `get_component_visual` when uncertain about layout structures or visual hierarchies
-3. **Code Generation** — Generates the complete migrated component code. **Does NOT output this to the user yet**
-4. **Code Verification & Self-Correction (MANDATORY)** — Calls `verify_migrated_code` with the generated code and framework. If the tool returns compiler errors, the AI analyzes the diagnostics, fixes the code, and retries. This loop runs for a **maximum of 3 attempts**. If verification still fails after 3 attempts, the AI presents the code with a prominent ⚠️ warning block containing the remaining errors
-5. **Final Output** — Presents the verified code (✅ on success, ⚠️ with diagnostics on failure)
+1. **Knowledge Acquisition** — Calls `list_migration_guides` then `get_migration_guide` for relevant versions. Studies package renames, missing components, prop changes
+2. **Asset Scanning** — Scans for color references (CSS classes, hex values, legacy `--db-color-*` variables) and icon references. Loads `color-migration` and `icon-migration` guides as sole source of truth. Flags any values not found in the tables
+3. **DB UX Mapping** — Calls `list_components`, `get_component_props`, and `get_example_code` to verify modern equivalents
+4. **Token Migration** — Calls `get_design_tokens` to replace legacy CSS variables, utility classes, or hardcoded values
 
 **Output structure:**
 
 1. "Migration Analysis" — Maps each legacy element to its modern replacement, referencing migration guide rules
-2. "Migrated Code" — Fully migrated, production-ready code with correct `@db-ux/*` imports. Marked ✅ VERIFIED or ⚠️ WARNING with remaining diagnostics
-3. "Accessibility Statement" — Confirmation of WCAG 2.2 AA compliance through the selected DB UX components
+2. "Refactored Code" — Fully migrated, production-ready code with correct `@db-ux/*` imports
+3. "Actionable Post-Migration Notes" — Behavioral shifts, ARIA states to verify, colors/icons not found in migration tables
 
 ### `audit_accessibility` — Deep A11y Scan