@openparachute/vault 0.4.0 → 0.4.4-rc.11

package/README.md

@@ -139,7 +139,7 @@ Password and 2FA secrets live in `~/.parachute/vault/config.yaml` at mode 0600 (
 
 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/vault/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.)
+To re-point Claude Code at a different vault, change `default_vault` in `~/.parachute/vault/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, run `parachute-vault mcp-install` (defaults to `--mint`, which mints a fresh scope-narrow hub JWT via `~/.parachute/operator.token` and writes it into `~/.claude.json` with an `Authorization: Bearer …` header). See the [cookbook](#install-vault-mcp-into-a-client-config) section below for the full flag surface — token paste, scope narrowing, project-level install, multi-vault.
 
 ### Claude Desktop (OAuth)
 
@@ -190,7 +190,13 @@ parachute-vault uninstall --yes --wipe     # scripted destructive wipe (prints a
 parachute-vault create work                # create a new 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
+parachute-vault mcp-install                # (re)write the MCP client entry; defaults to --mint (hub-issued JWT) at local scope
+parachute-vault mcp-install --token <t>    # paste an existing bearer instead of minting
+parachute-vault mcp-install --legacy-pat   # mint a vault-DB pvt_* (self-hosted-without-hub)
+parachute-vault mcp-install --install-scope user      # write ~/.claude.json top-level (every project)
+parachute-vault mcp-install --install-scope local     # write ~/.claude.json projects[<cwd>] (this directory only — default)
+parachute-vault mcp-install --install-scope project   # write ./.mcp.json (checked into the repo)
+parachute-vault mcp-install --vault work   # target the "work" vault (keyed as parachute-vault-work)
 
 # OAuth — owner password + 2FA
 parachute-vault set-password               # set/change the owner password (OAuth consent page)
@@ -432,6 +438,189 @@ GET            /vaults/list                                       public: vault
 GET            /health                                            health check
 ```
 
+## Common queries / cookbook
+
+Patterns that fall out of vault's read and write surfaces. All examples assume your vault is reachable at `http://localhost:1940` and your token is in `$VAULT_TOKEN`. MCP-side examples are how the same operation looks via the tool layer (Claude Code, Claude Desktop, Daily). Each recipe answers a question consumers have asked while building against vault — see [vault#285](https://github.com/ParachuteComputer/parachute-vault/issues/285) for the field-input thread these distilled from.
+
+### Fetch every note under a path subtree
+
+For an SSG or wiki rendering a section of the vault. `path_prefix` matches against the normalized path string — no `.md`, no trailing slash.
+
+```bash
+curl -H "Authorization: Bearer $VAULT_TOKEN" \
+  "http://localhost:1940/vault/default/api/notes?path_prefix=Boulder%20Civics/City%20Council/&include_content=true"
+```
+
+```jsonc
+// MCP
+{ "name": "query-notes", "arguments": { "path_prefix": "Boulder Civics/City Council/", "include_content": true } }
+```
+
+### Sort by a metadata field
+
+Sort by something other than `created_at`. The field must be declared `indexed: true` in some tag schema first — that's what materializes the backing generated column + B-tree index. The "tag authorizes the index" pattern lives in [`core/src/indexed-fields.ts`](./core/src/indexed-fields.ts).
+
+```bash
+curl -H "Authorization: Bearer $VAULT_TOKEN" \
+  "http://localhost:1940/vault/default/api/notes?order_by=meeting_date&sort=desc&include_content=true"
+```
+
+Declare the index via `update-tag`:
+
+```jsonc
+{ "name": "update-tag", "arguments": {
+    "tag": "meeting",
+    "fields": { "meeting_date": { "type": "string", "indexed": true } }
+} }
+```
+
+### Return previews instead of full bodies
+
+Listing pages don't need the whole note. By default `GET /notes` returns the lean shape — 120-char whitespace-collapsed `preview`, `byteSize`, and the usual metadata — with no `content`. Single-note `GET /notes/:id` still returns full content by default; pass `include_content=false` to drop it.
+
+```bash
+curl -H "Authorization: Bearer $VAULT_TOKEN" \
+  "http://localhost:1940/vault/default/api/notes?path_prefix=Posts/"
+# → [{ id, path, byteSize, preview, tags, metadata, ... }, ...]
+```
+
+Caller-tunable preview length is a future enhancement — file an issue if 120 chars isn't enough.
+
+### Incremental rebuilds: "what changed since X"
+
+The SSG / sync pattern. Two equivalent forms — bracket-style is canonical going forward; the flat form is the same shape that ships through the REST/MCP date filter today.
+
+```bash
+# Bracket-style (canonical)
+curl -H "Authorization: Bearer $VAULT_TOKEN" \
+  "http://localhost:1940/vault/default/api/notes?meta[updated_at][gte]=2026-04-01T00:00:00Z"
+
+# Flat form (DEPRECATED in 0.4.3; planned removal 0.6.0 per vault#288)
+curl -H "Authorization: Bearer $VAULT_TOKEN" \
+  "http://localhost:1940/vault/default/api/notes?date_field=updated_at&date_from=2026-04-01T00:00:00Z"
+```
+
+```jsonc
+// MCP — `date_filter` accepts created_at, updated_at, or any indexed metadata field.
+{ "name": "query-notes", "arguments": { "date_filter": { "field": "updated_at", "from": "2026-04-01T00:00:00Z" } } }
+```
+
+Only `gte` and `lt` are accepted on `created_at` / `updated_at` (other operators reject with `INVALID_QUERY` — these bracket forms route to the real-column `dateFilter`, not the full metadata operator set, so the half-open `[from, to)` shape is the only expressible range). The full operator set in the next recipe applies to *metadata* fields only.
+
+### Filter by metadata values (bracket style)
+
+Equality on any metadata field works with no setup:
+
+```bash
+curl -H "Authorization: Bearer $VAULT_TOKEN" \
+  "http://localhost:1940/vault/default/api/notes?meta[meeting-type]=study-session&include_content=true"
+```
+
+Range, `in`, `not_in`, and `exists` operators require the field to be declared `indexed: true` (same gate as `order_by`):
+
+```bash
+# Range — both bounds AND together on one field
+"…/notes?meta[date][gte]=2026-01-01&meta[date][lt]=2026-04-01"
+
+# Membership — `[]` array form OR comma-separated; same result.
+"…/notes?meta[status][in][]=active&meta[status][in][]=exploring"
+"…/notes?meta[status][in]=active,exploring"
+
+# Presence check
+"…/notes?meta[deadline][exists]=true"
+```
+
+Supported operators: `eq` (default when no operator given), `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `not_in`, `exists`. Multiple `meta[…]` filters AND together. Bracket-style and shorthand on the same field in one request reject loudly — pick one form.
+
+### Edit one line in a large note (without re-sending the whole body)
+
+`content_edit` does surgical find-and-replace. Payload is the changed text, not the whole note. `old_text` must occur exactly once; multiple matches or zero matches reject with a "re-read and retry" error.
+
+```jsonc
+// MCP
+{ "name": "update-note", "arguments": {
+    "id": "notes/decisions",
+    "content_edit": {
+      "old_text": "Status: pending",
+      "new_text": "Status: shipped (2026-05-10)"
+    },
+    "if_updated_at": "2026-05-10T12:34:56.789Z"
+} }
+```
+
+```bash
+# REST equivalent
+curl -X PATCH -H "Authorization: Bearer $VAULT_TOKEN" -H "Content-Type: application/json" \
+  -d '{"content_edit":{"old_text":"Status: pending","new_text":"Status: shipped (2026-05-10)"},"if_updated_at":"…"}' \
+  "http://localhost:1940/vault/default/api/notes/notes/decisions"
+```
+
+Set `include_content: false` on the request to cut the response cost too — you get back the lean `NoteIndex` shape instead of the full updated note.
+
+### Append to a note (no concurrency ceremony)
+
+Atomic at the SQL layer: two concurrent appends both land in some order, never clobber. Append-only and prepend-only updates are exempt from the `if_updated_at` precondition that other mutations require — the SQL-atomic concatenation can't lose data on a stale read, so the precondition would be ceremony for no benefit. Underlying mechanic in [`core/src/notes.ts:295-322`](./core/src/notes.ts).
+
+```jsonc
+{ "name": "update-note", "arguments": { "id": "notes/journal/2026-05-10", "append": "\n\nEvening note: …" } }
+```
+
+`prepend` is frontmatter-aware: if the note opens with YAML frontmatter, the prepended text is automatically injected *after* the closing `---` fence so parsers that expect frontmatter at byte 0 still find it. Detection is done in the same SQL UPDATE expression, so atomicity is preserved.
+
+### CI / public access via Tailscale Funnel
+
+The shortest path to a public HTTPS URL for a vault you control — useful for SSG rebuilds running on GitHub Actions, Vercel, or any runner that isn't on your tailnet. See [Remote access via Tailscale Funnel](#remote-access-via-tailscale-funnel) below for the full setup.
+
+### Install vault MCP into a client config
+
+Bare `parachute-vault mcp-install` from a terminal **walks you through a short contextual conversation** — picks defaults informed by your environment (how many vaults you have, whether the hub is reachable, whether you're in a project directory, whether vault is already installed somewhere), shows the JSON shape it will write before doing anything, and asks before each non-obvious choice. The patterns below are the non-interactive shapes — pass any flag (`--mint`, `--token`, `--scope`, `--install-scope`, `--vault`, `--legacy-pat`) and the walkthrough is skipped.
+
+#### Install scopes
+
+`--install-scope` accepts three values, matching Claude Code's own `claude mcp add --scope`:
+
+| Scope | Where the entry lives | Visibility |
+|---|---|---|
+| `local` *(default)* | `~/.claude.json` under `projects[<absolute-cwd>].mcpServers` | private to your machine, scoped to this directory |
+| `user` | `~/.claude.json` top-level `mcpServers` | every project, every directory on this machine |
+| `project` | `<cwd>/.mcp.json` | checked into the repo, shared with anyone who clones it |
+
+The default is **`local`** — Claude Code only loads the entry when launched from the directory you ran the install from. Pick `user` for a global install (every project sees the vault); pick `project` to commit the entry to the repo so collaborators get it on `git pull`.
+
+#### Cookbook
+
+```bash
+# 1. Default — mint a scope-narrow hub JWT (vault:<vault>:read) via your
+#    operator token; write it into ~/.claude.json under projects[<cwd>]
+#    (local scope, this directory only). Requires:
+#      - ~/.parachute/operator.token (run `parachute auth rotate-operator` if missing)
+#      - PARACHUTE_HUB_ORIGIN set OR an active `parachute expose` session
+parachute-vault mcp-install --mint
+
+# 2. Global install — write the entry at top-level ~/.claude.json so
+#    Claude Code loads it from every project, every directory.
+parachute-vault mcp-install --install-scope user
+
+# 3. Project-level install — write ./.mcp.json (committed to the repo,
+#    shared with the team). Pair with --scope vault:write when the
+#    project actually mutates the vault.
+parachute-vault mcp-install --install-scope project --scope vault:write
+
+# 4. Paste an existing token — useful when you already have a pvt_* in hand
+#    or want to re-use a long-lived bearer from another machine. Skips the
+#    mint step entirely.
+parachute-vault mcp-install --token pvt_abc123...
+
+# 5. Self-hosted-without-hub — mint a vault-DB pvt_* token (the legacy
+#    path; preserved so deployments without a hub keep working). Prints a
+#    deprecation notice.
+parachute-vault mcp-install --legacy-pat
+```
+
+**Multi-vault.** `--vault <name>` targets a specific vault and writes the entry under `parachute-vault-<name>` so multiple vaults coexist. Without `--vault`, the singular `parachute-vault` slot is used and one install clobbers another — that's intentional for the common single-vault case.
+
+**Doctor.** `parachute-vault doctor` checks `~/.claude.json` (both top-level and `projects[<cwd>]`) and `./.mcp.json`, and reports which one holds the entry, plus port-match and reachability of the MCP URL.
+
 ## Data model
 
 ```