# Vault Layout & Frontmatter Conventions Mirrors the canonical conventions defined in the vault's own `STRUCTURE.md` and `BOOTSTRAP.md`. If those change, they are the source of truth. ## Folder Map (root-addressed) ``` /vault/ ├── CLAUDE.md ← operating contract + session protocol ├── STRUCTURE.md ← layout, taxonomy, frontmatter standard ├── BOOTSTRAP.md ← preflight/repair manifest (read first) ├── spinup.md index.md README.md ├── inbox/ │ ├── captures/ ← quick captures (inbox.md), date-prefixed lines │ ├── imports/ ← raw imported material │ └── processing-log/ ├── journal/ │ ├── daily/ ← YYYY-MM-DD.md (has an "Agent Log" section) │ ├── weekly/ monthly/ │ └── templates/ ├── projects/ ← lifecycle: incubating → active → on-hold/archived │ ├── active/ ← current work (status: active) │ ├── incubating/ ← idea captured, not yet started (status: incubating) │ ├── on-hold/ ← paused but kept (status: on-hold) │ ├── archived/ ← done / abandoned (status: archived) │ └── project-template.md ├── areas/ ← business / personal / learning / systems ├── resources/ │ ├── concepts/ references/ meetings/ source-material/ │ └── people/ ← .md ├── decisions/ │ ├── by-date/ ← YYYY-MM-DD-.md (ADR-style) │ ├── by-project/ ← mirror by project │ └── decision-template.md ├── reviews/ ← weekly / monthly / quarterly / annual ├── archive/ ← notes / projects / imports └── _agent/ ├── context/ ← current-context.md and task bundles ├── memory/ │ ├── working/ ← transient, time-boxed │ ├── episodic/ ← what happened, when │ └── semantic/ ← durable facts/patterns (operator-preferences.md) ├── sessions/ ← YYYY-MM-DD-HHMM-.md ├── templates/ ← canonical note templates ├── outputs/ ← briefs / drafts / summaries / synthesis ├── skills/ ← active / archived └── heartbeat/ ``` **Slug rules:** kebab-case, ASCII only, truncate to ~40 chars. --- ## Canonical Frontmatter Every note starts with this block. Fill what applies; leave the rest empty rather than guessing. ```yaml --- type: # see Note Types below status: # active | draft | done | archived | complete created: # YYYY-MM-DD (or YYYY-MM-DDTHH:mm for sessions) updated: # YYYY-MM-DD tags: [] agent_written: false source_notes: [] # plain relative paths as strings — NEVER [[wikilinks]] --- ``` `agent_written: true` + a populated `source_notes` is the key signal separating agent-managed content from human-authored content. When appending with POST, do not rewrite frontmatter — the append goes after existing content. To change `updated:` or `status:`, use PATCH with `Target-Type: frontmatter`. > **No `[[wikilinks]]` in frontmatter.** YAML parses `[[...]]` as nested lists, so wiki > links there break and never render as clickable links in reading view. Put all > cross-references in a **`## Related`** section in the note **body** (bulleted `[[links]]`). > Frontmatter holds scalar/string metadata only; `source_notes` values are plain relative > paths, not links. ## Note Types `daily-note`, `weekly-note`, `monthly-note`, `project`, `project-update`, `area`, `concept`, `reference`, `person`, `meeting`, `decision`, `review`, `session-log`, `working-memory`, `episodic-memory`, `semantic-memory`, `context-bundle`, `skill`, `draft`, `inbox-item`. --- ## File-Specific Conventions ### operator-preferences.md (`_agent/memory/semantic/`) The profile analog. Canonical headings: - `## Operator` — who Bryan is (one paragraph) - `## Fact / Pattern` — **promoted, deduped rules.** No date prefix. Timeless. - `## Observations` — **timestamped raw observations.** Date-prefixed lines (`- 2026-06-07: ...`). Default landing zone for new evidence. - `## Evidence` — citations/links supporting the rules - `## Recommendation or Implication` — how the rules should shape behavior - `## Review Notes` — confidence / last review date Append observed facts under `## Observations` by default. Promote to `## Fact / Pattern` (dropping the date) once a pattern stabilizes. "The operator" is Bryan; do not attribute Jason's design preferences to Bryan without evidence — Jason's preferences live in the ECHO vault. ### projects/active/\.md ```markdown --- type: project status: active created: 2026-06-07 updated: 2026-06-07 tags: [] agent_written: false source_notes: [] --- # Project Name ## Current status One paragraph, kept fresh via PATCH replace. ## Decisions - [[YYYY-MM-DD-decision-slug]] — one-line summary ## Open threads - [ ] unresolved thing ## Log - 2026-06-07: observation or update ## Related - [[areas/business/business-ops]] ``` **Lifecycle / status agreement:** a project's folder under `projects/` (`active`, `incubating`, `on-hold`, `archived`) and its `status:` frontmatter MUST match — moving the file and updating `status:` are the same operation. A note in `projects/active/` with `status: on-hold` is broken state; fix it when you see it. Keep heading text ASCII (plain hyphens, no em dashes/parentheses) so headings stay PATCH-targetable. ### sessions/YYYY-MM-DD-HHMM-\.md See `session-log-template.md`. goldbrain uses an **HHMM time component** in the filename — this is **canonical, not optional**. The four-digit local-time component makes filenames lex-sort in true chronological order, which the loading procedure relies on. Older session logs without HHMM may exist; leave them alone, but every new one must use the full `YYYY-MM-DD-HHMM-.md` form. ### decisions/by-date/YYYY-MM-DD-\.md ADR-style: Context → Decision → Consequences. Mirror a project-relevant ADR as a `[[wikilink]]` under that project's `## Decisions` heading, and optionally into `by-project/` per the vault's `STRUCTURE.md`. The by-date ADR is always the canonical record. ### people/\.md `type: person`. Use lowercase kebab-case for the slug (e.g. `bryan-gilliom.md`). --- ## Cross-References Use Obsidian wiki links freely: `[[note-name]]` or `[[folder/note]]`. The REST API doesn't resolve them, but Obsidian does when the operator browses the vault.