Answer prose round 1: one sentence per idea for the image readings, a decision title that states the rule, item 86 names its shapes

src/conformance/commonmark-spec.test.ts

@@ -92,7 +92,7 @@ test('the refusal list is unique per example and names real examples', () => {
   for (const example of exampleToRefusal.keys()) assert.ok(spec.some((entry) => entry.example === example), `refusal ${example} names no example in the suite`)
 })
 
-// A mark is counted once per node it touches (docs/decisions.md §No schema validation).
+// A mark counts once per node carrying it: ADF marks each node where HTML nests one element (docs/decisions.md §No schema validation).
 const countKeys = ['a', 'blockquote', 'br', 'code', 'em', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'hr', 'img', 'li', 'ol', 'pre', 'strong', 'ul']
 const nodeElement: Record<string, string> = {
   blockquote: 'blockquote',

src/markdown/external-image.ts

@@ -1,6 +1,6 @@
 import type { AdfNode } from '../adf/document.ts'
 
-// spec/flavour.md, The CommonMark image: `![alt](url)` reads to `centeredImage([externalMedia(alt, url)])`, the only shape written back as it.
+// spec/flavour.md, The CommonMark image: `![alt](url)` reads to `centeredImage([externalMedia(alt, url)])`, the only shape `adfToLosslessMarkdown` writes as `![alt](url)`.
 export function centeredImage(content: AdfNode[]): AdfNode {
   return { attrs: { layout: 'center' }, content, type: 'mediaSingle' }
 }

src/markdown/parse/inline-content.ts

@@ -22,7 +22,7 @@ import { readDirectiveMark } from './directive-marks.ts'
 import { readInlineDirectiveNode } from './directive-nodes.ts'
 import { readTextDirective } from '../text-directive.ts'
 
-// `image` is the `mediaSingle` a lone image builds, for the one container that holds it: a plain paragraph. `nodes` reads it as its linked alt text.
+// Only a `paragraph` block takes `image`, the `mediaSingle` a lone image builds; every other container takes `nodes`, where the image is its linked alt text.
 export type InlineContent = { image?: AdfNode; nodes: AdfNode[] }
 
 // The text break leaf: it holds no marks, and stands between the nodes it parts until the outermost content checks and drops it.

src/markdown/parse/markdown-to-adf.ts

@@ -318,7 +318,7 @@ function codeBlockNode(language: string, text: string, reading: Reading, path: C
   return success(text === '' ? node : { ...node, content: [{ text, type: 'text' }] })
 }
 
-// spec/flavour.md, The CommonMark image: only a plain paragraph gives a lone image the block it needs.
+// spec/flavour.md, The CommonMark image: only a `paragraph` block gives a lone image the block it needs.
 function paragraphNode(text: string, reading: Reading, path: ConvertErrorPath): Result<AdfNode> {
   const content = parseInlineContent(text, reading.definitions, path, 'paragraph', reading.claims)
   if (!content.ok) return content