feat(docs): migrate the documentation site from VitePress to Docus

.gitignore

@@ -6,11 +6,7 @@ dist/
 .nuxt/
 # Written by the Nitro `vercel` preset and by the Vercel CLI's own local link file.
 .vercel/
-/.vitepress/
-!.vitepress/config.ts
 .maizzle/
-**/.vitepress/cache/
-**/.vitepress/.temp/
 .vitehub/
 *.tsbuildinfo
 coverage/

AGENTS.md

@@ -48,7 +48,7 @@ Agent Zero is an open-source autonomous engineer that finds, fixes, and verifies
 | `packages/i18n`           | `@agent-zero/i18n`           | Locale messages and i18n tooling                                 |
 | `packages/mail`           | `@agent-zero/mail`           | Transactional mail templates                                     |
 | `apps/dashboard`          | `@agent-zero/dashboard`      | The single deployable app and composition root                   |
-| `apps/docs`               | `@agent-zero/docs`           | VitePress documentation site (not deployed with the dashboard)   |
+| `apps/docs`               | `@agent-zero/docs`           | Docus documentation site (not deployed with the dashboard)       |
 | `apps/marketing`          | `@agent-zero/marketing`      | Frontend-only public marketing site                              |
 | `apps/mail-preview`       | `@agent-zero/mail-preview`   | Dev-only Maizzle preview server for `packages/mail`              |
 
@@ -134,7 +134,7 @@ Use the smallest relevant check while iterating, then run the complete set befor
 - `packages/database`: the schema, the Drizzle client, and the checked-in migrations. The only package that talks to Postgres. No policy, no HTTP, no runtime imports.
 - `packages/auth`: authentication policy and the Better Auth options factory. Reads the store through `packages/database`. No HTTP server, no runtime imports.
 - `packages/api`: the oRPC router and control-plane operations. The only package that composes the runtime, source-control, models, and config adapters into one API surface. Holds no HTTP host of its own.
-- `apps/docs`: the VitePress documentation site. Not deployed with the dashboard. The canonical architecture and provider references remain in `docs/*.md` (the site includes them verbatim); edit those files, not copies.
+- `apps/docs`: the Docus documentation site. Not deployed with the dashboard. The canonical architecture and provider references remain in `docs/*.md` (the site includes them verbatim); edit those files, not copies.
 - `apps/mail-preview`: dev-only Maizzle preview server for `packages/mail` templates. Not deployed; nothing may import it.
 - `apps/dashboard`: the single deployable app and composition root. A Nuxt app whose `server/` directory hosts `packages/api`'s router over `/rpc/**` (typed RPC) and `/api/v1/**` (OpenAPI/REST, with docs at `/api/v1/docs`), and mounts Better Auth in-process at `/api/auth/**` via `server/auth.config.ts`. The only process that opens the database, and it does so through `packages/database`.
 - `apps/marketing`: frontend-only Nuxt public marketing site. No persistence, no credentials, no session, no runtime-package imports; nothing imports it. Server-rendered and prerendered because it must be crawlable, so the only Nitro routes are the ones `@nuxtjs/seo` generates. Copy lives in `packages/i18n` (`locales/<locale>/marketing.json`), never in the app.

CONTRIBUTING.md

@@ -51,7 +51,7 @@ Read [AGENTS.md](AGENTS.md) and the matching files in `.agents/skills/` before m
 
 If an AI agent helps you write a change, read [AI_POLICY.md](AI_POLICY.md) first: you still own the diff, you still run the checks, and you disclose the agent in the pull request.
 
-Documentation lives in `apps/docs`, a VitePress site (`aube run dev --filter=@agent-zero/docs` to preview it). The canonical architecture and provider references stay in `docs/*.md` and are included by the site — edit those files rather than duplicating their content into site pages.
+Documentation lives in `apps/docs`, a [Docus](https://docus.dev) site (`aube run dev --filter=@agent-zero/docs` to preview it). The canonical architecture and provider references stay in `docs/*.md` and are included by the site — edit those files rather than duplicating their content into site pages.
 
 ## Development workflow
 

README.md

@@ -17,7 +17,7 @@
 
 ## Documentation
 
-The full documentation — getting started, architecture, configuration, API, authentication, and deployment — lives in [`apps/docs`](./apps/docs), a VitePress site. Run it locally with `aube run dev --filter=@agent-zero/docs`. The canonical architecture and provider references stay in [`docs/`](./docs) and are included by the site, so both always read the same source.
+The full documentation — getting started, architecture, configuration, API, authentication, and deployment — lives in [`apps/docs`](./apps/docs), a [Docus](https://docus.dev) site. Run it locally with `aube run dev --filter=@agent-zero/docs`. The canonical architecture and provider references stay in [`docs/`](./docs) and are included by the site, so both always read the same source.
 
 ---
 
@@ -101,7 +101,7 @@ aube run dev
 ```
 
 The root `.env` configures the CLI. Each app loads its own file: the dashboard uses
-`apps/dashboard/.env`, while the docs app optionally uses `apps/docs/.env` for `DOCS_BASE`.
+`apps/dashboard/.env`, while the docs app optionally uses `apps/docs/.env` for `NUXT_APP_BASE_URL`.
 
 `aube run <script>` and `aube test` check install freshness first, so a separate install step is rarely needed. aube reads and writes the existing `pnpm-lock.yaml` and `pnpm-workspace.yaml` in place — the lockfile stays in pnpm's v9 format for anyone who still runs pnpm.
 

apps/docs/.env.example

@@ -1,2 +1,2 @@
-# VitePress documentation app. GitHub Pages project sites usually use `/<repository>/`.
-DOCS_BASE=/
+# Docus documentation app. GitHub Pages project sites usually use `/<repository>/`.
+NUXT_APP_BASE_URL=/

apps/docs/app/app.config.ts

@@ -0,0 +1,21 @@
+export default defineAppConfig({
+  docus: {
+    name: 'Agent Zero',
+    description:
+      'An open-source autonomous engineer that finds, fixes, and verifies problems in pull requests.',
+    socials: {
+      github: 'https://github.com/wolfstar-project/agent-zero',
+    },
+    github: {
+      url: 'https://github.com/wolfstar-project/agent-zero',
+      branch: 'main',
+      rootDir: 'apps/docs',
+    },
+  },
+  ui: {
+    colors: {
+      primary: 'green',
+      neutral: 'neutral',
+    },
+  },
+});

apps/docs/app/app.css

@@ -0,0 +1,121 @@
+/* Agent Zero brand theme, mapped from the `--az-*` custom properties the dashboard and
+   marketing apps define in their `app/assets/css/main.css`. Those apps stay the source of
+   truth for the palette; this file restates the same oklch values on Nuxt UI's semantic
+   tokens because Docus themes through Tailwind/Nuxt UI rather than raw custom properties. */
+
+@theme static {
+  --font-sans: 'Geist', 'Inter', ui-sans-serif, system-ui, sans-serif;
+  --font-mono: 'Geist Mono', ui-monospace, SFMono-Regular, Consolas, monospace;
+
+  /* Brand green ramp anchored on the two accents: 400 is the dark-mode accent
+     oklch(0.82 0.2 136), 600 the light-mode accent oklch(0.46 0.17 140). */
+  --color-green-50: oklch(0.97 0.03 138);
+  --color-green-100: oklch(0.94 0.06 138);
+  --color-green-200: oklch(0.89 0.1 137);
+  --color-green-300: oklch(0.86 0.14 137);
+  --color-green-400: oklch(0.82 0.2 136);
+  --color-green-500: oklch(0.66 0.19 138);
+  --color-green-600: oklch(0.46 0.17 140);
+  --color-green-700: oklch(0.4 0.15 140);
+  --color-green-800: oklch(0.35 0.12 141);
+  --color-green-900: oklch(0.3 0.1 141);
+  --color-green-950: oklch(0.22 0.07 142);
+
+  /* Green-tinted neutral ramp: a stock gray reads visibly wrong beside the accent, so the
+     ramp endpoints are the exact canvas/panel/raised/line/muted values from the apps. */
+  --color-neutral-50: oklch(0.985 0.004 145);
+  --color-neutral-100: oklch(0.965 0.006 145);
+  --color-neutral-200: oklch(0.93 0.01 145);
+  --color-neutral-300: oklch(0.82 0.014 145);
+  --color-neutral-400: oklch(0.7 0.018 160);
+  --color-neutral-500: oklch(0.55 0.02 155);
+  --color-neutral-600: oklch(0.44 0.025 155);
+  --color-neutral-700: oklch(0.3 0.014 160);
+  --color-neutral-800: oklch(0.22 0.014 160);
+  --color-neutral-900: oklch(0.18 0.012 160);
+  --color-neutral-950: oklch(0.15 0.012 160);
+}
+
+:root {
+  /* Square corners: the brand renders no radius on panels or controls. */
+  --ui-radius: 0;
+
+  /* Light mode = the exact light `--az-*` values. */
+  --ui-bg: oklch(0.985 0.004 145); /* canvas */
+  --ui-bg-muted: oklch(0.965 0.006 145); /* panel */
+  --ui-bg-elevated: oklch(0.93 0.01 145); /* raised */
+  --ui-bg-accented: oklch(0.9 0.012 145);
+  --ui-bg-inverted: oklch(0.15 0.012 160);
+  --ui-border: oklch(0.82 0.014 145); /* line */
+  --ui-border-muted: oklch(0.88 0.012 145);
+  --ui-border-accented: oklch(0.82 0.014 145);
+  --ui-border-inverted: oklch(0.3 0.014 160);
+  --ui-text-dimmed: oklch(0.55 0.02 150);
+  --ui-text-muted: oklch(0.44 0.025 155); /* muted */
+  --ui-text-toned: oklch(0.35 0.022 155);
+  --ui-text: oklch(0.26 0.02 155);
+  --ui-text-highlighted: oklch(0.18 0.018 155); /* ink */
+  --ui-text-inverted: oklch(0.96 0.008 145);
+  --ui-primary: oklch(0.46 0.17 140); /* accent */
+  --ui-warning: oklch(0.55 0.14 75);
+  --ui-error: oklch(0.55 0.2 25);
+  --ui-info: oklch(0.48 0.17 250);
+
+  /* The theme-aware brand SVGs in public/ read these two. */
+  --az-accent: var(--ui-primary);
+  --az-ink: var(--ui-text-highlighted);
+  --az-grid: color-mix(in oklch, var(--ui-primary) 5%, transparent);
+}
+
+.dark {
+  --ui-bg: oklch(0.15 0.012 160); /* canvas */
+  --ui-bg-muted: oklch(0.18 0.012 160); /* panel */
+  --ui-bg-elevated: oklch(0.22 0.014 160); /* raised */
+  --ui-bg-accented: oklch(0.25 0.014 160);
+  --ui-bg-inverted: oklch(0.985 0.004 145);
+  --ui-border: oklch(0.3 0.014 160); /* line */
+  --ui-border-muted: oklch(0.26 0.014 160);
+  --ui-border-accented: oklch(0.3 0.014 160);
+  --ui-border-inverted: oklch(0.82 0.014 145);
+  --ui-text-dimmed: oklch(0.55 0.02 160);
+  --ui-text-muted: oklch(0.7 0.018 160); /* muted */
+  --ui-text-toned: oklch(0.82 0.012 155);
+  --ui-text: oklch(0.9 0.01 150);
+  --ui-text-highlighted: oklch(0.96 0.008 145); /* ink */
+  --ui-text-inverted: oklch(0.18 0.018 155);
+  --ui-primary: oklch(0.82 0.2 136); /* accent */
+  --ui-warning: oklch(0.82 0.15 80);
+  --ui-error: oklch(0.68 0.2 25);
+  --ui-info: oklch(0.73 0.15 250);
+
+  --az-accent: var(--ui-primary);
+  --az-ink: var(--ui-text-highlighted);
+  --az-grid: color-mix(in oklch, var(--ui-primary) 3%, transparent);
+}
+
+/* Signature canvas: the same 32px accent-tinted graph-paper grid the dashboard and
+   marketing sites draw on their body. */
+body {
+  background:
+    linear-gradient(var(--az-grid) 1px, transparent 1px),
+    linear-gradient(90deg, var(--az-grid) 1px, transparent 1px), var(--ui-bg);
+  background-size:
+    32px 32px,
+    32px 32px,
+    100% 100%;
+  background-repeat: repeat, repeat, no-repeat;
+}
+
+::selection {
+  color: var(--ui-bg);
+  background: var(--ui-primary);
+}
+
+:focus-visible {
+  outline: 2px solid var(--ui-primary);
+  outline-offset: 2px;
+}
+
+* {
+  scrollbar-color: var(--ui-border) var(--ui-bg);
+}

apps/docs/content/1.guide/.navigation.yml

@@ -0,0 +1,2 @@
+title: Guide
+icon: i-lucide-book-open

apps/docs/guide/introduction.md → apps/docs/content/1.guide/1.introduction.md

@@ -1,4 +1,6 @@
-# What is Agent Zero?
+---
+title: What is Agent Zero?
+---
 
 Agent Zero is an open-source autonomous engineer that finds, fixes, and verifies problems in pull requests.
 

apps/docs/content/1.guide/10.api/.navigation.yml

@@ -0,0 +1,2 @@
+title: API
+icon: i-lucide-plug

apps/docs/guide/api/overview.md → apps/docs/content/1.guide/10.api/1.overview.md

@@ -1,4 +1,6 @@
-# API overview
+---
+title: API overview
+---
 
 Agent Zero exposes one typed router — `rpcRouter` from `packages/api` — served over two wire protocols by the dashboard's Nitro server. Authorization behaves identically either way, because both transports serve the exact same procedures.
 

apps/docs/guide/api/define-endpoints.md → apps/docs/content/1.guide/10.api/2.define-endpoints.md

@@ -1,4 +1,6 @@
-# Define endpoints
+---
+title: Define endpoints
+---
 
 Procedures are defined once in `packages/api/src/orpc/router.ts` and served over both transports automatically. Before changing routes, read the `orpc-server` [Agent Skill](/guide/codebase/agent-skills).
 

apps/docs/guide/api/use-from-client.md → apps/docs/content/1.guide/10.api/3.use-from-client.md

@@ -1,4 +1,6 @@
-# Use the API from a client
+---
+title: Use the API from a client
+---
 
 ## Typed TypeScript clients
 

apps/docs/guide/api/protect-endpoints.md → apps/docs/content/1.guide/10.api/4.protect-endpoints.md

@@ -1,4 +1,6 @@
-# Protect endpoints
+---
+title: Protect endpoints
+---
 
 The control plane fails closed. Reads (`tasks.list`, `tasks.get`, `health`) stay open for the dashboard; every mutation requires an operator-issued bearer credential, and without configuration every mutation is rejected.
 

apps/docs/content/1.guide/11.authentication/.navigation.yml

@@ -0,0 +1,2 @@
+title: Authentication
+icon: i-lucide-lock