feat(gtm): round 1 — truth pass, positioning unification, community on-ramp, demo assets

GTM reviewer round 1 (baseline: positioning 6, funnel 4, open-paid 8, community 3, launch 3, metrics 2; 3 blockers + 3 majors, all repo-fixable): - TRUTH: removed the false 'no server required' claim (x3 on the website) and stale 'S3/GCS directly' sync claims in both plugin manifests — hub-only since v0.3.0 - POSITIONING: one line everywhere ('the open-source Google Drive for AI agents' + the attribution/read-analytics wedge) across README, website, marketplace.json, plugin.json, SKILL.md; third 'Why' card and AGPL-why rationale; nav CTA → Star on GitHub - COMMUNITY: CONTRIBUTING.md, issue forms + PR template, public dated ROADMAP.md, CHANGELOG.md seeded from all 8 releases - DEMO ASSETS: real product screenshots captured from the seeded demo hub (Insights treemap, browse-with-heat, public share page) embedded in README + website — no fabricated content anywhere - DOCS: self-hosting quickstart, metrics plan (north star: active shared brains), launch-plan drafts (Show HN/PH/launch week), and docs/gtm-handoff.md — the prioritized external-action checklist Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01P5cxPQdSGJnjXCYY9GeWXt
2026-08-25 08:08:08 +02:00 · 2026-07-15 11:56:14 -07:00
parent 19f69f2bb8
commit 00eee2c5ed
22 changed files with 582 additions and 21 deletions
@@ -1,14 +1,24 @@
 {
  "name": "beardrive",
-  "owner": { "name": "runbear", "email": "snow@runbear.io" },
-  "description": "BearDrive (beardrive) — a synced file system for AI agents",
+  "owner": {
+    "name": "runbear",
+    "email": "snow@runbear.io"
+  },
+  "description": "BearDrive — the open-source Google Drive for AI agents: one folder your team and their agents share, with per-change attribution and read analytics.",
  "plugins": [
    {
      "name": "beardrive",
      "source": "./plugin",
-      "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.",
+      "description": "BearDrive: folders that stay in sync across your team and agents through a self-hostable BearDrive hub, with per-file history and public share links. 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"]
+      "tags": [
+        "sync",
+        "files",
+        "workspace",
+        "agents",
+        "memory",
+        "claude-code"
+      ]
    }
  ]
 }
@@ -0,0 +1,47 @@
+name: Bug report
+description: Something misbehaved — a sync, the CLI, the hub, or the web UI
+labels: [bug]
+body:
+  - type: input
+    id: version
+    attributes:
+      label: bdrive version
+      description: Output of `bdrive version`
+      placeholder: beardrive v0.7.0
+    validations:
+      required: true
+  - type: input
+    id: os
+    attributes:
+      label: OS / platform
+      placeholder: macOS 15.2 (arm64) / Ubuntu 24.04
+    validations:
+      required: true
+  - type: dropdown
+    id: mode
+    attributes:
+      label: Where does it happen?
+      options:
+        - Syncing client (bdrive CLI / daemon)
+        - Self-hosted hub (bdrive web)
+        - Web UI in the browser
+        - Claude Code plugin / agent hooks
+        - Not sure
+    validations:
+      required: true
+  - type: textarea
+    id: repro
+    attributes:
+      label: What happened, and how do we reproduce it?
+      description: |
+        Steps, expected vs actual. For sync issues, `bdrive status` and
+        `bdrive log -n 20` output help a lot. Never paste tokens or the
+        contents of settings.json.
+    validations:
+      required: true
+  - type: textarea
+    id: logs
+    attributes:
+      label: Logs (optional)
+      description: Daemon log lives at `~/.bdrive/volumes/<mount-id>/daemon.log`.
+      render: text
@@ -0,0 +1,27 @@
+name: Feature request
+description: An idea for BearDrive — check ROADMAP.md first, it might already be planned
+labels: [enhancement]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: What are you trying to do?
+      description: The workflow or problem, not just the feature — context makes better designs.
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: What would you like BearDrive to do?
+    validations:
+      required: true
+  - type: dropdown
+    id: area
+    attributes:
+      label: Area
+      options:
+        - Sync engine / CLI
+        - Hub / web UI
+        - Agent integration (hooks, plugin, skills)
+        - Sharing / permissions
+        - Other
@@ -0,0 +1,10 @@
+## What & why
+
+<!-- One paragraph: what changes, and the problem it solves. -->
+
+## Checklist
+
+- [ ] `go build ./... && go vet ./... && go test ./...` green
+- [ ] Sync behavior changes have a multi-device test in `internal/syncer`
+- [ ] Frontend changes: `npm run build` re-committed `internal/webapp/static` and `npm run e2e` is green
+- [ ] CLI behavior changes updated both `README.md` and `plugin/skills/beardrive/SKILL.md`
@@ -0,0 +1,69 @@
+# Changelog
+
+Notable changes per release. Format loosely follows
+[Keep a Changelog](https://keepachangelog.com/); BearDrive is pre-1.0, so
+minor versions may ship breaking changes (see [SemVer §4](https://semver.org/#spec-item-4)).
+
+## v0.7.0 — 2026-07-14
+
+- **`bdrive url <file>`** — internal, permission-walled links (sign-in +
+  project membership required) that agents share when they create files;
+  the plugin now teaches agents to include the link in their reply.
+- Mobile layout overhaul: responsive chrome now covers tablet and phone
+  landscape, 44px touch targets throughout, five designer-review rounds.
+- Read-heat hooks re-registered on upgrade pick up broader matchers.
+
+## v0.6.0 — 2026-07-13
+
+- **Web UI rewritten in React + TypeScript** (same URLs, same design):
+  committed build output keeps `go build`/`go install` Node-free.
+- **Read-heat coverage fix**: agent reads via shell commands (`cat`,
+  `grep`, `tail`) and Grep matches now count, not just native file reads;
+  `bdrive hooks install` upgrades existing hook matchers in place.
+- Content-hashed assets served immutable; committed e2e harness +
+  42-spec Playwright suite.
+
+## v0.5.0 — 2026-07-12
+
+- **Project home page**: connect-an-agent guide (Claude Code & Cowork
+  plugin flow, Hermes/Codex CLI) with real hub URL + project id filled
+  in; Insights embedded for admins/org owners.
+- Two-file AGENTS.md orientation for shared folders in the plugin flows.
+- Expandable history notes; RESTful `/insights` and `/history` routes.
+
+## v0.4.0 — 2026-07-12
+
+- **Read heat / Insights**: per-file read telemetry (human vs agent vs
+  share), heat dots in listings, and the Insights dashboard — treemap,
+  reads×staleness scatter with the hot-but-stale danger quadrant, hot
+  path, per-agent coverage matrix.
+- **Agent read reporting**: `bdrive read-log` + hooks spool agent file
+  reads locally and report on next sync.
+
+## v0.3.1 — 2026-07-10
+
+- Parallel blob upload + progress bar for large initial imports.
+
+## v0.3.0 — 2026-07-10
+
+- **Hub-only architecture**: clients sync exclusively through a
+  `bdrive web` hub over HTTPS (the `remote` command and direct
+  client-to-bucket sync were removed); `bdrive logout` added.
+- **SQL metadata backends**: hub accounts/projects/orgs/shares can live
+  in SQLite or Postgres (incl. Supabase) instead of JSON files.
+- Dockerfile + Cloud Run deployment recipe.
+
+## v0.2.2 — 2026-07-08
+
+- **BearDrive**: the project (formerly `sfs`) got its name; CLI became
+  `bdrive`.
+- Multi-project sync hub with accounts and orgs; interactive
+  `bdrive init` / browser `bdrive login` onboarding; public share links;
+  web viewer folded into the CLI as `bdrive web`; per-file history in
+  the web UI; `/beardrive:install` team onboarding for Claude Code.
+
+## v0.1.0 — 2026-06-12
+
+- First release: per-device append-only journals, last-writer-wins
+  replay, content-addressed blobs, offline-first sync through S3/GCS/
+  file remotes, conflict copies, daemon with turn-boundary agent hooks.
@@ -0,0 +1,65 @@
+# Contributing to BearDrive
+
+Thanks for wanting to help. BearDrive is early (pre-1.0) and moving fast —
+small, focused PRs land quickest, and an issue or discussion before a big
+change saves everyone time.
+
+## Build & test
+
+```sh
+go build ./...        # everything, no CGO, no Node needed
+go vet ./...
+go test ./...         # full suite
+go test ./internal/syncer -run TestConflict -v   # one test
+```
+
+Set `BDRIVE_HOME=/some/tmp/dir` when testing the CLI by hand so you never
+touch your real `~/.bdrive`.
+
+## Run a local hub
+
+```sh
+go build -o bdrive ./cmd/bdrive
+mkdir -p /tmp/hub-storage
+./bdrive web /tmp/hub-storage --addr :8080 --upload   # plain-folder viewer
+```
+
+For hub mode with accounts, see the self-hosting guide
+([docs/self-hosting.md](docs/self-hosting.md)). The e2e test harness
+(`BDRIVE_E2E_SERVE=1 go test -run TestE2EServe ./internal/webapp`) starts a
+seeded hub on :8993 with test accounts — handy for frontend work.
+
+## The rules that matter here
+
+- **Sync changes need multi-device tests.** The real coverage lives in
+  `internal/syncer/syncer_test.go`: simulated devices syncing through a
+  shared remote, driven cycle by cycle. A new sync behavior without a
+  multi-device test is untested where it matters.
+- **Never break sync.** Errors degrade to offline and retry next cycle;
+  a cycle must not fail because a side feature (telemetry, hooks) did.
+  Read the invariants section in [CLAUDE.md](CLAUDE.md) before touching
+  `internal/syncer`, `internal/journal`, or `internal/store` — replay
+  determinism and journal ownership are the whole concurrency story.
+- **Frontend changes rebuild the committed assets.** The web UI lives in
+  `internal/webapp/frontend` (React + TS, Vite); its build output is
+  committed at `internal/webapp/static` so `go build` needs no Node.
+  After changing `frontend/src`: `npm run build`, commit the new
+  `static/`, and keep `npm run e2e` green. `frontend/check-dist.sh`
+  verifies freshness.
+- **Docs travel with behavior.** Changing CLI commands, flags, or output
+  means updating both `README.md` and `plugin/skills/beardrive/SKILL.md`
+  — the skill is what makes agents beardrive-aware and must match the
+  binary.
+
+## Where to start
+
+[ROADMAP.md](ROADMAP.md) marks items we'd love help with, and issues
+labeled `good first issue` / `help wanted` are curated to be approachable.
+Bug reports with a reproduction (the issue form asks for `bdrive version`,
+OS, and hub vs plain-folder mode) are gold.
+
+## Conduct
+
+Be kind, be direct, assume good intent. Maintainers reserve the right to
+moderate. Security issues: email snow@runbear.io rather than opening a
+public issue.
@@ -11,8 +11,18 @@ Two things it's for: **sharing files with people** — any synced file
 becomes a public URL that renders as a page — and **sharing context across
 AI agents**: give every agent on the team the same folder as memory, and
 your agent knows what their agent knows. Notes, plans, findings, and
-artifacts follow the team everywhere, with a full audit trail of which
-agent or human changed what.
+artifacts follow the team everywhere — and unlike a memory API, they stay
+**real files with provenance**: every change is attributed to the human,
+agent, and device that made it, and the hub's Insights show what your
+agents actually read (and which hot-but-stale docs nobody maintains).
+
+<p align="center">
+  <img src="docs/assets/insights.png" alt="Knowledge Insights — every file plotted by agent/human reads vs staleness; hot-but-stale docs are the danger zone" width="820">
+</p>
+
+| Browse with read heat | Public share pages |
+|---|---|
+| ![Folder listing with per-file agent read counts and change feed](docs/assets/browse.png) | ![A shared markdown file rendered as a public page](docs/assets/share.png) |

 ```console
 $ bdrive login                # once per device (browser sign-in)
@@ -507,14 +517,19 @@ deletes for it), and anything excluded by `.bdriveignore` or omitted from an

 ## Roadmap

- `beardrive restore <path>@<time>` — restore any file from history (all content
-  is already retained)
- FUSE/NFS mount mode for lazy-loading huge volumes
- Journal compaction & blob GC policies
- Per-path access scopes for multi-agent setups
+See [ROADMAP.md](ROADMAP.md) — the public, dated roadmap, including the
+items we'd love help with. Highlights: `beardrive restore <path>@<time>`
+(time travel — all content is already retained), FUSE/NFS mount mode,
+journal compaction & blob GC, per-path access scopes for multi-agent
+setups.

 ## Development

+Contributions welcome — see [CONTRIBUTING.md](CONTRIBUTING.md) for the
+build/test workflow and the rules that matter, [ROADMAP.md](ROADMAP.md)
+for where help is wanted, and [CHANGELOG.md](CHANGELOG.md) for what
+shipped when. Self-hosting a hub: [docs/self-hosting.md](docs/self-hosting.md).
+
 ```sh
 go build ./...
 go test ./...
@@ -548,6 +563,11 @@ npm run e2e       # Playwright suite; starts its own seeded hub on :8993

 GNU AGPL-3.0 — Copyright 2026 Runbear, Inc. See [LICENSE](LICENSE).

+We chose AGPL-3.0 deliberately: it keeps BearDrive fully open and
+self-hostable forever while preventing a cloud provider from offering a
+closed BearDrive-as-a-service. The managed service at beardrive.ai funds
+the project; the code stays open.
+
 Everything in this repo is open source and self-hostable: a complete BearDrive
 server for one organization's deployment, teams included. The managed service
 at beardrive.ai is the same core plus what only makes sense as an operated
@@ -0,0 +1,38 @@
+# BearDrive roadmap
+
+Last updated: 2026-07-15. This is the direction, not a contract — items
+move as we learn. Comments and PRs welcome; items marked **help wanted**
+are deliberately scoped for outside contributors.
+
+## Now (next release or two)
+
+- **Time travel / restore** — `bdrive restore <path>@<time>`: every blob
+  is already retained forever, so restore is re-putting an old blob as a
+  new op. The history UI and blob API already exist; this is the CLI and
+  revert UX.
+- **Demo assets & docs** — 60-second demo, richer self-hosting guide.
+
+## Next
+
+- **Journal compaction & blob GC policies** — bounded storage for
+  long-lived, high-churn volumes (opt-in; today everything is retained).
+- **Per-path access scopes** — multi-agent setups where an agent can be
+  limited to a subtree of a project. **help wanted** (design discussion
+  first — this touches the org/permission model).
+- **More agent platforms in `bdrive hooks install`** — the hook engine is
+  platform-generic; adding a platform is a small adapter + matcher set.
+  **help wanted**.
+
+## Later / exploring
+
+- **FUSE / NFS mount mode** — lazy-loading huge volumes instead of full
+  materialization.
+- **Search across the hub** — full-text + wikilink graph over a project.
+- **Webhooks / notifications** — "a file changed in `reports/`" pushed to
+  Slack or similar (hub-side).
+
+## Recently shipped
+
+See [CHANGELOG.md](CHANGELOG.md): React web UI (v0.6.0), read-heat
+Insights and agent read attribution (v0.4.0), `bdrive url` internal links
+(v0.7.0), SQL metadata backends incl. Postgres/Supabase (v0.3.0).
@@ -0,0 +1,62 @@
+# GTM handoff — actions only Snow can take
+
+Everything the GTM loop cannot do from inside the repo, prioritized.
+Draft copy is ready to paste; adjust voice as you like.
+
+## P0 — do before anything else (minutes each)
+
+1. **Enable GitHub Discussions** on runbear-io/beardrive (Settings →
+   Features). Then add categories: Announcements, Q&A, Ideas, Show &
+   tell. CONTRIBUTING.md already links "where to ask" there.
+2. **Set GitHub repo topics**: `ai-agents`, `claude-code`, `file-sync`,
+   `sync`, `agent-memory`, `self-hosted`, `golang`, `agpl`. (Repo →
+   About → gear.)
+3. **Set the repo social-preview image** (Settings → Social preview):
+   use `docs/assets/insights.png` for now — it's the most striking
+   frame; replace with a branded card later.
+4. **Repo About blurb** → paste:
+   > The open-source Google Drive for AI agents: one folder your team
+   > and their agents share — synced in seconds, every change
+   > attributed, with read analytics. Self-host in one Go binary.
+   Website field: `https://beardrive.ai`.
+
+## P1 — demo assets (an hour)
+
+5. **Record a 45–60s demo GIF/video** for the README hero and any
+   launch post. Script (uses two terminals + a browser):
+   - T1: `bdrive init --name demo --yes` in a folder with a few notes →
+     show `bdrive status` (daemon running).
+   - T1: have Claude Code write `wiki/findings.md` (or just edit it) →
+     within seconds…
+   - T2 (second machine/dir): the file appears; `bdrive log -n 3` shows
+     the change attributed to the agent session.
+   - Browser: the hub's History view for that file, then Insights.
+   - T1: `bdrive share wiki/findings.md` → open the public URL.
+   Tools: `vhs` (charmbracelet) or QuickTime + gifski. Put the result at
+   `docs/assets/demo.gif` and add it above the fold in README.
+6. **Verify beardrive.ai serves the updated landing page** (the repo's
+   `website/` — including the new `assets/insights.png`) after the next
+   deploy.
+
+## P2 — when you're ready to be seen (launch window)
+
+7. **Show HN post** — full drafts in [launch-plan.md](launch-plan.md):
+   title, body, and the first-comment founder note. Post from your
+   account; be present for the first 3 hours to answer everything.
+8. **Product Hunt** — drafts in launch-plan.md. Schedule after HN, not
+   the same day.
+9. **Claude Code plugin discoverability** — submit/announce the
+   marketplace entry wherever Anthropic surfaces community plugins
+   (Discord, awesome-lists PRs from your account).
+
+## P3 — measurement plumbing (see metrics.md)
+
+10. **Turn on GitHub traffic watching**: stars/clones/views are under
+    Insights → Traffic; consider a weekly note of the numbers in
+    Discussions → Announcements.
+11. **Homebrew install counts**: `brew info --analytics
+    runbear-io/tap/beardrive` (public analytics take ~30 days to
+    appear).
+12. **Decide on hub-side opt-in telemetry** (proposal in metrics.md —
+    requires your explicit approval before any implementation; nothing
+    is wired today).
@@ -65,6 +65,7 @@ fabricated proof) — record such rejections under Won't-fix with reasons.

 | Round | positioning | funnel | open-paid | community | launch | metrics | repo-fixable blockers/majors |
 |---|---|---|---|---|---|---|---|
+| 1 (baseline) | 6 | 4 | 8 | 3 | 3 | 2 | 3 blockers, 3 majors (all fixed this round; screenshots captured from the live demo hub — real UI, not fabricated) |

 ## Won't-fix / disputed

@@ -0,0 +1,70 @@
+# Launch plan (drafts — nothing here is posted; posting is Snow's call)
+
+Stage-1 launch: the goal is strangers who care — stars, issues, first
+outside users — not signups or revenue. Sequence: quiet HN → learnings →
+Product Hunt → Launch-Week-style feature cadence as Cloud approaches.
+
+## Show HN (primary)
+
+**Title (pick one):**
+1. `Show HN: BearDrive – open-source Google Drive for AI agents`
+2. `Show HN: A shared folder where your team's AI agents read and write — with attribution`
+3. `Show HN: BearDrive – give every agent on your team the same folder as memory`
+
+**Body draft:**
+
+> BearDrive mounts any folder as a synced volume for a team *and their
+> AI agents*: files sync through a self-hostable hub in seconds, every
+> change is attributed to the human/agent/device that made it, and the
+> hub shows what your agents actually read.
+>
+> Why we built it: our agents kept re-deriving context that a teammate's
+> agent had already figured out. Memory APIs felt wrong — we wanted
+> real files on disk (agents are great at files), with provenance. So:
+> append-only per-device journals, last-writer-wins replay,
+> content-addressed blobs (all history retained), offline-first, one Go
+> binary for CLI + daemon + hub. AGPL; a managed cloud will fund it.
+>
+> The part we like most: read telemetry. Agent hooks report which files
+> agents consume, so the Insights view shows "hot but stale" knowledge —
+> docs everyone's agents rely on that no one maintains.
+>
+> Happy to answer anything about the sync design (no locks — no object
+> ever has two writers), the AGPL choice, or the agent hooks.
+
+**First-comment (founder voice) draft:** technical deep-dive offer —
+"the whole concurrency story is that no object has two writers: each
+device appends to its own journal; replay is deterministic," + link to
+CLAUDE.md's invariants. Answer every comment for the first 3 hours.
+
+**Prep checklist:** demo GIF live in README (handoff #5), Discussions
+enabled, `docs/self-hosting.md` linked from README, hub demo instance
+warm (expect self-host attempts within minutes).
+
+## Product Hunt (after HN, separate day)
+
+- **Tagline:** "The open-source Google Drive for AI agents"
+- **Description:** One folder your whole team and their agents share —
+  synced in seconds, every change attributed, read analytics included.
+  Self-host in one Go binary, or join the cloud waitlist.
+- **First comment:** the HN body, warmer tone, plus the 60s demo video.
+
+## Launch-Week cadence (when Cloud nears — one artifact/day)
+
+1. **Sync core** — the journal/replay design post ("no locks, no two
+   writers").
+2. **Attribution & history** — every change knows who/what/where; time
+   travel is already free (blobs retained).
+3. **Share links** — files as public pages; sandboxed HTML.
+4. **Insights** — the read×staleness quadrant; what agents actually
+   read.
+5. **The Claude Code plugin** — `/beardrive:install`, two-file AGENTS.md
+   orientation, `bdrive url` links in agent replies.
+
+Each day: a blog-able writeup + a tweet-length version + a repo artifact
+(doc or demo). Drafts to be written per-day when scheduled.
+
+## Not part of launch
+
+Pricing (Cloud is waitlist-only), enterprise pages, paid promotion, and
+any claim of traction we don't have.
@@ -0,0 +1,41 @@
+# Metrics plan
+
+What we measure to know whether BearDrive is working as a project and a
+product. Stage-aware: today (a16z stage 1, project-community fit) the
+numbers that matter are attention and activation, not revenue.
+
+## North star
+
+> **Active shared brains**: projects with ≥2 members where an agent both
+> wrote and read a file in the last 7 days.
+
+This is the promise — "your agent knows what their agent knows" —
+actually happening: multiple people, agents on both sides of the sync,
+within a week. Everything else is upstream of it.
+
+## Funnel metrics (in order)
+
+| # | Metric | Source | Stage |
+|---|---|---|---|
+| 1 | README/landing views → GitHub stars | GitHub Insights → Traffic (handoff #10) | attention |
+| 2 | Installs: brew + `go install` | brew analytics (handoff #11); go proxy stats are noisy — treat as directional | acquisition |
+| 3 | Activation: `bdrive init` → first successful sync | today: anecdotal/self-reported; future: opt-in telemetry (below) | activation |
+| 4 | Team formation: project gains a 2nd member (invite redeemed) | hub data (self-hosted: invisible to us; beardrive.ai once live) | expansion |
+| 5 | Wedge proof: first agent read-telemetry event in a project | hub read ledger (same visibility caveat) | wedge |
+
+## What we can already see without any new code
+
+- GitHub: stars, forks, issues, Discussions activity, traffic.
+- Homebrew analytics (public, aggregated).
+- beardrive.ai hub metrics once Cloud is live: metrics 3–5 fall out of
+  data the hub already stores (device registry, org invites, read
+  ledger) — measurement is a query, not instrumentation.
+
+## Proposal (not implemented — needs Snow's approval)
+
+Opt-in, anonymous CLI telemetry (a single `bdrive init` success ping with
+version + OS, no paths, no identifiers beyond a random install id,
+disabled by default with `BDRIVE_TELEMETRY=1` to enable). This is the
+only way metric #3 becomes visible for self-hosted users. **Deliberately
+a proposal**: shipping any telemetry, even opt-in, changes the trust
+posture of an OSS tool and is Snow's call, not the GTM loop's.
@@ -0,0 +1,84 @@
+# Self-hosting a BearDrive hub in ~10 minutes
+
+Until BearDrive Cloud launches, self-hosting is *the* way to run a team
+hub — and it stays a first-class, fully-supported path forever (AGPL, no
+features held back). One static Go binary, one config file, any object
+store (or a plain directory).
+
+## 1. Install the binary
+
+```sh
+brew install runbear-io/tap/beardrive     # macOS / Linuxbrew
+# or: go install github.com/runbear-io/beardrive/cmd/bdrive@latest
+# or: grab a release tarball — https://github.com/runbear-io/beardrive/releases
+```
+
+## 2. Pick storage
+
+Any of: `s3://bucket/prefix`, `gs://bucket/prefix`, an S3-compatible
+endpoint, or — simplest for a first run — a plain directory
+(`file:///var/lib/bdrive/storage`). Files and change journals live
+there; hub metadata (accounts, projects, orgs) lives in the database you
+pick in step 3. Clients never see this storage — they sync through the
+hub over HTTPS.
+
+## 3. Write config.json
+
+```jsonc
+{
+  "remote": "file:///var/lib/bdrive/storage",
+  "addr": ":4173",
+  "upload": true,
+  "auth": {
+    // Signup is invite-only by default — the safe posture for a public
+    // URL. Your first account: start once with signup gated (or use an
+    // org invite), then invite teammates from the web UI.
+    "admins": ["you@example.com"],
+    "users_db": "/var/lib/bdrive/auth.json"
+  },
+  "reads": { "enabled": true },              // agent read analytics (Insights)
+  "database": { "driver": "sqlite", "dsn": "/var/lib/bdrive/hub.db" }
+}
+```
+
+Full knob reference (allowed domains, email verification via SMTP,
+admin approval, Postgres/Supabase, share-link rate limits): the
+[README's web-server section](../README.md#web-server).
+
+## 4. Run it
+
+```sh
+bdrive web -c config.json
+```
+
+Put TLS in front (Caddy/nginx/your platform's LB) — device tokens travel
+as bearer tokens. For containers, the repo ships a `Dockerfile`
+(distroless, CGO-free) with a Cloud Run recipe in [deploy/](../deploy/)
+— any container platform works the same way.
+
+## 5. First sign-in and first project
+
+1. Open `https://your-hub/` → create your account (first run: use the
+   signup posture you configured; hub admins are the `admins` emails).
+2. On any machine: `bdrive login https://your-hub` (browser flow), then
+   in the folder you want synced:
+   `bdrive init --name wiki --yes` — or `--shared docs` inside a repo to
+   sync only that subfolder.
+3. Invite a teammate: sidebar footer → **Manage** → **New invite** —
+   the join link both creates their account and adds them to your org.
+4. Connect agents: the project's home page in the web UI shows
+   copy-paste setup for Claude Code/Cowork, Hermes, and Codex; or run
+   `bdrive hooks install` in the folder.
+
+## Upgrading
+
+`brew upgrade beardrive` (clients and hub are the same binary — keep
+them roughly in step; the sync protocol is append-only journals + blobs,
+which old clients read forward). After upgrading a client, re-run
+`bdrive hooks install` once per project to pick up any hook improvements.
+
+## Backup
+
+Everything irreplaceable is in two places: the storage root (blobs +
+journals — files and their entire history) and the metadata database
+(accounts/projects/orgs/shares). Snapshot both; restore is copy-back.
@@ -1,11 +1,21 @@
 {
  "name": "beardrive",
  "displayName": "BearDrive",
-  "description": "BearDrive: a synced file system for AI agents. Mount folders that stay in sync across devices through S3/GCS/any object store, with automatic sync at turn boundaries and full change history. CLI: bdrive.",
+  "description": "BearDrive — the open-source Google Drive for AI agents: mount folders that stay in sync across devices and teammates through a self-hostable BearDrive hub (backed by S3/GCS/any object store), with turn-boundary sync, per-change attribution, and full change history. CLI: bdrive.",
  "version": "0.1.0",
-  "author": { "name": "runbear", "url": "https://github.com/runbear-io" },
+  "author": {
+    "name": "runbear",
+    "url": "https://github.com/runbear-io"
+  },
  "homepage": "https://github.com/runbear-io/beardrive",
  "repository": "https://github.com/runbear-io/beardrive",
  "license": "AGPL-3.0-only",
-  "keywords": ["sync", "files", "workspace", "s3", "gcs", "memory", "agents"]
+  "keywords": [
+    "sync",
+    "files",
+    "workspace",
+    "memory",
+    "agents",
+    "claude-code"
+  ]
 }
@@ -1,9 +1,9 @@
 ---
 name: beardrive
-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 hub, with accounts, per-file change history, public share links, and offline support. Use when the user wants to "set up beardrive", "sync this folder", "share this file by URL", "start/stop syncing", "connect to a beardrive server", "switch to a different hub", "check bdrive status", "see what changed", "who changed this file?", or troubleshoot a stuck sync.
+description: Use BearDrive — the open-source Google Drive for AI agents and their teams. Start syncing any project folder (bdrive init) and it stays in sync across devices and teammates through a BearDrive hub, with accounts, per-file change history, public share links, and offline support. Use when the user wants to "set up beardrive", "sync this folder", "share this file by URL", "start/stop syncing", "connect to a beardrive server", "switch to a different hub", "check bdrive status", "see what changed", "who changed this file?", or troubleshoot a stuck sync.
 ---

-# BearDrive — synced file system for AI agents
+# BearDrive — Google Drive for AI agents

 **BearDrive** (CLI: `bdrive`) turns any folder into a synced project: a background daemon per project scans for local changes and exchanges them with a **hub** (a `bdrive web` server). Files on disk are always real files — every tool, editor, and agent works on them with no integration.

@@ -4,9 +4,9 @@
 <meta charset="utf-8">
 <meta name="viewport" content="width=device-width, initial-scale=1">
 <title>BearDrive — Google Drive for AI agents</title>
-<meta name="description" content="Google Drive for AI agents: one synced folder for your whole team. Share any file with people as a public URL; share context across agents, so your agent knows what their agent knows. Open source, no server required.">
+<meta name="description" content="Google Drive for AI agents: one synced folder for your whole team. Share any file with people as a public URL; share context across agents, so your agent knows what their agent knows. Open source and self-hostable.">
 <meta property="og:title" content="BearDrive — Google Drive for AI agents">
-<meta property="og:description" content="One synced folder for humans and agents: files become public URLs for people, and shared memory for every teammate's agent. Open source, no server required.">
+<meta property="og:description" content="One synced folder for humans and agents: files become public URLs for people, and shared memory for every teammate's agent. Open source, self-host in one binary.">
 <meta property="og:type" content="website">
 <meta property="og:url" content="https://beardrive.ai">
 <link rel="icon" href="data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 100 100'><text y='.9em' font-size='90'>&#128059;</text></svg>">
@@ -276,7 +276,7 @@ footer a:hover { color: var(--text); }
      <a href="#claude">Claude Code</a>
      <a href="#get">Open source</a>
      <a href="https://github.com/runbear-io/beardrive" title="GitHub">GitHub</a>
-      <a class="btn" href="#get">Start syncing</a>
+      <a class="btn" href="https://github.com/runbear-io/beardrive">Star on GitHub</a>
    </div>
  </div>
 </nav>
@@ -287,7 +287,7 @@ footer a:hover { color: var(--text); }
    <h1>Google Drive for AI agents.<span class="green">Your agent knows what their agent knows.</span></h1>
    <p class="sub">One synced folder for your whole team — humans and agents.
    <b>Share any file with people</b> as a public URL; <b>give every agent the same
-    memory</b>, synced across machines in seconds. Real files. No server required.</p>
+    memory</b>, synced across machines in seconds. Real files. Self-host the whole thing in one Go binary.</p>
    <div class="cta-row">
      <a class="btn" href="#get">Start syncing</a>
      <button class="install" id="install" title="Copy">
@@ -362,7 +362,14 @@ every tool works          content-addressed blobs    append-only, no locks, offl
        session already knowing it</b>. Context stops being siloed per laptop;
        every agent on the team reads from, and writes to, the same brain.</p>
      </div>
+      <div class="card"><div class="ico">📊</div>
+        <p style="font-size:15px"><b>See what your agents actually read.</b> Every change is
+        attributed to the human, agent, or device that made it — and BearDrive's Insights
+        show which files your agents lean on and which "hot but stale" docs the team relies
+        on that nobody maintains. Agents aren't just users of the folder; they're measured.</p>
+      </div>
    </div>
+    <p style="margin-top:28px"><img src="assets/insights.png" alt="BearDrive Insights — every file plotted by agent and human reads versus staleness" loading="lazy" style="width:100%;border-radius:12px;border:1px solid rgba(255,255,255,.09)"></p>
  </div>
 </section>

@@ -464,7 +471,7 @@ every tool works          content-addressed blobs    append-only, no locks, offl
        </ul>
        <div class="cta-row" style="justify-content:flex-start">
          <a class="btn" href="https://github.com/runbear-io/beardrive">View on GitHub</a>
-          <a class="btn ghost" href="https://github.com/runbear-io/beardrive#the-sync-hub-and-bdrive-init">Self-hosting guide</a>
+          <a class="btn ghost" href="https://github.com/runbear-io/beardrive/blob/main/docs/self-hosting.md">Self-hosting guide</a>
        </div>
      </div>
      <div class="oss-card cloud">