@openparachute/vault 0.7.3-rc.9 → 0.7.3

package/src/config.test.ts

@@ -344,6 +344,22 @@ describe("config", () => {
     expect(readGlobalConfig().autostart).toBe(false);
   });
 
+  test("round-trips embeddings_enabled: true|false (semantic-search opt-in, 0.7.3)", () => {
+    // Absent means off — semantic search is opt-in as of 0.7.3. The key is
+    // only persisted when explicitly set (the self-host settings toggle).
+    writeGlobalConfig({ port: 1940 });
+    expect(readGlobalConfig().embeddings_enabled).toBeUndefined();
+
+    // Explicit true — the operator turned semantic search on without editing
+    // the env file; getSharedEmbeddingProvider threads this in as the default.
+    writeGlobalConfig({ port: 1940, embeddings_enabled: true });
+    expect(readGlobalConfig().embeddings_enabled).toBe(true);
+
+    // Explicit false — persisted opt-out (distinct from absent for clarity).
+    writeGlobalConfig({ port: 1940, embeddings_enabled: false });
+    expect(readGlobalConfig().embeddings_enabled).toBe(false);
+  });
+
   test("round-trips default_mirror: internal|off", () => {
     // Absent: createVault falls back to the in-code default ("internal" —
     // backup-on-by-default). The knob is only persisted when explicitly set.

package/src/config.ts

@@ -387,6 +387,18 @@ export interface GlobalConfig {
     /** Master toggle. Default false; the worker is a no-op when unset. */
     enabled?: boolean;
   };
+  /**
+   * Semantic-search opt-in (0.7.3, Aaron-ratified). Semantic search is OFF
+   * by default; set this to `true` to build the embedding provider and turn
+   * on embed-on-write + the backfill sweep. This is the persisted,
+   * settings-surface-friendly toggle a self-host operator flips without
+   * editing the env file. The `EMBEDDINGS_ENABLED` env var is the low-level
+   * OVERRIDE (`true`/`1` forces on, `false`/`0` forces off, anything else
+   * defers here) — see `src/embedding/select.ts`'s `resolveEmbeddingsEnabled`.
+   * Unset ⇒ off. Takes effect on server (re)start, since the process shares
+   * one embedding provider resolved at boot.
+   */
+  embeddings_enabled?: boolean;
 }
 
 // ---------------------------------------------------------------------------
@@ -1308,6 +1320,7 @@ export function readGlobalConfig(): GlobalConfig {
       const discoveryMatch = yaml.match(/^discovery:\s*(enabled|disabled)/m);
       const autostartMatch = yaml.match(/^autostart:\s*(true|false)/m);
       const autoCreateMatch = yaml.match(/^auto_create:\s*(true|false)/m);
+      const embeddingsEnabledMatch = yaml.match(/^embeddings_enabled:\s*(true|false)/m);
       const defaultMirrorMatch = yaml.match(/^default_mirror:\s*(internal|off)/m);
       // auto_transcribe block — currently single boolean `enabled` (vault#353).
       // Parsed as a nested 2-space-indent block so future fields can grow under
@@ -1340,6 +1353,9 @@ export function readGlobalConfig(): GlobalConfig {
       if (autoCreateMatch) {
         config.auto_create = autoCreateMatch[1]! === "true";
       }
+      if (embeddingsEnabledMatch) {
+        config.embeddings_enabled = embeddingsEnabledMatch[1]! === "true";
+      }
       if (defaultMirrorMatch) {
         config.default_mirror = defaultMirrorMatch[1]! as "internal" | "off";
       }
@@ -1416,6 +1432,7 @@ export function writeGlobalConfig(config: GlobalConfig): void {
   if (config.discovery) lines.push(`discovery: ${config.discovery}`);
   if (config.autostart !== undefined) lines.push(`autostart: ${config.autostart}`);
   if (config.auto_create !== undefined) lines.push(`auto_create: ${config.auto_create}`);
+  if (config.embeddings_enabled !== undefined) lines.push(`embeddings_enabled: ${config.embeddings_enabled}`);
   if (config.default_mirror) lines.push(`default_mirror: ${config.default_mirror}`);
   if (config.owner_password_hash) {
     lines.push(`owner_password_hash: "${config.owner_password_hash}"`);

package/src/embedding/select.test.ts

@@ -2,7 +2,8 @@ import { describe, test, expect } from "bun:test";
 import {
   resolveEmbeddingApiConfig,
   buildEmbeddingProvider,
-  embeddingsExplicitlyDisabled,
+  embeddingsEnabledEnvOverride,
+  resolveEmbeddingsEnabled,
   DEFAULT_EXTERNAL_EMBEDDING_MODEL,
 } from "./select.ts";
 import { ExternalApiEmbeddingProvider } from "./external-api.ts";
@@ -29,71 +30,98 @@ describe("resolveEmbeddingApiConfig", () => {
   });
 });
 
-describe("buildEmbeddingProvider — two-tier selection", () => {
+describe("buildEmbeddingProvider — two-tier selection (once ENABLED)", () => {
+  // Semantic search is opt-in as of 0.7.3, so every case here enables it
+  // (via the env override) before asserting WHICH tier is selected.
   test("zero-config: no EMBEDDING_API_URL -> the bundled floor (onnx-transformers)", () => {
-    const provider = buildEmbeddingProvider({});
+    const provider = buildEmbeddingProvider({ EMBEDDINGS_ENABLED: "true" });
     expect(provider).toBeInstanceOf(OnnxTransformersEmbeddingProvider);
   });
 
   test("EMBEDDING_API_URL set -> the config upgrade tier (external-api) wins", () => {
-    const provider = buildEmbeddingProvider({ EMBEDDING_API_URL: "http://localhost:11434/v1" });
+    const provider = buildEmbeddingProvider({ EMBEDDINGS_ENABLED: "true", EMBEDDING_API_URL: "http://localhost:11434/v1" });
     expect(provider).toBeInstanceOf(ExternalApiEmbeddingProvider);
-    expect(provider.model).toBe(DEFAULT_EXTERNAL_EMBEDDING_MODEL);
+    expect(provider!.model).toBe(DEFAULT_EXTERNAL_EMBEDDING_MODEL);
   });
 
   test("EMBEDDING_MODEL alone (no URL) has no effect — still the bundled floor", () => {
-    const provider = buildEmbeddingProvider({ EMBEDDING_MODEL: "bge-m3" });
+    const provider = buildEmbeddingProvider({ EMBEDDINGS_ENABLED: "true", EMBEDDING_MODEL: "bge-m3" });
     expect(provider).toBeInstanceOf(OnnxTransformersEmbeddingProvider);
   });
 
   test("an explicit EMBEDDING_MODEL overrides the config-tier default", () => {
     const provider = buildEmbeddingProvider({
+      EMBEDDINGS_ENABLED: "true",
       EMBEDDING_API_URL: "http://x",
       EMBEDDING_MODEL: "nomic-embed-text",
     });
-    expect(provider.model).toBe("nomic-embed-text");
+    expect(provider!.model).toBe("nomic-embed-text");
   });
 });
 
-describe("embeddingsExplicitlyDisabled — the EMBEDDINGS_ENABLED off switch (M1)", () => {
-  test("false only for the literal string \"false\"", () => {
-    expect(embeddingsExplicitlyDisabled({ EMBEDDINGS_ENABLED: "false" })).toBe(true);
+describe("embeddingsEnabledEnvOverride — the EMBEDDINGS_ENABLED tri-state override", () => {
+  test("\"true\"/\"1\" force ON (case-insensitive, trimmed)", () => {
+    expect(embeddingsEnabledEnvOverride({ EMBEDDINGS_ENABLED: "true" })).toBe(true);
+    expect(embeddingsEnabledEnvOverride({ EMBEDDINGS_ENABLED: "TRUE" })).toBe(true);
+    expect(embeddingsEnabledEnvOverride({ EMBEDDINGS_ENABLED: "  1  " })).toBe(true);
   });
 
-  test("case-insensitive and trims whitespace", () => {
-    expect(embeddingsExplicitlyDisabled({ EMBEDDINGS_ENABLED: "FALSE" })).toBe(true);
-    expect(embeddingsExplicitlyDisabled({ EMBEDDINGS_ENABLED: "  false  " })).toBe(true);
+  test("\"false\"/\"0\" force OFF (case-insensitive, trimmed)", () => {
+    expect(embeddingsEnabledEnvOverride({ EMBEDDINGS_ENABLED: "false" })).toBe(false);
+    expect(embeddingsEnabledEnvOverride({ EMBEDDINGS_ENABLED: "FALSE" })).toBe(false);
+    expect(embeddingsEnabledEnvOverride({ EMBEDDINGS_ENABLED: "  0  " })).toBe(false);
   });
 
-  test("unset defaults to enabled (not disabled)", () => {
-    expect(embeddingsExplicitlyDisabled({})).toBe(false);
+  test("unset / blank / unrecognized → undefined (defer to the persisted setting)", () => {
+    expect(embeddingsEnabledEnvOverride({})).toBeUndefined();
+    expect(embeddingsEnabledEnvOverride({ EMBEDDINGS_ENABLED: "" })).toBeUndefined();
+    expect(embeddingsEnabledEnvOverride({ EMBEDDINGS_ENABLED: "  " })).toBeUndefined();
+    expect(embeddingsEnabledEnvOverride({ EMBEDDINGS_ENABLED: "yes" })).toBeUndefined();
+  });
+});
+
+describe("resolveEmbeddingsEnabled — env override, else persisted, else OFF", () => {
+  test("defaults OFF when neither env nor persisted setting is present (opt-in)", () => {
+    expect(resolveEmbeddingsEnabled({})).toBe(false);
+    expect(resolveEmbeddingsEnabled({}, undefined)).toBe(false);
+  });
+
+  test("persisted setting decides when the env var is absent", () => {
+    expect(resolveEmbeddingsEnabled({}, true)).toBe(true);
+    expect(resolveEmbeddingsEnabled({}, false)).toBe(false);
+  });
+
+  test("env override wins over the persisted setting in BOTH directions", () => {
+    expect(resolveEmbeddingsEnabled({ EMBEDDINGS_ENABLED: "false" }, true)).toBe(false);
+    expect(resolveEmbeddingsEnabled({ EMBEDDINGS_ENABLED: "true" }, false)).toBe(true);
   });
 
-  test("\"true\" (and any other value) is enabled — this var is an off switch, not an opt-in", () => {
-    expect(embeddingsExplicitlyDisabled({ EMBEDDINGS_ENABLED: "true" })).toBe(false);
-    expect(embeddingsExplicitlyDisabled({ EMBEDDINGS_ENABLED: "0" })).toBe(false);
-    expect(embeddingsExplicitlyDisabled({ EMBEDDINGS_ENABLED: "no" })).toBe(false);
+  test("an unrecognized env value defers to the persisted setting (not a guess)", () => {
+    expect(resolveEmbeddingsEnabled({ EMBEDDINGS_ENABLED: "maybe" }, true)).toBe(true);
+    expect(resolveEmbeddingsEnabled({ EMBEDDINGS_ENABLED: "maybe" }, false)).toBe(false);
   });
 });
 
-describe("buildEmbeddingProvider — EMBEDDINGS_ENABLED=false (M1)", () => {
-  test("returns undefined even when the config-upgrade tier is otherwise fully configured", () => {
-    const provider = buildEmbeddingProvider({
-      EMBEDDINGS_ENABLED: "false",
-      EMBEDDING_API_URL: "http://localhost:11434/v1",
-      EMBEDDING_MODEL: "bge-m3",
-    });
-    expect(provider).toBeUndefined();
+describe("buildEmbeddingProvider — opt-in gate (0.7.3)", () => {
+  test("DEFAULT off: no provider when nothing enables it (unset env, no persisted setting)", () => {
+    expect(buildEmbeddingProvider({})).toBeUndefined();
+    expect(buildEmbeddingProvider({ EMBEDDING_API_URL: "http://localhost:11434/v1", EMBEDDING_MODEL: "bge-m3" })).toBeUndefined();
   });
 
-  test("returns undefined for the zero-config (bundled-floor) case too", () => {
-    expect(buildEmbeddingProvider({ EMBEDDINGS_ENABLED: "false" })).toBeUndefined();
+  test("EMBEDDINGS_ENABLED=false forces off even with the persisted setting on", () => {
+    expect(buildEmbeddingProvider({ EMBEDDINGS_ENABLED: "false" }, { persistedEnabled: true })).toBeUndefined();
   });
 
-  test("EMBEDDINGS_ENABLED=true (or unset) is unaffected — both tiers still resolve normally", () => {
+  test("EMBEDDINGS_ENABLED=true (or =1) enables — both tiers then resolve normally", () => {
     expect(buildEmbeddingProvider({ EMBEDDINGS_ENABLED: "true" })).toBeInstanceOf(OnnxTransformersEmbeddingProvider);
+    expect(buildEmbeddingProvider({ EMBEDDINGS_ENABLED: "1" })).toBeInstanceOf(OnnxTransformersEmbeddingProvider);
     expect(
       buildEmbeddingProvider({ EMBEDDINGS_ENABLED: "true", EMBEDDING_API_URL: "http://x" }),
     ).toBeInstanceOf(ExternalApiEmbeddingProvider);
   });
+
+  test("the persisted setting alone enables it (the self-host settings toggle, no env var)", () => {
+    expect(buildEmbeddingProvider({}, { persistedEnabled: true })).toBeInstanceOf(OnnxTransformersEmbeddingProvider);
+    expect(buildEmbeddingProvider({}, { persistedEnabled: false })).toBeUndefined();
+  });
 });

package/src/embedding/select.ts

@@ -17,15 +17,28 @@
  *     in-process. This is what makes semantic search work on a fresh
  *     install with no operator action.
  *
- * **Off switch:** `EMBEDDINGS_ENABLED=false` short-circuits BOTH tiers —
- * `buildEmbeddingProvider` returns `undefined` regardless of what else is
- * configured. Mirrors the `EMBEDDINGS_ENABLED` wrangler var C2 (cloud)
- * plans for the same gate. A caller wired against an `undefined` provider
- * (see `Store.embeddingProvider`) reports the `embeddings` capability as
+ * **Opt-in gate (0.7.3, Aaron-ratified):** semantic search is OFF by
+ * default. `buildEmbeddingProvider` returns a provider ONLY when the
+ * feature is explicitly enabled — otherwise it returns `undefined` and
+ * BOTH tiers are short-circuited. The enable signal is resolved with a
+ * two-level precedence (see `resolveEmbeddingsEnabled`):
+ *
+ *   1. **`EMBEDDINGS_ENABLED` env var** — the low-level override. `true`/`1`
+ *      forces ON, `false`/`0` forces OFF, anything else (incl. unset)
+ *      defers to the persisted setting. Mirrors the cloud wrangler var.
+ *   2. **Persisted `embeddings_enabled`** (config.yaml, wired in by the
+ *      caller — see `getSharedEmbeddingProvider`) — the self-host settings
+ *      toggle, so an operator can turn semantic search on without editing
+ *      the env file. Defaults OFF when unset.
+ *
+ * A caller wired against an `undefined` provider (see
+ * `Store.embeddingProvider`) reports the `embeddings` capability as
  * disabled and `semanticSearch` throws `semantic_unavailable` — the exact
  * same honest-failure path as "no provider configured" (never a silent
  * keyword fallback). The embed-on-write drain simply has nothing to
- * invoke, so it no-ops.
+ * invoke, so it no-ops — no hook work, no backfill sweep, and (because the
+ * ~270MB `@huggingface/transformers` import is dynamic and only happens
+ * inside a real `embed()` call) no model download until a user opts in.
  *
  * `EMBEDDING_MODEL` alone (no `EMBEDDING_API_URL`) has no effect — it only
  * shapes the config-upgrade tier. Resolved per-call (not cached here) so
@@ -58,28 +71,56 @@ export function resolveEmbeddingApiConfig(env: NodeJS.ProcessEnv = process.env):
 }
 
 /**
- * `true` only when `EMBEDDINGS_ENABLED` is explicitly the literal string
- * `"false"` (case-insensitive, trimmed) — the off switch. Every other
- * value, INCLUDING unset, is "enabled": the feature defaults ON (the
- * bundled floor tier makes that safe — zero-config still works), and this
- * var exists to opt OUT, not to opt in.
+ * Parse `EMBEDDINGS_ENABLED` as an explicit tri-state OVERRIDE of the
+ * persisted config setting (all matches case-insensitive + trimmed):
+ *
+ *   - `"true"` / `"1"`  → `true`  (force semantic search ON)
+ *   - `"false"` / `"0"` → `false` (force it OFF)
+ *   - unset / blank / anything unrecognized → `undefined` (no opinion —
+ *     defer to the persisted `embeddings_enabled` setting)
+ *
+ * Returning `undefined` (rather than guessing) for an unrecognized value is
+ * what lets the env var be a true override: only an explicit true/false
+ * short-circuits the persisted setting.
+ */
+export function embeddingsEnabledEnvOverride(env: NodeJS.ProcessEnv = process.env): boolean | undefined {
+  const raw = env.EMBEDDINGS_ENABLED?.trim().toLowerCase();
+  if (!raw) return undefined;
+  if (raw === "true" || raw === "1") return true;
+  if (raw === "false" || raw === "0") return false;
+  return undefined;
+}
+
+/**
+ * The effective enabled state for semantic search. Env override wins; else
+ * the persisted config setting; else OFF — semantic search is opt-in as of
+ * 0.7.3. Pure so both the provider factory and the "why is it off" hint
+ * derive from the same rule.
  */
-export function embeddingsExplicitlyDisabled(env: NodeJS.ProcessEnv = process.env): boolean {
-  return env.EMBEDDINGS_ENABLED?.trim().toLowerCase() === "false";
+export function resolveEmbeddingsEnabled(
+  env: NodeJS.ProcessEnv = process.env,
+  persistedEnabled?: boolean,
+): boolean {
+  return embeddingsEnabledEnvOverride(env) ?? persistedEnabled ?? false;
 }
 
 /**
  * Build the provider the current config selects, or `undefined` when
- * `EMBEDDINGS_ENABLED=false` (see the off-switch doc above). Pure factory
- * (no caching, no I/O beyond what the provider's own constructor does —
- * which is none; both providers lazy-load/lazy-connect on first
- * `embed()`), so it's cheap to call repeatedly in tests. Production
- * callers should go through the shared singleton
+ * semantic search is not enabled (see `resolveEmbeddingsEnabled` — env
+ * override, else the persisted `embeddings_enabled` setting, else OFF).
+ * Pure factory (no caching, no I/O beyond what the provider's own
+ * constructor does — which is none; both providers lazy-load/lazy-connect
+ * on first `embed()`), so it's cheap to call repeatedly in tests.
+ * Production callers should go through the shared singleton
  * (`getSharedEmbeddingProvider`) instead of calling this directly, so the
- * bundled ONNX model — when selected — loads at most once per process.
+ * bundled ONNX model — when selected — loads at most once per process, and
+ * so the persisted setting is threaded in.
  */
-export function buildEmbeddingProvider(env: NodeJS.ProcessEnv = process.env): EmbeddingProvider | undefined {
-  if (embeddingsExplicitlyDisabled(env)) return undefined;
+export function buildEmbeddingProvider(
+  env: NodeJS.ProcessEnv = process.env,
+  opts?: { persistedEnabled?: boolean },
+): EmbeddingProvider | undefined {
+  if (!resolveEmbeddingsEnabled(env, opts?.persistedEnabled)) return undefined;
   const config = resolveEmbeddingApiConfig(env);
   if (config.url) {
     return new ExternalApiEmbeddingProvider({

package/src/live-frame-parity.test.ts

@@ -98,6 +98,18 @@ describe("buildSnapshotFrames — chunking + done flag", () => {
     for (const f of frames) expect(new TextEncoder().encode(f).byteLength).toBeLessThan(1_000_000);
     expect(frames.flatMap((f) => JSON.parse(f).notes).length).toBe(8);
   });
+
+  it("is shape-agnostic — frames a lean NoteIndex entry verbatim", () => {
+    // A lean subscription hands `toNoteIndex`-projected entries; the framer
+    // serializes them byte-for-byte, no content field re-added.
+    const lean = { id: "x", byteSize: 3, preview: "abc", displayTitle: "abc", tags: ["chat"], metadata: {} };
+    const frames = buildSnapshotFrames([lean as any]);
+    expect(frames.length).toBe(1);
+    const f = JSON.parse(frames[0]!);
+    expect(f.done).toBe(true);
+    expect(f.notes).toEqual([lean]);
+    expect(f.notes[0].content).toBeUndefined();
+  });
 });
 
 describe("parseClientMessage", () => {
@@ -171,6 +183,15 @@ describe("validateWsSubscribeQuery — same rejects as the SSE route (byte-ident
     const v = validateWsSubscribeQuery(new URL("http://x/vault/v/api/subscribe?tag=chat&path_prefix=meetings/"));
     expect("queryOpts" in v).toBe(true);
   });
+  it("resolves include_content — default TRUE (full), `false`/`0` → lean, `true`/`1` → full", () => {
+    const at = (q: string) =>
+      validateWsSubscribeQuery(new URL(`http://x/vault/v/api/subscribe?tag=chat${q}`)) as { includeContent: boolean };
+    expect(at("").includeContent).toBe(true); // absent → full (byte-unchanged default)
+    expect(at("&include_content=false").includeContent).toBe(false); // opt into lean
+    expect(at("&include_content=0").includeContent).toBe(false);
+    expect(at("&include_content=true").includeContent).toBe(true);
+    expect(at("&include_content=1").includeContent).toBe(true);
+  });
   it("shares the SSE route's queryOpts-level guard (cursor/has_links/date filters)", () => {
     // The belt-and-suspenders layer both doors + the SSE route route through:
     // a date filter isn't expressible as a flat URL param (removed 0.6.4), but

package/src/mcp-http.ts

@@ -180,9 +180,15 @@ export async function handleMcp(
     }
     try {
       const result = await tool.execute((args ?? {}) as Record<string, unknown>);
-      return {
-        content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }],
-      };
+      // The one wrapper change (attachments-for-agents design, Wave 2):
+      // `resultContent`, when a tool defines it, decides the MCP content
+      // blocks instead of the universal single-text-block default —
+      // `read-attachment`'s image branch is the only current user (needs a
+      // REAL {type:"image"} block alongside the row-JSON text block).
+      const content = tool.resultContent
+        ? tool.resultContent(result)
+        : [{ type: "text" as const, text: JSON.stringify(result, null, 2) }];
+      return { content };
     } catch (err) {
       // vault#555 fix 6 — never re-wrap an already-formed McpError. Passing
       // the SAME instance straight through is strictly correct (no
@@ -231,6 +237,12 @@ export async function handleMcp(
         referencing_tags?: unknown;
         /** Attachment-tickets design (§2c "errors as JIT docs") — a short, imperative next-step, distinct from the older free-form `hint`. */
         how_to?: string;
+        /** `read-attachment` (Wave 2) refusals — `image_too_large` / `unsupported_attachment_type` carry the attachment's actual byte size. */
+        size?: number;
+        /** `read-attachment` `image_too_large` — the 4 MiB cap it exceeded. */
+        max_bytes?: number;
+        /** `read-attachment` `unsupported_attachment_type` — the mime type that couldn't be read. */
+        mime_type?: string;
       };
       // Honest-queries validation errors (vault#550) — `limit`/`offset`/date
       // values that are structurally invalid rather than merely "no
@@ -411,6 +423,11 @@ export async function handleMcp(
           ...(e.got !== undefined ? { got: e.got } : {}),
           ...(e.extension !== undefined ? { extension: e.extension } : {}),
           ...(e.how_to !== undefined ? { how_to: e.how_to } : {}),
+          // read-attachment (Wave 2) refusal fields — same forward-when-present
+          // discipline as the ticket fields just above.
+          ...(e.size !== undefined ? { size: e.size } : {}),
+          ...(e.max_bytes !== undefined ? { max_bytes: e.max_bytes } : {}),
+          ...(e.mime_type !== undefined ? { mime_type: e.mime_type } : {}),
         });
       }
       return {

package/src/mcp-tools.ts

@@ -45,6 +45,7 @@ import { looksLikeJwt } from "./hub-jwt.ts";
 import { readGlobalConfig, DEFAULT_PORT } from "./config.ts";
 import { getBaseUrl } from "./oauth-discovery.ts";
 import { getSharedAttachmentTicketProvider } from "./attachment-tickets.ts";
+import { createFsAttachmentBytesProvider } from "./attachment-bytes.ts";
 
 /**
  * Filter a vault projection to entries an in-scope tag contributes to.
@@ -112,10 +113,12 @@ export async function getServerInstruction(
     description: config?.description ?? null,
     projection,
     coordinates: resolveVaultCoordinates(),
-    // Bun always wires an in-process AttachmentTicketProvider (see
+    // Bun always wires an in-process AttachmentTicketProvider AND a fresh
+    // fs-backed AttachmentBytesProvider per session (see
     // `generateScopedMcpTools` below) — the connect-time brief can
-    // unconditionally teach the ticket tools on this door.
-    attachments: { ticketsEnabled: true },
+    // unconditionally teach both the ticket tools and read-attachment on
+    // this door.
+    attachments: { ticketsEnabled: true, readEnabled: true },
   });
 }
 
@@ -273,6 +276,15 @@ export function generateScopedMcpTools(
       urlBase: ticketUrlBase,
       ...(ticketNoteVisible ? { noteVisible: ticketNoteVisible } : {}),
     },
+    // Attachment bytes (Wave 2 model lane): bun always wires a fresh fs
+    // provider per session — cheap (stateless), unlike the ticket
+    // provider's process-wide shared Map. Same `ticketNoteVisible`
+    // tag-scope predicate as the ticket seam above (identical contract:
+    // "is the owning note in scope").
+    attachmentBytes: {
+      provider: createFsAttachmentBytesProvider(vaultName),
+      ...(ticketNoteVisible ? { noteVisible: ticketNoteVisible } : {}),
+    },
   });
 
   overrideVaultInfo(tools, vaultName, auth);

package/src/oauth-discovery.ts

@@ -27,6 +27,7 @@
  */
 
 import { getHubOrigin } from "./hub-jwt.ts";
+import { SCOPE_READ, SCOPE_WRITE } from "./scopes.ts";
 
 /**
  * OAuth scopes vault publishes through discovery, RESOURCE-NARROWED to the
@@ -87,6 +88,36 @@ export function handleProtectedResource(req: Request, vaultName: string): Respon
   });
 }
 
+/**
+ * Protected Resource Metadata (RFC 9728) for the CANONICAL ROOT `/mcp`
+ * endpoint (U1). Same document shape as `handleProtectedResource`, with two
+ * deliberate differences that follow from the root being vault-AGNOSTIC (the
+ * vault is derived from the token, not the URL):
+ *
+ *   - `resource` is the origin-root `<base>/mcp`, not a `/vault/<name>/mcp`.
+ *   - `scopes_supported` advertises the UN-NARROWED forms `vault:read` /
+ *     `vault:write` (there's no vault name to narrow to here). A spec-following
+ *     client reads these and requests the broad forms; the hub's consent picker
+ *     narrows the grant to a chosen vault at authorization time (that path
+ *     already exists hub-side), minting a token stamped with a
+ *     `vault:<name>:<verb>` scope + `aud=vault.<name>` — exactly what the root
+ *     endpoint derives the target vault from. `admin` is intentionally omitted:
+ *     the interactive connect flow grants read/write; admin is an operator
+ *     concern, not something the consent picker offers.
+ *
+ * Served at the RFC 9728 §3.1 path-insertion location for the root resource:
+ * `/.well-known/oauth-protected-resource/mcp`.
+ */
+export function handleRootProtectedResource(req: Request): Response {
+  const base = getBaseUrl(req);
+  return Response.json({
+    resource: `${base}/mcp`,
+    authorization_servers: [getHubOrigin()],
+    scopes_supported: [SCOPE_READ, SCOPE_WRITE],
+    bearer_methods_supported: ["header"],
+  });
+}
+
 /**
  * OAuth 2.0 Authorization Server Metadata (RFC 8414).
  *