port docs site from mintlify to fumadocs

.coderabbit.yaml

@@ -5,11 +5,11 @@ knowledge_base:
     filePatterns:
       - files: "CONTRIBUTING.md"
         applyTo: "**/*"
-      - files: ".facts,docs/reference/output-contract.mdx"
+      - files: ".facts,docs/content/docs/reference/output-contract.mdx"
         applyTo: "src/**/*.rs,tests/**/*.rs"
-      - files: "docs/reference/auth-matrix.mdx"
+      - files: "docs/content/docs/reference/auth-matrix.mdx"
         applyTo: "src/auth*.rs,src/api.rs,src/http.rs,src/main.rs"
-      - files: "docs/commands/mcp.mdx"
+      - files: "docs/content/docs/commands/mcp.mdx"
         applyTo: "src/main.rs,src/cli.rs,src/mcp_install.rs,tests/**/*.rs"
       - files: "docs/release-runbook.md"
         applyTo: "Cargo.toml,Cargo.lock,npm/**/*.cjs,npm/package.json,CHANGELOG.md,.github/workflows/release.yml,.github/workflows/npm-publish.yml"

.github/workflows/release.yml

@@ -207,28 +207,14 @@ jobs:
             gh release create "$RELEASE_TAG" dist/* --notes-file dist/release-notes.md --title "$RELEASE_TAG" --verify-tag
           fi
 
-      - name: Trigger Mintlify docs deployment
-        id: trigger_mintlify_docs
+      - name: Build Fumadocs docs site
+        id: build_docs_site
         continue-on-error: true
-        env:
-          MINTLIFY_DEPLOY_COOKIE: ${{ secrets.MINTLIFY_DEPLOY_COOKIE }}
         run: |
           set -euo pipefail
-
-          if [ -z "${MINTLIFY_DEPLOY_COOKIE:-}" ]; then
-            echo "MINTLIFY_DEPLOY_COOKIE is not configured; skipping Mintlify deployment trigger."
-            echo "status=skipped" >> "$GITHUB_OUTPUT"
-            exit 0
-          fi
-
-          curl -fsS -X POST \
-            -H "accept: */*" \
-            -H "content-type: application/json" \
-            -H "origin: https://app.mintlify.com" \
-            -H "referer: https://app.mintlify.com/kagi-cli/kagi-cli" \
-            -H "cookie: ${MINTLIFY_DEPLOY_COOKIE}" \
-            https://app.mintlify.com/api/deployment/update/kagi-cli
-          echo "status=triggered" >> "$GITHUB_OUTPUT"
+          corepack enable
+          pnpm --dir docs install --frozen-lockfile
+          pnpm --dir docs build
 
       - name: Sync Homebrew tap and Scoop bucket
         id: sync_package_indexes
@@ -512,6 +498,11 @@ jobs:
           fi
           echo "status=synced" >> "$GITHUB_OUTPUT"
 
+      - name: Report docs build warning
+        if: steps.build_docs_site.outcome == 'failure'
+        run: |
+          echo "::warning title=Docs build failed::GitHub release assets were published, but the Fumadocs docs app under docs/ did not build. Fix the build failure so docs changes can ship."
+
       - name: Report package index sync warning
         if: steps.sync_package_indexes.outcome == 'failure' || steps.sync_package_indexes.outputs.status == 'skipped'
         run: |
@@ -522,7 +513,3 @@ jobs:
         run: |
           echo "::warning title=AUR package sync incomplete::GitHub release assets were published, but the AUR package was not updated. Configure AUR_SSH_PRIVATE_KEY or update the AUR package manually."
 
-      - name: Report Mintlify deployment warning
-        if: steps.trigger_mintlify_docs.outcome == 'failure' || steps.trigger_mintlify_docs.outputs.status == 'skipped'
-        run: |
-          echo "::warning title=Mintlify deployment incomplete::GitHub release assets were published, but docs deployment was not confirmed. Configure or rotate MINTLIFY_DEPLOY_COOKIE, or trigger the deployment from the Mintlify dashboard."

docs/.gitignore

@@ -0,0 +1,5 @@
+node_modules/
+.next/
+.source/
+next-env.d.ts
+*.tsbuildinfo

docs/app/[[...slug]]/page.tsx

@@ -0,0 +1,52 @@
+import { source } from '@/lib/source';
+import { DocsLayout } from 'fumadocs-ui/layouts/docs';
+import { DocsBody, DocsPage } from 'fumadocs-ui/page';
+import { getMDXComponents } from '@/mdx-components';
+import { notFound } from 'next/navigation';
+import type { Metadata } from 'next';
+import { Logo } from '@/components/logo';
+
+export default async function Page(props: {
+  params: Promise<{ slug?: string[] }>;
+}) {
+  const params = await props.params;
+  const page = source.getPage(params.slug);
+  if (!page) notFound();
+
+  const MDX = page.data.body;
+
+  return (
+    <DocsLayout
+      tree={source.pageTree}
+      nav={{ title: <Logo /> }}
+      links={[
+        { text: 'GitHub', url: 'https://github.com/Microck/kagi-cli' },
+        { text: 'npm', url: 'https://www.npmjs.com/package/kagi-cli' },
+        { text: 'Kagi', url: 'https://kagi.com' },
+      ]}
+    >
+      <DocsPage toc={page.data.toc}>
+        <DocsBody>
+          <MDX />
+        </DocsBody>
+      </DocsPage>
+    </DocsLayout>
+  );
+}
+
+export function generateStaticParams() {
+  return source.generateParams();
+}
+
+export async function generateMetadata(props: {
+  params: Promise<{ slug?: string[] }>;
+}) {
+  const params = await props.params;
+  const page = source.getPage(params.slug);
+  if (!page) notFound();
+
+  return {
+    title: page.data.title,
+    description: page.data.description,
+  };
+}

docs/app/api/search/route.ts

@@ -0,0 +1,4 @@
+import { createFromSource } from 'fumadocs-core/search/server';
+import { source } from '@/lib/source';
+
+export const { GET } = createFromSource(source);

docs/app/global.css

@@ -0,0 +1,17 @@
+@import 'tailwindcss';
+@import 'fumadocs-ui/css/neutral.css';
+@import 'fumadocs-ui/css/preset.css';
+@import 'remark-github-blockquote-alert/alert.css';
+
+/*
+ * Kagi brand theme (ported from Mintlify docs.json "maple" theme):
+ * primary #ffb319, light #ffc85a, dark #18181a
+ */
+:root {
+  --color-fd-primary: #ffb319;
+}
+
+.dark {
+  --color-fd-primary: #ffc85a;
+  --color-fd-background: #18181a;
+}

docs/app/layout.tsx

@@ -0,0 +1,25 @@
+import './global.css';
+import { RootProvider } from 'fumadocs-ui/provider';
+import type { Metadata } from 'next';
+import type { ReactNode } from 'react';
+
+export const metadata: Metadata = {
+  title: {
+    template: '%s | kagi CLI',
+    default: 'kagi CLI documentation',
+  },
+  description:
+    'Documentation for the kagi CLI, a command-line interface and MCP server for Kagi search, summarization, extraction, and automation.',
+  metadataBase: new URL('https://kagi.micr.dev'),
+  icons: '/images/favicon.png',
+};
+
+export default function RootLayout({ children }: { children: ReactNode }) {
+  return (
+    <html lang="en" className="flex h-full flex-col antialiased" suppressHydrationWarning>
+      <body className="flex min-h-full flex-col">
+        <RootProvider>{children}</RootProvider>
+      </body>
+    </html>
+  );
+}

docs/components/logo.tsx

@@ -0,0 +1,20 @@
+import Link from 'next/link';
+
+// Brand logos from the Mintlify config: light variant for light mode,
+// dark variant for dark mode.
+export function Logo() {
+  return (
+    <Link href="/" className="inline-flex items-center gap-2 font-semibold">
+      <img
+        src="/images/kagi-cli-logo-light.svg"
+        alt="kagi CLI"
+        className="h-7 w-auto max-w-[180px] object-contain object-left dark:hidden"
+      />
+      <img
+        src="/images/kagi-cli-logo-dark.svg"
+        alt="kagi CLI"
+        className="hidden h-7 w-auto max-w-[180px] object-contain object-left dark:block"
+      />
+    </Link>
+  );
+}

docs/commands/assistant.mdx → docs/content/docs/commands/assistant.mdx

@@ -427,8 +427,7 @@ kagi assistant custom get "Research"
 ```
 
 ## Notes
-
-- Prompt mode now supports `json`, `pretty`, `compact`, and `markdown`.
+- Prompt mode now supports `json`, `toon`, `pretty`, `compact`, and `markdown`.
 - `thread export` defaults to markdown because that is the natural terminal transcript format.
 - `assistant custom list` includes built-in assistants as well as user-created ones.
 - File-upload Assistant flows are intentionally out of scope in this CLI today.

docs/content/docs/commands/meta.json

@@ -0,0 +1,34 @@
+{
+  "title": "Commands",
+  "defaultOpen": true,
+  "pages": [
+    "---Core Commands",
+    "search",
+    "batch",
+    "auth",
+    "usage",
+    "summarize",
+    "extract",
+    "watch",
+    "notify",
+    "completion",
+    "history",
+    "skills",
+    "mcp",
+    "---Content & Feeds",
+    "news",
+    "smallweb",
+    "---AI & Enrichment",
+    "assistant",
+    "quick",
+    "ask-page",
+    "translate",
+    "fastgpt",
+    "enrich",
+    "---Settings",
+    "lens",
+    "bang",
+    "redirect",
+    "site-pref"
+  ]
+}

docs/guides/advanced-usage.mdx → docs/content/docs/guides/advanced-usage.mdx

@@ -135,7 +135,7 @@ crontab -e
 source ~/.bashrc
 
 # Or set variables explicitly
-export KAGI_SESSION_TOKEN="$HOME/.kagi-session-token"
+export KAGI_SESSION_TOKEN="https://kagi.com/search?token=YOUR_SESSION_TOKEN"
 export PATH="/home/user/.local/bin:$PATH"
 
 # Now run kagi
@@ -153,7 +153,7 @@ Description=Kagi News Fetcher
 
 [Service]
 Type=oneshot
-Environment=KAGI_SESSION_TOKEN=/home/user/.kagi-session-token
+Environment=KAGI_SESSION_TOKEN=https://kagi.com/search?token=YOUR_SESSION_TOKEN
 ExecStart=/home/user/.local/bin/kagi news --category tech --limit 10
 StandardOutput=append:/home/user/logs/kagi-news.log
 StandardError=append:/home/user/logs/kagi-news.log

docs/guides/authentication.mdx → docs/content/docs/guides/authentication.mdx

@@ -260,6 +260,9 @@ kagi auth set --api-token 'YOUR_API_TOKEN'
 kagi auth set --session-token 'https://kagi.com/search?token=SESSION_TOKEN' --api-key 'API_KEY' --api-token 'API_TOKEN'
 ```
 
+> [!WARNING]
+> Flags put the credential in your shell history and the process list while the command runs. Prefer the interactive wizard (`kagi auth`) or environment variables for real credentials; use these flags only for automation where that trade-off is accepted.
+
 **Creating manually:**
 
 ```bash

docs/guides/installation.mdx → docs/content/docs/guides/installation.mdx

@@ -56,7 +56,7 @@ irm https://raw.githubusercontent.com/Microck/kagi-cli/main/scripts/install.ps1
 This script will:
 1. Detect your Windows architecture (x64 or ARM64)
 2. Download the appropriate binary from GitHub Releases
-3. Install it to `%LOCALAPPDATA%\*kagi*\bin`
+3. Install it to `%LOCALAPPDATA%\kagi\bin`
 4. Add the directory to your PATH
 
 **Verification:**
@@ -317,8 +317,8 @@ cargo build --release
 ```
 
 The compiled binary will be at:
-- **macOS/Linux**: `./target/release/*kagi*`
-- **Windows**: `.\target\release\*kagi*.exe`
+- **macOS/Linux**: `./target/release/kagi`
+- **Windows**: `.\target\release\kagi.exe`
 
 ### Install from Build
 
@@ -382,7 +382,7 @@ xattr -d com.apple.quarantine $(which kagi)
 - Fedora 32+
 - CentOS/RHEL 8+
 - Arch Linux
-- Alpine Linux (musl build)
+- Other distros (e.g. Alpine): no prebuilt musl binary is published yet, so build from source (see below)
 
 **Dependencies:**
 
@@ -476,10 +476,10 @@ kagi search --format pretty "test query"
 1. Find where *kagi* was installed:
    ```bash
    # macOS/Linux
-   which *kagi* || find ~ -name "*kagi*" -type f 2>/dev/null
+   which kagi || find ~ -name "kagi" -type f 2>/dev/null
 
    # Windows PowerShell
-   Get-Command *kagi* -ErrorAction SilentlyContinue
+   Get-Command kagi -ErrorAction SilentlyContinue
    ```
 
 2. Add the directory to your PATH (see Manual Installation section)

docs/content/docs/guides/meta.json

@@ -0,0 +1,14 @@
+{
+  "title": "Guides",
+  "defaultOpen": true,
+  "pages": [
+    "---Getting Started",
+    "installation",
+    "quickstart",
+    "authentication",
+    "---Usage",
+    "workflows",
+    "advanced-usage",
+    "troubleshooting"
+  ]
+}

docs/guides/troubleshooting.mdx → docs/content/docs/guides/troubleshooting.mdx

@@ -29,11 +29,11 @@ Recent *kagi* builds include more context in failed HTTP operations. Use these d
 
 ## Installation Issues
 
-### "command not found" or "*kagi* is not recognized"
+### "command not found" or "kagi is not recognized"
 
 **Symptoms:**
 - Shell reports `kagi: command not found`
-- PowerShell reports `kagi : The term '*kagi*' is not recognized`
+- PowerShell reports `kagi : The term 'kagi' is not recognized`
 
 **Causes:**
 - Binary not in PATH
@@ -77,7 +77,7 @@ source ~/.bashrc  # or ~/.zshrc
 ### Permission Denied (macOS/Linux)
 
 **Symptoms:**
-- `bash: /path/to/*kagi*: Permission denied`
+- `bash: /path/to/kagi: Permission denied`
 
 **Solutions:**
 
@@ -273,15 +273,15 @@ KAGI_SESSION_TOKEN='token'
 export KAGI_SESSION_TOKEN='token'
 ```
 
-**2. Subshell doesn't inherit:**
+**2. Set for a single command when the script needs it everywhere:**
 ```bash
-# Wrong - subshell doesn't see it
-export KAGI_SESSION_TOKEN='token'
-bash -c 'kagi auth status'
+# Only that one command sees it
+KAGI_SESSION_TOKEN='token' kagi auth status
 
-# Right - pass explicitly
-bash -c 'kagi auth status'  # won't work
-KAGI_SESSION_TOKEN='token' bash -c 'kagi auth status'  # works
+# Export first so every later command and child shell sees it
+export KAGI_SESSION_TOKEN='token'
+kagi auth status
+bash -c 'kagi auth status'  # works: exported vars reach child shells
 ```
 
 **3. Already set to empty:**