diff --git a/common/pkm/pkm-curation/references/vault-conventions.md b/common/pkm/pkm-curation/references/vault-conventions.md index c86f8e3..53f533d 100644 --- a/common/pkm/pkm-curation/references/vault-conventions.md +++ b/common/pkm/pkm-curation/references/vault-conventions.md @@ -6,6 +6,7 @@ tags: - knowledge-management - obsidian - reference + - okf - ai area: Personal Knowledge Management project: @@ -13,45 +14,164 @@ project: # Vault Conventions -## Required Frontmatter +This vault follows the [Open Knowledge Format (OKF) v0.1](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md) as its structural backbone. All notes, bundles, and links conform to OKF conventions unless noted below. -All notes should include YAML frontmatter with: +--- + +## Frontmatter Schema (merged — OKF + vault fields) + +Every non-reserved `.md` file **MUST** have YAML frontmatter with the following fields: ```yaml --- -id: unique-id -aliases: [] -tags: [] -area: Primary area/domain -project: [[Project Note]] +type: # OKF required +title: # OKF recommended +description: # OKF recommended +resource: # OKF recommended (when applicable) +tags: [, ...] # OKF recommended + vault required +timestamp: # OKF recommended +id: # vault required +aliases: [, ...] # vault required +area: # vault required +project: # vault required --- ``` -Use an empty value for `project:` when there is no relevant project note. +### Field Notes -## Core Principles +- **`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. -- Markdown-first -- explicit `[[wikilinks]]` -- atomic notes for durable ideas -- project, topic, and date-based organization -- consistency over novelty +**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//` | ✅ (each packet is a bundle) | +| `Projects//` | ✅ (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 -- `Dailies/`: day-specific notes and reflection -- `Templates/`: note templates -- `Knowledge/`: preferred home for evergreen atomic notes if the folder exists or is created -- project/topic folders: active work and structured reference material +- `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//`: research packets, each a self-contained bundle +- `Projects//`: active project notes, each project a sub-bundle + +--- ## Task Conventions -- Use Markdown task items: `- [ ] Task description [[Project Name]]` +- 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. @@ -59,3 +179,16 @@ Use an empty value for `project:` when there is no relevant project 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