docs: update docs engine to nextra

.github/workflows/docs.yml

@@ -1,7 +1,6 @@
 name: Docs
 
-# Mintlify publishes from the connected repository's docs/ directory.
-# This workflow validates sources only; it does not deploy to GitHub Pages.
+# Nextra exports static HTML and Pagefind search to docs/out for GitHub Pages.
 
 on:
   push:
@@ -14,18 +13,26 @@ on:
     branches: ["main"]
     paths:
       - "docs/**"
+      - "README.md"
+      - ".github/workflows/docs.yml"
   workflow_dispatch:
 
 permissions:
   contents: read
 
+concurrency:
+  group: docs-pages-${{ github.event_name == 'pull_request' && github.ref || 'production' }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
 jobs:
   build:
-    name: Validate Mintlify documentation
+    name: Build Nextra documentation
     runs-on: ubuntu-latest
 
     steps:
       - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
 
       - name: Set up Node
         uses: actions/setup-node@v4
@@ -44,6 +51,34 @@ jobs:
           npm test
           npm run check
 
-      - name: Validate Mintlify build
+      - name: Build static site and search index
         working-directory: docs
+        env:
+          NEXT_TELEMETRY_DISABLED: "1"
         run: npm run build
+
+      - name: Configure Pages
+        if: github.event_name != 'pull_request'
+        uses: actions/configure-pages@v5
+
+      - name: Upload static site
+        if: github.event_name != 'pull_request'
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/out
+
+  deploy:
+    name: Deploy to GitHub Pages
+    if: github.event_name != 'pull_request'
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -44,6 +44,8 @@ msbuild.log
 node_modules/
 .mintlify/
 docs/_site/
+docs/.next/
+docs/out/
 
 # ---------------------------------------------------------------------------
 # Environment

AGENTS.md

@@ -16,18 +16,18 @@ A change is not done until the docs that describe it are updated in the same com
 
 - `README.md` is a short landing page: pitch, install, feature summary, links to
   published documentation. Detail goes in `docs/`, never in the README.
-- `docs/` is the documentation site. Pages are `.mdx` files with `title` and `description`
-  frontmatter; `docs/docs.json` declares Mintlify's theme, branding and navigation.
-  `npm run dev` in `docs/` previews the actual Mintlify engine.
-  [docs.yml](./.github/workflows/docs.yml) validates sources; Mintlify's connected GitHub
-  integration handles hosting, not GitHub Pages.
-- A new `.mdx` page must be registered in the `navigation` of
-  [docs/docs.json](./docs/docs.json) or `node docs/check.mjs` fails — the site would
-  otherwise not link to it.
-- README links temporarily retain the legacy `https://meysamhadeli.github.io/codai` URL.
-  After Mintlify hosting is connected and verified, update those links and the temporary
-  base URL in `docs/check.mjs` together. Do not invent a live Mintlify URL. Hosting setup
-  is documented in `CONTRIBUTION.md`; Mintlify does not use `docs/CNAME`.
+- `docs/` is the Nextra documentation site. Pages live in `docs/content/` as `.mdx` files
+  with `title` and `description` frontmatter. Co-located `_meta.js` files declare navigation.
+  `npm run dev` in `docs/` previews it at `http://localhost:3000/codai/`.
+- Register each new page in its directory's `_meta.js` or `node docs/check.mjs` fails.
+  Use native Nextra MDX components and root-relative internal routes; Next.js adds the
+  `/codai` base path automatically. Public asset URLs must include that prefix.
+- `npm run build` exports static HTML to `docs/out` and builds Pagefind search.
+  [docs.yml](./.github/workflows/docs.yml) validates pull requests and deploys pushes to
+  `main` to GitHub Pages. No hosted documentation account is required.
+- The public URL is `https://meysamhadeli.github.io/codai`. Its base path, URL and branding
+  live in `docs/site.config.mjs`. If hosting changes, update that configuration, README
+  links and Pages settings together. Deployment setup is documented in `CONTRIBUTION.md`.
 - Links in `README.md` point at published docs pages, not local file paths.
 - `CHANGELOG.md` entries are user-facing, past tense, under `Added` / `Changed` / `Fixed` /
   `Removed`.
@@ -70,5 +70,5 @@ Never bump `<Version>` for a release by hand — the tag is the version.
 | `src/Codai.Core/` | Domain types and abstractions |
 | `src/Codai.Adapters/` | Providers, configuration, MCP, tools, analysis |
 | `tests/` | Test projects, one per area |
-| `docs/` | Mintlify documentation site source |
+| `docs/` | Nextra documentation site and GitHub Pages static export |
 | `assets/` | Images used by `README.md` |

CHANGELOG.md

@@ -9,12 +9,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
-- Added a Mintlify documentation experience using the `mint` theme, Codai-specific
-  light/dark wordmarks, native cards and steps, and a first-session quickstart.
-  Accents, wordmarks, and favicon matched the app's default blue (`#00AFFF`).
-  Replaced the custom GitHub Pages renderer with Mintlify preview and validation;
-  publishing now requires connecting the repository's `docs/` directory to Mintlify.
-  Existing README URLs were retained pending a verified Mintlify deployment.
+- Added a Nextra documentation experience with Codai-specific light/dark wordmarks,
+  native cards and steps, and a first-session quickstart. Accents, wordmarks, and favicon
+  matched the app's default blue (`#00AFFF`). Static Pagefind search worked without a
+  hosted documentation account.
+
+- Validated README and deployment-workflow changes on documentation pull requests,
+  in addition to documentation content. Patched the documentation build's transitive
+  XML parser without downgrading Nextra.
 
 - Added a cyan terminal-style SVG wordmark as the README logo.
 
@@ -42,7 +44,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   toggles move paths between `plugins` and `disabled_plugins`; remove deletes only the
   configuration entry. Concrete `.dll` validation, offline inspection, lazy startup and
   tests ensure no plugin binary is installed, loaded, executed or deleted. Full ACP/protocol
-  parity remains intentionally unsupported as documented in `docs/acp-compatibility.mdx`.
+  parity remains intentionally unsupported as documented in `docs/content/acp-compatibility.mdx`.
 
 - **Lazy foreground rule activation.** Read/write/edit file targets activate matching
   conditional rules before approval, hooks or I/O. Guidance-only results pause the rest
@@ -318,12 +320,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   version, verifies the `Codai` tool installs and pushes to nuget.org with the
   `NUGET_API_KEY` secret. Package and install verification runs during release publishing;
   regular CI is build-only.
-- **The documentation site is built and published by GitHub Actions.** `docs/` now holds
-  the pages themselves and a dependency-free-in-spirit Node build that renders them into
-  `docs/_site`; [docs.yml](.github/workflows/docs.yml) publishes that output to GitHub
-  Pages. `docs/check.mjs` fails when a page is missing from the `docs.json` navigation, has
-  no frontmatter, or is linked from `README.md` without existing. Mintlify is no longer
-  required.
+- **The documentation site is built and published by GitHub Actions.** Nextra and Next.js
+  exported all pages from `docs/content` into `docs/out`, with `/codai` links and assets.
+  [docs.yml](.github/workflows/docs.yml) restored GitHub Pages deployment after source,
+  static-link, asset, and search-index checks. Native `_meta.js` navigation replaced
+  Mintlify configuration; Mintlify hosting and login were no longer required.
 - **The documentation lives at https://meysamhadeli.github.io/codai.** `README.md` links
   point there instead of the unpublished `docs.codai.dev`.
 - **The CLI package is `Codai`.** `dotnet tool install --global Codai` now installs the

CONTRIBUTION.md

@@ -42,42 +42,50 @@ Codai.slnx --no-restore` will apply the mechanical ones.
 
 ### Documentation
 
-The docs site in `docs/` uses **Mintlify**, with the `mint` theme, native MDX components,
-search, and system-aware light/dark appearance. Pages are `.mdx` files with `title` and
-`description` frontmatter; `docs/docs.json` declares branding and navigation. Requires
-Node.js 22 or later. Before pushing a docs change:
+The docs site in `docs/` uses **Nextra** with the docs theme and Next.js static export.
+It includes Pagefind full-text search, native MDX components, and system-aware light/dark
+appearance. Pages live in `docs/content/` with `title` and `description` frontmatter;
+co-located `_meta.js` files declare sidebar order and labels. Requires Node.js 22 or later.
+Before pushing a docs change:
 
 ```bash
 cd docs
 npm ci
 npm test        # documentation checker regression tests
-npm run check   # registration, frontmatter, README routes, Mintlify broken links
-npm run build   # Mintlify validation; does not export a static site
-npm run dev     # local Mintlify preview at http://localhost:3000
+npm run check   # navigation, frontmatter, MDX links, README routes
+npm run build   # exports docs/out, indexes search, checks exported links and assets
+npm run dev     # preview at http://localhost:3000/codai/
 ```
 
 Documentation accents, wordmarks, and favicon use the app's default
 `deepskyblue1` (`#00AFFF`) in both light and dark modes.
 
-[docs.yml](.github/workflows/docs.yml) validates documentation on pull requests and pushes.
-It no longer builds or deploys GitHub Pages output. Mintlify is the actual rendering and
-hosting engine, not a custom renderer styled to resemble it.
-
-To publish, connect `meysamhadeli/codai` in the Mintlify dashboard, select the production
-branch (`main`), and set the documentation directory to `docs`. Authorize its GitHub
-integration and confirm the deployment in the dashboard. Pushes to the connected branch
-then publish through Mintlify. Account setup, plan availability, GitHub authorization,
-and any custom-domain DNS setup are managed outside this repository.
-
-The existing https://meysamhadeli.github.io/codai URL remains in README links temporarily.
-That legacy deployment does not receive these Mintlify changes. Mintlify cannot host at
-the GitHub-owned `github.io` URL. Once Mintlify assigns a public URL (or a custom domain is
-connected), verify it loads and update README links and the temporary `siteUrl` in
-`docs/check.mjs` together. Do not advertise a new domain before it is live.
-
-Register every new page in `docs/docs.json`, including nested paths without `.mdx`.
-Use root-relative internal routes such as `/getting-started/quickstart` in MDX links and
-cards. Keep Codai's branding and content; do not copy another project's screenshots or copy.
+[docs.yml](.github/workflows/docs.yml) validates and builds documentation on pull requests.
+Changes to `docs/`, `README.md`, or the documentation workflow itself trigger validation.
+Pushes to `main` and manual workflow runs also upload `docs/out` and deploy it to
+https://meysamhadeli.github.io/codai. In repository **Settings > Pages**, select
+**GitHub Actions** as the source. No Mintlify account, hosting subscription, or custom
+domain is needed. Local changes appear publicly only after they are pushed to `main`
+and the deployment succeeds.
+
+`docs/site.config.mjs` defines the `/codai` base path, published URL, and blue branding.
+Keep the base path when previewing locally. A custom domain would require updating that
+configuration, README links, and GitHub Pages domain settings together.
+
+Register every new page in its directory's `_meta.js`. Use root-relative internal routes
+such as `/getting-started/quickstart` with Markdown links or Nextra's `Cards.Card`;
+Next.js adds `/codai` automatically. Public asset URLs must include the base path.
+Use native `Cards`, `Steps`, and `Callout` from `nextra/components`, not Mintlify tags.
+Static export does not support features requiring a server at request time.
+
+Search indexes are generated by `npm run build` and included in the Pages artifact.
+Development mode can preview content without an index, but full search validation
+requires serving the exported site with `/codai` as its URL prefix.
+
+The docs package overrides `speech-rule-engine`'s pinned XML parser with patched
+`@xmldom/xmldom` 0.9.12. Keep this override until the parent dependency adopts a patched
+release. Remaining low-severity KaTeX advisories require upstream updates; do not run
+`npm audit fix --force`, which currently proposes downgrading Nextra to version 2.
 
 ### Live provider tests
 

README.md

@@ -96,17 +96,15 @@ Model availability and coding-tool support depend on the selected provider and m
 
 ## Documentation
 
-Documentation now uses **Mintlify**, with Codai's default blue, light/dark themes,
-search, native cards, and guided setup.
-
-> **Hosting transition:** Links below still point to the legacy GitHub Pages site.
-> The new Mintlify overview and Quickstart are available in local preview; publication
-> is pending a Mintlify connection. See [documentation development](CONTRIBUTION.md#documentation)
-> for preview and publishing instructions.
+Documentation uses **Nextra**, with Codai's default blue, light/dark themes, local
+full-text search, and guided setup. GitHub Actions builds and publishes the static site
+to **GitHub Pages** when documentation changes reach `main`; no hosted docs account is
+required. See [documentation development](CONTRIBUTION.md#documentation) for local preview.
 
 | Guide | Covers |
 | --- | --- |
 | [Overview](https://meysamhadeli.github.io/codai) | Introduction to Codai |
+| [Quickstart](https://meysamhadeli.github.io/codai/getting-started/quickstart) | Installation, model connection, and your first session |
 | [Agent mode](https://meysamhadeli.github.io/codai/agent-mode) | Modes, approval policy, terminal controls, and session recovery |
 | [Skills](https://meysamhadeli.github.io/codai/skills) | Project and global skills |
 | [Plugins](https://meysamhadeli.github.io/codai/plugins) | Custom tools and lifecycle hooks |

docs/app/[[...mdxPath]]/page.jsx

@@ -0,0 +1,22 @@
+import { generateStaticParamsFor, importPage } from "nextra/pages";
+import { useMDXComponents as getMDXComponents } from "../../mdx-components";
+
+export const generateStaticParams = generateStaticParamsFor("mdxPath");
+
+export async function generateMetadata({ params }) {
+  const { mdxPath } = await params;
+  const { metadata } = await importPage(mdxPath);
+  return metadata;
+}
+
+const Wrapper = getMDXComponents().wrapper;
+
+export default async function Page(props) {
+  const params = await props.params;
+  const { default: Content, toc, metadata, sourceCode } = await importPage(params.mdxPath);
+  return (
+    <Wrapper toc={toc} metadata={metadata} sourceCode={sourceCode}>
+      <Content {...props} params={params} />
+    </Wrapper>
+  );
+}

docs/app/globals.css

@@ -0,0 +1,67 @@
+:root {
+  font-family: ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+}
+
+.codai-logo {
+  display: inline-flex;
+  align-items: center;
+}
+
+.codai-logo-dark,
+.dark .codai-logo-light {
+  display: none;
+}
+
+.dark .codai-logo-dark {
+  display: block;
+}
+
+.codai-start {
+  border-radius: 0.65rem;
+  padding: 0.55rem 0.9rem;
+  background: var(--codai-blue);
+  color: #0f172a;
+  font-size: 0.875rem;
+  font-weight: 650;
+  white-space: nowrap;
+}
+
+.codai-start:hover {
+  filter: brightness(1.08);
+}
+
+.codai-lead {
+  margin: 1rem 0 1.5rem;
+  font-size: 1.35rem;
+  line-height: 1.65;
+  color: #526070;
+}
+
+.dark .codai-lead {
+  color: #a3b1c2;
+}
+
+.nextra-card {
+  padding: 1.25rem;
+  gap: 0.65rem;
+  font-size: 0.9rem;
+  line-height: 1.65;
+}
+
+.nextra-card > span {
+  order: -1;
+  padding: 0;
+  font-size: 1rem;
+}
+
+@media (max-width: 480px) {
+  .codai-start {
+    padding: 0.4rem 0.6rem;
+    font-size: 0.8rem;
+  }
+
+  .codai-logo img {
+    width: 118px;
+    height: auto;
+  }
+}