Moss Frontmatter

Moss Frontmatter

Frontmatter is an optional top-level YAML mapping before the note's H1.

---
status: active
tags:
  - project
people:
  - jane
---

# Note Title

Authoring Contract

• Use frontmatter for structured fields that help search, filtering, grouping, or retrieval.
• Prefer scalars and lists of strings. Moss parses nested arrays and objects but displays them read-only; preserve them unless the task explicitly requests a filesystem edit to that structure.
• type and status are workspace vocabularies, not fixed enums. Reuse values already present in the workspace when possible.
• Common fields are type, people, description, tags, and status; unknown fields are valid and must be preserved.
• For workspace notes under ~/Moss/Notes/, preserve existing created_date and let Moss set it for new notes. Do not invent or overwrite it.
• The note title comes from the leading H1, not a title field.
• Do not duplicate metadata as body headings or bold labels.
• Omit frontmatter when the note has no useful metadata.

Editing And Recovery

Filesystem writers may edit any field the task explicitly targets, including a nested value, while preserving unrelated keys. The Moss Properties UI edits supported scalar/list fields and treats nested values as read-only.

Keep YAML valid and retain the top-level mapping. If existing frontmatter is malformed, preserve it unless the user asks for repair; Moss retains malformed YAML but cannot edit it through Properties.

Final Check

• Frontmatter is the first block and closes before the H1.
• YAML is a top-level mapping.
• Unknown and unrelated fields remain intact.
• Workspace-managed created_date was not invented or overwritten.