From c6781aa9b3da1bc330f888d95af83e42014fbdd9 Mon Sep 17 00:00:00 2001
From: Lilleman auf Larv <lilleman@larvit.se>
Date: Mon, 28 Sep 2026 00:04:38 +0200
Subject: [PATCH] 36 - review: CHANGELOG flags the breaking readings and codes,
 README links it

---
 CHANGELOG.md | 17 ++++++++++-------
 README.md    |  3 ++-
 2 files changed, 12 insertions(+), 8 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index d44f92b..d2c8039 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,21 +4,24 @@
 
 - **Breaking:** directives, the opaque carry among them (now `carry`), are spelled under an `!adf:`
   prefix (`!adf:name … !adf:/name`, `!adf:name[content]{attrs}`, `!adf:name arg {attrs}`) in place
-  of the `:::`/`::`/`:name` forms; convert stored markdown per `MIGRATION.md`.
+  of the `:::`/`::`/`:name` forms: text holding an unescaped `!adf:` is claimed, and `adf` is an
+  ordinary code block language. Convert stored markdown per `MIGRATION.md`.
 - **Breaking:** `unspellable-link` leaves `ConvertErrorCode`; a link whose `href` or `title` no
   CommonMark escape spells is written as `!adf:link[text]{attrs}`.
+- **Breaking:** some directive refusals carry `malformed-directive` where they carried
+  `unsupported-node-shape`, and an empty node's leaf and closed spellings swap which one parses;
+  `MIGRATION.md` lists each.
+- **Breaking:** a link whose text holds another link keeps the inner link and leaves the outer
+  brackets literal text, where `0.1.0` split the outer link around it; see `MIGRATION.md`.
 - Add `adfToPlainMarkdown` and `plainMarkdownToAdf`, a lossy pair converting ADF to and from
   markdown GitHub, GitLab and Obsidian render: alerts, callouts, task lists, `==highlights==` and
   pipe tables.
-- Spell `rule`'s `color`, `style` and `weight` and `layoutSection`'s `columnRuleStyle` directly
-  where they rode the opaque carry.
-- Fix a link whose text holds another link: the inner link is kept and the outer brackets stay
-  text, where the outer link was dropped.
+- Spell `rule`'s `color`, `style` and `weight`, `layoutSection`'s `columnRuleStyle` and a link's
+  `collection`, `id` and `occurrenceKey` directly where they rode the opaque carry.
 - Fix an image inside another image's description: it flattens into the alt text, where it was
   refused.
 
 ## 0.1.0
 
 - First release: lossless conversion between ADF and an extended markdown flavour —
-  `adfToMarkdown`, `markdownToAdf` and `isAdfDocument`. Plain CommonMark is valid input, nothing
-  throws, and every error carries a `code` from a closed list.
+  `adfToMarkdown`, `markdownToAdf` and `isAdfDocument`. Nothing throws, and every error carries a `code` from a closed list.
diff --git a/README.md b/README.md
index d0a4d8b..37aa3aa 100644
--- a/README.md
+++ b/README.md
@@ -5,7 +5,8 @@ an HTML dialect.
 
 **Status: published — the markdown round-trip (`adfToMarkdown`, `markdownToAdf`); HTML at
 `0.2.0`.**
-Plan: `todo.md`. Changes: `CHANGELOG.md`. Decisions: `AGENTS.md`. The lossless flavour's grammar:
+Plan: `todo.md`. Changes:
+[`CHANGELOG.md`](https://gitea.larvit.se/larvit/adf-codec/src/branch/main/CHANGELOG.md). Decisions: `AGENTS.md`. The lossless flavour's grammar:
 [`spec/flavour.md`](https://gitea.larvit.se/larvit/adf-codec/src/branch/main/spec/flavour.md).
 Upgrading from `0.1.0`: [convert your markdown first](https://gitea.larvit.se/larvit/adf-codec/src/branch/main/MIGRATION.md).