This document describes the conventions used in this notes system. It supplements the base JSONHTL format specification. If you are an LLM or tool, check the version number above — if you already know version 7, you do not need to re-read this document.
All documents use JSONHTL. The base format defines three block types (para, heading, codeblock) and three inline types (plain strings, link, code). String values may also contain markdown inline formatting. See Format Details for the full rules.
Links connect documents in this store. A link may have an href that does not yet point to an existing node — this is permitted. See Link Conventions for resolution rules.
IMPORTANT: Always add links when creating child notes. See Avoiding Orphaned Notes and Information Loss for critical best practices.
Essential workflow guidance: See Workflow - Creating and Updating Notes for the correct order of operations when creating linked notes. DO NOT upload partial or incomplete documents.
Keys are plain strings. We use / as a logical separator to organise related documents, e.g. README/format. The server does not treat / specially — this is a convention only. See Key Conventions for details.
Documents should be brief. Prefer many small, focused nodes over fewer large ones. This supports fine-grained recall — an LLM or tool can load only the specific information it needs without consuming unnecessary context window.
The base JSONHTL spec allows any top-level keys. Convention documents define what additional keys mean. See Metadata Conventions for keys like version, created, and tags.
Runnable documents are supported. They are ordinary JSONHTL documents marked with "runnable": true at the top level, with executable code cells marked with "exec": true in codeblocks. See Runnable Document Conventions for guidelines on creating them.
Tooling documentation starts at README/tools. Command-line usage is in README/command-line-tools; MCP usage for agents is in README/mcp-tools.
- Use notes list or keys to discover and audit all notes in the system
- Always link child notes from their parent pages
- Preserve existing links when editing pages
- Back up before deleting notes
- Use notes load -d for CLI file loads, or MCP patch/batch with block IDs for agent edits
- Don't assume. Don't hide confusion. Surface tradeoffs.
- Minimum code that solves the problem. Nothing speculative.
- Touch only what you must. Clean up only your own mess.
- Define success criteria. Loop until verified.
- Document manual steps explicitly — if an operation is not automated by code or a playbook, say so and write down what to do. Manual steps leave no code as a record and are the most important to document.
- Plan the structure before writing — see the megadoc trap in Workflow.
- Fix incoming link text when renaming — the system has no backlink index; see Avoiding Orphaned Notes.
See Avoiding Orphaned Notes and Information Loss for critical guidance on maintaining system integrity.
Keep adding to notes as new facts are learned during work sessions; append incremental findings and outcomes as they happen, not only at the end.
See Lessons Learned for operational lessons from past sessions — read this when starting infrastructure or playbook work.