mirror of
https://github.com/runbear-io/beardrive.git
synced 2026-08-25 08:08:08 +02:00
docs: use cases move to the marketing site, and the logo goes home (#153)
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>
This commit is contained in:
Snow Lee (Sungwon)
co-authored by
Claude Opus 5
Claude Opus 5
parent
3d2acf658c
commit
8931004b4a
@@ -100,7 +100,7 @@ never spawns the binary outside a mount.
|
||||
|
||||
## Docs site (`web/docs`)
|
||||
|
||||
`web/docs/` is the public documentation at docs.beardrive.ai — Astro 7 + [Starlight](https://starlight.astro.build) (Starlight requires Astro ^7; the cloud landing is still on Astro 5 — separate projects, so they upgrade independently), static output, Pagefind search, `llms.txt` via `starlight-llms-txt`. Unlike the hub frontend (`internal/webapp/static`) and the cloud landing page (`cloud/internal/landing/dist`) it is **not** `go:embed`ed: docs change far more often than the binary, and a search index has no business shipping in every self-hoster's install. It deploys on its own from `dist/`, so `go build` never touches it. Sidebar order is explicit in `astro.config.mjs` — a new page under `src/content/docs/` is invisible until listed there, and every page needs a `description` (meta description, search snippet, and `llms.txt` line). **The sidebar order is the recommended path, and that path is agent-first**: `Start here` (what it is → set up with your agent → your first hour) never mentions installing a binary; the CLI route lives in `Manual setup (optional)` (install the CLI, set up by hand, hooks in detail) — same destination, one click away, never on the critical path. New onboarding content belongs in `Start here` and should say what to ask an agent, not what to type. `Use cases` (after `Manual setup`) holds job-shaped pages — "Share work across your team's agents", "Turn a personal brain into a company brain" — with the persona named in the first line and the `description`, not in the title; they route into the guides and never re-teach a feature. Moved URLs keep `redirects` entries in `astro.config.mjs` (static builds emit meta-refresh; real 301s live in the host config, see `web/docs/README.md`). **Guides are agent-workflow docs, not CLI tutorials** (`Working with agents`: shared agent memory, artifacts/links, read heat, scoping); command-by-command detail belongs in `reference/cli.md`. Design tokens are **generated, never copied**: `scripts/tokens.mjs` reads the `@theme` block in `internal/webapp/frontend/src/tw.css` and emits the gitignored `src/styles/tokens.gen.css`, which `src/styles/custom.css` maps onto Starlight's `--sl-color-*` — so the palette cannot drift and there is no checker to maintain (contrast the cloud landing, which keeps a copy policed by its own `check-tokens.mjs`). Because the build reads that file *outside* `web/docs`, a deploy host must check out the whole repo, not the subdirectory. Note `llms.txt` convention wants the root domain, so `beardrive.ai/llms.txt` should point at the docs subdomain — that redirect lives in the cloud landing and is the one cross-repo coordination point.
|
||||
`web/docs/` is the public documentation at docs.beardrive.ai — Astro 7 + [Starlight](https://starlight.astro.build) (Starlight requires Astro ^7; the cloud landing is still on Astro 5 — separate projects, so they upgrade independently), static output, Pagefind search, `llms.txt` via `starlight-llms-txt`. Unlike the hub frontend (`internal/webapp/static`) and the cloud landing page (`cloud/internal/landing/dist`) it is **not** `go:embed`ed: docs change far more often than the binary, and a search index has no business shipping in every self-hoster's install. It deploys on its own from `dist/`, so `go build` never touches it. Sidebar order is explicit in `astro.config.mjs` — a new page under `src/content/docs/` is invisible until listed there, and every page needs a `description` (meta description, search snippet, and `llms.txt` line). **The sidebar order is the recommended path, and that path is agent-first**: `Start here` (what it is → set up with your agent → your first hour) never mentions installing a binary; the CLI route lives in `Manual setup (optional)` (install the CLI, set up by hand, hooks in detail) — same destination, one click away, never on the critical path. New onboarding content belongs in `Start here` and should say what to ask an agent, not what to type. Job-shaped "use case" pages — the ones aimed at someone deciding rather than someone building — belong on the marketing site (beardrive.ai/use-cases), not here; the docs sidebar ends with a `More` group of off-site links (use cases, blog, GitHub) and the header logo points at beardrive.ai via the `SiteTitle` override in `src/components/`, since Starlight has no config for that link. Moved URLs keep `redirects` entries in `astro.config.mjs` (static builds emit meta-refresh; real 301s live in the host config, see `web/docs/README.md`). **Guides are agent-workflow docs, not CLI tutorials** (`Working with agents`: shared agent memory, artifacts/links, read heat, scoping); command-by-command detail belongs in `reference/cli.md`. Design tokens are **generated, never copied**: `scripts/tokens.mjs` reads the `@theme` block in `internal/webapp/frontend/src/tw.css` and emits the gitignored `src/styles/tokens.gen.css`, which `src/styles/custom.css` maps onto Starlight's `--sl-color-*` — so the palette cannot drift and there is no checker to maintain (contrast the cloud landing, which keeps a copy policed by its own `check-tokens.mjs`). Because the build reads that file *outside* `web/docs`, a deploy host must check out the whole repo, not the subdirectory. Note `llms.txt` convention wants the root domain, so `beardrive.ai/llms.txt` should point at the docs subdomain — that redirect lives in the cloud landing and is the one cross-repo coordination point.
|
||||
|
||||
## PR descriptions
|
||||
|
||||
|
||||
+15
-4
@@ -102,16 +102,27 @@ recommended path is agent-first:
|
||||
- **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.
|
||||
- **Use cases** — job-shaped titles ("Share work across your team's agents"),
|
||||
persona named in the first line and in the `description`. These pages ROUTE:
|
||||
who it's for, what you get, the one setup difference, links out. The moment
|
||||
one starts teaching a feature, it links to the guide that owns it instead.
|
||||
- **Self-hosting**, **Reference**, **Concepts** — unchanged in intent.
|
||||
- **More** — off-site links (use cases, blog, GitHub), last because the order
|
||||
is the recommended path and nothing that leaves the docs belongs above them.
|
||||
|
||||
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.
|
||||
|
||||
Job-shaped "use case" pages — written for someone deciding, not someone
|
||||
building — live on the marketing site (`beardrive.ai/use-cases`), which owns
|
||||
that audience and already had its own copy of all of them. The docs used to
|
||||
carry a parallel set; they were deleted and each URL redirects to its
|
||||
counterpart there.
|
||||
|
||||
The header logo links to `beardrive.ai`, not the docs index. Starlight always
|
||||
points it at the docs root and exposes no option for it, so that link lives in
|
||||
`src/components/SiteTitle.astro` — Starlight's own component with one changed
|
||||
`href`, registered through `components:` in `astro.config.mjs`. If a Starlight
|
||||
upgrade restyles the header, that file is the first thing to re-diff against
|
||||
`node_modules/@astrojs/starlight/components/SiteTitle.astro`.
|
||||
|
||||
## Deploying
|
||||
|
||||
Static output in `dist/`. Any static host works; build command `npm run build`,
|
||||
|
||||
+26
-16
@@ -69,6 +69,19 @@ export default defineConfig({
|
||||
"/start/quickstart": "/manual/setup-by-hand/",
|
||||
"/guides/connect-an-agent": "/start/setup/",
|
||||
"/manual/skills-and-hooks": "/manual/hooks/",
|
||||
// Use cases moved to the marketing site, which already published the same
|
||||
// six pages at the same slugs. They were live and indexed here for a
|
||||
// month, so every one of them keeps a redirect — off-site, which is
|
||||
// exactly what a page that is no longer documentation should do.
|
||||
"/use-cases/team-artifacts": "https://beardrive.ai/use-cases/team-artifacts",
|
||||
"/use-cases/team-wiki": "https://beardrive.ai/use-cases/team-wiki",
|
||||
"/use-cases/business-context": "https://beardrive.ai/use-cases/business-context",
|
||||
"/use-cases/company-brain": "https://beardrive.ai/use-cases/company-brain",
|
||||
"/use-cases/personal-wiki": "https://beardrive.ai/use-cases/personal-wiki",
|
||||
"/use-cases/multi-device": "https://beardrive.ai/use-cases/multi-device",
|
||||
// The one with no counterpart over there yet — land on the index rather
|
||||
// than a 404 someone else's deploy has to fix.
|
||||
"/use-cases/shared-skills": "https://beardrive.ai/use-cases/",
|
||||
},
|
||||
integrations: [
|
||||
// Starlight adds @astrojs/sitemap itself, but only when the config hasn't
|
||||
@@ -81,6 +94,9 @@ export default defineConfig({
|
||||
description:
|
||||
"Google Drive for AI agents. One shared folder your whole team's agents read and write — real files, synced in seconds, with history, provenance, and share links.",
|
||||
logo: { src: "./src/assets/bear.svg", alt: "BearDrive" },
|
||||
// The logo is the way back to beardrive.ai. Starlight always points it
|
||||
// at the docs root, so the link lives in a component override.
|
||||
components: { SiteTitle: "./src/components/SiteTitle.astro" },
|
||||
customCss: ["./src/styles/tokens.gen.css", "./src/styles/custom.css"],
|
||||
social: [
|
||||
{
|
||||
@@ -135,22 +151,6 @@ export default defineConfig({
|
||||
{ label: "Hooks in detail", slug: "manual/hooks" },
|
||||
],
|
||||
},
|
||||
{
|
||||
// Job-shaped titles, persona named in the description (which is also
|
||||
// the search snippet and the llms.txt line). These pages ROUTE — the
|
||||
// moment one starts teaching a feature, it links to the guide that
|
||||
// owns it instead.
|
||||
label: "Use cases",
|
||||
items: [
|
||||
{ label: "Share work across your team's agents", slug: "use-cases/team-artifacts" },
|
||||
{ label: "Keep a wiki your agents maintain", slug: "use-cases/team-wiki" },
|
||||
{ label: "Give your coding agents the business context", slug: "use-cases/business-context" },
|
||||
{ label: "Turn a personal brain into a company brain", slug: "use-cases/company-brain" },
|
||||
{ label: "Run a personal wiki, publish part of it", slug: "use-cases/personal-wiki" },
|
||||
{ label: "Carry one context across agents and devices", slug: "use-cases/multi-device" },
|
||||
{ label: "Give every agent on the team the same skills", slug: "use-cases/shared-skills" },
|
||||
],
|
||||
},
|
||||
{
|
||||
label: "Self-hosting",
|
||||
items: [
|
||||
@@ -175,6 +175,16 @@ export default defineConfig({
|
||||
{ label: "Project permissions", slug: "concepts/permissions" },
|
||||
],
|
||||
},
|
||||
// Off-site, and last on purpose: the sidebar order is the recommended
|
||||
// path, so nothing that leaves the docs belongs above the docs.
|
||||
{
|
||||
label: "More",
|
||||
items: [
|
||||
{ label: "Use cases", link: "https://beardrive.ai/use-cases/" },
|
||||
{ label: "Blog", link: "https://beardrive.ai/blog/" },
|
||||
{ label: "GitHub", link: "https://github.com/runbear-io/beardrive" },
|
||||
],
|
||||
},
|
||||
],
|
||||
}),
|
||||
],
|
||||
|
||||
@@ -0,0 +1,52 @@
|
||||
---
|
||||
// The header logo goes HOME, and home is beardrive.ai — not the docs index.
|
||||
// Starlight has no config knob for that link (it always points at the docs
|
||||
// root), so this is the documented escape hatch: a component override that
|
||||
// changes the href and nothing else. Everything below is Starlight's own
|
||||
// SiteTitle, minus the two-logo branch this site doesn't use — one `src`, so
|
||||
// the light/dark alternate never renders.
|
||||
import { logos } from "virtual:starlight/user-images";
|
||||
import config from "virtual:starlight/user-config";
|
||||
const { siteTitle } = Astro.locals.starlightRoute;
|
||||
---
|
||||
|
||||
<a href="https://beardrive.ai" class="site-title sl-flex">
|
||||
{
|
||||
config.logo && logos.dark && (
|
||||
<img
|
||||
alt={config.logo.alt}
|
||||
src={logos.dark.src}
|
||||
width={logos.dark.width}
|
||||
height={logos.dark.height}
|
||||
/>
|
||||
)
|
||||
}
|
||||
<span class:list={{ "sr-only": config.logo?.replacesTitle }} translate="no">
|
||||
{siteTitle}
|
||||
</span>
|
||||
</a>
|
||||
|
||||
<style>
|
||||
@layer starlight.core {
|
||||
.site-title {
|
||||
align-items: center;
|
||||
gap: var(--sl-nav-gap);
|
||||
font-size: var(--sl-text-h4);
|
||||
font-weight: 600;
|
||||
color: var(--sl-color-text-accent);
|
||||
text-decoration: none;
|
||||
white-space: nowrap;
|
||||
min-width: 0;
|
||||
}
|
||||
span {
|
||||
overflow: hidden;
|
||||
}
|
||||
img {
|
||||
height: calc(var(--sl-nav-height) - 2 * var(--sl-nav-pad-y));
|
||||
width: auto;
|
||||
max-width: 100%;
|
||||
object-fit: contain;
|
||||
object-position: 0 50%;
|
||||
}
|
||||
}
|
||||
</style>
|
||||
@@ -40,7 +40,7 @@ page.
|
||||
Code, one paste anywhere else, and the folder syncs from then on.
|
||||
- **[Your first hour](/start/first-hour/)** — what a connected folder feels like:
|
||||
ask for a doc, get a link back, teammates' agents pick it up.
|
||||
- **[Use cases](/use-cases/team-artifacts/)** — how this fits a real situation:
|
||||
- **[Use cases](https://beardrive.ai/use-cases/)** — how this fits a real situation:
|
||||
a team sharing what its agents produce, a wiki that maintains itself, an
|
||||
existing knowledge base that needs teammates, one context across devices.
|
||||
- **[Run a hub](/self-hosting/run-a-hub/)** — self-host in about ten minutes.
|
||||
|
||||
@@ -46,7 +46,7 @@ more choice: start from a structure, or from scratch. Four are shipped:
|
||||
actionable something is, with explicit archiving.
|
||||
- **Shared agent skills** (`.claude/skills/`) — a skill library the whole
|
||||
team's agents load, kept current by syncing. See
|
||||
[Give every agent on the team the same skills](/use-cases/shared-skills/).
|
||||
[Give every agent on the team the same skills](https://beardrive.ai/use-cases/).
|
||||
|
||||
Each is a small skeleton plus an `AGENTS.md` telling every agent on the team
|
||||
where a new file goes, when something is archived or superseded, and what a good
|
||||
|
||||
@@ -1,140 +0,0 @@
|
||||
---
|
||||
title: Give your coding agents the business context
|
||||
description: For an engineering team whose customer context lives where their coding agents can't see it. Sync a context folder into the repo so agents build with the calls, renewals, and roadmap rationale in front of them — and write back what shipped.
|
||||
---
|
||||
|
||||
Your coding agent has the whole codebase and none of the reasons. Why this
|
||||
customer needs the export, which account the deadline is really for, what was
|
||||
promised on last week's call — all of it lives in a meeting tool, a CRM, or
|
||||
someone's head. So the agent writes technically correct code that solves the
|
||||
wrong problem, and the correction arrives in review.
|
||||
|
||||
The fix is not another integration. It is a folder of markdown, synced into the
|
||||
repo, that the agent reads the same way it reads `src/`.
|
||||
|
||||
## What you end up with
|
||||
|
||||
- A `context/` folder inside the repo, synced from the hub, that every coding
|
||||
agent on the team reads before it plans.
|
||||
- Context written by the people who have it — sales, CS, support, PM — from
|
||||
their own agents, without any of them opening the repo.
|
||||
- A path back: what shipped, what was deferred, and the known limitations, in
|
||||
the same folder, where the customer-facing team's agents pick it up.
|
||||
|
||||
## Set it up
|
||||
|
||||
Ask your agent, in the repo:
|
||||
|
||||
> Set up BearDrive here, syncing only `context/`.
|
||||
|
||||
That runs `bdrive init context`, which makes `./context` the project — creating
|
||||
the folder if it doesn't exist, writing `context/.bdrive/config.json`, and
|
||||
starting the daemon. Nothing outside `context/` is scanned or sent — `.git/` and
|
||||
`.bdrive/` never sync at all.
|
||||
|
||||
### Then tell git to ignore it
|
||||
|
||||
This step is not optional. Add to `.gitignore`:
|
||||
|
||||
```gitignore
|
||||
context/
|
||||
.bdrive/
|
||||
```
|
||||
|
||||
A path must have **one writer**. If `context/` is also git-tracked, a
|
||||
teammate's `git pull` or branch switch rewrites those files with older content,
|
||||
and sync broadcasts that as a fresh edit — silently reverting the team's latest
|
||||
notes. Git moves the code; BearDrive moves the context; they never touch the
|
||||
same paths.
|
||||
|
||||
If the folder is already committed, hand it over rather than deleting it:
|
||||
`git rm -r --cached context` and commit the `.gitignore` change. Teammates pull,
|
||||
run the same setup, and identical content converges with no conflicts.
|
||||
|
||||
### Point the agent at it
|
||||
|
||||
Add a few lines to the repo's `AGENTS.md` (or `CLAUDE.md`) saying what is in
|
||||
`context/` and when to read it. Without it, agents treat the folder as
|
||||
decoration:
|
||||
|
||||
```markdown
|
||||
## Business context
|
||||
|
||||
`context/` is synced from BearDrive — customer calls, account notes, and
|
||||
roadmap rationale, maintained by the GTM team. Read it before planning any
|
||||
customer-facing change. It is not git-tracked; do not commit it.
|
||||
```
|
||||
|
||||
See [Shared agent memory](/guides/shared-agent-memory/) for the two-file
|
||||
pattern this follows.
|
||||
|
||||
## The loop
|
||||
|
||||
**Context in.** A CS lead finishes a renewal call and asks their own agent to
|
||||
write it up. They are not in the repo and never will be — they are in a folder
|
||||
on their laptop that happens to be the same project:
|
||||
|
||||
> Write up the Acme renewal call in `customers/acme/`.
|
||||
|
||||
Seconds later it is on every engineer's disk, under `context/customers/acme/`.
|
||||
|
||||
**Context used.** An engineer starts work:
|
||||
|
||||
> Add bulk export to the reporting page.
|
||||
|
||||
Their agent reads the context folder before it plans, and comes back with the
|
||||
constraint nobody put in the ticket — Acme needs CSV specifically, because the
|
||||
renewal call flagged their finance team can't ingest JSON. That is the whole
|
||||
point: the objection arrives before the code, not in review.
|
||||
|
||||
**Context back.** When it ships:
|
||||
|
||||
> Note what we shipped for Acme in `context/customers/acme/shipped.md`.
|
||||
|
||||
The CS lead's agent reads that before the next call. The folder is a loop, not a
|
||||
feed — engineering is a producer of context too, and the round trip is what
|
||||
keeps the GTM side from promising things that were quietly deferred.
|
||||
|
||||
## Getting notes in from meeting tools
|
||||
|
||||
BearDrive has no connectors, and does not need one to be useful here: exports
|
||||
are files. Gong, Granola, Fathom and most CRMs will drop a markdown or text
|
||||
transcript, and anything that lands in the folder is on every machine seconds
|
||||
later. A scheduled job that writes exports into the folder is a normal writer
|
||||
like any other.
|
||||
|
||||
Two things worth deciding before you turn the tap on:
|
||||
|
||||
- **Raw transcripts are not context.** A folder of hour-long transcripts makes
|
||||
agents slower and less accurate, not better. Have the writing agent produce a
|
||||
short summary and keep the transcript out, or park raw material in a
|
||||
subfolder the repo's agents are told to skip.
|
||||
- **One writer per path.** If a job rewrites `customers/acme/notes.md` on a
|
||||
schedule and a human's agent edits the same file, you get conflict copies.
|
||||
Give automation its own subfolder.
|
||||
|
||||
## Keep it small, and keep it clean
|
||||
|
||||
Everything in `context/` lands on every engineer's laptop. That is the feature,
|
||||
and it is also the thing to be deliberate about.
|
||||
|
||||
- **Scope by project, not by folder.** Membership is per project, and everyone
|
||||
in a project sees all of it. Material that shouldn't reach the whole
|
||||
engineering team belongs in a *separate project* — not a subfolder. See
|
||||
[Turn a personal brain into a company brain](/use-cases/company-brain/) for
|
||||
how that model works.
|
||||
- **Opt things out** with `.bdriveignore` — see
|
||||
[Scoping the folder](/guides/scoping/). It always syncs, so one person's rules
|
||||
apply for the whole team.
|
||||
- **Watch what actually gets read.** [Read heat](/guides/what-agents-read/)
|
||||
shows which context pages agents consume. Pages nothing has read in a month
|
||||
are candidates for deletion, and deleting them makes the rest work better.
|
||||
|
||||
## What matters for this case
|
||||
|
||||
- **[Scoping the folder](/guides/scoping/)** — subfolder syncing and
|
||||
`.bdriveignore`, which is the whole mechanism this case rests on.
|
||||
- **[Shared agent memory](/guides/shared-agent-memory/)** — the `AGENTS.md`
|
||||
pointer that makes agents actually open the folder.
|
||||
- **[Share work across your team's agents](/use-cases/team-artifacts/)** — the
|
||||
general version, for teams whose shared folder isn't attached to a repo.
|
||||
@@ -1,110 +0,0 @@
|
||||
---
|
||||
title: Turn a personal brain into a company brain
|
||||
description: You already have a knowledge base your agent reads — an OKF bundle, a gbrain repo, an Obsidian vault. Sync it so every teammate's agent reads the same one, with no export and no schema.
|
||||
---
|
||||
|
||||
You already have the brain. It works, your agent reads it, and it is markdown on
|
||||
disk. What it doesn't have is teammates.
|
||||
|
||||
## Why there is nothing to convert
|
||||
|
||||
BearDrive syncs directories of real files. A knowledge base that is already a
|
||||
folder of markdown needs no export, no adapter, and no schema:
|
||||
|
||||
- **[OKF](https://cloud.google.com/blog/products/data-analytics/how-the-open-knowledge-format-can-improve-data-sharing/)**
|
||||
bundles — markdown with YAML frontmatter, cross-linked, `index.md` and
|
||||
`log.md` at the root.
|
||||
- **[gbrain](https://github.com/garrytan/gbrain)** brain repos — `people/`,
|
||||
`companies/`, `projects/`, `notes/`, one page per concept.
|
||||
- Obsidian vaults, Logseq graphs, or a folder of notes you never named.
|
||||
|
||||
Your format is already the wire format. BearDrive moves the files and stays out
|
||||
of the way — it has no opinion about frontmatter, link syntax, or folder names.
|
||||
|
||||
Derived state stays put too. gbrain keeps its index in PGLite or Postgres and
|
||||
its config in `~/.gbrain/`, both outside the brain repo, so there is nothing to
|
||||
exclude. If yours does write an index beside the notes, drop it in
|
||||
[`.bdriveignore`](/guides/scoping/).
|
||||
|
||||
## Set it up
|
||||
|
||||
Same as any project — [ask your agent](/start/setup/), in the brain folder:
|
||||
|
||||
> Set up BearDrive here and invite my team.
|
||||
|
||||
If the brain is a subfolder of something larger, name it and only it:
|
||||
`bdrive init brain` — the folder you name is the project, and nothing outside it
|
||||
is scanned. Teammates mount the same project on their own
|
||||
machines, wherever they like it on disk, and keep running their own local brain
|
||||
against the synced files.
|
||||
|
||||
That is the whole migration. Files start arriving in seconds.
|
||||
|
||||
## What you can skip at small scale
|
||||
|
||||
gbrain's own company-brain setup shares a brain through infrastructure: a remote
|
||||
Postgres, an HTTP MCP server, and OAuth credentials scoped per teammate, with
|
||||
isolation enforced in SQL. That buys real things — one retrieval endpoint, and
|
||||
per-person access the database itself guarantees.
|
||||
|
||||
If what you actually want is *everyone's agent reading the same notes*, file
|
||||
sync plus each person's local brain gets you there with no shared database, no
|
||||
server to run, and no connection limits. Keep the server for SQL-enforced
|
||||
scoping, a single query endpoint, or a brain too large to sit on a laptop.
|
||||
|
||||
The two compose. BearDrive distributes the source of truth; anything you run on
|
||||
top of those files is your business.
|
||||
|
||||
## Privacy is per project, not per folder
|
||||
|
||||
This is the one place the models differ, and it is worth getting right.
|
||||
|
||||
gbrain scopes access per person — `internal/bob/` invisible to Alice, enforced
|
||||
by OAuth and SQL. **BearDrive's unit of membership is the project**: everyone in
|
||||
a project sees the whole folder. There is no per-folder permission.
|
||||
|
||||
So a walled boundary is a **separate project**:
|
||||
|
||||
| Content | Project |
|
||||
|---|---|
|
||||
| Company knowledge everyone should have | `company-brain` — whole team |
|
||||
| HR, comp, performance notes | `people-ops` — that team only |
|
||||
| A customer's material you can't mix | `customer-acme` — the account team |
|
||||
|
||||
One machine can mount all three, in sibling folders. Your agent reads across
|
||||
them locally, because on disk they're just folders — the wall is on the hub,
|
||||
where it belongs.
|
||||
|
||||
## When two brains rewrite one note
|
||||
|
||||
Consolidation passes rewrite markdown. If two teammates' agents rewrite the same
|
||||
file in the same window, BearDrive resolves it last-writer-wins and preserves
|
||||
the loser as a conflict copy beside it — nothing is lost, but someone has to
|
||||
merge the two.
|
||||
|
||||
In practice:
|
||||
|
||||
- Let **one machine** run scheduled consolidation, not everybody's.
|
||||
- Give people **their own subfolders** for raw capture (`notes/alice/`), and
|
||||
keep the synthesized pages in shared space.
|
||||
- Ad-hoc edits are fine. The window that matters is seconds, and
|
||||
[history](/guides/agent-artifacts/) shows who wrote what if you need to look.
|
||||
|
||||
## What you get that the git repo didn't
|
||||
|
||||
- **No git ceremony on notes.** No commit, no push, no pull, no merge conflicts
|
||||
in prose. Files land in seconds.
|
||||
- **Provenance per change** — the account, the device, and the agent session
|
||||
behind every edit, in the hub's history.
|
||||
- **Share links** for people outside the team: any page becomes a public URL
|
||||
that renders, revocable and optionally expiring.
|
||||
- **[Read heat](/guides/what-agents-read/)** — which pages your agents actually
|
||||
consume, and which ones everyone relies on and nobody maintains. Brains rot
|
||||
quietly; this is how you see it.
|
||||
|
||||
## Read next
|
||||
|
||||
- **[Shared agent memory](/guides/shared-agent-memory/)** — an `AGENTS.md` map at
|
||||
the brain's root, so a teammate's agent knows the layout on its first turn.
|
||||
- **[Scoping the folder](/guides/scoping/)** — subfolder syncing and
|
||||
`.bdriveignore`, for the parts that shouldn't travel.
|
||||
@@ -1,57 +0,0 @@
|
||||
---
|
||||
title: Carry one context across agents and devices
|
||||
description: For one person running several machines and more than one agent — laptop, desktop, a server, Claude Code and Codex. One project, mounted everywhere, so whichever agent you talk to starts from the same state.
|
||||
---
|
||||
|
||||
The work is continuous; the machines are not. You start something in Claude Code
|
||||
on the laptop, pick it up in Codex on the desktop, and the second agent knows
|
||||
nothing about the first.
|
||||
|
||||
## What you end up with
|
||||
|
||||
- One project, mounted on every machine, in whatever folder each one prefers.
|
||||
- Every agent on every device starts its turn from the same files.
|
||||
- Offline is normal, not an error state — changes queue and reconcile when the
|
||||
machine is reachable again.
|
||||
|
||||
## Set it up
|
||||
|
||||
[Set up with your agent](/start/setup/) on the first machine. On each additional
|
||||
one, connect the *same project* rather than making a new one — the agent needs
|
||||
the project id, which the hub shows on the project's home page:
|
||||
|
||||
> Set up BearDrive here, connecting to project `79d0a07c-1b2c-4d3e-8f90-a1b2c3d4e5f6`.
|
||||
|
||||
The folder does not have to match across machines. State is keyed by a stable
|
||||
project id, never a path, so `~/work` on one and `~/Documents/work` on another
|
||||
are the same project. Moving or renaming a folder later is free.
|
||||
|
||||
The hooks are registered **once per machine** — `bdrive init` does it on each
|
||||
new device — and from then on they cover every folder that machine syncs. That is what makes each agent pull before it answers. See
|
||||
[hooks in detail](/manual/hooks/).
|
||||
|
||||
## More than one agent per machine
|
||||
|
||||
The hooks are written into each platform's own user config, so Claude Code,
|
||||
Codex, Gemini CLI, and Hermes can all be wired into the same folder at once. They read the same files and their writes are stamped with which agent
|
||||
session made them, so `bdrive log` and the hub's history stay legible even when
|
||||
four agents share a project.
|
||||
|
||||
## What happens when two machines edit the same file
|
||||
|
||||
Each device writes only its own append-only journal, and every device replays
|
||||
all journals in the same deterministic order — so they converge without a
|
||||
locking service.
|
||||
|
||||
If the same file was edited on two machines in the same window, the later write
|
||||
wins and the other is preserved as a conflict copy beside it. Nothing is lost;
|
||||
you decide what to merge. Working offline for a day and reconnecting is the same
|
||||
mechanism, just with a longer window.
|
||||
|
||||
## What matters for this case
|
||||
|
||||
- **[Hooks in detail](/manual/hooks/)** — what each new
|
||||
machine registers, and why the pull hook is the one that matters.
|
||||
- **[How sync works](/concepts/how-it-works/)** — journals, blobs, and
|
||||
deterministic replay, if you want to know why this converges rather than
|
||||
hoping it does.
|
||||
@@ -1,53 +0,0 @@
|
||||
---
|
||||
title: Run a personal wiki, publish part of it
|
||||
description: For one person — a researcher, writer, or consultant — who wants a versioned notebook their agent maintains, and the ability to publish a single page without publishing the notebook.
|
||||
---
|
||||
|
||||
You keep notes and your agent helps write them. Two things are missing: a
|
||||
reliable record of how a document got to its current state, and a way to show
|
||||
one page to someone without handing over the whole notebook.
|
||||
|
||||
## What you end up with
|
||||
|
||||
- A notebook your agent reads and writes, on every machine you use.
|
||||
- Full history — every version of every file, kept forever, attributed to the
|
||||
session that wrote it.
|
||||
- Public links for the pages you choose, revocable and optionally expiring.
|
||||
|
||||
## Set it up
|
||||
|
||||
You don't need a team or a server. [Set up with your agent](/start/setup/) —
|
||||
signing up on [beardrive.ai](https://beardrive.ai) creates a free personal
|
||||
workspace, and `bdrive login` targets it by default.
|
||||
|
||||
## Tracking what changed
|
||||
|
||||
Ask, rather than diffing:
|
||||
|
||||
> What changed in my notes this week?
|
||||
|
||||
The hub's **History** answers the same question visually: a feed of every change
|
||||
with time, device, and agent session, and any past version one click away.
|
||||
Nothing is deleted — content is content-addressed and retained, so a version
|
||||
from three months ago is still there.
|
||||
|
||||
This is the difference between a notebook and a synced folder: you can always
|
||||
reconstruct how a conclusion was reached.
|
||||
|
||||
## Publishing one page
|
||||
|
||||
> Share `research/pricing-teardown.md` publicly, expiring in a week.
|
||||
|
||||
You get a URL that renders the markdown as a page. No account needed to read it,
|
||||
it always serves the file's latest content, and you can revoke it at any time.
|
||||
The rest of the notebook stays private — sharing is per file, never per folder.
|
||||
|
||||
Public pages are sandboxed and rate-limited, and carry a small "Shared with
|
||||
BearDrive" footer.
|
||||
|
||||
## What matters for this case
|
||||
|
||||
- **[Artifacts and links](/guides/agent-artifacts/)** — public share links in
|
||||
full: expiry, revocation, and how shared files render.
|
||||
- **[Carry one context across agents and devices](/use-cases/multi-device/)** —
|
||||
if the notebook should follow you to a second machine.
|
||||
@@ -1,68 +0,0 @@
|
||||
---
|
||||
title: Give every agent on the team the same skills
|
||||
description: For the person on the team who writes the good prompts — the one whose agent always seems to know the right steps. Skills, commands and subagents sync like any other file, so what you teach your agent, everyone's agent knows.
|
||||
---
|
||||
|
||||
You are the person on the team who writes the good skills. Yours knows the
|
||||
deploy checklist, the query that answers the recurring question, the three
|
||||
gotchas in the billing code. Everyone else's agent re-derives them every week,
|
||||
and the only way you have to share one is to paste a file into chat.
|
||||
|
||||
## What you end up with
|
||||
|
||||
- One folder holding the team's skills. A skill you write is on a teammate's
|
||||
disk before their agent's next turn — no export step, no registry, no MCP
|
||||
server to configure per client.
|
||||
- The same for `.claude/commands`, `.claude/agents`, `AGENTS.md` and
|
||||
`CLAUDE.md`. Everything an agent *reads* travels; agent **hook**
|
||||
configuration never does, because a hook is a shell command and syncing one
|
||||
would install it on your teammate's machine. See
|
||||
[What agents read](/guides/what-agents-read/).
|
||||
- Change history per skill: who edited it, when, from which device, and every
|
||||
previous version. A skill that got worse is one `bdrive log` away from
|
||||
showing you when.
|
||||
|
||||
## Set it up
|
||||
|
||||
Start your agent in the folder you want shared and give it the one paste from
|
||||
[Set up with your agent](/start/setup/). Ask for the skills structure and it
|
||||
seeds one — an `AGENTS.md` explaining how the library is kept plus an example
|
||||
`.claude/skills/<name>/SKILL.md` to copy:
|
||||
|
||||
> Set up BearDrive here from the `skills` template.
|
||||
|
||||
For a project's skills, sync the project folder your agent already starts
|
||||
sessions in and the `.claude/` inside it comes along. For a library that is not
|
||||
tied to one project, sync `~/.claude/skills` — **the `skills` directory,
|
||||
never `~/.claude` itself**, which also holds this machine's credentials and
|
||||
every saved session. `bdrive init` refuses that directory for exactly that
|
||||
reason and points at `skills` instead.
|
||||
|
||||
## The loop
|
||||
|
||||
> Write a skill for our release checklist and put it in `.claude/skills/`.
|
||||
|
||||
The turn ends and the skill is on the hub. Your colleague's next session picks
|
||||
it up on its own — their pull hook runs before their agent's first turn, so the
|
||||
file is simply there, on disk, the way a skill they wrote themselves would be.
|
||||
Nobody installed anything.
|
||||
|
||||
When the checklist changes, edit the skill. Everyone is on the new one by their
|
||||
next session, and the hub's History view shows what it said before.
|
||||
|
||||
## Use it with, not instead of
|
||||
|
||||
A skills *registry* answers "who is allowed to publish this, and was it
|
||||
reviewed" — governance before the fact. BearDrive answers arrival: the file is
|
||||
on the machine, current, before the agent's first turn. If your team needs
|
||||
approval gates, keep them and let BearDrive be the delivery; the two do
|
||||
different jobs.
|
||||
|
||||
## What matters for this case
|
||||
|
||||
- **[What agents read](/guides/what-agents-read/)** — exactly which agent files
|
||||
sync and which never do, and why the line falls there.
|
||||
- **[Shared agent memory](/guides/shared-agent-memory/)** — the `AGENTS.md`
|
||||
that tells every teammate's agent how the library is kept.
|
||||
- **[Project files](/reference/project-files/)** — the full table of paths
|
||||
BearDrive excludes in both directions.
|
||||
@@ -1,60 +0,0 @@
|
||||
---
|
||||
title: Share work across your team's agents
|
||||
description: For a team that doesn't live in a terminal — marketing, ops, design, founders working in Claude Cowork or Claude Code. Everything your agents produce lands in one folder the whole team's agents can read.
|
||||
---
|
||||
|
||||
Your team works with agents all day and the output goes nowhere. A brief lives
|
||||
in one person's chat history, a competitive analysis in another's, and the third
|
||||
person's agent re-does work that already exists.
|
||||
|
||||
## What you end up with
|
||||
|
||||
- One folder every agent on the team writes into and reads from.
|
||||
- Whatever your agent produces is on a teammate's machine seconds later —
|
||||
nobody attaches, uploads, or pastes anything.
|
||||
- A link you can send a person. Markdown and HTML render as pages, so anything
|
||||
an agent wrote is already readable at a URL — one link that opens only for
|
||||
members, one public link for anyone outside.
|
||||
|
||||
## Set it up
|
||||
|
||||
Start your agent in the folder you want shared and give it the one paste from
|
||||
[Set up with your agent](/start/setup/).
|
||||
|
||||
Nobody on the team needs to open a terminal: the agent installs what it needs
|
||||
and reports back. Invite teammates from the hub's sidebar (**Manage → New
|
||||
invite**); the link creates their account and adds them in one step, and they
|
||||
give their own agent the same paste.
|
||||
|
||||
If the shared work should live in one subfolder rather than everything on your
|
||||
disk, say so — "sync only `client-work/`" — and the agent scopes it.
|
||||
|
||||
## The loop
|
||||
|
||||
> Draft the Q3 campaign brief and put it in `campaigns/`.
|
||||
|
||||
The turn ends and the brief is on the hub. Your colleague, an hour later, asks
|
||||
their own agent about Q3 — and it has already read the brief, because it pulls
|
||||
the team's current files before it answers. Nobody sent anything.
|
||||
|
||||
Agents aren't the only readers. When a person needs to see it, send the hub
|
||||
link rather than the file — the hub renders markdown and HTML as pages, so
|
||||
paste it into Slack, an email or a ticket and teammates get the current version
|
||||
as a document. Anyone outside the org gets a wall, so the link is safe to
|
||||
forward internally. (Your agent appends one of these to every synced path it
|
||||
mentions, so there's usually nothing to go and copy.)
|
||||
|
||||
When it needs to leave the company:
|
||||
|
||||
> Share the brief with the agency.
|
||||
|
||||
You get a public URL that renders the document as a page — no account required,
|
||||
revocable, and it can expire on its own.
|
||||
|
||||
## What matters for this case
|
||||
|
||||
- **[Shared agent memory](/guides/shared-agent-memory/)** — write a short map of
|
||||
the folder so every teammate's agent knows where things go. Without it, five
|
||||
agents invent five folder structures.
|
||||
- **[Artifacts and links](/guides/agent-artifacts/)** — internal links for
|
||||
teammates, public links for clients, and which to use when.
|
||||
@@ -1,62 +0,0 @@
|
||||
---
|
||||
title: Keep a wiki your agents maintain
|
||||
description: For a team whose knowledge lives in documents nobody updates. The wiki gets written as a side effect of work, every change is attributed, and the project Dashboard shows which pages are load-bearing and stale.
|
||||
---
|
||||
|
||||
Every team has the same wiki problem: the pages that matter most are the ones
|
||||
nobody has touched in a year, and nobody knows which those are.
|
||||
|
||||
An agent-maintained wiki inverts it. Knowledge gets written because writing it
|
||||
is now the cheapest way to finish the task, and the hub tells you which pages
|
||||
are carrying weight.
|
||||
|
||||
## What you end up with
|
||||
|
||||
- A wiki that grows as a side effect of work, not as a chore someone schedules.
|
||||
- Every page attributed: the account, the device, and the agent session behind
|
||||
each change, with every past version retained.
|
||||
- A read map — which pages your team's agents actually consume, and which of
|
||||
those are stale.
|
||||
|
||||
## Set it up
|
||||
|
||||
Inside a repository, sync only the wiki:
|
||||
|
||||
> Set up BearDrive here, but only sync `wiki/`.
|
||||
|
||||
Git directories never sync (per-file last-writer-wins would corrupt a
|
||||
repository), and a narrow scope keeps the surface honest. A standalone wiki
|
||||
folder works the same way — see [Set up with your agent](/start/setup/).
|
||||
|
||||
## The loop
|
||||
|
||||
Work normally. When something is worth keeping, say where it goes:
|
||||
|
||||
> Write up what we learned in `wiki/research/q3-findings.md`.
|
||||
|
||||
Next week someone asks their agent about churn. It reads the findings page
|
||||
first, because it pulls before it answers — then writes what *it* learned back
|
||||
into the same folder. That is the compounding part.
|
||||
|
||||
The wiki improves every time anyone works, which is the only wiki maintenance
|
||||
model that has ever survived contact with a busy team.
|
||||
|
||||
## Reading the health of it
|
||||
|
||||
The hub's project **Dashboard** (every member) plots reads against
|
||||
staleness. The quadrant to watch is **hot and stale**: pages your agents read
|
||||
constantly that nobody has updated. That is your maintenance queue, and it is
|
||||
usually three pages, not thirty.
|
||||
|
||||
Folder listings show read counts to every member, so the signal is not locked
|
||||
behind an admin screen.
|
||||
|
||||
## What matters for this case
|
||||
|
||||
- **[What agents read](/guides/what-agents-read/)** — read heat, the Dashboard, and
|
||||
what the hub deliberately does not record.
|
||||
- **[Shared agent memory](/guides/shared-agent-memory/)** — an `AGENTS.md` map
|
||||
at the wiki root so agents file things consistently instead of inventing a
|
||||
structure per session.
|
||||
- **[Scoping the folder](/guides/scoping/)** — subfolder syncing and
|
||||
`.bdriveignore`.
|
||||
Reference in New Issue
Block a user