Documentation Site

Forge's documentation is rendered with VitePress and managed with Bun. The Markdown files remain normal repository files so humans, editors, scripts, and coding agents can use them without depending on the site. Every page has exactly one source file under docs/; nothing is mirrored or copied into the site. The only generated page is docs/course/COURSE_BOOK.md, which is rebuilt from the lessons before every dev/build run and is gitignored.

Only the repository-root README.md and AGENTS.md live outside docs/, because they are read by GitHub and by coding agents rather than through the site.

Commands

From the repository root:

bun install
bun run docs:dev

Production validation:

bun run docs:build
bun run docs:preview

Documentation maintenance:

bun run docs:course   # rebuild docs/course/COURSE_BOOK.md
bun run docs:links    # verify relative Markdown links
bun run docs:check    # rebuild course + link check + production VitePress build

Reading offline (PWA)

The site is an installable Progressive Web App via @vite-pwa/vitepress. The service worker precaches every page, the local search index, fonts, and icons, so once installed the whole handbook works with no network. It updates itself the next time the phone opens it online.

bun run docs:deploy   # build + upload to Cloudflare Pages (run `bunx wrangler login` once first)
bun run docs:icons    # regenerate icons after changing docs/public/logo.svg

On Android: open the deployed URL in Chrome once while online, then menu → Add to Home screen / Install app. Service workers need HTTPS or localhost, so a plain LAN IP will not install.

Where configuration lives

package.json
└── Bun scripts and VitePress dependencies

docs/
├── .vitepress/
│   ├── config.mts
│   └── theme/
│       ├── index.ts
│       └── custom.css
├── index.md          site home
├── start-here.md
├── context.md        canonical vocabulary
├── roadmap.md
├── status/           CURRENT.md is the per-session status page
├── course/
├── plans/
├── workflow/
├── product/
├── architecture/
├── design/
├── adr/
├── research/
└── archive/

Each directory has a single index.md landing page. Do not add a README.md beside it; VitePress only serves index.md, so a second landing page silently drifts.

The VitePress theme stays deliberately light. Forge is a product project, not a custom documentation-theme project. Prefer the default theme and small readability improvements unless a real documentation need proves otherwise.

Bun is the package manager

Use Bun commands in repository documentation and automation for the JavaScript workspace. Do not add package-lock.json, pnpm-lock.yaml, or yarn.lock. When bun install is run, commit Bun's lockfile so installations become reproducible.

VitePress documents Bun as a supported installation and run path: https://vitepress.dev/guide/getting-started. Bun workspace documentation: https://bun.sh/docs/install/workspaces.