From 7eabb3baf4c14d5305f44b865fb1b5d209d3234b Mon Sep 17 00:00:00 2001 From: "Snow Lee (Sungwon)" Date: Wed, 12 Aug 2026 14:49:58 -0700 Subject: [PATCH] docs: the starting paste is one sentence, not a template to fill in (#158) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The setup page opened with a prompt carrying three placeholders — project id, hub URL, project name — none of which a first-time reader has. It was the teammate-joining paste doing double duty as the getting-started paste, and it asked someone with nothing to substitute values into a two-line string before they could begin. The start is now: Follow beardrive.ai/setup to set up BearDrive. Ask me which folder to sync. Same destination — beardrive.ai/setup 302s to INSTALL_FOR_AGENTS.md — and the same wording the landing page hands out, so the two surfaces stop disagreeing about how this begins. The join case keeps its placeholders and moves to where it belongs: the project's own home page in the hub already renders that paste pre-filled, and the page now says to use it rather than hand-assemble one. Getting this wrong means a teammate creating a second project beside yours, so it is stated as the consequence rather than a preference. Also says why "Ask me which folder to sync" is in the sentence at all. It is not politeness: without it agents read the rest as permission to decide, and the guess is the whole folder — the one answer INSTALL_FOR_AGENTS.md tells them never to recommend (#157). README carries the same paste and is updated with it, per the sync rule in CLAUDE.md. Claude-Session: https://claude.ai/code/session_01CmKrcXaXxamwcPqR4DcU7S Co-authored-by: Claude Opus 5 (1M context) --- README.md | 31 +++++++++------- web/docs/src/content/docs/start/setup.md | 45 ++++++++++++++++-------- 2 files changed, 48 insertions(+), 28 deletions(-) diff --git a/README.md b/README.md index 1703ef0..d3b75b8 100644 --- a/README.md +++ b/README.md @@ -133,22 +133,27 @@ No terminal needed: start any agent (Claude Code, Codex, Gemini CLI, Hermes) in the folder you want synced and give it one paste: ``` -Follow https://raw.githubusercontent.com/runbear-io/beardrive/main/INSTALL_FOR_AGENTS.md -to set up BearDrive project on . Ask me which folder to -sync (the project is named ""). +Follow beardrive.ai/setup to set up BearDrive. Ask me which folder to sync. ``` -Joining a teammate's project? They can copy that paste with the hub URL and -project id already filled in from the project's home page in the web UI. -Starting fresh, drop the trailing sentence — the agent recommends `shared/` -and names the new project `shared`. +Keep the second sentence. Without it an agent reads the first as permission to +decide for you, and the usual guess is *this whole folder* — the one answer the +runbook tells it never to recommend. With it, you get a named recommendation to +accept or override: `shared/` from a standing start, or a notes folder it +already found. -The agent fetches [INSTALL_FOR_AGENTS.md](INSTALL_FOR_AGENTS.md) and follows -it: install the CLI, then one `bdrive init` — which signs in (an approval link -when there is no local browser), registers the sync hooks, and prints the -project link. The instructions live at that URL rather than inside the prompt -so they never go stale in someone's copy, and the agent handles every -deviation (already installed, no Homebrew, sign-in, wrong folder). +Self-hosting? Say where: `… to set up BearDrive on https://hub.example.com.` +Joining a teammate's project? Use the paste on that project's home page in the +web UI instead — it carries the hub URL and project id, so the agent joins the +project rather than creating a second one beside it. + +`beardrive.ai/setup` redirects to [INSTALL_FOR_AGENTS.md](INSTALL_FOR_AGENTS.md), +which the agent fetches and follows: install the CLI, then one `bdrive init` — +which signs in (an approval link when there is no local browser), registers the +sync hooks, and prints the project link. The instructions live at that URL +rather than inside the prompt so they never go stale in someone's copy, and the +agent handles every deviation (already installed, no Homebrew, sign-in, wrong +folder). Those hooks are the whole integration, and `bdrive init` registers them in each platform's user config (`~/.claude/settings.json` and friends), once per diff --git a/web/docs/src/content/docs/start/setup.md b/web/docs/src/content/docs/start/setup.md index d24157a..6b68e4e 100644 --- a/web/docs/src/content/docs/start/setup.md +++ b/web/docs/src/content/docs/start/setup.md @@ -15,22 +15,35 @@ Start the agent — Claude Code, Cowork, Codex, Gemini CLI, Hermes — in the fo you want synced, and paste: ``` -Follow https://raw.githubusercontent.com/runbear-io/beardrive/main/INSTALL_FOR_AGENTS.md -to set up BearDrive project on . Ask me which folder to -sync (the project is named ""). +Follow beardrive.ai/setup to set up BearDrive. Ask me which folder to sync. ``` -The agent fetches that page and works through it — install the CLI, sign in -(it prints a link you approve in the browser), connect the project, register -the sync hooks. You copy one -thing; the agent handles every deviation — already installed, no Homebrew, -browser sign-in, wrong folder. On BearDrive Cloud, drop `on ` — -sign-in defaults to beardrive.ai. +`beardrive.ai/setup` redirects to +[INSTALL_FOR_AGENTS.md](https://github.com/runbear-io/beardrive/blob/main/INSTALL_FOR_AGENTS.md), +the runbook the agent actually follows. It fetches that page and works through +it — install the CLI, sign in (it prints a link you approve in the browser), +create the project, register the sync hooks. You copy one thing; the agent +handles every deviation — already installed, no Homebrew, browser sign-in, +wrong folder. The instructions live at that URL rather than inside the prompt, +so they never go stale in someone's copy. -The project name is in the prompt because the agent recommends a folder of -the same name — so `handbook` on the hub is `handbook/` on everyone's disk. -Starting from nothing (no project id, no name), it recommends `shared/` and -names the new project `shared`. +**"Ask me which folder to sync" is doing real work — keep it.** Without it, +an agent reads the rest of the sentence as permission to decide for you, and +the usual guess is *this whole folder*, which is the one answer the runbook +tells it never to recommend. With it, the agent stops and offers you a named +recommendation first. Starting from nothing it suggests creating `shared/` +and names the new project `shared`; if it finds a folder that already looks +like notes, it suggests that one instead. + +**Self-hosting?** Say where: `Follow beardrive.ai/setup to set up BearDrive on +https://hub.example.com. Ask me which folder to sync.` On BearDrive Cloud +there is nothing to add — sign-in defaults to beardrive.ai. + +**Joining a project a teammate already made?** Use the pre-filled paste from +that project's home page in the hub (see the tip below) rather than this one. +It carries the project's id and name, so the agent joins the existing project +instead of creating a new one — and recommends a folder named after it, so +`handbook` on the hub is `handbook/` on everyone's disk. If the folder turns out to be empty once it is connected, the agent offers one more choice: start from a structure, or from scratch. Four are shipped: @@ -59,8 +72,10 @@ The hooks step is the durable part: once they are registered, every later session in every folder syncs automatically, with nothing to remember. :::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. +A project's home page in the hub shows a paste with your hub URL and project +id already filled in. Send people there rather than asking them to assemble +one — it is the difference between a teammate joining your project and a +teammate creating a second one beside it. ::: ## What your agent just set up