This document describes the correct workflow for creating and updating notes to avoid incomplete documents, broken links, and overwritten metadata.
Use this note for the overall create/update workflow. Use MCP Note Editing Guide for the mechanics of MCP patch, batch, put, reorder and table_op edits.
Before writing any content for a new topic area, sketch the parent/child split. The natural instinct is to put everything in one note first and split it later. This is the megadoc trap — splitting a finished megadoc is harder than writing focused notes from the start, and the split rarely happens cleanly after the fact.
Ask: what are the distinct questions a reader might want to answer? Each answer is a note. A note that answers three different questions should be three notes. This matters for LLMs too: a focused 20-block note loaded on demand costs far less context window than a 100-block megadoc loaded because one fact in it was needed.
A note has a parent and children, and for most topics that is enough. Once a topic grows to three or more closely related notes, it stops being enough: a reader arriving at any one of them cannot see the shape of the whole, and the parent index is usually too general to show it. Promote one note to a hub. The hub keeps its own content and additionally carries a compact map of the thread — what each sibling answers, and how the ideas branch.
Keep the map coarse. It exists so a reader can choose the right note in one look, not to reproduce what the notes say — roughly one line per note, plus the relationships between them. A plain-text diagram in a codeblock works well when ideas branch; prose bullets are fine when the structure is flat. If the map needs scrolling, the thread wants splitting rather than a bigger map.
Apply this to the extent it is useful and no further. Two notes and a parent link need no map. General index pages such as CONTENTS are lists and should stay lists — a mind map belongs on the hub of a specific thread, where the relationships between the ideas are themselves worth recording. A map that has to be maintained but tells a reader nothing they could not get from the link list is overhead. Worked example: Representation, Not Language.
Correct order: create children first, then update the parent.
When you need to create multiple related notes:
1. Create all child notes first with complete content.
2. Read the parent page to preserve existing content, links, and metadata.
3. Update the parent page to add links to the children.
4. Verify all links resolve correctly.
• Avoids uploading incomplete parent documents with empty sections.
• Child notes exist before being referenced.
• Clear sequential workflow - no partial states.
• Easier to verify completeness before linking.
CLI / raw HTTP: create or edit a complete JSON file, then load/PUT the whole document. Use ~/tmp/ for scratch files.
MCP: use put for complete child notes and deliberate structural rewrites; use patch or batch for targeted block edits after reading with include_block_ids: true. See MCP Note Editing Guide.
Suppose you want to document a new feature with three aspects: design, implementation, and testing.
Step 1: create child notes with full content.
# CLI example: create ~/tmp/design.json with complete content
notes load -d project/feature-design ~/tmp/design.json
# MCP equivalent: put(key="project/feature-design", value=<complete JSONHTL document>)Step 2: read the parent to preserve existing content.
notes read project
# MCP equivalent: get(key="project", include_block_ids=true)Step 3: update the parent with links to children.
# CLI: edit ~/tmp/project-updated.json, preserving metadata and existing links
notes load -d project ~/tmp/project-updated.json
# MCP: use put for a structural rewrite, or batch/patch for a small targeted additionDo not:
• Upload a parent with links to children that do not exist yet.
• Upload a parent with placeholder sections like "TODO: add content".
• Upload a parent, then realise you need children, then update again as part of the same planned structure.
While JSONHTL permits links to non-existent documents, uploading a parent with hanging links creates confusion:
• Readers see broken links and think content is missing.
• It is harder to track what is complete vs incomplete.
• It creates an intermediate incomplete state.
When modifying an existing note:
1. Read the current version.
2. Preserve all existing links to children.
3. Preserve metadata: title, version, created, tags, and any domain-specific fields.
4. Increment version and set updated to today's date.
5. Use the safest write path for the edit size: targeted MCP patch/batch for simple block changes; whole-document put/load for structural rewrites.
6. Read back the note and verify the changed section, metadata, and links.
Creating linked notes:
1. Create all children with complete content.
2. Read parent.
3. Update parent to link children.
4. Verify links resolve.
Updating existing note:
1. Read current version.
2. Preserve metadata and links.
3. Increment version, add updated date.
4. Write through the safest path for the edit.
5. Read back and verify.
See also: Avoiding Orphaned Notes and MCP Note Editing Guide.
Always use ~/tmp/ (i.e. $HOME/tmp/) for scratch files, not /tmp/. This avoids permission issues on multi-user systems and keeps scratch files in a predictable personal location. Create the directory if needed: mkdir -p ~/tmp.