Snow LeeandClaude Opus 4.8
fdbedbd837
Adds web/docs — the public product documentation, built with Astro + Starlight and deployed on its own rather than embedded in the binary. Why a standalone site in the OSS repo, rather than a section of the cloud landing page: - Docs change far more often than the binary does. Embedding them would mean a Go rebuild and redeploy to fix a typo, and would ship a Pagefind search index inside every self-hoster's install. - Self-hosting instructions and the CLI reference document the OSS project, so "edit this page" should resolve to something an outside contributor can open a PR against. - Design tokens get easier, not harder: scripts/tokens.mjs generates src/styles/tokens.gen.css from the @theme block in the hub frontend's tw.css, so there is one source of truth and nothing to police. (The cloud landing sits across a module edge and has to keep a *copy*, guarded by its own check-tokens.mjs.) custom.css maps Starlight's --sl-color-* onto those tokens and invents no colors of its own. Content is seeded from README.md, docs/self-hosting.md, and the plugin skill. Guides deliberately cover agent workflows — connecting an agent, the two-file AGENTS.md orientation pattern, artifacts and links, read heat, scoping the folder — rather than re-teaching the CLI, which lives in Reference. starlight-llms-txt emits /llms.txt at build. Convention wants that at the root domain, so beardrive.ai/llms.txt should point here; that redirect belongs to the cloud landing and is the one cross-repo coordination point this split introduces. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018GcqsM6prjdv9rUrhVVEiC
docs.beardrive.ai
The public product documentation: CLI, sync model, self-hosting. Astro + Starlight, static output, Pagefind search.
npm install
npm run dev # http://localhost:4321
npm run build # -> dist/
npm run preview
Why this is a standalone site
Unlike the hub frontend (internal/webapp/static) and the cloud landing page
(cloud/internal/landing/dist), this is not embedded into a Go binary:
- Docs change far more often than the binary. Embedding them would mean a Go rebuild and redeploy to fix a typo.
- A Pagefind search index has no business shipping inside every self-hoster's install.
It lives in the OSS repo because that is what it documents. "Edit this page" resolves to something an outside contributor can open a PR against.
Design tokens
scripts/tokens.mjs reads the @theme block in
internal/webapp/frontend/src/tw.css — the source of truth for the BearDrive
palette — and emits src/styles/tokens.gen.css. That file is generated,
gitignored, and regenerated by npm run dev and npm run build, so the palette
cannot drift. src/styles/custom.css maps Starlight's --sl-color-* variables
onto it and invents no colors of its own.
(The cloud landing page can't do this — it sits in a different Go module and
keeps a copy of the tokens, policed by its own check-tokens.mjs.)
Adding a page
Drop a .md file under src/content/docs/<section>/ with title and
description frontmatter, then add its slug to the sidebar in
astro.config.mjs. Sidebar order is explicit, not alphabetical.
Write description for every page: it is the meta description, the search
result snippet, and what llms.txt shows.
llms.txt
starlight-llms-txt generates /llms.txt, /llms-small.txt, and
/llms-full.txt at build time.
Convention puts llms.txt at the root domain, not a docs subdomain — so
beardrive.ai/llms.txt should redirect or proxy to docs.beardrive.ai/llms.txt.
That redirect lives in the cloud landing page and is the one cross-repo
coordination point this split introduces.
Deploying
Static output in dist/. Any static host works; build command npm run build,
output directory dist, project root web/docs.
Note that the build reads a file outside web/docs (the token source), so
the host must check out the whole repository rather than just this
subdirectory.