Assessment from 2026-05-28: JSONHTL is broadly well documented for its current size and purpose. The core model is clear, minimal, and LLM-friendly. The main documentation risk is undocumented extensions that have grown around the base format.
• JSONHTL_SPEC clearly defines document objects, content, block elements, inline elements, links, and unknown-key tolerance.
• README separates base format from local notes-system conventions.
• README/metadata, README/workflow, README/orphaning, and README/mcp-tools cover the operational rules that matter in practice.
• The principle of convention documents over spec changes is sound: JSONHTL stays small while this notes system can grow around it.
• The base spec defines codeblock.lang and codeblock.body. Older notes have used aliases such as language and text. A linter should catch or normalize these system-wide.
• A list block appears in existing notes, but JSONHTL_SPEC does not define a standard list block. Either document it as an extension or convert notes to paragraph-based bullets.
• Tables are used and supported by MCP table_op, but table block syntax is not documented in the base spec or a linked extension note.
• Runnable document fields are documented separately, but there is no single registry of JSONHTL extensions used by this store.
• Error handling and renderer behaviour for malformed or unknown blocks are not specified beyond the general unknown-key tolerance rule.
• Create a JSONHTL extension registry note, e.g. README/jsonhtl-extensions or JSONHTL_EXTENSIONS.
• Document supported extension blocks and fields: list, table, runnable codeblock fields, and any renderer-tolerated aliases.
• Add linter checks for canonical codeblock fields, missing metadata, unsupported blocks, malformed inline elements, orphaned links, and table shape errors.
• Add examples of canonical and tolerated shorthand forms so implementers can normalize consistently.