@openparachute/vault 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,80 @@
+# Changelog
+
+All notable changes to Parachute Vault are documented here.
+
+This project loosely follows [Keep a Changelog](https://keepachangelog.com) and [Semantic Versioning](https://semver.org).
+
+## [0.2.0] — 2026-04-17
+
+First tagged public release. Ships the auth, backup, and onboarding surface the project needs for first-wave users.
+
+### Authentication
+
+- **OAuth 2.1 + PKCE** with Dynamic Client Registration (RFC 7591). Claude Desktop, Parachute Daily, and any OAuth-capable MCP client can connect with no manual token paste — user clicks "Add integration", browser opens to the vault's consent page, done.
+- **Owner password** (bcrypt-hashed, min 12 characters) for the OAuth consent page. Prompt fires at `vault init`; manage later with `parachute vault set-password` / `--clear`.
+- **TOTP 2FA with single-use backup codes**. `parachute vault 2fa enroll` prints a QR and one-time backup codes; `status` / `disable` / `backup-codes` subcommands for lifecycle.
+- **Per-vault OAuth scope** — discovery at `/vaults/{name}/.well-known/oauth-authorization-server` returns vault-scoped endpoints. Tokens minted there authenticate only against that vault.
+- **Cross-vault substitution blocked**: an OAuth code issued for one vault cannot be redeemed at another vault's token endpoint (schema-enforced via a `vault_name` column on `oauth_codes`).
+- **Honest token response**: `/oauth/token` returns `{ access_token, token_type, scope, vault }` so the client knows which vault it just connected to.
+- **Two permission tiers**: `full` (CRUD + delete + token management) and `read` (query / list / find-path / vault-info). Tokens default to `full`; pass `--read` to `tokens create` for read-only.
+- **Token CLI**: `parachute vault tokens` (list), `tokens create [--vault] [--read] [--expires <N{h|d|w|m|y}>] [--label]`, `tokens revoke <id> [--vault]`. Tokens are SHA-256 hashed at rest.
+- **Query-param auth for `/view`**: `?key=pvt_...` works alongside `Authorization: Bearer` and `X-API-Key` headers, convenient for browsers.
+
+### Backup
+
+- **`parachute vault backup`** — one-shot snapshot: atomic `VACUUM INTO` of every vault's `vault.db`, plus `config.yaml` and each vault's `vault.yaml`, bundled as a timestamped `.tar.gz`. Safe under concurrent reads/writes.
+- **Scheduled runs** via `parachute vault backup --schedule hourly|daily|weekly|manual` (macOS launchd). Linux systemd-timer support is a follow-up; wire cron yourself for now.
+- **`backup status`** shows schedule, last run, destinations, next run, and per-destination tier breakdown.
+- **Tiered (grandfather-father-son) retention**. Default: `daily: 7 / weekly: 4 / monthly: 12 / yearly: null` (unbounded). Set any tier to `0` to disable. Local-timezone bucketing.
+- **Pluggable destinations**. `local` (any filesystem path — iCloud Drive, external disk, rsync/Syncthing folder) ships in 0.2.0. `s3`, `rsync`, and `cloud` destinations designed but not yet implemented.
+- **`vault uninstall` tears down the backup agent too** on macOS, so scheduled backups don't keep firing on a removed install.
+
+### Reliability
+
+- **`parachute vault doctor`** — diagnostic suite covering server-path pointer, wrapper script, launchd agent (macOS) / systemd service (Linux), bun-on-PATH, MCP entry in `~/.claude.json` (presence + URL port match + reachability), port-collision (free / ours / foreign via `lsof` or `ss`), and — when scheduled backups are configured — backup agent + per-destination writability. Exits 1 on any `fail`.
+- **`vault status`** is healthcheck-aware and reports live daemon state, not just service registration.
+- **`vault restart`** blocks until `/health` returns 200, with a sensible budget and progress indicator.
+- **Path-resilient `start.sh`** — the wrapper launchd/systemd executes embeds an absolute `bun` path + points at `~/.parachute/server-path`, which resolves to the current repo location. Move the repo, re-run `vault init`, and the daemon follows you.
+- **Idempotent `vault init`** — safe to re-run after a folder move or config edit; refreshes the pointer, wrapper, and service registration without touching user data.
+- **Graceful shutdown**: in-flight webhook triggers get a 5 s drain window before the daemon exits on SIGTERM/SIGINT.
+
+### Multi-vault
+
+- **Public `GET /vaults/list`** — unauthenticated discovery endpoint returning only vault names (no descriptions, timestamps, counts, or keys). Lets a client populate a vault picker before OAuth. Operators who want to hide vault existence can set `discovery: disabled` in `~/.parachute/config.yaml` to make the endpoint return 404.
+- **Single-vault auto-default** — when the server has exactly one vault, the unscoped `/mcp`, `/api/*`, and `/oauth/*` paths transparently resolve to it regardless of its name. A lone vault named `journal` works at `/mcp` with no vault-in-URL needed.
+- **Vault-management CLI**: `parachute vault create <name>`, `list` (alias `ls`), `remove <name> --yes` (alias `rm`).
+- **Automatic `default_vault` management** — `vault create` promotes a new vault to default when none is set or the configured default points at a missing vault. `vault remove` promotes the sole survivor when you delete the default and one vault remains.
+
+### Install / uninstall
+
+- **`vault uninstall`** — removes the daemon registration, the `start.sh` wrapper, the `~/.parachute/server-path` pointer, and the `parachute-vault` entry in `~/.claude.json`. On macOS, tears down both the main vault agent and the backup agent. Preserves all user data.
+- **`vault uninstall --wipe`** — additionally removes `vaults/`, `.env`, `config.yaml`, `vault.log`, and `vault.err` after a second interactive confirm (default NO).
+- **`vault uninstall --yes --wipe`** — scripted destructive path. Skips both confirms and prints an ISO-timestamped audit line to stdout naming the target paths.
+- **`vault url`** prints the local server URL in a script-friendly form.
+
+### API / primitives
+
+- **Optimistic concurrency on `update-note`** via an `if_updated_at` parameter. When supplied and it doesn't match the note's current `updated_at`, the update is rejected (MCP: `ConflictError`; HTTP: 409). Batch updates fail fast on the first conflict.
+- **Link expansion on `query-notes`** — new `expand_links` / `expand_depth` (0–3) / `expand_mode` (`"full"` | `"summary"`) parameters inline `[[wikilink]]` targets directly into the returned content. Works on the MCP tool and the HTTP routes (single-note, search, and structured-list).
+- **9 composable MCP tools** (was 30): `query-notes`, `create-note`, `update-note`, `delete-note`, `list-tags`, `update-tag`, `delete-tag`, `find-path`, `vault-info`. Every note parameter accepts either an ID or a path.
+- **Webhook triggers** — declarative config-driven webhooks fire on note mutations matching tag / metadata predicates. Three send modes: `json` (general), `attachment` (Whisper-compatible transcription), `content` (OpenAI-compatible TTS).
+
+### Documentation
+
+- Entirely overhauled onboarding path: OAuth walkthrough, doctor + troubleshooting, first-run narrative (what `vault init` does on disk), multi-vault subsection, Tailscale Funnel walkthrough, prerequisites block.
+- Honest token-shape documentation (`pvt_` is modern; `pvk_` is legacy and still accepted).
+- README tells the truth about what `vault init` writes to `~/.claude.json` — a vault-scoped URL with a baked-in `pvt_` bearer, not OAuth.
+
+### Removed
+
+- **Semantic / vector search** — the embeddings path (`sqlite-vec`, `semantic-search` tool, embedding-provider setup wizard, `/api/ingest` endpoint). Full-text search via `query-notes` `search=` remains.
+- **`parachute vault keys` subcommand** — superseded by `parachute vault tokens`. Legacy `pvk_...` keys in `config.yaml` are still honored at runtime.
+
+### For contributors
+
+- **Async `Store` interface**, renamed to `BunSqliteStore`. Paves the way for Durable Object SQLite and R2 blob backends (in flight).
+- **`src/routing.ts`** extracted from `src/server.ts` so the request dispatcher is unit-testable without spinning up `Bun.serve()`.
+- **`core/src/test-preload.ts`** isolates `PARACHUTE_HOME` for tests so `bun test` never touches a user's real `~/.parachute/`.
+- Test suite at release cut: **538 passing / 0 failing / 3 skipped** across 22 files (541 tests total).
+
+[0.2.0]: https://github.com/ParachuteComputer/parachute-vault/releases/tag/v0.2.0

package/CLAUDE.md

@@ -6,9 +6,9 @@ Agent-native knowledge graph. Notes, tags, links over MCP. Self-hosted, one comm
 
 ```
 parachute vault init     →  ~/.parachute/ (config, .env, daemon, MCP)
-parachute vault create   →  new vault (SQLite DB + vault.yaml + API key)
+parachute vault create   →  new vault (SQLite DB + vault.yaml + pvt_ token)
 parachute vault config   →  manage env vars (PORT, etc.)
-parachute vault keys     →  list / create / revoke API keys
+parachute vault tokens   →  list / create / revoke per-vault tokens
 
 CLI  →  Bun server (port 1940)  →  multiple vaults (each its own SQLite DB)
                                          ↑

package/README.md

@@ -1,14 +1,16 @@
 # Parachute Vault
 
-A self-hosted knowledge graph for AI agents. Notes, tags, links — exposed over MCP. Any AI gets a personal knowledge vault in one command.
+**Parachute Vault is a self-hosted knowledge graph that any AI can read and write, over the open [MCP](https://modelcontextprotocol.io) protocol.** Your notes, tags, links, and attachments live on your machine — in plain SQLite databases under `~/.parachute/`, not in a vendor's cloud.
+
+Works with Claude, ChatGPT, Gemini, or any future MCP-capable AI. Switch tools without losing your knowledge. No vendor lock-in, no re-import step when the next model lands. One command to install; one OAuth consent to connect each AI client.
 
 ## Quick start
 
-Requires [Bun](https://bun.sh) (`curl -fsSL https://bun.sh/install | bash`).
+Requires [Bun](https://bun.sh) (`curl -fsSL https://bun.sh/install | bash`) and macOS 13+ or Linux. No root needed — see [Requirements](#requirements) below for specifics.
 
 ```bash
 # Install globally (registers the `parachute` CLI)
-bun add -g github:ParachuteComputer/parachute-vault
+bun add -g @openparachute/vault
 parachute vault init
 
 # Or clone and run directly
@@ -35,17 +37,167 @@ A server on port 1940 with:
 
 Each vault is its own SQLite database. Run multiple vaults on one server.
 
+## What `vault init` does
+
+A mental model for "where is my data?" and "what can I poke at?" after the one-command setup.
+
+### On disk — `~/.parachute/`
+
+```
+~/.parachute/
+  config.yaml           # global config — port, default_vault, owner password hash,
+                        # TOTP secret, backup-codes hashes, backup schedule. 0600.
+  .env                  # runtime env vars (PORT=1940 by default; any webhook API
+                        # keys you add later). Sourced by the daemon wrapper.
+  vault.log             # stdout of the running daemon (tail via `parachute vault logs`)
+  vault.err             # stderr of the running daemon
+  server-path           # text file: absolute path to the repo's src/server.ts —
+                        # how the daemon wrapper finds the source after you move it
+  start.sh              # the wrapper launchd/systemd execs. Knows the absolute
+                        # path to `bun` so a later PATH change doesn't break the daemon
+  assets/               # legacy top-level uploads dir (attachments now land per-vault)
+  vaults/               # one subdirectory per vault
+    default/
+      vault.db          # the SQLite database — notes, tags, links, attachments,
+                        # per-vault tokens, OAuth clients + codes, tag schemas
+      vault.yaml        # per-vault config — description (sent as MCP session
+                        # instruction), published_tag override, legacy api_keys
+      assets/           # per-vault uploaded attachments (audio, images)
+```
+
+`config.yaml` is the one file written at 0600 because it holds the bcrypt owner-password hash and the plaintext TOTP secret. `.env` is written with your umask default (typically 0644); if you add webhook API keys there, tighten the mode yourself. SQLite DBs follow your umask.
+
+### Registered externally
+
+- **macOS**: a launchd user agent labelled `computer.parachute.vault` (plus `computer.parachute.vault.backup` if you ran `vault backup --schedule`).
+- **Linux + systemd**: a user service named `parachute-vault.service` (managed via `systemctl --user`).
+- **Neither of the above**: `vault init` prints a reminder to start the server yourself (`bun src/server.ts` or Docker). No service registration.
+
+The daemon binds `0.0.0.0:1940` (or whatever you set in `PORT`) and serves REST, MCP, and OAuth routes. `parachute vault status` is the fast check; `parachute vault url` prints just the URL for use in scripts.
+
+### `~/.claude.json`
+
+`vault init` adds one entry — `mcpServers["parachute-vault"]` — pointing at `http://127.0.0.1:<port>/vaults/<default-vault>/mcp` with a baked-in `Authorization: Bearer pvt_...` header. Next Claude Code session picks it up; there's no further wiring. See [Connecting a client](#connecting-a-client) for rotating that token or pointing it elsewhere.
+
+### Your API token
+
+The `pvt_...` token printed at init is the one baked into `~/.claude.json`. It's not stored anywhere retrievable — save it if you need it for `curl`, cron, or any other script. Lost it? Just mint a new one: `parachute vault tokens create`. Tokens are SHA-256 hashed at rest in each vault's `vault.db`.
+
+### Owner password prompt
+
+Init pauses for one interactive prompt: "Set an owner password for OAuth consent?" The password is what the consent page asks for when Claude Desktop / Parachute Daily / any browser-OAuth client connects. You can skip it and set it later with `parachute vault set-password`; without it, the consent page falls back to pasting a vault token. See [Connecting a client → Owner password](#owner-password-needed-for-oauth).
+
+## Connecting a client
+
+Two ways to authenticate — pick based on the client, not the deployment:
+
+| Path | When to use | User action |
+|---|---|---|
+| **OAuth 2.1 + PKCE (browser flow)** | Claude Desktop, Parachute Daily, any third-party MCP client set up interactively | Click "Add integration", enter server URL, a browser opens to the vault's consent page, you enter the owner password, done — no token ever touches your clipboard |
+| **Bearer token** | Claude Code (auto-wired by `vault init`), CLI scripts, cron jobs, any non-interactive caller | `curl -H "Authorization: Bearer pvt_..."` — the token is printed once at `vault init` (save it) or minted on demand with `parachute vault tokens create` |
+
+Both paths end up with the same kind of token in the vault's DB — a `pvt_` string, scoped to one vault and one permission level (`full` or `read`). OAuth just moves the "how does the client get that token" step from "human copy-pastes it" to "browser-based handshake with the owner's consent."
+
+### Owner password (needed for OAuth)
+
+`vault init` prompts you to set an owner password (minimum 12 characters). This is what the OAuth consent page asks for when a client requests access. If you skip the prompt, OAuth still works but the consent page falls back to asking for a vault token instead — functional but clunky. Set it later with:
+
+```bash
+parachute vault set-password                # set / change
+parachute vault set-password --clear        # remove (reverts to token fallback)
+parachute vault 2fa enroll                  # optional: add TOTP 2FA on top
+```
+
+Password and 2FA secrets live in `~/.parachute/config.yaml` at mode 0600 (bcrypt hash + base32 TOTP secret).
+
+### Claude Code
+
+`vault init` fully auto-configures `~/.claude.json` — there's nothing else to do. The entry it writes uses a baked-in `pvt_` token rather than OAuth:
+
+```json
+{
+  "mcpServers": {
+    "parachute-vault": {
+      "type": "http",
+      "url": "http://127.0.0.1:1940/vaults/{name}/mcp",
+      "headers": { "Authorization": "Bearer pvt_..." }
+    }
+  }
+}
+```
+
+Where `{name}` is `default` on a fresh install, or whatever vault you pointed `vault init` at. **First MCP call after `vault init` requires no browser handoff — Claude Code uses the baked-in token and the vault's tools show up in your next session.** This is intentional: for an owner connecting their own machine's vault to their own Claude Code, the token is already there and OAuth would add friction.
+
+To re-point Claude Code at a different vault, change `default_vault` in `~/.parachute/config.yaml` and re-run `parachute vault init` — which re-mints an API token and re-writes the `~/.claude.json` entry end-to-end. To rotate the token only, edit `~/.claude.json` and replace the `Authorization` header value with a fresh token from `parachute vault tokens create`. (Running `parachute vault mcp-install` on its own overwrites the MCP entry *without* an `Authorization` header and is intended for the rare case where you want to drop the token and connect via OAuth instead.)
+
+### Claude Desktop (OAuth)
+
+For Claude Desktop — or any install where the server is on a different machine from the client — use the browser-based OAuth flow:
+
+1. Claude Desktop → Settings → Integrations → Add MCP server.
+2. Enter the URL: `https://vault.yourdomain.com/vaults/{name}/mcp` (replace `{name}`, or use the unscoped `https://vault.yourdomain.com/mcp` on a single-vault deployment). **Do not paste a bearer token** — leave the auth field empty.
+3. An OAuth-capable MCP client discovers the vault's authorization server at `/.well-known/oauth-authorization-server`, registers itself via Dynamic Client Registration (RFC 7591), and opens your browser to the vault's consent page.
+4. Enter your owner password (plus TOTP code / backup code if 2FA is enabled), pick a scope (`full` or `read`), click Authorize.
+5. Browser redirects back. The connection is live. The client now holds a `pvt_` token scoped to this vault.
+
+If you'd rather skip OAuth — e.g. you're scripting the setup — Claude Desktop also accepts a bearer token via the integration's auth header field. Use a token from `parachute vault tokens create` (or the one from `vault init` if you still have it). This is the "manual bearer" fallback; OAuth is the recommended path.
+
+### Parachute Daily (mobile)
+
+Daily uses the same OAuth flow. On first launch: enter the server URL, pick the vault from the drop-down (populated from the public `GET /vaults/list` endpoint), tap **Connect to Vault**. The same consent-page handoff runs in your phone's browser, then redirects back to the app via the `parachute://oauth/callback` deep link. The app stores the `pvt_` token in platform secure storage.
+
+### Multi-vault
+
+One server, many vaults. Each vault is its own SQLite DB with its own MCP endpoint, its own OAuth, and its own tokens.
+
+```bash
+parachute vault create work     # new vault named "work"
+parachute vault list            # show all vaults on this server
+parachute vault remove work --yes
+```
+
+**The default vault is managed for you.** `vault init` creates `default` on first install and records it as `default_vault` in `~/.parachute/config.yaml`. `vault create <name>` promotes the newly-created vault to default when no default exists or when the configured default points at a missing vault. `vault remove <name>` promotes the sole survivor when you delete the default and one vault remains; if multiple remain after removing the default, it clears the setting and tells you to edit `config.yaml` yourself. There is no `vault set-default` subcommand — to point the server at a different existing vault, edit the `default_vault:` line in `~/.parachute/config.yaml` and `parachute vault restart`.
+
+**Single-vault rule.** When the server has exactly one vault, the unscoped `/oauth/*` and `/mcp` paths transparently resolve to it — regardless of its name. A lone vault named `journal` works at `https://vault.example.com/mcp` with no vault-in-URL needed.
+
+**Multi-vault rule.** When the server has two or more vaults, always use the vault-scoped path (`/vaults/{name}/mcp`, `/vaults/{name}/oauth/authorize`). OAuth tokens minted there are scoped to that vault alone — cross-vault substitution is enforced at the OAuth layer: an auth code minted for one vault cannot be redeemed at another vault's token endpoint.
+
+**Listing vaults from a client.** The authenticated `GET /vaults` endpoint returns full vault metadata. The public `GET /vaults/list` endpoint returns names only, no metadata, no auth required — this is what Parachute Daily's vault picker calls before the user authenticates. Operators who want to hide the vault list from unauthenticated callers can set `discovery: disabled` in `~/.parachute/config.yaml` to make `/vaults/list` return 404.
+
 ## CLI
 
 ```bash
 # Setup
-parachute vault init                       # one-command setup
+parachute vault init                       # one-command setup (idempotent — safe to re-run)
 parachute vault status                     # check what's running
+parachute vault doctor                     # diagnose install/config issues (see Troubleshooting)
+parachute vault url                        # print the local server URL (for scripts)
+parachute vault uninstall                  # remove daemon + MCP entry; keeps user data
+parachute vault uninstall --wipe           # ...and also remove vaults, .env, config.yaml, logs
+parachute vault uninstall --yes --wipe     # scripted destructive wipe (prints an audit line)
 
 # Vaults
 parachute vault create work                # create a new vault
-parachute vault list                       # list all vaults
-parachute vault remove work --yes          # delete a vault
+parachute vault list                       # list all vaults (alias: `ls`)
+parachute vault remove work --yes          # delete a vault (alias: `rm`)
+parachute vault mcp-install                # (re)write the ~/.claude.json MCP entry for the default vault
+
+# OAuth — owner password + 2FA
+parachute vault set-password               # set/change the owner password (OAuth consent page)
+parachute vault set-password --clear       # remove the owner password (falls back to vault-token auth)
+parachute vault 2fa status                 # show 2FA state + remaining backup codes
+parachute vault 2fa enroll                 # enroll TOTP (shows QR + prints one-time backup codes)
+parachute vault 2fa disable                # disable 2FA (requires password or TOTP/backup code)
+parachute vault 2fa backup-codes           # regenerate backup codes (invalidates the old set)
+
+# Tokens
+parachute vault tokens                     # list all tokens across all vaults
+parachute vault tokens create                                 # full-access token in the default vault
+parachute vault tokens create --vault work                    # ...in a specific vault
+parachute vault tokens create --read                          # read-only token
+parachute vault tokens create --expires 30d                   # expiring token (N{h|d|w|m|y})
+parachute vault tokens create --label mobile                  # labeled token
+parachute vault tokens revoke <token-id>                      # revoke (default vault; add --vault to target)
 
 # Obsidian
 parachute vault import ~/Obsidian/MyVault              # import into default vault
@@ -53,18 +205,20 @@ parachute vault import ~/Obsidian/Work --vault work    # import into a specific
 parachute vault import <path> --dry-run                # preview without importing
 parachute vault export ./output --vault work           # export a specific vault
 
-# Tokens
-parachute vault tokens                     # list all tokens
-parachute vault tokens create --vault work                    # new full-access token
-parachute vault tokens create --vault work --read             # read-only token
-parachute vault tokens create --vault work --expires 30d      # token with expiry
-parachute vault tokens create --vault work --label mobile     # labeled token
-parachute vault tokens revoke <token-id> --vault work         # revoke a token
-
 # Config
-parachute vault config                     # show all options
-parachute vault config set KEY value       # set a config value
-parachute vault restart                    # apply changes
+parachute vault config                     # show current configuration
+parachute vault config set KEY value       # set an env var (e.g. PORT=1940)
+parachute vault config unset KEY           # remove an env var
+parachute vault restart                    # apply config changes (bounces the daemon)
+
+# Server
+parachute vault serve                      # run the server in the foreground (no daemon)
+parachute vault logs                       # stream vault.log + vault.err (tail -f)
+
+# Backup
+parachute vault backup                         # one-shot backup to configured destinations
+parachute vault backup --schedule daily        # hourly | daily | weekly | manual (macOS launchd)
+parachute vault backup status                  # schedule, last run, destinations, next run
 ```
 
 ## MCP tools (9)
@@ -164,12 +318,57 @@ triggers:
 
 Webhook servers (scribe, narrate) are stateless — they don't need vault's API key.
 
+### Backing up your vault
+
+Your vault is just SQLite DBs + a handful of YAML files under `~/.parachute/`. `parachute vault backup` snapshots everything into a single timestamped tarball, for a one-shot or a scheduled run.
+
+```bash
+parachute vault backup                         # one-shot — snapshot + ship to destinations
+parachute vault backup --schedule daily        # register a launchd agent (macOS)
+parachute vault backup --schedule manual       # stop scheduled backups
+parachute vault backup status                  # schedule, last run, destinations, next run
+```
+
+Configure destinations in `~/.parachute/config.yaml`:
+
+```yaml
+backup:
+  schedule: daily       # hourly | daily | weekly | manual
+  retention:
+    daily: 7            # last 7 daily snapshots
+    weekly: 4           # last-of-week for 4 weeks
+    monthly: 12         # last-of-month for 12 months
+    yearly: null        # last-of-year, unbounded (null = keep every year forever)
+  destinations:
+    - kind: local
+      path: ~/Library/Mobile Documents/com~apple~CloudDocs/parachute-backups
+```
+
+**Retention is tiered** (grandfather / father / son). After each run, the pruner keeps the union of four tiers:
+
+| Tier    | What it keeps                                          |
+|---------|--------------------------------------------------------|
+| daily   | The N most recent snapshots.                           |
+| weekly  | The last snapshot of each of the last N ISO weeks.     |
+| monthly | The last snapshot of each of the last N calendar months.|
+| yearly  | The last snapshot of each year — `null` means unbounded.|
+
+A snapshot that qualifies for multiple tiers is kept once. Set any tier to `0` to disable it; sparse data (days without a backup) just means some tiers contribute nothing that day. Bucketing uses your local timezone, so calendars line up with what you see, not UTC.
+
+**What's in a snapshot**: atomic `VACUUM INTO` copies of every `vaults/<name>/vault.db`, your `config.yaml`, and each vault's `vault.yaml`, bundled as `parachute-backup-<timestamp>.tar.gz`. Safe under concurrent reads/writes — no need to stop the daemon.
+
+**Restore**: extract the tarball into a fresh `~/.parachute/` and run `parachute vault init` to re-register the daemon. The DBs and configs drop in place; you don't need any special restore command (for now — a dedicated `vault restore` is coming soon).
+
+Destination kinds shipping in this release: `local` (any filesystem path — including iCloud Drive, a mounted external disk, or an rsync/Syncthing-backed folder). `s3`, `rsync`, and `cloud` destinations are planned but not yet implemented.
+
+On Linux, scheduled runs via systemd timers are a follow-up; for now `parachute vault backup` works on Linux but you'll need to wire the cron yourself.
+
 ### View endpoint
 
 Serve notes as clean HTML pages at `/view/:noteId`:
 
 - **Without auth**: only serves notes tagged `published` (or with `metadata.published: true`). Returns 404 for unpublished notes.
-- **With auth**: serves any note. Pass API key via `Authorization: Bearer pvk_...` header or `?key=pvk_...` query param.
+- **With auth**: serves any note. Pass your token via `Authorization: Bearer pvt_...` header or `?key=pvt_...` query param.
 - **Custom tag**: set `published_tag` in vault.yaml to use a different tag name (default: `publish`).
 
 ```yaml
@@ -212,11 +411,14 @@ Metadata is a JSON column. Vaults start blank — no predefined tags or schema.
 
 **All API and MCP requests require a valid API key.** No exceptions — localhost gets no special treatment.
 
-`vault init` generates an API key automatically and configures Claude Code's MCP with it.
+For wiring up an AI client (Claude Code, Claude Desktop, Parachute Daily), see [Connecting a client](#connecting-a-client) above. This section covers token-level details: how to pass a key, how to manage tokens, and which endpoints are public by design (`/health`, published notes at `/view/:id`).
 
 ### Passing the key
 
-Both legacy API keys (`pvk_...`) and scoped tokens (`pvt_...`) work interchangeably:
+Tokens come in two shapes. Both work interchangeably at every authenticated endpoint:
+
+- `pvt_...` — per-vault scoped tokens (the modern format; what `vault init` mints, what OAuth issues, what `parachute vault tokens create` produces)
+- `pvk_...` — legacy global API keys from `config.yaml` (still honored for existing deployments)
 
 ```bash
 # Header (preferred)
@@ -229,26 +431,6 @@ curl -H "X-API-Key: pvt_..." http://localhost:1940/api/notes
 curl http://localhost:1940/view/noteId?key=pvt_...
 ```
 
-### Claude Desktop
-
-Settings → Integrations → Add MCP → URL: `https://vault.yourdomain.com/mcp`, Header: `Authorization: Bearer pvk_...`
-
-### Claude Code
-
-`vault init` auto-configures `~/.claude.json`. To set manually:
-
-```json
-{
-  "mcpServers": {
-    "parachute-vault": {
-      "type": "http",
-      "url": "http://127.0.0.1:1940/mcp",
-      "headers": { "Authorization": "Bearer pvk_..." }
-    }
-  }
-}
-```
-
 ### Token management
 
 Per-vault tokens with two permission levels:
@@ -294,6 +476,37 @@ For remote access, always use a TLS-terminating proxy:
 | Direct LAN IP (no TLS) | Plaintext on WiFi | Avoid |
 | Direct internet (no TLS) | Plaintext on internet | Never do this |
 
+## Troubleshooting
+
+### `parachute vault doctor` is your first stop
+
+`doctor` inspects the install and prints one line per check with a status (`✓` pass, `!` warn, `✗` fail) and, when relevant, a suggested fix. It exits 1 on any `fail` and 0 otherwise. Run it any time something feels off.
+
+The checks, in the order they're emitted:
+
+| Check | What it verifies | Typical fix when failing |
+|---|---|---|
+| server-path pointer | `~/.parachute/server-path` exists, is non-empty, and points at a `src/server.ts` that actually exists. This is where the stale-path failure after a repo move shows up first. | `parachute vault init` from the current repo location. |
+| wrapper script | `~/.parachute/start.sh` exists. Without it, launchd / systemd has nothing to exec. | `parachute vault init`. |
+| launchd agent (macOS) / systemd service (Linux) | The daemon is registered and loaded/active. On Linux without systemd, the check is silently skipped. | `parachute vault restart` or re-run `vault init`. |
+| bun on PATH | `bun` is resolvable via your shell's PATH. Not required once the daemon is installed (`start.sh` embeds an absolute bun path at init time) but missing bun is the #1 first-time-user failure. | `curl -fsSL https://bun.sh/install \| bash` and restart the shell. |
+| MCP entry in `~/.claude.json` | An entry is present. When it is, two follow-ups: the URL's port matches the running vault's port, and the MCP URL is reachable over HTTP (any response — even 401 — counts as reachable). | `parachute vault mcp-install` to rewrite the entry, or `parachute vault restart` if the daemon is down. |
+| port `1940` availability | Probes via `lsof` / `ss` and classifies: free, held by our daemon (pass), held by a foreign process (warn), or unknown (tool unavailable → check silently omitted). | Stop the conflicting process, or set a different `PORT` in `~/.parachute/.env` and re-run `vault init`. |
+| backup agent (macOS, only when `backup.schedule != manual`) | The scheduled-backup launchd agent is loaded. | `parachute vault backup --schedule <hourly\|daily\|weekly>` to reinstall the agent. |
+| backup destinations (only when `backup.schedule != manual`) | At least one destination is configured; each configured destination is writable. | Edit `~/.parachute/config.yaml` under `backup.destinations`, or fix the path's permissions. |
+
+### Common failure modes
+
+- **Daemon won't start after a port change.** `~/.parachute/.env` has the new `PORT=...` but the daemon is still trying to bind the old one, or something else already holds the new port. `parachute vault doctor` surfaces both conditions. Fix the holder (or pick a different port) and `parachute vault restart`.
+- **MCP entry is stale after moving the repo.** launchd/systemd keeps pointing at the old path. `doctor` flags this as a failed `server.ts at pointer target` check; `parachute vault init` from the new location rewrites the pointer, wrapper, and daemon registration.
+- **Claude Code shows no vault tools.** Check in order: (1) is the daemon up (`parachute vault status`)? (2) does `~/.claude.json` have a `parachute-vault` entry with both `url` and a valid `Authorization` header? (3) does the URL's vault name match an existing vault? `parachute vault doctor` catches the first two. A missing or stale `Authorization` header after a bare `vault mcp-install` is the usual culprit for #2 — see the Claude Code section of [Connecting a client](#connecting-a-client) for how to rewrite it.
+- **Claude Desktop / Daily won't connect via OAuth.** If the owner-password prompt was skipped at `vault init`, the consent page falls back to requiring a vault token in place of the password (functional but clunky). Set one now with `parachute vault set-password`. If 2FA is enrolled, have your authenticator app ready before starting the flow; lost TOTP access recovers via the backup codes printed at enrollment.
+- **Scheduled backups aren't running.** On macOS: `doctor` flags `backup agent: not loaded` when `schedule` isn't `manual` but the launchd agent is missing — rerun `parachute vault backup --schedule <freq>` to reinstall it. On Linux: systemd-timer support for backup isn't shipped yet, so `--schedule daily` silently skips the scheduler. Run `parachute vault backup` from cron (or similar) until that lands.
+
+### Getting help
+
+If `doctor` is all-green but something still isn't working, capture the output alongside `parachute vault status` and open an issue at <https://github.com/ParachuteComputer/parachute-vault/issues>. Redact tokens from any logs before attaching.
+
 ## Deployment
 
 ### Remote access via Cloudflare Tunnel (free)
@@ -331,7 +544,37 @@ sudo cloudflared service install
 sudo systemctl start cloudflared
 ```
 
-Then in Claude Desktop: Settings → Integrations → Add MCP → `https://vault.yourdomain.com/mcp` with `Authorization: Bearer pvk_...`.
+Then point any client at `https://vault.yourdomain.com/vaults/{name}/mcp` (or `https://vault.yourdomain.com/mcp` for a single-vault deployment). See [Connecting a client → Claude Desktop (OAuth)](#claude-desktop-oauth) — the flow is identical to the local case once the URL is remote; the browser-based OAuth handshake makes the connection without pasting a bearer token.
+
+### Remote access via Tailscale Funnel
+
+If you're already on [Tailscale](https://tailscale.com), Funnel is the shortest path to a public HTTPS URL — no custom domain, no reverse-proxy config, no cert management. Good for a single-user vault or a vault shared with a handful of people; the edge has bandwidth and connection-count caps, so not suited to heavy traffic.
+
+Prerequisites: Tailscale v1.52 or later (earlier versions use a two-command `tailscale serve` + `tailscale funnel on` form that is now deprecated), the tailnet must have MagicDNS and HTTPS enabled in the admin console, and the `funnel` node attribute must be granted in your ACLs. The CLI adds the ACL entry on first use if you're the tailnet owner.
+
+Expose the vault:
+
+```bash
+# One command — Tailscale provisions the HTTPS cert, updates the ACL if needed,
+# and registers a persistent funnel that survives reboots.
+tailscale funnel --bg --https=443 localhost:1940
+
+# See what's being served and on which tailnet hostname
+tailscale funnel status
+
+# Take it down later
+tailscale funnel --https=443 localhost:1940 off
+# ...or nuke the whole funnel config
+tailscale funnel reset
+```
+
+The resulting URL is `https://<your-device>.<your-tailnet>.ts.net/` — `tailscale funnel status` prints it verbatim. You can also use ports `8443` or `10000` via `--https=<port>`; no other public ports are available to Funnel.
+
+Point any MCP client at the Tailscale URL:
+- Claude Desktop → Settings → Integrations → Add MCP → `https://<your-device>.<your-tailnet>.ts.net/vaults/{name}/mcp` (leave the Authorization field empty; the OAuth flow will handle it — see [Connecting a client](#connecting-a-client)).
+- Parachute Daily → enter the base URL `https://<your-device>.<your-tailnet>.ts.net`, pick the vault, tap Connect.
+
+**Cloudflare vs Tailscale, at a glance.** Pick Cloudflare when you want a custom domain, bandwidth headroom for heavier traffic, or to share the vault with people who aren't on your tailnet. Pick Tailscale when you're already running it, you're fine with a `*.ts.net` URL, and you want the setup to fit in two commands.
 
 ### Docker
 
@@ -347,9 +590,11 @@ docker compose up -d
 
 ## Requirements
 
-- [Bun](https://bun.sh) — `curl -fsSL https://bun.sh/install | bash`
-- macOS (launchd) or Linux (systemd) for background daemon
-- [cloudflared](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/) for remote access (optional)
+- **Bun** — `curl -fsSL https://bun.sh/install | bash` ([bun.sh](https://bun.sh)).
+- **macOS 13+** (launchd user agent) **or Linux** (systemd user service; other init systems work if you start the server yourself).
+- **No root / sudo required** — `vault init` writes to your user home (`~/.parachute/`) and registers the daemon in your user scope only. Never touches system paths or global services.
+- **Not supported on Windows natively.** WSL2 hasn't been tested; file an issue if you try it and want it to work.
+- Optional, for remote access: [cloudflared](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/) (Cloudflare Tunnel) or [Tailscale](https://tailscale.com) — see [Deployment](#deployment).
 
 ## License