Snow LeeandClaude Opus 4.8
16ababe37d
"Is this for me?" was answerable only by reading the guides and doing the translation yourself. These five pages answer it directly, sit between Start here and Working with agents, and route out rather than re-teaching features: - Share work across your team's agents — a team that doesn't live in a terminal: Cowork and Claude Code share plugins, so the agent does the setup and nobody opens a shell. - Keep a wiki your agents maintain — knowledge written as a side effect of work; Insights' hot-and-stale quadrant is the maintenance queue. - Turn a personal brain into a company brain — OKF bundles, gbrain repos, Obsidian vaults. They are already markdown directories, so there is nothing to convert. - Run a personal wiki, publish part of it — history as the point, plus per-file public links. - Carry one context across agents and devices — one project, many mounts, and what actually happens when two machines edit one file. Titles are job-shaped; the persona is named in the first line and in the description, which is also the search snippet and the llms.txt line. The company-brain page is the long one (790 words vs ~400) because it carries two frictions worth being honest about. gbrain's own team setup shares a brain through a remote Postgres, an HTTP MCP server, and per-teammate OAuth with isolation enforced in SQL; file sync plus each person's local brain skips all of that at small scale, and the page says what the server still buys you rather than dunking. And privacy does not map cleanly: gbrain scopes per person, BearDrive's unit of membership is the project, so a walled boundary is a separate project — stated plainly, with a table. Unverified: whether "let one machine run consolidation" matches how gbrain teams actually work. Written from the docs, not from practice. Verified: 23 pages build, zero broken internal links, both external references (Google Cloud's OKF announcement, the gbrain repo) resolve 200. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
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.
Structure
The sidebar order in astro.config.mjs is the recommended path, and the
recommended path is agent-first:
- Start here — what it is, set up with your agent, first hour. No
brew installappears in this group. - Working with agents — the workflows the product exists for.
- Manual setup (optional) — the CLI route: install, set up by hand, skills and hooks in detail. Same destination, more steps; one click away, never on the critical path.
- Self-hosting, Reference, Concepts — unchanged in intent.
Keep new onboarding content out of Manual. If a page teaches someone how to get started, it belongs in Start here and should say what to ask an agent, not what to type.
Deploying
Static output in dist/. Any static host works; build command npm run build,
output directory dist, project root web/docs.
Redirects
The docs were reorganized around the agent-first path, so three old URLs moved:
| Old | New |
|---|---|
/start/install |
/manual/install/ |
/start/quickstart |
/manual/setup-by-hand/ |
/guides/connect-an-agent |
/start/setup/ |
astro.config.mjs declares these, which in a static build emits meta-refresh
pages — fine for humans, weak for search engines. Real 301s belong in the host.
Firebase Hosting (simplest static option on GCP — CDN, TLS, and custom domains included):
{
"hosting": {
"public": "dist",
"ignore": ["firebase.json", "**/.*"],
"redirects": [
{ "source": "/start/install", "destination": "/manual/install/", "type": 301 },
{ "source": "/start/quickstart", "destination": "/manual/setup-by-hand/", "type": 301 },
{ "source": "/guides/connect-an-agent", "destination": "/start/setup/", "type": 301 }
]
}
}
Cloud Storage behind an external Application Load Balancer: put the rules in the URL map, which redirects before the bucket is ever reached.
gcloud compute url-maps edit docs-url-map # pathMatchers[].pathRules[]:
# - paths: ["/start/install"]
# urlRedirect:
# pathRedirect: "/manual/install/"
# redirectResponseCode: MOVED_PERMANENTLY_DEFAULT
# stripQuery: false
Whichever host wins, keep the Astro redirects block as well: it is the
portable fallback, and it keeps local npm run preview honest.
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.