@openparachute/vault 0.4.3 → 0.4.4-rc.11

package/README.md

@@ -139,7 +139,7 @@ Password and 2FA secrets live in `~/.parachute/vault/config.yaml` at mode 0600 (
 
 Where `{name}` is `default` on a fresh install, or whatever vault you pointed `vault init` at. **First MCP call after `vault init` requires no browser handoff — Claude Code uses the baked-in token and the vault's tools show up in your next session.** This is intentional: for an owner connecting their own machine's vault to their own Claude Code, the token is already there and OAuth would add friction.
 
-To re-point Claude Code at a different vault, change `default_vault` in `~/.parachute/vault/config.yaml` and re-run `parachute-vault init` — which re-mints an API token and re-writes the `~/.claude.json` entry end-to-end. To rotate the token only, edit `~/.claude.json` and replace the `Authorization` header value with a fresh token from `parachute-vault tokens create`. (Running `parachute-vault mcp-install` on its own overwrites the MCP entry *without* an `Authorization` header and is intended for the rare case where you want to drop the token and connect via OAuth instead.)
+To re-point Claude Code at a different vault, change `default_vault` in `~/.parachute/vault/config.yaml` and re-run `parachute-vault init` — which re-mints an API token and re-writes the `~/.claude.json` entry end-to-end. To rotate the token only, run `parachute-vault mcp-install` (defaults to `--mint`, which mints a fresh scope-narrow hub JWT via `~/.parachute/operator.token` and writes it into `~/.claude.json` with an `Authorization: Bearer …` header). See the [cookbook](#install-vault-mcp-into-a-client-config) section below for the full flag surface — token paste, scope narrowing, project-level install, multi-vault.
 
 ### Claude Desktop (OAuth)
 
@@ -190,7 +190,13 @@ parachute-vault uninstall --yes --wipe     # scripted destructive wipe (prints a
 parachute-vault create work                # create a new vault
 parachute-vault list                       # list all vaults (alias: `ls`)
 parachute-vault remove work --yes          # delete a vault (alias: `rm`)
-parachute-vault mcp-install                # (re)write the ~/.claude.json MCP entry for the default vault
+parachute-vault mcp-install                # (re)write the MCP client entry; defaults to --mint (hub-issued JWT) at local scope
+parachute-vault mcp-install --token <t>    # paste an existing bearer instead of minting
+parachute-vault mcp-install --legacy-pat   # mint a vault-DB pvt_* (self-hosted-without-hub)
+parachute-vault mcp-install --install-scope user      # write ~/.claude.json top-level (every project)
+parachute-vault mcp-install --install-scope local     # write ~/.claude.json projects[<cwd>] (this directory only — default)
+parachute-vault mcp-install --install-scope project   # write ./.mcp.json (checked into the repo)
+parachute-vault mcp-install --vault work   # target the "work" vault (keyed as parachute-vault-work)
 
 # OAuth — owner password + 2FA
 parachute-vault set-password               # set/change the owner password (OAuth consent page)
@@ -565,6 +571,56 @@ Atomic at the SQL layer: two concurrent appends both land in some order, never c
 
 The shortest path to a public HTTPS URL for a vault you control — useful for SSG rebuilds running on GitHub Actions, Vercel, or any runner that isn't on your tailnet. See [Remote access via Tailscale Funnel](#remote-access-via-tailscale-funnel) below for the full setup.
 
+### Install vault MCP into a client config
+
+Bare `parachute-vault mcp-install` from a terminal **walks you through a short contextual conversation** — picks defaults informed by your environment (how many vaults you have, whether the hub is reachable, whether you're in a project directory, whether vault is already installed somewhere), shows the JSON shape it will write before doing anything, and asks before each non-obvious choice. The patterns below are the non-interactive shapes — pass any flag (`--mint`, `--token`, `--scope`, `--install-scope`, `--vault`, `--legacy-pat`) and the walkthrough is skipped.
+
+#### Install scopes
+
+`--install-scope` accepts three values, matching Claude Code's own `claude mcp add --scope`:
+
+| Scope | Where the entry lives | Visibility |
+|---|---|---|
+| `local` *(default)* | `~/.claude.json` under `projects[<absolute-cwd>].mcpServers` | private to your machine, scoped to this directory |
+| `user` | `~/.claude.json` top-level `mcpServers` | every project, every directory on this machine |
+| `project` | `<cwd>/.mcp.json` | checked into the repo, shared with anyone who clones it |
+
+The default is **`local`** — Claude Code only loads the entry when launched from the directory you ran the install from. Pick `user` for a global install (every project sees the vault); pick `project` to commit the entry to the repo so collaborators get it on `git pull`.
+
+#### Cookbook
+
+```bash
+# 1. Default — mint a scope-narrow hub JWT (vault:<vault>:read) via your
+#    operator token; write it into ~/.claude.json under projects[<cwd>]
+#    (local scope, this directory only). Requires:
+#      - ~/.parachute/operator.token (run `parachute auth rotate-operator` if missing)
+#      - PARACHUTE_HUB_ORIGIN set OR an active `parachute expose` session
+parachute-vault mcp-install --mint
+
+# 2. Global install — write the entry at top-level ~/.claude.json so
+#    Claude Code loads it from every project, every directory.
+parachute-vault mcp-install --install-scope user
+
+# 3. Project-level install — write ./.mcp.json (committed to the repo,
+#    shared with the team). Pair with --scope vault:write when the
+#    project actually mutates the vault.
+parachute-vault mcp-install --install-scope project --scope vault:write
+
+# 4. Paste an existing token — useful when you already have a pvt_* in hand
+#    or want to re-use a long-lived bearer from another machine. Skips the
+#    mint step entirely.
+parachute-vault mcp-install --token pvt_abc123...
+
+# 5. Self-hosted-without-hub — mint a vault-DB pvt_* token (the legacy
+#    path; preserved so deployments without a hub keep working). Prints a
+#    deprecation notice.
+parachute-vault mcp-install --legacy-pat
+```
+
+**Multi-vault.** `--vault <name>` targets a specific vault and writes the entry under `parachute-vault-<name>` so multiple vaults coexist. Without `--vault`, the singular `parachute-vault` slot is used and one install clobbers another — that's intentional for the common single-vault case.
+
+**Doctor.** `parachute-vault doctor` checks `~/.claude.json` (both top-level and `projects[<cwd>]`) and `./.mcp.json`, and reports which one holds the entry, plus port-match and reachability of the MCP URL.
+
 ## Data model
 
 ```

package/core/src/core.test.ts

@@ -3678,6 +3678,122 @@ describe("schema validation (tags.fields)", async () => {
     const result = await create.execute({ content: "x", tags: ["task"] }) as any;
     expect(result.validation_status).toBeUndefined();
   });
+
+  // vault#310 — integer type validation. JSON has no separate integer
+  // type, so a JSON number with zero fractional part (`5`, `5.0`) must
+  // pass an `integer`-typed field. Pre-fix, the validator had no
+  // `"integer"` case at all — falling through the switch returned
+  // undefined and every integer-typed field warned `type_mismatch` on
+  // legitimate values. Gitcoin Brain's drift detector emits JSON for
+  // diffs; every `kpi: 3` triggered the false-positive and buried the
+  // real warnings.
+
+  it("integer-typed field: JSON integer (5) passes (vault#310)", async () => {
+    await store.upsertTagSchema("kpi", { fields: { count: { type: "integer" } } });
+    const tools = generateMcpTools(store);
+    const create = tools.find((t) => t.name === "create-note")!;
+    const result = await create.execute({
+      content: "x",
+      tags: ["kpi"],
+      metadata: { count: 5 },
+    }) as any;
+    expect(result.validation_status?.warnings ?? []).toEqual([]);
+  });
+
+  it("integer-typed field: JSON `5.0` (zero-fractional) passes (vault#310)", async () => {
+    // 5.0 is the canonical Gitcoin shape — JSON.parse decodes the
+    // emitted JSON number as a JS Number; the JS Number for `5.0` is
+    // identical to `5` so Number.isInteger reports true. This is the
+    // load-bearing assertion for the Gitcoin drift-detector use case.
+    await store.upsertTagSchema("kpi", { fields: { count: { type: "integer" } } });
+    const tools = generateMcpTools(store);
+    const create = tools.find((t) => t.name === "create-note")!;
+    const result = await create.execute({
+      content: "x",
+      tags: ["kpi"],
+      metadata: { count: 5.0 },
+    }) as any;
+    expect(result.validation_status?.warnings ?? []).toEqual([]);
+  });
+
+  it("integer-typed field: JSON `5.5` (non-zero fractional) warns type_mismatch (vault#310)", async () => {
+    await store.upsertTagSchema("kpi", { fields: { count: { type: "integer" } } });
+    const tools = generateMcpTools(store);
+    const create = tools.find((t) => t.name === "create-note")!;
+    const result = await create.execute({
+      content: "x",
+      tags: ["kpi"],
+      metadata: { count: 5.5 },
+    }) as any;
+    expect(result.validation_status.warnings.length).toBe(1);
+    expect(result.validation_status.warnings[0].reason).toBe("type_mismatch");
+    expect(result.validation_status.warnings[0].field).toBe("count");
+  });
+
+  it("integer-typed field: string `\"5\"` warns type_mismatch (no string→number coercion) (vault#310)", async () => {
+    await store.upsertTagSchema("kpi", { fields: { count: { type: "integer" } } });
+    const tools = generateMcpTools(store);
+    const create = tools.find((t) => t.name === "create-note")!;
+    const result = await create.execute({
+      content: "x",
+      tags: ["kpi"],
+      metadata: { count: "5" },
+    }) as any;
+    expect(result.validation_status.warnings.length).toBe(1);
+    expect(result.validation_status.warnings[0].reason).toBe("type_mismatch");
+  });
+
+  it("integer-typed field: edge `5.0000000000001` warns type_mismatch (vault#310)", async () => {
+    await store.upsertTagSchema("kpi", { fields: { count: { type: "integer" } } });
+    const tools = generateMcpTools(store);
+    const create = tools.find((t) => t.name === "create-note")!;
+    const result = await create.execute({
+      content: "x",
+      tags: ["kpi"],
+      metadata: { count: 5.0000000000001 },
+    }) as any;
+    expect(result.validation_status.warnings.length).toBe(1);
+    expect(result.validation_status.warnings[0].reason).toBe("type_mismatch");
+  });
+
+  it("integer-typed field: boolean warns type_mismatch (vault#310)", async () => {
+    // Pin that boolean is rejected (Number.isInteger(true) returns
+    // false, but extra coverage in case anyone "improves" the check
+    // with a looser predicate later).
+    await store.upsertTagSchema("kpi", { fields: { count: { type: "integer" } } });
+    const tools = generateMcpTools(store);
+    const create = tools.find((t) => t.name === "create-note")!;
+    const result = await create.execute({
+      content: "x",
+      tags: ["kpi"],
+      metadata: { count: true },
+    }) as any;
+    expect(result.validation_status.warnings.length).toBe(1);
+    expect(result.validation_status.warnings[0].reason).toBe("type_mismatch");
+  });
+
+  // Note on NaN/Infinity: those values pass through
+  // JSON.stringify as `null`, then the validator's null short-circuit
+  // (schema-defaults.ts:327 — "value === null → skip") filters them out
+  // before reaching the type check. We can't observe them in
+  // validation_status from this layer; a dedicated unit test against
+  // `valueMatchesType` would catch the case at the inner boundary.
+  // Pinned at the next layer down:
+
+  it("valueMatchesType('integer', ...) rejects NaN / Infinity (vault#310)", async () => {
+    // Reach the unexported helper indirectly via validateNote on a
+    // hand-built resolved-schemas + metadata where the value is the
+    // actual NaN/Infinity (no JSON round-trip).
+    const { validateNote, loadSchemaConfig } = await import("./schema-defaults.js");
+    // Seed via the public surface, then load the resolved schemas
+    // snapshot.
+    await store.upsertTagSchema("k", { fields: { c: { type: "integer" } } });
+    const resolved = loadSchemaConfig((store as any).db);
+    expect(validateNote(resolved, { tags: ["k"], metadata: { c: Number.NaN } })?.warnings[0]?.reason)
+      .toBe("type_mismatch");
+    expect(validateNote(resolved, { tags: ["k"], metadata: { c: Number.POSITIVE_INFINITY } })?.warnings[0]?.reason)
+      .toBe("type_mismatch");
+  });
 });
 
 // ---------------------------------------------------------------------------

package/core/src/mcp.ts

@@ -469,6 +469,7 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
 - When removing a wikilink-type link, \`[[brackets]]\` are also removed from content.
 - 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. \`append\` / \`prepend\` only updates are exempt from the precondition (no-conflict-by-design).
+- **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\`, \`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.`,
       inputSchema: {
         type: "object",
@@ -491,6 +492,7 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
           created_at: { type: "string", description: "New created_at timestamp" },
           if_updated_at: { type: "string", description: "Optimistic concurrency check: the updated_at value you last read. Rejects with a conflict error if the note has been modified since. Required unless `force: true` is set or the call is `append`/`prepend`-only." },
           force: { type: "boolean", description: "Override the required `if_updated_at` check and run the update unconditionally. Use only for bulk migrations or scripted writes where concurrency is known-safe." },
+          if_missing: { type: "string", enum: ["fail", "create"], description: "What to do when the note (by `id`/path) doesn't exist. `\"fail\"` (default) — error, current behavior. `\"create\"` — create the note from this same payload (content/path/tags/metadata become the create fields; the response carries `created: true`). Skips the `if_updated_at` precondition on the create branch (nothing to conflict with). Idempotent for sync loops that don't know ahead of time whether the note exists. See vault#309." },
           tags: {
             type: "object",
             properties: {
@@ -554,6 +556,7 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
                 created_at: { type: "string" },
                 if_updated_at: { type: "string", description: "Optimistic concurrency check for this item; rejects with a conflict error if the note has been modified since. Required unless `force: true` is set on this item or the item is `append`/`prepend`-only." },
                 force: { type: "boolean", description: "Override the required `if_updated_at` check for this item." },
+                if_missing: { type: "string", enum: ["fail", "create"], description: "Per-item: see top-level `if_missing` docs. Each batch item carries its own setting." },
                 tags: { type: "object" },
                 links: { type: "object" },
               },
@@ -572,6 +575,11 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
         }
 
         const updated: Note[] = [];
+        // Track which note IDs were freshly created via `if_missing: "create"`
+        // so the response can carry `created: true|false` per-note. The
+        // sync-loop caller (Gitcoin Brain et al) reads this to know which
+        // path fired without doing a separate query. vault#309.
+        const createdIds = new Set<string>();
         // Wrap multi-item batches in a SQLite transaction so any mid-batch
         // failure (precondition error, content_edit miss, ConflictError, …)
         // rolls back every prior mutation in the batch — see #236.
@@ -581,7 +589,77 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
         if (batched) db.exec("BEGIN");
         try {
         for (const item of items) {
-          const note = requireNote(db, item.id as string);
+          // Try ID-then-path resolve. If not found AND
+          // `if_missing: "create"` is set, fall through to the create
+          // branch using this same item's payload. Otherwise mirror the
+          // existing `requireNote` behavior (throw "Note not found").
+          // vault#309.
+          const resolved = resolveNote(db, item.id as string);
+          if (!resolved) {
+            if (item.if_missing === "create") {
+              // Treat the update payload as a create payload. Minimum:
+              // content OR a path/id (something the createNote-empty-row
+              // invariant accepts). createNote enforces its own
+              // not-both-empty check — we leave that to the Store and
+              // surface any error to the caller verbatim.
+              //
+              // Field mapping (mirrors the create-note tool surface):
+              //   - `item.id` → both the note's `id` AND a fallback
+              //     `path` when `item.path` isn't set. Treating `id` as
+              //     the path-or-id lookup key matches Gitcoin's nightly
+              //     sync shape where the canonical key is a path string
+              //     like "Inbox/2026-05-13-meeting". If the caller
+              //     supplied an opaque ULID as `id` and no `path`, we
+              //     still create with that as `id` (path stays null).
+              //   - `item.content` / `item.path` / `item.tags` /
+              //     `item.metadata` / `item.created_at` → forwarded.
+              //   - `if_updated_at` / `force` / `content_edit` /
+              //     `append` / `prepend` / `links` are
+              //     update-only — silently ignored on the create branch.
+              //     (Content-edit on a non-existent note is a nonsense
+              //     combination; the caller's intent on missing-note is
+              //     "create the row", not "patch in this section".)
+              const idOrPath = item.id as string;
+              // Heuristic: if `path` isn't set AND the `id` looks like a
+              // path (contains "/" or doesn't match a typical opaque-id
+              // shape), use it as the path too. Otherwise treat it as a
+              // pure id. The shared `id` field for update is ID-or-path
+              // already (see `resolveNote`), so this preserves the
+              // caller's intent.
+              const idLooksLikePath = idOrPath.includes("/") || !/^[A-Za-z0-9_-]+$/.test(idOrPath);
+              const explicitPath = typeof item.path === "string" ? item.path as string : undefined;
+              const createOpts: Parameters<Store["createNote"]>[1] = {
+                ...(idLooksLikePath ? { path: explicitPath ?? idOrPath } : { id: idOrPath, ...(explicitPath !== undefined ? { path: explicitPath } : {}) }),
+                ...(item.tags && Array.isArray((item.tags as any).add)
+                  ? { tags: (item.tags as any).add as string[] }
+                  : Array.isArray(item.tags)
+                    ? { tags: item.tags as string[] }
+                    : {}),
+                ...(item.metadata !== undefined ? { metadata: item.metadata as Record<string, unknown> } : {}),
+                ...(item.created_at !== undefined ? { created_at: item.created_at as string } : {}),
+              };
+              const content = (item.content as string | undefined) ?? "";
+              const created = await store.createNote(content, createOpts);
+              await applySchemaDefaults(store, db, [created.id], created.tags ?? []);
+              // Apply links.add if the caller declared any.
+              const linksAdd = (item.links as any)?.add as { target: string; relationship: string; metadata?: Record<string, unknown> }[] | undefined;
+              if (linksAdd) {
+                for (const link of linksAdd) {
+                  const target = resolveNote(db, link.target);
+                  if (target) await store.createLink(created.id, target.id, link.relationship, link.metadata);
+                }
+              }
+              const fresh = noteOps.getNote(db, created.id) ?? created;
+              updated.push(fresh);
+              createdIds.add(fresh.id);
+              continue;
+            }
+            // Fallthrough: not-found + no if_missing → existing error
+            // contract. Match `requireNote`'s message shape so existing
+            // callers see no behavior change.
+            throw new Error(`Note not found: "${item.id}"`);
+          }
+          const note = resolved;
 
           // --- Validate mutual exclusion of content modes ---
           const hasContent = item.content !== undefined;
@@ -745,14 +823,21 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
         // Response shape: full Note (back-compat default) or lean NoteIndex
         // (#285 friction point 2.response — opt-out for callers making
         // frequent small edits to large notes). `validation_status` from
-        // `tags.fields` is preserved across either shape.
+        // `tags.fields` is preserved across either shape. `created: true|false`
+        // (vault#309) is attached to every response so callers using
+        // `if_missing: "create"` can tell which branch fired without a
+        // separate query. `false` for the (overwhelmingly common) update
+        // path; `true` only when this call took the create-on-missing
+        // branch.
         const includeContent = params.include_content !== false;
         const final = updated.map((n) => {
           const validated = attachValidationStatus(store, db, n);
-          if (includeContent) return validated;
+          const created = createdIds.has(n.id);
+          if (includeContent) return { ...validated, created } as Note & { created: boolean };
           const lean: any = noteOps.toNoteIndex(validated);
           const vs = (validated as any).validation_status;
           if (vs !== undefined) lean.validation_status = vs;
+          lean.created = created;
           return lean;
         });
         return batch ? final : final[0];
@@ -1127,8 +1212,13 @@ function defaultForField(field: { type: string; enum?: string[] }): unknown {
  *
  * Returns the note unchanged when no tag declares fields, so callers
  * without any tag schemas see no behavior change.
+ *
+ * Exported so both transports (MCP `update-note` here, HTTP `PATCH
+ * /api/notes/:id` in `src/routes.ts`) attach the same status field by
+ * the same recipe — see vault#287 for the asymmetry that motivated
+ * exposing it.
  */
-function attachValidationStatus(store: Store, _db: Database, note: Note): Note {
+export function attachValidationStatus(store: Store, _db: Database, note: Note): Note {
   // Short-circuit cheaply: when no tag declares fields, the resolver
   // returns null without us paying a re-read of the note.
   const status = store.validateNoteAgainstSchemas({

package/core/src/obsidian.ts

@@ -1,15 +1,41 @@
 /**
- * Obsidian vault parser — reads .md files and extracts notes, tags, links.
+ * Obsidian-compatible markdown export/import — back-compat shim.
  *
- * Handles:
- *   - YAML frontmatter → note.metadata
- *   - Inline #tags and frontmatter tags → tags table
- *   - [[wikilinks]] → handled by wikilinks.ts on note creation
- *   - File path → note.path
+ * @deprecated The canonical home for the markdown knowledge-base format
+ * is `portable-md.ts`. The format isn't Obsidian-specific (it's consumed
+ * unchanged by Logseq, Foam, Quartz, Dendron, and most markdown-shaped
+ * static-site generators) — anchoring the function name to the format
+ * keeps the door open as other consumers adopt the same shape. See
+ * vault#308.
+ *
+ * What lives here:
+ *   - `toObsidianMarkdown` — the **legacy** lossy emitter (flat
+ *     frontmatter, no IDs, no typed links, no attachments). Kept for
+ *     existing callers; for round-trippable exports use
+ *     `toPortableMarkdown` in `portable-md.ts`.
+ *   - `parseObsidianVault` / `parseObsidianFile` — directory + file
+ *     parsers. These delegate to `portable-md.ts`'s parser, which
+ *     handles both the new lossless shape and the legacy flat
+ *     frontmatter shape.
+ *   - Re-exports of `parseFrontmatter`, `extractInlineTags`,
+ *     `walkMarkdownFiles` from `portable-md.ts` so existing imports
+ *     keep working without code-level churn.
+ *
+ * New code should import from `portable-md.ts` directly.
  */
 
-import { readdirSync, readFileSync, statSync } from "fs";
-import { join, relative, extname, basename } from "path";
+import { readFileSync } from "fs";
+import { relative } from "path";
+
+// Re-export the canonical parser helpers so existing callers (and tests)
+// keep working against the legacy import path.
+export {
+  parseFrontmatter,
+  extractInlineTags,
+  walkMarkdownFiles,
+} from "./portable-md.js";
+
+import { parseFrontmatter, walkMarkdownFiles, extractInlineTags } from "./portable-md.js";
 
 // ---------------------------------------------------------------------------
 // Types
@@ -34,121 +60,7 @@ export interface ImportStats {
   errors: { path: string; error: string }[];
 }
 
-// ---------------------------------------------------------------------------
-// Frontmatter parsing
-// ---------------------------------------------------------------------------
-
-/**
- * Parse YAML frontmatter from markdown content.
- * Returns { frontmatter, content } where content has frontmatter stripped.
- *
- * Uses a simple parser — no dependency on a YAML library.
- * Handles common frontmatter patterns: strings, arrays, numbers, booleans.
- */
-export function parseFrontmatter(raw: string): {
-  frontmatter: Record<string, unknown>;
-  content: string;
-} {
-  if (!raw.startsWith("---")) {
-    return { frontmatter: {}, content: raw };
-  }
-
-  const endIdx = raw.indexOf("\n---", 3);
-  if (endIdx === -1) {
-    return { frontmatter: {}, content: raw };
-  }
-
-  const yamlBlock = raw.slice(4, endIdx); // skip opening "---\n"
-  const content = raw.slice(endIdx + 4).replace(/^\n/, ""); // skip closing "---\n"
-
-  const frontmatter: Record<string, unknown> = {};
-  let currentKey = "";
-  let currentArray: string[] | null = null;
-
-  for (const line of yamlBlock.split("\n")) {
-    // Array item (continuation of previous key)
-    if (currentArray !== null && /^\s+-\s+/.test(line)) {
-      const val = line.replace(/^\s+-\s+/, "").trim();
-      currentArray.push(unquote(val));
-      continue;
-    }
-
-    // If we were building an array, save it (or save empty string if no items found)
-    if (currentArray !== null) {
-      frontmatter[currentKey] = currentArray.length > 0 ? currentArray : "";
-      currentArray = null;
-    }
-
-    // Key: value pair — keys must be YAML-valid (word chars and hyphens, no spaces)
-    const kvMatch = line.match(/^([\w][\w-]*):\s*(.*)/);
-    if (kvMatch) {
-      const key = kvMatch[1]!;
-      const value = kvMatch[2]!.trim();
-
-      if (value === "[]") {
-        frontmatter[key] = [];
-      } else if (value === "") {
-        // Empty value: could be start of array (next lines are "- item")
-        // or genuinely empty string. We start array accumulation and
-        // handle the empty case when a non-array line follows.
-        currentKey = key;
-        currentArray = [];
-      } else if (value.startsWith("[") && value.endsWith("]")) {
-        // Inline array: [item1, item2]
-        const items = value.slice(1, -1).split(",").map((s) => unquote(s.trim())).filter(Boolean);
-        frontmatter[key] = items;
-      } else {
-        frontmatter[key] = parseValue(value);
-      }
-    }
-  }
-
-  // Save any trailing array (or empty string if no items)
-  if (currentArray !== null) {
-    frontmatter[currentKey] = currentArray.length > 0 ? currentArray : "";
-  }
-
-  return { frontmatter, content };
-}
-
-function unquote(s: string): string {
-  if ((s.startsWith('"') && s.endsWith('"')) || (s.startsWith("'") && s.endsWith("'"))) {
-    return s.slice(1, -1);
-  }
-  return s;
-}
-
-function parseValue(s: string): unknown {
-  s = unquote(s);
-  if (s === "true") return true;
-  if (s === "false") return false;
-  if (s === "null") return null;
-  if (/^-?\d+$/.test(s)) return parseInt(s, 10);
-  if (/^-?\d+\.\d+$/.test(s)) return parseFloat(s);
-  return s;
-}
-
-// ---------------------------------------------------------------------------
-// Tag extraction
-// ---------------------------------------------------------------------------
-
-/** Extract inline #tags from markdown content. Excludes tags in code blocks. */
-export function extractInlineTags(content: string): string[] {
-  // Strip code blocks and inline code
-  let stripped = content.replace(/```[\s\S]*?```/g, "");
-  stripped = stripped.replace(/`[^`\n]+`/g, "");
-
-  const tags = new Set<string>();
-  // Match #tag and #nested/tag — must be preceded by whitespace or start of line
-  const regex = /(?:^|\s)#([\w][\w/-]*[\w]|[\w])/gm;
-  let match: RegExpExecArray | null;
-  while ((match = regex.exec(stripped)) !== null) {
-    tags.add(match[1]!.toLowerCase());
-  }
-  return [...tags];
-}
-
-/** Extract tags from frontmatter (handles both array and string formats). */
+/** Tags from frontmatter (handles both array and string formats). */
 function extractFrontmatterTags(frontmatter: Record<string, unknown>): string[] {
   const raw = frontmatter.tags;
   if (!raw) return [];
@@ -157,35 +69,6 @@ function extractFrontmatterTags(frontmatter: Record<string, unknown>): string[]
   return [];
 }
 
-// ---------------------------------------------------------------------------
-// Directory walking
-// ---------------------------------------------------------------------------
-
-/** Recursively list all .md files in a directory, excluding .obsidian/ and hidden dirs. */
-export function walkMarkdownFiles(dir: string): string[] {
-  const results: string[] = [];
-
-  function walk(current: string) {
-    for (const entry of readdirSync(current)) {
-      // Skip hidden directories and .obsidian config
-      if (entry.startsWith(".")) continue;
-      if (entry === "node_modules") continue;
-
-      const full = join(current, entry);
-      const stat = statSync(full);
-
-      if (stat.isDirectory()) {
-        walk(full);
-      } else if (stat.isFile() && extname(entry).toLowerCase() === ".md") {
-        results.push(full);
-      }
-    }
-  }
-
-  walk(dir);
-  return results.sort();
-}
-
 // ---------------------------------------------------------------------------
 // Parse a single file
 // ---------------------------------------------------------------------------
@@ -207,12 +90,7 @@ export function parseObsidianFile(filePath: string, vaultRoot: string): Obsidian
   const metadata = { ...frontmatter };
   delete metadata.tags;
 
-  return {
-    path,
-    content,
-    frontmatter: metadata,
-    tags: allTags,
-  };
+  return { path, content, frontmatter: metadata, tags: allTags };
 }
 
 // ---------------------------------------------------------------------------
@@ -254,9 +132,13 @@ export function parseObsidianVault(vaultPath: string): {
 }
 
 // ---------------------------------------------------------------------------
-// Export to Obsidian format
+// Legacy export — kept for back-compat. New code: use `toPortableMarkdown`.
 // ---------------------------------------------------------------------------
 
+/**
+ * Note shape the legacy export accepts. Distinct from `PortableNote` —
+ * older + lossy by design (no IDs, no typed links, no attachments).
+ */
 export interface ExportableNote {
   path?: string;
   id: string;
@@ -267,34 +149,33 @@ export interface ExportableNote {
 }
 
 /**
- * Convert a vault note to Obsidian-compatible markdown with YAML frontmatter.
+ * Convert a vault note to Obsidian-compatible markdown with YAML
+ * frontmatter — legacy flat-frontmatter shape (metadata keys at the
+ * top level, no IDs, no typed links, no attachments).
+ *
+ * @deprecated Prefer `toPortableMarkdown` in `portable-md.ts` for new
+ * code. This function is preserved for callers that intentionally want
+ * the legacy lossy shape — typically one-shot "give me an Obsidian
+ * copy" exports without round-trip concerns. See vault#308.
  */
 export function toObsidianMarkdown(note: ExportableNote): string {
   const fm: Record<string, unknown> = {};
 
-  // Add tags to frontmatter
-  if (note.tags && note.tags.length > 0) {
-    fm.tags = note.tags;
-  }
-
-  // Add metadata fields (excluding internal ones)
+  if (note.tags && note.tags.length > 0) fm.tags = note.tags;
   if (note.metadata) {
     for (const [key, value] of Object.entries(note.metadata)) {
-      if (key === "tags") continue; // already handled
+      if (key === "tags") continue;
       fm[key] = value;
     }
   }
 
-  // Build frontmatter string
   let result = "";
   if (Object.keys(fm).length > 0) {
     result += "---\n";
     for (const [key, value] of Object.entries(fm)) {
       if (Array.isArray(value)) {
         result += `${key}:\n`;
-        for (const item of value) {
-          result += `  - ${item}\n`;
-        }
+        for (const item of value) result += `  - ${item}\n`;
       } else if (typeof value === "object" && value !== null) {
         result += `${key}: ${JSON.stringify(value)}\n`;
       } else {
@@ -309,14 +190,11 @@ export function toObsidianMarkdown(note: ExportableNote): string {
 }
 
 /**
- * Determine the file path for an exported note.
- * Notes with paths use the path; pathless notes use date/id.
+ * Determine the file path for an exported note (legacy form).
+ * @deprecated Use `portableExportFilePath` from `portable-md.ts`.
  */
 export function exportFilePath(note: ExportableNote): string {
-  if (note.path) {
-    return note.path + ".md";
-  }
-  // Fallback: use date prefix + truncated id
+  if (note.path) return note.path + ".md";
   const date = note.createdAt.split("T")[0];
   return `${date}/${note.id}.md`;
 }