From 16ababe37d660182771767691b28d2b09b568304 Mon Sep 17 00:00:00 2001 From: Snow Lee Date: Sun, 19 Jul 2026 21:40:00 -0700 Subject: [PATCH] =?UTF-8?q?docs:=20use=20cases=20=E2=80=94=20five=20job-sh?= =?UTF-8?q?aped=20pages=20that=20route=20into=20the=20guides?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit "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) --- web/docs/astro.config.mjs | 14 +++ web/docs/src/content/docs/index.md | 3 + .../content/docs/use-cases/company-brain.md | 109 ++++++++++++++++++ .../content/docs/use-cases/multi-device.md | 58 ++++++++++ .../content/docs/use-cases/personal-wiki.md | 53 +++++++++ .../content/docs/use-cases/team-artifacts.md | 52 +++++++++ .../src/content/docs/use-cases/team-wiki.md | 62 ++++++++++ 7 files changed, 351 insertions(+) create mode 100644 web/docs/src/content/docs/use-cases/company-brain.md create mode 100644 web/docs/src/content/docs/use-cases/multi-device.md create mode 100644 web/docs/src/content/docs/use-cases/personal-wiki.md create mode 100644 web/docs/src/content/docs/use-cases/team-artifacts.md create mode 100644 web/docs/src/content/docs/use-cases/team-wiki.md diff --git a/web/docs/astro.config.mjs b/web/docs/astro.config.mjs index fd56788..42b548b 100644 --- a/web/docs/astro.config.mjs +++ b/web/docs/astro.config.mjs @@ -63,6 +63,20 @@ export default defineConfig({ { label: "Your first hour", slug: "start/first-hour" }, ], }, + { + // 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: "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" }, + ], + }, { // Guides are about working with agents — that's what the product is // for. Command-by-command CLI detail belongs in Reference. diff --git a/web/docs/src/content/docs/index.md b/web/docs/src/content/docs/index.md index 54dbc52..47eb50c 100644 --- a/web/docs/src/content/docs/index.md +++ b/web/docs/src/content/docs/index.md @@ -40,6 +40,9 @@ 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: + 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. - **[Manual setup](/manual/install/)** — the same result command by command, if you'd rather see the moving parts. diff --git a/web/docs/src/content/docs/use-cases/company-brain.md b/web/docs/src/content/docs/use-cases/company-brain.md new file mode 100644 index 0000000..9c37c76 --- /dev/null +++ b/web/docs/src/content/docs/use-cases/company-brain.md @@ -0,0 +1,109 @@ +--- +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, sync just that subfolder: +`bdrive init --shared brain/`. 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. diff --git a/web/docs/src/content/docs/use-cases/multi-device.md b/web/docs/src/content/docs/use-cases/multi-device.md new file mode 100644 index 0000000..5481b8e --- /dev/null +++ b/web/docs/src/content/docs/use-cases/multi-device.md @@ -0,0 +1,58 @@ +--- +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 `p-79d0a07c`. + +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. + +Install the skill and hooks **once per machine**, and the hooks once per project +— that is what makes each agent pull before it answers. See +[skills and hooks in detail](/manual/skills-and-hooks/). + +## More than one agent per machine + +The skill is a cross-agent format and the hooks are written per platform, 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 + +- **[Skills and hooks in detail](/manual/skills-and-hooks/)** — what to run on + each new machine, 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. diff --git a/web/docs/src/content/docs/use-cases/personal-wiki.md b/web/docs/src/content/docs/use-cases/personal-wiki.md new file mode 100644 index 0000000..70b6e39 --- /dev/null +++ b/web/docs/src/content/docs/use-cases/personal-wiki.md @@ -0,0 +1,53 @@ +--- +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. diff --git a/web/docs/src/content/docs/use-cases/team-artifacts.md b/web/docs/src/content/docs/use-cases/team-artifacts.md new file mode 100644 index 0000000..39e1470 --- /dev/null +++ b/web/docs/src/content/docs/use-cases/team-artifacts.md @@ -0,0 +1,52 @@ +--- +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 for anyone outside the team, when you want one. + +## Set it up + +Install the plugin once — Cowork and Claude Code share plugins, so this covers +both — then run `/beardrive:install` in the folder you want shared. +[Set up with your agent](/start/setup/) has the two commands. + +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 +run the same `/beardrive:install` on their own machine. + +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. + +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. diff --git a/web/docs/src/content/docs/use-cases/team-wiki.md b/web/docs/src/content/docs/use-cases/team-wiki.md new file mode 100644 index 0000000..a5852ab --- /dev/null +++ b/web/docs/src/content/docs/use-cases/team-wiki.md @@ -0,0 +1,62 @@ +--- +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 Insights 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 **Insights** (hub admins and org owners) 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, Insights, 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`.