Add Cursor prompts to migrate a branch from Hugo to Mintlify (#1804)

## Description

Add Cursor prompts to migrate a branch from Hugo to Mintlify

- Locally, ports a branch with changes that were started before the Hugo
migration to Mintlify.
  - Updates file locations, syntax, frontmatter, TOCs, links.
  - Validates Mintlify content using `mint dev` and `mint broken-links`
- Recreates commits as a single squashed commit against current
`origin/main`

Afterward, the human user:
- Closes the original PR.
- Force-pushes the branch.
- Creates a new PR against the branch.
- Continues working or getting review in the new PR.

Currently added to the `.ai/` directory. Migrating the existing prompts
in that directory to Cursor format is WIP, and these will be in place to
be picked up automatically in scope of that migration.

## Testing
Successfully ported #1627 to #1802
Successfully ported #1563 to #1803

Author: mdlinville

.ai/README.md

@@ -1,130 +1,67 @@
-# AI resources for wandb/docs
+# AI Assistant Resources
 
-This directory contains resources, prompts, and tools designed to help AI agents work effectively with the wandb/docs repository.
+This directory contains resources, prompts, and templates specifically designed for AI agents working with the W&B documentation repository.
 
-## Getting started
+## Directory Structure
 
-Start by reading the [system prompt](./system-prompt.md) to understand your role as a member of the W&B docs team.
-
-## Directory structure
-
-### `system-prompt.md`
-The foundational context for AI agents joining the W&B docs team. Defines your role, responsibilities, and key principles for creating documentation.
-
-### `style-guide.md`
-Comprehensive style guide for W&B documentation. Covers formatting, punctuation, code examples, and W&B-specific conventions.
-
-### `runbooks/`
-Standardized, task-specific instructions for AI agents performing complex operations in this repository. These runbooks ensure consistent, reliable execution of recurring tasks.
-
-**Example tasks:**
-- Testing GitHub Actions changes
-- Performing large-scale refactoring
-- Managing release processes
-
-See [runbooks/README.md](./runbooks/README.md) for detailed information.
-
-### Future directories (planned)
-
-#### `prompts/`
-System prompts and context for different types of AI interactions:
-- Documentation writing guidelines
-- Code review standards
-- Style and tone specifications
-
-#### `tools/`
-Scripts and utilities that AI agents can use:
-- Validation scripts
-- Automation helpers
-- Analysis tools
-
-#### `context/`
-Repository-specific context that helps AI agents understand:
-- Architecture decisions
-- Historical context
-- Domain-specific knowledge
-
-## Usage guidelines
-
-### For repository maintainers
-1. Keep runbooks up-to-date as processes change
-2. Test runbooks regularly with AI agents
-3. Document any repository-specific quirks or constraints
-4. Version control all AI resources alongside code
-
-### For AI agent users
-1. Always check for relevant runbooks before starting complex tasks
-2. Provide runbooks as context to your AI agent
-3. Report issues or ambiguities in runbooks
-4. Contribute improvements based on your experience
-
-## Collaboration guidelines
-
-When working with human and AI teammates on documentation changes:
+```
+.ai/
+├── migrations/           # One-off migration tools and templates
+├── style-guide/         # Writing and code style guidance for AI agents
+└── runbooks/           # Step-by-step procedures for complex tasks
+```
 
-### Before creating a PR
-- **Feature branches**: Push feature branches to collaborate with others before opening a PR.
-- **Branch naming**: Use descriptive names that indicate the purpose (for example, `fix/broken-links-automation-guide`).
+## For Human Contributors
 
-### Creating pull requests
-1. **Start with draft PRs**: Create a draft pull request initially. This won't request reviews and can't be merged accidentally.
-2. **Wait for tests**: Ensure all PR tests pass before marking as ready for review.
-3. **Coordinate with humans**: The human coordinating the work should verify the changes meet requirements before marking the PR ready for review. A human should ultimately merge a PR, not an agent.
+These resources help AI assistants provide consistent, high-quality contributions to the docs. When working with an AI agent:
 
-### PR titles and descriptions
-- **Be meaningful but concise**: Write clear titles that describe what changed.
-- **Link relevant context**: Include:
-  - JIRA IDs (for example, `DOCS-1234`)
-  - GitHub issue IDs (for example, `#456`)
-  - Related PRs for additional context
-- **Add before/after comparison**: When applicable, include:
-  - Links to the current live documentation
-  - Links to the PR's HTML preview showing the changes
-  - Brief description of what changed and why
+1. **For migrations**: Direct the agent to `.ai/migrations/` for specific migration templates
+2. **For style questions**: Reference `.ai/style-guide/` for consistency
+3. **For complex procedures**: Use `.ai/runbooks/` for detailed workflows
 
-### Example PR description
-```
-## Description
+## For AI Agents
 
-Updates AI agent style guide to improve accessibility and code quality.
+When assisting with documentation tasks:
 
-The style guide now provides clearer guidance for AI agents creating documentation:
-- Added accessibility guidelines (no emojis)
-- Added code example best practices  
-- Created runbook template
+1. **Check this directory first** for relevant templates and guidance
+2. **Follow style guides** in `.ai/style-guide/` to ensure consistency
+3. **Use migration templates** in `.ai/migrations/` for structural changes
+4. **Reference runbooks** in `.ai/runbooks/` for multi-step procedures
 
-### Before/After
-- Live docs: https://docs.wandb.ai/guides/ai-resources
-- PR preview: https://preview-12345.pages.dev/guides/ai-resources
+## Current Resources
 
-## Related issues
-
-- Fixes DOCS-1234
-- Related to #456
-```
+### Migrations
+- **hugo-to-mintlify/**: Templates for migrating PRs from Hugo to Mintlify structure
+  - `migration_prompt_template.md`: Step-by-step migration guide
+  - `migration_user_prompt.md`: User-facing prompts for requesting migrations
 
-## Best practices
+### Style Guide
+*(Coming soon)*
+- Writing style guidelines
+- Code formatting standards
+- Naming conventions
 
-1. **Capture knowledge immediately**: After completing any complex task with an AI agent, ask them to draft a runbook while the details are fresh
-2. **Specificity**: Be explicit about every step, assumption, and requirement
-3. **Adaptability**: Include variations for common scenarios
-4. **Safety**: Always include cleanup steps and error handling
-5. **Testing**: Verify runbooks work with multiple AI providers
-6. **Maintenance**: Update runbooks when workflows or tools change
-7. **Iterative improvement**: Have agents review and improve existing runbooks based on their experience
+### Runbooks
+*(Coming soon)*
+- Release process
+- Documentation testing procedures
+- PR review checklist
 
-## Contributing
+## Adding New Resources
 
-When adding AI resources:
+When adding new AI resources:
+1. Place them in the appropriate subdirectory
+2. Update this README with a description
+3. Include clear instructions for both humans and AI agents
+4. Consider whether the resource is temporary (migration) or permanent (style guide)
 
-1. Follow existing naming conventions and structure
-2. Include comprehensive documentation
-3. Test with at least one AI agent
-4. Update relevant README files
-5. Consider security implications of any shared context
+## Note on Tool Compatibility
 
-## Security notes
+These resources are tool-agnostic and work with:
+- Cursor
+- GitHub Copilot
+- Claude (via API or web)
+- ChatGPT
+- Other AI coding assistants
 
-- Never include sensitive information (API keys, passwords, etc.)
-- Be cautious about exposing internal URLs or infrastructure details
-- Review all contributions for potential security risks
+For tool-specific configurations (like `.cursorrules`), those remain in their respective directories.

.ai/migrations/hugo-to-mintlify/README.md

@@ -0,0 +1,97 @@
+# Hugo to Mintlify Migration Guide
+
+This directory contains templates and prompts for migrating documentation from Hugo to Mintlify structure.
+
+## Quick Start for Humans
+
+If you have a PR or branch that was created when the docs used Hugo, follow these steps:
+
+### 1. Identify Your Situation
+
+- **Have a PR number?** → Use Option 1 in `migration_user_prompt.md`
+- **Have a local branch?** → Use Option 2 in `migration_user_prompt.md`  
+- **Have uncommitted changes?** → Use Option 3 in `migration_user_prompt.md`
+
+### 2. Request the Migration
+
+1. Open your AI assistant (Cursor, GitHub Copilot Chat, etc.)
+2. Copy the appropriate prompt from `migration_user_prompt.md`
+3. Fill in the placeholders (PR number, branch name, or file list)
+4. Paste to your AI assistant
+
+### 3. What to Expect
+
+The AI agent will:
+- Identify your Hugo changes
+- Find where files moved in Mintlify structure
+- Convert Hugo syntax to Mintlify components
+- Update navigation in `docs.json`
+- Create a clean commit with only Mintlify files
+
+### 4. After Migration
+
+- **If you had a PR**: Close the old PR and create a new one from the migrated branch
+- **If you had a branch**: Create a new PR directly
+- **Why?** PRs created during Hugo era don't get Mintlify preview deployments
+
+## Files in This Directory
+
+### `migration_prompt_template.md`
+Detailed step-by-step instructions for AI agents to perform the migration. This is the "how-to" guide the AI follows.
+
+### `migration_user_prompt.md`
+Ready-to-use prompts for humans to copy/paste when requesting a migration. Pick the option that matches your situation.
+
+## Common Issues and Solutions
+
+### "Hugo template errors when running mint dev"
+The AI needs to do a hard reset and recreate the commit with only Mintlify files. Ask:
+```
+I'm getting Hugo template errors. Please hard reset to origin/main and recreate the commit with only Mintlify files.
+```
+
+### "My new page doesn't appear in the navigation"
+The AI needs to update `docs.json`. Ask:
+```
+Please add my new page to the navigation in docs.json
+```
+
+### "The PR preview isn't working"
+This is expected for PRs created during Hugo era. You must:
+1. Close the old PR (don't delete the branch)
+2. Create a new PR from the same branch
+3. The new PR will get Mintlify previews
+
+## Prerequisites
+
+Before starting a migration:
+1. Install Mintlify CLI: `npm i -g mintlify`
+2. Have your changes ready (in a PR, branch, or locally)
+3. Be in the docs repository
+
+## Examples of Successful Migrations
+
+- PR #1627 → PR #1802 (org_dashboard documentation)
+- PR #1563 (automation history documentation)
+
+## Need Help?
+
+If the migration fails or you encounter issues:
+1. Check that you're on the latest `main` branch
+2. Ensure no Hugo files are staged (only `models/`, `platform/`, etc.)
+3. Verify `mint dev` runs without errors
+4. Ask the AI to show you what files it's trying to commit
+
+## Technical Notes
+
+### File Structure Changes
+- **Hugo**: `content/en/guides/` → **Mintlify**: Root-level directories
+- **Hugo**: `.md` files → **Mintlify**: `.mdx` files
+- **Hugo**: `content/en/guides/core/` → **Mintlify**: `models/`
+- **Hugo**: `content/en/guides/hosting/` → **Mintlify**: `platform/`
+
+### Syntax Conversions
+- **Tabs**: `{{< tabpane >}}` → `<Tabs>`
+- **Links**: `{{< relref >}}` → Direct paths
+- **Comments**: `<!-- -->` → `{/* */}`
+- **Includes**: `{{< readfile >}}` → Import statements or inline content