@openparachute/vault 0.5.1-rc.1 → 0.5.1

package/core/src/core.test.ts

@@ -5609,6 +5609,13 @@ describe("vault projection (vault#271)", async () => {
     expect(md).toContain("#person");
     expect(md).toContain("vault-info");
     expect(md).toContain("list-tags { include_schema: true }");
+    // Scripting pointer (closes the "points nowhere" gap): the brief routes an
+    // agent to the HTTP API + the public guide, with the vault name baked into
+    // the copy-paste mint command.
+    expect(md).toContain("## Scripting & automation (beyond this session)");
+    expect(md).toContain("https://parachute.computer/scripting/");
+    expect(md).toContain("parachute auth mint-token --scope vault:test:read --ephemeral");
+    expect(md).toContain("vault/test/api");
   });
 
   it("markdown brief degrades gracefully when no schemas declared", async () => {

package/core/src/obsidian-alignment.test.ts

@@ -0,0 +1,375 @@
+/**
+ * Obsidian-importer alignment fixtures (vault#423).
+ *
+ * These assert the vault/CLI parser + write adapter against the SHARED
+ * canonical fixture set in the alignment contract. The parachute-surface
+ * web parser asserts the SAME fixtures (its own test runner) so both
+ * importers produce identical parsed results. Do NOT change expected
+ * values here without changing the contract + the web side in lockstep.
+ *
+ * Fixture inputs are inline strings (`srcPath` + content). Parse-tier
+ * fixtures write the file to a temp dir and parse via `parseObsidianFile`
+ * — the same code the CLI runs. Write-tier fixtures (FX-ID-COLLISION,
+ * FX-SAME-STEM-COLLISION, FX-CREATED-AT write assertion) exercise the
+ * real `importObsidianNotes` adapter against an in-memory SqliteStore.
+ */
+import { describe, it, expect, beforeEach } from "bun:test";
+import { Database } from "bun:sqlite";
+import { SqliteStore } from "./store.js";
+import {
+  parseObsidianFile,
+  importObsidianNotes,
+  isMarkdownExtension,
+  isExcludedPath,
+  type ObsidianNote,
+} from "./obsidian.js";
+import { mkdirSync, writeFileSync, rmSync } from "fs";
+import { join, dirname } from "path";
+import { tmpdir } from "os";
+
+// ---------------------------------------------------------------------------
+// Parse-tier helper: write `content` at `srcPath` under a fresh temp root,
+// parse it via the real `parseObsidianFile`, and return the ObsidianNote.
+// ---------------------------------------------------------------------------
+
+const PARSE_ROOT = join(tmpdir(), "parachute-align-parse");
+
+function parseFixture(srcPath: string, content: string): ObsidianNote {
+  rmSync(PARSE_ROOT, { recursive: true, force: true });
+  const full = join(PARSE_ROOT, srcPath);
+  mkdirSync(dirname(full), { recursive: true });
+  writeFileSync(full, content);
+  return parseObsidianFile(full, PARSE_ROOT);
+}
+
+/** Sorted tag array, for stable comparison against the contract's
+ *  "(sorted)" expected tag lists. */
+function tags(note: ObsidianNote): string[] {
+  return [...note.tags].sort();
+}
+
+describe("alignment: parse tier", () => {
+  it("FX-FENCE-BOM — strips BOM then parses frontmatter", () => {
+    const n = parseFixture("Note.md", "---\nid: bom1\ntags: [a]\n---\nhello");
+    expect(n.path).toBe("Note");
+    expect(tags(n)).toEqual(["a"]);
+    expect(n.id).toBe("bom1");
+    expect(n.createdAt).toBeUndefined();
+    expect(n.content).toBe("hello");
+    expect(n.frontmatter).toEqual({});
+  });
+
+  it("FX-FENCE-FOURDASH — ---- body line is not a close fence", () => {
+    const n = parseFixture("Doc.md", "---\nid: x9\n---\nbefore\n----\nafter");
+    expect(n.path).toBe("Doc");
+    expect(tags(n)).toEqual([]);
+    expect(n.id).toBe("x9");
+    expect(n.content).toBe("before\n----\nafter");
+    expect(n.frontmatter).toEqual({});
+  });
+
+  it("FX-FENCE-FOURDASH-OPEN — ---- after open, no real close → whole file is body", () => {
+    const n = parseFixture("D2.md", "---\nid: y\n----\nbody text");
+    expect(n.path).toBe("D2");
+    expect(tags(n)).toEqual([]);
+    expect(n.id).toBeUndefined();
+    expect(n.content).toBe("---\nid: y\n----\nbody text");
+    expect(n.frontmatter).toEqual({});
+  });
+
+  it("FX-FENCE-UNCLOSED — open never closed → whole file is body", () => {
+    const n = parseFixture("U.md", "---\nid: z\nbody no close");
+    expect(n.path).toBe("U");
+    expect(tags(n)).toEqual([]);
+    expect(n.id).toBeUndefined();
+    expect(n.content).toBe("---\nid: z\nbody no close");
+    expect(n.frontmatter).toEqual({});
+  });
+
+  it("FX-CODE-TAG — #tag inside fenced + inline code is dropped", () => {
+    const content = "#realtag at top\n\n`#inlinenope`\n\n```\n#fencednope\n```\n";
+    const n = parseFixture("C.md", content);
+    expect(n.path).toBe("C");
+    expect(tags(n)).toEqual(["realtag"]);
+    expect(n.content).toBe(content);
+    expect(n.frontmatter).toEqual({});
+  });
+
+  it("FX-NUMERIC-TAG — #2024 is not a tag, #q3/#v2 are", () => {
+    const n = parseFixture("N.md", "plan #2024 and #q3 and #v2 done");
+    expect(n.path).toBe("N");
+    expect(tags(n)).toEqual(["q3", "v2"]);
+    expect(n.frontmatter).toEqual({});
+  });
+
+  it("FX-HIER-TAG — hierarchical inline tag keeps the slash", () => {
+    const n = parseFixture("H.md", "see #area/subarea here");
+    expect(n.path).toBe("H");
+    expect(tags(n)).toEqual(["area/subarea"]);
+    expect(n.frontmatter).toEqual({});
+  });
+
+  it("FX-FM-TAGS-VALIDATE — slug-validate + normalize frontmatter tags", () => {
+    const n = parseFixture(
+      "T.md",
+      '---\ntags: [Foo, "bad tag!", 42, true, ok-1, "#hash"]\n---\nbody',
+    );
+    expect(n.path).toBe("T");
+    expect(tags(n)).toEqual(["42", "foo", "hash", "ok-1", "true"]);
+    expect(n.content).toBe("body");
+    expect(n.frontmatter).toEqual({});
+  });
+
+  it("FX-INLINE-ARRAY — quote-aware inline-array split (2 items, not 3)", () => {
+    const n = parseFixture("IA.md", '---\nkeywords: ["a, b", c]\n---\nx');
+    expect(n.path).toBe("IA");
+    expect(tags(n)).toEqual([]);
+    expect(n.content).toBe("x");
+    expect(n.frontmatter).toEqual({ keywords: ["a, b", "c"] });
+  });
+
+  it("FX-MARKDOWN-EXT — .markdown ingest + classifier", () => {
+    const n = parseFixture("Folder/Note.markdown", "---\nid: m1\n---\nbody");
+    expect(n.path).toBe("Folder/Note");
+    expect(tags(n)).toEqual([]);
+    expect(n.id).toBe("m1");
+    expect(n.content).toBe("body");
+    expect(n.frontmatter).toEqual({});
+
+    expect(isMarkdownExtension("x.markdown")).toBe(true);
+    expect(isMarkdownExtension("x.md")).toBe(true);
+    expect(isMarkdownExtension("x.mdx")).toBe(false);
+  });
+
+  it("FX-PATH-OVERRIDE — frontmatter path: wins, not in metadata", () => {
+    const n = parseFixture("deep/orig.md", "---\npath: Custom/Place\n---\nbody");
+    expect(n.path).toBe("Custom/Place");
+    expect(tags(n)).toEqual([]);
+    expect(n.id).toBeUndefined();
+    expect(n.content).toBe("body");
+    expect(n.frontmatter).toEqual({});
+  });
+
+  it("FX-PATH-OVERRIDE-EXT — frontmatter path: override is extension-stripped", () => {
+    // Pins contract §1.8: a `path:` override ending in .md/.markdown has
+    // its extension stripped (matches the web side). A real web-side
+    // divergence here stayed green because nothing pinned the invariant.
+    const n = parseFixture("deep/orig.md", "---\npath: My/Note.md\n---\nbody");
+    expect(n.path).toBe("My/Note");
+    expect(tags(n)).toEqual([]);
+    expect(n.id).toBeUndefined();
+    expect(n.content).toBe("body");
+    expect(n.frontmatter).toEqual({});
+  });
+
+  it("FX-PATH-NORMALIZE — backslash + collapse + case-preserve", () => {
+    // Frontmatter path value: \Win\Path\\x\  (double-quoted in YAML).
+    const n = parseFixture("X.md", '---\npath: "\\\\Win\\\\Path\\\\\\\\x\\\\"\n---\nb');
+    expect(n.path).toBe("Win/Path/x");
+    expect(n.content).toBe("b");
+    expect(n.frontmatter).toEqual({});
+  });
+
+  it("FX-CREATED-AT — created_at + updated_at hoisted verbatim, not in metadata", () => {
+    const n = parseFixture(
+      "CA.md",
+      "---\nid: t1\ncreated_at: 2024-05-01T10:00:00Z\nupdated_at: 2024-06-01T12:00:00Z\n---\nbody",
+    );
+    expect(n.path).toBe("CA");
+    expect(n.id).toBe("t1");
+    expect(n.createdAt).toBe("2024-05-01T10:00:00Z");
+    expect(n.updatedAt).toBe("2024-06-01T12:00:00Z");
+    expect(n.content).toBe("body");
+    expect(n.frontmatter).toEqual({});
+  });
+
+  it("FX-CREATED-AT-CAMEL — camelCase createdAt fallback", () => {
+    const n = parseFixture("CC.md", "---\ncreatedAt: 2024-05-01T10:00:00Z\n---\nx");
+    expect(n.path).toBe("CC");
+    expect(n.createdAt).toBe("2024-05-01T10:00:00Z");
+    expect(n.frontmatter).toEqual({});
+  });
+
+  it("FX-NO-ID — id absent → field omitted", () => {
+    const n = parseFixture("NI.md", "---\ntitle: Hello\n---\nbody");
+    expect(n.path).toBe("NI");
+    expect(n.id).toBeUndefined();
+    expect(tags(n)).toEqual([]);
+    expect(n.content).toBe("body");
+    expect(n.frontmatter).toEqual({ title: "Hello" });
+  });
+
+  it("FX-DOTDIR-EXCLUDE — intake exclusion classifier", () => {
+    expect(isExcludedPath(".obsidian/app.json")).toBe(true);
+    expect(isExcludedPath(".trash/x.md")).toBe(true);
+    expect(isExcludedPath(".git/config")).toBe(true);
+    expect(isExcludedPath(".parachute/vault.yaml")).toBe(true);
+    expect(isExcludedPath("__MACOSX/x")).toBe(true);
+    expect(isExcludedPath("node_modules/y/z.md")).toBe(true);
+    expect(isExcludedPath(".DS_Store")).toBe(true);
+    expect(isExcludedPath("sub/.hidden.md")).toBe(true);
+    expect(isExcludedPath("Notes/a.md")).toBe(false);
+    expect(isExcludedPath("Notes/Sub/b.markdown")).toBe(false);
+  });
+
+  it("FX-WIKILINK-PASSTHROUGH — wikilinks untouched, inline #tag still extracted", () => {
+    const content = "See [[Other]] and ![[Embed]] and #tag";
+    const n = parseFixture("WL.md", content);
+    expect(n.content).toContain("[[Other]]");
+    expect(n.content).toContain("![[Embed]]");
+    expect(tags(n)).toEqual(["tag"]);
+    expect(n.frontmatter).toEqual({});
+  });
+
+  it("FX-CRLF — CRLF frontmatter", () => {
+    const n = parseFixture("CR.md", "---\r\nid: cr1\r\ntags: [a]\r\n---\r\nbody");
+    expect(n.path).toBe("CR");
+    expect(n.id).toBe("cr1");
+    expect(tags(n)).toEqual(["a"]);
+    expect(n.content).toBe("body");
+    expect(n.frontmatter).toEqual({});
+  });
+
+  it("FX-DOTTED-KEY — dotted frontmatter key accepted, not confused with created_at", () => {
+    const n = parseFixture("DK.md", "---\ncreated.at: 2024\nid: dk1\n---\nx");
+    expect(n.path).toBe("DK");
+    expect(n.id).toBe("dk1");
+    expect(n.createdAt).toBeUndefined();
+    expect(n.frontmatter).toEqual({ "created.at": 2024 });
+    expect(n.content).toBe("x");
+  });
+
+  it("FX-COMMENT-LINE — comment inside frontmatter is skipped", () => {
+    const n = parseFixture("CM.md", "---\n# a yaml comment\nid: cm1\n---\nbody");
+    expect(n.path).toBe("CM");
+    expect(n.id).toBe("cm1");
+    expect(n.content).toBe("body");
+    expect(n.frontmatter).toEqual({});
+  });
+
+  it("FX-NO-FRONTMATTER — plain markdown, inline tag only", () => {
+    const content = "# Title\n\nbody with #tag";
+    const n = parseFixture("P.md", content);
+    expect(n.path).toBe("P");
+    expect(n.id).toBeUndefined();
+    expect(tags(n)).toEqual(["tag"]);
+    expect(n.content).toBe(content);
+    expect(n.frontmatter).toEqual({});
+  });
+
+  it("FX-METADATA-EXCLUSIONS — all seven hoisted keys excluded from metadata", () => {
+    const n = parseFixture(
+      "M.md",
+      "---\nid: i\npath: P/Q\ntags: [t]\ncreated_at: 2024\ncreatedAt: 2024\nupdated_at: 2024\nupdatedAt: 2024\nextra: keep\n---\nb",
+    );
+    expect(n.path).toBe("P/Q");
+    expect(n.id).toBe("i");
+    expect(tags(n)).toEqual(["t"]);
+    expect(n.createdAt).toBe("2024");
+    expect(n.updatedAt).toBe("2024");
+    expect(n.content).toBe("b");
+    expect(n.frontmatter).toEqual({ extra: "keep" });
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Write tier — real `importObsidianNotes` adapter against an in-memory Store.
+// ---------------------------------------------------------------------------
+
+describe("alignment: write tier (importObsidianNotes adapter)", () => {
+  let store: SqliteStore;
+
+  beforeEach(() => {
+    store = new SqliteStore(new Database(":memory:"));
+  });
+
+  it("FX-CREATED-AT — timestamps pegged on the id path (not new Date())", async () => {
+    const note = parseFixture(
+      "CA.md",
+      "---\nid: t1\ncreated_at: 2024-05-01T10:00:00Z\nupdated_at: 2024-06-01T12:00:00Z\n---\nbody",
+    );
+    const { imported, skipped } = await importObsidianNotes(store, [note]);
+    expect(imported).toBe(1);
+    expect(skipped).toBe(0);
+    const stored = (await store.getNote("t1"))!;
+    expect(stored).toBeTruthy();
+    expect(stored.createdAt).toBe("2024-05-01T10:00:00Z");
+    expect(stored.updatedAt).toBe("2024-06-01T12:00:00Z");
+  });
+
+  it("FX-CREATED-AT (no-id variant) — minted note still gets the frontmatter created_at", async () => {
+    const note = parseFixture(
+      "CA.md",
+      "---\ncreated_at: 2024-05-01T10:00:00Z\nupdated_at: 2024-06-01T12:00:00Z\n---\nbody",
+    );
+    expect(note.id).toBeUndefined();
+    const { imported } = await importObsidianNotes(store, [note]);
+    expect(imported).toBe(1);
+    const stored = (await store.getNoteByPath("CA"))!;
+    expect(stored).toBeTruthy();
+    expect(stored.createdAt).toBe("2024-05-01T10:00:00Z");
+    expect(stored.updatedAt).toBe("2024-06-01T12:00:00Z");
+  });
+
+  it("FX-ID-COLLISION — id-upsert path guard skips, does not overwrite", async () => {
+    // Pre-seed a note id=dup1 at path Existing/Place.
+    await store.createNoteRaw("original body", { id: "dup1", path: "Existing/Place" });
+    const before = (await store.getNote("dup1"))!;
+
+    const note = parseFixture("anything.md", "---\nid: dup1\npath: Different/Place\n---\nnew body");
+    expect(note.id).toBe("dup1");
+    expect(note.path).toBe("Different/Place");
+
+    const { imported, skipped } = await importObsidianNotes(store, [note]);
+    expect(imported).toBe(0);
+    expect(skipped).toBe(1);
+
+    // The pre-existing note is untouched.
+    const after = (await store.getNote("dup1"))!;
+    expect(after.content).toBe("original body");
+    expect(after.path).toBe("Existing/Place");
+    expect(before.content).toBe(after.content);
+    // No new note created at Different/Place.
+    expect(await store.getNoteByPath("Different/Place")).toBeNull();
+  });
+
+  it("FX-SAME-STEM-COLLISION — Foo.md + Foo.markdown → 1 created, 1 skipped, no throw", async () => {
+    const fooMd = parseFixture("Foo.md", "AAA");
+    const fooMarkdown = parseFixture("Foo.markdown", "BBB");
+    expect(fooMd.path).toBe("Foo");
+    expect(fooMarkdown.path).toBe("Foo");
+
+    // Sorted walk order: Foo.markdown sorts before Foo.md.
+    const { imported, skipped } = await importObsidianNotes(store, [fooMarkdown, fooMd]);
+    expect(imported).toBe(1);
+    expect(skipped).toBe(1);
+
+    const stored = (await store.getNoteByPath("Foo"))!;
+    expect(stored).toBeTruthy();
+    expect(["AAA", "BBB"]).toContain(stored.content);
+  });
+
+  it("intra-batch collision survives even when dedup is bypassed (try/catch isolation)", async () => {
+    // Two no-id notes at the same path but built so the second slips past
+    // the seenPaths guard would still be caught by the UNIQUE insert. Here
+    // we exercise the belt-and-suspenders try/catch by forcing a duplicate
+    // through with distinct objects (same normalized path).
+    const a: ObsidianNote = { path: "Dup", content: "one", frontmatter: {}, tags: [] };
+    const b: ObsidianNote = { path: "Dup", content: "two", frontmatter: {}, tags: [] };
+    const { imported, skipped } = await importObsidianNotes(store, [a, b]);
+    expect(imported).toBe(1);
+    expect(skipped).toBe(1);
+    expect((await store.getNoteByPath("Dup"))!.content).toBe("one");
+  });
+
+  it("id-upsert same-path updates content + replaces tags", async () => {
+    await store.createNoteRaw("v1", { id: "up1", path: "Same/Place", tags: ["old"] });
+    const note = parseFixture("x.md", "---\nid: up1\npath: Same/Place\ntags: [new]\n---\nv2");
+    const { imported, skipped } = await importObsidianNotes(store, [note]);
+    expect(imported).toBe(1);
+    expect(skipped).toBe(0);
+    const stored = (await store.getNote("up1"))!;
+    expect(stored.content).toBe("v2");
+    expect(stored.tags).toEqual(["new"]);
+  });
+});

package/core/src/obsidian.ts

@@ -33,23 +33,41 @@ export {
   parseFrontmatter,
   extractInlineTags,
   walkMarkdownFiles,
+  normalizeTagValue,
+  isMarkdownExtension,
+  isExcludedPath,
 } from "./portable-md.js";
 
-import { parseFrontmatter, walkMarkdownFiles, extractInlineTags } from "./portable-md.js";
+import {
+  parseFrontmatter,
+  walkMarkdownFiles,
+  extractInlineTags,
+  normalizeTagValue,
+} from "./portable-md.js";
 
 // ---------------------------------------------------------------------------
 // Types
 // ---------------------------------------------------------------------------
 
 export interface ObsidianNote {
-  /** Relative path without .md extension (e.g., "Projects/Parachute/README") */
+  /** Relative path without .md/.markdown extension (e.g.,
+   *  "Projects/Parachute/README"). A frontmatter `path:` override wins. */
   path: string;
   /** Raw markdown content (frontmatter stripped) */
   content: string;
-  /** Parsed YAML frontmatter */
+  /** Parsed YAML frontmatter with hoisted keys (id/path/tags/timestamps)
+   *  removed — i.e. the metadata bag the importer persists. */
   frontmatter: Record<string, unknown>;
   /** Tags from both frontmatter and inline #tags */
   tags: string[];
+  /** Frontmatter `id` (string, trimmed, non-empty), if present. The write
+   *  adapter upserts-by-id when set. Absent → field omitted. */
+  id?: string;
+  /** Frontmatter `created_at` / `createdAt` (verbatim string, no Date
+   *  coercion), if present. Preserved on write. */
+  createdAt?: string;
+  /** Frontmatter `updated_at` / `updatedAt` (verbatim string), if present. */
+  updatedAt?: string;
 }
 
 export interface ImportStats {
@@ -60,13 +78,43 @@ export interface ImportStats {
   errors: { path: string; error: string }[];
 }
 
-/** Tags from frontmatter (handles both array and string formats). */
+/**
+ * Tags from frontmatter (handles both array and string formats), routed
+ * through the canonical `normalizeTagValue` (contract C6 / §1.4) so they
+ * are slug-validated, lowercased, and `#`-stripped identically to the web
+ * parser. A string value is split on `/[,\s]+/` (comma OR whitespace).
+ * Invalid values (`My Tag!`, non-scalars) are dropped.
+ */
 function extractFrontmatterTags(frontmatter: Record<string, unknown>): string[] {
   const raw = frontmatter.tags;
-  if (!raw) return [];
-  if (Array.isArray(raw)) return raw.map((t) => String(t).toLowerCase().trim()).filter(Boolean);
-  if (typeof raw === "string") return raw.split(",").map((t) => t.toLowerCase().trim()).filter(Boolean);
-  return [];
+  if (raw === undefined || raw === null) return [];
+  const candidates: unknown[] = Array.isArray(raw)
+    ? raw
+    : typeof raw === "string"
+      ? raw.split(/[,\s]+/)
+      : [];
+  const out: string[] = [];
+  for (const c of candidates) {
+    const tag = normalizeTagValue(c);
+    if (tag) out.push(tag);
+  }
+  return out;
+}
+
+/**
+ * Normalize an import path (contract §1.8). Case-PRESERVING: backslash →
+ * forward slash, strip trailing `.md`/`.markdown`, collapse repeated
+ * slashes, trim leading/trailing slashes. Empty result → "". Does not
+ * lowercase or slugify (friend-friendly paths). Agrees with the Store's
+ * `paths.ts::normalizePath` on the slug rules; additionally strips
+ * `.markdown` and returns "" (not null) for empty.
+ */
+function normalizeImportPath(p: string): string {
+  return p
+    .replace(/\\/g, "/")
+    .replace(/\.(md|markdown)$/i, "")
+    .replace(/\/+/g, "/")
+    .replace(/^\/+|\/+$/g, "");
 }
 
 // ---------------------------------------------------------------------------
@@ -77,20 +125,59 @@ export function parseObsidianFile(filePath: string, vaultRoot: string): Obsidian
   const raw = readFileSync(filePath, "utf-8");
   const { frontmatter, content } = parseFrontmatter(raw);
 
-  // Path: relative to vault root, without .md extension
-  const rel = relative(vaultRoot, filePath);
-  const path = rel.replace(/\.md$/i, "");
+  // Path: a frontmatter `path:` override wins (contract §1.8); otherwise
+  // derive from the source filename. Both routed through the
+  // case-preserving `normalizeImportPath` (strips .md/.markdown,
+  // backslash→/, collapse + trim slashes).
+  const fmPath = frontmatter.path;
+  const path =
+    typeof fmPath === "string" && fmPath.trim() !== ""
+      ? normalizeImportPath(fmPath.trim())
+      : normalizeImportPath(relative(vaultRoot, filePath));
+
+  // Hoist id (contract §1.5) — string, trimmed, non-empty.
+  const rawId = frontmatter.id;
+  const id =
+    typeof rawId === "string" && rawId.trim() !== "" ? rawId.trim() : undefined;
+
+  // Hoist created_at/updated_at (contract §1.6) — verbatim string, with
+  // camelCase fallback, NO Date coercion.
+  const createdAt = hoistTimestamp(frontmatter.created_at ?? frontmatter.createdAt);
+  const updatedAt = hoistTimestamp(frontmatter.updated_at ?? frontmatter.updatedAt);
 
-  // Merge tags from frontmatter and inline
+  // Merge tags from frontmatter and inline.
   const fmTags = extractFrontmatterTags(frontmatter);
   const inlineTags = extractInlineTags(content);
   const allTags = [...new Set([...fmTags, ...inlineTags])];
 
-  // Remove tags from metadata (they go to the tags table)
+  // Strip all hoisted keys from the metadata bag (contract C7) — they
+  // become first-class note fields / the tags table, not metadata.
   const metadata = { ...frontmatter };
+  delete metadata.id;
+  delete metadata.path;
   delete metadata.tags;
+  delete metadata.created_at;
+  delete metadata.createdAt;
+  delete metadata.updated_at;
+  delete metadata.updatedAt;
+
+  const note: ObsidianNote = { path, content, frontmatter: metadata, tags: allTags };
+  if (id !== undefined) note.id = id;
+  if (createdAt !== undefined) note.createdAt = createdAt;
+  if (updatedAt !== undefined) note.updatedAt = updatedAt;
+  return note;
+}
 
-  return { path, content, frontmatter: metadata, tags: allTags };
+/** Coerce a hoisted timestamp frontmatter value to a verbatim trimmed
+ *  string (contract §1.6) — no Date coercion. Numbers (e.g. a bare year
+ *  `2024`) stringify; non-scalars are dropped. */
+function hoistTimestamp(v: unknown): string | undefined {
+  if (typeof v === "string") {
+    const t = v.trim();
+    return t === "" ? undefined : t;
+  }
+  if (typeof v === "number") return String(v);
+  return undefined;
 }
 
 // ---------------------------------------------------------------------------
@@ -131,6 +218,139 @@ export function parseObsidianVault(vaultPath: string): {
   return { notes, errors };
 }
 
+// ---------------------------------------------------------------------------
+// Legacy import write adapter (contract C10)
+// ---------------------------------------------------------------------------
+
+import type { Note } from "./types.js";
+
+/**
+ * The Store surface `importObsidianNotes` needs. `SqliteStore` satisfies
+ * this structurally; defined locally (rather than importing the full
+ * `Store` interface) because `createNoteRaw` is a Store-implementation
+ * method, not on the public `Store` interface.
+ */
+export interface ImportWriteStore {
+  getNote(id: string): Promise<Note | null>;
+  getNoteByPath(path: string, extension?: string): Promise<Note | null>;
+  createNoteRaw(
+    content: string,
+    opts?: {
+      id?: string;
+      path?: string;
+      tags?: string[];
+      metadata?: Record<string, unknown>;
+      created_at?: string;
+      extension?: string;
+    },
+  ): Promise<Note>;
+  updateNote(
+    id: string,
+    updates: { content?: string; path?: string; metadata?: Record<string, unknown> },
+  ): Promise<Note>;
+  tagNote(noteId: string, tags: string[]): Promise<void>;
+  untagNote(noteId: string, tags: string[]): Promise<void>;
+  restoreNoteTimestamps(id: string, createdAt: string, updatedAt: string): Promise<void>;
+}
+
+/**
+ * Write parsed Obsidian notes into the Store (legacy import path —
+ * contract C10). Behavior:
+ *
+ *  - **id-aware upsert** (correction #4): a frontmatter `id` upserts by id.
+ *    If that id already exists at a DIFFERENT path, the import does NOT
+ *    overwrite the unrelated note — it skips with a warning. Same id +
+ *    same/absent path updates in place.
+ *  - **timestamp preservation** (correction #3): frontmatter
+ *    `created_at`/`updated_at` are pegged via `restoreNoteTimestamps` on
+ *    BOTH the id and no-id branches (the no-id path mints an id first).
+ *  - **intra-batch path-dedup + write isolation** (correction #5):
+ *    `Foo.md` + `Foo.markdown` both normalize to path `Foo`; the second is
+ *    counted skipped (dedup OR a caught `PathConflictError`). Each note's
+ *    write is wrapped in try/catch so one failure never aborts the batch.
+ *
+ * Does NOT run wikilink sync — the caller does a single post-batch pass
+ * (much faster for large vaults). Returns `{ imported, skipped }`.
+ */
+export async function importObsidianNotes(
+  store: ImportWriteStore,
+  notes: ObsidianNote[],
+): Promise<{ imported: number; skipped: number }> {
+  let imported = 0;
+  let skipped = 0;
+
+  // `getNoteByPath` matches COLLATE NOCASE, so the dedup key is lowercased.
+  const seenPaths = new Set<string>();
+
+  for (const note of notes) {
+    const metadata = Object.keys(note.frontmatter).length > 0 ? note.frontmatter : undefined;
+
+    try {
+      if (note.id) {
+        const existing = await store.getNote(note.id);
+        if (existing && existing.path != null && note.path && existing.path !== note.path) {
+          console.warn(
+            `skip: id ${note.id} exists at "${existing.path}", incoming path "${note.path}" differs`,
+          );
+          skipped++;
+          continue;
+        }
+        if (existing) {
+          await store.updateNote(note.id, {
+            content: note.content,
+            ...(note.path ? { path: note.path } : {}),
+            ...(metadata ? { metadata: metadata as Record<string, unknown> } : {}),
+          });
+          if (existing.tags && existing.tags.length > 0) await store.untagNote(note.id, existing.tags);
+          if (note.tags.length > 0) await store.tagNote(note.id, note.tags);
+        } else {
+          await store.createNoteRaw(note.content, {
+            id: note.id,
+            path: note.path || undefined,
+            tags: note.tags.length > 0 ? note.tags : undefined,
+            metadata: metadata as Record<string, unknown>,
+          });
+        }
+        if (note.createdAt) {
+          await store.restoreNoteTimestamps(note.id, note.createdAt, note.updatedAt ?? note.createdAt);
+        }
+        if (note.path) seenPaths.add(note.path.toLowerCase());
+        imported++;
+      } else {
+        const key = (note.path || "").toLowerCase();
+        if (note.path && seenPaths.has(key)) {
+          skipped++;
+          continue;
+        }
+        const existing = note.path ? await store.getNoteByPath(note.path) : null;
+        if (existing) {
+          skipped++;
+          if (note.path) seenPaths.add(key);
+          continue;
+        }
+        const created = await store.createNoteRaw(note.content, {
+          path: note.path || undefined,
+          tags: note.tags.length > 0 ? note.tags : undefined,
+          metadata: metadata as Record<string, unknown>,
+        });
+        if (note.path) seenPaths.add(key);
+        if (note.createdAt) {
+          await store.restoreNoteTimestamps(created.id, note.createdAt, note.updatedAt ?? note.createdAt);
+        }
+        imported++;
+      }
+    } catch (err) {
+      // A collision that slips past the dedup (or a path-conflict on the
+      // id-upsert branch) throws from the UNIQUE insert. Collect + continue
+      // rather than aborting the whole import (correction #5).
+      console.warn(`skip: ${note.path}: ${err instanceof Error ? err.message : String(err)}`);
+      skipped++;
+    }
+  }
+
+  return { imported, skipped };
+}
+
 // ---------------------------------------------------------------------------
 // Legacy export — kept for back-compat. New code: use `toPortableMarkdown`.
 // ---------------------------------------------------------------------------

package/core/src/portable-md.ts

@@ -2091,11 +2091,29 @@ 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/, "");
+  // 1. Strip a leading UTF-8 BOM (U+FEFF) if present. Without this an
+  //    Obsidian export saved with a BOM (`---\n…`) fails the open
+  //    test and the whole file — frontmatter included — falls into the
+  //    body, silently losing id/tags/timestamps (contract FX-FENCE-BOM).
+  const src = raw.charCodeAt(0) === 0xfeff ? raw.slice(1) : raw;
+
+  // 2. Line-scan close-fence (CRLF-aware). The opening line must be
+  //    EXACTLY `---`; the closing fence is the FIRST subsequent line that
+  //    is EXACTLY `---` — not `----`, not `---text`, not `  ---`. An
+  //    unclosed block means the whole file is body (never swallow). This
+  //    replaces the old `indexOf("\n---")` which wrongly matched `\n----`
+  //    and `\n---more` (contract §1.1, FX-FENCE-FOURDASH-OPEN).
+  const lines = src.split(/\r?\n/);
+  if (lines[0] !== "---") return { frontmatter: {}, content: src };
+
+  let closeIdx = -1;
+  for (let i = 1; i < lines.length; i++) {
+    if (lines[i] === "---") { closeIdx = i; break; }
+  }
+  if (closeIdx === -1) return { frontmatter: {}, content: src };
+
+  const yamlBlock = lines.slice(1, closeIdx).join("\n");
+  const content = lines.slice(closeIdx + 1).join("\n");
   return { frontmatter: parseBlock(yamlBlock, 0).value, content };
 }
 
@@ -2119,11 +2137,16 @@ function parseBlock(text: string, baseIndent: number): ParseResult {
   while (i < lines.length) {
     const line = lines[i]!;
     if (line.trim() === "") { i++; continue; }
+    // Skip `#`-comment lines (contract C3 / §1.2). A comment at the
+    // block's base level is not a key line; the parser must step over it.
+    if (line.trimStart().startsWith("#")) { i++; continue; }
     const indent = countLeadingSpaces(line);
     if (indent < baseIndent) break;
     if (indent > baseIndent) { i++; continue; } // shouldn't happen at this level
 
-    const kv = line.slice(baseIndent).match(/^([\w][\w-]*):\s*(.*)$/);
+    // Key regex (contract C2 / §1.2): dots allowed in keys, optional
+    // whitespace before the colon (`created.at:` / `key :` both parse).
+    const kv = line.slice(baseIndent).match(/^([\w][\w.-]*)\s*:\s*(.*)$/);
     if (!kv) { i++; continue; }
     const key = kv[1]!;
     const valueText = kv[2]!.trim();
@@ -2199,7 +2222,8 @@ function parseArrayBlock(lines: string[], start: number, arrayIndent: number): {
     // First content after `- `.
     const after = line.slice(indent + 2).trim();
     // Is this a scalar item (`- foo`) or an object item (`- key: value`)?
-    const objMatch = after.match(/^([\w][\w-]*):\s*(.*)$/);
+    // Key regex matches parseBlock's (contract C2): dots + optional space.
+    const objMatch = after.match(/^([\w][\w.-]*)\s*:\s*(.*)$/);
     if (!objMatch) {
       result.push(parseScalarOrInline(after));
       i++;
@@ -2251,7 +2275,7 @@ function parseArrayBlock(lines: string[], start: number, arrayIndent: number): {
       const sibIndent = countLeadingSpaces(sib);
       if (sibIndent !== itemIndent) break;
       if (sib.slice(sibIndent).startsWith("- ")) break;
-      const sibKv = sib.slice(sibIndent).match(/^([\w][\w-]*):\s*(.*)$/);
+      const sibKv = sib.slice(sibIndent).match(/^([\w][\w.-]*)\s*:\s*(.*)$/);
       if (!sibKv) break;
       const sibKey = sibKv[1]!;
       const sibValue = sibKv[2]!.trim();
@@ -2287,6 +2311,36 @@ function parseArrayBlock(lines: string[], start: number, arrayIndent: number): {
   return { value: result, consumed: i - start };
 }
 
+/**
+ * Quote-aware split of an inline-array body on top-level commas
+ * (contract C4 / §1.2). A comma inside a single- or double-quoted string
+ * does not separate items, so `"a, b", c` → `['"a, b"', 'c']`. Quote
+ * chars are preserved in the parts; `parseScalarOrInline` strips them via
+ * `unquote`. Mirrors the web parser's `splitInlineArray`.
+ */
+function splitInlineArray(inner: string): string[] {
+  const parts: string[] = [];
+  let buf = "";
+  let quote: '"' | "'" | null = null;
+  for (let i = 0; i < inner.length; i++) {
+    const ch = inner[i]!;
+    if (quote) {
+      buf += ch;
+      if (ch === quote) quote = null;
+    } else if (ch === '"' || ch === "'") {
+      quote = ch;
+      buf += ch;
+    } else if (ch === ",") {
+      parts.push(buf);
+      buf = "";
+    } else {
+      buf += ch;
+    }
+  }
+  parts.push(buf);
+  return parts;
+}
+
 /**
  * Parse a scalar or inline form (`[a, b]`, `{ k: v }`). Used for the
  * value portion of `key: value` lines.
@@ -2295,7 +2349,10 @@ function parseScalarOrInline(s: string): unknown {
   if (s.startsWith("[") && s.endsWith("]")) {
     const inner = s.slice(1, -1).trim();
     if (inner === "") return [];
-    return inner.split(",").map((part) => parseScalarOrInline(part.trim()));
+    // Quote-aware split (contract C4 / §1.2): a comma inside a quoted
+    // string is NOT an item separator, so `["a, b", c]` → 2 items, not 3.
+    // Matches the web parser's `splitInlineArray`.
+    return splitInlineArray(inner).map((part) => parseScalarOrInline(part.trim()));
   }
   if (s.startsWith("{") && s.endsWith("}")) {
     const inner = s.slice(1, -1).trim();
@@ -2376,18 +2433,59 @@ function unquote(s: string): unknown {
 // Directory walking — shared with obsidian.ts
 // ---------------------------------------------------------------------------
 
-/** Recursively list all .md files in a directory, excluding hidden dirs
- *  (including `.parachute/` and `.obsidian/`). */
+/**
+ * Markdown-file classification (contract §1.7). Case-insensitive `.md`
+ * OR `.markdown`. `.mdx`, `.txt`, etc. are NOT markdown for the importer.
+ * Identical to the web parser's classifier.
+ */
+export function isMarkdownExtension(path: string): boolean {
+  return /\.(md|markdown)$/i.test(path);
+}
+
+/**
+ * Named intake-excluded directory/entry segments (contract §1.9). The
+ * generic `startsWith(".")` rule below subsumes the dot-prefixed ones;
+ * the named set is kept explicit for readability + to cover
+ * `__MACOSX`/`node_modules` (which do not start with ".").
+ */
+const EXCLUDED_SEGMENTS = new Set([
+  ".obsidian",
+  ".trash",
+  ".git",
+  ".parachute",
+  "__MACOSX",
+  "node_modules",
+]);
+
+/**
+ * Intake (file-selection) exclusion (contract §1.9). Excludes a source
+ * path if ANY `/`-segment is a named-excluded entry OR starts with "."
+ * (generic dotfile/dotdir). Applied identically by both parsers before
+ * parsing. The generic dot rule means legit dot-prefixed user files
+ * (`.daily-note.md`) ARE excluded — the chosen, consistent behavior.
+ */
+export function isExcludedPath(sourcePath: string): boolean {
+  for (const segment of sourcePath.split("/")) {
+    if (segment === "") continue;
+    if (EXCLUDED_SEGMENTS.has(segment)) return true;
+    if (segment.startsWith(".")) return true;
+  }
+  return false;
+}
+
+/** Recursively list all .md / .markdown files in a directory, excluding
+ *  hidden + named-internal dirs per the canonical `isExcludedPath` rule
+ *  (`.parachute/`, `.obsidian/`, `node_modules`, …). Legacy import path. */
 export function walkMarkdownFiles(dir: string): string[] {
   const results: string[] = [];
   function walk(current: string) {
     for (const entry of readdirSync(current)) {
-      if (entry.startsWith(".")) continue;
-      if (entry === "node_modules") continue;
+      // Per-segment exclusion: the named set + generic dotfile rule.
+      if (EXCLUDED_SEGMENTS.has(entry) || entry.startsWith(".")) 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);
+      else if (stat.isFile() && isMarkdownExtension(entry)) results.push(full);
     }
   }
   walk(dir);
@@ -2417,15 +2515,43 @@ export function walkContentFiles(dir: string): string[] {
   return results.sort();
 }
 
+/**
+ * Canonical inline-tag regex (contract §1.3). `#` at line-start or after
+ * whitespace; body chars `[A-Za-z0-9_/-]` (slash for hierarchy); the tag
+ * MUST contain ≥1 non-numeric char (the middle `[A-Za-z_/-]`), so `#2024`
+ * is NOT a tag but `#v2`, `#2024-plan`, `#area/sub` are. Identical to the
+ * web parser's `INLINE_HASHTAG`.
+ */
+const INLINE_TAG_REGEX = /(?:^|\s)#([A-Za-z0-9_/-]*[A-Za-z_/-][A-Za-z0-9_/-]*)/g;
+
+/**
+ * Normalize + slug-validate a tag value (contract §1.4). Shared by inline
+ * tag extraction and frontmatter tag extraction (obsidian.ts re-exports
+ * this) so both surfaces validate identically. Returns null when the
+ * value is unusable (non-string non-scalar, empty, or fails slug rules).
+ */
+export function normalizeTagValue(v: unknown): string | null {
+  if (typeof v === "number" || typeof v === "boolean") {
+    return String(v).toLowerCase();
+  }
+  if (typeof v !== "string") return null;
+  const stripped = v.trim().replace(/^#/, "").toLowerCase();
+  if (stripped === "") return null;
+  // Slug-validate: lowercase alnum, underscore, hyphen, slash (hierarchy).
+  if (!/^[a-z0-9_/-]+$/.test(stripped)) return null;
+  return stripped;
+}
+
 /** Extract inline #tags from markdown content. Excludes tags in code blocks. */
 export function extractInlineTags(content: string): string[] {
   let stripped = content.replace(/```[\s\S]*?```/g, "");
   stripped = stripped.replace(/`[^`\n]+`/g, "");
   const tags = new Set<string>();
-  const regex = /(?:^|\s)#([\w][\w/-]*[\w]|[\w])/gm;
+  const regex = new RegExp(INLINE_TAG_REGEX.source, INLINE_TAG_REGEX.flags);
   let match: RegExpExecArray | null;
   while ((match = regex.exec(stripped)) !== null) {
-    tags.add(match[1]!.toLowerCase());
+    const tag = normalizeTagValue(match[1]!);
+    if (tag) tags.add(tag);
   }
   return [...tags];
 }

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/package.json

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

package/src/cli.ts

@@ -2760,34 +2760,17 @@ async function cmdImport(args: string[]) {
     return;
   }
 
-  // Import into vault — use createNoteRaw to skip per-note wikilink sync,
-  // then do a single pass after all notes are imported (much faster for large vaults).
+  // Import into vault — use the shared `importObsidianNotes` adapter
+  // (obsidian.ts). It uses createNoteRaw to skip per-note wikilink sync,
+  // id-aware upsert with a path-conflict guard, intra-batch collision
+  // dedup, per-note error isolation, and timestamp preservation. The
+  // single wikilink pass runs below, after all notes exist.
+  const { importObsidianNotes } = await import("../core/src/obsidian.ts");
   const store = getVaultStore(vaultName);
-  let imported = 0;
-  let skipped = 0;
+  const { imported, skipped } = await importObsidianNotes(store, notes);
 
-  for (const note of notes) {
-    // Skip if a note with this path already exists
-    const existing = await store.getNoteByPath(note.path);
-    if (existing) {
-      skipped++;
-      continue;
-    }
-
-    // Build metadata from frontmatter (excluding tags, already extracted)
-    const metadata = Object.keys(note.frontmatter).length > 0 ? note.frontmatter : undefined;
-
-    await store.createNoteRaw(note.content, {
-      path: note.path,
-      tags: note.tags.length > 0 ? note.tags : undefined,
-      metadata: metadata as Record<string, unknown>,
-    });
-    imported++;
-  }
-
-  // Single-pass wikilink sync after all notes exist
   console.log(`\nImported ${imported} notes into vault "${vaultName}"`);
-  if (skipped > 0) console.log(`Skipped ${skipped} notes (path already exists)`);
+  if (skipped > 0) console.log(`Skipped ${skipped} notes (path already exists or conflict)`);
 
   if (imported > 0) {
     const linkResult = await store.syncAllWikilinks();