diff --git a/web/docs/astro.config.mjs b/web/docs/astro.config.mjs
index fd56788..42b548b 100644
--- a/web/docs/astro.config.mjs
+++ b/web/docs/astro.config.mjs
@@ -63,6 +63,20 @@ export default defineConfig({
             { label: "Your first hour", slug: "start/first-hour" },
           ],
         },
+        {
+          // Job-shaped titles, persona named in the description (which is also
+          // the search snippet and the llms.txt line). These pages ROUTE — the
+          // moment one starts teaching a feature, it links to the guide that
+          // owns it instead.
+          label: "Use cases",
+          items: [
+            { label: "Share work across your team's agents", slug: "use-cases/team-artifacts" },
+            { label: "Keep a wiki your agents maintain", slug: "use-cases/team-wiki" },
+            { 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" },
+          ],
+        },
         {
           // Guides are about working with agents — that's what the product is
           // for. Command-by-command CLI detail belongs in Reference.
diff --git a/web/docs/src/content/docs/index.md b/web/docs/src/content/docs/index.md
index 54dbc52..47eb50c 100644
--- a/web/docs/src/content/docs/index.md
+++ b/web/docs/src/content/docs/index.md
@@ -40,6 +40,9 @@ page.
   Code, one paste anywhere else, and the folder syncs from then on.
 - **[Your first hour](/start/first-hour/)** — what a connected folder feels like:
   ask for a doc, get a link back, teammates' agents pick it up.
+- **[Use cases](/use-cases/team-artifacts/)** — how this fits a real situation:
+  a team sharing what its agents produce, a wiki that maintains itself, an
+  existing knowledge base that needs teammates, one context across devices.
 - **[Run a hub](/self-hosting/run-a-hub/)** — self-host in about ten minutes.
 - **[Manual setup](/manual/install/)** — the same result command by command, if
   you'd rather see the moving parts.
diff --git a/web/docs/src/content/docs/use-cases/company-brain.md b/web/docs/src/content/docs/use-cases/company-brain.md
new file mode 100644
index 0000000..9c37c76
--- /dev/null
+++ b/web/docs/src/content/docs/use-cases/company-brain.md
@@ -0,0 +1,109 @@
+---
+title: Turn a personal brain into a company brain
+description: You already have a knowledge base your agent reads — an OKF bundle, a gbrain repo, an Obsidian vault. Sync it so every teammate's agent reads the same one, with no export and no schema.
+---
+
+You already have the brain. It works, your agent reads it, and it is markdown on
+disk. What it doesn't have is teammates.
+
+## Why there is nothing to convert
+
+BearDrive syncs directories of real files. A knowledge base that is already a
+folder of markdown needs no export, no adapter, and no schema:
+
+- **[OKF](https://cloud.google.com/blog/products/data-analytics/how-the-open-knowledge-format-can-improve-data-sharing/)**
+  bundles — markdown with YAML frontmatter, cross-linked, `index.md` and
+  `log.md` at the root.
+- **[gbrain](https://github.com/garrytan/gbrain)** brain repos — `people/`,
+  `companies/`, `projects/`, `notes/`, one page per concept.
+- Obsidian vaults, Logseq graphs, or a folder of notes you never named.
+
+Your format is already the wire format. BearDrive moves the files and stays out
+of the way — it has no opinion about frontmatter, link syntax, or folder names.
+
+Derived state stays put too. gbrain keeps its index in PGLite or Postgres and
+its config in `~/.gbrain/`, both outside the brain repo, so there is nothing to
+exclude. If yours does write an index beside the notes, drop it in
+[`.bdriveignore`](/guides/scoping/).
+
+## Set it up
+
+Same as any project — [ask your agent](/start/setup/), in the brain folder:
+
+> Set up BearDrive here and invite my team.
+
+If the brain is a subfolder of something larger, sync just that subfolder:
+`bdrive init --shared brain/`. Teammates mount the same project on their own
+machines, wherever they like it on disk, and keep running their own local brain
+against the synced files.
+
+That is the whole migration. Files start arriving in seconds.
+
+## What you can skip at small scale
+
+gbrain's own company-brain setup shares a brain through infrastructure: a remote
+Postgres, an HTTP MCP server, and OAuth credentials scoped per teammate, with
+isolation enforced in SQL. That buys real things — one retrieval endpoint, and
+per-person access the database itself guarantees.
+
+If what you actually want is *everyone's agent reading the same notes*, file
+sync plus each person's local brain gets you there with no shared database, no
+server to run, and no connection limits. Keep the server for SQL-enforced
+scoping, a single query endpoint, or a brain too large to sit on a laptop.
+
+The two compose. BearDrive distributes the source of truth; anything you run on
+top of those files is your business.
+
+## Privacy is per project, not per folder
+
+This is the one place the models differ, and it is worth getting right.
+
+gbrain scopes access per person — `internal/bob/` invisible to Alice, enforced
+by OAuth and SQL. **BearDrive's unit of membership is the project**: everyone in
+a project sees the whole folder. There is no per-folder permission.
+
+So a walled boundary is a **separate project**:
+
+| Content | Project |
+|---|---|
+| Company knowledge everyone should have | `company-brain` — whole team |
+| HR, comp, performance notes | `people-ops` — that team only |
+| A customer's material you can't mix | `customer-acme` — the account team |
+
+One machine can mount all three, in sibling folders. Your agent reads across
+them locally, because on disk they're just folders — the wall is on the hub,
+where it belongs.
+
+## When two brains rewrite one note
+
+Consolidation passes rewrite markdown. If two teammates' agents rewrite the same
+file in the same window, BearDrive resolves it last-writer-wins and preserves
+the loser as a conflict copy beside it — nothing is lost, but someone has to
+merge the two.
+
+In practice:
+
+- Let **one machine** run scheduled consolidation, not everybody's.
+- Give people **their own subfolders** for raw capture (`notes/alice/`), and
+  keep the synthesized pages in shared space.
+- Ad-hoc edits are fine. The window that matters is seconds, and
+  [history](/guides/agent-artifacts/) shows who wrote what if you need to look.
+
+## What you get that the git repo didn't
+
+- **No git ceremony on notes.** No commit, no push, no pull, no merge conflicts
+  in prose. Files land in seconds.
+- **Provenance per change** — the account, the device, and the agent session
+  behind every edit, in the hub's history.
+- **Share links** for people outside the team: any page becomes a public URL
+  that renders, revocable and optionally expiring.
+- **[Read heat](/guides/what-agents-read/)** — which pages your agents actually
+  consume, and which ones everyone relies on and nobody maintains. Brains rot
+  quietly; this is how you see it.
+
+## Read next
+
+- **[Shared agent memory](/guides/shared-agent-memory/)** — an `AGENTS.md` map at
+  the brain's root, so a teammate's agent knows the layout on its first turn.
+- **[Scoping the folder](/guides/scoping/)** — subfolder syncing and
+  `.bdriveignore`, for the parts that shouldn't travel.
diff --git a/web/docs/src/content/docs/use-cases/multi-device.md b/web/docs/src/content/docs/use-cases/multi-device.md
new file mode 100644
index 0000000..5481b8e
--- /dev/null
+++ b/web/docs/src/content/docs/use-cases/multi-device.md
@@ -0,0 +1,58 @@
+---
+title: Carry one context across agents and devices
+description: For one person running several machines and more than one agent — laptop, desktop, a server, Claude Code and Codex. One project, mounted everywhere, so whichever agent you talk to starts from the same state.
+---
+
+The work is continuous; the machines are not. You start something in Claude Code
+on the laptop, pick it up in Codex on the desktop, and the second agent knows
+nothing about the first.
+
+## What you end up with
+
+- One project, mounted on every machine, in whatever folder each one prefers.
+- Every agent on every device starts its turn from the same files.
+- Offline is normal, not an error state — changes queue and reconcile when the
+  machine is reachable again.
+
+## Set it up
+
+[Set up with your agent](/start/setup/) on the first machine. On each additional
+one, connect the *same project* rather than making a new one — the agent needs
+the project id, which the hub shows on the project's home page:
+
+> Set up BearDrive here, connecting to project `p-79d0a07c`.
+
+The folder does not have to match across machines. State is keyed by a stable
+project id, never a path, so `~/work` on one and `~/Documents/work` on another
+are the same project. Moving or renaming a folder later is free.
+
+Install the skill and hooks **once per machine**, and the hooks once per project
+— that is what makes each agent pull before it answers. See
+[skills and hooks in detail](/manual/skills-and-hooks/).
+
+## More than one agent per machine
+
+The skill is a cross-agent format and the hooks are written per platform, so
+Claude Code, Codex, Gemini CLI, and Hermes can all be wired into the same folder
+at once. They read the same files and their writes are stamped with which agent
+session made them, so `bdrive log` and the hub's history stay legible even when
+four agents share a project.
+
+## What happens when two machines edit the same file
+
+Each device writes only its own append-only journal, and every device replays
+all journals in the same deterministic order — so they converge without a
+locking service.
+
+If the same file was edited on two machines in the same window, the later write
+wins and the other is preserved as a conflict copy beside it. Nothing is lost;
+you decide what to merge. Working offline for a day and reconnecting is the same
+mechanism, just with a longer window.
+
+## What matters for this case
+
+- **[Skills and hooks in detail](/manual/skills-and-hooks/)** — what to run on
+  each new machine, and why the pull hook is the one that matters.
+- **[How sync works](/concepts/how-it-works/)** — journals, blobs, and
+  deterministic replay, if you want to know why this converges rather than
+  hoping it does.
diff --git a/web/docs/src/content/docs/use-cases/personal-wiki.md b/web/docs/src/content/docs/use-cases/personal-wiki.md
new file mode 100644
index 0000000..70b6e39
--- /dev/null
+++ b/web/docs/src/content/docs/use-cases/personal-wiki.md
@@ -0,0 +1,53 @@
+---
+title: Run a personal wiki, publish part of it
+description: For one person — a researcher, writer, or consultant — who wants a versioned notebook their agent maintains, and the ability to publish a single page without publishing the notebook.
+---
+
+You keep notes and your agent helps write them. Two things are missing: a
+reliable record of how a document got to its current state, and a way to show
+one page to someone without handing over the whole notebook.
+
+## What you end up with
+
+- A notebook your agent reads and writes, on every machine you use.
+- Full history — every version of every file, kept forever, attributed to the
+  session that wrote it.
+- Public links for the pages you choose, revocable and optionally expiring.
+
+## Set it up
+
+You don't need a team or a server. [Set up with your agent](/start/setup/) —
+signing up on [beardrive.ai](https://beardrive.ai) creates a free personal
+workspace, and `bdrive login` targets it by default.
+
+## Tracking what changed
+
+Ask, rather than diffing:
+
+> What changed in my notes this week?
+
+The hub's **History** answers the same question visually: a feed of every change
+with time, device, and agent session, and any past version one click away.
+Nothing is deleted — content is content-addressed and retained, so a version
+from three months ago is still there.
+
+This is the difference between a notebook and a synced folder: you can always
+reconstruct how a conclusion was reached.
+
+## Publishing one page
+
+> Share `research/pricing-teardown.md` publicly, expiring in a week.
+
+You get a URL that renders the markdown as a page. No account needed to read it,
+it always serves the file's latest content, and you can revoke it at any time.
+The rest of the notebook stays private — sharing is per file, never per folder.
+
+Public pages are sandboxed and rate-limited, and carry a small "Shared with
+BearDrive" footer.
+
+## What matters for this case
+
+- **[Artifacts and links](/guides/agent-artifacts/)** — public share links in
+  full: expiry, revocation, and how shared files render.
+- **[Carry one context across agents and devices](/use-cases/multi-device/)** —
+  if the notebook should follow you to a second machine.
diff --git a/web/docs/src/content/docs/use-cases/team-artifacts.md b/web/docs/src/content/docs/use-cases/team-artifacts.md
new file mode 100644
index 0000000..39e1470
--- /dev/null
+++ b/web/docs/src/content/docs/use-cases/team-artifacts.md
@@ -0,0 +1,52 @@
+---
+title: Share work across your team's agents
+description: For a team that doesn't live in a terminal — marketing, ops, design, founders working in Claude Cowork or Claude Code. Everything your agents produce lands in one folder the whole team's agents can read.
+---
+
+Your team works with agents all day and the output goes nowhere. A brief lives
+in one person's chat history, a competitive analysis in another's, and the third
+person's agent re-does work that already exists.
+
+## What you end up with
+
+- One folder every agent on the team writes into and reads from.
+- Whatever your agent produces is on a teammate's machine seconds later —
+  nobody attaches, uploads, or pastes anything.
+- A link for anyone outside the team, when you want one.
+
+## Set it up
+
+Install the plugin once — Cowork and Claude Code share plugins, so this covers
+both — then run `/beardrive:install` in the folder you want shared.
+[Set up with your agent](/start/setup/) has the two commands.
+
+Nobody on the team needs to open a terminal: the agent installs what it needs
+and reports back. Invite teammates from the hub's sidebar (**Manage → New
+invite**); the link creates their account and adds them in one step, and they
+run the same `/beardrive:install` on their own machine.
+
+If the shared work should live in one subfolder rather than everything on your
+disk, say so — "sync only `client-work/`" — and the agent scopes it.
+
+## The loop
+
+> Draft the Q3 campaign brief and put it in `campaigns/`.
+
+The turn ends and the brief is on the hub. Your colleague, an hour later, asks
+their own agent about Q3 — and it has already read the brief, because it pulls
+the team's current files before it answers. Nobody sent anything.
+
+When it needs to leave the company:
+
+> Share the brief with the agency.
+
+You get a public URL that renders the document as a page — no account required,
+revocable, and it can expire on its own.
+
+## What matters for this case
+
+- **[Shared agent memory](/guides/shared-agent-memory/)** — write a short map of
+  the folder so every teammate's agent knows where things go. Without it, five
+  agents invent five folder structures.
+- **[Artifacts and links](/guides/agent-artifacts/)** — internal links for
+  teammates, public links for clients, and which to use when.
diff --git a/web/docs/src/content/docs/use-cases/team-wiki.md b/web/docs/src/content/docs/use-cases/team-wiki.md
new file mode 100644
index 0000000..a5852ab
--- /dev/null
+++ b/web/docs/src/content/docs/use-cases/team-wiki.md
@@ -0,0 +1,62 @@
+---
+title: Keep a wiki your agents maintain
+description: For a team whose knowledge lives in documents nobody updates. The wiki gets written as a side effect of work, every change is attributed, and Insights shows which pages are load-bearing and stale.
+---
+
+Every team has the same wiki problem: the pages that matter most are the ones
+nobody has touched in a year, and nobody knows which those are.
+
+An agent-maintained wiki inverts it. Knowledge gets written because writing it
+is now the cheapest way to finish the task, and the hub tells you which pages
+are carrying weight.
+
+## What you end up with
+
+- A wiki that grows as a side effect of work, not as a chore someone schedules.
+- Every page attributed: the account, the device, and the agent session behind
+  each change, with every past version retained.
+- A read map — which pages your team's agents actually consume, and which of
+  those are stale.
+
+## Set it up
+
+Inside a repository, sync only the wiki:
+
+> Set up BearDrive here, but only sync `wiki/`.
+
+Git directories never sync (per-file last-writer-wins would corrupt a
+repository), and a narrow scope keeps the surface honest. A standalone wiki
+folder works the same way — see [Set up with your agent](/start/setup/).
+
+## The loop
+
+Work normally. When something is worth keeping, say where it goes:
+
+> Write up what we learned in `wiki/research/q3-findings.md`.
+
+Next week someone asks their agent about churn. It reads the findings page
+first, because it pulls before it answers — then writes what *it* learned back
+into the same folder. That is the compounding part.
+
+The wiki improves every time anyone works, which is the only wiki maintenance
+model that has ever survived contact with a busy team.
+
+## Reading the health of it
+
+The hub's **Insights** (hub admins and org owners) plots reads against
+staleness. The quadrant to watch is **hot and stale**: pages your agents read
+constantly that nobody has updated. That is your maintenance queue, and it is
+usually three pages, not thirty.
+
+Folder listings show read counts to every member, so the signal is not locked
+behind an admin screen.
+
+## What matters for this case
+
+- **[What agents read](/guides/what-agents-read/)** — read heat, Insights, and
+  what the hub deliberately does not record.
+- **[Shared agent memory](/guides/shared-agent-memory/)** — an `AGENTS.md` map
+  at the wiki root so agents file things consistently instead of inventing a
+  structure per session.
+- **[Scoping the folder](/guides/scoping/)** — subfolder syncing and
+  `.bdriveignore`.