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

[RedStar071]

Rebuild apps/docs on Docus (Nuxt 4 + Nuxt UI + @nuxt/content) with a custom theme that restates the dashboard/marketing brand tokens on Nuxt UI's semantic variables: the green accent and green-tinted neutrals from the apps' --az-* palette, dark-first color mode, square corners, the 32px accent-tinted grid canvas, and the theme-aware brand SVGs from apps/marketing/public.

The canonical docs/*.md files stay the single source: a content:file:beforeParse hook re-implements VitePress's "" directives, and a missing file or region fails a production build so include drift cannot ship (@nuxt/content alone would downgrade the parse failure to a warning and drop the page).

Content moves to the numbered content/ tree Docus derives navigation from; numeric prefixes are stripped from routes, so every existing /guide/... and /reference/... URL is preserved. VitePress containers become MDC callouts, page H1s move into frontmatter titles, and the landing page is rebuilt with u-page-hero and u-page-feature.

Wiring follows apps/marketing: turbo outputs .output/**, the base-path env becomes NUXT_APP_BASE_URL, vercel.json switches to the nuxtjs framework, knip gets a Nuxt-shaped entry, and @nuxt/content uses Node's built-in sqlite instead of better-sqlite3 so no native build step is required.

Verified with a standalone build: prerender succeeds, all 15 includes resolve, callouts and the landing page render, and a misspelled region fails the build. pnpm-lock.yaml is not updated here because this environment's egress policy blocks pkg.pr.new (the pinned @lunariajs/core tarball packages/i18n already depends on); run aube install once where that host is reachable to record the docus subtree in the lockfile.

Claude-Session: https://claude.ai/code/session_012SK7GND614AB6qpZ51aPFx

Summary

Why

Verification

• aube run check:repo
• aube run lint:ci
• aube run typecheck
• aube test
• aube run build

Safety and compatibility

• I added or updated deterministic tests for changed behavior.
• I preserved observe mode as read-only, or explained the policy change above.
• Runtime commands and target-repository writes remain inside the runner boundary.
• I did not expose secrets, tokens, personal data, or untrusted output in logs.
• I updated documentation and Agent Skills when workflows or boundaries changed.

Agent context

• Agent/tools used:
• What the agent did, and what you changed or verified yourself:

Reviewer notes

Note

Migrate apps/docs from VitePress to Docus (Nuxt)

• Replaces VitePress with Docus/Nuxt across nuxt.config.ts, package.json, vercel.json, and turbo.jsonc; env var DOCS_BASE becomes NUXT_APP_BASE_URL and build outputs move from .vitepress/dist to .output.
• Adds a custom content hook in nuxt.config.ts to resolve VitePress-style <!--@include: path#region--> directives at content-parse time, with recursive include support and strict abort on production build failures.
• Migrates all guide/reference pages to the Docus content tree with frontmatter titles, .navigation.yml metadata, and ::warning/::tip admonition syntax replacing VitePress ::: blocks.
• Adds a new Docus landing page (content/index.md), brand theme CSS (app/app.css), and app config (app/app.config.ts) with Nuxt UI color tokens.
• Risk: the custom @include hook in nuxt.config.ts aborts the production build if any include path fails to resolve; canonical docs under docs/*.md are now build inputs via turbo.jsonc so missing changes there can fail the docs build.

^{Macroscope summarized fdc6e18.}

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
agent-zero-dashboard	Ready	Preview	Aug 20, 2026 12:35pm
agent-zero-docs	Ready	Preview	Aug 20, 2026 12:35pm
agent-zero-marketing	Ready	Preview	Aug 20, 2026 12:35pm

[macroscopeapp]

Approvability

Verdict: Approved at fdc6e18

Macroscope's review found this PR approvable — Documentation tooling migration from VitePress to Docus with no runtime application impact. Changes are mechanical file reorganization and config translation for an isolated docs site.

^{You can add or adjust custom eligibility rules. Learn more.}

[socket-security]

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	docus@​5.12.3
	better-sqlite3@​12.11.1

View full report

[socket-security]

Warning

Review the following alerts detected in dependencies.

According to your organization's Security Policy, it is recommended to resolve "Warn" alerts. Learn more about Socket for GitHub.

Action	Severity	Alert  (click "▶" to expand/collapse)
Warn		Obfuscated code: npm @tanstack/table-core is 90.0% likely obfuscated Confidence: 0.90 Location: Package overview From: pnpm-lock.yaml → npm/docus@5.12.3 → npm/@tanstack/table-core@8.21.3 ℹ Read more on: This package | This alert | What is obfuscated code? Next steps: Take a moment to review the security alert above. Review the linked package source code to understand the potential risk. Ensure the package is not malicious before proceeding. If you're unsure how to proceed, reach out to your security team or ask the Socket team for help at support@socket.dev. Suggestion: Packages should not obfuscate their code. Consider not using packages with obfuscated code. Mark the package as acceptable risk. To ignore this alert only in this pull request, reply with the comment @SocketSecurity ignore npm/@tanstack/table-core@8.21.3. You can also ignore all packages with @SocketSecurity ignore-all. To ignore an alert for all future pull requests, use Socket's Dashboard to change the triage state of this alert.
Warn		Obfuscated code: npm better-sqlite3 is 90.0% likely obfuscated Confidence: 0.90 Location: Package overview From: pnpm-lock.yaml → npm/better-sqlite3@12.11.1 ℹ Read more on: This package | This alert | What is obfuscated code? Next steps: Take a moment to review the security alert above. Review the linked package source code to understand the potential risk. Ensure the package is not malicious before proceeding. If you're unsure how to proceed, reach out to your security team or ask the Socket team for help at support@socket.dev. Suggestion: Packages should not obfuscate their code. Consider not using packages with obfuscated code. Mark the package as acceptable risk. To ignore this alert only in this pull request, reply with the comment @SocketSecurity ignore npm/better-sqlite3@12.11.1. You can also ignore all packages with @SocketSecurity ignore-all. To ignore an alert for all future pull requests, use Socket's Dashboard to change the triage state of this alert.
Warn		Obfuscated code: npm embla-carousel is 90.0% likely obfuscated Confidence: 0.90 Location: Package overview From: pnpm-lock.yaml → npm/docus@5.12.3 → npm/embla-carousel@8.6.0 ℹ Read more on: This package | This alert | What is obfuscated code? Next steps: Take a moment to review the security alert above. Review the linked package source code to understand the potential risk. Ensure the package is not malicious before proceeding. If you're unsure how to proceed, reach out to your security team or ask the Socket team for help at support@socket.dev. Suggestion: Packages should not obfuscate their code. Consider not using packages with obfuscated code. Mark the package as acceptable risk. To ignore this alert only in this pull request, reply with the comment @SocketSecurity ignore npm/embla-carousel@8.6.0. You can also ignore all packages with @SocketSecurity ignore-all. To ignore an alert for all future pull requests, use Socket's Dashboard to change the triage state of this alert.

View full report