# @suaveplan/docs - Docusaurus 3.10 documentation site for the SuavePlan monorepo

The `@suaveplan/docs` app is the public-facing documentation portal for
the genesis monorepo. It serves a Docusaurus 3.10 site that renders the
package READMEs, OpenSpec specs, and architecture guides under a single
sidebar.

## Local development

```bash
bun install
bun run --filter @suaveplan/docs dev
```

The dev server runs on `http://localhost:6043`. Hot-reload is enabled.

## Runtime: pure Bun

This app runs end-to-end under Bun — no Node required. The site is built
with **VitePress** (Vite + Vue) which works cleanly under Bun's runtime;
we previously tried Docusaurus 3.10 but its webpack-bundled SSR step
fails with `require.resolveWeak is not a function` regardless of Bun
flags or `@docusaurus/faster` config.

The static output is served in production by a Bun bytecode-compiled
binary (`docs-app`) — no Node, no Bun runtime, no `node_modules` on the
deployment target.

## Content pipeline

`scripts/snapshot-docs-content.ts` (at the repo root) mirrors every
`README.md`, package module `.md`, and OpenSpec capability spec from the
source tree into `apps/docs/docs/`, preserving paths so the auto-generated
relative links keep resolving locally. The snapshot runs automatically as
part of `bun run build`. All mirrored content is gitignored — the source
of truth stays in the package directories.

## Production build

```bash
bun run --filter @suaveplan/docs build
bun run --filter @suaveplan/docs serve
```

The static output lands in `apps/docs/build/`. Serve it from any static
host — Cloudflare Pages, Vercel, or a plain `bun --static-serve` setup.

## Content layout

- `docs/` — markdown / MDX pages picked up by the auto-generated sidebar.
- `src/css/custom.css` — site-wide theme variables.
- `docusaurus.config.ts` — navbar, footer, presets.

This app intentionally has zero workspace `@suaveplan/*` runtime deps. It
is a documentation portal that reads filesystem content; it does not import
genesis libraries.

<!-- begin:auto-spec-link -->
## OpenSpec

Canonical capability spec: [`../../openspec/specs/docs/spec.md`](../../openspec/specs/docs/spec.md).
<!-- end:auto-spec-link -->