steve/skills
Public Access
1
0
Fork 0
Code Issues 11 Pull Requests 1 Actions Packages Projects Releases Wiki Activity

phase1: update vault-conventions.md with OKF v0.1 spec alignment

Browse Source 
- Merged OKF + vault frontmatter schema
- Standard markdown links (not wikilinks)
- Bundle definition with index.md/log.md conventions
- Fixed type vocabulary (18 types)
- Bundle map for all vault directories
- Updated curation heuristics for bundle awareness
- Added OKF core principles
This commit is contained in:
gitadmin
2026-07-06 21:26:46 -04:00
parent 1676528fad
commit 41d1d48025
1 changed files with 153 additions and 20 deletions
Download Patch File Download Diff File Expand all files Collapse all files
common/pkm/pkm-curation/references/vault-conventions.md
+153 -20
View File
@@ -6,6 +6,7 @@ tags:
- knowledge-management - knowledge-management
- obsidian - obsidian
- reference - reference
- okf
- ai - ai
area: Personal Knowledge Management area: Personal Knowledge Management
project: project:
@@ -13,45 +14,164 @@ project:
# Vault Conventions # 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 ```yaml
--- ---
id: unique-id type: <OKF type name> # OKF required
aliases: [] title: <display name> # OKF recommended
tags: [] description: <one-line summary> # OKF recommended
area: Primary area/domain resource: <canonical URI> # OKF recommended (when applicable)
project: [[Project Note]] 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
--- ---
``` ```
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 **OKF extensions:** Any additional producer-defined keys may be included. Consumers MUST preserve unknown keys when round-tripping.
- explicit `[[wikilinks]]`
- atomic notes for durable ideas ---
- project, topic, and date-based organization
- consistency over novelty ## 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 ## Folder Roles
- `Inbox/`: raw capture and unprocessed notes - `Inbox/`: raw capture and unprocessed notes (not a bundle)
- `Dailies/`: day-specific notes and reflection - `Dailies/`: day-specific notes and reflection (not a bundle)
- `Templates/`: note templates - `Templates/`: note templates (not a bundle)
- `Knowledge/`: preferred home for evergreen atomic notes if the folder exists or is created - `Clippings/`: clipped web articles (not a bundle)
- project/topic folders: active work and structured reference material - `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 ## 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 - Add status and priority tags where useful
- Use `due:: YYYY-MM-DD` for due dates - Use `due:: YYYY-MM-DD` for due dates
- Add `start::` and `end::` only when explicitly requested or when tracking active work - Add `start::` and `end::` only when explicitly requested or when tracking active work
---
## Curation Heuristics ## Curation Heuristics
- A saved thing is not yet a knowledge note. - 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 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. - A long note may remain long if it is reference material; only extract notes when reuse is likely.
- Prefer gradual improvement over mass refactoring. - 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