README.md

@@ -39,12 +39,10 @@ In priority order.
 4. **Output a person can edit.** A node CommonMark can spell gets that spelling; the lossless
    flavour's directive form carries only what CommonMark cannot hold.
 5. **Lossy conversion keeps the content.** `adfToPlainMarkdown` and `plainMarkdownToAdf` drop what
-   plain markdown cannot hold — format, design, structure — never content: what a reader of the
-   rendered document sees or follows, its text, images and link targets. Content the document only
-   references is marked where it stood, by a note that reads as the converter's and names what was
-   left out. The lossy pair creates and exports; it never saves back over the document it read —
-   a document's identity (task, mention, media ids) survives a round trip only through the lossless
-   pair.
+   plain markdown cannot hold — format, design, structure — never content the document holds: what
+   a reader of the rendered document sees or follows, its text, images and link targets. The lossy
+   pair creates and exports; it never saves back over the document it read — a document's identity
+   (task, mention, media ids) survives a round trip only through the lossless pair.
 6. **What happens is what the audience expects.** Where the goals leave a choice, a conversion
    takes the one its audience would predict, reading the input as written.
 7. **Failures are values.** Nothing throws, and `code` is a closed list — as much a contract as
@@ -139,15 +137,17 @@ read replaces mentions, attachments and macros with text.
 | `table` | a pipe table: the first row its header, a cell's blocks on one line, a span kept under its header by empty cells | — |
 | `decisionList` | a bullet list | — |
 | `mention`, `status`, `emoji`, `date` | their text: `@` kept, a mention with none `@` and its id, an emoji its `shortName` without, a date `2026-09-13` in UTC | — |
-| `inlineCard`, `blockCard`, `embedCard` | a link to the card's URL | — |
+| `inlineCard`, `blockCard`, `embedCard` | a link to the card's URL, else its name | — |
 | external `media` | `![alt](url)` in a block, `[alt](url)` inline | — |
 | stored `media`, `mediaInline`, `extension`, `inlineExtension` | their `alt` or `text` | — |
 | `layoutSection`, `bodiedExtension`, `bodiedSyncBlock`, `multiBodiedExtension`, `extensionFrame`, `caption`, a node this version does not know | its blocks or its text | — |
 | `placeholder` | nothing | — |
 
-- Content the document only references leaves an italic note naming it where it stood:
-  `_(image not included)_`, `_(jira-issues-table not included)_`, `_(synced block not included)_`,
-  `_(link card not included)_`, `_(extension not included)_`.
+- Content the document only references, with no text of its own to keep, leaves an italic note
+  naming it where it stood: `_(image not included)_` for stored media with no `alt`,
+  `_(link card not included)_` for a card with neither URL nor name, an extension with no `text`
+  its key, `_(jira-issues-table not included)_`, or `_(extension not included)_` without one, and
+  `_(synced block not included)_` for a `syncBlock`.
 - `backgroundColor`, `code`, `em`, `link`, `strike` and `strong` stay; every other mark drops,
   keeping its text, and so does a mark the flavour cannot spell where it stands.
 - A newline in text is a hard break and in an expand's title a space, edge whitespace outside a

docs/decisions.md

@@ -156,8 +156,9 @@ MkDocs, Docusaurus, Typora, Joplin, Logseq, Bear, Notion, Azure DevOps and Disco
 renderer confirming each shape. Reader panels settled `error` as an error panel, the `==` bounds
 (3 of 3) and a Han, Hangul, kana, Thai, Lao, Khmer or Myanmar character on either side bounding a
 delimiter, so `は==日本語==で` (3 of 3), `==한국어==에서만` and `iPhone==専用==` (6 of 7) highlight,
-the external image's two forms (6 of 7), the omission notes and a rule opening a list item
-dropping (3 of 3), and a list's numbering overflowing into bullets (3 of 3, 5 of 7).
+the external image's two forms (6 of 7), a rule opening a list item dropping and the omission
+notes (3 of 3), and a list's numbering overflowing into bullets (3 of 3, 5 of 7).
+An omission note reads as the converter's, never as the author's.
 Reading takes other tools' spellings, since it reads their output and writes none of them.
 Rejected: `~sub~` and `^sup^` (`~2~` is a strike on GitHub, so `subsup` drops), underline and colour
 spellings, raw HTML (`<details>`, `<mark>`), MkDocs `!!!` and the `:::` admonition family,