Editing — choosing the right write

Blenau writes commit to your repo (see How sync works). Choosing the right operation keeps your documents — and their structure — intact.

Pick the right operation

Goal	Use
Create a new document	ingest_document — creates the file and commits it
Change an existing section’s body	edit_section
Add/prepend/replace part of a section	patch_section
Rename a section (change its heading)	rename_section
Delete a section	delete_section

Each of these is a first-class, commit-backed operation, and each accepts dry_run: true to preview the resulting diff without writing.

Safe editing

1. Read the section first: get_section (or get_document_structure) returns its current content and version.
2. Edit the body only.
3. Write with edit_section, passing the expected_version you just read. This is optimistic locking: if someone else changed the section meanwhile, you get a clear conflict (with the current content) instead of silently overwriting their work.

Anti-patterns

• Don’t put a heading inside edit_section. edit_section replaces a section’s body only. A new_content that begins with a different ## Heading is a rename, not an edit, so it’s rejected with a clear error telling you to use rename_section. (This used to silently corrupt the document into a duplicate plus an orphan; it’s now a clean guardrail.)
• Never re-ingest a document to “fix” it. ingest_document replaces the whole document and, on a repo-backed doc, resets its provenance from github to manual — severing the link to your repo. Use edit_section / patch_section for changes.

Verify your edit

After writing, call get_document_structure and confirm the headings and section count are what you expect. Edits splice only the section you named — the rest of the document is left byte-for-byte untouched. Limits lists the behaviors still worth watching for.