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
Retire a whole document	delete_document

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.

Retiring a document

When you consolidate two documents into one, the loser has to stop existing:

delete_document(path="eng/old-runbook.md", dry_run=True)   # preview
delete_document(path="eng/old-runbook.md")                 # do it

It removes the .md from GitHub and the index, in that order — so a GitHub failure changes nothing at all — and the delete stays recoverable from git history.

Two things that look like retiring a document and are not:

• delete_section on the H1. It splices out the last section and commits an empty file. The document stays in every listing with its old title, marked ready, and answers no search. Brain health reports this as empty_document.
• Leaving a redirect stub. It’s one more file in the tree, and consolidating is supposed to leave fewer.

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.