gofastskill · aroff · Jul 10, 2026 · Jul 10, 2026
diff --git a/webdocs/MIGRATION.md b/webdocs/MIGRATION.md
@@ -0,0 +1,59 @@
+# Fumadocs Migration Notes
+
+This directory contains documentation content converted from Mintlify to [Fumadocs](https://fumadocs.dev) MDX format.
+
+## What changed
+
+### Navigation: mint.json → meta.json
+
+Mintlify's central `mint.json` was replaced with per-folder `meta.json` files. Fumadocs derives the sidebar from the folder structure plus `meta.json` ordering. The root `meta.json` uses `---Separator---` entries to recreate the original navigation groups (Getting Started, Configuration, Skill Management, etc.).
+
+### Component mappings
+
+| Mintlify | Fumadocs | Notes |
+|----------|----------|-------|
+| `<Note>` | `<Callout>` | Default type (info) |
+| `<Info>` | `<Callout type="info">` | |
+| `<Warning>` | `<Callout type="warn">` | |
+| `<Tip>` | `<Callout>` | Mapped to default (info) |
+| `<Check>` | `<Callout type="success">` | |
+| `<CardGroup>` / `<Card icon="...">` | `<Cards>` / `<Card>` | `icon` props stripped (string names need JSX components in host app) |
+| `<AccordionGroup>` / `<Accordion>` | `<Accordions>` / `<Accordion id="..." title="...">` | Slugified `id` added |
+| `<Steps>` / `<Step title="X">` | `### X [step]` headings | Requires `remark-steps` plugin in host app |
+| `<Tabs>` / `<Tab title="X">` | `<Tabs items=[...]>` / `<Tab value="X">` | |
+| `<ParamField path="..." type="...">` | `#### \`field\` (type, required/optional)` | Converted to heading + bullets |
+| `<Frame>` | removed | Content (images) kept |
+
+### Other changes
+
+- `TROUBLESHOOTING.md` renamed to `troubleshooting.mdx` for slug consistency.
+- Fixed duplicate `</Accordions>` in `skill-management/validation.mdx`.
+- Card `icon="..."` props were stripped. Fumadocs requires JSX icon components (e.g. `lucide-react`), not string names. Add icons in the host app via the `icon` handler on `loader()` or per-card.
+
+## What the hosting app needs to do
+
+This migration covers content only. To serve these docs:
+
+1. **Create a fumadocs app** (Next.js recommended): `pnpm create fumadocs-app`
+2. **Point content source at this directory**: set `dir: 'content/docs'` (or wherever you place these files) in `source.config.ts` → `defineDocs()`.
+3. **Enable remark-steps**: the `[step]` heading markers require the `remark-steps` plugin. Add it to `mdxOptions` in `source.config.ts`.
+4. **Place static assets in `public/`**: images referenced as `/images/...` and logos in `/logo/` must live in the host app's `public/` directory.
+5. **Configure theme and search**: colors, logo, topbar CTA, and search (Algolia/Orama) are host-app concerns, not content-level config.
+6. **Map card icons** (optional): if you want icons on cards, pass an `icon` handler to `loader()` that resolves icon names to `lucide-react` components.
+
+### File structure
+
+```
+webdocs/
+  meta.json              ← root navigation (groups + ordering)
+  index.mdx              ← landing page
+  welcome.mdx
+  quickstart.mdx
+  ...
+  cli-reference/
+    meta.json            ← folder page ordering
+    overview.mdx
+    ...
+  images/                ← static assets (move to public/ in host app)
+  logo/                  ← logo SVGs (move to public/ in host app)
+```
diff --git a/webdocs/cheatsheet.mdx b/webdocs/cheatsheet.mdx
@@ -51,9 +51,9 @@ Quick reference for common FastSkill operations, ordered from everyday manifest
 | Environment check | `fastskill doctor` | Reports configuration and environment readiness, including whether an embedding provider is configured for semantic search |
 | Machine-readable | `fastskill doctor --json` | Same checks as JSON |
 
-<Note>
+<Callout>
 Modern agents (Claude Code, Cursor, …) read skills directly from the skills directory — there is no metadata-file sync step. Just `fastskill install` (or `fastskill add`) and the agent discovers them.
-</Note>
+</Callout>
 
 ## Skill authoring
 

diff --git a/webdocs/cli-reference/discovery-commands.mdx b/webdocs/cli-reference/discovery-commands.mdx
@@ -7,25 +7,25 @@ description: "FastSkill CLI commands for skill search, vector indexing, and repo
 
 Discovery commands help you find, index, and manage skills in your FastSkill ecosystem. These commands provide semantic search, vector indexing, and repository management capabilities.
 
-<Info>
+<Callout type="info">
 **Command Architecture**:
 - **Repository Management**: Use `fastskill repos` for all repository operations (add, remove, list, test, refresh) and catalog browsing (skills, show, versions)
 - **Skill Discovery**: Use `fastskill search` (remote catalogs by default; add `--local` for installed skills and embeddings)
-</Info>
+</Callout>
 
-<Note>
+<Callout>
 For detailed documentation on specific commands, see the dedicated command pages linked below.
-</Note>
+</Callout>
 
 ## Command Reference
 
 ### fastskill search
 
 Query skills. **Default scope is remote** (catalog APIs). Use `--local` to search installed skills; local embedding search uses OpenAI when configured and respects `--embedding`.
 
-<Info>
+<Callout type="info">
 See [search Command](/cli-reference/search-command) for complete documentation with output formats.
-</Info>
+</Callout>
 
 ```bash
 # Remote catalog search (default)
@@ -64,9 +64,9 @@ fastskill search "process text" --repository my-repo
 
 Rebuild the vector search index by scanning all installed skills. Updates embeddings and similarity database.
 
-<Info>
+<Callout type="info">
 See [reindex Command](/cli-reference/reindex-command) for complete documentation with concurrency options.
-</Info>
+</Callout>
 
 ```bash
 # Reindex all skills (uses configured skills directory)
@@ -105,9 +105,9 @@ fastskill reindex --skills-dir ./.claude/skills
 
 Manage skill repositories for discovering and installing skills. Supports multiple repository types with authentication and priority-based resolution. This is the **primary command** for repository management and catalog browsing.
 
-<Info>
+<Callout type="info">
 See [repos Command](/cli-reference/repository-command) for complete documentation with subcommands and authentication.
-</Info>
+</Callout>
 
 ```bash
 # List all configured repositories
@@ -196,9 +196,9 @@ When skills are available in multiple repositories, priority determines the orde
 - Default priority: 0
 - Higher priority values are checked later
 
-<Warning>
+<Callout type="warn">
 **Legacy commands**: `sources` (alias `source`) and `registry` are hidden from `fastskill --help` but still exist for compatibility. Prefer `fastskill repos` for repository and catalog operations.
-</Warning>
+</Callout>
 
 ## Search and Reindex Workflow
 
@@ -270,77 +270,75 @@ fastskill search "skill name or description"
 
 ## Troubleshooting
 
-<AccordionGroup>
-<Accordion title="Search returns no results">
-  <Warning>
+<Accordions>
+<Accordion id="search-returns-no-results" title="Search returns no results">
+  <Callout type="warn">
   **Index not built**: Make sure you've run `fastskill reindex` after installing skills.
-  </Warning>
+  </Callout>
 
-  <Warning>
+  <Callout type="warn">
   **Query too specific**: Try broader terms or different phrasing.
-  </Warning>
+  </Callout>
 
-  <Warning>
+  <Callout type="warn">
   **Skills not installed**: Verify skills are in `.claude/skills/` with `fastskill list`.
-  </Warning>
+  </Callout>
 </Accordion>
 
-<Accordion title="Reindex fails">
-  <Info>
+<Accordion id="reindex-fails" title="Reindex fails">
+  <Callout type="info">
   **OpenAI API key not set**: Set `OPENAI_API_KEY` environment variable.
   ```bash
   export OPENAI_API_KEY="your-key-here"
   fastskill reindex
   ```
-  </Info>
+  </Callout>
 
-  <Info>
+  <Callout type="info">
   **API rate limit errors**: Reduce concurrent requests with `--max-concurrent 3`.
-  </Info>
+  </Callout>
 
-  <Info>
+  <Callout type="info">
   **Network errors**: Check internet connectivity and OpenAI API status.
-  </Info>
+  </Callout>
 </Accordion>
 
-<Accordion title="Repository not found">
-  <Tip>
+<Accordion id="repository-not-found" title="Repository not found">
+  <Callout>
   **Invalid repository name**: Check repository name with `fastskill repos list`.
-  </Tip>
+  </Callout>
 
-  <Tip>
+  <Callout>
   **Repository URL incorrect**: Verify URL is accessible with `fastskill repos test <name>`.
-  </Tip>
+  </Callout>
 
-  <Tip>
+  <Callout>
   **Authentication failed**: Verify authentication type and credentials with `fastskill repos info <name>`.
-  </Tip>
+  </Callout>
 </Accordion>
-</AccordionGroup>
+</Accordions>
 
 ## Best Practices
 
-<Steps>
-<Step title="Reindex after changes">
-  Always run `fastskill reindex` after installing, updating, or modifying skills to keep search index current.
-</Step>
+### 1. Reindex after changes
 
-<Step title="Use natural language queries">
-  Search queries work best with natural language that matches skill descriptions in SKILL.md files.
-</Step>
+Always run `fastskill reindex` after installing, updating, or modifying skills to keep search index current.
 
-<Step title="Organize repositories by priority">
-  Set lower priority numbers for primary repositories to ensure preferred skills are discovered first.
-</Step>
+### 2. Use natural language queries
 
-<Step title="Test repositories after configuration">
-  Use `fastskill repos test <name>` to verify repositories are accessible before using them.
-</Step>
+Search queries work best with natural language that matches skill descriptions in SKILL.md files.
 
-<Step title="Control API concurrency for reindexing">
-  Use `--max-concurrent` to balance speed and API rate limits. Start with default and adjust based on rate limit errors.
-</Step>
-</Steps>
+### 3. Organize repositories by priority
+
+Set lower priority numbers for primary repositories to ensure preferred skills are discovered first.
+
+### 4. Test repositories after configuration
+
+Use `fastskill repos test <name>` to verify repositories are accessible before using them.
+
+### 5. Control API concurrency for reindexing
+
+Use `--max-concurrent` to balance speed and API rate limits. Start with default and adjust based on rate limit errors.
 
 ## See Also
 

diff --git a/webdocs/cli-reference/eval-command.mdx b/webdocs/cli-reference/eval-command.mdx
@@ -7,9 +7,9 @@ description: "Validate, run, report, and score skill evaluation suites defined i
 
 `fastskill eval` runs skill quality checks using prompts and rubrics under `[tool.fastskill.eval]` in `skill-project.toml`. Subcommands are `validate`, `run`, `report`, and `score`.
 
-<Info>
+<Callout type="info">
 `eval run` requires an agent on `PATH` for the chosen `--agent` key (for example `codex`, `claude`, `gemini`, `opencode`, or `agent`). Use `eval validate --agent <key>` to verify availability.
-</Info>
+</Callout>
 
 ## Usage
 

diff --git a/webdocs/cli-reference/init-command.mdx b/webdocs/cli-reference/init-command.mdx
@@ -68,9 +68,9 @@ Overwrite existing `skill-project.toml`:
 fastskill init --force
 ```
 
-<Warning>
+<Callout type="warn">
 Using `--force` will overwrite your existing `skill-project.toml` file. Make sure to backup if you need to preserve any custom configurations.
-</Warning>
+</Callout>
 
 ## Behavior
 
@@ -133,9 +133,9 @@ fastskill init
 # Creates: [metadata] id = "my-skill"
 ```
 
-<Info>
+<Callout type="info">
 If you're in a project directory (no SKILL.md), the `skill-project.toml` can still be used to declare dependencies for installation via `fastskill install`.
-</Info>
+</Callout>
 
 ## Context Detection
 
@@ -191,9 +191,9 @@ license: MIT
 Skill content here...
 ```
 
-<Info>
+<Callout type="info">
 If you provide `--version`, `--description`, or `--author` flags, they will override the values from SKILL.md frontmatter.
-</Info>
+</Callout>
 
 ## Version Validation
 

diff --git a/webdocs/cli-reference/install-command.mdx b/webdocs/cli-reference/install-command.mdx
@@ -45,9 +45,9 @@ Install production skills only, excluding dev group:
 fastskill install --without dev
 ```
 
-<Info>
+<Callout type="info">
 This is useful for CI/CD pipelines where you want lean production deployments without development dependencies.
-</Info>
+</Callout>
 
 ### Install Only Specific Groups
 
@@ -72,9 +72,9 @@ Install exact versions from `skills.lock`:
 fastskill install --lock
 ```
 
-<Check>
+<Callout type="success">
 Use `--lock` for production deployments to ensure you install the exact same versions that were used in development.
-</Check>
+</Callout>
 
 ### Combined Example: Production Deployment
 
@@ -120,9 +120,9 @@ test-helper = { source = "git", url = "https://github.com/user/test-helper.git",
 mock-skill = { source = "registry", id = "mock-skill", groups = ["test"] }
 ```
 
-<Info>
+<Callout type="info">
 If no `groups` are specified, the skill belongs to no groups and will always be installed.
-</Info>
+</Callout>
 
 ### Default Group Behavior
 
@@ -446,27 +446,25 @@ jobs:
 
 ## Best Practices
 
-<Steps>
-<Step title="Commit both skill-project.toml and skills.lock">
-  Always commit both files to version control. This ensures all team members install the same versions.
-</Step>
+### 1. Commit both skill-project.toml and skills.lock
 
-<Step title="Use groups for environment-specific dependencies">
-  Separate dev, test, and production dependencies into groups. Use `--without dev` for production builds.
-</Step>
+Always commit both files to version control. This ensures all team members install the same versions.
 
-<Step title="Run fastskill install before committing">
-  Run `fastskill install` after modifying `skill-project.toml` to update `skills.lock` with new versions.
-</Step>
+### 2. Use groups for environment-specific dependencies
 
-<Step title="Use --lock for production deployments">
-  Always use `--lock` flag in production to ensure exact version matches.
-</Step>
+Separate dev, test, and production dependencies into groups. Use `--without dev` for production builds.
 
-<Step title="Reindex after installation">
-  Run `fastskill reindex` after installation to update the semantic search index.
-</Step>
-</Steps>
+### 3. Run fastskill install before committing
+
+Run `fastskill install` after modifying `skill-project.toml` to update `skills.lock` with new versions.
+
+### 4. Use --lock for production deployments
+
+Always use `--lock` flag in production to ensure exact version matches.
+
+### 5. Reindex after installation
+
+Run `fastskill reindex` after installation to update the semantic search index.
 
 ## See Also
 

diff --git a/webdocs/cli-reference/meta.json b/webdocs/cli-reference/meta.json
@@ -0,0 +1,16 @@
+{
+  "pages": [
+    "overview",
+    "skill-commands",
+    "discovery-commands",
+    "init-command",
+    "install-command",
+    "update-command",
+    "reindex-command",
+    "search-command",
+    "serve-command",
+    "repository-command",
+    "eval-command",
+    "tooling-commands"
+  ]
+}