diff --git a/CLAUDE.md b/CLAUDE.md index c5bbee6..c0ca25c 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -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 diff --git a/web/docs/README.md b/web/docs/README.md index 370f71c..0e5193d 100644 --- a/web/docs/README.md +++ b/web/docs/README.md @@ -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`, diff --git a/web/docs/astro.config.mjs b/web/docs/astro.config.mjs index b8b675b..6d4a2d8 100644 --- a/web/docs/astro.config.mjs +++ b/web/docs/astro.config.mjs @@ -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" }, + ], + }, ], }), ], diff --git a/web/docs/src/components/SiteTitle.astro b/web/docs/src/components/SiteTitle.astro new file mode 100644 index 0000000..d5a4d59 --- /dev/null +++ b/web/docs/src/components/SiteTitle.astro @@ -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; +--- + + + { + config.logo && logos.dark && ( + {config.logo.alt} + ) + } + + {siteTitle} + + + + diff --git a/web/docs/src/content/docs/index.md b/web/docs/src/content/docs/index.md index bd8ab70..347e2b5 100644 --- a/web/docs/src/content/docs/index.md +++ b/web/docs/src/content/docs/index.md @@ -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. diff --git a/web/docs/src/content/docs/start/setup.md b/web/docs/src/content/docs/start/setup.md index eb7e94c..d24157a 100644 --- a/web/docs/src/content/docs/start/setup.md +++ b/web/docs/src/content/docs/start/setup.md @@ -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 diff --git a/web/docs/src/content/docs/use-cases/business-context.md b/web/docs/src/content/docs/use-cases/business-context.md deleted file mode 100644 index 2aa4706..0000000 --- a/web/docs/src/content/docs/use-cases/business-context.md +++ /dev/null @@ -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. diff --git a/web/docs/src/content/docs/use-cases/company-brain.md b/web/docs/src/content/docs/use-cases/company-brain.md deleted file mode 100644 index 88f93b8..0000000 --- a/web/docs/src/content/docs/use-cases/company-brain.md +++ /dev/null @@ -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. diff --git a/web/docs/src/content/docs/use-cases/multi-device.md b/web/docs/src/content/docs/use-cases/multi-device.md deleted file mode 100644 index b8d2f8a..0000000 --- a/web/docs/src/content/docs/use-cases/multi-device.md +++ /dev/null @@ -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. diff --git a/web/docs/src/content/docs/use-cases/personal-wiki.md b/web/docs/src/content/docs/use-cases/personal-wiki.md deleted file mode 100644 index 70b6e39..0000000 --- a/web/docs/src/content/docs/use-cases/personal-wiki.md +++ /dev/null @@ -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. diff --git a/web/docs/src/content/docs/use-cases/shared-skills.md b/web/docs/src/content/docs/use-cases/shared-skills.md deleted file mode 100644 index 9fd1b6d..0000000 --- a/web/docs/src/content/docs/use-cases/shared-skills.md +++ /dev/null @@ -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//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. diff --git a/web/docs/src/content/docs/use-cases/team-artifacts.md b/web/docs/src/content/docs/use-cases/team-artifacts.md deleted file mode 100644 index 4c9b194..0000000 --- a/web/docs/src/content/docs/use-cases/team-artifacts.md +++ /dev/null @@ -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. diff --git a/web/docs/src/content/docs/use-cases/team-wiki.md b/web/docs/src/content/docs/use-cases/team-wiki.md deleted file mode 100644 index 03f3c44..0000000 --- a/web/docs/src/content/docs/use-cases/team-wiki.md +++ /dev/null @@ -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`.