feat(cli): add explanations to migration prompts (#1270)

## Summary

Closes #1030

When running `vp migrate` interactively, users are prompted with choices
(which agents to use, whether to merge editor configs, whether to
migrate ESLint/Prettier, etc.) but are given no context for why. This PR
adds a brief gray explanation embedded directly in each prompt message
so users understand what they're agreeing to before making a choice.

## Demo

<!-- screenshot here -->

<img width="1451" height="784" alt="スクリーンショット 2026-04-02 17 05 23"
src="https://github.com/user-attachments/assets/92b605e0-037f-4e1d-982b-8219c32d6fe0"
/>

## Test plan

- [x] `vp check --fix` passes
- [x] `pnpm bootstrap-cli && pnpm test` passes (snap tests unaffected —
all new messages are inside `interactive` guards)
- [x] GPG-signed commits

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-authored-by: MK (fengmk2) <fengmk2@gmail.com>

Author: 3 people

packages/cli/src/migration/bin.ts

@@ -75,7 +75,12 @@ function warnLegacyEslintConfig(legacyConfigFile: string) {
 async function confirmEslintMigration(interactive: boolean): Promise<boolean> {
   if (interactive) {
     const confirmed = await prompts.confirm({
-      message: 'Migrate ESLint rules to Oxlint using @oxlint/migrate?',
+      message:
+        'Migrate ESLint rules to Oxlint using @oxlint/migrate?\n  ' +
+        styleText(
+          'gray',
+          "Oxlint is Vite+'s built-in linter — significantly faster than ESLint with compatible rule support. @oxlint/migrate converts your existing rules automatically.",
+        ),
       initialValue: true,
     });
     if (prompts.isCancel(confirmed)) {
@@ -129,7 +134,12 @@ function warnPackageLevelPrettier() {
 async function confirmPrettierMigration(interactive: boolean): Promise<boolean> {
   if (interactive) {
     const confirmed = await prompts.confirm({
-      message: 'Migrate Prettier to Oxfmt?',
+      message:
+        'Migrate Prettier to Oxfmt?\n  ' +
+        styleText(
+          'gray',
+          "Oxfmt is Vite+'s built-in formatter that replaces Prettier with faster performance. Your configuration will be converted automatically.",
+        ),
       initialValue: true,
     });
     if (prompts.isCancel(confirmed)) {
@@ -392,7 +402,12 @@ async function collectMigrationPlan(
   for (const conflict of agentConflicts) {
     if (options.interactive) {
       const action = await prompts.select({
-        message: `Agent instructions already exist at ${conflict.targetPath}.`,
+        message:
+          `Agent instructions already exist at ${conflict.targetPath}.\n  ` +
+          styleText(
+            'gray',
+            'The Vite+ template includes guidance on `vp` commands, the build pipeline, and project conventions.',
+          ),
         options: [
           { label: 'Append', value: 'append' as const, hint: 'Add template content to the end' },
           { label: 'Skip', value: 'skip' as const, hint: 'Leave existing file unchanged' },
@@ -424,7 +439,12 @@ async function collectMigrationPlan(
   for (const conflict of editorConflicts) {
     if (options.interactive) {
       const action = await prompts.select({
-        message: `${conflict.displayPath} already exists.`,
+        message:
+          `${conflict.displayPath} already exists.\n  ` +
+          styleText(
+            'gray',
+            'Vite+ adds editor settings for the built-in linter and formatter. Merge adds new keys without overwriting existing ones.',
+          ),
         options: [
           {
             label: 'Merge',

packages/cli/src/utils/agent.ts

@@ -1,6 +1,7 @@
 import fs from 'node:fs';
 import fsPromises from 'node:fs/promises';
 import path from 'node:path';
+import { styleText } from 'node:util';
 
 import * as prompts from '@voidzero-dev/vite-plus-prompts';
 
@@ -210,7 +211,12 @@ export async function selectAgentTargetPaths({
 
   if (interactive && !agent) {
     const selectedAgents = await prompts.multiselect({
-      message: 'Which agents are you using?',
+      message:
+        'Which agents are you using?\n  ' +
+        styleText(
+          'gray',
+          'Writes an instruction file for each selected agent to help it understand `vp` commands and the project workflow.',
+        ),
       options: AGENTS.map((option) => ({
         label: option.label,
         value: option.id,
@@ -528,7 +534,12 @@ export async function writeAgentInstructions({
         conflictAction = preResolved;
       } else if (interactive) {
         const action = await prompts.select({
-          message: `Agent instructions already exist at ${targetPathToWrite}.`,
+          message:
+            `Agent instructions already exist at ${targetPathToWrite}.\n  ` +
+            styleText(
+              'gray',
+              'The Vite+ template includes guidance on `vp` commands, the build pipeline, and project conventions.',
+            ),
           options: [
             {
               label: 'Append',

packages/cli/src/utils/editor.ts

@@ -1,6 +1,7 @@
 import fs from 'node:fs';
 import fsPromises from 'node:fs/promises';
 import path from 'node:path';
+import { styleText } from 'node:util';
 
 import * as prompts from '@voidzero-dev/vite-plus-prompts';
 
@@ -175,14 +176,19 @@ export async function selectEditor({
       value: option.id,
       hint: option.targetDir,
     }));
-    const noneOption = {
-      label: 'None',
+    const otherOption = {
+      label: 'Other',
       value: null,
       hint: 'Skip writing editor configs',
     };
     const selectedEditor = await prompts.select({
-      message: 'Which editor are you using?',
-      options: [...editorOptions, noneOption],
+      message:
+        'Which editor are you using?\n  ' +
+        styleText(
+          'gray',
+          'Writes editor config files to enable recommended extensions and Oxlint/Oxfmt integrations.',
+        ),
+      options: [...editorOptions, otherOption],
       initialValue: 'vscode',
     });
 
@@ -293,7 +299,12 @@ export async function writeEditorConfigs({
         conflictAction = preResolved;
       } else if (interactive) {
         const action = await prompts.select({
-          message: `${displayPath} already exists.`,
+          message:
+            `${displayPath} already exists.\n  ` +
+            styleText(
+              'gray',
+              `Vite+ adds ${editorConfig.label} settings for the built-in linter and formatter. Merge adds new keys without overwriting existing ones.`,
+            ),
           options: [
             {
               label: 'Merge',