docs+skill: fold live-e2e findings into onboarding docs; add onboarding-e2e skill

From the first agent-conversation e2e against a live hub:
- install.md: git handoff for tracked knowledge folders (one transport per
  folder), .bdrive//.bdriveignore git guidance, Hermes per-user hook warning,
  drop stale share--list aside
- SKILL.md: .bdriveignore is local-only on --shared mounts (root file sits
  outside the include list) — doc now matches behavior
- new project skill .claude/skills/onboarding-e2e: reusable procedure to
  re-run the conversation-level e2e (staging, instruction materialization,
  agent prompt contract, verification, pass bar)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VbiaaVM2ACxeRi8ySG9ybc
This commit is contained in:
Snow Lee
2026-07-18 21:25:35 -07:00
co-authored by Claude Fable 5
parent 66f7a98fcc
commit a6ee5aa75e
3 changed files with 98 additions and 4 deletions
+17 -3
View File
@@ -29,9 +29,9 @@ browser window is coming, then sign in:
If `$ARGUMENTS` gives a project name and/or `--shared <dir>`, use them.
Otherwise ask the user two questions (or infer from their request):
- **Create a new project or connect an existing one?** (`bdrive share --list`
isn't needed here — `bdrive init --name <name>` creates-or-joins by name;
`bdrive init --project <p-id>` connects by id.)
- **Create a new project or connect an existing one?** (`bdrive init
--name <name>` creates-or-joins by name; `bdrive init --project <p-id>`
connects by id.)
- **Sync the whole folder, or only a shared subfolder?** Hard rule:
**never sync a repo root** — inside a repo, knowledge always syncs as a
scoped subfolder via `--shared`. Whole-folder is only for a dedicated
@@ -41,6 +41,12 @@ Otherwise ask the user two questions (or infer from their request):
markdown-heavy, not source code) and propose the best candidate for
confirmation, e.g. "I found `./wiki` — sync that?".
**One transport per folder.** If the chosen folder is currently git-tracked,
BearDrive and git would both write it — the silent-revert hazard. Get consent,
then hand it off: `git rm -r --cached <dir>` and add `<dir>/` to `.gitignore`;
stage the change but let the user commit. (Full detection ladder — git,
Obsidian, symlinks — in the beardrive skill's "Connecting knowledge tooling".)
Then run it non-interactively, e.g.:
```sh
bdrive init --name <project-name> --yes # dedicated knowledge folder
@@ -49,6 +55,11 @@ bdrive init --name <project-name> --shared wiki # in a repo: only ./wiki sync
Re-running `bdrive init --yes` later is always safe: it resumes syncing
(including after the folder was renamed or moved).
After init, tell git what's what: add `.bdrive/` to `.gitignore` (per-machine
state, never committed) and COMMIT `.bdriveignore` (on a `--shared` mount the
root `.bdriveignore` is local-only to each clone, so git is how the team
shares it).
## 4. Teach agents about the shared folder (ask first — never do this silently)
Two files with different jobs (full rationale: the beardrive skill's
@@ -118,6 +129,9 @@ Tell the user which platforms got hooks (`bdrive hooks` shows the status
table). If Codex is among them, mention they must run `/hooks` inside
Codex once to trust the project's `.codex` layer. To register a platform
that wasn't detected: `bdrive hooks install --agent claude,codex,gemini,hermes`.
Heads-up before installing: Hermes hooks are PER-USER (`~/.hermes/config.yaml`,
outside the repo) — mention that when it's among the targets, and skip it
unless the user actually uses Hermes.
## 6. Verify and summarize
+1 -1
View File
@@ -37,7 +37,7 @@ Use this skill whenever the user is working with the `bdrive` CLI: initializing
Two files at the mount root control a folder's sync behavior:
- **`.bdrive/`** — the folder's settings **directory**; `config.json` inside holds the **stable mount id** (`m-xxxxxxxx`) plus `volume`, `remote`, optional `include`. Written by `bdrive init`; safe to hand-edit (a running daemon picks changes up on its next tick). It is **never synced**, holds **no credentials** (the token lives in `~/.bdrive/settings.json`), and because all state is keyed by the mount id — not the path — the folder can be **renamed or moved freely**; the daemon exits on a move and the next bdrive command at the new location resumes.
- **`.bdriveignore`** — opt-out list, gitignore-style. **Syncs like a normal file**, so all devices share the same rules. Syntax subset: `#` comments, `*` within a segment, `**` across segments, `?`, trailing `/` for directories-only, a `/` elsewhere anchors to the mount root, `!` re-includes.
- **`.bdriveignore`** — opt-out list, gitignore-style. On a whole-folder mount it **syncs like a normal file**, so all devices share the same rules; on a `--shared <dir>` mount the seeded root `.bdriveignore` sits OUTSIDE the include list and is **local-only** — commit it to git (or place ignore rules inside the shared dir) if the team should share it. Syntax subset: `#` comments, `*` within a segment, `**` across segments, `?`, trailing `/` for directories-only, a `/` elsewhere anchors to the mount root, `!` re-includes.
```jsonc
// .bdrive/config.json