feat(docs): mount docs site at /docs subpath via basePath + multi-zone

Configure the Fumadocs site so it can be served at multica.ai/docs:

- Add basePath: '/docs' to apps/docs/next.config.mjs
- Flatten routes: drop standalone home, render content/docs/index.mdx at
  the root, move catch-all from app/docs/[[...slug]] to app/[...slug]
- Wrap children with DocsLayout in the root layout (was a separate
  segment-level layout under app/docs/)
- Set source loader baseUrl to '/' so URL slugs no longer carry the
  basePath (Next.js prepends it automatically)
- Strip the now-redundant '/docs/' prefix from internal MDX links and
  drop the duplicate "Documentation" nav entry
- Add app/not-found.tsx for App Router 404 handling

Wire up multi-zone routing so apps/web proxies /docs/* to the docs app:

- Add DOCS_URL env (default http://localhost:4000) and rewrites for
  /docs and /docs/:path* in apps/web/next.config.ts
- Whitelist DOCS_URL in turbo.json globalEnv

apps/docs/app/(home)/layout.tsx

@@ -1,7 +0,0 @@
-import type { ReactNode } from "react";
-import { HomeLayout } from "fumadocs-ui/layouts/home";
-import { baseOptions } from "@/app/layout.config";
-
-export default function Layout({ children }: { children: ReactNode }) {
-  return <HomeLayout {...baseOptions}>{children}</HomeLayout>;
-}

apps/docs/app/(home)/page.tsx

@@ -1,29 +0,0 @@
-import Link from "next/link";
-
-export default function HomePage() {
-  return (
-    <main className="flex min-h-screen flex-col items-center justify-center gap-6 text-center px-4">
-      <h1 className="text-4xl font-bold tracking-tight sm:text-5xl">
-        Multica Documentation
-      </h1>
-      <p className="max-w-2xl text-lg text-fd-muted-foreground">
-        The open-source managed agents platform. Turn coding agents into real
-        teammates — assign tasks, track progress, compound skills.
-      </p>
-      <div className="flex gap-4">
-        <Link
-          href="/docs"
-          className="inline-flex items-center rounded-md bg-fd-primary px-6 py-3 text-sm font-medium text-fd-primary-foreground transition-colors hover:bg-fd-primary/90"
-        >
-          Get Started
-        </Link>
-        <Link
-          href="https://github.com/multica-ai/multica"
-          className="inline-flex items-center rounded-md border border-fd-border px-6 py-3 text-sm font-medium transition-colors hover:bg-fd-accent"
-        >
-          GitHub
-        </Link>
-      </div>
-    </main>
-  );
-}

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

@@ -10,7 +10,7 @@ import defaultMdxComponents from "fumadocs-ui/mdx";
 import type { Metadata } from "next";
 
 export default async function Page(props: {
-  params: Promise<{ slug?: string[] }>;
+  params: Promise<{ slug: string[] }>;
 }) {
   const params = await props.params;
   const page = source.getPage(params.slug);
@@ -29,12 +29,12 @@ export default async function Page(props: {
   );
 }
 
-export async function generateStaticParams() {
-  return source.generateParams();
+export function generateStaticParams() {
+  return source.generateParams().filter((p) => p.slug.length > 0);
 }
 
 export async function generateMetadata(props: {
-  params: Promise<{ slug?: string[] }>;
+  params: Promise<{ slug: string[] }>;
 }): Promise<Metadata> {
   const params = await props.params;
   const page = source.getPage(params.slug);

apps/docs/app/docs/layout.tsx

@@ -1,12 +0,0 @@
-import { DocsLayout } from "fumadocs-ui/layouts/docs";
-import type { ReactNode } from "react";
-import { baseOptions } from "@/app/layout.config";
-import { source } from "@/lib/source";
-
-export default function Layout({ children }: { children: ReactNode }) {
-  return (
-    <DocsLayout tree={source.pageTree} {...baseOptions}>
-      {children}
-    </DocsLayout>
-  );
-}

apps/docs/app/layout.config.tsx

@@ -1,5 +1,4 @@
 import type { BaseLayoutProps } from "fumadocs-ui/layouts/shared";
-import { BookOpen, Terminal, Rocket, Code } from "lucide-react";
 
 export const baseOptions: BaseLayoutProps = {
   nav: {
@@ -8,11 +7,6 @@ export const baseOptions: BaseLayoutProps = {
     ),
   },
   links: [
-    {
-      text: "Documentation",
-      url: "/docs",
-      active: "nested-url",
-    },
     {
       text: "GitHub",
       url: "https://github.com/multica-ai/multica",

apps/docs/app/layout.tsx

@@ -1,7 +1,10 @@
 import "./global.css";
 import { RootProvider } from "fumadocs-ui/provider";
+import { DocsLayout } from "fumadocs-ui/layouts/docs";
 import type { ReactNode } from "react";
 import type { Metadata } from "next";
+import { baseOptions } from "@/app/layout.config";
+import { source } from "@/lib/source";
 
 export const metadata: Metadata = {
   title: {
@@ -16,7 +19,11 @@ export default function Layout({ children }: { children: ReactNode }) {
   return (
     <html lang="en" suppressHydrationWarning>
       <body>
-        <RootProvider>{children}</RootProvider>
+        <RootProvider>
+          <DocsLayout tree={source.pageTree} {...baseOptions}>
+            {children}
+          </DocsLayout>
+        </RootProvider>
       </body>
     </html>
   );

apps/docs/app/not-found.tsx

@@ -0,0 +1,18 @@
+import Link from "next/link";
+
+export default function NotFound() {
+  return (
+    <main className="flex flex-1 flex-col items-center justify-center gap-4 px-4 py-24 text-center">
+      <h1 className="text-3xl font-semibold">Page not found</h1>
+      <p className="text-fd-muted-foreground">
+        The page you are looking for doesn&apos;t exist.
+      </p>
+      <Link
+        href="/"
+        className="inline-flex items-center rounded-md bg-fd-primary px-4 py-2 text-sm font-medium text-fd-primary-foreground transition-colors hover:bg-fd-primary/90"
+      >
+        Back to docs
+      </Link>
+    </main>
+  );
+}

apps/docs/app/page.tsx

@@ -0,0 +1,37 @@
+import { source } from "@/lib/source";
+import {
+  DocsPage,
+  DocsBody,
+  DocsDescription,
+  DocsTitle,
+} from "fumadocs-ui/page";
+import { notFound } from "next/navigation";
+import defaultMdxComponents from "fumadocs-ui/mdx";
+import type { Metadata } from "next";
+
+export default function Page() {
+  const page = source.getPage([]);
+  if (!page) notFound();
+
+  const MDX = page.data.body;
+
+  return (
+    <DocsPage toc={page.data.toc}>
+      <DocsTitle>{page.data.title}</DocsTitle>
+      <DocsDescription>{page.data.description}</DocsDescription>
+      <DocsBody>
+        <MDX components={{ ...defaultMdxComponents }} />
+      </DocsBody>
+    </DocsPage>
+  );
+}
+
+export function generateMetadata(): Metadata {
+  const page = source.getPage([]);
+  if (!page) notFound();
+
+  return {
+    title: page.data.title,
+    description: page.data.description,
+  };
+}

apps/docs/content/docs/cli/installation.mdx

@@ -68,7 +68,7 @@ multica setup
 
 This configures the CLI for Multica Cloud, opens your browser for login, discovers your workspaces, and starts the agent daemon.
 
-For self-hosted servers, use `multica setup self-host` instead. See [Self-Hosting](/docs/getting-started/self-hosting) for details.
+For self-hosted servers, use `multica setup self-host` instead. See [Self-Hosting](/getting-started/self-hosting) for details.
 
 ## Verify
 

apps/docs/content/docs/index.mdx

@@ -41,7 +41,7 @@ No more copy-pasting prompts. No more babysitting runs. Your agents show up on t
 
 ## Next Steps
 
-- [Cloud Quickstart](/docs/getting-started/cloud-quickstart)
-- [Self-Hosting](/docs/getting-started/self-hosting)
-- [CLI Installation](/docs/cli/installation)
-- [Contributing](/docs/developers/contributing)
+- [Cloud Quickstart](/getting-started/cloud-quickstart)
+- [Self-Hosting](/getting-started/self-hosting)
+- [CLI Installation](/cli/installation)
+- [Contributing](/developers/contributing)

apps/docs/lib/source.ts

@@ -2,6 +2,6 @@ import { docs } from "@/.source";
 import { loader } from "fumadocs-core/source";
 
 export const source = loader({
-  baseUrl: "/docs",
+  baseUrl: "/",
   source: docs.toFumadocsSource(),
 });

apps/docs/next.config.mjs

@@ -5,6 +5,7 @@ const withMDX = createMDX();
 /** @type {import('next').NextConfig} */
 const config = {
   reactStrictMode: true,
+  basePath: "/docs",
 };
 
 export default withMDX(config);

apps/web/next.config.ts

@@ -6,6 +6,7 @@ import { resolve } from "path";
 config({ path: resolve(__dirname, "../../.env") });
 
 const remoteApiUrl = process.env.REMOTE_API_URL || "http://localhost:8080";
+const docsUrl = process.env.DOCS_URL || "http://localhost:4000";
 
 // Parse hostnames from CORS_ALLOWED_ORIGINS so that Next.js dev server
 // allows cross-origin HMR / webpack requests (e.g. from Tailscale IPs).
@@ -49,6 +50,14 @@ const nextConfig: NextConfig = {
         source: "/uploads/:path*",
         destination: `${remoteApiUrl}/uploads/:path*`,
       },
+      {
+        source: "/docs",
+        destination: `${docsUrl}/docs`,
+      },
+      {
+        source: "/docs/:path*",
+        destination: `${docsUrl}/docs/:path*`,
+      },
     ];
   },
 };

turbo.json

@@ -8,6 +8,7 @@
     "NEXT_PUBLIC_API_URL",
     "NEXT_PUBLIC_WS_URL",
     "MULTICA_SERVER_URL",
+    "DOCS_URL",
     "COMPOSE_PROJECT_NAME",
     "POSTGRES_DB",
     "POSTGRES_PORT"