Docs

.gitignore

@@ -27,6 +27,7 @@ build
 dist
 .output
 .nitro
+.astro
 
 
 # Debug
@@ -58,6 +59,7 @@ templates-binary
 
 # Auto-generated at build time (avoids merge conflicts)
 packages/template-generator/src/templates.generated.ts
+apps/web/public/docs/
 
 # Ralph (autonomous agent loop)
 scripts/ralph/

AGENTS.md

@@ -39,6 +39,8 @@ See `docs/guidelines/` for deeper reference on these topics:
 - Surprise worth remembering: prompt-interactivity helpers can pick up ambient `process.env.CI` through destructuring defaults and make tests fail only on GitHub Actions. When injecting prompt environment state in `apps/cli`, resolve CI defaults explicitly so `ci: undefined` remains an override instead of silently inheriting the runner environment.
 - Surprise worth remembering: addon setup helpers can bypass the shared prompt-environment guard if they call Clack prompts directly. For scripted scaffolds (`bun create ... --addons ...`, smoke tests, `create()` silent mode), ensure addon-specific setup paths like `mcp` and `ultracite` fall back to deterministic defaults instead of prompting, or they can exit before `bts.jsonc` is written.
 - Surprise worth remembering: TanStack Start route generation in `apps/web` only reads ignore settings from `tanstackStart({ router: ... })` in `apps/web/vite.config.ts`, not from top-level plugin options. Any `createFileRoute` scratch/design file left in `apps/web/src/routes` will be pulled into `routeTree.gen.ts` and build output unless it matches `routeFileIgnorePrefix`/`routeFileIgnorePattern`.
+- Surprise worth remembering: docs content for `apps/web` lives in `apps/web/content/docs`, so `import.meta.glob` calls from `apps/web/src/lib/docs/*` must use `../../../content/docs/**` paths or the docs registry can build empty and `/docs` will 404 in preview.
+- Surprise worth remembering: TanStack Start loaders must stay serializable. In `apps/web/src/routes/docs/*`, do not return the MDX `Component` from `getPage()` in loader data; return slug/frontmatter only and resolve the page component inside the route component.
 - Surprise worth remembering: `packages/template-generator/tsconfig.json` includes only `src/**/*`, so tests added under `packages/template-generator/test/` are not covered by the package's normal TypeScript check unless you add a dedicated test tsconfig or expand the include set.
 - Surprise worth remembering: ecosystem additions can still miss `apps/web/src/lib/stack-search-schema.ts`, which used to hardcode the web URL `ecosystem` enum separately from `@better-fullstack/types`. When adding or renaming ecosystems, keep that parser on the shared `EcosystemSchema` so pre-commit `apps/web` typecheck does not fail after the main stack wiring looks complete.
 - Surprise worth remembering: `.github/workflows/release.yaml` should keep Bun pinned for deterministic release verification, but the actual package publish path is safer through `npm publish` on Node 24. The release job's `bun publish` steps started failing on npm with a misleading 404 for `@better-fullstack/*`, while npm's current publish flow can use trusted publishing/OIDC when configured and still fall back to `NPM_TOKEN`. Treat Bun or publish-tooling changes there as release-sensitive.

README.md

@@ -16,7 +16,7 @@
 
 <div align="center">
 
-**Scaffold production-ready fullstack apps in seconds. Pick your stack from 340+ options — the CLI wires everything together.**
+**Scaffold production-ready fullstack apps in seconds. Pick your stack from 424 options — the CLI wires everything together.**
 
 <br>
 
@@ -34,8 +34,8 @@
 
 Most scaffolding tools lock you into one framework and one opinion. Better Fullstack doesn't.
 
-- **340+ options** — frontend, backend, database, auth, payments, AI, DevOps, and more
-- **4 ecosystems** — TypeScript, Rust, Python, Go — with more coming
+- **424 options** — frontend, backend, database, auth, payments, AI, DevOps, and more
+- **5 ecosystems** — TypeScript, Rust, Python, Go, Java — with more coming
 - **Visual builder** — configure your stack in the browser, get a ready-to-run CLI command
 - **Wired for you** — no manual glue code; every picked integration is preconfigured and working out of the box
 
@@ -58,6 +58,10 @@ Configure your stack visually — pick every option from a UI, preview your choi
 
 ### 💻 CLI
 
+```bash
+npm create better-fullstack@latest
+```
+
 ```bash
 bun create better-fullstack@latest
 ```
@@ -74,6 +78,8 @@ npx create-better-fullstack@latest
 yarn create better-fullstack@latest
 ```
 
+Bun is only required when you choose Bun as the generated app runtime or package manager. Node.js with npm works for Node-based projects.
+
 </td>
 </tr>
 </table>
@@ -100,7 +106,7 @@ yarn create better-fullstack@latest
 ## 🧩 The Stack
 
 <details>
-<summary><strong>Ecosystems</strong> — TypeScript · Rust · Python · Go</summary>
+<summary><strong>Ecosystems</strong> — TypeScript · Rust · Python · Go · Java</summary>
 <br>
 
 | | |
@@ -109,6 +115,7 @@ yarn create better-fullstack@latest
 | **Rust** | Axum · Actix Web · Leptos · Dioxus · SeaORM · SQLx · tonic · async-graphql |
 | **Python** | FastAPI · Django · SQLAlchemy · SQLModel · Pydantic · LangChain · CrewAI · Celery |
 | **Go** | Gin · Echo · GORM · sqlc · gRPC · Cobra · BubbleTea · Zap |
+| **Java** | Spring Boot · Maven · Gradle · Spring Data JPA · Spring Security · JUnit · Testcontainers |
 
 </details>
 

apps/cli/README.md

@@ -1,23 +1,28 @@
 # Better Fullstack
 
-Scaffold production-ready fullstack apps in seconds. Pick your stack from 270+ options — the CLI wires everything together.
+Scaffold production-ready fullstack apps in seconds. Pick your stack from 424 options — the CLI wires everything together.
 
 ## Quick Start
 
 ```bash
-# Using bun (recommended)
-bun create better-fullstack@latest
+# Using npm
+npm create better-fullstack@latest
+
+# Using npx
+npx create-better-fullstack@latest
 
 # Using pnpm
 pnpm create better-fullstack@latest
 
-# Using npm
-npx create-better-fullstack@latest
+# Using bun
+bun create better-fullstack@latest
 
 # Using yarn
 yarn create better-fullstack@latest
 ```
 
+Bun is required only when the generated project selects Bun as its runtime or package manager. Node.js with npm is enough for Node-based projects.
+
 ## Web Builder
 
 Configure your stack visually — pick every option from a UI, preview your choices, and get a ready-to-run command.
@@ -26,8 +31,8 @@ Configure your stack visually — pick every option from a UI, preview your choi
 
 ## Features
 
-- **270+ options** — frontend, backend, database, auth, payments, AI, DevOps, and more
-- **4 ecosystems** — TypeScript, Rust, Python, Go
+- **424 options** — frontend, backend, database, auth, payments, AI, DevOps, and more
+- **5 ecosystems** — TypeScript, Rust, Python, Go, Java
 - **Visual builder** — configure your stack in the browser
 - **Wired for you** — every picked integration is preconfigured and working out of the box
 
@@ -37,7 +42,7 @@ Configure your stack visually — pick every option from a UI, preview your choi
 --yes              # Accept all defaults
 --yolo             # Scaffold a random stack — good for exploring
 --template <name>  # Use a preset (t3, mern, pern, uniwind)
---ecosystem <lang> # Start in rust, python, or go mode
+--ecosystem <lang> # Start in typescript, rust, python, go, or java mode
 --version-channel  # Dependency channel: stable, latest, beta
 --no-git           # Skip git initialization
 --no-install       # Skip dependency installation

apps/cli/package.json

@@ -1,7 +1,7 @@
 {
   "name": "create-better-fullstack",
   "version": "1.6.0",
-  "description": "Scaffold production-ready fullstack apps in seconds. Pick your stack from 340+ options — the CLI wires everything together.",
+  "description": "Scaffold production-ready fullstack apps in seconds. Pick your stack from 424 options — the CLI wires everything together.",
   "keywords": [
     "algolia",
     "angular",

apps/cli/src/index.ts

@@ -144,6 +144,7 @@ import {
   type JavaAuth,
   JavaTestingLibrariesSchema,
   type JavaTestingLibraries,
+  OPTION_CATEGORY_METADATA,
   AiDocsSchema,
   type AiDocs,
   ShadcnBaseSchema,
@@ -160,10 +161,15 @@ import { openUrl } from "./utils/open-url";
 import { renderTitle } from "./utils/render-title";
 import { displaySponsors, fetchSponsors } from "./utils/sponsors";
 
+const OPTION_ENTRY_COUNT = Object.values(OPTION_CATEGORY_METADATA).reduce(
+  (sum, metadata) => sum + metadata.options.length,
+  0,
+);
+
 export const router = os.router({
   create: os
     .meta({
-      description: "Scaffold a new Better Fullstack project from 270+ compatible stack options",
+      description: `Scaffold a new Better Fullstack project from ${OPTION_ENTRY_COUNT} compatible stack options`,
       default: true,
       negateBooleans: true,
     })

apps/cli/src/mcp.ts

@@ -42,6 +42,7 @@ import {
   LoggingSchema,
   ObservabilitySchema,
   ORMSchema,
+  OPTION_CATEGORY_METADATA,
   PackageManagerSchema,
   PaymentsSchema,
   type ProjectConfig,
@@ -79,7 +80,12 @@ import z from "zod";
 import { readBtsConfig, writeBtsConfig } from "./utils/bts-config";
 import { getLatestCLIVersion } from "./utils/get-latest-cli-version";
 
-const INSTRUCTIONS = `Better-Fullstack scaffolds fullstack projects across TypeScript, Rust, Go, Python, and Java ecosystems with 270+ configurable options.
+const OPTION_ENTRY_COUNT = Object.values(OPTION_CATEGORY_METADATA).reduce(
+  (sum, metadata) => sum + metadata.options.length,
+  0,
+);
+
+const INSTRUCTIONS = `Better-Fullstack scaffolds fullstack projects across TypeScript, Rust, Go, Python, and Java ecosystems with ${OPTION_ENTRY_COUNT} configurable options.
 
 RECOMMENDED WORKFLOW:
 1. Call bfs_get_guidance to understand field semantics, required fields, and workflow rules.

apps/web/content/docs/ai/mcp.mdx

@@ -0,0 +1,41 @@
+---
+title: MCP
+description: Connect Better Fullstack to MCP-compatible AI coding agents.
+---
+
+The MCP server lets agents scaffold projects through structured tool calls instead of guessing CLI flags.
+
+## Start the server
+
+```npm
+npx create-better-fullstack@latest mcp
+```
+
+## Recommended tool order
+
+1. `bfs_get_guidance`
+2. `bfs_get_schema`
+3. `bfs_check_compatibility`
+4. `bfs_plan_project`
+5. `bfs_create_project`
+
+For existing projects:
+
+1. `bfs_plan_addition`
+2. `bfs_add_feature`
+
+## Important rules
+
+- Dependency installation is skipped in MCP mode.
+- Array fields include `frontend`, `addons`, `examples`, `aiDocs`, `rustLibraries`, `pythonAi`, `javaLibraries`, and `javaTestingLibraries`.
+- `none` means “skip this feature.”
+- TypeScript fields are ignored for Rust, Python, Go, and Java projects.
+- Always validate compatibility before creating.
+
+## Agent prompt
+
+Use this prompt when you want an agent to create a project:
+
+```text
+Use Better Fullstack MCP. First inspect guidance and schema, then validate the stack, then dry-run it. Only create the project after the dry-run succeeds. Skip dependency installation and tell me the exact commands to install, test, and run the project.
+```

apps/web/content/docs/ai/meta.json

@@ -0,0 +1,5 @@
+{
+  "title": "AI Agents",
+  "defaultOpen": true,
+  "pages": ["overview", "mcp"]
+}

apps/web/content/docs/ai/overview.mdx

@@ -0,0 +1,48 @@
+---
+title: AI Agents
+description: How AI coding agents should use Better Fullstack safely and quickly.
+---
+
+Better Fullstack is designed to work well with AI coding agents. Agents should use structured inputs, validate compatibility, preview output, and create projects only after the stack is clear.
+
+## Preferred workflow
+
+1. Determine the target ecosystem first: `typescript`, `rust`, `python`, `go`, or `java`.
+2. Fetch valid schema/options.
+3. Validate the requested stack.
+4. Preview the generated file tree.
+5. Scaffold with dependency installation disabled.
+6. Tell the user the exact install and run commands.
+
+## CLI-first workflow
+
+For agents without MCP access:
+
+```npm
+npm create better-fullstack@latest my-app -- \
+  --ecosystem typescript \
+  --frontend next \
+  --backend self \
+  --runtime none \
+  --database postgres \
+  --orm drizzle \
+  --auth better-auth \
+  --ai-docs agents-md \
+  --no-install
+```
+
+## MCP workflow
+
+For MCP-compatible agents, use the Better Fullstack MCP server. It exposes tools for schema lookup, compatibility checks, dry-run previews, project creation, and feature additions.
+
+Read the [MCP guide](/docs/ai/mcp/) for setup.
+
+## Generated AI docs
+
+Use `--ai-docs` to generate project-local context files:
+
+```bash
+--ai-docs agents-md claude-md cursorrules
+```
+
+Agents should update those files when they change project structure, dependencies, or workflows.

apps/web/content/docs/cli/add.mdx

@@ -0,0 +1,25 @@
+---
+title: Add Features
+description: Add supported addons and deployment targets to existing Better Fullstack projects.
+---
+
+The `add` command reads the generated `bts.jsonc` file and applies supported additions to an existing project.
+
+```npm
+npm create better-fullstack@latest add -- --addons mcp skills
+```
+
+## What it can add
+
+- AI-agent configuration through the `mcp` addon.
+- Curated coding-agent skills through the `skills` addon.
+- Documentation addons such as Starlight or Fumadocs when supported by the selected stack.
+- Deployment target configuration where available.
+
+## Recommended workflow
+
+1. Commit or stash your current work.
+2. Run `add` with explicit flags.
+3. Review generated file changes.
+4. Install dependencies if the addon introduced new packages.
+5. Run the project’s test or typecheck command.

apps/web/content/docs/cli/create.mdx

@@ -0,0 +1,65 @@
+---
+title: Create Command
+description: How to use create-better-fullstack to scaffold new projects.
+---
+
+The create command scaffolds a project from your selected stack.
+
+```npm
+npm create better-fullstack@latest [project-name] -- [flags]
+```
+
+With `npm create`, pass Better Fullstack flags after `--`. The other launchers above pass flags directly.
+
+## Common flags
+
+| Flag | Purpose |
+| --- | --- |
+| `--dry-run` | Preview generated files without writing them. |
+| `--yes` | Accept defaults. Do not combine with explicit stack flags. |
+| `--template <name>` | Use a preset such as `t3`, `mern`, `pern`, or `uniwind`. |
+| `--ecosystem <name>` | Start with `typescript`, `rust`, `python`, `go`, or `java`. |
+| `--runtime <name>` | Choose the TypeScript server runtime, such as `node`, `bun`, or `none`. |
+| `--ai-docs <items...>` | Generate AI context files such as `agents-md` or `claude-md`. |
+| `--addons <items...>` | Add optional features such as `mcp`, `skills`, `turborepo`, or `starlight`. |
+| `--no-install` | Skip dependency installation. Recommended for automation. |
+| `--no-git` | Skip Git initialization. |
+| `--package-manager <name>` | Choose dependency installation commands for generated projects: `npm`, `pnpm`, `yarn`, or `bun`. |
+
+## Explicit TypeScript example
+
+```npm
+npm create better-fullstack@latest my-app -- \
+  --frontend tanstack-router \
+  --backend hono \
+  --runtime node \
+  --database sqlite \
+  --orm drizzle \
+  --api orpc \
+  --auth better-auth \
+  --package-manager npm \
+  --addons turborepo \
+  --ai-docs agents-md \
+  --no-install
+```
+
+Bun is not required for this example because it selects `--runtime node` and `--package-manager npm`. If you select `--runtime bun` or `--package-manager bun`, install Bun before running the generated project commands.
+
+## Explicit Java example
+
+```npm
+npm create better-fullstack@latest my-api -- \
+  --ecosystem java \
+  --java-web-framework spring-boot \
+  --java-build-tool maven \
+  --java-orm spring-data-jpa \
+  --java-auth spring-security \
+  --java-libraries spring-actuator flyway springdoc-openapi \
+  --java-testing-libraries junit5 mockito testcontainers \
+  --ai-docs agents-md \
+  --no-install
+```
+
+## Automation rule
+
+For scripts and AI agents, use explicit flags and `--no-install`, then run installation after reviewing the generated files.

apps/web/content/docs/cli/meta.json

@@ -0,0 +1,5 @@
+{
+  "title": "CLI",
+  "defaultOpen": true,
+  "pages": ["create", "add"]
+}