skills/common/pkm/pkm-curation/references/vault-conventions.md

id, aliases, tags, area, project

id	aliases	tags	area	project
pkm-curation-vault-conventions	PKM Curation Vault Conventions	knowledge-management obsidian reference okf ai	Personal Knowledge Management

Vault Conventions

This vault follows the Open Knowledge Format (OKF) v0.1 as its structural backbone. All notes, bundles, and links conform to OKF conventions unless noted below.

---

Frontmatter Schema (merged — OKF + vault fields)

Every non-reserved .md file MUST have YAML frontmatter with the following fields:

---
type: <OKF type name>              # OKF required
title: <display name>              # OKF recommended
description: <one-line summary>    # OKF recommended
resource: <canonical URI>          # OKF recommended (when applicable)
tags: [<tag>, ...]                 # OKF recommended + vault required
timestamp: <ISO 8601 datetime>     # OKF recommended
id: <unique identifier>            # vault required
aliases: [<alias>, ...]            # vault required
area: <area/domain>                # vault required
project: <project name or ''>      # vault required
---

Field Notes

• type — Must be one of the OKF type names from the Type Vocabulary table below. This is the only required OKF field.
• title — Human-readable display name. If omitted, consumers may derive a title from the filename.
• description — One-line summary. Used by index.md generators, search snippets, and previews.
• resource — A URI identifying the underlying asset the concept describes. Omit for abstract ideas.
• tags — YAML list of short strings for cross-cutting categorization. Always include at least one tag.
• timestamp — ISO 8601 datetime of last meaningful change (e.g. 2026-07-06T12:00:00Z).
• id — Stable unique identifier (kebab-case slug, never changes).
• aliases — List of alternative titles for search/discovery.
• area — Primary domain or area of knowledge.
• project — Associated project name, or empty string '' when none.

OKF extensions: Any additional producer-defined keys may be included. Consumers MUST preserve unknown keys when round-tripping.

---

Link Convention

Use standard markdown links: [text](relative/path.md).

Do NOT use [[wikilinks]]. Obsidian renders standard markdown links identically to wikilinks, and markdown links are portable across all markdown renderers.

Link Forms

Target	Markdown form
Another note in same directory	[Note Title](Note%20Title.md)
Note in subdirectory	[Note Title](../Subdir/Note%20Title.md)
Note with alias	[alias](Note%20Title.md)
Absolute (bundle-relative)	[Note Title](/path/from/bundle/root.md)
External URL	[text](https://example.org)

When to Link

Add links only when they express a real relationship:

• concept to broader concept
• source note to extracted idea
• project note to relevant knowledge note
• daily note to work done or ideas learned
• sibling concepts that genuinely inform one another

Do not link on shared words alone.

---

Bundle Definition

A bundle is a subdirectory that follows OKF progressive-disclosure conventions. Every bundle contains two reserved files:

File	Purpose
index.md	OKF progressive-disclosure listing (no frontmatter, sections with bullet links)
log.md	OKF chronological update history (datestamped entries, newest first)

These filenames are reserved — they MUST NOT be used for concept documents.

Bundle root (vault root)

sjb-brain/ (the vault root) is a bundle. It has its own index.md and log.md.

Bundle map

Path	bundle?
sjb-brain/ (root)	✅
Knowledge/	✅
Notes/ + subdirs	✅ (each subdir is a sub-bundle)
Resources/ + subdirs	✅ (each subdir is a sub-bundle)
Profiles/	✅
AI Conversation Summaries/	✅
Research/<packet>/	✅ (each packet is a bundle)
Projects/<project>/	✅ (each project is a bundle, migrate flat notes to dirs)
Inbox/	❌
Dailies/	❌
Templates/	❌
Clippings/	❌
Tasks/, tools/, wts-services/	⏳ deferred

Non-bundle directories are treated as flat collections. They do not get index.md or log.md.

---

Type Vocabulary

The following OKF type names are used in this vault. Every note MUST have exactly one type from this table.

type	Purpose
Inbox	Raw capture, unprocessed
Source	Based on external material
Concept	One durable evergreen idea
Project	Active work, planning
Daily	Day-specific activity
Reference	Lookup material, specs
Conversation Report	Narrative summary of conversation
Conversation Transcript	Raw conversation transcript
Research Synthesis	Compiled answer for a research topic
Research Claim Index	Collection of evidence-backed claims
Research Source List	Index of sources consulted
Research Glossary	Term definitions for a topic
Research Questions	Open and resolved questions
Research Log	Chronological research session log
MOC	Map of content / curated index
Template	Template note for note creation
Person	A person you want notes about
Tool	A tool, app, or service

---

Folder Roles

• Inbox/: raw capture and unprocessed notes (not a bundle)
• Dailies/: day-specific notes and reflection (not a bundle)
• Templates/: note templates (not a bundle)
• Clippings/: clipped web articles (not a bundle)
• Knowledge/: preferred home for evergreen atomic notes (bundle)
• Notes/: technical and domain notes, with subdirectories for each topic (bundle with sub-bundles)
• Resources/: reference and resource notes, with subdirectories for each domain (bundle with sub-bundles)
• Profiles/: notes about people (bundle)
• AI Conversation Summaries/: saved conversation summaries and transcripts (bundle)
• Research/<packet>/: research packets, each a self-contained bundle
• Projects/<project>/: active project notes, each project a sub-bundle

---

Task Conventions

• Use Markdown task items: - [ ] Task description [Project Name](Projects/Project%20Name.md)
• Add status and priority tags where useful
• Use due:: YYYY-MM-DD for due dates
• Add start:: and end:: only when explicitly requested or when tracking active work

---

Curation Heuristics

• A saved thing is not yet a knowledge note.
• A source note is not the same as an evergreen note.
• A link should reflect a real conceptual or project relationship.
• A long note may remain long if it is reference material; only extract notes when reuse is likely.
• Prefer gradual improvement over mass refactoring.
• When creating or editing notes inside a bundle directory, maintain the bundle's index.md (add/update entries).
• When a bundle's contents change significantly, append an entry to the bundle's log.md.

---

Core Principles

• Markdown-first
• OKF-conformant bundles with index.md and log.md
• Standard markdown [...](...) links (not wikilinks)
• Atomic notes for durable ideas
• Project, topic, and date-based organization
• Consistency over novelty