--- name: obsidian-vault-conventions description: Writing into a live Obsidian vault a human also edits — frontmatter, links, paths, and what never to touch. when_to_use: You are committing notes, digests or scripts into the valhalla-vault repository. tags: [research, conventions] --- # The vault is somebody's live workspace `valhalla-vault` is a real Obsidian vault a human edits and syncs continuously. It is not scratch space. Two consequences drive everything below. ## Never commit to `main` Mission work lands on the run's own branch. `library.rs` does this deliberately and only auto-merges when the change is provably additive — every file in `git diff --name-status base...branch` is an `A`. A rename or a delete is not additive and stops the merge. That rule protects the human: an auto-merge can add a note beside their work, never rewrite it. ## Stay in your folders ``` 60 Papers/arxiv-.md one note per paper, written by the harvest ContinuousResearch//... one folder per run — yours ``` Do not reorganise, rename or "tidy" anything outside those. What looks like a stray file is usually load-bearing in someone's graph. ## Frontmatter is the index Obsidian queries it, so it must be parseable YAML and keys must stay stable: ```yaml --- date: 2026-08-17 type: research-digest harvested: 23 surfaced: 4 --- ``` **Hash the body, not the file.** Sync rewrites `updated:` and `size_kb:` on notes it touches; hashing the whole file reports phantom edits on notes nobody changed and makes "unchanged" meaningless. ## Links `[[wikilinks]]` are the vault's native form — use them for internal references, plain markdown links for external URLs. A link to a note that does not exist yet is fine and idiomatic: it marks something worth writing. ## `source:` is not identity The vault uses `source:` for local provenance — often a path like `/Users/…/Downloads/paper.pdf`. It is not a citable identifier and must never be used as a dedup key. Identity is `arxiv:`, version suffix stripped.