Authoring with MarkdownDataStore

This chapter describes how callers should structure files and sections so they match the datastore conventions.

File and Type Conventions

All operations are relative to the configured dataDir. When type is provided, files are read from dataDir/type; otherwise they are read directly from dataDir. File names are provided without .md.

Section Conventions

Sections are persisted in the canonical numbered heading form ### N. Name. Callers should use stable section names and avoid duplicating semantic aliases, because section-name matching is case-insensitive but normalized to one canonical section entry.

When a section is written without meaningful text, the datastore persists *None*.

Recommended Write Patterns

Use replaceFile for complete section rewrites, updateFile for targeted section upserts, and appendToFile when extending existing section content incrementally.