From 8f239dfae471fe355dea7aba777466492300e294 Mon Sep 17 00:00:00 2001 From: Snow Lee Date: Sun, 19 Jul 2026 20:52:20 -0700 Subject: [PATCH] docs: reorganize around the agent path, CLI becomes optional MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The sidebar and the homepage disagreed. index.md's "Where to start" already led with connecting an agent, but the left rail read Install (brew) -> Quickstart (bdrive login, bdrive init) -> ... -> Connect an agent, three groups down. Anyone following the rail met the CLI first and the skill last — the opposite of how the product is meant to be adopted. The agent page was also filed under guides/, which this repo defines as agent-workflow docs rather than setup. Sidebar order is now the recommended path, and that path is agent-first: Start here what it is -> set up with your agent -> your first hour Working with agents shared memory, artifacts, read heat, scoping Manual setup (opt) install the CLI, set up by hand, skills and hooks Self-hosting / Reference / Concepts unchanged - start/setup (was guides/connect-an-agent): rewritten as the front door. Claude Code's plugin, then the one-paste for Codex/Gemini/Hermes, then what the agent just installed and how to check it. - start/first-hour (new): the page that was missing — ask for a doc, get a link back, share it, a teammate's agent picks it up. What success looks like without a command you have to type. - manual/skills-and-hooks (new): the mechanics lifted out of the old onboarding page — per-platform paths, hook events, idempotency, project-level vs per-user — so the Start page can stay conversational. - manual/install and manual/setup-by-hand (were start/*): both now open by saying you probably don't need them, and link back to the agent path. - index.md leads with "You don't install it — you ask your agent to"; the CLI and hub sentence moves below it. No `brew install` appears anywhere in Start here. Reference -> CLI stays exactly where it was: the people most likely to self-host are CLI-first, and burying it would read as condescending. Three public URLs moved, so astro.config.mjs declares redirects. Static builds emit meta-refresh only, so README carries copy-paste 301 rules for the host — Firebase Hosting and a Cloud Storage + load balancer URL map. Verified: 18 pages build, zero broken internal links across the built output, all three redirects resolve. CLAUDE.md and the docs README record the rule so this doesn't quietly revert. Co-Authored-By: Claude Opus 4.8 (1M context) --- CLAUDE.md | 2 +- web/docs/README.md | 62 ++++++++++ web/docs/astro.config.mjs | 27 ++++- .../content/docs/guides/agent-artifacts.md | 2 +- .../content/docs/guides/connect-an-agent.md | 111 ------------------ .../content/docs/guides/what-agents-read.md | 2 +- web/docs/src/content/docs/index.md | 22 ++-- .../content/docs/{start => manual}/install.md | 13 +- .../quickstart.md => manual/setup-by-hand.md} | 16 ++- .../content/docs/manual/skills-and-hooks.md | 87 ++++++++++++++ .../content/docs/self-hosting/run-a-hub.md | 2 +- web/docs/src/content/docs/start/first-hour.md | 74 ++++++++++++ web/docs/src/content/docs/start/setup.md | 104 ++++++++++++++++ 13 files changed, 391 insertions(+), 133 deletions(-) delete mode 100644 web/docs/src/content/docs/guides/connect-an-agent.md rename web/docs/src/content/docs/{start => manual}/install.md (64%) rename web/docs/src/content/docs/{start/quickstart.md => manual/setup-by-hand.md} (80%) create mode 100644 web/docs/src/content/docs/manual/skills-and-hooks.md create mode 100644 web/docs/src/content/docs/start/first-hour.md create mode 100644 web/docs/src/content/docs/start/setup.md diff --git a/CLAUDE.md b/CLAUDE.md index a72ff46..fc54d7a 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -71,7 +71,7 @@ The real coverage is the integration tests in `internal/syncer/syncer_test.go`: ## 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). **Guides are agent-workflow docs, not CLI tutorials** (`Working with agents`: connect an agent, 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, skills and 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. 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. ## Docs to keep in sync diff --git a/web/docs/README.md b/web/docs/README.md index a7ee65d..1e24ff3 100644 --- a/web/docs/README.md +++ b/web/docs/README.md @@ -54,11 +54,73 @@ Convention puts `llms.txt` at the **root** domain, not a docs subdomain — so That redirect lives in the cloud landing page and is the one cross-repo coordination point this split introduces. +## Structure + +The sidebar order in `astro.config.mjs` **is** the recommended path, and the +recommended path is agent-first: + +- **Start here** — what it is, set up with your agent, first hour. No `brew + install` appears in this group. +- **Working with agents** — the workflows the product exists for. +- **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. +- **Self-hosting**, **Reference**, **Concepts** — unchanged in intent. + +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. + ## Deploying Static output in `dist/`. Any static host works; build command `npm run build`, output directory `dist`, project root `web/docs`. +### Redirects + +The docs were reorganized around the agent-first path, so three old URLs moved: + +| Old | New | +|---|---| +| `/start/install` | `/manual/install/` | +| `/start/quickstart` | `/manual/setup-by-hand/` | +| `/guides/connect-an-agent` | `/start/setup/` | + +`astro.config.mjs` declares these, which in a static build emits **meta-refresh +pages** — fine for humans, weak for search engines. Real 301s belong in the host. + +**Firebase Hosting** (simplest static option on GCP — CDN, TLS, and custom +domains included): + +```json +{ + "hosting": { + "public": "dist", + "ignore": ["firebase.json", "**/.*"], + "redirects": [ + { "source": "/start/install", "destination": "/manual/install/", "type": 301 }, + { "source": "/start/quickstart", "destination": "/manual/setup-by-hand/", "type": 301 }, + { "source": "/guides/connect-an-agent", "destination": "/start/setup/", "type": 301 } + ] + } +} +``` + +**Cloud Storage behind an external Application Load Balancer:** put the rules in +the URL map, which redirects before the bucket is ever reached. + +```sh +gcloud compute url-maps edit docs-url-map # pathMatchers[].pathRules[]: +# - paths: ["/start/install"] +# urlRedirect: +# pathRedirect: "/manual/install/" +# redirectResponseCode: MOVED_PERMANENTLY_DEFAULT +# stripQuery: false +``` + +Whichever host wins, keep the Astro `redirects` block as well: it is the +portable fallback, and it keeps local `npm run preview` honest. + Note that the build reads a file **outside** `web/docs` (the token source), so the host must check out the whole repository rather than just this subdirectory. diff --git a/web/docs/astro.config.mjs b/web/docs/astro.config.mjs index cc674ba..fd56788 100644 --- a/web/docs/astro.config.mjs +++ b/web/docs/astro.config.mjs @@ -16,6 +16,14 @@ import llmsTxt from "starlight-llms-txt"; // contributor can actually open a PR against. export default defineConfig({ site: "https://docs.beardrive.ai", + // The docs were reorganized around the agent-first path; these URLs were + // public and indexed. Astro emits meta-refresh pages for static output — + // real 301s belong in the host config (see README, "Deploying"). + redirects: { + "/start/install": "/manual/install/", + "/start/quickstart": "/manual/setup-by-hand/", + "/guides/connect-an-agent": "/start/setup/", + }, integrations: [ starlight({ title: "BearDrive", @@ -44,11 +52,15 @@ export default defineConfig({ plugins: [llmsTxt()], sidebar: [ { + // The reading order IS the recommended path, and the recommended path + // is agent-first: nobody should meet `brew install` before they meet + // /beardrive:install. Everything CLI lives under "Manual setup", + // one click away and never on the critical path. label: "Start here", items: [ { label: "What is BearDrive?", slug: "" }, - { label: "Install", slug: "start/install" }, - { label: "Quickstart", slug: "start/quickstart" }, + { label: "Set up with your agent", slug: "start/setup" }, + { label: "Your first hour", slug: "start/first-hour" }, ], }, { @@ -56,13 +68,22 @@ export default defineConfig({ // for. Command-by-command CLI detail belongs in Reference. label: "Working with agents", items: [ - { label: "Connect an agent", slug: "guides/connect-an-agent" }, { label: "Shared agent memory", slug: "guides/shared-agent-memory" }, { label: "Artifacts and links", slug: "guides/agent-artifacts" }, { label: "What agents read", slug: "guides/what-agents-read" }, { label: "Scoping the folder", slug: "guides/scoping" }, ], }, + { + // For people who would rather type it, and for machines with no agent + // on them. Same destination, more steps. + label: "Manual setup (optional)", + items: [ + { label: "Install the CLI", slug: "manual/install" }, + { label: "Set up by hand", slug: "manual/setup-by-hand" }, + { label: "Skills and hooks in detail", slug: "manual/skills-and-hooks" }, + ], + }, { label: "Self-hosting", items: [ diff --git a/web/docs/src/content/docs/guides/agent-artifacts.md b/web/docs/src/content/docs/guides/agent-artifacts.md index 82d80dd..564c275 100644 --- a/web/docs/src/content/docs/guides/agent-artifacts.md +++ b/web/docs/src/content/docs/guides/agent-artifacts.md @@ -32,7 +32,7 @@ With no argument, `bdrive url` gives the project home. The sync hook installed by `bdrive hooks install` injects the project's gated-link formula into the agent's context, so a connected agent appends `path` [🔗](link) to every synced path it mentions — without being asked. See -[Connect an agent](/guides/connect-an-agent/). +[Set up with your agent](/start/setup/). ::: ## Public links, for everyone else diff --git a/web/docs/src/content/docs/guides/connect-an-agent.md b/web/docs/src/content/docs/guides/connect-an-agent.md deleted file mode 100644 index 9e256ab..0000000 --- a/web/docs/src/content/docs/guides/connect-an-agent.md +++ /dev/null @@ -1,111 +0,0 @@ ---- -title: Connect an agent -description: Wire Claude Code, Codex, Gemini CLI, or Hermes into a BearDrive folder so it reads fresh team files every turn and pushes its own artifacts automatically. ---- - -An agent connected to BearDrive pulls the team's latest files at the start of -every turn and pushes whatever it writes the moment it writes it. Your teammate's -agent sees it seconds later. - -## The two pieces - -Whatever agent you use, setup is the same two things. - -**The skill** teaches the agent the `bdrive` CLI, so "share this file" or "what -changed?" just works without you explaining anything. - -```sh -bdrive skill install -``` - -It writes `SKILL.md` — a cross-agent format — into every detected platform's -user-level skills directory: `~/.claude/skills/beardrive/`, `~/.codex/…`, -`~/.gemini/…`, `~/.hermes/…`. - -**The hooks** are what make syncing automatic: a blocking pull when you send a -message, so the agent always reads fresh files, and an async push when the turn -ends. - -```sh -bdrive hooks install -``` - -Both commands are idempotent and both detect the platform (override with -`--agent`). The hook no-ops instantly in folders without a `.bdrive/` project, -so registering it globally is safe. - -:::caution[Don't skip the hooks] -This is the step people skip when they copy commands by hand, and it's the one -that makes the whole thing automatic. Without it you're back to running -`bdrive sync` yourself and the agent will read stale files. -::: - -## Claude Code - -Install the plugin: - -``` -/plugin marketplace add runbear-io/beardrive -/plugin install beardrive@beardrive -``` - -Then run **`/beardrive:install`**. It sets the project up conversationally: -installs the CLI, signs in, creates or connects a project (whole folder or a -subfolder like `wiki/`), offers to write the -[agent orientation files](/guides/shared-agent-memory/), and registers -project-level hooks in `.claude/settings.json`. - -Those project-level hooks are the part that matters for teams: they're committed -with the repository, so **teammates sync whether or not they installed the -plugin**. - -Also available: - -- **`/beardrive:init [folder]`** — just start syncing. Takes `--name`, - `--project`, `--shared`. -- **`/beardrive:status`** — diagnose sync problems. - -## Codex, Gemini CLI, Hermes - -These agents ship no BearDrive knowledge, so setup is one paste. Start the agent -in the folder you want the files and give it: - -``` -Set up BearDrive in this folder. -1. If `bdrive` is missing, install it: brew install runbear-io/tap/beardrive - (no Homebrew? grab the release binary for this OS/arch from - https://github.com/runbear-io/beardrive/releases) -2. bdrive skill install # so you know the CLI next time -3. bdrive login --device https://your-hub # show me the code and the URL -4. bdrive init --project -5. bdrive hooks install # don't skip this - it's what syncs every turn -Then tell me what got set up. -``` - -You copy one thing; the agent handles every deviation — already installed, no -Homebrew, sign-in, wrong folder. - -Step 2 is the durable part. Once the skill is installed, the agent knows the CLI -from then on without being told. - -:::tip -A project's home page in the web UI shows this same paste with your hub URL and -project id already filled in, plus a plain-terminal version. Send teammates -there rather than retyping it. -::: - -## Check what's wired up - -```sh -bdrive skill # what's installed on this machine -bdrive hooks # what's registered for this project -bdrive status # projects, daemon state, pending changes -``` - -Re-run `bdrive hooks install` once per project and `bdrive skill install` once -per machine after a CLI upgrade. - -## Next - -[Shared agent memory](/guides/shared-agent-memory/) — a freshly connected folder -is hundreds of opaque files to an agent. This is how you fix that. diff --git a/web/docs/src/content/docs/guides/what-agents-read.md b/web/docs/src/content/docs/guides/what-agents-read.md index 3d06e7e..6cffe50 100644 --- a/web/docs/src/content/docs/guides/what-agents-read.md +++ b/web/docs/src/content/docs/guides/what-agents-read.md @@ -20,7 +20,7 @@ Hubs track it. Sync replication never counts as a read, and neither does viewing a blob in history. Only genuine consumption. -Agent reads require the hooks from [Connect an agent](/guides/connect-an-agent/). +Agent reads require the hooks from [Set up with your agent](/start/setup/). Without them you'll see human traffic only. ## In the file browser diff --git a/web/docs/src/content/docs/index.md b/web/docs/src/content/docs/index.md index 90e79e7..54dbc52 100644 --- a/web/docs/src/content/docs/index.md +++ b/web/docs/src/content/docs/index.md @@ -7,8 +7,15 @@ BearDrive mounts any folder as a synced volume. Its contents stay synchronized across all your devices and teammates through a BearDrive **hub**, every change is tracked (who, when, on which device), and everything keeps working offline. -The CLI is `bdrive`. A hub is a `bdrive web` server you (or we) run on an object -store — clients sync through it over HTTPS and never touch the storage directly. +**You don't install it — you ask your agent to.** One command in Claude Code, or +one paste in Codex, Gemini CLI, or Hermes, and the folder is connected: your +agent reads the team's current files before it answers and pushes whatever it +writes when the turn ends. + +Underneath there is a CLI called `bdrive` and a **hub** — a `bdrive web` server +you (or we) run on an object store, which clients sync through over HTTPS and +never touch the storage directly. You can drive all of it by hand, and most +people never do. ## What it's for @@ -29,12 +36,13 @@ page. ## Where to start -- **[Connect an agent](/guides/connect-an-agent/)** — the point of the product. - Claude Code, Codex, Gemini CLI, or Hermes, reading and writing the shared - folder every turn. -- **[Quickstart](/start/quickstart/)** — sign in and start syncing a folder, if - you'd rather see the mechanics first. +- **[Set up with your agent](/start/setup/)** — the way in. One command in Claude + 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. - **[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. ## What you get diff --git a/web/docs/src/content/docs/start/install.md b/web/docs/src/content/docs/manual/install.md similarity index 64% rename from web/docs/src/content/docs/start/install.md rename to web/docs/src/content/docs/manual/install.md index fc55bd8..f4632d2 100644 --- a/web/docs/src/content/docs/start/install.md +++ b/web/docs/src/content/docs/manual/install.md @@ -1,8 +1,14 @@ --- -title: Install -description: Install the bdrive CLI with Homebrew, go install, or a release binary. +title: Install the CLI +description: Install the bdrive binary with Homebrew, go install, or a release tarball — for setting a folder up by hand, or for running a hub. --- +Most people never run this. [Setting up through your agent](/start/setup/) +installs the binary as its first step. + +Install it yourself when you would rather drive the setup by hand, when you are +[running a hub](/self-hosting/run-a-hub/), or when a machine has no agent on it. + BearDrive ships one binary, `bdrive`. It is the CLI, the sync daemon, and the web server. macOS and Linux. @@ -49,4 +55,5 @@ agent skill. ## Next -[Quickstart](/start/quickstart/) — sign in and start syncing a folder. +[Set up by hand](/manual/setup-by-hand/) — sign in and start syncing a folder, +command by command. diff --git a/web/docs/src/content/docs/start/quickstart.md b/web/docs/src/content/docs/manual/setup-by-hand.md similarity index 80% rename from web/docs/src/content/docs/start/quickstart.md rename to web/docs/src/content/docs/manual/setup-by-hand.md index b6f4a1b..92c8af1 100644 --- a/web/docs/src/content/docs/start/quickstart.md +++ b/web/docs/src/content/docs/manual/setup-by-hand.md @@ -1,9 +1,15 @@ --- -title: Quickstart -description: Sign a device in, start syncing a folder, and connect a second machine — the whole loop in a few minutes. +title: Set up by hand +description: The same setup an agent performs, run yourself — sign a device in, start syncing a folder, and connect a second machine. --- -Three steps: sign the device in, start syncing a folder, work normally. +This is [what your agent does for you](/start/setup/), one command at a time. +Useful on a machine with no agent, when scripting a fleet, or when you simply +want to see the moving parts. + +Three steps: sign the device in, start syncing a folder, work normally. Then +[register the hooks](/manual/skills-and-hooks/) — that last step is what keeps +an agent's files fresh, and it is the one hand-setups forget. ## 1. Sign this device in @@ -87,8 +93,8 @@ changes. ## Next -- [Connect an agent](/guides/connect-an-agent/) — wire Claude Code, Codex, - Gemini CLI, or Hermes into this folder. This is what BearDrive is for. +- [Skills and hooks in detail](/manual/skills-and-hooks/) — the two commands + that make an agent read fresh files every turn. Don't stop before this one. - [Shared agent memory](/guides/shared-agent-memory/) — orient agents in the folder so they know where to read and write. - [Artifacts and links](/guides/agent-artifacts/) — internal links for diff --git a/web/docs/src/content/docs/manual/skills-and-hooks.md b/web/docs/src/content/docs/manual/skills-and-hooks.md new file mode 100644 index 0000000..84b4e11 --- /dev/null +++ b/web/docs/src/content/docs/manual/skills-and-hooks.md @@ -0,0 +1,87 @@ +--- +title: Skills and hooks in detail +description: What bdrive skill install and bdrive hooks install actually write — per-platform paths, hook events, idempotency, and when to re-run them. +--- + +Setting up through your agent runs these two commands for you. This is what +they do, for when you want to run them yourself, review what changed, or debug a +folder that isn't syncing. + +## The skill + +```sh +bdrive skill install # every detected platform +bdrive skill install --agent codex,hermes +bdrive skill # status table +``` + +It writes one `SKILL.md` — the cross-agent format — into each platform's +user-level skills directory: + +| Platform | Path | +|---|---| +| Claude Code | `~/.claude/skills/beardrive/SKILL.md` | +| Codex | `~/.codex/skills/beardrive/SKILL.md` | +| Gemini CLI | `~/.gemini/skills/beardrive/SKILL.md` | +| Hermes | `~/.hermes/skills/beardrive/SKILL.md` | + +Installs are user-level on purpose: the skill is about the CLI, not about one +folder, and a synced project folder should never carry it. The file is the +binary's own copy, so re-running after a CLI upgrade refreshes a stale one. + +The Claude Code plugin ships the same skill, so `/plugin install +beardrive@beardrive` covers Claude without this command. + +## The hooks + +```sh +bdrive hooks install # every detected platform, this project +bdrive hooks install --agent claude,codex,gemini,hermes +bdrive hooks # status table +``` + +Each platform gets the same three hooks written into its own config format: + +| Platform | Config it writes | Pull / push / read events | +|---|---|---| +| Claude Code | `/.claude/settings.json` | `UserPromptSubmit` / `PostToolUse` (Write\|Edit) / `PostToolUse` (Read\|Grep\|Bash) | +| Codex | `/.codex/hooks.json` | `UserPromptSubmit` / `PostToolUse` (apply_patch) / `PostToolUse` (read_file\|shell) | +| Gemini CLI | `/.gemini/settings.json` | `BeforeAgent` / `AfterTool` (write_file\|replace) / `AfterTool` (read tools) | +| Hermes | `~/.hermes/config.yaml` (per user) | `pre_llm_call` / `post_tool_call` (write_file\|patch) / `post_tool_call` (read_file\|grep\|bash) | + +Three hooks, three jobs: + +- **Pull**, before the agent answers, so it never reads a stale file. This one + blocks — it is the only place BearDrive makes you wait, and it is why the + whole thing works. +- **Push**, after an edit, so teammates see the change within seconds rather + than whenever a daemon tick lands. +- **Read tracking**, on the agent's read-shaped tools, queued locally and sent + on the next sync. This is what fills [Insights](/guides/what-agents-read/). + Listing tools are deliberately excluded: seeing a filename is not reading it. + +Every platform pipes hook JSON with a session id, so one hook command serves all +four, and changes are stamped with ` session ` — visible in +`bdrive log` and the hub's history. + +Codex asks once to trust the project's `.codex` layer. Answer yes, or run +`/hooks` inside Codex. + +## Both are safe to re-run + +Merging is idempotent and preserves hooks you already have. Each hook carries +its own marker, so a config written before a hook existed gains just the missing +one, and a registered hook's matcher is upgraded in place when coverage grows. + +Re-run after a CLI upgrade: `bdrive hooks install` once per project, `bdrive +skill install` once per machine. + +## Where they live matters + +Claude Code, Codex, and Gemini CLI hooks are **project-level** — they ride the +repository, so a teammate who clones it syncs whether or not they installed +anything. Hermes hooks are **per-user** (`~/.hermes/config.yaml`), outside the +repo, so each person registers their own. + +The hook is a fast no-op in any folder without a `.bdrive/` directory, which is +what makes registering it globally safe. diff --git a/web/docs/src/content/docs/self-hosting/run-a-hub.md b/web/docs/src/content/docs/self-hosting/run-a-hub.md index 2f211f9..e51e8b8 100644 --- a/web/docs/src/content/docs/self-hosting/run-a-hub.md +++ b/web/docs/src/content/docs/self-hosting/run-a-hub.md @@ -81,7 +81,7 @@ container platform works the same way. link both creates their account and adds them to your org. 4. Connect agents: the project's home page shows one-paste setup for Claude Code, Hermes, and Codex, with the hub URL and project id already filled in. - See [Connect an agent](/guides/connect-an-agent/). + See [Set up with your agent](/start/setup/). ## How the hub is organized diff --git a/web/docs/src/content/docs/start/first-hour.md b/web/docs/src/content/docs/start/first-hour.md new file mode 100644 index 0000000..bc71661 --- /dev/null +++ b/web/docs/src/content/docs/start/first-hour.md @@ -0,0 +1,74 @@ +--- +title: Your first hour +description: What a connected folder feels like — ask an agent to write something, get a link back, share it outside the team, and watch a teammate's agent pick it up. +--- + +Setup is done and nothing looks different: the folder is still a folder, the +files are still files. The change shows up in what you stop doing. + +## Ask for something to be written + +Work normally. When the agent produces something worth keeping — a plan, a +findings doc, a runbook — ask it to put that in the shared folder: + +> Write up what we decided in `wiki/decisions/pricing.md`. + +The turn ends, the hook pushes, and the file is on the hub seconds later. +Nobody uploaded anything. + +## The link you get back + +A connected agent hands you a link to what it just wrote: + +``` +Saved to wiki/decisions/pricing.md 🔗 +``` + +That is an **internal link** — it opens the file in the hub for anyone signed in +and in the project, and 404s for everyone else. Paste it in Slack without +thinking about it. You can also mint one yourself with `bdrive url `. + +For people outside the team, ask for a public one: + +> Share that pricing doc with the customer. + +The agent runs `bdrive share`, and you get a URL that renders the markdown as a +page — no account needed, revocable, and optionally self-destructing +(`--expires 24h`). [Artifacts and links](/guides/agent-artifacts/) covers both +kinds in depth. + +## What a teammate sees + +They set their own machine up the same way, in a folder of their choosing. From +then on, their agent starts every turn by pulling — so the pricing doc is simply +*there* the next time they ask about pricing. No one sends anyone a file. + +That's the whole thesis: your agent knows what their agent knows. + +## Now look at the hub + +Open the project in a browser. Three things are worth a minute: + +- **History** — every change, with the account, the time, the device, and the + agent session that made it. Any past version is one click away, and nothing is + ever deleted. +- **The file browser** — folders show read counts, so you can see which + documents your team's agents actually consume. +- **Insights** (hub admins and org owners) — reads against staleness. The + hot-but-stale quadrant is the knowledge everyone relies on and nobody + maintains. See [What agents read](/guides/what-agents-read/). + +## From here on + +Every turn, in every connected folder: pull before the agent answers, push after +it edits, stamped with the session that did it. You don't run a command and you +don't think about sync. + +Two things repay the ten minutes they cost: + +- **[Shared agent memory](/guides/shared-agent-memory/)** — a fresh folder is + hundreds of opaque files to an agent. A short `AGENTS.md` map fixes that, and + it syncs with everything else. +- **[Scoping the folder](/guides/scoping/)** — decide what agents can see. Sync + one subfolder rather than a whole repository, and opt files out with + `.bdriveignore`. diff --git a/web/docs/src/content/docs/start/setup.md b/web/docs/src/content/docs/start/setup.md new file mode 100644 index 0000000..fc85503 --- /dev/null +++ b/web/docs/src/content/docs/start/setup.md @@ -0,0 +1,104 @@ +--- +title: Set up with your agent +description: You don't install BearDrive — you ask your agent to. One command in Claude Code, or one paste in Codex, Gemini CLI, or Hermes, and the folder syncs from then on. +--- + +You don't set BearDrive up. Your agent does. + +Give it one instruction and it installs the CLI, signs this machine in, connects +the folder to a project, and registers the hooks that keep everything in sync — +then tells you what it did. You never open a config file. + +## Claude Code and Cowork + +Install the plugin once, in any session: + +``` +/plugin marketplace add runbear-io/beardrive +/plugin install beardrive@beardrive +``` + +Then, in the folder you want synced: + +``` +/beardrive:install +``` + +It walks you through it: creates or connects a project, asks whether to sync the +whole folder or a subfolder like `wiki/`, offers to write the +[agent orientation files](/guides/shared-agent-memory/), and registers the sync +hooks. It asks before anything it changes. + +Cowork shares Claude Code's plugins, so installing it once covers both. + +Two more commands come with the plugin: **`/beardrive:init`** to start syncing +without the full setup conversation, and **`/beardrive:status`** to diagnose a +sync problem. + +:::tip[Project-level hooks reach the whole team] +`/beardrive:install` writes hooks into `.claude/settings.json`, which is +committed with the repository — so **teammates sync whether or not they +installed the plugin**. +::: + +## Codex, Gemini CLI, and Hermes + +These agents ship no BearDrive knowledge yet, so the instructions travel in the +message. Start the agent in the folder you want synced and paste: + +``` +Set up BearDrive in this folder. +1. If `bdrive` is missing, install it: brew install runbear-io/tap/beardrive + (no Homebrew? grab the release binary for this OS/arch from + https://github.com/runbear-io/beardrive/releases) +2. bdrive skill install # so you know the CLI next time +3. bdrive login --device https://your-hub # show me the code and the URL +4. bdrive init --project +5. bdrive hooks install # don't skip this - it's what syncs every turn +Then tell me what got set up. +``` + +You copy one thing; the agent handles every deviation — already installed, no +Homebrew, browser sign-in, wrong folder. + +Step 2 is the durable part. Once the skill is installed the agent knows the CLI +from then on, so "share this file" or "what changed?" work without you +explaining anything again. + +:::tip[Don't retype this for teammates] +A project's home page in the hub shows this same paste with your hub URL and +project id already filled in. Send people there. +::: + +## What your agent just set up + +Two things, worth knowing by name: + +- **The skill** — a `SKILL.md` in the agent's own skills directory, teaching it + the `bdrive` CLI. It is a cross-agent format, so one file works in Claude Code, + Codex, Gemini CLI, and Hermes. +- **The hooks** — a blocking pull when you send a message, so the agent always + reads the team's current files, and an async push when the turn ends, so what + it writes reaches everyone else within seconds. + +The hooks are what make syncing automatic, and they are the step people skip +when they set up by hand. [Skills and hooks in detail](/manual/skills-and-hooks/) +covers what gets written where. + +## Check it worked + +Ask the agent — "is BearDrive set up in this folder?" — or look yourself: + +```sh +bdrive status # projects, daemon state, pending changes +bdrive skill # which agents know the CLI on this machine +bdrive hooks # which agents sync this project automatically +``` + +## Next + +[Your first hour](/start/first-hour/) — what the loop feels like once an agent is +connected. + +Would rather drive it yourself? [Manual setup](/manual/install/) reaches the same +place, command by command.