feat(cli,docs): say that agent skills sync, and refuse ~/.claude as a mount root (BEA-117) (#138)

`.claude/skills/**` has always synced — deliberately, per the reservation
rule's own comment — but the only sentence saying so sits under the heading
"What beardrive does not sync". Nobody knows.

Track B, the one real bug: `bdrive init ~/.claude` was accepted. The
reserved-path rule matches ".claude/settings.json" on its directory segment,
so at that mount root the file is bare "settings.json" — reserved by nothing —
along with .credentials.json and every saved session under projects/. New
exported config.AgentConfigDir folds the keys of agentHookConfigs the way
ReservedDir folds (case, trailing dots), and init refuses before any network
call or file write. Only that direction leaks: a mount CONTAINING ~/.claude
still sees .claude/settings.json, reserved at any depth.

Track A, the content job: a README Features bullet stating the positive claim,
a 7th use-case page (plus its astro.config.mjs sidebar entry, without which it
is invisible), and a `skills` template appended last to the registry so `docs`
keeps the RECOMMENDED badge. The embed directive becomes `//go:embed all:files`
— a plain pattern drops dot-prefixed paths silently, so the template whose
whole payload is .claude/skills/<name>/SKILL.md would have shipped empty.

templates_test.go's every-directory-holds-a-file rule now marks ancestors, not
just the direct parent: skills is the first template more than one level deep,
and the rule was stricter than its own stated reason (an intermediate
directory on the way to a file is not empty).

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>

web/docs/astro.config.mjs

@@ -148,6 +148,7 @@ export default defineConfig({
             { 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" },
           ],
         },
         {

web/docs/src/content/docs/reference/cli.md

@@ -11,7 +11,7 @@ One binary, `bdrive` — the CLI, the sync daemon, and the web server.
 |---|---|
 | `bdrive login [server-url]` | Sign this device in. Browser flow — the page names the account this terminal would act as and lets you switch before approving; `--device` forces the approval-link flow, and shells without a TTY (agents, CI, SSH) fall back to it automatically. Default server is beardrive.ai — the managed cloud, free personal workspace on signup; pass your hub URL to self-host. Switch hubs with `bdrive login <new-url>`. `--status` shows the current server and account |
 | `bdrive logout` | Sign this device out — revokes this device's token on the hub, then clears it locally. `--forget` also drops the remembered server |
-| `bdrive init [folder]` | Create or connect a project and start syncing — the mount is always exactly the folder named. Interactive on a TTY; flags (`--name`, `--project`, `--server`, `--only`, `--template`, `--yes`) for scripts. `--template docs\|wiki\|para` starts a new project from a structure instead of an empty folder. Also registers agent sync hooks for detected platforms (`--no-hooks` skips them) and a login item so sync resumes after a reboot (`--no-autostart` skips), and prints the project's hub link. Re-run to resume |
+| `bdrive init [folder]` | Create or connect a project and start syncing — the mount is always exactly the folder named. Interactive on a TTY; flags (`--name`, `--project`, `--server`, `--only`, `--template`, `--yes`) for scripts. `--template docs\|wiki\|para\|skills` starts a new project from a structure instead of an empty folder. Also registers agent sync hooks for detected platforms (`--no-hooks` skips them) and a login item so sync resumes after a reboot (`--no-autostart` skips), and prints the project's hub link. Re-run to resume |
 | `bdrive resume` | Restart the sync daemon for every project on this device that isn't paused — after a reboot, a crash, or a manual kill. Idempotent, so running it twice is harmless. This is what the login item runs |
 | `bdrive autostart [install\|uninstall]` | Show, add, or remove the login registration that runs `bdrive resume` after a reboot: a user LaunchAgent on macOS, a systemd user unit on Linux (needs systemd). `bdrive init` installs it; `--no-autostart` skips it |
 | `bdrive stop [folder]` | Stop syncing — daemon and agent sync hooks both pause. Files stay on disk; `bdrive init` resumes |
@@ -51,11 +51,12 @@ setting. Full flag bypass with `--name`, `--project`, `--template`, `--only`,
 
 A **new** project can start from a structure rather than an empty folder:
 `--template docs` (docs/, decisions/), `--template wiki` (an LLM-maintained
-wiki: sources/, wiki/, index.md, log.md) or `--template para` (projects/,
-areas/, resources/, archives/). Each one is a small directory skeleton plus the
+wiki: sources/, wiki/, index.md, log.md), `--template para` (projects/, areas/,
+resources/, archives/) or `--template skills` (a shared agent-skill library:
+`.claude/skills/`). Each one is a small directory skeleton plus the
 `AGENTS.md` that says where a new note goes, when something is archived, and
 what a good filename looks like — the instructions are the point, the folders
-are the scaffolding. On a TTY the same three starting points are offered as a
+are the scaffolding. On a TTY the same starting points are offered as a
 menu (recommended first, "empty project" last, and preselected); `--yes` and
 non-TTY never prompt and stay empty.
 

web/docs/src/content/docs/start/setup.md

@@ -44,6 +44,9 @@ more choice: start from a structure, or from scratch. Three are shipped:
   competitor file, a company brain fed by transcripts and threads.
 - **PARA** (`projects/`, `areas/`, `resources/`, `archives/`) — sorted by how
   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/).
 
 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

web/docs/src/content/docs/use-cases/shared-skills.md

@@ -0,0 +1,68 @@
+---
+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/<name>/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.