9b41d51231
Some checks are pending
Auto-update PR branches / Update open PR branches (push) Waiting to run
CI / Frontend Static Quality Checks (push) Waiting to run
CI / Frontend Tests & Coverage (push) Waiting to run
CI / Rust Tests & Quality Checks (push) Waiting to run
CI / Linux build verification (push) Waiting to run
Deploy docs / Build VitePress site (push) Waiting to run
Deploy docs / Deploy to GitHub Pages (push) Blocked by required conditions
Release (Alpha) / Compute alpha version (push) Waiting to run
Release (Alpha) / Build release artifacts (push) Blocked by required conditions
Release (Alpha) / GitHub Release (alpha) (push) Blocked by required conditions
Release (Alpha) / Update docs and release pages (push) Blocked by required conditions
Source snapshot: 514ab1975951d94342ea38e64101d5a0f1c51c77
2.1 KiB
2.1 KiB
type, id, title, status, date
| type | id | title | status | date |
|---|---|---|---|---|
| ADR | 0006 | Flat vault structure (no type-based folders) | active | 2026-03-15 |
Context
Originally, notes were organized into type-based subfolders (project/, person/, topic/, etc.). Changing a note's type required moving it between folders, which broke wikilinks, complicated wikilink resolution (paths vs titles), and created friction for users who wanted to reorganize their knowledge. It also made vault scanning more complex and introduced edge cases around folder creation/deletion.
Decision
All user notes live as flat .md files at the vault root. Type is determined solely from the type: frontmatter field — never inferred from folder location. Only a small set of protected folders exist: type/ (type definition documents), config/ (meta-configuration), and attachments/.
Options considered
- Option A (chosen): Flat vault with frontmatter-only type — simple wikilink resolution (title/filename only), no file moves on type change, vault scanning restricted to root + protected folders. Downside: large vaults may look cluttered in Finder.
- Option B: Keep type-based folders — familiar Obsidian-like structure. Downside: type changes require file moves, wikilink resolution needs path awareness, scanning is recursive and slower.
- Option C: Hybrid (folders optional, type still from frontmatter) — maximum flexibility. Downside: two ways to do the same thing, confusing for AI agents and automation.
Consequences
- Wikilink resolution is simplified to multi-pass title/filename matching — no path-based matching needed.
- Changing a note's type is a frontmatter edit, not a file move.
- A
flatten_vaultmigration command and wizard were added for existing vaults with type folders. vault_health_checkdetects stray files in non-protected subfolders.scan_vaultonly indexes root-level.mdfiles plus protected folders — non-protected subdirectories are ignored.- Re-evaluation trigger: if users need nested folder hierarchies for non-type organization (e.g., project-specific subdirectories).