init: scaffold doc.moleculesai.app with Fumadocs + Next.js 15

Customer-facing documentation site for Molecule AI. Built with Fumadocs
(open-source MIT, Next.js 15 App Router native, Tailwind v4, MDX) so we
own the deployment and aesthetic and can grow into custom doc components
for our agent-canvas flows.

## Why Fumadocs (over Mintlify, Nextra, Docusaurus)
- Open source, no vendor lock-in (vs Mintlify SaaS subscription)
- Built on Next.js 15 App Router — matches our existing canvas stack
- Less opinionated than Nextra; can grow into custom doc components
- React/Tailwind first; team already on this stack
- Ships search, dark mode, Shiki highlighting, MDX out of the box

## Initial structure
- app/                 — Next.js App Router (home + docs + search route)
- content/docs/        — MDX source (3 hand-written + 9 stub pages)
- lib/source.ts        — Fumadocs loader bound to the MDX content
- mdx-components.tsx   — default + future custom MDX renderers
- source.config.ts     — MDX compile config

## Hand-written launch content
- index.mdx     — landing / what you can build / how it works
- quickstart.mdx — clone repo → docker compose → import template → talk to PM
- concepts.mdx  — the five primitives: workspaces / plugins / channels / schedules / canvas

## Stub pages (Documentation Specialist agent fills these in on cron)
- org-template, plugins, channels, schedules
- architecture, api-reference, self-hosting
- observability, troubleshooting

## Ownership
The Documentation Specialist agent in the molecule-dev org template will
own this repo end-to-end:
- Watches PRs landing in the platform monorepo
- Auto-opens docs PRs when public APIs / templates / plugins / channels change
- Runs daily cron to backfill stubs and refresh stale pages

Manual edits welcome. Agent picks up on next cron tick.
This commit is contained in:
rabbitblood 2026-04-14 21:01:17 -07:00
commit 7cdc0bc9b4
30 changed files with 727 additions and 0 deletions

44
.gitignore vendored Normal file
View File

@ -0,0 +1,44 @@
# dependencies
/node_modules
/.pnp
.pnp.*
.yarn/*
!.yarn/patches
!.yarn/plugins
!.yarn/releases
!.yarn/versions
# testing
/coverage
# next.js
/.next/
/out/
# fumadocs generated source
/.source/
# production
/build
# misc
.DS_Store
*.pem
# debug
npm-debug.log*
yarn-debug.log*
yarn-error.log*
.pnpm-debug.log*
# env files
.env*.local
.env
# typescript
*.tsbuildinfo
next-env.d.ts
# IDE
.vscode/
.idea/

86
README.md Normal file
View File

@ -0,0 +1,86 @@
# Molecule AI Documentation
The customer-facing documentation site for Molecule AI, deployed at
[doc.moleculesai.app](https://doc.moleculesai.app).
Built with **[Fumadocs](https://fumadocs.dev)** + Next.js 15 (App Router) +
Tailwind v4 + MDX.
## Why Fumadocs
- **Open source** (MIT) — we self-host on our own domain, no vendor lock-in
- **Next.js 15 native** — matches the canvas stack already in the platform monorepo
- **Flexible** — can grow into custom doc components for our agent canvas
flows, embedded mini-canvases in docs, etc.
- **Modern aesthetic** — Shiki code highlighting, full-text search, dark
mode, all out of the box
## Local development
```bash
npm install
npm run dev
```
Visit [http://localhost:3000](http://localhost:3000).
## Adding pages
1. Create a new `.mdx` file under `content/docs/`.
2. Add an entry to `content/docs/meta.json` to control sidebar ordering.
3. Frontmatter: `title` and `description` are required.
```mdx
---
title: My new page
description: One-line summary used in nav + meta tags.
---
Content goes here.
```
## Repository layout
```
.
├── app/ # Next.js App Router routes
│ ├── (home)/ # marketing landing
│ ├── docs/[[...slug]]/ # docs dynamic route
│ ├── api/search/ # built-in full-text search
│ ├── layout.tsx # root layout + RootProvider
│ └── layout.config.tsx # nav links shared by home + docs
├── content/docs/ # MDX source — the actual documentation
│ ├── meta.json # sidebar order
│ ├── index.mdx # docs landing
│ └── *.mdx # one file per page
├── lib/source.ts # Fumadocs loader bound to the MDX source
├── mdx-components.tsx # default + custom MDX renderers
├── source.config.ts # MDX compile config (remark/rehype plugins)
├── next.config.mjs # Next config wrapped with createMDX
├── postcss.config.mjs # Tailwind v4 postcss plugin
└── package.json
```
## Who maintains this
The **Documentation Specialist** agent in our `molecule-dev` org template
owns this repo end-to-end. It runs on a schedule, watches PRs landing in the
[platform monorepo](https://github.com/Molecule-AI/molecule-monorepo), and
opens docs PRs here whenever:
- A new public API endpoint lands
- A new template / plugin / channel is added
- A user-facing concept changes
- An ecosystem-watch entry needs publishing
Manual edits welcome. The agent picks up changes on its next cron tick.
## Deployment
This site is deployed to `doc.moleculesai.app` via Vercel (TBD — once the
domain is configured). PRs to `main` ship to preview URLs automatically.
## Contributing
Open a PR. The Documentation Specialist + a human reviewer will look at it
within one cron tick (currently daily).

7
app/(home)/layout.tsx Normal file
View File

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

29
app/(home)/page.tsx Normal file
View File

@ -0,0 +1,29 @@
import Link from 'next/link';
export default function HomePage() {
return (
<main className="flex flex-1 flex-col items-center justify-center px-6 py-24 text-center">
<h1 className="mb-4 text-5xl font-bold tracking-tight sm:text-6xl">
Molecule AI
</h1>
<p className="mb-8 max-w-2xl text-lg text-fd-muted-foreground">
Build and run multi-agent organisations. Templates, plugins, channels,
and the runtime that ties them together documented end to end.
</p>
<div className="flex flex-wrap items-center justify-center gap-3">
<Link
href="/docs"
className="rounded-md bg-fd-primary px-5 py-2.5 text-sm font-medium text-fd-primary-foreground transition-colors hover:opacity-90"
>
Read the docs
</Link>
<Link
href="https://github.com/Molecule-AI/molecule-monorepo"
className="rounded-md border border-fd-border px-5 py-2.5 text-sm font-medium transition-colors hover:bg-fd-muted"
>
View on GitHub
</Link>
</div>
</main>
);
}

4
app/api/search/route.ts Normal file
View File

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

View File

@ -0,0 +1,46 @@
import { source } from '@/lib/source';
import {
DocsBody,
DocsDescription,
DocsPage,
DocsTitle,
} from 'fumadocs-ui/page';
import { notFound } from 'next/navigation';
import { getMDXComponents } from '@/mdx-components';
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 MDXContent = page.data.body;
return (
<DocsPage toc={page.data.toc} full={page.data.full}>
<DocsTitle>{page.data.title}</DocsTitle>
<DocsDescription>{page.data.description}</DocsDescription>
<DocsBody>
<MDXContent components={getMDXComponents()} />
</DocsBody>
</DocsPage>
);
}
export async 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,
};
}

12
app/docs/layout.tsx Normal file
View File

@ -0,0 +1,12 @@
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>
);
}

3
app/global.css Normal file
View File

@ -0,0 +1,3 @@
@import 'tailwindcss';
@import 'fumadocs-ui/css/neutral.css';
@import 'fumadocs-ui/css/preset.css';

21
app/layout.config.tsx Normal file
View File

@ -0,0 +1,21 @@
import type { BaseLayoutProps } from 'fumadocs-ui/layouts/shared';
export const baseOptions: BaseLayoutProps = {
nav: {
title: (
<span className="font-semibold tracking-tight">Molecule AI</span>
),
},
links: [
{
text: 'Documentation',
url: '/docs',
active: 'nested-url',
},
{
text: 'GitHub',
url: 'https://github.com/Molecule-AI/molecule-monorepo',
external: true,
},
],
};

28
app/layout.tsx Normal file
View File

@ -0,0 +1,28 @@
import './global.css';
import { RootProvider } from 'fumadocs-ui/provider';
import { Inter } from 'next/font/google';
import type { ReactNode } from 'react';
const inter = Inter({
subsets: ['latin'],
});
export const metadata = {
title: {
default: 'Molecule AI Documentation',
template: '%s | Molecule AI Docs',
},
description:
'Build and run multi-agent organisations on the Molecule AI platform. Templates, plugins, channels, and the runtime that ties them together.',
metadataBase: new URL('https://doc.moleculesai.app'),
};
export default function Layout({ children }: { children: ReactNode }) {
return (
<html lang="en" className={inter.className} suppressHydrationWarning>
<body className="flex flex-col min-h-screen">
<RootProvider>{children}</RootProvider>
</body>
</html>
);
}

View File

@ -0,0 +1,11 @@
---
title: Api Reference
description: Stub page — content coming soon.
---
> 🚧 **Coming soon.** The Documentation Specialist agent will populate this
> page on its next maintenance cycle.
If you need this content urgently, open an issue on the
[docs repo](https://github.com/Molecule-AI/docs/issues/new) and the agent
will prioritise it on its next cron tick.

View File

@ -0,0 +1,11 @@
---
title: Architecture
description: Stub page — content coming soon.
---
> 🚧 **Coming soon.** The Documentation Specialist agent will populate this
> page on its next maintenance cycle.
If you need this content urgently, open an issue on the
[docs repo](https://github.com/Molecule-AI/docs/issues/new) and the agent
will prioritise it on its next cron tick.

11
content/docs/channels.mdx Normal file
View File

@ -0,0 +1,11 @@
---
title: Channels
description: Stub page — content coming soon.
---
> 🚧 **Coming soon.** The Documentation Specialist agent will populate this
> page on its next maintenance cycle.
If you need this content urgently, open an issue on the
[docs repo](https://github.com/Molecule-AI/docs/issues/new) and the agent
will prioritise it on its next cron tick.

105
content/docs/concepts.mdx Normal file
View File

@ -0,0 +1,105 @@
---
title: Concepts
description: The five primitives that compose every Molecule AI org — workspaces, plugins, channels, schedules, and the canvas.
---
If you understand these five concepts, you understand the whole platform.
## Workspaces
A **workspace** is a real Docker container running a real LLM agent. Each
workspace has:
- A **role** (a one-line job description fed into its system prompt)
- An **initial prompt** (run once at first boot — typically clone repo,
read CLAUDE.md, memorise context)
- A **runtime** (`claude-code`, `langgraph`, `crewai`, `autogen`, etc.)
- A **tier** (resource budget — memory and CPU caps)
- An optional **parent** (forms the org tree)
- An optional **workspace_dir** (a host path bind-mounted into the
container — gives the agent direct access to your codebase)
Workspaces talk to each other via A2A (agent-to-agent) messages, routed
by the platform. Every message becomes an edge on the canvas in real
time.
## Plugins
A **plugin** is a bundle of capabilities a workspace can install:
- **Hooks** — `PreToolUse`, `PostToolUse`, `UserPromptSubmit` — for
guardrails, audit trails, dangerous-command refusal
- **Skills** — multi-criteria code review, cross-vendor adversarial
review, LLM-as-judge gates
- **Slash commands** — `/triage`, `/retro`, etc.
- **MCP servers** — bring in tools the model can call
- **Builtin tools** — Python/JS extensions exposed to the agent
Plugins compose. Per-workspace plugin lists UNION with the org-wide
defaults — so adding one extra capability to one role doesn't require
re-listing every default.
## Channels
A **channel** wires a workspace to an external messaging surface:
Telegram, Slack, Discord, email, webhooks. Once connected, the user can
talk to the agent from outside the canvas — and the agent can broadcast
back.
## Schedules
A **schedule** is a cron-driven recurring prompt. Each tick fires an A2A
message into the workspace, which the agent treats as a new task. Every
running schedule is supervised — panics in the dispatch path are
recovered with exponential backoff, and a liveness watchdog surfaces
stuck subsystems via `/admin/liveness`.
Schedules let you build the *evolution* loop alongside the *review*
loop: hourly security audits, daily ecosystem watches, weekly plugin
curation, etc.
## The canvas
The **canvas** is a Next.js 15 React Flow visualisation of your org.
Every workspace is a node. Every A2A message is an edge. Every memory
write, every scheduled fire, every status change pushes a WebSocket
event in real time.
The canvas isn't just a viewer — it's the operator surface. Drag nodes
to reorganise, click to chat, watch the team work.
## How they fit together
A typical org definition looks like:
```yaml
org_name: My Team
defaults:
runtime: claude-code
tier: 2
plugins: [ecc, molecule-dev, superpowers, molecule-careful-bash, ...]
category_routing:
security: [Backend Engineer]
ui: [Frontend Engineer]
workspaces:
- name: PM
canvas: { x: 400, y: 50 }
plugins: [molecule-workflow-triage, molecule-workflow-retro]
channels:
- type: telegram
config: { ... }
children:
- name: Dev Lead
children:
- name: Frontend Engineer
- name: Backend Engineer
schedules:
- name: Hourly typecheck
cron_expr: "0 * * * *"
prompt: "Run npm run typecheck and report any new errors..."
```
That's the entire mental model. Templates → plugins → channels →
schedules → canvas. Everything else in the docs is depth on one of
these five.

52
content/docs/index.mdx Normal file
View File

@ -0,0 +1,52 @@
---
title: Welcome to Molecule AI
description: Multi-agent organisations as code — templates, plugins, channels, and the runtime that ties them together.
---
Molecule AI is an open platform for building, running, and operating
multi-agent organisations. You define your team in one YAML file
(`org.yaml`), pick the plugins each role needs, wire up the channels they
talk on, schedule their recurring work — and the platform takes care of the
rest.
## What you can build
- **Self-running engineering teams** — PM, Dev Lead, frontend / backend / devops
agents, security auditor, QA — all coordinating through A2A messages and
scheduled audits, opening real PRs to your real repo.
- **Research squads** — market analysts, technical researchers, competitive
intelligence agents that sweep the web on a cadence and write findings to
shared memory.
- **Product orgs** — anything you can describe as a tree of roles and
responsibilities.
## How it works
1. **Templates.** Describe your org as a YAML tree of workspaces. Each workspace
is a real container running an LLM agent. Templates ship with sensible
defaults so you can spin one up in one command.
2. **Plugins.** Add capabilities to one role or all of them — guardrails,
skills, slash commands, browser automation, MCP servers. Plugins compose;
per-role overrides UNION with the defaults.
3. **Channels.** Connect any role to Telegram, Slack, email, or webhooks so
the user can talk to it directly.
4. **Schedules.** Define recurring work in cron syntax. The runtime fires the
prompt at the scheduled time, supervised against panics with a liveness
watchdog so a single bad input can't silently kill the loop.
5. **The canvas.** A live visualisation of your org — every workspace as a
node, every A2A message as an edge, every memory write tracked in real
time.
## Where to next
- New here? Read the [Quickstart](/docs/quickstart) — spin up your first
agent in under five minutes.
- Want the architecture tour? Start with [Concepts](/docs/concepts) and
[Architecture](/docs/architecture).
- Ready to build your own org? Jump straight to
[Org Templates](/docs/org-template).
> This documentation is maintained automatically by the
> Documentation Specialist agent in our own dogfood org. Every PR to the
> platform repo triggers a docs sync. Spot something stale? Open an issue or
> a PR — those signals reach the agent on its next cron tick.

21
content/docs/meta.json Normal file
View File

@ -0,0 +1,21 @@
{
"title": "Documentation",
"pages": [
"index",
"---Getting Started---",
"quickstart",
"concepts",
"---Building Your Org---",
"org-template",
"plugins",
"channels",
"schedules",
"---Platform Reference---",
"architecture",
"api-reference",
"self-hosting",
"---Operating---",
"observability",
"troubleshooting"
]
}

View File

@ -0,0 +1,11 @@
---
title: Observability
description: Stub page — content coming soon.
---
> 🚧 **Coming soon.** The Documentation Specialist agent will populate this
> page on its next maintenance cycle.
If you need this content urgently, open an issue on the
[docs repo](https://github.com/Molecule-AI/docs/issues/new) and the agent
will prioritise it on its next cron tick.

View File

@ -0,0 +1,11 @@
---
title: Org Template
description: Stub page — content coming soon.
---
> 🚧 **Coming soon.** The Documentation Specialist agent will populate this
> page on its next maintenance cycle.
If you need this content urgently, open an issue on the
[docs repo](https://github.com/Molecule-AI/docs/issues/new) and the agent
will prioritise it on its next cron tick.

11
content/docs/plugins.mdx Normal file
View File

@ -0,0 +1,11 @@
---
title: Plugins
description: Stub page — content coming soon.
---
> 🚧 **Coming soon.** The Documentation Specialist agent will populate this
> page on its next maintenance cycle.
If you need this content urgently, open an issue on the
[docs repo](https://github.com/Molecule-AI/docs/issues/new) and the agent
will prioritise it on its next cron tick.

View File

@ -0,0 +1,74 @@
---
title: Quickstart
description: Spin up your first multi-agent org in under five minutes.
---
This guide gets you from zero to a running PM + Dev Lead + Engineer team
using the bundled `molecule-dev` template.
## Prerequisites
- Docker Desktop (or any Docker daemon) running locally
- Go 1.25+ and Node 22+ if you want to build the platform from source
- A Claude API key (`CLAUDE_CODE_OAUTH_TOKEN`) in your environment
## 1. Clone the monorepo
```bash
git clone https://github.com/Molecule-AI/molecule-monorepo.git
cd molecule-monorepo
```
## 2. Boot the platform
```bash
docker compose up -d --build platform canvas
```
This starts:
- **platform** (Go API on `localhost:8080`)
- **canvas** (Next.js 15 frontend on `localhost:3000`)
- **postgres** + **redis** for state and pub/sub
## 3. Import the dev template
```bash
curl -X POST http://localhost:8080/org/import \
-H 'Content-Type: application/json' \
-d '{"dir":"molecule-dev"}'
```
This provisions the 12-workspace dev team — PM, Research Lead and 3
researchers, Dev Lead and 5 engineers, plus Security/QA/UIUX auditors —
each as its own Docker container.
## 4. Open the canvas
Navigate to [http://localhost:3000](http://localhost:3000). You should
see your team rendered as a tree of nodes. Click any node to chat with
that agent directly.
## 5. Talk to PM
PM is the entry point. Send it a task:
> *"Add a 'Last seen' column to the user list table on the admin page."*
PM will break the request into specific assignments, fan them out to the
right leads in parallel, verify the results, and report back when the
work is shipped.
## What just happened
You spun up a self-organising engineering team in one command. They're
clones of real Claude Code agents — they can read your codebase, run
tests, open PRs to GitHub. Their schedules (security audit, UX audit,
template fitness checks) run hourly on their own.
## Next steps
- Customise the [Org Template](/docs/org-template) to match your team's
actual structure.
- Add [Plugins](/docs/plugins) to give specific roles new capabilities.
- Wire a [Channel](/docs/channels) so you can talk to PM from Telegram.
- Read about the [Architecture](/docs/architecture) under the hood.

View File

@ -0,0 +1,11 @@
---
title: Schedules
description: Stub page — content coming soon.
---
> 🚧 **Coming soon.** The Documentation Specialist agent will populate this
> page on its next maintenance cycle.
If you need this content urgently, open an issue on the
[docs repo](https://github.com/Molecule-AI/docs/issues/new) and the agent
will prioritise it on its next cron tick.

View File

@ -0,0 +1,11 @@
---
title: Self Hosting
description: Stub page — content coming soon.
---
> 🚧 **Coming soon.** The Documentation Specialist agent will populate this
> page on its next maintenance cycle.
If you need this content urgently, open an issue on the
[docs repo](https://github.com/Molecule-AI/docs/issues/new) and the agent
will prioritise it on its next cron tick.

View File

@ -0,0 +1,11 @@
---
title: Troubleshooting
description: Stub page — content coming soon.
---
> 🚧 **Coming soon.** The Documentation Specialist agent will populate this
> page on its next maintenance cycle.
If you need this content urgently, open an issue on the
[docs repo](https://github.com/Molecule-AI/docs/issues/new) and the agent
will prioritise it on its next cron tick.

7
lib/source.ts Normal file
View File

@ -0,0 +1,7 @@
import { docs } from '@/.source';
import { loader } from 'fumadocs-core/source';
export const source = loader({
baseUrl: '/docs',
source: docs.toFumadocsSource(),
});

9
mdx-components.tsx Normal file
View File

@ -0,0 +1,9 @@
import defaultMdxComponents from 'fumadocs-ui/mdx';
import type { MDXComponents } from 'mdx/types';
export function getMDXComponents(components?: MDXComponents): MDXComponents {
return {
...defaultMdxComponents,
...components,
};
}

10
next.config.mjs Normal file
View File

@ -0,0 +1,10 @@
import { createMDX } from 'fumadocs-mdx/next';
const withMDX = createMDX();
/** @type {import('next').NextConfig} */
const config = {
reactStrictMode: true,
};
export default withMDX(config);

31
package.json Normal file
View File

@ -0,0 +1,31 @@
{
"name": "molecule-docs",
"version": "0.1.0",
"private": true,
"description": "Molecule AI documentation site — doc.moleculesai.app",
"scripts": {
"build": "next build",
"dev": "next dev",
"start": "next start",
"postinstall": "fumadocs-mdx",
"lint": "next lint"
},
"dependencies": {
"fumadocs-core": "^15.0.0",
"fumadocs-mdx": "^11.0.0",
"fumadocs-ui": "^15.0.0",
"next": "^15.0.0",
"react": "^19.0.0",
"react-dom": "^19.0.0"
},
"devDependencies": {
"@types/mdx": "^2.0.13",
"@types/node": "^22.0.0",
"@types/react": "^19.0.0",
"@types/react-dom": "^19.0.0",
"tailwindcss": "^4.0.0",
"@tailwindcss/postcss": "^4.0.0",
"postcss": "^8.4.49",
"typescript": "^5.6.3"
}
}

5
postcss.config.mjs Normal file
View File

@ -0,0 +1,5 @@
export default {
plugins: {
'@tailwindcss/postcss': {},
},
};

11
source.config.ts Normal file
View File

@ -0,0 +1,11 @@
import { defineConfig, defineDocs } from 'fumadocs-mdx/config';
export const docs = defineDocs({
dir: 'content/docs',
});
export default defineConfig({
mdxOptions: {
// Add remark/rehype plugins here as needed.
},
});

23
tsconfig.json Normal file
View File

@ -0,0 +1,23 @@
{
"compilerOptions": {
"target": "ES2022",
"lib": ["dom", "dom.iterable", "esnext"],
"allowJs": true,
"skipLibCheck": true,
"strict": true,
"noEmit": true,
"esModuleInterop": true,
"module": "esnext",
"moduleResolution": "Bundler",
"resolveJsonModule": true,
"isolatedModules": true,
"jsx": "preserve",
"incremental": true,
"plugins": [{ "name": "next" }],
"paths": {
"@/*": ["./*"]
}
},
"include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
"exclude": ["node_modules"]
}