feat(templates): start a project from a structure, not an empty folder (#97)

* feat(templates): start a project from a structure, not an empty folder

A new project was an empty folder with a .bdriveignore in it, so every agent
session invented its own layout and the folder rotted into a pile. Both
surfaces now offer the same three starting points — from a template, from
scratch, from an existing folder (which is just a non-empty folder, and is
never restructured).

internal/templates holds the shipped set as literal go:embed'ed files: `docs`
(docs/, decisions/) and `para` (projects/, areas/, resources/, archives/).
cmd/bdrive is one binary for the CLI and the hub, so both read the identical
set — no gallery, no drift. The AGENTS.md in each is the deliverable: where a
new note goes, when something is archived, what a good filename looks like.
Every directory holds a real file, because BearDrive syncs paths and an empty
directory would never reach a teammate.

The hub seeds at creation through the existing Upload+Commit path, journaled
under its own device, and records the choice on the project record — so a user
who picked PARA in a browser sees PARA in the browser, and a later init cannot
seed a second copy. `bdrive init --template <name>` goes through the same
endpoint, with a local-seed fallback for a hub too old to know the field, and
seeds in place when re-run in an already-initialized folder (the agent's
post-init path). Seeding never overwrites an existing path, which is what makes
a double-seed a no-op rather than a divergence.

Refusals cost nothing: an unknown name and --template with --only are both
rejected before any network call or write.

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

* test(cli): joining a project that already has a template is refused by name

The one acceptance case with no test behind it: connecting to an existing
project with --template must say what the project was actually created from,
and must not write the other skeleton on the way out.

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

* fix(templates): name the docs template in plain English, not an acronym

"Plain docs + ADRs" was the recommended, first, preselected-adjacent option in
a picker that non-engineers see — and it's the label people accept without
reading further, so half of it not parsing is the worst place for jargon. The
title also disagreed with its own blurb: "ADRs" over "docs/, decisions/", two
words for the same folder one line apart.

Now "Docs + decision records", which says the same thing to everyone and
matches the folder names. The term itself moves into
decisions/0001-record-decisions.md, where the reader is already inside the
structure and the file can teach it in passing.

One line in the registry drives both the web dialog and the CLI menu; the rest
is prose echoing it.

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

* feat(templates): add the LLM wiki template

The third starting point from the issue title, unblocked: the spec parked it
because shipping an approximation under someone's name needed a source, and
there is now one — Karpathy's LLM Wiki gist. Worth noting the issue's own
one-line description of it ("few large, append-heavy topic pages") does not
match the source, which is the opposite: many interlinked pages, where a single
ingest touches 10-15 of them.

The pattern is three layers and three operations, not a folder shape. sources/
is yours and immutable; wiki/ is the agent's and it owns every page; AGENTS.md
is the schema layer — which is exactly the file this template system already
treats as the deliverable, so the fit is direct. index.md and log.md ship as
the two navigation files the pattern turns on.

Three of the things the gist tells you to go set up, BearDrive already is:
version history and collaboration (per-file history, bdrive log), an Obsidian-
style reader for [[wikilinks]] (the hub viewer), and a surface for the lint
pass (the dashboard is literally reads x staleness).

Two rules in the AGENTS.md are load-bearing and deliberate. A page write that
has not updated the index is an incomplete write — a stale index is worse than
a missing page, because it is read first and believed. And with no sources yet,
build nothing: the structure grows out of the material rather than ahead of it.

Shipped second, not first: docs stays the recommendation because a default is
the option chosen by people not reading closely, and this pattern degrades
badly when half-followed. Promoting it later is one line in the registry.

The shipped-template test now checks the "what happens when something stops
being true" question through a set of alternatives — PARA archives, a wiki
supersedes and revises — since the vocabulary honestly differs by structure.

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

* feat(web): "I already have a folder" as a starting point

The third way to start from the spec — adopt what you already have — had no
presence in the browser. Templates and "empty" were the only visible answers,
so someone with a folder of notes either hesitated or picked a template and got
four directories merged into their material.

The constraint that shapes it: the browser cannot reach your disk, so this
cannot change what is created. It creates the same empty project "Empty
project" does; what it changes is the next screen. Create therefore stays
enabled — disabling it would leave the dialog a dead end AND produce no project
id, which is the one thing the paste prompt actually needs.

Landing on the project home with the intent, three things differ: the guide
says "in the folder you already have", a note states plainly that connecting
never moves, renames or overwrites anything, and the paste prompt tells the
agent a folder already exists. That last one is the part that isn't cosmetic —
without it an agent reads an empty project and proposes creating shared/, the
one recommendation that is wrong here. It still asks which folder: that is the
runbook's hard gate and nothing here weakens it.

The intent rides in the URL (?connect=existing) rather than onto the project
record, the same way ?v= pins a file version. It belongs to whoever is
connecting right now — a teammate who connects next week has their own answer
and would be told the wrong thing by a persisted flag.

Five rows made the dialog tall enough to push Create off a short viewport, so
.modal scrolls internally. A hairline divider between the seeding and
non-seeding rows was tried and removed: --border is 7% white, which at 1px in a
gap renders as literally nothing. The gap is the cue that reads.

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

* feat(web): with no projects, open the create dialog and give the page a way in

A signed-in account with no projects landed on a page whose only path forward
was pasting a prompt into a coding agent. Now the create dialog opens itself —
with nothing to browse there is nothing else on that page to do — and the page
behind it leads with "Start a project" and a button, so closing the dialog is
not a dead end.

The dialog moves up to HubApp because three things ask for it now: the
sidebar's +, the empty state's button, and the auto-open. ProjectNav keeps only
an onNew callback; one owner beats three copies of the create handler.

Two guards on the auto-open. It fires once per mount, keyed off a ref rather
than the empty state, or closing it would immediately reopen it. And it never
fires on a read-only hub, which refuses creation server-side with a 403 —
opening a dialog that cannot succeed is worse than the page it covers.

The agent paste-prompt stays, demoted to "Or let your agent do it": it is still
the right path for someone who wants the folder connected in the same breath,
and it is the only path on a hub where this account cannot create.

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

---------

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

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 — clear the saved token and account. `--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`, `--yes`) for scripts. 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` 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), a per-user Run entry on Windows. `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 |
@@ -45,8 +45,25 @@ connect-existing (showing a project list) and whole-folder versus only some
 subfolders. To sync part of a folder without moving the mount, use
 `--only <dirs>` (comma-separated — `bdrive init . --only wiki,docs`), which
 writes a managed block of `.bdriveignore` rules rather than a separate scope
-setting. Full flag bypass with `--name`, `--project`, `--only`, `--yes`, and
-it never prompts without a TTY.
+setting. Full flag bypass with `--name`, `--project`, `--template`, `--only`,
+`--yes`, and it never prompts without a TTY.
+
+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
+`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
+menu (recommended first, "empty project" last, and preselected); `--yes` and
+non-TTY never prompt and stay empty.
+
+The hub seeds the template when the project is created, so it is there in the
+browser and arrives on every device that connects afterwards. Joining a project
+that already exists never restructures it, seeding never overwrites a file that
+already exists, and `--template` together with `--only` is refused before
+anything is written — scope rules live in the synced `.bdriveignore`, so a
+scope that left out the template's folders would hide them for the whole team.
 
 It runs the login flow first when there is no session, writes
 `.bdrive/config.json`, seeds `.bdriveignore`, registers agent sync hooks for

web/docs/src/content/docs/reference/project-files.md

@@ -39,7 +39,10 @@ so every device shares the same rules. See
 ## And nothing else
 
 Those two are all BearDrive puts in a project: `.bdrive/config.json`,
-`.bdriveignore`, and your own files. No agent-config directory is ever created
+`.bdriveignore`, and your own files. (A project created from a template also
+starts with an `AGENTS.md` and a directory skeleton — but those are ordinary
+synced files, yours to edit or delete like any other; nothing reads them but
+your agents.) No agent-config directory is ever created
 here — the sync hooks live in each platform's user config
 (`~/.claude/settings.json`, `~/.codex/hooks.json`, `~/.gemini/settings.json`,
 `~/.hermes/config.yaml`), written once per machine. See

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

@@ -32,6 +32,26 @@ the same name — so `handbook` on the hub is `handbook/` on everyone's disk.
 Starting from nothing (no project id, no name), it recommends `shared/` and
 names the new project `shared`.
 
+If the folder turns out to be empty once it is connected, the agent offers one
+more choice: start from a structure, or from scratch. Three are shipped:
+
+- **Docs + decision records** (`docs/`, `decisions/`) — the boring default, and
+  the one to take if you are not sure.
+- **LLM wiki** (`sources/`, `wiki/`, `index.md`, `log.md`) — you curate the raw
+  material and ask the questions; the agent writes and maintains every page,
+  keeps the index current, and health-checks the whole thing for stale claims
+  and orphans. It suits accumulating knowledge over weeks — research, a
+  competitor file, a company brain fed by transcripts and threads.
+- **PARA** (`projects/`, `areas/`, `resources/`, `archives/`) — sorted by how
+  actionable something is, with explicit archiving.
+
+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
+filename looks like. That file is the point; the folders are scaffolding. A
+folder that already has files in it is never restructured, and "from scratch"
+stays a real answer. The same choices appear when you create a project in the
+hub, and on the command line as `bdrive init --template docs`.
+
 The hooks step is the durable part: once they are registered, every later
 session in every folder syncs automatically, with nothing to remember.