feat(agents-md): support for migration docs (#175)

* feat: agents-md for migration docs

* fix(agents-md): parse fumadocs include tags

Author: Peterl561

README.md

@@ -473,14 +473,15 @@ heroui agents-md [options]
 #### Features
 
 > 1. Downloads latest HeroUI documentation from the `v3` branch
-> 2. Supports both React and Native documentation
-> 3. Generates separate sections for React or Native in the markdown file
+> 2. Supports React, Native, and Migration (v2→v3) documentation
+> 3. Generates a section for the selected library (React, Native, or Migration) in the markdown file
 > 4. Automatically adds `.heroui-docs/` to `.gitignore`
 
 #### Agents-md Options
 
-- `--react` [boolean] Include only React docs
-- `--native` [boolean] Include only Native docs
+- `--react` [boolean] Include React docs only (one library at a time)
+- `--native` [boolean] Include Native docs only
+- `--migration` [boolean] Include HeroUI v2 to v3 migration docs only
 - `--output <file>` [string] Target file path (e.g., `AGENTS.md`, `CLAUDE.md`)
 - `--ssh` [boolean] Use SSH instead of HTTPS for git clone
 
@@ -504,10 +505,10 @@ Download Native docs:
 heroui agents-md --native --output CLAUDE.md
 ```
 
-Download both React and Native docs:
+Download migration docs (v2→v3):
 
 ```bash
-heroui agents-md --react --native --output AGENTS.md
+heroui agents-md --migration --output AGENTS.md
 ```
 
 Use SSH for cloning (useful if HTTPS fails):
@@ -523,7 +524,8 @@ heroui agents-md --react --ssh --output AGENTS.md
 3. **Injects into Markdown**: Injects the index into your specified markdown file (e.g., `AGENTS.md`) with special markers:
    - `<!-- HEROUI-REACT-AGENTS-MD-START -->` / `<!-- HEROUI-REACT-AGENTS-MD-END -->` for React docs
    - `<!-- HEROUI-NATIVE-AGENTS-MD-START -->` / `<!-- HEROUI-NATIVE-AGENTS-MD-END -->` for Native docs
-4. **Preserves Sections**: When updating one library, the other library's section is preserved
+   - `<!-- HEROUI-MIGRATION-AGENTS-MD-START -->` / `<!-- HEROUI-MIGRATION-AGENTS-MD-END -->` for Migration docs
+4. **Single library**: Only one of React, Native, or Migration can be selected at a time
 
 #### File Structure
 
@@ -532,8 +534,9 @@ After running the command, you'll have:
 ```
 your-project/
 ├── .heroui-docs/          # Downloaded documentation (gitignored)
-│   ├── react/            # React documentation files
-│   └── native/           # Native documentation files (if selected)
+│   ├── react/            # React documentation files (if selected)
+│   ├── native/           # Native documentation files (if selected)
+│   └── migration/        # Migration docs (v2→v3, if selected)
 ├── AGENTS.md             # Your markdown file with injected index
 └── .gitignore            # Updated to include .heroui-docs/
 ```

src/actions/docs-action.ts

@@ -10,6 +10,7 @@ import {
   buildDocTree,
   collectDemoFiles,
   collectDocFiles,
+  collectMigrationDocFiles,
   ensureGitignoreEntry,
   generateHerouiMdIndex,
   getHerouiVersions,
@@ -25,6 +26,13 @@ import {compareVersions} from 'src/scripts/helpers';
 
 const DOCS_DIR_NAME = '.heroui-docs';
 
+function formatSelectionText(selection: DocSelection): string {
+  if (selection === 'react') return 'HeroUI React v3';
+  if (selection === 'native') return 'HeroUI Native';
+
+  return 'HeroUI Migration (v2→v3)';
+}
+
 function formatSize(bytes: number): string {
   if (bytes < 1024) return `${bytes} B`;
   const kb = bytes / 1024;
@@ -84,7 +92,7 @@ function validateRequirements(cwd: string, selection: DocSelection): ValidationR
     }
 
     // For React docs: Check React >= 19.0.0
-    if (selection === 'react' || selection === 'both') {
+    if (selection === 'react') {
       const reactVersion = allDeps.react;
 
       if (reactVersion) {
@@ -172,19 +180,23 @@ export async function docsAction(options: DocsOptions) {
   try {
     // Mode logic:
     // 1. No flags → autodetect package, prompt only if neither found (or if both found)
-    // 2. Library flags (--react, --native) → use that selection, prompt for output file if --output not provided
+    // 2. Library flags (--react, --native, --migration) → use that selection, prompt for output file if --output not provided
     // 3. --output alone → autodetect package, use provided output file
 
     let selection: DocSelection;
     let outputFiles: string[] | undefined;
 
-    // Determine selection from flags
-    if (options.react && options.native) {
-      selection = 'both';
-    } else if (options.react) {
-      selection = 'react';
-    } else if (options.native) {
-      selection = 'native';
+    // Determine selection from flags (only one library at a time)
+    const flagCount = [options.react, options.native, options.migration].filter(Boolean).length;
+
+    if (flagCount > 1) {
+      throw new ValidationError(
+        'Only one library option is supported at a time. Use --react, --native, or --migration (not in combination).'
+      );
+    }
+
+    if (options.react || options.native || options.migration) {
+      selection = options.migration ? 'migration' : options.native ? 'native' : 'react';
     } else {
       // Autodetect installed packages
       const {hasNative, hasReact} = detectInstalledPackages(cwd);
@@ -194,18 +206,21 @@ export async function docsAction(options: DocsOptions) {
         if (options.output) {
           selection = await promptForLibrarySelection(false);
         } else {
-          const promptedOptions = await promptForOptions();
+          const promptedOptions = await promptForOptions(false);
 
           selection = promptedOptions.selection;
           outputFiles = promptedOptions.targetFiles;
         }
       } else if (hasReact) {
+        // Only React found - use it automatically
         selection = 'react';
         Logger.log(chalk.dim('Detected @heroui/react, using HeroUI React v3 docs'));
       } else if (hasNative) {
+        // Only Native found - use it automatically
         selection = 'native';
         Logger.log(chalk.dim('Detected heroui-native, using HeroUI Native docs'));
       } else {
+        // Neither found - prompt for selection with warning
         if (options.output) {
           selection = await promptForLibrarySelection(true);
         } else {
@@ -242,12 +257,7 @@ export async function docsAction(options: DocsOptions) {
 
     const docsPath = path.join(cwd, DOCS_DIR_NAME);
 
-    const selectionText =
-      selection === 'both'
-        ? 'HeroUI React v3 and HeroUI Native'
-        : selection === 'react'
-          ? 'HeroUI React v3'
-          : 'HeroUI Native';
+    const selectionText = formatSelectionText(selection);
 
     Logger.log(`\nDownloading ${selectionText} documentation to ${chalk.cyan(DOCS_DIR_NAME)}...`);
 
@@ -265,9 +275,10 @@ export async function docsAction(options: DocsOptions) {
     // Collect and build trees for selected docs
     let reactSections: ReturnType<typeof buildDocTree> | undefined;
     let nativeSections: ReturnType<typeof buildDocTree> | undefined;
+    let migrationSections: ReturnType<typeof buildDocTree> | undefined;
     let reactDemoFiles: {relativePath: string}[] | undefined;
 
-    if (selection === 'react' || selection === 'both') {
+    if (selection === 'react') {
       const reactDocsPath = path.join(docsPath, 'react');
 
       if (fs.existsSync(reactDocsPath)) {
@@ -276,15 +287,14 @@ export async function docsAction(options: DocsOptions) {
         reactSections = buildDocTree(reactDocFiles);
       }
 
-      // Collect demo files
       const reactDemosPath = path.join(docsPath, 'react', 'demos');
 
       if (fs.existsSync(reactDemosPath)) {
         reactDemoFiles = collectDemoFiles(reactDemosPath);
       }
     }
 
-    if (selection === 'native' || selection === 'both') {
+    if (selection === 'native') {
       const nativeDocsPath = path.join(docsPath, 'native');
 
       if (fs.existsSync(nativeDocsPath)) {
@@ -294,10 +304,20 @@ export async function docsAction(options: DocsOptions) {
       }
     }
 
-    const reactDocsLinkPath =
-      selection === 'react' || selection === 'both' ? `./${DOCS_DIR_NAME}/react` : undefined;
-    const nativeDocsLinkPath =
-      selection === 'native' || selection === 'both' ? `./${DOCS_DIR_NAME}/native` : undefined;
+    if (selection === 'migration') {
+      const migrationDocsPath = path.join(docsPath, 'migration');
+
+      if (fs.existsSync(migrationDocsPath)) {
+        const migrationDocFiles = collectMigrationDocFiles(migrationDocsPath);
+
+        migrationSections = buildDocTree(migrationDocFiles);
+      }
+    }
+
+    const reactDocsLinkPath = selection === 'react' ? `./${DOCS_DIR_NAME}/react` : undefined;
+    const nativeDocsLinkPath = selection === 'native' ? `./${DOCS_DIR_NAME}/native` : undefined;
+    const migrationDocsLinkPath =
+      selection === 'migration' ? `./${DOCS_DIR_NAME}/migration` : undefined;
 
     // Generate index content once (reused for all output files)
     const indexData: Parameters<typeof generateHerouiMdIndex>[0] = {
@@ -307,19 +327,19 @@ export async function docsAction(options: DocsOptions) {
 
     if (nativeDocsLinkPath) indexData.nativeDocsPath = nativeDocsLinkPath;
     if (nativeSections) indexData.nativeSections = nativeSections;
+    if (migrationDocsLinkPath) indexData.migrationDocsPath = migrationDocsLinkPath;
+    if (migrationSections) indexData.migrationSections = migrationSections;
     if (reactDocsLinkPath) indexData.reactDocsPath = reactDocsLinkPath;
     if (reactSections) indexData.reactSections = reactSections;
     if (reactDemoFiles) indexData.reactDemoFiles = reactDemoFiles;
 
-    // Generate separate index content for React and Native
+    // Generate index content for the selected library only
     const reactIndexContent =
-      selection === 'react' || selection === 'both'
-        ? generateHerouiMdIndex(indexData, 'react')
-        : undefined;
+      selection === 'react' ? generateHerouiMdIndex(indexData, 'react') : undefined;
     const nativeIndexContent =
-      selection === 'native' || selection === 'both'
-        ? generateHerouiMdIndex(indexData, 'native')
-        : undefined;
+      selection === 'native' ? generateHerouiMdIndex(indexData, 'native') : undefined;
+    const migrationIndexContent =
+      selection === 'migration' ? generateHerouiMdIndex(indexData, 'migration') : undefined;
 
     // Write to all output files
     const gitignoreResult = ensureGitignoreEntry(cwd);
@@ -336,7 +356,12 @@ export async function docsAction(options: DocsOptions) {
         isNewFile = false;
       }
 
-      const newContent = injectIntoClaudeMd(existingContent, reactIndexContent, nativeIndexContent);
+      const newContent = injectIntoClaudeMd(
+        existingContent,
+        reactIndexContent,
+        nativeIndexContent,
+        migrationIndexContent
+      );
 
       fs.writeFileSync(filePath, newContent, 'utf-8');
 
@@ -359,7 +384,7 @@ export async function docsAction(options: DocsOptions) {
     Logger.log(chalk.cyan('📚 What was installed:'));
     Logger.log(`  • Documentation files downloaded to ${chalk.bold(`.${DOCS_DIR_NAME}/`)}`);
     Logger.log(`  • Index generated in ${chalk.bold(outputFiles.join(', '))}`);
-    if (selection === 'react' || selection === 'both') {
+    if (selection === 'react') {
       Logger.log(`  • Demo files included for React code examples`);
     }
     Logger.newLine();
@@ -405,7 +430,7 @@ async function promptForLibrarySelection(neitherFound: boolean = false): Promise
   const selection = await getSelect('Select docs to include', [
     {title: 'HeroUI React v3', value: 'react'},
     {title: 'HeroUI Native', value: 'native'},
-    {title: 'Both', value: 'both'}
+    {title: 'HeroUI Migration (v2→v3)', value: 'migration'}
   ]);
 
   if (selection === undefined) {

src/analytics/analytics.ts

@@ -5,7 +5,7 @@ import {getErrorMessage} from './utils';
 export type AgentsMdEvent = 'AGENTS_MD_SUCCESS' | 'AGENTS_MD_ERROR';
 
 export interface AgentsMdProperties {
-  selection?: 'react' | 'native' | 'both';
+  selection?: 'react' | 'native' | 'migration';
   outputFiles?: string[];
   outputFileCount?: number;
   duration?: number;

src/commands/agents-md.ts

@@ -10,6 +10,7 @@ export function registerAgentsMdCommand(cmd: Command) {
     )
     .option('--react', 'Include only React docs')
     .option('--native', 'Include only Native docs')
+    .option('--migration', 'Include HeroUI v2 to v3 migration docs')
     .option(
       '--output <files...>',
       'Target file path(s) (e.g., AGENTS.md, or AGENTS.md CLAUDE.md for multiple)'