@openparachute/vault 0.6.0-rc.1 → 0.6.1

package/core/src/tag-schemas.ts

@@ -33,10 +33,13 @@ export interface TagFieldSchema {
 }
 
 /**
- * Cardinality vocabulary for typed relationships. Names rather than
- * algebra so AI clients reading `list-tags` can reason about intent
- * directly. Phase 1 is informational — declarations are not enforced
- * at write time. See patterns/tag-data-model.md §Typed relationships.
+ * Cardinality vocabulary for the historical typed-relationship shape.
+ * Names rather than algebra so AI clients reading `list-tags` can reason
+ * about intent directly. Retained for callers that still want the typed
+ * `{ target_tag, cardinality }` declaration — but `relationships` is now an
+ * opaque vocabulary map (see `TagRelationshipMap` / `validateRelationships`),
+ * so this is one valid value shape among many, not a required one.
+ * See patterns/tag-data-model.md §Relationships.
  */
 export type TagRelCardinality = "one" | "optional" | "many" | "many-required";
 
@@ -47,12 +50,24 @@ export const TAG_REL_CARDINALITIES: readonly TagRelCardinality[] = [
   "many-required",
 ] as const;
 
+/**
+ * The historical typed-relationship declaration. Still a valid opaque-map
+ * value — vault no longer enforces it. New apps (the Weaver / structural-link
+ * picker) declare their own freeform vocabulary instead.
+ */
 export interface TagRelationship {
   target_tag: string;
   cardinality: TagRelCardinality;
   description?: string;
 }
 
+/**
+ * `relationships` is an opaque vocabulary map: relationship-name → arbitrary
+ * JSON value the declaring app interprets. Vault stores and returns the values
+ * verbatim and enforces only that the top-level value is a JSON object (a map).
+ */
+export type TagRelationshipMap = Record<string, unknown>;
+
 /**
  * Schema-only view of a tag — the historical shape. Backwards-compatible
  * with v13-and-earlier callers.
@@ -67,7 +82,7 @@ export interface TagSchema {
  * Full tag record — schema + typed relationships + hierarchy parents.
  */
 export interface TagRecord extends TagSchema {
-  relationships?: Record<string, TagRelationship>;
+  relationships?: TagRelationshipMap;
   parent_names?: string[];
   created_at?: string;
   updated_at?: string;
@@ -100,7 +115,7 @@ export function listTagRecords(db: Database): TagRecord[] {
 export function getTagRecord(db: Database, tag: string): TagRecord | null {
   const row = db.prepare(
     "SELECT name, description, fields, relationships, parent_names, created_at, updated_at FROM tags WHERE name = ?",
-  ).get(tag) as TagRow | undefined;
+  ).get(tag) as TagRow | null;
   return row ? rowToRecord(row) : null;
 }
 
@@ -115,7 +130,7 @@ export function upsertTagRecord(
   patch: {
     description?: string | null;
     fields?: Record<string, TagFieldSchema> | null;
-    relationships?: Record<string, TagRelationship> | null;
+    relationships?: TagRelationshipMap | null;
     parent_names?: string[] | null;
   },
 ): TagRecord {
@@ -174,7 +189,7 @@ export function listTagSchemas(db: Database): TagSchema[] {
 export function getTagSchema(db: Database, tag: string): TagSchema | null {
   const row = db.prepare(
     "SELECT name, description, fields FROM tags WHERE name = ?",
-  ).get(tag) as { name: string; description: string | null; fields: string | null } | undefined;
+  ).get(tag) as { name: string; description: string | null; fields: string | null } | null;
   if (!row) return null;
   if (row.description === null && row.fields === null) return null;
   return {
@@ -226,56 +241,56 @@ export function deleteTagSchema(db: Database, tag: string): boolean {
 }
 
 // ---------------------------------------------------------------------------
-// Validation — typed relationships
+// Validation — relationships (opaque vocabulary map)
 // ---------------------------------------------------------------------------
 
 /**
- * Validate a `relationships` payload before persisting. Returns the
- * canonicalized object on success; throws Error with a user-readable
- * message on the first violation. Rules:
+ * Validate a `relationships` payload before persisting. `relationships` is
+ * an **opaque vocabulary map**: a JSON object whose keys are relationship
+ * names and whose values are arbitrary JSON the declaring app interprets
+ * (e.g. the Weaver / structural-link picker's `{ "works-on": { from, to } }`
+ * shape). Vault does not enforce any inner structure — it stores and returns
+ * the values verbatim.
+ *
+ * Rules (the only ones):
+ *   - The top-level value must be a plain JSON object (a map). A top-level
+ *     array or primitive is rejected — relationships is a map, not a list.
+ *   - The payload must be JSON-serializable (no circular refs / functions /
+ *     bigints), since it's persisted as a JSON column.
  *
- *   - Each value must declare `target_tag` (non-empty string) and
- *     `cardinality` from the named vocabulary.
- *   - `description` is optional, must be a string when present.
- *   - Relationship keys must be non-empty strings.
+ * Returns the value verbatim (round-trips through JSON.parse(JSON.stringify)
+ * to both prove serializability and strip anything non-serializable). The
+ * historical typed shape `{ target_tag, cardinality }` is a valid opaque map,
+ * so this is a backwards-compatible superset — existing typed declarations
+ * and callers keep working unchanged.
+ *
+ * Phase 1 was already informational ("declarations are not enforced at write
+ * time"); dropping the inner-shape gate is consistent with that intent.
  */
-export function validateRelationships(
-  raw: unknown,
-): Record<string, TagRelationship> {
+export function validateRelationships(raw: unknown): Record<string, unknown> {
   if (raw === null || raw === undefined) {
     throw new Error("relationships: expected an object, got null/undefined");
   }
   if (typeof raw !== "object" || Array.isArray(raw)) {
-    throw new Error("relationships: expected an object mapping rel name → declaration");
+    throw new Error(
+      "relationships: expected an object mapping relationship name → value (got an array or primitive)",
+    );
   }
-  const out: Record<string, TagRelationship> = {};
-  for (const [rel, decl] of Object.entries(raw as Record<string, unknown>)) {
-    if (!rel || typeof rel !== "string") {
+  for (const rel of Object.keys(raw as Record<string, unknown>)) {
+    if (!rel) {
       throw new Error("relationships: keys must be non-empty strings");
     }
-    if (!decl || typeof decl !== "object" || Array.isArray(decl)) {
-      throw new Error(`relationships["${rel}"]: declaration must be an object`);
-    }
-    const d = decl as Record<string, unknown>;
-    if (typeof d.target_tag !== "string" || d.target_tag.length === 0) {
-      throw new Error(`relationships["${rel}"]: target_tag must be a non-empty string`);
-    }
-    const card = d.cardinality;
-    if (typeof card !== "string" || !TAG_REL_CARDINALITIES.includes(card as TagRelCardinality)) {
-      throw new Error(
-        `relationships["${rel}"]: cardinality must be one of ${TAG_REL_CARDINALITIES.join(" | ")}; got ${JSON.stringify(card)}`,
-      );
-    }
-    if (d.description !== undefined && typeof d.description !== "string") {
-      throw new Error(`relationships["${rel}"]: description must be a string when set`);
-    }
-    out[rel] = {
-      target_tag: d.target_tag,
-      cardinality: card as TagRelCardinality,
-      ...(d.description !== undefined ? { description: d.description as string } : {}),
-    };
   }
-  return out;
+  // Round-trip through JSON to (a) confirm the payload is serializable —
+  // the column is stored as JSON — and (b) return a clean, owned copy with
+  // no non-JSON values lingering. Throws on circular refs / bigint / etc.
+  let serialized: string;
+  try {
+    serialized = JSON.stringify(raw);
+  } catch (err) {
+    throw new Error(`relationships: value must be JSON-serializable (${(err as Error).message})`);
+  }
+  return JSON.parse(serialized) as Record<string, unknown>;
 }
 
 // ---------------------------------------------------------------------------
@@ -287,7 +302,7 @@ function rowToRecord(row: TagRow): TagRecord {
     tag: row.name,
     description: row.description ?? undefined,
     fields: parseJson<Record<string, TagFieldSchema>>(row.fields),
-    relationships: parseJson<Record<string, TagRelationship>>(row.relationships),
+    relationships: parseJson<TagRelationshipMap>(row.relationships),
     parent_names: parseJson<string[]>(row.parent_names),
     created_at: row.created_at ?? undefined,
     updated_at: row.updated_at ?? undefined,

package/core/src/triggers-store.test.ts

@@ -0,0 +1,100 @@
+/**
+ * Unit tests for the persisted-triggers store (core/src/triggers-store.ts) —
+ * JSON encode/decode round-trip + upsert/list/get/delete semantics over an
+ * in-memory SQLite DB (schema v21).
+ */
+
+import { describe, test, expect, beforeEach } from "bun:test";
+import { Database } from "bun:sqlite";
+import { initSchema } from "./schema.js";
+import {
+  upsertTrigger,
+  listTriggers,
+  getTrigger,
+  deleteTrigger,
+  loadAllTriggers,
+} from "./triggers-store.js";
+
+let db: Database;
+
+beforeEach(() => {
+  db = new Database(":memory:");
+  initSchema(db);
+});
+
+function sample(name: string) {
+  return {
+    name,
+    events: ["created", "updated"] as Array<"created" | "updated">,
+    when: { tags: ["channel-message"], has_content: true },
+    action: {
+      webhook: "https://example.test/hook",
+      send: "json" as const,
+      timeout: 30000,
+      auth: { bearer: "jwt-token" },
+    },
+  };
+}
+
+describe("triggers-store", () => {
+  test("the triggers table exists after initSchema (v21)", () => {
+    const row = db
+      .prepare("SELECT name FROM sqlite_master WHERE type='table' AND name='triggers'")
+      .get();
+    expect(row).toBeTruthy();
+  });
+
+  test("upsert → get round-trips the structured JSON columns", () => {
+    upsertTrigger(db, sample("inbound"));
+    const got = getTrigger(db, "inbound");
+    expect(got).not.toBeNull();
+    expect(got!.when).toEqual({ tags: ["channel-message"], has_content: true });
+    expect(got!.action.webhook).toBe("https://example.test/hook");
+    expect(got!.action.auth).toEqual({ bearer: "jwt-token" });
+    expect(got!.events).toEqual(["created", "updated"]);
+    expect(got!.created_at).toBeTruthy();
+    expect(got!.updated_at).toBeTruthy();
+  });
+
+  test("upsert by name replaces + preserves created_at, bumps updated_at", async () => {
+    const first = upsertTrigger(db, sample("inbound"));
+    // Ensure clock advances so updated_at differs.
+    await new Promise((r) => setTimeout(r, 5));
+    const second = upsertTrigger(db, {
+      ...sample("inbound"),
+      action: { webhook: "https://example.test/v2" },
+    });
+
+    expect(listTriggers(db)).toHaveLength(1);
+    expect(second.created_at).toBe(first.created_at);
+    expect(second.updated_at >= first.updated_at).toBe(true);
+    expect(getTrigger(db, "inbound")!.action.webhook).toBe("https://example.test/v2");
+  });
+
+  test("events defaults to [created, updated] when omitted", () => {
+    upsertTrigger(db, {
+      name: "no-events",
+      when: { tags: ["x"] },
+      action: { webhook: "https://example.test/hook" },
+    });
+    expect(getTrigger(db, "no-events")!.events).toEqual(["created", "updated"]);
+  });
+
+  test("list / loadAllTriggers return all rows ordered by name", () => {
+    upsertTrigger(db, sample("zebra"));
+    upsertTrigger(db, sample("alpha"));
+    expect(listTriggers(db).map((t) => t.name)).toEqual(["alpha", "zebra"]);
+    expect(loadAllTriggers(db).map((t) => t.name)).toEqual(["alpha", "zebra"]);
+  });
+
+  test("delete removes the row; returns false on a missing name", () => {
+    upsertTrigger(db, sample("inbound"));
+    expect(deleteTrigger(db, "inbound")).toBe(true);
+    expect(getTrigger(db, "inbound")).toBeNull();
+    expect(deleteTrigger(db, "inbound")).toBe(false);
+  });
+
+  test("getTrigger returns null for an unknown name", () => {
+    expect(getTrigger(db, "nope")).toBeNull();
+  });
+});

package/core/src/triggers-store.ts

@@ -0,0 +1,165 @@
+/**
+ * Persisted runtime triggers — per-vault CRUD over the `triggers` table
+ * (schema v21).
+ *
+ * Complements the static `config.yaml` trigger system: config.yaml triggers
+ * are loaded at boot and fire globally (all vaults); rows in this table live
+ * in a single vault's SQLite DB and are re-registered at boot scoped to that
+ * vault (they fire ONLY for events on the vault they were stored under).
+ *
+ * The structured columns (`events`, `when`, `action`) are JSON-encoded on
+ * write and parsed on read. `name` is the primary key, so `upsertTrigger`
+ * is a true upsert (insert-or-replace by name). The shape here is kept
+ * structurally compatible with `src/config.ts`'s `TriggerConfig` /
+ * `TriggerWhen` / `TriggerAction` without importing from `src/` — core stays
+ * dependency-free of the server layer.
+ *
+ * `action.auth.bearer`, when present, becomes an `Authorization: Bearer`
+ * header on the webhook POST (the JWT webhook-auth path that retires the
+ * old `?secret=` query param). It is stored verbatim in the JSON column.
+ */
+
+import type { Database } from "bun:sqlite";
+
+/** Predicate shape — mirrors src/config.ts:TriggerWhen. */
+export interface StoredTriggerWhen {
+  tags?: string[];
+  has_content?: boolean;
+  missing_metadata?: string[];
+  has_metadata?: string[];
+}
+
+/** Webhook auth — only the bearer-JWT path for now. */
+export interface StoredTriggerAuth {
+  bearer?: string;
+}
+
+/** Action shape — mirrors src/config.ts:TriggerAction plus `auth`. */
+export interface StoredTriggerAction {
+  webhook: string;
+  timeout?: number;
+  send?: "json" | "attachment" | "content";
+  auth?: StoredTriggerAuth;
+  // Forward-compat: include_context and any other action fields round-trip
+  // through the JSON column verbatim even though core doesn't interpret them.
+  [key: string]: unknown;
+}
+
+/** A persisted trigger row, decoded. */
+export interface StoredTrigger {
+  name: string;
+  events: Array<"created" | "updated">;
+  when: StoredTriggerWhen;
+  action: StoredTriggerAction;
+  created_at: string;
+  updated_at: string;
+}
+
+/** The writable subset callers pass to upsert. */
+export interface TriggerInput {
+  name: string;
+  events?: Array<"created" | "updated">;
+  when: StoredTriggerWhen;
+  action: StoredTriggerAction;
+}
+
+interface TriggerRow {
+  name: string;
+  events: string;
+  when: string;
+  action: string;
+  created_at: string;
+  updated_at: string;
+}
+
+function decodeRow(row: TriggerRow): StoredTrigger {
+  return {
+    name: row.name,
+    events: safeParse(row.events, ["created", "updated"]) as Array<"created" | "updated">,
+    when: safeParse(row.when, {}) as StoredTriggerWhen,
+    action: safeParse(row.action, { webhook: "" }) as StoredTriggerAction,
+    created_at: row.created_at,
+    updated_at: row.updated_at,
+  };
+}
+
+function safeParse(json: string, fallback: unknown): unknown {
+  try {
+    return JSON.parse(json);
+  } catch {
+    return fallback;
+  }
+}
+
+/**
+ * Insert or replace a trigger by name. Preserves `created_at` on update
+ * (re-fetches the existing row's timestamp) and stamps a fresh `updated_at`.
+ * Returns the stored shape.
+ */
+export function upsertTrigger(db: Database, input: TriggerInput): StoredTrigger {
+  const now = new Date().toISOString();
+  const existing = db
+    .prepare("SELECT created_at FROM triggers WHERE name = ?")
+    .get(input.name) as { created_at: string } | null;
+  const createdAt = existing?.created_at ?? now;
+  const events = input.events ?? ["created", "updated"];
+
+  db.prepare(
+    `INSERT INTO triggers (name, events, "when", action, created_at, updated_at)
+     VALUES (?, ?, ?, ?, ?, ?)
+     ON CONFLICT(name) DO UPDATE SET
+       events = excluded.events,
+       "when" = excluded."when",
+       action = excluded.action,
+       updated_at = excluded.updated_at`,
+  ).run(
+    input.name,
+    JSON.stringify(events),
+    JSON.stringify(input.when),
+    JSON.stringify(input.action),
+    createdAt,
+    now,
+  );
+
+  return {
+    name: input.name,
+    events,
+    when: input.when,
+    action: input.action,
+    created_at: createdAt,
+    updated_at: now,
+  };
+}
+
+/** List all persisted triggers for this vault, ordered by name. */
+export function listTriggers(db: Database): StoredTrigger[] {
+  const rows = db
+    .prepare(
+      `SELECT name, events, "when", action, created_at, updated_at
+       FROM triggers ORDER BY name`,
+    )
+    .all() as TriggerRow[];
+  return rows.map(decodeRow);
+}
+
+/** Fetch a single trigger by name, or null. */
+export function getTrigger(db: Database, name: string): StoredTrigger | null {
+  const row = db
+    .prepare(
+      `SELECT name, events, "when", action, created_at, updated_at
+       FROM triggers WHERE name = ?`,
+    )
+    .get(name) as TriggerRow | null;
+  return row ? decodeRow(row) : null;
+}
+
+/** Delete a trigger by name. Returns true if a row was removed. */
+export function deleteTrigger(db: Database, name: string): boolean {
+  const res = db.prepare("DELETE FROM triggers WHERE name = ?").run(name);
+  return res.changes > 0;
+}
+
+/** Load all persisted triggers (boot path). Alias of listTriggers for clarity. */
+export function loadAllTriggers(db: Database): StoredTrigger[] {
+  return listTriggers(db);
+}

package/core/src/types.ts

@@ -1,10 +1,13 @@
-import type { TagFieldSchema, TagRelationship, TagRecord } from "./tag-schemas.js";
+import type { Database } from "bun:sqlite";
+import type { TagFieldSchema, TagRelationship, TagRelationshipMap, TagRecord } from "./tag-schemas.js";
 import type { PrunedField } from "./indexed-fields.js";
+import type { TagExpandMode } from "./tag-hierarchy.js";
 
 // ---- Re-exports ----
 
-export type { TagFieldSchema, TagRelationship, TagRecord } from "./tag-schemas.js";
+export type { TagFieldSchema, TagRelationship, TagRelationshipMap, TagRecord } from "./tag-schemas.js";
 export type { PrunedField } from "./indexed-fields.js";
+export type { TagExpandMode } from "./tag-hierarchy.js";
 
 // ---- Note ----
 
@@ -25,6 +28,14 @@ export interface Note {
   updatedAt?: string;
   tags?: string[];
   links?: Link[];
+  /**
+   * Opt-in link degree (raw row count, both directions by default). Present
+   * only when the caller requests it via `include_link_count` (REST/MCP).
+   * Surfaced the same way `links`/`attachments` are — an extra key injected
+   * onto the response after the base shape. See `getLinkCounts` in links.ts
+   * for the exact degree semantics (self-loop = 2 under `both`).
+   */
+  linkCount?: number;
 }
 
 // ---- Link ----
@@ -59,6 +70,16 @@ export interface VaultStats {
   tagCount: number;
   attachmentCount: number;
   linkCount: number;
+  /**
+   * Total bytes of all note content, computed as the sum of the UTF-8 byte
+   * length of every note's `content`. The SQL uses `LENGTH(CAST(content AS
+   * BLOB))` deliberately: SQLite's bare `LENGTH(text)` returns the number of
+   * *characters*, not bytes, so a note full of multibyte UTF-8 (emoji, CJK,
+   * accents) would undercount its true on-disk/on-wire footprint. Casting to
+   * BLOB forces `LENGTH` to count raw bytes. This is the logical content size,
+   * not the physical DB-file size (see `usage.ts:dbBytes` for the latter).
+   */
+  contentBytes: number;
 }
 
 // ---- Query Options ----
@@ -66,6 +87,18 @@ export interface VaultStats {
 export interface QueryOpts {
   tags?: string[];
   tagMatch?: "all" | "any"; // "all" = must have ALL tags (default), "any" = must have ANY tag
+  /**
+   * Tag-expansion axis (vault tag `expand` axis — design
+   * `design/2026-06-09-tag-expand-axis.md`). Selects how each `tags` entry
+   * expands:
+   * - `"subtypes"` (DEFAULT): tag ∪ `parent_names` descendants. Today's
+   *   semantic is-a behavior, unchanged. `_default` universal magic fires here.
+   * - `"namespace"`: tag ∪ lexically name-prefixed `tag/*` (the filing axis).
+   * - `"both"`: union of subtypes + namespace.
+   * - `"exact"`: the literal tag only, no expansion.
+   * Absent → `"subtypes"` → byte-identical to pre-axis behavior.
+   */
+  expand?: TagExpandMode;
   excludeTags?: string[];
   // Presence filters. `true` → has at least one; `false` → has none.
   // When `tags` is also set, `hasTags` is ignored (the tag filter already constrains the set).
@@ -115,6 +148,12 @@ export interface QueryOpts {
   // declared `indexed: true`; errors loudly otherwise. Direction is taken
   // from `sort` (default "asc") and `created_at` is appended as a stable
   // tiebreaker.
+  //
+  // The pseudo-field `link_count` is special-cased (no indexed-field
+  // declaration needed): it sorts by link DEGREE — the both-directions
+  // raw row count — using the same directional-sum definition as the
+  // `linkCount` response field, so the sort key equals the field value for
+  // every note (self-loops included). See `queryNotes`/`getLinkCounts`.
   orderBy?: string;
   limit?: number;
   offset?: number;
@@ -153,6 +192,8 @@ export interface NoteSummary {
   createdAt: string;
   updatedAt?: string;
   tags?: string[];
+  /** Opt-in link degree (see `Note.linkCount`). */
+  linkCount?: number;
 }
 
 /**
@@ -169,6 +210,8 @@ export interface NoteIndex {
   metadata?: Record<string, unknown>;
   byteSize: number;
   preview: string;
+  /** Opt-in link degree (see `Note.linkCount`). */
+  linkCount?: number;
 }
 
 /** Link with hydrated note summaries. */
@@ -180,6 +223,15 @@ export interface HydratedLink extends Link {
 // ---- Store Interface ----
 
 export interface Store {
+  /**
+   * The underlying `bun:sqlite` handle. Exposed (read-only) so callers that
+   * need to run a raw query the Store interface doesn't surface — e.g. the
+   * token-table reverse-lookups in routes.ts and MCP tool generation in
+   * mcp.ts — can reach it without an `(store as any).db` cast. The concrete
+   * `Store` class declares this as `public readonly db: Database`. See vault#242.
+   */
+  readonly db: Database;
+
   // Notes
   createNote(content: string, opts?: { id?: string; path?: string; tags?: string[]; metadata?: Record<string, unknown>; created_at?: string; extension?: string }): Promise<Note>;
   getNote(id: string): Promise<Note | null>;
@@ -218,7 +270,7 @@ export interface Store {
    * agent loop can persist a single watermark and keep polling.
    */
   queryNotesPaged(opts: QueryOpts): Promise<QueryNotesPage>;
-  searchNotes(query: string, opts?: { tags?: string[]; limit?: number }): Promise<Note[]>;
+  searchNotes(query: string, opts?: { tags?: string[]; limit?: number; expand?: TagExpandMode }): Promise<Note[]>;
 
   // Tags
   tagNote(noteId: string, tags: string[]): Promise<void>;
@@ -230,6 +282,18 @@ export interface Store {
    * compute the effective allowlisted tag-set at auth time.
    */
   expandTagsWithDescendants(tags: string[]): Promise<Set<string>>;
+  /**
+   * Mode-aware tag expansion (vault tag `expand` axis). Expands each input tag
+   * along the selected axis and returns the union:
+   * - `"subtypes"` (default): `{tag} ∪ parent_names-descendants` — identical to
+   *   `expandTagsWithDescendants` (which is a thin shim over this).
+   * - `"namespace"`: `{tag} ∪ lexically name-prefixed tag/*`.
+   * - `"both"`: union of the two.
+   * - `"exact"`: `{tag}` only.
+   * Always includes each input tag. Used by the live-query matcher to lower the
+   * IDENTICAL expansion the snapshot query engine uses for the same `expand`.
+   */
+  expandTags(tags: string[], mode?: TagExpandMode): Promise<Set<string>>;
   listTags(): Promise<{ name: string; count: number }[]>;
   deleteTag(name: string): Promise<{ deleted: boolean; notes_untagged: number }>;
   renameTag(
@@ -313,7 +377,7 @@ export interface Store {
     patch: {
       description?: string | null;
       fields?: Record<string, TagFieldSchema> | null;
-      relationships?: Record<string, TagRelationship> | null;
+      relationships?: TagRelationshipMap | null;
       parent_names?: string[] | null;
     },
   ): Promise<TagRecord>;

package/core/src/vault-projection.ts

@@ -305,5 +305,25 @@ 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.");
 
+  // 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
+  // lean (token-budget note above). Uses the concrete vault name so the mint
+  // command is copy-paste ready.
+  lines.push("");
+  lines.push("## Scripting & automation (beyond this session)");
+  lines.push("");
+  lines.push(
+    "This vault is also a plain HTTP API — reach for it when the user wants a script, cron job, or CI step rather than an interactive session:",
+  );
+  lines.push(
+    `- Mint a scoped credential: \`parachute auth mint-token --scope vault:${vaultName}:read --ephemeral\` (\`--ephemeral\` = short-lived, ideal for scripts; use \`:write\` to create/edit).`,
+  );
+  lines.push(`- Call the REST API at \`<hub-origin>/vault/${vaultName}/api/...\`.`);
+  lines.push(
+    "- Full guide — copy-paste bash/Python/JS examples, plus how to design tags vs paths vs schemas: https://parachute.computer/scripting/",
+  );
+  lines.push("- For a prompt on a schedule with no code, see Parachute Runner.");
+
   return lines.join("\n");
 }

package/core/src/wikilinks.ts

@@ -137,7 +137,7 @@ export function resolveWikilink(db: Database, target: string): string | null {
     const extPart = extMatch[2]!.toLowerCase();
     const explicit = db.prepare(
       "SELECT id FROM notes WHERE path = ? COLLATE NOCASE AND LOWER(extension) = ?",
-    ).get(pathPart, extPart) as { id: string } | undefined;
+    ).get(pathPart, extPart) as { id: string } | null;
     if (explicit) return explicit.id;
     // No match for explicit (path, ext) — fall through to the looser
     // rules so a literal note named `Recipe.v2` (where `v2` isn't an
@@ -199,7 +199,7 @@ export function resolveWikilinkDetailed(db: Database, target: string): WikilinkR
     const extPart = extMatch[2]!.toLowerCase();
     const explicit = db.prepare(
       "SELECT id, path FROM notes WHERE path = ? COLLATE NOCASE AND LOWER(extension) = ?",
-    ).get(pathPart, extPart) as { id: string; path: string } | undefined;
+    ).get(pathPart, extPart) as { id: string; path: string } | null;
     if (explicit) {
       return { resolved: true, note_id: explicit.id, path: explicit.path, candidates: [] };
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openparachute/vault",
-  "version": "0.6.0-rc.1",
+  "version": "0.6.1",
   "description": "Agent-native knowledge graph. Notes, tags, links over MCP.",
   "module": "src/cli.ts",
   "type": "module",
@@ -22,12 +22,11 @@
     "test:core": "cd core && node --experimental-vm-modules node_modules/vitest/dist/cli.js run",
     "typecheck": "tsc --noEmit",
     "build:spa": "cd web/ui && bun install --frozen-lockfile && bun run build",
-    "postinstall": "if [ -d web/ui ]; then bun run build:spa; fi",
     "prepack": "bun run build:spa"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.1",
-    "@openparachute/scope-guard": "^0.4.0-rc.2",
+    "@openparachute/scope-guard": "^0.4.1-rc.1",
     "jose": "^6.2.2",
     "otpauth": "^9.5.0",
     "qrcode-terminal": "^0.12.0"