YANP Vault Specification

Core Rules

Files: .md, UTF-8, LF line endings (CRLF accepted on read; tools normalize to LF on write), lowercase kebab-case filenames, unique vault-wide (case-insensitively).

Frontmatter: YAML, optional. When present, delimited by --- at top of file.

Links: Wikilinks [[Note Title]] and [[Note Title|Display Text]] within the vault. Resolved by title or alias, case-insensitive, across full vault regardless of folder depth. Transformed to standard relative markdown links on publish — source files are never modified.

Assets: Non-.md files (images, PDFs, etc.) are referenced with standard markdown syntax: ![alt](assets/file.png). Wikilink syntax does not apply to non-.md files. Embed transclusion (![[...]]) is not part of this spec; tools may support it as an extension.

Publish output: Valid CommonMark. No wikilink syntax in rendered output.

Frontmatter Schema

All fields optional. Unknown fields must be preserved by conforming tools.

Frontmatter is written once. Fields are set at authorship and not overwritten. Corrections are the only exception. Temporal evolution belongs in appendices, not in frontmatter rewrites.

Canonical field order for agent-written notes:

---
tags:
  - topic
author: claude
hostname: nova
date: 2026-03-29
status: draft
---

List values use - (YAML requirement). Key-value pairs use :.

Tags

Both inline #tag in body text and frontmatter tags: are valid and equivalent. Conforming tools merge both sources. In practice: agents write frontmatter tags (structured); humans write inline tags (natural flow). The author field predicts which style to expect.

Tags are case-insensitive. #Tag and #tag are the same tag. Conforming tools normalize tags to lowercase when indexing.

Hierarchical tags are supported: #topic/subtopic.

Parsing boundaries: Inline tags are not parsed inside fenced code blocks, inline code spans, or raw HTML blocks. Tags in blockquotes and list items are parsed normally.

Folder Conventions

Topic-based, shallow preferred. The following folders are conventional — a vault without them is still conforming. Tools that create periodic notes should use these paths.

Reserved file: inbox.md — default capture target.

Config

~/.jot/config.json (or tool-namespaced equivalent):

{
  "vault": "/path/to/vault",
  "editor": "...",
  "noOpen": false,
  "publishDrafts": false,
  "defaults": {
    "staleDays": 30,
    "dashboardLimit": 5
  },
  "templates": "/path/to/templates",
  "queries": "/path/to/saved-queries.json"
}

Resolution Rules

Lookup precedence

When resolving a wikilink [[name]], a conforming tool searches in this order:

1. Frontmatter title (case-insensitive)
2. Frontmatter aliases entries (case-insensitive)
3. Filename stem (case-insensitive, without extension)

The first match wins. If no match is found, the link is unresolved.

Path prefix disambiguation

A wikilink target may include a path prefix: [[folder/note]]. When a path prefix is present, the tool skips the title and alias steps and matches only against the normalized file path relative to the vault root (case-insensitive, without extension). This is the canonical way to disambiguate notes that share a name or alias.

Display title

If title is absent from frontmatter, a tool may optionally use the first # H1 heading as the display title in UI and listings. However, the first H1 must not be used for wikilink resolution — resolution falls back to filename stem only.

Conflicts

If two or more notes resolve to the same name (via title, alias, or filename), the tool must either warn the user at index time or resolve to the most recently modified note. Tools must not silently pick an arbitrary winner. A conforming tool may refuse to publish a vault with unresolved conflicts.

Rename behavior

When a note is renamed, the tool must update the filename and (if present) the frontmatter title field. All inbound wikilinks across the vault that resolved to the old name must be rewritten to the new name. Aliases are not automatically updated — they may be left as additional resolution targets or removed by the user.

Delete behavior

When a note is deleted, all inbound wikilinks that previously resolved to it become unresolved. A conforming tool must warn the user before deletion if inbound links exist, listing the affected notes. The tool must not silently leave dangling links without surfacing the impact.

Conformance

A conforming tool must:

1. Read/write .md files with optional YAML frontmatter
2. Preserve unknown frontmatter fields
3. Resolve wikilinks by title, alias, or filename stem using the precedence order
4. Warn or resolve deterministically when multiple notes match a wikilink target
5. Update all inbound wikilinks when a note is renamed or moved
6. Warn before deleting a note that has inbound wikilinks
7. Reject creation of a note whose filename, title, or aliases would conflict with an existing entry in the vault index, and report the conflict
8. Transform wikilinks to relative links on publish
9. Never modify vault source during publish

A conforming vault must:

1. Use .md files, UTF-8
2. Lowercase kebab-case filenames
3. Wikilinks for internal links
4. Require no specific tool to be read or edited

Why Wikilinks?

Standard relative links [text](../path/note.md) break on rename. Wikilinks resolve by name — a rename only requires updating the filename; a conforming tool handles all inbound links automatically. The publish transform makes this invisible to SSGs.

Conforming Tools

Implementer's Reference

Everything an agent or developer needs to build a conforming tool from this spec alone.

Wikilink regex

\[\[([^\]|]+)(?:\|([^\]]+))?\]\]

Capture group 1 is the note name (used for resolution). Capture group 2, if present, is the display text. Examples:

• [[Meeting Notes]] → name: Meeting Notes, display: Meeting Notes
• [[Meeting Notes|today's meeting]] → name: Meeting Notes, display: today's meeting

Inline tag regex

(?:^|(?<=\s))#([\w][\w/-]*[\w]|[\w])

Matches #tag and #topic/subtopic at start of line or after whitespace. Strip trailing punctuation (.,;:!?) after matching. Do not scan inside fenced code blocks (```), inline code spans (`...`), or raw HTML blocks.

Complete frontmatter example

---
tags:
  - work
  - meeting
author: chris
hostname: nova
date: 2026-03-28
status: active
title: Sprint Review
aliases:
  - Weekly Sync
  - Friday Review
priority: high
due: 2026-04-01
scheduled: 2026-03-28
project: Q2 Planning
---

# Sprint Review

Attendees: [[Alice]], [[Bob]]

Discussed progress on the #planning/quarterly goals.

- [x] Review last week's action items
- [ ] Finalize budget #finance
- [ ] Schedule follow-up with [[Carol|Carol in marketing]]

Resolution algorithm

Given a wikilink target string and a vault index:

1. Lowercase the target string.
2. If the target contains a /, treat it as a path prefix. Match against normalized file paths (lowercased, without .md, relative to vault root). If exactly one match, return it. Skip steps 3–5.
3. Search all notes for a matching frontmatter title (lowercased). If exactly one match, return it.
4. Search all notes for a matching aliases entry (lowercased). If exactly one match, return it.
5. Search all notes for a matching filename stem (lowercased, without .md). If exactly one match, return it.
6. If multiple matches at any step, warn the user and resolve to the most recently modified note.
7. If no matches, mark the link as unresolved.

Publish transform

For each note in the vault (excluding status: draft notes unless publishDrafts is true; notes with no status field are always included):

1. Copy the note to the output directory, preserving folder structure.
2. Replace each [[Name]] with [Name](relative/path/to/note.md) using the resolution algorithm.
3. Replace each [[Name|Display]] with [Display](relative/path/to/note.md).
4. Leave unresolved links as plain text (no link) or mark them visibly, per tool preference.
5. Do not modify source files.

Minimum viable conforming tool

A conforming tool needs, at minimum: a vault indexer that reads all .md files and builds a name-to-path map (by title, aliases, and filename stem), a wikilink resolver that uses the precedence order above, and a publish command that rewrites wikilinks to relative markdown links in a separate output directory. Everything else — search, tags, tasks, dashboards — is useful but not required for conformance.