Initial Commit

apps/docs/README.md

@@ -0,0 +1,62 @@
+# @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 -->