port docs site from mintlify to fumadocs (#175)

* docs: address review findings on auth examples and docs app

- replace credential-in-argument examples in auth-matrix with the
  interactive wizard flow (shell history and process list exposure)
- warn about flag-based credential entry in the authentication guide
- document credential-specific validation endpoints for auth check
- distinguish session-only filters from V1-compatible filters
- fix KAGI_SESSION_TOKEN examples that pointed at a file path instead of
  a token value; correct the subshell inheritance example
- gate the lens workflow on KAGI_SESSION_TOKEN, not just auth check
- stop recommending committing config.toml with credentials
- fix mermaid diagram edges (KAGI_API_KEY for search/extract) and the
  config lookup order in the precedence example
- render mermaid blocks via @theguild/remark-mermaid
- fix literal *kagi* markers inside code spans, align Alpine Linux entry
  with published assets, point regenerated demo gifs at public/images
- add completion to commands nav, toon format note in assistant page,
  drop leftover probe.ts

* docs: apply second-round review nits

- lens workflow guard also confirms the selected credential is a session
  token via auth status output, matching real CLI output format
- index page: clarify that the redacted template is what gets committed
  while kagi auth writes credentials to ~/.config/kagi-cli/config.toml,
  add extract to the public-API mermaid diagram (KAGI_API_KEY)
- demos: mkdir the docs/public/images/demos output dir actually used by
  the agg commands
- auth-matrix: drop contradictory region classification (V1-compatible
  only), rename the legacy-token migration heading

Author: Microck

.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/.mintignore

@@ -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/[[...slug]]/page.tsx

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

docs/app/api/search/route.ts

@@ -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/global.css

@@ -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/app/layout.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>
+  );
+}