@openparachute/vault 0.6.0-rc.1 → 0.6.1

package/.parachute/module.json

@@ -6,10 +6,21 @@
   "port": 1940,
   "paths": ["/vault/default"],
   "health": "/vault/default/health",
-  "managementUrl": "/admin/",
-  "uiUrl": "/admin/",
+  "managementUrl": "admin/",
+  "uiUrl": "admin/",
+  "configUiUrl": "/vault/admin/",
+  "focus": "core",
+  "adminCapabilities": ["config", "credentials"],
   "startCmd": ["parachute-vault", "serve"],
   "scopes": {
     "defines": ["vault:read", "vault:write", "vault:admin"]
-  }
+  },
+  "events": [
+    { "key": "note.created", "title": "A note was created" },
+    { "key": "note.updated", "title": "A note was updated" },
+    { "key": "note.deleted", "title": "A note was deleted" }
+  ],
+  "actions": [
+    { "key": "note.create", "title": "Create a note", "inputSchema": {} }
+  ]
 }

package/README.md

@@ -99,7 +99,7 @@ The daemon binds `0.0.0.0:1940` (or whatever you set in `PORT`) and serves REST,
 
 `vault init` asks two explicit questions: (1) install vault as an MCP server in `~/.claude.json`? (2) also surface the access token so you can paste it into other MCP clients (Codex, Goose, OpenCode, Cursor, Zed, Cline), scripts, or `curl`? Both default yes. Pass `--mcp` / `--no-mcp` and `--token` / `--no-token` for non-interactive installs.
 
-If you said yes to (2), the hub-issued JWT is printed prominently at the end — it's the same token baked into `~/.claude.json` (if you also said yes to (1)). It's not stored anywhere retrievable — save it if you need it for `curl`, cron, or any other script. Lost it? Mint a fresh one with `parachute auth mint-token --scope vault:<name>:<verb>` (or rewire an MCP client with `parachute-vault mcp-install`, or use the admin SPA Tokens page). As of vault 0.6.0 (vault#282 Stage 2) vault no longer mints its own `pvt_*` tokens — minting is the hub's job.
+If you said yes to (2), the hub-issued JWT is printed prominently at the end — it's the same token baked into `~/.claude.json` (if you also said yes to (1)). It's not stored anywhere retrievable — save it if you need it for `curl`, cron, or any other script. Lost it? Mint a fresh one with `parachute auth mint-token --scope vault:<name>:<verb>` (or rewire an MCP client with `parachute-vault mcp-install`, or use the admin SPA Tokens page). As of vault 0.5.0 (vault#282 Stage 2) vault no longer mints its own `pvt_*` tokens — minting is the hub's job.
 
 ### OAuth lives on the hub
 
@@ -122,7 +122,7 @@ Two ways to authenticate — pick based on the client, not the deployment:
 | **OAuth 2.1 + PKCE (browser flow, via hub)** | Claude Desktop, Parachute Daily, any third-party MCP client set up interactively | Click "Add integration", enter the vault MCP URL, a browser opens to the **hub's** consent page, sign in with hub credentials, done — no token ever touches your clipboard |
 | **Bearer token (hub JWT)** | Claude Code (auto-wired by `vault init`), CLI scripts, cron jobs, any non-interactive caller | `curl -H "Authorization: Bearer <hub-jwt>"` — mint one with `parachute-vault mcp-install` (MCP clients) or `parachute auth mint-token --scope vault:<name>:<verb>` (scripts) |
 
-As of 0.6.0 (vault#282 Stage 2) vault is a **pure hub resource-server**: both paths use a hub-signed JWT that vault validates against the hub's JWKS. (The OAuth path is the interactive browser handshake; the bearer path mints the same kind of JWT non-interactively.) The old vault-local `pvt_*` opaque token was dropped — vault no longer mints or accepts it. The server-wide `VAULT_AUTH_TOKEN` operator bearer remains for the no-granular-auth / cross-container path.
+As of 0.5.0 (vault#282 Stage 2) vault is a **pure hub resource-server**: both paths use a hub-signed JWT that vault validates against the hub's JWKS. (The OAuth path is the interactive browser handshake; the bearer path mints the same kind of JWT non-interactively.) The old vault-local `pvt_*` opaque token was dropped — vault no longer mints or accepts it. The server-wide `VAULT_AUTH_TOKEN` operator bearer remains for the no-granular-auth / cross-container path.
 
 ### Claude Code
 
@@ -219,7 +219,7 @@ parachute-vault 2fa backup-codes           # regenerate backup codes
 # Tokens — vault#282 Stage 2: vault no longer mints its own tokens. Mint a
 # hub JWT with `parachute-vault mcp-install` (MCP clients) or
 # `parachute auth mint-token --scope vault:<name>:<verb>` (scripts).
-parachute-vault tokens                     # list any vestigial pre-0.6.0 token rows (all vaults)
+parachute-vault tokens                     # list any vestigial pre-0.5.0 token rows (all vaults)
 parachute-vault tokens revoke <token-id>   # revoke a vestigial row (default vault; add --vault to target)
 
 # Obsidian
@@ -233,6 +233,14 @@ 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)
+# Env vars live in ~/.parachute/vault/.env. Notable ones:
+#   PORT                          — server port (default 1940)
+#   PARACHUTE_GITHUB_CLIENT_ID +
+#   PARACHUTE_GITHUB_APP_SLUG     — bring-your-own GitHub App for the mirror
+#                                   "Back up to GitHub" flow (defaults to the
+#                                   shared Parachute app). Set BOTH or NEITHER:
+#                                   the pair must name the same app — mixing
+#                                   apps breaks the install probe.
 
 # Server
 parachute-vault serve                      # run the server in the foreground (no daemon)
@@ -522,6 +530,23 @@ curl -H "Authorization: Bearer $VAULT_TOKEN" \
 
 Caller-tunable preview length is a future enhancement — file an issue if 120 chars isn't enough.
 
+### Read a large note in chunks (content range)
+
+A 100KB+ transcript won't fit in one MCP response. Pass `content_offset` / `content_length` (UTF-8 bytes) for a bounded read — the response carries the slice plus `content_total_length` and `content_next_offset` (`null` when complete). Loop, feeding `content_next_offset` back in as `content_offset`; concatenating the slices reconstructs the content byte-for-byte. Slices end on a codepoint boundary within the budget (never over `content_length`, at most 3 bytes under).
+
+```bash
+curl -H "Authorization: Bearer $VAULT_TOKEN" \
+  "http://localhost:1940/vault/default/api/notes/Meetings%2F2026-06-09?content_offset=0&content_length=65536"
+# → { ..., "content": "<first ≤64KB>", "content_total_length": 118034, "content_next_offset": 65530 }
+```
+
+```jsonc
+// MCP — same params on query-notes; works per-note on lists with include_content: true
+{ "name": "query-notes", "arguments": { "id": "Meetings/2026-06-09", "content_offset": 0, "content_length": 65536 } }
+```
+
+Range params require content in the response — with `include_content=false` (or a list query left on its lean default) they error rather than silently no-op. Full semantics in [docs/HTTP_API.md](./docs/HTTP_API.md) ("Content range — bounded reads for large notes").
+
 ### 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.
@@ -531,7 +556,7 @@ The SSG / sync pattern. Two equivalent forms — bracket-style is canonical goin
 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)
+# Flat form (DEPRECATED in 0.4.3; planned removal in a later 0.x 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"
 ```
@@ -704,13 +729,13 @@ For wiring up an AI client (Claude Code, Claude Desktop, Parachute Daily), see [
 
 ### Passing the key
 
-As of 0.6.0 (vault#282 Stage 2) vault accepts these bearers at every authenticated endpoint:
+As of 0.5.0 (vault#282 Stage 2) vault accepts these bearers at every authenticated endpoint:
 
 - **Hub-issued JWT** (`eyJ...`) — the user-credential path; what OAuth issues and what `parachute-vault mcp-install` / `parachute auth mint-token` produce. Audience-bound to `vault.<name>`, scope-narrowed (`vault:<name>:<verb>`).
 - **`VAULT_AUTH_TOKEN`** — the server-wide operator bearer (env var; full-admin against any vault on the server).
 - **`pvk_...`** — legacy global API keys from `config.yaml` / per-vault `vault.yaml` (still honored for existing deployments).
 
-The old vault-local `pvt_*` opaque token was **dropped at 0.6.0** — vault no longer mints or accepts it.
+The old vault-local `pvt_*` opaque token was **dropped at 0.5.0** — vault no longer mints or accepts it.
 
 ```bash
 # Header (preferred)
@@ -742,7 +767,7 @@ Two permission levels carry through the JWT scope verb:
 | `read` | Query, list, find-path, vault-info only |
 
 `parachute-vault tokens list` / `tokens revoke` remain only to clean up any
-vestigial pre-0.6.0 rows. Legacy `pvk_...` keys from config.yaml still work at
+vestigial pre-0.5.0 rows. Legacy `pvk_...` keys from config.yaml still work at
 runtime; the `vault keys` CLI commands were removed long ago.
 
 ### Public endpoints

package/core/src/content-range.test.ts

@@ -0,0 +1,374 @@
+/**
+ * Content range / pagination tests — bounded reads for large notes.
+ *
+ * Three layers:
+ *   1. Unit tests of the parse + slice helpers (boundary cases: offset
+ *      past end, sub-minimum budget, multi-byte codepoints at the cut).
+ *   2. Property test of the reassembly invariant: walking a string from
+ *      offset 0 via `content_next_offset` and concatenating the slices is
+ *      byte-identical to the full content, for arbitrary unicode content
+ *      and budgets — and no slice ever exceeds the byte budget.
+ *   3. MCP face (`query-notes` execute): single + list shapes, the
+ *      include_content interaction, and the no-params regression
+ *      (response shape byte-identical to pre-pagination behavior).
+ *
+ * The REST face is exercised in src/content-range-routes.test.ts.
+ */
+
+import { describe, it, expect, beforeEach } from "bun:test";
+import { Database } from "bun:sqlite";
+import { SqliteStore } from "./store.js";
+import { generateMcpTools } from "./mcp.js";
+import {
+  parseContentRange,
+  sliceContentRange,
+  applyContentRange,
+  MIN_CONTENT_LENGTH,
+} from "./content-range.js";
+
+// ---------------------------------------------------------------------------
+// 1. parseContentRange
+// ---------------------------------------------------------------------------
+
+describe("parseContentRange", () => {
+  it("returns null when neither param is present (range mode off)", () => {
+    expect(parseContentRange(undefined, undefined)).toBeNull();
+    expect(parseContentRange(null, null)).toBeNull();
+  });
+
+  it("treats empty strings as absent (REST `?content_offset=`)", () => {
+    expect(parseContentRange("", "")).toBeNull();
+  });
+
+  it("offset only → length omitted (read to end)", () => {
+    expect(parseContentRange(10, undefined)).toEqual({ offset: 10 });
+  });
+
+  it("length only → offset defaults to 0", () => {
+    expect(parseContentRange(undefined, 64)).toEqual({ offset: 0, length: 64 });
+  });
+
+  it("accepts decimal strings (REST query params)", () => {
+    expect(parseContentRange("5", "1024")).toEqual({ offset: 5, length: 1024 });
+  });
+
+  it("rejects negative offset", () => {
+    expect(() => parseContentRange(-1, undefined)).toThrow(/content_offset/);
+  });
+
+  it("rejects non-integer values", () => {
+    expect(() => parseContentRange(1.5, undefined)).toThrow(/content_offset/);
+    expect(() => parseContentRange(undefined, 7.2)).toThrow(/content_length/);
+    expect(() => parseContentRange("abc", undefined)).toThrow(/content_offset/);
+    expect(() => parseContentRange(undefined, "-4")).toThrow(/content_length/);
+  });
+
+  it(`rejects zero / negative / sub-minimum budget (< ${MIN_CONTENT_LENGTH})`, () => {
+    expect(() => parseContentRange(undefined, 0)).toThrow(/content_length/);
+    expect(() => parseContentRange(undefined, -8)).toThrow(/content_length/);
+    expect(() => parseContentRange(undefined, MIN_CONTENT_LENGTH - 1)).toThrow(/content_length/);
+    // The minimum itself is fine.
+    expect(parseContentRange(undefined, MIN_CONTENT_LENGTH)).toEqual({
+      offset: 0,
+      length: MIN_CONTENT_LENGTH,
+    });
+  });
+
+  it("throws QueryError with INVALID_QUERY code", () => {
+    try {
+      parseContentRange(undefined, 2);
+      throw new Error("should have thrown");
+    } catch (e: any) {
+      expect(e.name).toBe("QueryError");
+      expect(e.code).toBe("INVALID_QUERY");
+    }
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 2. sliceContentRange — boundary cases
+// ---------------------------------------------------------------------------
+
+describe("sliceContentRange", () => {
+  it("plain ASCII window", () => {
+    const r = sliceContentRange("hello world", { offset: 0, length: 5 });
+    expect(r.content).toBe("hello");
+    expect(r.content_offset).toBe(0);
+    expect(r.content_total_length).toBe(11);
+    expect(r.content_next_offset).toBe(5);
+  });
+
+  it("continuation window reaches the end → next_offset null", () => {
+    const r = sliceContentRange("hello world", { offset: 5, length: 100 });
+    expect(r.content).toBe(" world");
+    expect(r.content_next_offset).toBeNull();
+  });
+
+  it("offset with no length reads to the end", () => {
+    const r = sliceContentRange("hello world", { offset: 6 });
+    expect(r.content).toBe("world");
+    expect(r.content_total_length).toBe(11);
+    expect(r.content_next_offset).toBeNull();
+  });
+
+  it("offset exactly at end → empty slice, complete", () => {
+    const r = sliceContentRange("abc", { offset: 3 });
+    expect(r.content).toBe("");
+    expect(r.content_offset).toBe(3);
+    expect(r.content_total_length).toBe(3);
+    expect(r.content_next_offset).toBeNull();
+  });
+
+  it("offset past end → empty slice, complete (graceful loop termination)", () => {
+    const r = sliceContentRange("abc", { offset: 999, length: 16 });
+    expect(r.content).toBe("");
+    expect(r.content_offset).toBe(3); // clamped to total
+    expect(r.content_total_length).toBe(3);
+    expect(r.content_next_offset).toBeNull();
+  });
+
+  it("empty content → empty slice, total 0", () => {
+    const r = sliceContentRange("", { offset: 0, length: 16 });
+    expect(r.content).toBe("");
+    expect(r.content_total_length).toBe(0);
+    expect(r.content_next_offset).toBeNull();
+  });
+
+  it("budget cutting mid-codepoint backs off to the boundary (never over budget)", () => {
+    // "ab😀cd" — bytes: a=0, b=1, 😀=2..5 (4 bytes), c=6, d=7; total 8.
+    const s = "ab\u{1F600}cd";
+    expect(Buffer.byteLength(s, "utf8")).toBe(8);
+
+    // Budget 5 would cut mid-emoji → slice backs off to byte 2.
+    const r1 = sliceContentRange(s, { offset: 0, length: 5 });
+    expect(r1.content).toBe("ab");
+    expect(Buffer.byteLength(r1.content, "utf8")).toBeLessThanOrEqual(5);
+    expect(r1.content_next_offset).toBe(2);
+
+    // Next window picks up the whole emoji.
+    const r2 = sliceContentRange(s, { offset: 2, length: 4 });
+    expect(r2.content).toBe("\u{1F600}");
+    expect(r2.content_next_offset).toBe(6);
+
+    // Final window.
+    const r3 = sliceContentRange(s, { offset: 6, length: 4 });
+    expect(r3.content).toBe("cd");
+    expect(r3.content_next_offset).toBeNull();
+  });
+
+  it("offset landing mid-codepoint aligns DOWN (no bytes skipped) and echoes the effective offset", () => {
+    const s = "ab\u{1F600}cd"; // emoji occupies bytes 2..5
+    const r = sliceContentRange(s, { offset: 4, length: 8 });
+    expect(r.content_offset).toBe(2); // aligned down to the emoji's lead byte
+    expect(r.content).toBe("\u{1F600}cd");
+    expect(r.content_next_offset).toBeNull();
+  });
+
+  it("minimum budget always makes progress, even on a 4-byte codepoint", () => {
+    const s = "\u{1F600}\u{1F601}"; // two 4-byte emoji
+    const r = sliceContentRange(s, { offset: 0, length: MIN_CONTENT_LENGTH });
+    expect(r.content).toBe("\u{1F600}");
+    expect(r.content_next_offset).toBe(4);
+  });
+
+  it("applyContentRange mutates the shaped result in place", () => {
+    const result: any = { id: "n1", content: "hello world", tags: ["x"] };
+    applyContentRange(result, { offset: 0, length: 5 });
+    expect(result.content).toBe("hello");
+    expect(result.content_offset).toBe(0);
+    expect(result.content_total_length).toBe(11);
+    expect(result.content_next_offset).toBe(5);
+    expect(result.tags).toEqual(["x"]); // untouched
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 2b. Property test — reassembly invariant
+// ---------------------------------------------------------------------------
+
+/** Deterministic PRNG (mulberry32) so failures reproduce. */
+function mulberry32(seed: number): () => number {
+  let a = seed >>> 0;
+  return () => {
+    a |= 0;
+    a = (a + 0x6d2b79f5) | 0;
+    let t = Math.imul(a ^ (a >>> 15), 1 | a);
+    t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+describe("content range — reassembly property", () => {
+  // Mixed-width pool: 1-byte ASCII, 2-byte (é, ψ), 3-byte (你, ‱), 4-byte
+  // (😀, 𝄞) — plus whitespace, so windows land on every codepoint width.
+  const POOL = ["a", "Z", "9", " ", "\n", "é", "ψ", "你", "‱", "\u{1F600}", "\u{1D11E}"];
+
+  it("concatenating all slices is byte-identical to the full content; no slice exceeds the budget", () => {
+    const rand = mulberry32(0xc0ffee);
+    for (let iter = 0; iter < 60; iter++) {
+      const charCount = Math.floor(rand() * 120); // includes 0 (empty content)
+      let content = "";
+      for (let i = 0; i < charCount; i++) {
+        content += POOL[Math.floor(rand() * POOL.length)]!;
+      }
+      const budget = MIN_CONTENT_LENGTH + Math.floor(rand() * 13); // 4..16 bytes
+      const totalBytes = Buffer.byteLength(content, "utf8");
+
+      let offset = 0;
+      let assembled = "";
+      let lastTotal: number | null = null;
+      // Hard ceiling on iterations: every window must advance by >= 1 byte.
+      for (let step = 0; step <= totalBytes + 2; step++) {
+        const slice = sliceContentRange(content, { offset, length: budget });
+        expect(Buffer.byteLength(slice.content, "utf8")).toBeLessThanOrEqual(budget);
+        expect(slice.content_total_length).toBe(totalBytes);
+        lastTotal = slice.content_total_length;
+        assembled += slice.content;
+        if (slice.content_next_offset === null) break;
+        // Progress guarantee — next offset strictly advances.
+        expect(slice.content_next_offset).toBeGreaterThan(offset);
+        offset = slice.content_next_offset;
+      }
+
+      expect(assembled).toBe(content);
+      expect(Buffer.from(assembled, "utf8").equals(Buffer.from(content, "utf8"))).toBe(true);
+      expect(lastTotal).toBe(totalBytes);
+    }
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 3. MCP face — query-notes
+// ---------------------------------------------------------------------------
+
+describe("MCP query-notes — content range", () => {
+  let db: Database;
+  let store: SqliteStore;
+
+  beforeEach(() => {
+    db = new Database(":memory:");
+    store = new SqliteStore(db);
+  });
+
+  function queryTool() {
+    const tools = generateMcpTools(store);
+    return tools.find((t) => t.name === "query-notes")!;
+  }
+
+  it("single note: paged read loop reassembles the full content", async () => {
+    // Mixed-width content so windows hit multi-byte boundaries.
+    const content = ("section \u{1F600} 你好 " .repeat(40)).trim();
+    const note = await store.createNote(content);
+    const query = queryTool();
+
+    let offset = 0;
+    let assembled = "";
+    for (;;) {
+      const r: any = await query.execute({ id: note.id, content_offset: offset, content_length: 64 });
+      expect(r.content_total_length).toBe(Buffer.byteLength(content, "utf8"));
+      assembled += r.content;
+      if (r.content_next_offset === null) break;
+      offset = r.content_next_offset;
+    }
+    expect(assembled).toBe(content);
+  });
+
+  it("single note: response carries the range fields and the slice", async () => {
+    const note = await store.createNote("0123456789");
+    const r: any = await queryTool().execute({ id: note.id, content_length: 4 });
+    expect(r.content).toBe("0123");
+    expect(r.content_offset).toBe(0);
+    expect(r.content_total_length).toBe(10);
+    expect(r.content_next_offset).toBe(4);
+    expect(r.id).toBe(note.id); // rest of the note shape intact
+  });
+
+  it("single note, no range params → byte-identical to today (regression)", async () => {
+    const note = await store.createNote("full body here");
+    const r: any = await queryTool().execute({ id: note.id });
+    expect(r.content).toBe("full body here");
+    expect("content_total_length" in r).toBe(false);
+    expect("content_next_offset" in r).toBe(false);
+    expect("content_offset" in r).toBe(false);
+  });
+
+  it("single note: content_offset past end → empty slice, complete", async () => {
+    const note = await store.createNote("abc");
+    const r: any = await queryTool().execute({ id: note.id, content_offset: 999 });
+    expect(r.content).toBe("");
+    expect(r.content_total_length).toBe(3);
+    expect(r.content_next_offset).toBeNull();
+  });
+
+  it("single note: include_content=false + range params → loud error", async () => {
+    const note = await store.createNote("abc");
+    expect(
+      queryTool().execute({ id: note.id, include_content: false, content_length: 8 }),
+    ).rejects.toThrow(/include_content/);
+  });
+
+  it("rejects sub-minimum / invalid budgets before any query work", async () => {
+    const note = await store.createNote("abc");
+    expect(queryTool().execute({ id: note.id, content_length: 0 })).rejects.toThrow(/content_length/);
+    expect(queryTool().execute({ id: note.id, content_length: -5 })).rejects.toThrow(/content_length/);
+    expect(queryTool().execute({ id: note.id, content_length: 2 })).rejects.toThrow(/content_length/);
+    expect(queryTool().execute({ id: note.id, content_offset: -1 })).rejects.toThrow(/content_offset/);
+  });
+
+  it("list query: include_content=true applies the window per note", async () => {
+    await store.createNote("alpha alpha alpha", { tags: ["big"] });
+    await store.createNote("beta beta beta beta", { tags: ["big"] });
+    const out: any[] = (await queryTool().execute({
+      tag: "big",
+      include_content: true,
+      content_length: 5,
+    })) as any[];
+    expect(out.length).toBe(2);
+    for (const n of out) {
+      expect(Buffer.byteLength(n.content, "utf8")).toBeLessThanOrEqual(5);
+      expect(typeof n.content_total_length).toBe("number");
+      expect(n.content_next_offset).toBe(5);
+    }
+  });
+
+  it("list query: lean default (no include_content) + range params → loud error", async () => {
+    await store.createNote("alpha", { tags: ["big"] });
+    expect(queryTool().execute({ tag: "big", content_length: 8 })).rejects.toThrow(
+      /include_content/,
+    );
+  });
+
+  it("list query, no range params → no range fields injected (regression)", async () => {
+    await store.createNote("alpha", { tags: ["big"] });
+    const out: any[] = (await queryTool().execute({ tag: "big", include_content: true })) as any[];
+    expect(out.length).toBe(1);
+    expect("content_total_length" in out[0]).toBe(false);
+    expect("content_next_offset" in out[0]).toBe(false);
+  });
+
+  it("expand_links: the range applies to the EXPANDED content", async () => {
+    await store.createNote("inlined body of B", { path: "B" });
+    const a = await store.createNote("A says: [[B]]", { path: "A" });
+    const query = queryTool();
+
+    const unpaged: any = await query.execute({ id: a.id, expand_links: true });
+    const paged: any = await query.execute({
+      id: a.id,
+      expand_links: true,
+      content_offset: 0,
+      content_length: 100000,
+    });
+    expect(paged.content).toBe(unpaged.content);
+    expect(paged.content_total_length).toBe(Buffer.byteLength(unpaged.content, "utf8"));
+    expect(paged.content_next_offset).toBeNull();
+  });
+
+  it("query-notes schema advertises the params (MCP discovery)", () => {
+    const query = queryTool();
+    const props = (query.inputSchema as any).properties;
+    expect(props.content_offset).toBeDefined();
+    expect(props.content_length).toBeDefined();
+    expect(query.description).toContain("content_offset");
+    expect(query.description).toContain("content_next_offset");
+  });
+});