AGENTS.md

@@ -55,8 +55,9 @@ Round-trip equality is a property tested over a corpus, not a claim made in pros
   spells the mark; `!adf:link[text]{attrs}` where it does not — an attribute CommonMark cannot
   hold, an `href` or `title` no canonical escape spells, a paragraph opening whose CommonMark
   spelling would read as a link reference definition — and a directive link CommonMark could spell
-  is refused (the maintainer, 2026-09-13). No link wraps a link, which is CommonMark's prose where
+  is refused (the maintainer, 2026-09-13). No link wraps a link — the bracket form goes literal,
-  its reference implementation nests one `<a>` in another (the maintainer, 2026-09-17).
+  the directive form refused — which is CommonMark's prose where its reference implementation
+  nests one `<a>` in another (the maintainer, 2026-09-17).
 - Identity-bearing nodes carry their ids in attributes; a document is only portable within its
   site — accepted.
 - The HTML dialect mirrors this: semantic elements, stable `adf-*` classes, `data-*` for what HTML

MIGRATION.md

@@ -49,11 +49,11 @@ holding an unescaped `!adf:` and a `carry` fence are claimed instead.
 
 ### Readings
 
-Markdown the spelling table leaves alone, reading to a different document.
+Markdown the spelling table leaves alone, which `0.2.0` reads as a different document.
 
 | Input | `0.1.0` | `0.2.0` |
 | --- | --- | --- |
-| a link whose text already holds one (`[a<https://example.com/>b](/v)`) | marks every node the inner link does not, splitting the outer link around it | leaves the outer brackets literal text |
+| a link whose text already holds one (`[a<https://example.com/>b](/v)`) | marks every node the inner link does not, splitting the outer link around it | leaves the outer brackets literal text; write the pieces as separate links to keep them |
 
 ### Error codes
 

README.md

@@ -111,17 +111,17 @@ emit refuses:
 - Plain CommonMark is valid input to `markdownToAdf` apart from the raw HTML below, with three
   carve-outs — literal text matching directive, pipe-table or strikethrough syntax is claimed
   (escapable — `spec/flavour.md`) — and one gap: a CommonMark image fits only as its own
-  title-less paragraph; mid-text and titled images are error results. Converting back yields the
+  title-less paragraph; mid-text and titled images are error results, save an image inside
+  another's description, which flattens into the alt text. Converting back yields the
   library's canonical spelling, which round-trips byte-identically — where it converts back at
   all: a parse succeeding is no promise of that, so keep the source until the way back succeeds.
   ``` ` `` ` ``` reads cleanly and then refuses.
-- Four CommonMark spellings parse without an error and build a document the reference renders
+- Four CommonMark spellings parse without an error and build a document the reference
-  differently: `[](/url)` and `[]()` stay literal text against CommonMark's empty link, a list
+  implementation renders differently: `[](/url)` and `[]()` stay literal text against CommonMark's
-  continuing past a marker change stays one list against CommonMark's two, a shortcut
+  empty link, a list continuing past a marker change stays one list against CommonMark's two, a
-  reference matching its definition only under Unicode case folding stays unresolved, and a link
+  shortcut reference matching its definition only under Unicode case folding stays unresolved, and
-  whose text holds an autolink keeps the inner link and leaves the outer brackets literal text,
+  a link whose text holds an autolink keeps the inner link and leaves the outer brackets literal
-  which the spec requires and the reference implementation itself breaks, nesting one `<a>` in the
+  text, which the spec requires and the reference itself breaks, nesting one `<a>` in the other. The first three are pinned `pending` in `corpus/commonmark-spec/exceptions.json`; the
-  other. The first three are pinned `pending` in `corpus/commonmark-spec/exceptions.json`; the
   suite holds no example of the fourth.
 - Raw HTML in markdown input is an error result, never a silent drop — a tag, a comment and a
   processing instruction alike. ADF holds no raw-HTML node; the element mapping ships at `0.2.0`.