Answer product-owner round 1: the docs say how to keep an image an image, and the empty link takes its own changelog entry

CHANGELOG.md

@@ -61,8 +61,9 @@
   but alone in a plain paragraph reads as its alt text linked to its URL, or inside a link as plain
   text the link marks. A titled one alone in a plain paragraph reads as the image captioned with
   its title, and a link alone in a plain paragraph whose whole text is an image as the image the
-  link marks. An empty link text reads as its destination, `[](/url)` as `/url` linked, and
-  `[]()` as nothing, where both stayed literal text. See `MIGRATION.md`.
+  link marks. To keep an image an image, give it a paragraph of its own. See `MIGRATION.md`.
+- **Breaking:** an empty link text reads as its destination, `[](/url)` as `/url` linked, and
+  `[]()` as nothing, where both spellings stayed literal text. See `MIGRATION.md`.
 - Fix a JSON key holding an escape, in a carried node or a JSON attribute such as `parameters`:
   `losslessMarkdownToAdf` reads it as the key it spells, where on V8 13.6 and later (Node 24, Deno,
   Chrome) `markdownToAdf` could refuse markdown `adfToMarkdown` wrote, as `unsupported-node-shape`,

MIGRATION.md

@@ -79,7 +79,7 @@ four now reads, or refuses with the code the table gives.
 
 | Input | `0.1.0` | `0.2.0` |
 | --- | --- | --- |
-| an image anywhere but alone in a plain paragraph (`See ![a](u).`, `# ![a](u)`), on parse | `unmappable-image` | its alt text linked to its URL, or, inside a link, plain text the link marks |
+| an image anywhere but alone in a plain paragraph (`See ![a](u).`, `# ![a](u)`), on parse | `unmappable-image` | its alt text linked to its URL, or, inside a link, plain text the link marks; give the image a paragraph of its own, a blank line before and after, to keep it an image |
 | a titled image alone in its paragraph (`![a](u "t")`), on parse | `unmappable-image` | the image, captioned with its title |
 | an image that is a link's whole text, alone in its paragraph (`[![a](u)](/v)`), on parse | `unmappable-image` | the image, its `media` marked with the link |
 | a link whose `href` or `title` no CommonMark escape spells, on emit | `unspellable-link` | spells `!adf:link[text]{attrs}` |

README.md

@@ -246,9 +246,11 @@ Serves Goals 1, 4 and 5.
   - An image anywhere but alone in a plain paragraph reads as its alt text linked to its URL,
     `See ![the moon](moon.png).` as `See [the moon](moon.png).`, and inside a link as plain text
     the link marks — unless the link's whole text is the image and the link stands alone in a
-    plain paragraph, which reads as the image the link marks.
-  - An image's title reads as its caption where the image reads as an image, as its link's title
-    where it reads as alt text linked to its URL, and inside a link otherwise it drops.
+    plain paragraph, which reads as the image the link marks. To keep an image an image, give it
+    a paragraph of its own, a blank line before and after, in a list item or a quote too: images
+    on consecutive lines share a paragraph.
+  - An image's title becomes its caption when the image stays an image, and its link's title when
+    it becomes linked alt text. Inside another link, the title is dropped.
 
   And three more: a list continuing past a marker change stays one list against CommonMark's two,
   a shortcut reference matching its definition only under Unicode case folding stays unresolved,