@openparachute/vault 0.7.3-rc.4 → 0.7.3-rc.6

package/core/src/display-title.test.ts

@@ -0,0 +1,149 @@
+/**
+ * Title axis (ratified 2026-07-17): a note's title IS its first line —
+ * derived from content, never stored. This file covers:
+ *   - `computeDisplayTitle` derivation (first non-empty line, heading
+ *     markers stripped, truncation, null-on-empty);
+ *   - `displayTitle` presence on the lean `NoteIndex` shape, both via the
+ *     MCP `query-notes` list path and the REST `GET /notes` list path.
+ *
+ * The search title-BOOST (ranking notes whose first line matches query
+ * terms above the rest) lives in `search-title-boost.test.ts` — a
+ * different concern (ranking) from derivation (this file).
+ */
+import { describe, it, expect, beforeEach } from "bun:test";
+import { Database } from "bun:sqlite";
+import { SqliteStore } from "./store.js";
+import { generateMcpTools } from "./mcp.js";
+import { computeDisplayTitle, toNoteIndex, DISPLAY_TITLE_MAX_LEN } from "./notes.js";
+import type { Note } from "./types.js";
+
+describe("computeDisplayTitle", () => {
+  it("returns the first line when content is a single line", () => {
+    expect(computeDisplayTitle("Grocery List")).toBe("Grocery List");
+  });
+
+  it("returns the first NON-EMPTY line, skipping leading blank lines", () => {
+    expect(computeDisplayTitle("\n\n  \nReal Title\nbody text")).toBe("Real Title");
+  });
+
+  it("strips a leading markdown heading marker + its whitespace", () => {
+    expect(computeDisplayTitle("# Grocery List\nmilk, eggs")).toBe("Grocery List");
+    expect(computeDisplayTitle("## Section Two\nbody")).toBe("Section Two");
+    expect(computeDisplayTitle("###### h6\nbody")).toBe("h6");
+  });
+
+  it("strips a heading marker with no space after it", () => {
+    expect(computeDisplayTitle("###Title\nbody")).toBe("Title");
+  });
+
+  it("treats a heading-marker-only line as blank and moves to the next line", () => {
+    expect(computeDisplayTitle("##\nReal Title")).toBe("Real Title");
+  });
+
+  it("does not strip markers past the first six (never a valid heading)", () => {
+    // 7 leading `#`s: the regex only matches 1-6, so the 7th `#` survives
+    // as ordinary content.
+    expect(computeDisplayTitle("####### Title")).toBe("# Title");
+  });
+
+  it("returns null for empty content", () => {
+    expect(computeDisplayTitle("")).toBeNull();
+  });
+
+  it("returns null for null/undefined content", () => {
+    expect(computeDisplayTitle(null)).toBeNull();
+    expect(computeDisplayTitle(undefined)).toBeNull();
+  });
+
+  it("returns null when content is whitespace-only", () => {
+    expect(computeDisplayTitle("   \n\t\n   ")).toBeNull();
+  });
+
+  it("returns null when every line is a bare heading marker", () => {
+    expect(computeDisplayTitle("#\n##\n### ")).toBeNull();
+  });
+
+  it("truncates to DISPLAY_TITLE_MAX_LEN code points", () => {
+    const longTitle = "a".repeat(200);
+    const result = computeDisplayTitle(longTitle)!;
+    expect(result.length).toBe(DISPLAY_TITLE_MAX_LEN);
+    expect(result).toBe("a".repeat(DISPLAY_TITLE_MAX_LEN));
+  });
+
+  it("does not truncate a title at or under the limit", () => {
+    const exact = "a".repeat(DISPLAY_TITLE_MAX_LEN);
+    expect(computeDisplayTitle(exact)).toBe(exact);
+    const short = "short title";
+    expect(computeDisplayTitle(short)).toBe(short);
+  });
+
+  it("truncates by Unicode code point, not UTF-16 code unit (no split surrogate pairs)", () => {
+    // Astral-plane emoji are 2 UTF-16 code units each but 1 code point.
+    const emojiTitle = "😀".repeat(150);
+    const result = computeDisplayTitle(emojiTitle)!;
+    expect(Array.from(result).length).toBe(DISPLAY_TITLE_MAX_LEN);
+  });
+});
+
+describe("toNoteIndex — displayTitle wiring", () => {
+  const baseNote: Note = {
+    id: "n1",
+    content: "# Real Title\nbody",
+    createdAt: new Date().toISOString(),
+    tags: [],
+    metadata: {},
+  };
+
+  it("carries the computed display title onto the lean shape", () => {
+    const index = toNoteIndex(baseNote);
+    expect(index.displayTitle).toBe("Real Title");
+  });
+
+  it("is null when content is empty", () => {
+    const index = toNoteIndex({ ...baseNote, content: "" });
+    expect(index.displayTitle).toBeNull();
+  });
+
+  it("is null when content is missing entirely (defensive — matches preview's ?? \"\" fallback)", () => {
+    const { content: _drop, ...rest } = baseNote;
+    const index = toNoteIndex(rest as Note);
+    expect(index.displayTitle).toBeNull();
+  });
+});
+
+let store: SqliteStore;
+let db: Database;
+
+beforeEach(() => {
+  db = new Database(":memory:");
+  store = new SqliteStore(db);
+});
+
+describe("displayTitle — list-shape presence (MCP)", () => {
+  it("query-notes list mode (include_content default false) carries displayTitle", async () => {
+    await store.createNote("# Meeting Notes\nagenda: budget", { path: "a" });
+    const tools = generateMcpTools(store);
+    const queryNotes = tools.find((t) => t.name === "query-notes")!;
+    const result = await queryNotes.execute({}) as any[];
+    expect(result).toHaveLength(1);
+    expect(result[0].displayTitle).toBe("Meeting Notes");
+    expect(result[0].content).toBeUndefined();
+  });
+
+  it("query-notes include_content=true does NOT carry displayTitle (full Note shape, unchanged)", async () => {
+    await store.createNote("# Meeting Notes\nagenda: budget", { path: "a" });
+    const tools = generateMcpTools(store);
+    const queryNotes = tools.find((t) => t.name === "query-notes")!;
+    const result = await queryNotes.execute({ include_content: true }) as any[];
+    expect(result[0].content).toBeTruthy();
+    expect(result[0].displayTitle).toBeUndefined();
+  });
+
+  it("displayTitle is null on the lean shape for an empty note", async () => {
+    await store.createNote("", { path: "empty" });
+    const tools = generateMcpTools(store);
+    const queryNotes = tools.find((t) => t.name === "query-notes")!;
+    const result = await queryNotes.execute({}) as any[];
+    expect(result[0].displayTitle).toBeNull();
+  });
+});

package/core/src/mcp.ts

@@ -1619,7 +1619,7 @@ A note's response carries \`existed\` (true/false) whenever ITS \`if_exists\` wa
 - For batch: pass a \`notes\` array, each with an \`id\` field.
 - **Optimistic concurrency is required by default.** Pass \`if_updated_at\` with the \`updated_at\` value you last read — the update is rejected with a conflict error if the note has changed since. Re-read, reconcile, and retry. To skip the safety check (e.g. bulk migration), pass \`force: true\` instead; the update then runs unconditionally. \`force\` only waives the *requirement to supply* \`if_updated_at\` — if you pass both, the precondition you supplied still applies and a mismatch returns a conflict error. \`append\` / \`prepend\` only updates are exempt from the precondition (no-conflict-by-design). **Batch default (vault#554):** a top-level \`force\` and/or \`if_updated_at\` alongside a \`notes\` array applies as the DEFAULT for every item that doesn't set its own — e.g. \`{force: true, notes: [{id: "a", content: "..."}, {id: "b", content: "...", if_updated_at: "..."}]}\` forces item "a" but still enforces the precondition on item "b" (its own \`if_updated_at\` wins). Per-item values always take precedence over the top-level default.
 - **Idempotent upsert via \`if_missing: "create"\`** — when the note doesn't exist, create it from this same payload (content/path/tags/metadata become the create fields; OC precondition skipped — nothing to conflict with). Response carries \`created: true\`. Useful for nightly sync loops that don't know ahead of time whether the note exists. Default \`"fail"\` (current behavior — missing note errors). See vault#309.
-- \`include_content\` (default \`true\`) — set \`false\` to receive a lean index shape (\`id\`, \`path\`, \`createdAt\`, \`updatedAt\`, \`createdBy\`, \`createdVia\`, \`lastUpdatedBy\`, \`lastUpdatedVia\`, \`tags\`, \`metadata\`, \`byteSize\`, \`preview\`) instead of full content. Useful for agents making frequent small edits to large notes (e.g. via \`append\` or \`content_edit\`) where re-receiving the body is the dominant cost. \`validation_status\` is preserved on the lean shape when present.
+- \`include_content\` (default \`true\`) — set \`false\` to receive a lean index shape (\`id\`, \`path\`, \`createdAt\`, \`updatedAt\`, \`createdBy\`, \`createdVia\`, \`lastUpdatedBy\`, \`lastUpdatedVia\`, \`tags\`, \`metadata\`, \`byteSize\`, \`preview\`, \`displayTitle\`) instead of full content. Useful for agents making frequent small edits to large notes (e.g. via \`append\` or \`content_edit\`) where re-receiving the body is the dominant cost. \`validation_status\` is preserved on the lean shape when present. \`displayTitle\` is the note's first non-empty content line (heading markers stripped, ~120 chars max), \`null\` when content is empty — never stored, computed fresh from content already in hand.
 
 Write-attribution (vault#298): every result carries \`createdBy\`/\`createdVia\` (the principal + interface of the first write) and \`lastUpdatedBy\`/\`lastUpdatedVia\` (the most recent write). NULL on notes written before attribution existed. Filter on them with \`created_by\`/\`last_updated_by\`/\`created_via\`/\`last_updated_via\`.`,
       inputSchema: {
@@ -1693,7 +1693,7 @@ Write-attribution (vault#298): every result carries \`createdBy\`/\`createdVia\`
           },
           include_content: {
             type: "boolean",
-            description: "Response shape opt-out. Default `true` (returns the full Note with content). Set `false` to receive the lean index shape (drops `content`, adds `byteSize` and a whitespace-collapsed `preview`). `validation_status` is preserved on the lean shape when present. Applies uniformly to single and batch responses.",
+            description: "Response shape opt-out. Default `true` (returns the full Note with content). Set `false` to receive the lean index shape (drops `content`, adds `byteSize`, a whitespace-collapsed `preview`, and a computed `displayTitle`). `validation_status` is preserved on the lean shape when present. Applies uniformly to single and batch responses.",
           },
           include_links: {
             type: "boolean",

package/core/src/notes.ts

@@ -25,6 +25,7 @@ import { computeExpandedTagCounts, loadTagHierarchy, stripTagHash } from "./tag-
 import { chunkForInClause, IN_VIA_JSON_EACH, jsonEachParam } from "./sql-in.js";
 import {
   buildLiteralSearchQuery,
+  extractLiteralBoostTerms,
   SEARCH_WEIGHT_PATH,
   SEARCH_WEIGHT_CONTENT,
   type SearchMode,
@@ -1810,6 +1811,61 @@ function searchSyntaxError(rawQuery: string, err: unknown, mode: SearchMode): Qu
   });
 }
 
+/**
+ * Post-rank a search result page (title axis, ratified 2026-07-17) so
+ * notes whose display title (first line of content) contains EVERY boost
+ * term outrank the rest — a title-match tier ahead of a body-only-match
+ * tier. Stable partition: within a tier, the incoming order (FTS5
+ * relevance, or an explicit `sort`) is preserved untouched — two notes
+ * that both match, or both don't, keep their relative order.
+ *
+ * No-migration by design (see the search-seam note on `searchNotes`
+ * below): re-orders the already-fetched page in memory instead of adding
+ * a weighted title column to `notes_fts`, which would need a schema
+ * migration + backfill. `notes_fts`'s existing `SEARCH_WEIGHT_PATH` bm25
+ * weighting (above) already boosts by note PATH — a different axis from
+ * the ratified title model (title = first line of CONTENT, not path).
+ * This function is the one that boosts by the content-derived title.
+ */
+function boostTitleMatches(notes: Note[], terms: string[]): Note[] {
+  if (terms.length === 0) return notes;
+  return notes
+    .map((note, index) => ({ note, index, titleMatch: titleMatchesAllTerms(note.content, terms) }))
+    .sort((a, b) => {
+      if (a.titleMatch === b.titleMatch) return a.index - b.index; // stable
+      return a.titleMatch ? -1 : 1;
+    })
+    .map((x) => x.note);
+}
+
+function titleMatchesAllTerms(content: string | null | undefined, terms: string[]): boolean {
+  const title = computeDisplayTitle(content);
+  if (!title) return false;
+  const lower = title.toLowerCase();
+  return terms.every((t) => lower.includes(t));
+}
+
+/**
+ * Apply the title-boost post-rank to a fetched search page. Skipped
+ * whenever it would fight the caller's intent:
+ *   - an explicit `sort: "asc"|"desc"` means the caller wants chronological
+ *     order, not relevance re-ranking;
+ *   - `search_mode: "advanced"` text carries raw FTS5 syntax (boolean
+ *     operators, column filters, prefix `*`) — naively tokenizing it into
+ *     "terms" would misread operators as content (see
+ *     `extractLiteralBoostTerms`'s doc comment). Only literal-mode queries
+ *     (the default) get boosted today.
+ */
+function applySearchTitleBoost(
+  notes: Note[],
+  mode: SearchMode,
+  rawQuery: string,
+  sort: "asc" | "desc" | undefined,
+): Note[] {
+  if (sort !== undefined || mode !== "literal") return notes;
+  return boostTitleMatches(notes, extractLiteralBoostTerms(rawQuery));
+}
+
 export function searchNotes(
   db: Database,
   query: string,
@@ -1846,6 +1902,14 @@ export function searchNotes(
   // The weights are our own numeric constants (not user input) interpolated
   // directly — bm25()'s weight arguments are positional per-column
   // multipliers, not general SQL expressions callers can influence.
+  //
+  // NOTE: "title" here means the note's `path` — this predates the title
+  // axis (ratified 2026-07-17), under which a note's title is its first
+  // CONTENT line, not its path. `applySearchTitleBoost` (below) is the
+  // mechanism for THAT axis: a post-rank pass over the already-scored page,
+  // not a third FTS column. The two are complementary, not redundant — a
+  // note can have a matching path with a non-matching first line, or vice
+  // versa.
   const scoreExpr = `(-1.0 * bm25(notes_fts, ${SEARCH_WEIGHT_PATH}, ${SEARCH_WEIGHT_CONTENT}))`;
 
   // `sort` honored under search (vault#551 WS2A item 3): default stays FTS5
@@ -1886,7 +1950,7 @@ export function searchNotes(
         ORDER BY ${orderBy}
         LIMIT ?
       `).all(ftsQuery, ...searchTags, limit) as (NoteRow & { score: number })[];
-      return notesWithTags(db, rows, scoresById(rows));
+      return applySearchTitleBoost(notesWithTags(db, rows, scoresById(rows)), mode, query, opts?.sort);
     } catch (err) {
       // Surface EVERY FTS5 error structured, never a raw rethrow (vault#551):
       // advanced mode expects it (the caller passed raw syntax); literal
@@ -1908,7 +1972,7 @@ export function searchNotes(
       ORDER BY ${orderBy}
       LIMIT ?
     `).all(ftsQuery, limit) as (NoteRow & { score: number })[];
-    return notesWithTags(db, rows, scoresById(rows));
+    return applySearchTitleBoost(notesWithTags(db, rows, scoresById(rows)), mode, query, opts?.sort);
   } catch (err) {
     if (err instanceof QueryError) throw err;
     throw searchSyntaxError(query, err, mode);
@@ -2702,10 +2766,52 @@ export function mergeTags(
 /** Max code points in a NoteIndex preview. */
 export const NOTE_INDEX_PREVIEW_LEN = 120;
 
+/** Max code points in a computed `displayTitle` (title axis, ratified 2026-07-17). */
+export const DISPLAY_TITLE_MAX_LEN = 120;
+
+/**
+ * Derive a note's display title: the first non-empty line of `content`,
+ * with a leading markdown heading marker (`#` through `######`) and its
+ * following whitespace stripped, truncated to `DISPLAY_TITLE_MAX_LEN` code
+ * points. `null` when content has no non-empty line (empty or
+ * whitespace/heading-marker-only note).
+ *
+ * The ratified title model (2026-07-17): a note's title IS its first line
+ * — derived from content, NEVER stored as its own column. This function is
+ * the one place that derivation happens; callers (`toNoteIndex` below) call
+ * it fresh at read time. Timestamp-path formatting — what a surface shows
+ * in place of a `null` title — is deliberately NOT this function's job; it
+ * reports the honest content-derived value (or its absence) and leaves
+ * rendering to the caller.
+ */
+export function computeDisplayTitle(content: string | null | undefined): string | null {
+  if (!content) return null;
+  for (const rawLine of content.split("\n")) {
+    const stripped = rawLine.replace(/^#{1,6}\s*/, "").trim();
+    if (stripped === "") continue;
+    // Iterate by Unicode code points so we don't split surrogate pairs mid-character.
+    const codePoints = Array.from(stripped);
+    return codePoints.length > DISPLAY_TITLE_MAX_LEN
+      ? codePoints.slice(0, DISPLAY_TITLE_MAX_LEN).join("")
+      : stripped;
+  }
+  return null;
+}
+
 /**
  * Convert a full Note into its lean index shape:
- * drops `content`, adds `byteSize` and a whitespace-collapsed `preview`.
- * Shared between the `query-notes` MCP tool, HTTP /notes endpoints, and /graph.
+ * drops `content`, adds `byteSize`, a whitespace-collapsed `preview`, and a
+ * computed `displayTitle`. Shared between the `query-notes` MCP tool, HTTP
+ * /notes endpoints, and /graph.
+ *
+ * Perf note: `displayTitle` costs nothing extra here — every caller of this
+ * function already has the full `Note` (content included) in hand by the
+ * time it's called. `queryNotes`'s two-phase page fetch selects a narrow
+ * `id`-only column list for the ORDER BY/pagination phase, but the second
+ * phase (`fetchNotesByIdsOrdered`) always `SELECT *`s the page's full rows
+ * before `toNoteIndex` ever runs — same as `preview`/`byteSize` today. If a
+ * future lean-list path is added that genuinely avoids a content read, it
+ * must NOT call this function (or `toNoteIndex`) on a content-less row.
  */
 export function toNoteIndex(note: Note): NoteIndex {
   const content = note.content ?? "";
@@ -2732,6 +2838,7 @@ export function toNoteIndex(note: Note): NoteIndex {
     metadata: note.metadata,
     byteSize,
     preview,
+    displayTitle: computeDisplayTitle(note.content),
     ...(note.score !== undefined ? { score: note.score } : {}),
   };
 }

package/core/src/search-fts-v25.test.ts

@@ -132,7 +132,15 @@ describe("search — v24 → v25 migration (legacy vault upgrade)", () => {
     );
     insert.run(
       "legacy-1",
-      "a dedicated writeup mentioning propolis only once in passing text",
+      // Deliberately multi-line, with the "propolis" mention on a LATER
+      // line — this fixture isolates the PATH-weighted bm25 axis (below)
+      // from the separate content-title-boost axis (title axis, ratified
+      // 2026-07-17): that boost derives a note's "title" from its FIRST
+      // content line, and a single-line note IS its own title in full, so
+      // a one-line body mentioning "propolis" would (correctly, under the
+      // newer axis) count as a title match and confound this test's
+      // path-only signal. See `search-title-boost.test.ts` for that axis.
+      "Notes on foraging patterns\n\na dedicated writeup mentioning propolis only once in passing text",
       "beekeeping-notes",
       "2026-01-01T00:00:00.000Z",
       "2026-01-01T00:00:00.000Z",

package/core/src/search-query.test.ts

@@ -4,6 +4,7 @@ import {
   escapeFtsToken,
   buildLiteralSearchQuery,
   isValidSearchMode,
+  extractLiteralBoostTerms,
 } from "./search-query.js";
 
 describe("escapeFtsToken", () => {
@@ -147,3 +148,44 @@ describe("isValidSearchMode / SEARCH_MODES", () => {
     expect(isValidSearchMode(["literal"])).toBe(false);
   });
 });
+
+describe("extractLiteralBoostTerms (search title-boost input, title axis)", () => {
+  it("lowercases and whitespace-splits", () => {
+    expect(extractLiteralBoostTerms("Budget Review")).toEqual(["budget", "review"]);
+  });
+
+  it("collapses whitespace runs", () => {
+    expect(extractLiteralBoostTerms("widgets    gadgets")).toEqual(["widgets", "gadgets"]);
+  });
+
+  it("trims leading/trailing whitespace", () => {
+    expect(extractLiteralBoostTerms("  widgets  ")).toEqual(["widgets"]);
+  });
+
+  it("strips literal quote characters a caller typed, unlike buildLiteralSearchQuery", () => {
+    // buildLiteralSearchQuery treats a manually-typed `"` as ordinary
+    // content (escaped into the FTS phrase); the boost-term extractor
+    // strips it instead, since a title-string comparison shouldn't
+    // require the title to contain a literal quote mark.
+    expect(extractLiteralBoostTerms(`"eleven-day capping delay"`)).toEqual([
+      "eleven-day",
+      "capping",
+      "delay",
+    ]);
+  });
+
+  it("preserves punctuation that isn't a quote (hyphen, period, apostrophe)", () => {
+    expect(extractLiteralBoostTerms("eleven-day")).toEqual(["eleven-day"]);
+    expect(extractLiteralBoostTerms("18.6")).toEqual(["18.6"]);
+    expect(extractLiteralBoostTerms("didn't")).toEqual(["didn't"]);
+  });
+
+  it("returns an empty array for blank/whitespace-only input", () => {
+    expect(extractLiteralBoostTerms("")).toEqual([]);
+    expect(extractLiteralBoostTerms("   ")).toEqual([]);
+  });
+
+  it("sanitizes control characters as separators, matching buildLiteralSearchQuery", () => {
+    expect(extractLiteralBoostTerms("hello\x00world")).toEqual(["hello", "world"]);
+  });
+});

package/core/src/search-query.ts

@@ -153,3 +153,30 @@ export function buildLiteralSearchQuery(raw: string): LiteralSearchQuery {
   const tokens = cleaned.trim().split(/\s+/).filter(Boolean);
   return { query: tokens.map(escapeFtsToken).join(" "), isEmpty: false };
 }
+
+/**
+ * Extract lowercase whitespace-delimited terms from raw literal-mode search
+ * text, for the search title-boost post-rank (title axis, ratified
+ * 2026-07-17) — NOT used to build the FTS5 MATCH query itself (that's
+ * `buildLiteralSearchQuery`, above). Sanitizes control characters the same
+ * way, plus strips any literal `"` a caller typed (kept as ordinary content
+ * by `buildLiteralSearchQuery`, but a display-title substring check
+ * shouldn't require the title to contain a literal quote mark).
+ *
+ * This is a heuristic re-rank signal, not a second index — it deliberately
+ * does not attempt FTS5-tokenizer parity (stemming, unicode normalization).
+ * It only needs to answer "does the note's first line plausibly contain the
+ * query," not reproduce FTS5's match semantics exactly. Restricted to
+ * literal-mode callers by convention (see `core/src/notes.ts` `searchNotes`)
+ * — `search_mode: "advanced"` text carries FTS5 boolean/column/prefix
+ * operators (`AND`, `path:`, `foo*`) that would leak into the term list as
+ * false "content" if tokenized the same naive way.
+ */
+export function extractLiteralBoostTerms(raw: string): string[] {
+  const cleaned = raw.replace(CONTROL_CHARS, " ").toLowerCase();
+  return cleaned
+    .trim()
+    .split(/\s+/)
+    .map((t) => t.replace(/^"+|"+$/g, ""))
+    .filter(Boolean);
+}

package/core/src/search-title-boost.test.ts

@@ -0,0 +1,107 @@
+/**
+ * Search title-boost (title axis, ratified 2026-07-17): literal-mode
+ * search results whose `displayTitle` (first non-empty content line, NOT
+ * `path`) contains every query term are post-ranked ahead of body-only
+ * matches. No-migration — an in-memory re-rank of the already-fetched
+ * page, not a `notes_fts` schema change (see `applySearchTitleBoost` /
+ * `boostTitleMatches` in `notes.ts`).
+ *
+ * This is a DIFFERENT axis from the existing `path`-weighted bm25 ranking
+ * covered in `search-fts-v25.test.ts` — a note's title here is its first
+ * CONTENT line, not its `path`.
+ */
+import { describe, it, expect, beforeEach } from "bun:test";
+import { Database } from "bun:sqlite";
+import { SqliteStore } from "./store.js";
+
+let store: SqliteStore;
+let db: Database;
+
+beforeEach(() => {
+  db = new Database(":memory:");
+  store = new SqliteStore(db);
+});
+
+describe("search title-boost", () => {
+  it("ranks a first-line (title) match above a body-only match", async () => {
+    // Body-only match: "budget" appears only deep in the body, first line
+    // is unrelated.
+    await store.createNote(
+      "Weekly Standup\nlots of unrelated notes here, but somewhere we discuss the budget in passing",
+      { path: "standup-notes" },
+    );
+    // First-line (title) match: "Budget" is the first line itself.
+    await store.createNote("Budget Review\nQ3 numbers", { path: "budget-review" });
+
+    const hits = await store.searchNotes("budget");
+    expect(hits.length).toBeGreaterThanOrEqual(2);
+    expect(hits[0].path).toBe("budget-review");
+  });
+
+  it("requires ALL query terms to be present in the first line to boost (a partial title match doesn't qualify)", async () => {
+    // "budget" is in the title but "review" is only in the body — a
+    // PARTIAL title match, which stays in the body-only tier.
+    await store.createNote("Budget notes\nsee the quarterly review for details", { path: "partial" });
+    // Both "budget" and "review" are in the title — a FULL title match.
+    await store.createNote("Budget Review\nQ3 numbers", { path: "full-match" });
+
+    const hits = await store.searchNotes("budget review");
+    expect(hits.map((n) => n.path)).toEqual(["full-match", "partial"]);
+  });
+
+  it("ties (both notes in the same tier) keep the existing relevance order", async () => {
+    // Two title-matching notes plus one body-only note. Comparing literal
+    // mode (boosted) against advanced mode with the same plain-word query
+    // (identical FTS5 syntax, so identical underlying bm25 order, but no
+    // boost pass) isolates the boost's effect: within the title-match
+    // tier, the boost must preserve whatever relative order the
+    // underlying relevance ranking already gave — a stable sort, not a
+    // fresh comparator that could reshuffle ties.
+    await store.createNote("Project Widget\nfirst, mentions widget again for relevance", { path: "w1" });
+    await store.createNote("Project Widget\nsecond", { path: "w2" });
+    await store.createNote("Unrelated\nbody-only mention of widget project", { path: "body-only" });
+
+    const boosted = await store.searchNotes("widget project");
+    const rawOrder = await store.searchNotes("widget project", { mode: "advanced" });
+
+    const titleTierBoosted = boosted.map((n) => n.path).filter((p) => p === "w1" || p === "w2");
+    const titleTierRaw = rawOrder.map((n) => n.path).filter((p) => p === "w1" || p === "w2");
+    expect(titleTierBoosted).toEqual(titleTierRaw);
+    // The title-match tier precedes the body-only note in the boosted result.
+    expect(boosted.map((n) => n.path).indexOf("body-only")).toBeGreaterThan(
+      Math.max(...["w1", "w2"].map((p) => boosted.map((n) => n.path).indexOf(p))),
+    );
+  });
+
+  it("does not disturb ordering when an explicit sort is requested", async () => {
+    await store.createNote("Zebra body-only mention of gadget", { path: "z" });
+    await store.createNote("Gadget Launch\nfirst line title match", { path: "a" });
+
+    const asc = await store.searchNotes("gadget", { sort: "asc" });
+    // created_at ASC means "z" (created first) comes before "a" — the
+    // title-boost must NOT override an explicit sort.
+    expect(asc.map((n) => n.path)).toEqual(["z", "a"]);
+  });
+
+  it("does not apply the boost under search_mode: advanced (raw FTS5 syntax, not naively tokenizable)", async () => {
+    await store.createNote("Body only mentions gadget in passing text here", { path: "body-only" });
+    await store.createNote("Gadget\nfirst line title match", { path: "title-match" });
+
+    const advanced = await store.searchNotes("gadget", { mode: "advanced" });
+    const literal = await store.searchNotes("gadget");
+
+    // Literal mode boosts the title match to the front.
+    expect(literal[0].path).toBe("title-match");
+    // Advanced mode is unaffected by the boost — order comes from bm25
+    // relevance alone (title-match still likely ranks first via the
+    // EXISTING path-weighted bm25, but that's a different mechanism; the
+    // test here just confirms advanced mode doesn't throw and returns
+    // both notes, not that ordering matches/mismatches literal mode).
+    expect(advanced.map((n) => n.path).sort()).toEqual(["body-only", "title-match"]);
+  });
+
+  it("a query with no results is unaffected (empty array in, empty array out)", async () => {
+    const hits = await store.searchNotes("nonexistent_term_xyz");
+    expect(hits).toEqual([]);
+  });
+});

package/core/src/seed-packs.ts

@@ -1025,6 +1025,14 @@ export interface ApplySeedPackResult {
   pack: string;
   /** Tag names upserted (upserts are idempotent; always every declared tag). */
   tags: string[];
+  /**
+   * Subset of `tags` whose DESCRIPTION was left untouched this run because it
+   * had been hand-edited away from the pack's canonical text (see
+   * `applySeedPack`'s description-preservation rule below). `fields` /
+   * `parent_names` / `relationships` are still upserted unconditionally for
+   * these tags — only the description write was skipped.
+   */
+  preservedTagDescriptions: string[];
   /** Note paths written this run (absent ones). */
   seededNotes: string[];
   /** Note paths skipped because a note already lives there (idempotency). */
@@ -1037,6 +1045,30 @@ export interface ApplySeedPackResult {
  * rows — so a re-run can never duplicate, and never clobbers a note the
  * operator/AI has since edited or recreated.
  *
+ * **Tag description preservation** (Aaron-ratified 2026-07-17): a pack writes
+ * a tag's `description` only when (a) the tag has no prior description (new
+ * tag, or an existing bare row nothing ever described), or (b) the prior
+ * description is still byte-identical to the pack's own text — i.e. no one
+ * has touched it. The moment a description differs from the pack's current
+ * text, it's treated as a deliberate hand edit (a user-tuned "constitution")
+ * and is never overwritten by a re-apply; omitting the `description` key from
+ * the `upsertTagRecord` patch is what preserves it (the store keeps whatever
+ * is already there). `fields` / `parent_names` / `relationships` are NOT
+ * given this treatment here — they still upsert unconditionally, same as
+ * before this change; those axes are more entangled with schema-validation
+ * side effects (indexed-column lifecycle, cross-tag type agreement) to
+ * safely split out in this pass. Description-only is the ratified scope.
+ *
+ * Known, accepted tradeoff: this compares against the pack's CURRENT text
+ * only, not any prior canonical version. If a pack's canonical description
+ * changes upstream, a vault that never touched it reads as "matches the OLD
+ * text, therefore edited" from the new pack's point of view, and keeps the
+ * old text too — same outcome as a genuine hand edit. That's fine:
+ * constitutions aren't security patches that must propagate; a future
+ * doctor-style scan can surface "description drifted from the current pack
+ * text" as an informational finding without this applier needing to guess
+ * intent. See CHANGELOG.
+ *
  * Errors propagate — best-effort semantics (seed-must-never-fail-a-create)
  * belong to the caller, which knows its failure policy.
  *
@@ -1051,6 +1083,7 @@ export async function applySeedPack(
   const result: ApplySeedPackResult = {
     pack: pack.name,
     tags: [],
+    preservedTagDescriptions: [],
     seededNotes: [],
     skippedNotes: [],
   };
@@ -1058,12 +1091,19 @@ export async function applySeedPack(
   // Parents first so `parent_names` reads naturally in logs (the store accepts
   // forward references, but the order matches the conceptual model).
   for (const decl of pack.tags) {
+    const existing = await store.getTagRecord(decl.name);
+    const priorDescription = existing?.description ?? null;
+    const isUserEdited = priorDescription != null && priorDescription !== decl.description;
+
     await store.upsertTagRecord(decl.name, {
-      description: decl.description,
+      // Omitted (not `undefined`-valued) when preserving — `upsertTagRecord`
+      // treats an absent `description` key as "keep the current value".
+      ...(isUserEdited ? {} : { description: decl.description }),
       ...(decl.parent_names ? { parent_names: decl.parent_names } : {}),
       ...(decl.fields ? { fields: decl.fields } : {}),
     });
     result.tags.push(decl.name);
+    if (isUserEdited) result.preservedTagDescriptions.push(decl.name);
   }
 
   for (const note of pack.notes) {

package/core/src/types.ts

@@ -400,6 +400,12 @@ export interface NoteIndex {
   metadata?: Record<string, unknown>;
   byteSize: number;
   preview: string;
+  /** Derived from the first non-empty line of content (title axis, ratified
+   *  2026-07-17) — NEVER stored, computed fresh at read time by
+   *  `computeDisplayTitle`. `null` when content has no non-empty line.
+   *  Surfaces decide how to render a `null` title (e.g. a timestamp/path
+   *  fallback); core just reports the honest content-derived value. */
+  displayTitle: string | null;
   /** Opt-in link degree (see `Note.linkCount`). */
   linkCount?: number;
   /** Full-text search relevance score (see `Note.score`). Carried onto the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openparachute/vault",
-  "version": "0.7.3-rc.4",
+  "version": "0.7.3-rc.6",
   "description": "Agent-native knowledge graph. Notes, tags, links over MCP.",
   "module": "src/cli.ts",
   "type": "module",

package/src/add-pack.test.ts

@@ -140,3 +140,35 @@ describe("add-pack surface-starter", () => {
     expect(stdout).toContain("~ tag   capture (upserted)");
   });
 });
+
+describe("add-pack — tag description preservation on re-apply (Aaron-ratified 2026-07-17)", () => {
+  test("a hand-edited description survives a re-apply and is reported 'kept', not 'upserted'", () => {
+    expect(runCli(["create", "packed", "--json"], { PARACHUTE_HOME: home }).exitCode).toBe(0);
+
+    // Simulate an operator/AI hand-editing the capture tag's constitution.
+    const dbPath = join(home, "vault", "data", "packed", "vault.db");
+    const editedDescription = "Our house rules for capture — not the default text.";
+    const writeDb = new Database(dbPath);
+    writeDb.query("UPDATE tags SET description = ? WHERE name = ?").run(
+      editedDescription,
+      "capture",
+    );
+    writeDb.close();
+
+    const { exitCode, stdout } = runCli(
+      ["add-pack", "welcome", "--vault", "packed"],
+      { PARACHUTE_HOME: home },
+    );
+    expect(exitCode).toBe(0);
+    expect(stdout).toContain("~ tag   capture (kept user description)");
+    // guide wasn't edited, so it still reports the old vocabulary.
+    expect(stdout).toContain("~ tag   guide (upserted)");
+
+    const readDb = new Database(dbPath, { readonly: true });
+    const row = readDb
+      .query("SELECT description FROM tags WHERE name = ?")
+      .get("capture") as { description: string };
+    readDb.close();
+    expect(row.description).toBe(editedDescription);
+  });
+});

package/src/cli.ts

@@ -4842,7 +4842,11 @@ async function cmdAddPack(args: string[]) {
       console.log(`  = note  ${path} (already exists — left untouched)`);
     }
     for (const tag of result.tags) {
-      console.log(`  ~ tag   ${tag} (upserted)`);
+      if (result.preservedTagDescriptions.includes(tag)) {
+        console.log(`  ~ tag   ${tag} (kept user description)`);
+      } else {
+        console.log(`  ~ tag   ${tag} (upserted)`);
+      }
     }
     if (result.seededNotes.length === 0 && result.tags.length === 0) {
       console.log("  Nothing to add — everything was already in place.");

package/src/onboarding-seed.test.ts

@@ -23,14 +23,17 @@ import { BunStore } from "./vault-store.ts";
 import { seedOnboardingNotes } from "./onboarding-seed.ts";
 import {
   applySeedPack,
+  ARCHIVED_TAG,
   CAPTURE_ANYTHING_PATH,
   CONNECT_AI_PATH,
   GETTING_STARTED_PATH,
   NOTES_REQUIRED_TAGS,
+  STARTER_ONTOLOGY_PACK,
   SURFACE_STARTER_PACK,
   SURFACE_STARTER_PATH,
   TAGS_GRAPH_PATH,
   WELCOME_PATH,
+  welcomePack,
   YOURS_TO_KEEP_PATH,
 } from "../core/src/seed-packs.ts";
 import {
@@ -290,6 +293,67 @@ describe("applySeedPack — surface-starter via add-pack", () => {
   });
 });
 
+describe("applySeedPack — tag description preservation on re-apply (Aaron-ratified 2026-07-17)", () => {
+  test("fresh apply: a brand-new tag gets the pack's description, reported as touched not preserved", async () => {
+    const result = await applySeedPack(store, STARTER_ONTOLOGY_PACK);
+    expect(result.tags).toContain(ARCHIVED_TAG.name);
+    expect(result.preservedTagDescriptions).toEqual([]);
+
+    const record = await store.getTagRecord(ARCHIVED_TAG.name);
+    expect(record!.description).toBe(ARCHIVED_TAG.description);
+  });
+
+  test("re-apply unmodified: description is still the pack's text — upserted, not preserved", async () => {
+    await applySeedPack(store, STARTER_ONTOLOGY_PACK);
+    const rerun = await applySeedPack(store, STARTER_ONTOLOGY_PACK);
+    expect(rerun.preservedTagDescriptions).toEqual([]);
+
+    const record = await store.getTagRecord(ARCHIVED_TAG.name);
+    expect(record!.description).toBe(ARCHIVED_TAG.description);
+  });
+
+  test("re-apply after a user edit: the hand-tuned description survives and is reported preserved", async () => {
+    await applySeedPack(store, STARTER_ONTOLOGY_PACK);
+    const edited = "My own house rules for archiving — nothing like the default.";
+    await store.upsertTagRecord(ARCHIVED_TAG.name, { description: edited });
+
+    const rerun = await applySeedPack(store, STARTER_ONTOLOGY_PACK);
+    expect(rerun.preservedTagDescriptions).toContain(ARCHIVED_TAG.name);
+    // Still listed in `tags` — the tag itself was touched (fields/parent_names
+    // upsert unconditionally); only the description write was skipped.
+    expect(rerun.tags).toContain(ARCHIVED_TAG.name);
+
+    const record = await store.getTagRecord(ARCHIVED_TAG.name);
+    expect(record!.description).toBe(edited);
+  });
+
+  test("capture byte-identity anchor (NOTES_REQUIRED_TAGS) holds under either apply order", async () => {
+    // welcome, then starter-ontology.
+    await applySeedPack(store, welcomePack());
+    expect((await store.getTagRecord("capture"))!.description).toBe(
+      NOTES_REQUIRED_TAGS[0]!.description,
+    );
+    const afterOntology = await applySeedPack(store, STARTER_ONTOLOGY_PACK);
+    expect(afterOntology.preservedTagDescriptions).not.toContain("capture");
+    expect((await store.getTagRecord("capture"))!.description).toBe(
+      NOTES_REQUIRED_TAGS[0]!.description,
+    );
+  });
+
+  test("capture byte-identity anchor holds in the reverse order too", async () => {
+    // starter-ontology, then welcome.
+    await applySeedPack(store, STARTER_ONTOLOGY_PACK);
+    expect((await store.getTagRecord("capture"))!.description).toBe(
+      NOTES_REQUIRED_TAGS[0]!.description,
+    );
+    const afterWelcome = await applySeedPack(store, welcomePack());
+    expect(afterWelcome.preservedTagDescriptions).not.toContain("capture");
+    expect((await store.getTagRecord("capture"))!.description).toBe(
+      NOTES_REQUIRED_TAGS[0]!.description,
+    );
+  });
+});
+
 describe("vault-info / projection pointer (A2)", () => {
   test("projection carries getting_started when the note exists", async () => {
     // Absent before seeding → no pointer.

package/src/vault.test.ts

@@ -2139,6 +2139,22 @@ describe("HTTP /notes", async () => {
     expect(body[0]).not.toHaveProperty("content");
     expect(body[0]).toHaveProperty("byteSize");
     expect(body[0]).toHaveProperty("preview");
+    expect(body[0]).toHaveProperty("displayTitle");
+  });
+
+  // Title axis (ratified 2026-07-17) — displayTitle on the REST lean shape.
+  test("GET /notes lean shape carries the computed displayTitle", async () => {
+    await store.createNote("# Meeting Notes\nagenda: budget", { path: "meeting" });
+    const res = await handleNotes(mkReq("GET", "/notes"), store, "");
+    const body = await res.json() as any[];
+    expect(body[0].displayTitle).toBe("Meeting Notes");
+  });
+
+  test("GET /notes lean shape reports null displayTitle for an empty note", async () => {
+    await store.createNote("", { path: "empty" });
+    const res = await handleNotes(mkReq("GET", "/notes"), store, "");
+    const body = await res.json() as any[];
+    expect(body[0].displayTitle).toBeNull();
   });
 
   test("GET /notes?include_content=true returns full notes", async () => {