From f12710d5270b3868b4a731ceb9ac5792f6f8af39 Mon Sep 17 00:00:00 2001 From: Snow Lee Date: Wed, 8 Jul 2026 15:09:11 -0700 Subject: [PATCH] docs(plugin): retire the "mount" framing; /beardrive:mount -> /beardrive:init MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit bdrive mnt was replaced by bdrive init, but the plugin still taught the old model — /beardrive:mount even instructed Claude to run a command that no longer exists. - /beardrive:mount -> /beardrive:init: login-aware, uses bdrive init (resume/create/connect, --shared), points at /beardrive:install for the full team setup. - Skill description reframed around "start syncing a project"; "mount a folder" kept as a trigger phrase since people still say it. - status command, marketplace manifest, README plugin section, and CLAUDE.md updated to match. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01R7Q9ZKSZRTdvrSJkYLUmYs --- .claude-plugin/marketplace.json | 2 +- CLAUDE.md | 2 +- README.md | 19 +++++++++------- plugin/commands/init.md | 37 ++++++++++++++++++++++++++++++++ plugin/commands/mount.md | 28 ------------------------ plugin/commands/status.md | 6 +++--- plugin/skills/beardrive/SKILL.md | 6 +++--- 7 files changed, 56 insertions(+), 44 deletions(-) create mode 100644 plugin/commands/init.md delete mode 100644 plugin/commands/mount.md diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 6c9e73c..4c6fe24 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -6,7 +6,7 @@ { "name": "beardrive", "source": "./plugin", - "description": "BearDrive: mount folders that stay in sync across devices through S3/GCS/any object store. Installs the beardrive skill, /beardrive:mount and /beardrive:status commands, and turn-boundary sync hooks in one step.", + "description": "BearDrive: folders that stay in sync across your team and agents through a BearDrive server (or S3/GCS directly). Installs the beardrive skill, /beardrive:install, /beardrive:init and /beardrive:status commands, and turn-boundary sync hooks in one step.", "category": "workflow", "tags": ["sync", "files", "workspace", "s3", "gcs", "agents"] } diff --git a/CLAUDE.md b/CLAUDE.md index 87a007b..f299ca8 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -62,7 +62,7 @@ The real coverage is the integration tests in `internal/syncer/syncer_test.go`: ## Claude Code plugin -`plugin/` is a Claude Code plugin (skill + `/beardrive:install` + `/beardrive:mount` + `/beardrive:status` commands + turn-boundary sync hooks). `/beardrive:install` (`plugin/commands/install.md`) is the team onboarding flow: binary, login, init, a consent-gated CLAUDE.md section about the shared folder, and project-level hooks in `.claude/settings.json` (blocking pull at UserPromptSubmit, async push on PostToolUse Write/Edit) so teammates without the plugin still sync, published via the marketplace manifest at `.claude-plugin/marketplace.json` (`/plugin marketplace add runbear-io/beardrive`). The canonical skill lives at `plugin/skills/beardrive/SKILL.md`; `.claude/skills/beardrive` is a symlink to it. The hook script `plugin/scripts/beardrive-sync.sh` (and the inline project-level hook commands) must stay a fast no-op for folders without a `.bdrive/` dir — it runs on every turn in every project. +`plugin/` is a Claude Code plugin (skill + `/beardrive:install` + `/beardrive:init` + `/beardrive:status` commands + turn-boundary sync hooks). `/beardrive:install` (`plugin/commands/install.md`) is the team onboarding flow: binary, login, init, a consent-gated CLAUDE.md section about the shared folder, and project-level hooks in `.claude/settings.json` (blocking pull at UserPromptSubmit, async push on PostToolUse Write/Edit) so teammates without the plugin still sync, published via the marketplace manifest at `.claude-plugin/marketplace.json` (`/plugin marketplace add runbear-io/beardrive`). The canonical skill lives at `plugin/skills/beardrive/SKILL.md`; `.claude/skills/beardrive` is a symlink to it. The hook script `plugin/scripts/beardrive-sync.sh` (and the inline project-level hook commands) must stay a fast no-op for folders without a `.bdrive/` dir — it runs on every turn in every project. ## Docs to keep in sync diff --git a/README.md b/README.md index 7a77234..ae30039 100644 --- a/README.md +++ b/README.md @@ -344,17 +344,20 @@ Install beardrive support in Claude Code with two commands: The plugin sets up everything at once: -- **`/beardrive:mount [folder] [remote]`** — one command that installs beardrive if - needed, mounts the folder (daemon + `.bdrive` config), and verifies the sync. - `/beardrive:status` diagnoses problems. +- **`/beardrive:install`** — the full team setup, conversationally: CLI, + sign-in, project init (whole folder or a shared subfolder like `wiki/`), + a consent-gated CLAUDE.md section for agents, and project-level sync + hooks in `.claude/settings.json`. +- **`/beardrive:init [folder] [--name/--project/--shared]`** — just start + syncing a project; `/beardrive:status` diagnoses problems. - **Turn-boundary sync hooks**, registered automatically: a blocking pull when you send a message (Claude always reads fresh files) and an async - push when the turn ends. The hook no-ops instantly in folders that aren't - beardrive mounts, so it's safe globally. + push when the turn ends. The hook no-ops instantly in folders without a + `.bdrive/` project, so it's safe globally. - **The `beardrive` skill** ([plugin/skills/beardrive](plugin/skills/beardrive/SKILL.md)), - covering mount/unmount/sync, backends and credentials, selective sync, and - troubleshooting. Working in a clone of this repo picks the same skill up - automatically via `.claude/skills/`. + covering init/stop/sync, sharing by URL, backends and credentials, + selective sync, and troubleshooting. Working in a clone of this repo + picks the same skill up automatically via `.claude/skills/`. ## How it works diff --git a/plugin/commands/init.md b/plugin/commands/init.md new file mode 100644 index 0000000..261512d --- /dev/null +++ b/plugin/commands/init.md @@ -0,0 +1,37 @@ +--- +description: Start syncing a project in this folder — create a new BearDrive project or connect an existing one, whole folder or a shared subfolder, and start the sync daemon +argument-hint: "[folder] [--name | --project ] [--shared ]" +--- + +Start syncing a project with BearDrive. Arguments: `$ARGUMENTS` (optional +folder, optional `--name`/`--project`/`--shared`). + +Follow these steps: + +1. **Check the bdrive CLI is installed**: run `command -v bdrive`. If + missing, offer to install it (`brew install runbear-io/tap/beardrive`, + or `go install github.com/runbear-io/beardrive/cmd/bdrive@latest`) and + wait for the user's choice before installing. + +2. **Sign in if needed**: run `bdrive login --status`. With no server or a + stale token, run `bdrive login` (tell the user a browser window is + coming; it completes by itself). Default server is beardrive.ai; pass a + self-hosted URL if the user mentioned one. + +3. **Initialize**: if the folder already contains `.bdrive/`, just run + `bdrive init --yes` there — it resumes syncing (including after a + rename/move). Otherwise decide the project name (argument, or ask, or + default to the folder name) and scope (whole folder, or only a shared + subfolder like `./wiki` via `--shared`), then run it non-interactively: + + ```sh + bdrive init --name --yes # whole folder + bdrive init --name --shared wiki # only ./wiki syncs + ``` + +4. **Verify**: run `bdrive status ` and confirm the daemon is + running and pending is 0. Summarize: project name/id, what syncs, and + that edits propagate to every team member within seconds. + +For the full team setup (CLAUDE.md guidance + per-project sync hooks in +`.claude/settings.json`), suggest `/beardrive:install` instead. diff --git a/plugin/commands/mount.md b/plugin/commands/mount.md deleted file mode 100644 index ec63a47..0000000 --- a/plugin/commands/mount.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -description: Mount a folder as a synced beardrive volume — one command sets up the sync daemon, the .bdrive project config, and (via this plugin's hooks) automatic sync at every turn boundary -argument-hint: [folder] [remote e.g. s3://bucket/prefix] ---- - -Mount a folder as a synced beardrive volume. Arguments: `$ARGUMENTS` (optional folder, optional remote URL). - -Follow these steps: - -1. **Check the bdrive CLI is installed**: run `command -v bdrive`. If missing, offer to install it (`brew install runbear-io/tap/beardrive`, or `go install github.com/runbear-io/beardrive/cmd/bdrive@latest`) and wait for the user's choice before installing. - -2. **Determine the folder**: first argument if given, otherwise the current directory. If the folder already contains a `.bdrive` file, the volume and remote are already configured — just run `bdrive mnt ` and skip step 3. - -3. **Determine the remote**: second argument if given. If not given, ask the user which backend they want: - - `s3://bucket/prefix` — Amazon S3 or any S3-compatible store (R2/MinIO via `AWS_ENDPOINT_URL`) - - `gs://bucket/prefix` — Google Cloud Storage - - `file:///abs/path` — a plain shared directory (NAS, external drive) - - none — local-only for now (`bdrive remote set` can add one later) - -4. **Mount**: run `bdrive mnt [--remote ]`. This registers the background sync daemon and writes the folder's settings to `/.bdrive`. - -5. **Verify**: run `bdrive status ` and show the result. If the remote errored, consult the beardrive skill's troubleshooting table (credentials are the usual cause). - -6. **Tell the user what's now active** (briefly): - - the daemon syncs continuously (every few seconds); - - this plugin's hooks also sync at every turn boundary — a blocking pull when they send a message, an async push when the turn ends — so Claude always works on fresh files; - - `.bdriveignore` in the folder root excludes files (gitignore-style); an `"include"` list in `.bdrive` narrows what syncs; - - `bdrive log` shows who changed what, `bdrive umnt` stops syncing. diff --git a/plugin/commands/status.md b/plugin/commands/status.md index affca84..75ec894 100644 --- a/plugin/commands/status.md +++ b/plugin/commands/status.md @@ -1,13 +1,13 @@ --- -description: Show bdrive sync status — mounts, daemon state, pending changes — and diagnose any sync problems +description: Show bdrive sync status — projects, daemon state, pending changes — and diagnose any sync problems argument-hint: [folder] --- -Show the bdrive sync status. Argument: `$ARGUMENTS` (optional folder; default all mounts). +Show the bdrive sync status. Argument: `$ARGUMENTS` (optional folder; default all projects). 1. Run `bdrive status $ARGUMENTS` and show the output. 2. If anything looks wrong, diagnose using the beardrive skill: - - `daemon: stopped` → restart with `bdrive mnt ` + - `daemon: stopped` → restart with `bdrive init ` - `pending` stuck above 0 → run `bdrive sync ` and read the error; it usually points at credentials or the remote - changes not appearing from another device → run `bdrive log ` to see whether the ops arrived 3. Summarize the state in one or two sentences. diff --git a/plugin/skills/beardrive/SKILL.md b/plugin/skills/beardrive/SKILL.md index 75a3388..b8d996c 100644 --- a/plugin/skills/beardrive/SKILL.md +++ b/plugin/skills/beardrive/SKILL.md @@ -1,13 +1,13 @@ --- name: beardrive -description: Use beardrive — a mountable, synced file system for AI agents. Mount any folder and it stays synced across devices through cloud object storage (S3, GCS, S3-compatible, or a shared directory) with full per-file change history and offline support. Use when the user wants to "mount a folder", "unmount", "sync now", "set up beardrive cloud storage", "connect beardrive to S3/GCS/R2/MinIO/NAS", "check bdrive status", "see beardrive logs", "see what changed", "who changed this file?", or troubleshoot a stuck sync. +description: Use BearDrive — a synced file system for AI agents and teams. Start syncing any project folder (bdrive init) and it stays in sync across devices and teammates through a BearDrive server or object storage, with accounts, per-file change history, public share links, and offline support. Use when the user wants to "set up beardrive", "sync this folder", "mount a folder", "share this file by URL", "start/stop syncing", "connect to a beardrive server", "check bdrive status", "see what changed", "who changed this file?", or troubleshoot a stuck sync. --- # BearDrive — synced file system for AI agents -**BearDrive** (CLI: `bdrive`) mounts any folder as a synced volume backed by an object store. Each mount runs a per-mount background daemon that scans for local changes and exchanges with the remote. Files on disk are always real files — every tool, editor, and agent works on them with no integration. +**BearDrive** (CLI: `bdrive`) turns any folder into a synced project: a background daemon per project scans for local changes and exchanges with the server (or object store). Files on disk are always real files — every tool, editor, and agent works on them with no integration. -Use this skill whenever the user is working with the `bdrive` CLI: mounting, unmounting, syncing, configuring a remote, inspecting state, reading change history, or debugging. +Use this skill whenever the user is working with the `bdrive` CLI: initializing or stopping projects, syncing, sharing files by URL, configuring a remote, inspecting state, reading change history, or debugging. ("Mount" in older docs = today's `bdrive init`.) ## Command map