v0.2
This commit is contained in:
@@ -0,0 +1,155 @@
|
||||
# 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/ ← <name>.md
|
||||
├── decisions/
|
||||
│ ├── by-date/ ← YYYY-MM-DD-<slug>.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-<slug>.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/\<slug\>.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-\<slug\>.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-<slug>.md` form.
|
||||
|
||||
### decisions/by-date/YYYY-MM-DD-\<slug\>.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/\<name\>.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.
|
||||
Reference in New Issue
Block a user