@openparachute/vault 0.7.2 → 0.7.3-rc.10

package/core/src/store.ts

@@ -1,5 +1,5 @@
 import { Database } from "bun:sqlite";
-import type { Store, Note, Link, Attachment, QueryOpts, QueryNotesPage, AggregateRow } from "./types.js";
+import type { Store, Note, Link, Attachment, QueryOpts, QueryNotesPage, AggregateRow, SemanticSearchResult } from "./types.js";
 import { initSchema } from "./schema.js";
 import * as noteOps from "./notes.js";
 import * as linkOps from "./links.js";
@@ -38,6 +38,7 @@ import {
   loadSchemaConfig,
   validateNote as runValidateNote,
   resolveNoteSchemas,
+  normalizeDateFields,
   type ResolvedSchemas,
   type ValidationStatus,
 } from "./schema-defaults.js";
@@ -47,6 +48,9 @@ import {
 } from "./conformance.js";
 import type { SearchMode } from "./search-query.js";
 import { runDoctorScan, type DoctorReport, type DoctorScanOpts } from "./doctor.js";
+import { EmbeddingError, type EmbeddingProvider } from "./embedding/provider.js";
+import { normalize } from "./embedding/vector-codec.js";
+import { QueryError } from "./query-operators.js";
 
 /**
  * Normalize a `type: "reference"` field value (scalar OR array — see
@@ -94,9 +98,38 @@ export class BunSqliteStore implements Store {
   private _tagHierarchy: TagHierarchy | null = null;
   private _schemaConfig: ResolvedSchemas | null = null;
 
-  constructor(public readonly db: Database, opts?: { hooks?: HookRegistry }) {
+  /**
+   * The active `EmbeddingProvider` (EXPERIMENTAL — semantic search MVP),
+   * when one is configured. `undefined` on a vault with no provider —
+   * `semanticSearch` reports that honestly (`semantic_unavailable`)
+   * rather than silently falling back to keyword search. Resolved ONCE at
+   * construction (mirrors `hooks`) — self-host/cloud each build the
+   * concrete provider (ONNX/external-API, Workers AI) and pass it in here;
+   * core never imports a model library itself (dependency-purity rule).
+   */
+  public readonly embeddingProvider?: EmbeddingProvider;
+
+  /**
+   * WHY `embeddingProvider` is absent, when the caller knows a specific
+   * reason (currently: the operator set `EMBEDDINGS_ENABLED=false` — see
+   * `src/embedding/select.ts`). Core never reads env vars itself
+   * (dependency-purity rule — see `embeddingProvider`'s doc comment
+   * above), so it can't distinguish "explicitly turned off" from "never
+   * configured" on its own; the caller passes this through so
+   * `semanticSearch`'s error hint can be honest either way instead of
+   * defaulting to generic provider-setup instructions when the operator
+   * deliberately opted out.
+   */
+  public readonly embeddingDisabledReason?: string;
+
+  constructor(
+    public readonly db: Database,
+    opts?: { hooks?: HookRegistry; embeddingProvider?: EmbeddingProvider; embeddingDisabledReason?: string },
+  ) {
     initSchema(db);
     this.hooks = opts?.hooks ?? new HookRegistry();
+    this.embeddingProvider = opts?.embeddingProvider;
+    this.embeddingDisabledReason = opts?.embeddingDisabledReason;
   }
 
   /**
@@ -468,6 +501,16 @@ export class BunSqliteStore implements Store {
   // ---- Notes ----
 
   async createNote(content: string, opts?: { id?: string; path?: string; tags?: string[]; metadata?: Record<string, unknown>; created_at?: string; extension?: string; actor?: string | null; via?: string | null }): Promise<Note> {
+    // Normalize `date`-typed field values to canonical UTC ISO form BEFORE
+    // the write (vault#date-field-type — mixed-offset TEXT-compare
+    // corruption). COPY-ON-WRITE (round 2) — reassign the local `opts`
+    // binding from the returned value rather than mutating the caller's
+    // object; see `normalizeDateFields`'s doc comment.
+    if (opts?.metadata) {
+      const normalized = normalizeDateFields(this.getSchemaConfig(), { tags: opts.tags, metadata: opts.metadata });
+      if (normalized !== opts.metadata) opts = { ...opts, metadata: normalized };
+    }
+
     const note = noteOps.createNote(this.db, content, opts);
 
     if (content) {
@@ -516,6 +559,20 @@ export class BunSqliteStore implements Store {
       actor?: string | null;
       via?: string | null;
       if_updated_at?: string;
+      /**
+       * `date`-field normalization override (vault#date-field-type review
+       * round 2). By default, `normalizeDateFields` below resolves the note's
+       * effective schema against its CURRENT tags in the DB — correct when
+       * this call doesn't also change tags. A caller that adds a tag IN THIS
+       * SAME logical update (via a separate `store.tagNote` issued right
+       * after this call — see mcp.ts's `update-note` handler and the batch
+       * upsert "update"/"replace" branch) must pass the PROJECTED final tag
+       * set here instead, or a newly-added tag's `type: "date"` field never
+       * gets seen (the schema resolution would still be looking at the
+       * pre-write tag set) and its offset-bearing value would persist
+       * verbatim. Ignored when `updates.metadata` is undefined.
+       */
+      tagsForSchemaResolution?: string[];
     },
   ): Promise<Note> {
     let oldPath: string | undefined;
@@ -529,7 +586,19 @@ export class BunSqliteStore implements Store {
     if (updates.path !== undefined || updates.metadata !== undefined) {
       const existing = noteOps.getNote(this.db, id);
       if (updates.path !== undefined) oldPath = existing?.path;
-      if (updates.metadata !== undefined) priorMetadataForRefs = existing?.metadata;
+      if (updates.metadata !== undefined) {
+        priorMetadataForRefs = existing?.metadata;
+        // Normalize `date`-typed field values to canonical UTC ISO form
+        // BEFORE the write (vault#date-field-type — mixed-offset TEXT-
+        // compare corruption). COPY-ON-WRITE (round 2) — reassign the local
+        // `updates` binding from the returned value rather than mutating the
+        // caller's object; see `normalizeDateFields`'s doc comment.
+        // `tagsForSchemaResolution` (when the caller is ALSO adding a tag in
+        // this same logical update) wins over the note's current DB tags.
+        const tagsForResolution = updates.tagsForSchemaResolution ?? existing?.tags;
+        const normalized = normalizeDateFields(this.getSchemaConfig(), { tags: tagsForResolution, metadata: updates.metadata });
+        if (normalized !== updates.metadata) updates = { ...updates, metadata: normalized };
+      }
     }
 
     const note = noteOps.updateNote(this.db, id, updates);
@@ -814,6 +883,75 @@ export class BunSqliteStore implements Store {
     return noteOps.searchNotes(this.db, query, opts);
   }
 
+  /**
+   * Semantic search (EXPERIMENTAL — `SEMANTIC-MVP-PLAN.md`). The ONE
+   * invocation point for `embeddingProvider`: resolves it, embeds
+   * `nearText` into a query vector, normalizes it (stored vectors are
+   * ALSO L2-normalized — see `note_vectors`'s schema comment — so the
+   * scan's dot product is cosine similarity), and calls
+   * `noteOps.semanticSearchNotes` with the SAME tag-hierarchy expansion
+   * `queryNotes` applies (so `semantic: true, tag: "manual"` composes with
+   * the tag `expand` axis identically to a structured query).
+   *
+   * Throws a `QueryError` (`error_type: "semantic_unavailable"`) when no
+   * provider is configured, the configured one reports itself not ready,
+   * OR the embed call itself fails mid-flight (e.g. the bundled ONNX
+   * floor's lazy model load fails on this — the FIRST — real `embed()`
+   * attempt, after `available()` optimistically reported `ok: true`; see
+   * `onnx-transformers.ts`'s "lazy-fail, not crash" doc) — NEVER a silent
+   * fallback to keyword search, and never a raw unstructured 500. Callers
+   * (MCP/REST) let this propagate uncaught, same as
+   * `invalid_search_syntax` above.
+   */
+  async semanticSearch(nearText: string, opts?: QueryOpts): Promise<SemanticSearchResult> {
+    if (!this.embeddingProvider) {
+      // Honest either way: if the caller told us WHY (operator explicitly
+      // set EMBEDDINGS_ENABLED=false), say that — not generic provider-setup
+      // instructions that would be actively misleading for a deliberate
+      // opt-out. See `embeddingDisabledReason`'s doc comment.
+      throw new QueryError(
+        `semantic search requires an embedding provider — none is configured on this vault`,
+        "SEMANTIC_UNAVAILABLE",
+        {
+          error_type: "semantic_unavailable",
+          hint:
+            this.embeddingDisabledReason ??
+            "configure EMBEDDING_API_URL/EMBEDDING_API_KEY/EMBEDDING_MODEL, or rely on the bundled floor provider (self-host); semantic search is not yet available on this door otherwise",
+        },
+      );
+    }
+    const availability = await this.embeddingProvider.available();
+    if (!availability.ok) {
+      throw new QueryError(
+        `semantic search is unavailable: ${availability.reason ?? "embedding provider not ready"}`,
+        "SEMANTIC_UNAVAILABLE",
+        { error_type: "semantic_unavailable", hint: availability.reason },
+      );
+    }
+
+    let vectors: Float32Array[];
+    try {
+      ({ vectors } = await this.embeddingProvider.embed({ texts: [nearText] }));
+    } catch (err) {
+      // `available()` passing is only a CHEAP readiness check (never a real
+      // network/model round-trip — see EmbeddingProvider.available's doc
+      // comment) — it can't catch a provider whose actual first embed call
+      // fails (a lazy model load blowing up, a transient upstream error).
+      // Map ANY embed()-time failure to the same honest semantic_unavailable
+      // shape as the checks above, rather than letting a raw EmbeddingError
+      // (or whatever else a provider throws) surface as an unstructured 500.
+      const reason = err instanceof EmbeddingError ? err.message : err instanceof Error ? err.message : String(err);
+      throw new QueryError(`semantic search is unavailable: ${reason}`, "SEMANTIC_UNAVAILABLE", {
+        error_type: "semantic_unavailable",
+        hint: reason,
+      });
+    }
+    const queryVector = normalize(vectors[0]!);
+
+    const filterOpts = this.expandQueryTags(this.normalizeQueryTags(opts ?? {}));
+    return noteOps.semanticSearchNotes(this.db, queryVector, filterOpts, this.embeddingProvider.model);
+  }
+
   // ---- Tags ----
 
   async tagNote(noteId: string, tags: string[]): Promise<void> {
@@ -933,7 +1071,18 @@ export class BunSqliteStore implements Store {
   // ---- Bulk Operations ----
 
   async createNotes(inputs: noteOps.BulkNoteInput[]): Promise<Note[]> {
-    const notes = noteOps.createNotes(this.db, inputs);
+    // Same pre-write `date`-field normalization as singleton createNote
+    // (vault#date-field-type) — this bulk path bypasses it otherwise.
+    // COPY-ON-WRITE (round 2) — build a new array with only the items that
+    // actually need a rewrite replaced; never mutate the caller's `inputs`
+    // or its element objects.
+    const schemaConfig = this.getSchemaConfig();
+    const normalizedInputs = inputs.map((input) => {
+      if (!input.metadata) return input;
+      const normalized = normalizeDateFields(schemaConfig, { tags: input.tags, metadata: input.metadata });
+      return normalized !== input.metadata ? { ...input, metadata: normalized } : input;
+    });
+    const notes = noteOps.createNotes(this.db, normalizedInputs);
     for (const note of notes) {
       // Bulk path needs the same config-cache invalidation as singleton
       // createNote — without it, a batch that includes `_tags/*` notes
@@ -1143,7 +1292,7 @@ export class BunSqliteStore implements Store {
         const mapped = indexedFieldOps.mapFieldType(spec.type);
         if (!mapped) {
           throw new indexedFieldOps.IndexedFieldError(
-            `field "${fieldName}" has unsupported type "${spec.type}" for indexing (supported: string, integer, boolean, reference)`,
+            `field "${fieldName}" has unsupported type "${spec.type}" for indexing (supported: string, integer, boolean, reference, date)`,
           );
         }
         // Throws IndexedFieldError on an invalid identifier (e.g. kebab-case).
@@ -1275,6 +1424,14 @@ export class BunSqliteStore implements Store {
    * place.)
    */
   async createNoteRaw(content: string, opts?: { id?: string; path?: string; tags?: string[]; metadata?: Record<string, unknown>; created_at?: string; extension?: string }): Promise<Note> {
+    // Same pre-write `date`-field normalization as createNote
+    // (vault#date-field-type) — the legacy Obsidian importer (obsidian.ts)
+    // funnels through this path and bypasses createNote's copy otherwise.
+    // COPY-ON-WRITE (round 2) — see normalizeDateFields's doc comment.
+    if (opts?.metadata) {
+      const normalized = normalizeDateFields(this.getSchemaConfig(), { tags: opts.tags, metadata: opts.metadata });
+      if (normalized !== opts.metadata) opts = { ...opts, metadata: normalized };
+    }
     return noteOps.createNote(this.db, content, opts);
   }
 

package/core/src/tag-schemas.ts

@@ -18,6 +18,7 @@
 import { Database } from "bun:sqlite";
 import { mapFieldType, validateFieldName } from "./indexed-fields.js";
 import { loadTagHierarchy, findParentCycle } from "./tag-hierarchy.js";
+import { timestampToMs } from "./cursor.js";
 
 // ---------------------------------------------------------------------------
 // Types
@@ -192,7 +193,7 @@ export class InvalidFieldDefaultError extends Error {
 
 /**
  * Thrown by `upsertTagRecord` (core/src/store.ts's chokepoint) when a
- * field's declared `type` isn't one of the six recognized values (vault#555
+ * field's declared `type` isn't one of the recognized values (vault#555
  * — `update-tag{fields:{weird:{type:"frobnicator"}}}` used to be accepted
  * and persisted verbatim, no error, for any NON-indexed field: the only
  * existing type check, `mapFieldType`, ran solely on `indexed: true` fields
@@ -255,13 +256,13 @@ export function validateFieldDefault(field: string, spec: TagFieldSchema): TagFi
 
 /**
  * The full recognized vocabulary for `TagFieldSchema.type` — storage/
- * advisory validation accepts all seven; only `string`/`integer`/`boolean`/
- * `reference` are INDEXABLE (that narrower subset is `indexed-fields.ts`'s
- * `TYPE_MAP`, enforced separately via `mapFieldType` for `indexed: true`
- * fields). Matches `defaultMatchesType`'s switch and `schema-defaults.ts`'s
- * `SchemaField.type` union — kept in lockstep by hand across the two
- * deliberately-decoupled modules (see `validateFieldDefault`'s doc comment
- * for why they don't cross-import).
+ * advisory validation accepts all eight; only `string`/`integer`/`boolean`/
+ * `reference`/`date` are INDEXABLE (that narrower subset is
+ * `indexed-fields.ts`'s `TYPE_MAP`, enforced separately via `mapFieldType`
+ * for `indexed: true` fields). Matches `defaultMatchesType`'s switch and
+ * `schema-defaults.ts`'s `SchemaField.type` union — kept in lockstep by hand
+ * across the two deliberately-decoupled modules (see `validateFieldDefault`'s
+ * doc comment for why they don't cross-import).
  *
  * `reference` (vault#typed-reference-field) is a dual-write field type: the
  * value is stored + validated exactly like `string` (an id/path/title the
@@ -270,11 +271,18 @@ export function validateFieldDefault(field: string, spec: TagFieldSchema): TagFi
  * to a note and maintains a graph `links` edge from this note to the
  * resolved target, with `relationship` set to the field name. See
  * `docs/design/typed-reference-field.md` for the full design + known gaps.
+ *
+ * `date` stores/validates like `string` (an ISO-8601 date or timestamp) so
+ * indexed `date` fields sort correctly under a plain TEXT comparison — see
+ * `defaultMatchesType`'s `"date"` case and `schema-defaults.ts`'s
+ * `valueMatchesType`, both of which reuse `cursor.ts`'s `timestampToMs`
+ * (the SAME UTC-correct parser `date_filter`'s `updated_at` bound uses) so
+ * there's exactly one ISO-parsing implementation in the codebase, not two.
  */
-export const VALID_FIELD_TYPES = ["string", "number", "integer", "boolean", "array", "object", "reference"] as const;
+export const VALID_FIELD_TYPES = ["string", "number", "integer", "boolean", "array", "object", "reference", "date"] as const;
 
 /**
- * Validate that a field's declared `type` is one of the six recognized
+ * Validate that a field's declared `type` is one of the recognized
  * values (vault#555). Returns `null` when `type` is unset (own-field checks
  * elsewhere already treat an unset type as "nothing to check against") or
  * recognized; otherwise a {@link TagFieldViolation} with `reason:
@@ -328,7 +336,7 @@ export function collectOwnFieldDefaultAndTypeViolations(
   return violations;
 }
 
-/** Same seven-type vocabulary as `TagFieldSchema.type`'s doc comment. Unknown/unset types pass (nothing to check against). */
+/** Same eight-type vocabulary as `TagFieldSchema.type`'s doc comment. Unknown/unset types pass (nothing to check against). */
 function defaultMatchesType(value: unknown, type: string): boolean {
   switch (type) {
     case "string":
@@ -348,6 +356,13 @@ function defaultMatchesType(value: unknown, type: string): boolean {
     // VALID_FIELD_TYPES's doc comment.
     case "reference":
       return typeof value === "string";
+    // `date` accepts an ISO-8601 date (`YYYY-MM-DD`) or full RFC3339
+    // timestamp — the SAME grammar `date_filter`'s `updated_at` bound
+    // parses (`timestampToMs`, imported from cursor.ts), not a second,
+    // independently-drifting date parser. See VALID_FIELD_TYPES's doc
+    // comment.
+    case "date":
+      return typeof value === "string" && timestampToMs(value) !== null;
     default:
       return true;
   }
@@ -767,7 +782,7 @@ export function collectTagFieldViolations(
         violations.push({
           field: fieldName,
           reason: "unsupported_indexed_type",
-          message: `field "${fieldName}" has unsupported type "${spec.type}" for indexing (supported: string, integer, boolean, reference)`,
+          message: `field "${fieldName}" has unsupported type "${spec.type}" for indexing (supported: string, integer, boolean, reference, date)`,
         });
       } else {
         try {

package/core/src/types.ts

@@ -31,6 +31,13 @@ export interface Note {
    * `core/src/portable-md.ts:supportsInlineFrontmatter`.
    */
   extension?: string;
+  /**
+   * Always present on notes read back from the store — NULL/`"{}"`/
+   * unparseable metadata all collapse to `{}` rather than an absent key
+   * (mirrors `tags`, which is likewise always `[]`). Optional here only so
+   * write-input shapes (`createNote`/`updateNote` options) can share this
+   * type without forcing every caller to pass an empty object.
+   */
   metadata?: Record<string, unknown>;
   createdAt: string; // ISO-8601
   updatedAt?: string;
@@ -271,6 +278,43 @@ export interface QueryOpts {
    * row per group, not a paginated note list.
    */
   aggregate?: AggregateSpec;
+  /**
+   * Semantic-search MVP (EXPERIMENTAL — `SEMANTIC-MVP-PLAN.md`). Free text
+   * to rank notes by MEANING rather than keyword. Requires `semantic:
+   * true` and is mutually exclusive with `search` (structurally the same
+   * "text in → ranked notes with a score out" shape as `search`, but
+   * routed through `note_vectors` cosine similarity instead of FTS5
+   * bm25). Every other filter on this `QueryOpts` (tags, metadata, date
+   * range, path, ...) narrows the candidate set FIRST, exactly like
+   * `search` — see `core/src/notes.ts:semanticSearchNotes`.
+   */
+  nearText?: string;
+  /**
+   * Opt into vector ranking. `true` requires `nearText`; omitting it (or
+   * passing `false`) is a plain structured/keyword query, byte-identical
+   * to pre-semantic-search behavior. See `nearText`.
+   */
+  semantic?: boolean;
+}
+
+/**
+ * Result of a semantic-search scan (EXPERIMENTAL — see
+ * `QueryOpts.nearText`/`semantic`). Returned by
+ * `core/src/notes.ts:semanticSearchNotes` and `Store.semanticSearch`.
+ */
+export interface SemanticSearchResult {
+  /** Notes ranked by cosine similarity (best matching chunk per note), highest first. Each carries `.score`. */
+  notes: Note[];
+  /**
+   * Count of candidate notes (post structured-filter, pre-rank) with NO
+   * vector row yet for the active embedding model — the `embeddings_pending`
+   * signal. A note with SOME but not all chunks embedded still counts as
+   * "has a vector" here (coarse-but-honest: it can be ranked, just not on
+   * its full content yet) — see the doc comment on `semanticSearchNotes`.
+   */
+  pendingCount: number;
+  /** Total candidate notes considered, after structured filters, before ranking/limit. */
+  totalCandidates: number;
 }
 
 /**
@@ -352,9 +396,16 @@ export interface NoteIndex {
   lastUpdatedBy?: string | null;
   lastUpdatedVia?: string | null;
   tags?: string[];
+  /** Always present (`{}` when empty) — see `Note.metadata`. */
   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
@@ -405,7 +456,7 @@ export interface Store {
    */
   getNoteByPath(path: string, extension?: string): Promise<Note | null>;
   getNotes(ids: string[]): Promise<Note[]>;
-  updateNote(id: string, updates: { content?: string; append?: string; prepend?: string; path?: string; extension?: string; metadata?: Record<string, unknown>; created_at?: string; skipUpdatedAt?: boolean; actor?: string | null; via?: string | null; if_updated_at?: string }): Promise<Note>;
+  updateNote(id: string, updates: { content?: string; append?: string; prepend?: string; path?: string; extension?: string; metadata?: Record<string, unknown>; created_at?: string; skipUpdatedAt?: boolean; actor?: string | null; via?: string | null; if_updated_at?: string; tagsForSchemaResolution?: string[] }): Promise<Note>;
   /**
    * Set a note's `created_at` and `updated_at` explicitly. Import-only:
    * used by the portable-md round-trip path to restore timestamps from
@@ -455,6 +506,17 @@ export interface Store {
    * `created_at` ordering. See `core/src/search-query.ts`.
    */
   searchNotes(query: string, opts?: { tags?: string[]; limit?: number; expand?: TagExpandMode; mode?: SearchMode; sort?: "asc" | "desc" }): Promise<Note[]>;
+  /**
+   * Semantic search (EXPERIMENTAL — see `QueryOpts.nearText`/`semantic`).
+   * The one invocation point for the store's `EmbeddingProvider`: embeds
+   * `nearText`, ranks notes by cosine similarity over `note_vectors`
+   * (best chunk per note), and applies every other filter on `opts`
+   * (tags/metadata/dates/...) first, exactly like `queryNotes`. Throws a
+   * structured `QueryError` (`error_type: "semantic_unavailable"`) when no
+   * provider is configured or the configured one isn't ready — never a
+   * silent fallback to keyword search.
+   */
+  semanticSearch(nearText: string, opts?: QueryOpts): Promise<SemanticSearchResult>;
 
   // Tags
   tagNote(noteId: string, tags: string[]): Promise<void>;

package/core/src/vault-projection.ts

@@ -272,6 +272,42 @@ function sqliteToUserType(t: string): string {
   return t.toLowerCase();
 }
 
+// ---------------------------------------------------------------------------
+// Attachments orientation block (attachment-tickets design, Wave 0+1)
+// ---------------------------------------------------------------------------
+
+/**
+ * The Attachments orientation block, rendered into the connect-time
+ * markdown brief (`projectionToMarkdown`) so every agent learns, every
+ * session, how to move file bytes into/out of this vault without spending
+ * its own context on them (bytes never ride MCP either way).
+ *
+ * `ticketsEnabled` reflects whether THIS door has wired an
+ * `AttachmentTicketProvider` (bun: always, as of this PR; cloud: not yet
+ * — its mirror is a separate PR). An unwired door omits BOTH the ticket
+ * tools from `tools/list` (see `generateMcpTools`'s `attachmentTickets`
+ * opt) AND the ticket-tool sentences here — the brief never dangles a
+ * pointer at a tool the agent can't actually call.
+ *
+ * Kept as a single dense paragraph (not its own multi-line list) to stay
+ * inside the connect-time brief's token budget — see
+ * `projectionToMarkdown`'s doc comment.
+ */
+export function attachmentsInstructionBlock(opts: { ticketsEnabled: boolean }): string {
+  const sentences: string[] = [
+    "Notes can carry file attachments (`include_attachments: true` on `query-notes` returns their rows; bytes don't ride MCP).",
+  ];
+  if (opts.ticketsEnabled) {
+    sentences.push(
+      "To move bytes, call `request-attachment-upload` / `request-attachment-download` — each mints a short-lived, single-use URL (with a ready-to-run `curl_example`) your shell spends directly; no MCP session credential is needed to spend it.",
+    );
+  }
+  sentences.push(
+    "If your runtime holds this vault's own API token, REST works too: upload = `POST {base}/storage/upload` (multipart `file`, ≤100 MB) then `POST {base}/notes/{id}/attachments` `{path, mimeType, transcribe?}`; download = `GET {base}/storage/{path}` with the same `Authorization: Bearer`. Audio attached with `transcribe: true` is transcribed automatically.",
+  );
+  return sentences.join(" ");
+}
+
 // ---------------------------------------------------------------------------
 // Markdown rendering — for getServerInstruction
 // ---------------------------------------------------------------------------
@@ -302,6 +338,13 @@ export function projectionToMarkdown(args: {
    * known and always surfaced. See `chooseHubOrigin` (src/mcp-install.ts).
    */
   coordinates?: { hubOrigin: string; hubOriginKnown: boolean };
+  /**
+   * Attachments orientation (see `attachmentsInstructionBlock`). Omitted
+   * defaults to `{ ticketsEnabled: false }` — safe-by-default so a caller
+   * that hasn't wired ticket support yet (or a test fixture) never
+   * accidentally advertises tools it can't back.
+   */
+  attachments?: { ticketsEnabled: boolean };
 }): string {
   const { vaultName, description, projection, coordinates } = args;
   const stats = projection.stats;
@@ -418,6 +461,11 @@ export function projectionToMarkdown(args: {
   lines.push("");
   lines.push("If schema or tags change during this session, call `vault-info` to refresh the full projection. Call `list-tags { include_schema: true }` for tag-only details.");
 
+  lines.push("");
+  lines.push("## Attachments");
+  lines.push("");
+  lines.push(attachmentsInstructionBlock(args.attachments ?? { ticketsEnabled: false }));
+
   // Scripting pointer block: the connect-time brief used to dead-end on
   // querying — an agent had no path to "how do I script/automate against this
   // vault." Point at the guide rather than inlining it, to keep this brief

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openparachute/vault",
-  "version": "0.7.2",
+  "version": "0.7.3-rc.10",
   "description": "Agent-native knowledge graph. Notes, tags, links over MCP.",
   "module": "src/cli.ts",
   "type": "module",
@@ -25,6 +25,7 @@
     "prepack": "bun run build:spa"
   },
   "dependencies": {
+    "@huggingface/transformers": "^4.2.0",
     "@modelcontextprotocol/sdk": "^1.12.1",
     "@openparachute/scope-guard": "^0.5.0",
     "jose": "^6.2.2",
@@ -34,6 +35,10 @@
   "devDependencies": {
     "@types/bun": "latest"
   },
+  "trustedDependencies": [
+    "onnxruntime-node",
+    "protobufjs"
+  ],
   "peerDependencies": {
     "typescript": "^5"
   },

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);
+  });
+});