The hub already abstracted authentication — AuthProvider, with BuiltinAuth
as the built-in implementation — and then reached around that seam three
times: Accounts() was declared on neither interface, admin.go type-asserted
*BuiltinAuth (five handlers silently degraded to 404/empty under any other
provider), and organizations were not on the seam at all.
That last gap had teeth. A deployment whose identities come from elsewhere
had no way to own its orgs, so the code that did own them wrote into the
hub's OrgDB from the side — and nothing stopped the hub from inventing an
org that the identity system had never heard of. One did: a hub-created org
held every project while the mirrored one sat empty, and no sync path could
see the difference.
Directory (directory.go) is where organizations live now. LocalDirectory
wraps today's OrgDB unchanged — same last-owner protection, same normEmail,
same "o-"+randHex(4) ids, same file/SQL persistence — so a self-hosted hub
behaves exactly as before. A deployment whose orgs are owned elsewhere
implements the same interface, returns ErrManagedElsewhere from the write
half, and the handlers answer 409 with ManageURL. The hub never learns why
a write was refused, only where to send the user.
Two rules shape the interface. Reads are on the request path: Role runs on
every project request, including the /store/* endpoints a device hits every
few seconds with a token that carries no identity claims, so an
implementation backed by a remote system answers from its own cache — and
that cache is its business, not the hub's. Writes are optional, because
"this hub owns its orgs" is a deployment fact, not a code path.
- Server.Orgs *OrgDB becomes Server.Dir Directory: 28 call sites, 8
nil-checks, one writeDirErr helper for the 409 translation.
- /api/orgs gains manage_url per org — the destination of the account
menu's Settings entry. The client follows a link and never branches on
which kind of hub it is talking to.
- Org administration becomes a real route, /orgs/<id>, retiring one of the
two URL-less panels CLAUDE.md grandfathers. When a directory's ManageURL
is not hub-local, the SPA fallback redirects there instead — so a hub that
cannot administer its orgs cannot paint a console whose every control 409s.
- Accounts() moves onto AuthProvider. admin.go's type assertion becomes an
optional AccountApprover, and a provider without one now answers 503
rather than an empty approval queue: "no queue here" and "queue is empty"
are different answers and only one of them was true.
Two reviews drove the rest. The architecture review caught a browser page
load that could delete org members (a display read ran the full membership
reconcile, and a 200 with an empty user list evicted everyone), one write
site that escaped the 409 translation, and a webhook that could wedge an
event stream behind an unappliable event. The design review, over eight
rounds, caught the org page rendering live controls on a hub that cannot
use them, a share link made unrevokable by a long filename, nine keyboard
tab stops parked off-screen behind a closed drawer, and — five separate
times — a fix of mine that looked right in the source and did nothing in
the browser.
Conformance tests run both a writable and a read-only implementation against
one contract; the seat, prune, and out-of-order regressions each have a test
written to fail against the old code.
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>
"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>
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>
Replaces the 🐻 emoji standing in for a logo everywhere. The mark is the
letter B built from three rectangles — a rail and two blocks, the same
shape as the product (a spine with volumes hanging off it). One fill, so
`currentColor` themes it in the sidebar, the favicon, and flat ink.
- Web app: <Mark> in shell.tsx replaces the emoji-in-a-gradient-tile
badge; the mark takes the honey and the wordmark takes text colour, so
the accent lands once. #vault-name sets in Jersey 10 at 18px — the face
is condensed, so that measures like 13px of the UI face.
- Auth pages (authlocal.go): server-rendered, so they had their own emoji
logo. Same mark, inline.
- Docs: bear.svg becomes the mark (fixed honey fill — Starlight renders
the logo as <img>, which can't inherit currentColor), and .site-title
sets in Jersey 10. Starlight tints that title with the accent by
default, which put honey on white in light mode and failed contrast;
it now takes --sl-color-white, matching the app.
- Favicon: the mark, as a data URI.
Jersey 10 is SIL OFL and self-hosted in both trees — Vite fingerprints
the app's copy into static/assets/, the docs serve theirs from public/ —
so no surface makes a third-party font request. Licence ships beside each
file. It is deliberately not a design token: tw.css's @theme block is
mirrored by the cloud landing's tokens.css and a drift check fails the
build if they diverge, so the logo face lives in plain CSS.
The cloud landing page carries the same mark and face (separate repo).
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>
The landing page sells BearDrive Cloud, so it now lives in the private
cloud module (web/landing, served by the hub at / for signed-out visitors)
instead of this repo. A self-hosted hub should never serve "Start free"
CTAs pointing at our managed service, and marketing for the paid product
doesn't belong in the AGPL tree.
Rebuilt there as an Astro site on the webapp's own design tokens, so the
landing and the app stop drifting apart visually.
Doc pointers updated to the new location.
Claude-Session: https://claude.ai/code/session_01RA5pQH92cxk5SfiYJeTUjK
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Existing tracked docs (self-hosting, assets) stay tracked — README and
the website link them; the ignore only keeps new files local.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- --page-read and --page-app both resolve to 768px (Tailwind md)
- History, folder listings, and the onboarding empty state move to the
default app column; Insights already sat there. Only rendered markdown
keeps read (HTML files keep their wide frame).
- layout.spec.ts repinned first (test-first); 59/59 e2e green
- shell.tsx docstring and stale style.css width comments updated
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Two changes to the demo data, both driven by how the screenshots read.
Warning triangles were on roughly half the files, which stops meaning
"look here" and starts meaning nothing. Staleness is now ~15% overall, and
correlated with reads rather than uniform: a heavily-read file is far
likelier to be stale, because it's the one everybody trusts and nobody
owns. That puts the red on big cells in the treemap and in the top-right
of the scatter — where the story is — instead of scattering it across a
hundred files nobody opens. Fewer warnings, and the ones left are the ones
worth reading.
The agent fleet goes from four to eight: one per teammate plus shared CI,
which is what a team's coverage matrix actually looks like once everyone
runs their own. Each has a bias (agentBias) toward particular areas, so
the matrix shows agents specialising instead of eight identical rows.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RA5pQH92cxk5SfiYJeTUjK
The demo harness generated files named run-015.md, des-031.md and so on,
with one-line bodies. Screenshots taken from it end up on the website, and
"des-031.md" in a treemap tells a visitor nothing about what BearDrive is
for.
Replaced the generator with a wiki a company would actually have: runbooks,
ADRs with real slugs, dated meeting notes, product and research docs, and
three hand-written documents (q3-findings, incident-response, first-week)
whose markdown renders with headings, tables, code and lists so the file
view is worth screenshotting. Read-heat shaping is unchanged — runbooks are
what the on-call agents live in, research notes are written for humans and
barely read by anything — so the insights views still light up.
Project renamed proj -> acme-wiki to match.
Also dropped the "must never be committed" note: the file has been in the
tree for a while and is genuinely useful for exploring the UI and taking
product screenshots. It still only runs under BDRIVE_MANUAL_SERVE=1.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RA5pQH92cxk5SfiYJeTUjK
A design pass over the new tiers found four problems, two of them
introduced by the refactor itself:
- Insights was assigned `wide`, but its charts are viewBox="0 0 720 …"
SVGs at width:100% — a wider column didn't show more, it magnified:
measured 1.67x at 1600px, painting a 10.5px treemap label at 21px,
larger than the page h1. Insights moves back to `app` and .in-chart
caps at its 760px design width. Widening a column must never mean
scaling content up; that line is now written into shell.tsx.
- /install rendered the same ConnectGuide as the project home, but
wrapped in the .onboard card: x=652 w=560 top=186 against home's
x=492 w=880 top=96 — two sidebar items apart, same component, three
different numbers. It renders directly now. .onboard stays what it
is, the empty-state hero card.
- History was `app`, so `.htime { margin-left: auto }` stranded each
timestamp ~600px from its path. It's a listing — same rows as the
folder view — so it belongs in `read` alongside it.
- --hero-top: 10vh is viewport-relative in the wrong direction: 84px on
a 390x844 phone against 80px on a 1280x800 desktop, i.e. the smallest
screen paid the most. Now clamp(32px, 8vh, 88px).
Also fixes the Copy button in the guide's code blocks: it was absolutely
positioned over a scrolling box, so its 72px of reserved padding
scrolled away with the content and the button landed on top of the
command (visible mid-token at 560px and on mobile). The block is a grid
now — code scrolls in its own track, the button can't overlap it.
layout.spec.ts gains three assertions: /install and home render the
guide identically, no chart scales past ~1.0x at 1600, and the tier map
matches the new assignments.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Every route invented its own content column: widths ran 560px to
unbounded (704 / 760 / 860 / 936 / 560), half of them uncentered because
they set max-width with no auto margins, and markdown pages carried the
constraint on #content itself so the 40px gutter came out of the reading
measure — .md text ran 624px against the folder listing's 704px directly
beside it in the tree.
Now there is exactly one primitive:
- #content owns scrolling and the page gutter, never a width.
- <Page width="read|app|wide"> (shell.tsx) owns width and centering, one
per view, driven by CSS tokens --page-read/-app/-wide (704/880/1200).
read = prose + listings, app = structured views, wide = data-dense.
- .markdown goes back to being typography only; the column around it is
.page.read, which also retires the #content.markdown min-width hack.
- Views declare no layout: .guide/.insights/.history/.admin/.dirlist/
.markdown lost their max-widths, Browser picks the width per route.
- Short centered states (empty, loading, not-found, no-preview, onboard)
shared one --hero-top instead of 8/12/15/22vh apiece.
Insights moves to wide — its treemap and coverage matrix were cramped at
760. Everything else lines up: app pages at 880, read pages at 704, same
edges on every route.
e2e/layout.spec.ts locks it in: one .page per route, widths resolve to
the tokens, same-width routes share edges, #content never constrains
width, and no view re-declares a column inside .page.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The hub's install guide told Codex and Hermes users to run four CLI
commands by hand, and the one people skipped — `bdrive hooks install` —
is exactly the one that makes files sync at turn boundaries. Hand the
setup to the agent instead, the way the Claude tab hands it to the
plugin.
- `bdrive skill install` (internal/agentskills, plugin/embed.go): the
binary now carries the beardrive skill and writes it to any agent that
reads SKILL.md — ~/.{claude,codex,gemini,hermes}/skills/beardrive/.
User-level on purpose: the skill is about the CLI, not one folder, and
a synced project folder should never carry it. Idempotent; refreshes a
stale copy after a CLI upgrade. Bare `bdrive skill` prints the table,
mirroring `bdrive hooks`.
- Guide's Codex/Hermes tabs are now a single paste, no terminal: the
prompt has the agent install the CLI, keep the skill, sign in, init,
and register hooks. The commands ride inside the prompt because these
agents ship no BearDrive knowledge (Claude's tab is terse only because
the plugin carries it). `login --device` there — a browser-callback
sign-in is invisible to an agent mid-turn, while the device flow gives
it a code and URL to relay. Plain commands live on in an "or run it
yourself" fallback.
- Docs realigned: README, SKILL.md, /beardrive:install, self-hosting.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Members and shares-audit render through @tanstack/react-table (sortable,
spec-first); org rename, hub signup policy, and onboarding create/join are
react-hook-form + zod with inline errors replacing toast-on-typo. 55/55.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VbiaaVM2ACxeRi8ySG9ybc
Only the visible window renders (collapsed subtrees not at all — the ~5k-file
DOM cliff from the CTO review is gone). Flat rows keep data-path/.active
contract, nesting guide lines, mobile 44px rows; scroll-into-view moves into
FileTree via scrollToIndex. Fold behavior pinned by spec first. 54/54.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VbiaaVM2ACxeRi8ySG9ybc
On /insights/<path> and /history/<path> the tree highlights (and unfolds to)
the target; Dashboard/History menu items light up only for their root,
project-wide views. 50/50 e2e.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VbiaaVM2ACxeRi8ySG9ybc
Icon-only trigger in the vault header (Linear-style); a tiny search.ts
emitter asks Browser's palette to open — no plumbing through the shell.
Custom tooltip card (label + kbd chip, arrow) on hover/focus. Topbar search
and its centered styles removed. 47/47 e2e incl. header-trigger spec.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VbiaaVM2ACxeRi8ySG9ybc
- search control sits centered in the topbar at ~2x width, kbd right-aligned
(static again on mobile)
- Share is icon-only
- History button shows only on the project home: gone from dashboard/history
(and other view routes) and whenever a file/folder is selected — the ⋯
menu and sidebar carry it
- Download is ⋯-menu-only; a hidden anchor keeps the browser download flow
46/46 e2e.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VbiaaVM2ACxeRi8ySG9ybc
/<pid>/install and /<pid>/settings join /insights and /history as view
routes — deep links, reload, and back/forward work; the sidebar menu
navigates instead of toggling panel state. Rule recorded in CLAUDE.md:
new surfaces are view routes, never URL-less panels (org/hub admin panels
are the legacy exceptions). 46/46 e2e incl. deep-link spec.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VbiaaVM2ACxeRi8ySG9ybc
Panels are not routes: navigating to the already-current /insights URL never
changes pathname, so the route-change effect couldn't close the open panel.
Menu Dashboard (and the ⋯ Insights entry) now close the panel explicitly.
Regression spec added; 46/46.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VbiaaVM2ACxeRi8ySG9ybc
Under the project dropdown: Dashboard (project insights), Installation
(connect guide, moved out of Settings), Settings (project facts). Active
states follow the open view/panel; the inline gear next to the dropdown is
gone. 46/46 e2e.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VbiaaVM2ACxeRi8ySG9ybc
The ⋯ menu's Insights opens /insights/<current path>: a folder scopes the
treemap/scatter/hot-path/agent-coverage to its subtree, a file to itself;
crumb and title show the scope. urlForView now carries targets for insights
like it did for history. 45/45 e2e.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VbiaaVM2ACxeRi8ySG9ybc
Topbar button, ⋯ menu entry, palette action, hidden file input, and the
upload plumbing (upload.ts) are gone; the server upload API stays (devices
and the store proxy depend on it). Spec reworked to seed via API and assert
the affordance is absent. 44/44 green.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VbiaaVM2ACxeRi8ySG9ybc
- header is the brand only (BearDrive), linking home
- Projects section is a dropdown (native select, styled) with the project
mark, plus the project-settings gear beside it and + to create
- sidebar footer is the account row (avatar, name, email) opening a popover:
Organization → <org> Settings, Hub → Signup & access (admins), Account →
Log out (danger red)
- volume mode unchanged (sign-out stays in its header)
- Playwright suite reworked for the new layout — 44/44 green; static rebuilt
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VbiaaVM2ACxeRi8ySG9ybc
Design feedback applied:
- icons are lucide-react (lucide.dev) behind the existing <Icon name> API;
the inline SVG sprite is gone
- org bar (sidebar footer): the Manage text button is a gear icon opening
the org admin panel; sign-out moved here, after the gear
- header: the org-manage (people) button is removed; the header gear now
opens a new per-PROJECT settings panel (identity facts + connect guide);
sign-out stays in the header only when no project/org bar is present
(volume mode, loading, empty state)
Playwright suite updated and green (44/44); static/ rebuilt.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VbiaaVM2ACxeRi8ySG9ybc
Snow Lee