This document explains critical practices for maintaining the integrity of the notes system and preventing information loss.
An orphaned note is one that exists in the system but has no links pointing to it from any other page. It is effectively hidden and undiscoverable unless you know its exact key and use notes read <key> directly.
Example: A note created at key envoy/design-spec with valuable architectural information, but no link from the envoy parent page, remains undiscovered even though it contains important documentation.
1. Create a child note but forget to link it: You create project/design but forget to add a link from the project page.
2. Delete a link without reviewing content: You remove a link from the parent page thinking the document is no longer needed, but valuable information was in that child note.
3. Update a parent page and accidentally omit child links: You edit the envoy page but don't preserve links to envoy/design-spec and envoy/design-supplement.
4. Overwrite metadata accidentally: You reset the version number, lose the created date, or remove tags when updating content.
5. Strip important structural information: You remove the title or lose descriptive metadata that provides context.
6. Update a note's title without fixing incoming link text: You rename a note but parent notes still show the old title as link text. The link still resolves, so nothing breaks visibly — but readers are misled. The system has no backlink index; stale link text is invisible until someone reads the parent.
When editing any note, always preserve:
All links pointing to related documents, especially child pages. These maintain the discoverability and navigation structure of the system.
title — The human-readable document title.
version — Must be incremented, never reset or removed.
created — Original creation date (ISO format). Never change this.
updated — Set to current date when making changes.
tags — Classification tags. Review before removing.
Hierarchical relationships between parent and child documents. Check notes list or keys to see what child keys exist before editing a parent.
Any custom top-level keys specific to the document type (e.g. description, status, author). Review the existing structure before overwriting.
CONTENTS and any other master/index page are not manually maintained by John alone — every agent (Claude, Codex, etc.) is responsible for keeping them current. If you create, restructure, or rename a note that should appear in an index, update that index in the same session. This is the same discipline as linking from a direct parent, applied to system-wide indexes too.
As the corpus grows, agent-time upkeep alone won't catch everything. See Future (Search and Discovery) for the plan to add periodic Envoy-driven audits of orphaned notes and stale index entries once volume justifies it.
Discoverability: LLMs, tools, and humans rely on navigating from linked pages. Orphaned notes become lost knowledge.
Information Loss: Valuable architectural decisions, design discussions, and domain knowledge can disappear from active use, even if the data technically exists in the database.
Historical Context: Version numbers and timestamps provide chronology. Losing them makes it impossible to understand when decisions were made or how documents evolved.
System Integrity: The notes system depends on explicit links and consistent metadata. Broken relationships indicate gaps in the system structure.
1. Create the child note with complete content.
2. Immediately read the parent page.
3. Update the parent page to include a link to the child.
4. Verify the link resolves correctly.
Before you overwrite a page:
1. Read the current content.
2. Review for child links you might accidentally remove.
3. Check metadata: version, created, title, tags, etc.
4. Use notes list or keys to check if child notes exist (keys with your page as a prefix).
5. Preserve all existing links when you update.
6. Preserve all metadata fields unless you explicitly intend to change them.
7. Increment the version number.
8. Update the updated field to today's date.
The system has no backlink index. Changing a note's title does not automatically update link text in other notes. After renaming:
1. Identify parent notes that link to this key (check notes that logically contain it).
2. Read each parent and update any link text that now mismatches the new title.
3. Increment version and update the updated date on each parent you change.
Before removing a link:
1. Verify the target still has value.
2. Check if anyone depends on it.
3. If deleting, consider archiving instead of removing.
4. Document why the link was removed.
Use notes delete only after:
1. Verifying the note has no value for future reference.
2. Checking that no links point to it.
3. Confirming no child notes exist under it.
4. Optionally backing up the content first.
Use notes list / keys regularly to audit the system:
1. Run notes list or keys to see all keys.
2. For each relevant key, read the note and check its content.
3. Verify that parent-child relationships are properly linked.
4. Check that metadata is present and consistent.
5. If you find an orphaned note, either link it from a parent or delete it with confidence.
On 2026-02-09, two important design documents were created:
• envoy/design-spec (architectural specification)
• envoy/design-supplement (design decisions)
However, the main envoy page was not updated to include links to these notes. They remained orphaned and undiscoverable until explicitly searched for using notes list. This valuable architectural guidance was effectively hidden despite existing in the system.
Lesson: Always link new child notes immediately from their parent pages.
• Create + Link must happen together.
• Read before you write — always check existing content.
• Preserve all metadata: version, created, title, tags, etc.
• Never remove links without reviewing the target.
• Increment version numbers, never reset them.
• Never change the created date; update updated instead.
• Use notes list / keys to audit regularly.
• Document deletions if you must remove content.