# Mandu Documentation
> The agent-native meta-framework for Bun + React

## Getting Started
Install Mandu, scaffold a project, and ship your first agent-driven route.

- [Quickstart](/docs/start/quickstart): Ship a Mandu app in 5 minutes — install, scaffold, dev. Two install paths, one prompt your agent can run end-to-end.
- [Start](/docs/start): Install Mandu, scaffold an app, and run it locally in 5 minutes.

## Architect
Design Mandu applications: routing, layers, contracts, and guardrails.

- [Architecture Overview](/docs/architect/overview): The three pillars that keep Mandu apps — and the agents writing them — from drifting.
- [Rendering Modes](/docs/architect/rendering-modes): Mandu blends eight rendering strategies — here's when to use each.
- [Prerender](/docs/architect/prerender): Static-by-default rendering — how Mandu turns your routes into HTML at build time, and the tiny lever that opts out.
- [SSR & Streaming SSR](/docs/architect/ssr): Render on the server per request — including chunked Suspense streams.
- [Client Rendering](/docs/architect/client-rendering): `"use client"` pages, `*.island.tsx` islands, and partials — when to pick which.
- [Island](/docs/architect/island): The .island.tsx contract — the single signal Mandu uses to decide what ships to the browser, and the mismatch guards that keep hydration honest.
- [Smooth Navigation](/docs/architect/smooth-navigation): CSS View Transitions + hover-based link prefetch, auto-injected into every SSR response. Closes the perceived-latency gap against Next.js / Astro / SvelteKit without requiring a client-side SPA runtime.
- [Content Layer](/docs/architect/content-layer): Astro-style build-time content collections with Zod validation and digest caching.
- [Guard](/docs/architect/guard): The invariant layer — every rule Mandu's static analyzer enforces, what each one means, and how to fix the violation.
- [Decision Memory (ADR)](/docs/architect/decision-memory): Persistent architectural memory for agents — save, search, and enforce decisions.
- [Transactions & Rollback](/docs/architect/transaction): Atomic code changes — beginChange, commitChange, rollbackChange.
- [Accessing generated content](/docs/architect/generated-access): The official pattern for reading .mandu/generated/ artifacts from user code — runtime registry, not direct imports.
- [Architect](/docs/architect): The three pillars — Prerender, Island, Guard — that shape every Mandu app.

## Build with Agents
MCP integration, agent guides, and safe code-generation workflows.

- [MCP Setup](/docs/build-with-agents/mcp-setup): Connect Claude Code, Cursor, and Gemini CLI to the Mandu MCP server so agents can negotiate, scaffold, and guard without ad-hoc shell commands.
- [Architecture Negotiation](/docs/build-with-agents/negotiation): Agents propose structure first, get approval, then scaffold — no cowboy coding.
- [ATE — Agent Test Engine](/docs/build-with-agents/ate): Extract → Generate → Run → Report → Heal. A six-stage pipeline that turns the interaction graph of your app into runnable Playwright specs and suggests diffs when they fail.
- [Change — snapshot transactions](/docs/build-with-agents/change): begin → commit or rollback. Atomic, snapshot-backed edits so agents can experiment without leaving the repo in a half-written state.
- [Build with Agents](/docs/build-with-agents): Guards, MCP, and ATE — the tools that keep LLM-written code honest.

## Testing
Batteries-included test runner — unit, integration, E2E, coverage, watch, and snapshots.

- [Unit Tests](/docs/testing/unit): Run fast, pure-function tests against fillings and handlers without booting a server — `testFilling`, `createTestRequest`, `createTestContext` via `@mandujs/core/testing`.
- [Integration Tests](/docs/testing/integration): Exercise the full HTTP stack with `createTestServer` + `createTestSession` + `createTestDb` — from `@mandujs/core/testing`. Each fixture implements `Symbol.asyncDispose` so `await using` handles teardown.
- [E2E Tests](/docs/testing/e2e): `mandu test --e2e` wraps the ATE (Automation Test Engine) pipeline to extract the interaction graph, generate Playwright specs, and run them — with optional heal-on-failure suggestions.
- [Coverage](/docs/testing/coverage): `mandu test --coverage` turns on Bun's native line coverage and Playwright V8 coverage, then merges them into the canonical `.mandu/coverage/lcov.info`.
- [Watch mode](/docs/testing/watch): `mandu test --watch` keeps a persistent chokidar watcher over `app/`, `src/`, and `packages/` and re-runs only the tests affected by each change — a ~500ms red-green-refactor cycle.
- [Snapshot testing](/docs/testing/snapshot): Use bun:test's `toMatchSnapshot()` helper for golden-file tests, plus `--update-snapshots` to regenerate after intentional UI or contract changes.
- [Testing](/docs/testing): Mandu ships its own batteries-included test runner — unit, integration, E2E, coverage, watch — all driven by a single `mandu test` command.

## Deploy
`mandu deploy` and its seven adapters — Docker, Compose, Fly, Vercel, Railway, Netlify, Cloudflare Pages.

- [Docker](/docs/deploy/docker): Emit a multi-stage `Dockerfile` + `.dockerignore` tuned for Bun + Mandu. Artifact-only — users run `docker build` / `docker push` themselves.
- [Docker Compose](/docs/deploy/docker-compose): Multi-service scaffold — Mandu app + Postgres sidecar + `.env.example`. Ideal for local reproducible dev environments and single-host self-hosting.
- [Fly.io](/docs/deploy/fly): `mandu deploy --target=fly` emits a `fly.toml` + `Dockerfile` pair. With `--execute` + `flyctl ≥ 0.1.0` installed, Mandu invokes `fly deploy` on your behalf.
- [Vercel](/docs/deploy/vercel): `mandu deploy --target=vercel` emits a `vercel.json` + a Node SSR function at `api/_mandu.ts`. With `--execute` and `vercel ≥ 28.0.0` installed, Mandu triggers a deploy.
- [Railway](/docs/deploy/railway): `mandu deploy --target=railway` emits a `railway.json` + `nixpacks.toml` pair tuned for Bun + Mandu. With `--execute` and `railway ≥ 3.0.0` installed, Mandu triggers a deploy.
- [Netlify](/docs/deploy/netlify): `mandu deploy --target=netlify` emits a `netlify.toml` + a Node SSR function at `netlify/functions/ssr.ts`. With `--execute` and `netlify ≥ 17.0.0` installed, Mandu triggers a deploy.
- [Cloudflare Pages](/docs/deploy/cf-pages): `mandu deploy --target=cf-pages` emits a `wrangler.toml` + a `functions/_middleware.ts` glue file. Artifact-only in Phase 13 — runtime compatibility via the Phase 15 Workers adapter.
- [Deploy](/docs/deploy): `mandu deploy` turns a built Mandu project into the config files + pipeline each hosting provider expects. Seven adapters, one CLI surface, zero secrets-in-artifacts.

## Edge
Edge runtime adapters from `@mandujs/edge` — Cloudflare Workers shipped; Deno / Vercel / Netlify coming.

- [Cloudflare Workers](/docs/edge/cloudflare-workers): Ship a Mandu app to Cloudflare Workers via `@mandujs/edge/workers`. `mandu build --target=workers` emits a bundled Worker + `wrangler.toml`. Bindings (KV, R2, D1) via `AsyncLocalStorage`-backed accessors.
- [Deno / Vercel Edge / Netlify Edge](/docs/edge/deno-vercel-netlify): Roadmap for Phase 15.2+ adapters in `@mandujs/edge`. Deno Deploy, Vercel Edge Functions, and Netlify Edge Functions are scaffolded stubs — file structure in place, implementations coming.
- [Edge](/docs/edge): `@mandujs/edge` ships edge-runtime adapters for Cloudflare Workers (Phase 15.1, shipped). Deno Deploy, Vercel Edge, and Netlify Edge adapters are scaffolded and land in Phase 15.2+.

## AI
`mandu ai` playground + eval harness, prompt templates, MCP tools, loop closure, and skills.

- [`mandu ai chat`](/docs/ai/chat): Interactive REPL with streaming responses and slash commands. Works offline with the `local` echo provider, or hit Claude / OpenAI / Gemini / Ollama / LM-Studio.
- [`mandu ai eval`](/docs/ai/eval): Non-interactive prompt evaluator — runs one prompt across one or more providers and prints JSON to stdout. Exit 0 if every provider succeeded; exit 1 if any errored. Ideal for CI diff tests.
- [Prompt templates](/docs/ai/prompts): Mandu's prompt template system — `docs/prompts/*.md` files loaded via `--preset` or `/preset`, plus the provider-specific adapter architecture behind `mandu ai`.
- [MCP tools (Phase 14.3)](/docs/ai/mcp-tools): Four new tools added to `@mandujs/mcp` in Phase 14.3 — `mandu.run.tests`, `mandu.deploy.preview`, `mandu.ai.brief`, and `mandu.loop.close`. Each closes the loop between an agent's actions and its orchestrator.
- [Loop closure](/docs/ai/loop-closure): Pure detector + emitter framework that recognizes stall patterns in agent output (stdout / stderr + exit code) and composes an advisory `nextPrompt`. No I/O. Deterministic. Safe to call on untrusted output.
- [Skills generator](/docs/ai/skills-generator): `@mandujs/skills` auto-generates a per-project skill manifest — the list of domain-specific actions an agent can perform in this repo. Pure, deterministic, safe to run in CI.
- [AI](/docs/ai): `mandu ai` is a terminal playground for streaming chat with Claude, OpenAI, Gemini, or a local Ollama/LM-Studio. Plus the prompt template system, 4 new MCP tools, loop closure framework, and auto skills generator.

## CLI Commands
Extended day-to-day CLI commands — `db seed`, `upgrade`, `mcp register`. For the exhaustive flag reference see /docs/reference/cli.

- [`mandu db seed`](/docs/cli/db-seed): Replay deterministic fixture data against the live database. Declarative or imperative seed files, parameter-bound SQL with `quoteIdent()` injection defense, idempotent upsert + tamper detection.
- [`mandu upgrade`](/docs/cli/upgrade): Self-updater for both the npm-installed `@mandujs/*` packages and the standalone compile-binary builds. SHA-256 verified, atomic swap, `--rollback` capable.
- [`mandu mcp register`](/docs/cli/mcp-register): Automatic IDE integration — writes a Mandu MCP server entry into Claude Code, Cursor, Continue, or Aider without touching sibling configuration. Merge-safe, tolerant of JSON-C, preserves YAML preamble.

## Reference
CLI, configuration, APIs, and invariants — exhaustive and stable.

- [CLI Reference](/docs/reference/cli): Exhaustive reference for every mandu subcommand: flags, environment variables, exit codes.
- [mandu.config.ts Reference](/docs/reference/config): Full schema for ManduConfig — every top-level field and sub-field with types, defaults, and examples.
- [Client Router](/docs/reference/client-router): useRouter, useParams, Link, NavLink — the SPA navigation hooks.
- [Reference](/docs/reference): Auto-generated API surface, CLI flags, and config reference.

## Recipes
Task-oriented how-tos: auth, i18n, streaming, deployment, and more.

- [Build an API endpoint](/docs/recipes/create-api): Two patterns for an API route — a quick filling chain, or a type-safe contract. One prompt covers both.
- [Authentication](/docs/recipes/auth): Sessions, JWT, OAuth, and CSRF — wired into Mandu's filling chain via middleware.
- [Internationalisation (i18n)](/docs/recipes/i18n): Add a `[lang]` segment, translation modules, and a locale switcher — the same pattern this docs site uses across 23 languages.
- [Streaming responses](/docs/recipes/streaming): SSE and chunked streams for AI chat, live progress, and large payloads — without breaking the filling chain.
- [Deploy](/docs/recipes/deploy): Ship a Mandu app — Vercel, Cloudflare Pages, Fly, Railway, Netlify, Docker, or a plain VPS. One command per target.
- [Testing](/docs/recipes/testing): Unit, integration, and E2E — all through Bun's test runner with Mandu's ATE auto-generating contract tests for you.
- [Recipes](/docs/recipes): Copy-paste patterns for common tasks — auth, forms, data, deploy.

## Migrate
Move to Mandu from Next.js, Remix, Astro, or SvelteKit.

- [Migrate](/docs/migrate): Move an existing Next.js, Vite, or Remix app to Mandu.

## Benchmarks
Side-by-side comparisons against Next.js, Remix, and Hono — architecture, agent-friendliness, and runtime numbers.

- [Mandu vs Next.js](/docs/benchmarks/vs-nextjs): An honest, agent-first comparison — file-system routing, type-safe APIs, runtime guard, and AI-editor workflows on Bun + React.
- [Mandu vs Remix](/docs/benchmarks/vs-remix): Two routing-first React frameworks compared — loaders/actions vs filling chain, web standards vs MCP-driven agents.
- [Mandu vs Hono](/docs/benchmarks/vs-hono): When the API layer is everything — Hono's router-as-library vs Mandu's full fullstack framework with built-in agent surface.

## For Agents
Every Agent Prompt the docs ship, indexed in one place. Fetch this URL and you have the whole site.

- [For Agents](/docs/for-agents): Every Agent Prompt the Mandu docs ship, indexed in one place — fetch this URL and you have the whole site.