# 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`.

**Frontmatter field semantics:**

- `created:` is the **earliest known date** the entity was tracked in the vault — *not* "today". When merging notes (e.g. promoting an `on-hold/` project into `active/`), preserve the earliest `created:` from any merged source and only update `updated:`.
- `source_notes` is a **backward link** — the note(s) that triggered or supplied content for this one (e.g. the session log a project update came from). Forward links go in the `## Related` body section, never here.
- `status:` for a project MUST match its folder under `projects/` (`active`, `incubating`, `on-hold`, `archived`). Moving the file and updating `status:` are the same operation.

> **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. Headings include `Operator`, `Fact / Pattern`, `Evidence`,
`Recommendation or Implication`, `Review Notes`. Append observed facts under the
right heading via PATCH. "The operator" is Jason — he is both
operator and architect of this vault.

### projects/active/\<slug\>.md

```markdown
---
type: project
status: active
created: 2026-06-05
updated: 2026-06-05
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-05: observation or update

## Related
- [[areas/business/business-ops]]
```

### sessions/YYYY-MM-DD-HHMM-\<slug\>.md

See `session-log-template.md`. Note ECHO uses an **HHMM time component** in the
filename (unlike a date-only convention).

### decisions/by-date/YYYY-MM-DD-\<slug\>.md

ADR-style: Context → Decision → Consequences. Mirror a link into `by-project/`.

### people/\<name\>.md

`type: person`. Use lowercase kebab-case for the slug (e.g. `jason-stedwell.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.