The seven use-case pages were the one part of docs.beardrive.ai that wasn't
documentation — job-shaped routing pages, aimed at someone deciding rather
than someone building. beardrive.ai already publishes six of them, same
titles, same slugs, so the docs copy was a fork of marketing copy that no one
was keeping in step.
They're deleted here, and every URL redirects to its counterpart over there
rather than to an index: those pages were live and indexed for a month, and
sending all seven to /use-cases/ would throw away which one someone asked
for. shared-skills is the exception — the landing site has no page for it
yet, so that one lands on the index.
The logo now points at beardrive.ai. Starlight always aims it at the docs
root and has no config for it, so this is a SiteTitle component override:
its own markup, one changed href, minus the two-logo branch this site never
takes (one `src`, so the light/dark alternate can't render).
Three off-site links — Use cases, Blog, GitHub — go at the BOTTOM of the
sidebar. The sidebar order is the recommended path, so a link that leaves
the docs must not sit above the docs.
Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
docs.beardrive.ai was serving a build from around 2026-07-19 — three weeks
and 38 docs commits stale. /manual/hooks/ 404s while /manual/skills-and-hooks/,
deleted in #85, still serves; the sitemap has no <lastmod> and robots.txt is
Cloudflare's managed content-signals file with no Sitemap: line, so #140
plainly never shipped.
The cause: the Pages project (beardrive-docs, docs.beardrive.ai) is a
direct-upload project with no Git provider. Someone ran `wrangler pages
deploy` by hand, then stopped, and nothing anywhere noticed — every check
this repo has runs during a deploy that was no longer happening.
docs.yml builds web/docs on PRs that touch it and deploys to Pages on pushes
to main. Not the Pages Git integration, deliberately: it clones shallow, and
astro.config.mjs reads each page's <lastmod> from the commit date behind it,
so a depth-1 checkout drops all 27 of them — hence fetch-depth: 0. It also
would rebuild the docs for every commit in a repo that is mostly Go.
The path filter includes internal/webapp/frontend/src/tw.css: the palette is
generated from that file, so it is a docs input even though it lives outside
web/docs (which is also why the checkout can't be sparse).
The post-deploy check:sitemap run is continue-on-error. Half of what it
checks — a Cloudflare-managed robots.txt shadowing ours, cache propagation
right after upload — isn't this repo's call, and a good deploy shouldn't go
red over it.
Needs CLOUDFLARE_API_TOKEN (Pages: Edit) and CLOUDFLARE_ACCOUNT_ID.
Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
docs.beardrive.ai shipped no robots.txt, so nothing on that host named the
sitemap — a crawler arriving at the subdomain had to guess the URL or be
handed it in Search Console. And every entry was a bare <loc>: no freshness
signal at all, on the site whose whole value is being current.
Each URL now carries the commit date of the markdown behind it, read from one
`git log` for the whole tree. The build refuses to guess: in a shallow clone
(the default for CI checkouts) git can only attribute every file to the single
commit it has, so lastmod is omitted entirely rather than claiming the site
changed wholesale on every deploy — Google discounts a sitemap that does that,
which would cost more than the absent dates. Hosts that want the dates need
full history; README says so.
Declaring @astrojs/sitemap explicitly replaces the copy Starlight adds for
itself rather than duplicating it — that's the supported way to reach these
options, and Starlight's own version only configures i18n, which this
single-language site doesn't use.
Adds `npm run check:sitemap <origin>`: robots.txt -> index -> every advertised
URL returns 200, the checks Search Console runs, against a local preview or
against production. Run against production today it fails on the missing
Sitemap: line, and reports the deployed site is several commits behind the
repo — /concepts/permissions/ and /reference/migration/ are live 404s.
Sidebar order is now Start here -> Working with agents -> Manual setup
(optional) -> Use cases -> Self-hosting -> Reference -> Concepts.
README and CLAUDE.md carry the group order and the rule for what belongs
in each, so both move with it.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The sidebar and the homepage disagreed. index.md's "Where to start"
already led with connecting an agent, but the left rail read Install
(brew) -> Quickstart (bdrive login, bdrive init) -> ... -> Connect an
agent, three groups down. Anyone following the rail met the CLI first and
the skill last — the opposite of how the product is meant to be adopted.
The agent page was also filed under guides/, which this repo defines as
agent-workflow docs rather than setup.
Sidebar order is now the recommended path, and that path is agent-first:
Start here what it is -> set up with your agent -> your first hour
Working with agents shared memory, artifacts, read heat, scoping
Manual setup (opt) install the CLI, set up by hand, skills and hooks
Self-hosting / Reference / Concepts unchanged
- start/setup (was guides/connect-an-agent): rewritten as the front door.
Claude Code's plugin, then the one-paste for Codex/Gemini/Hermes, then
what the agent just installed and how to check it.
- start/first-hour (new): the page that was missing — ask for a doc, get
a link back, share it, a teammate's agent picks it up. What success
looks like without a command you have to type.
- manual/skills-and-hooks (new): the mechanics lifted out of the old
onboarding page — per-platform paths, hook events, idempotency,
project-level vs per-user — so the Start page can stay conversational.
- manual/install and manual/setup-by-hand (were start/*): both now open
by saying you probably don't need them, and link back to the agent path.
- index.md leads with "You don't install it — you ask your agent to";
the CLI and hub sentence moves below it.
No `brew install` appears anywhere in Start here. Reference -> CLI stays
exactly where it was: the people most likely to self-host are CLI-first,
and burying it would read as condescending.
Three public URLs moved, so astro.config.mjs declares redirects. Static
builds emit meta-refresh only, so README carries copy-paste 301 rules for
the host — Firebase Hosting and a Cloud Storage + load balancer URL map.
Verified: 18 pages build, zero broken internal links across the built
output, all three redirects resolve. CLAUDE.md and the docs README record
the rule so this doesn't quietly revert.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
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.
Claude-Session: https://claude.ai/code/session_018GcqsM6prjdv9rUrhVVEiC
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
