From 7684643e6b60c280629d9c5e2585ad0fce456c9c Mon Sep 17 00:00:00 2001
From: Lilleman auf Larv <lilleman@larvit.se>
Date: Mon, 9 Nov 2026 09:43:14 +0100
Subject: [PATCH] =?UTF-8?q?Answer=20prose=20round=201:=200=20=F0=9F=94=B4,?=
 =?UTF-8?q?=2013=20=F0=9F=9F=A1=20(0=20misread);=20state=20the=20overlap?=
 =?UTF-8?q?=20and=20the=20table=20question=20plainly,=20and=20fix=20the=20?=
 =?UTF-8?q?report's=20citations?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/kovetskiy-mark.md | 93 +++++++++++++++++++++---------------------
 todo.md                |  9 ++--
 2 files changed, 52 insertions(+), 50 deletions(-)

diff --git a/docs/kovetskiy-mark.md b/docs/kovetskiy-mark.md
index 00d42d4..2027d9c 100644
--- a/docs/kovetskiy-mark.md
+++ b/docs/kovetskiy-mark.md
@@ -1,11 +1,11 @@
 # `kovetskiy/mark` compared with this package
 
-Read and run on 2026-11-09 at `mark` v17.0.0 (`eacff19`): its README, the nine pages under its
-`docs/`, `AGENTS.md`, `go.mod`, the issue search and the storage-format calls in its source. Run: the
-program, built in a `golang:1.27.3` container, with `publish --compile-only` and no network, on 14
-fixtures from `corpus/round-trip/` and on one file of its own syntax. Only read: everything that
-needs a Confluence account (publishing, page lookup, link resolution, attachments, labels, `mark
-export`).
+On 2026-11-09, at `mark` v17.0.0 (`eacff19`), read: its README, the nine pages under its `docs/`,
+`AGENTS.md`, `go.mod`, its issue tracker's search and the storage-format calls in its source. Run:
+the program, built in a `golang:1.27.3` container, with `publish --compile-only` and no network, on
+14 fixtures from `corpus/round-trip/` and on one file of its own syntax. Not run, only read: all
+that needs a Confluence account (publishing, page lookup, link resolution, attachments, labels,
+`mark export`).
 
 ## What it is
 
@@ -16,70 +16,71 @@ back as markdown.
 ## Which format
 
 Not ADF. It parses markdown with goldmark and writes Confluence **storage format**, an XML dialect
-(`ac:structured-macro`, `ac:task-list`, `<time datetime>`); the source holds no `atlas_doc_format`
-and sends every body as `"representation": "storage"`. Confluence's editor turns that into ADF
-itself, so mark never sees ADF.
+(`ac:structured-macro`, `ac:task-list`, `<time datetime>`). The source holds no `atlas_doc_format`
+and sends every body as `"representation": "storage"`, so `mark` never sees ADF.
 
-It reads a page back only through `mark export`, from storage format, and writes storage format it
-has no markdown for into the markdown as it is, much as the lossless flavour's carry holds a node
-(`docs/export.md` §What stays storage format). Its list of what does not come back the same is
-the same kind as ours.
+It reads a page back only through `mark export`, from storage format. Storage format it has no
+markdown for stays in the exported markdown as it is, much as the lossless flavour's carry holds a
+node (`docs/export.md` in `mark`'s repo, §What stays storage format). Its list of what does not
+come back the same from a publish after an export is like our list of exceptions under the README's
+[The guarantees](../README.md#the-guarantees).
 
 ## How its spellings differ from ours
 
 Each row ran through `mark` and through `commonMarkToAdf`, `losslessMarkdownToAdf` and
-`portableMarkdownToAdf` of v0.3.1.
+`portableMarkdownToAdf` of `@larvit/adf-codec` v0.3.1.
 
 | Confluence feature | `mark` spells | This package | Difference |
 | --- | --- | --- | --- |
-| Info, tip, note and warning boxes | `> [!NOTE]`, `> Note:`, `!!! note` | `portableMarkdownToAdf` reads `> [!NOTE]` as a `panel`; the lossless flavour spells `!adf:panel warning` | `[!IMPORTANT]`: blue info box in `mark`, `note` panel (purple, as on GitHub) here. `NOTE`, `TIP`, `WARNING` and `CAUTION` give the same box in both (`mark`'s note and warning boxes are ADF's `warning` and `error`). A colon marker and `!!! note` stay a quote and a paragraph here |
+| Info, tip, note and warning boxes | `> [!NOTE]`, `> Note:`, `!!! note` | `portableMarkdownToAdf` reads `> [!NOTE]` as a `panel`; the lossless flavour spells `!adf:panel warning` | `[!IMPORTANT]`: blue info box in `mark`, `note` panel (purple, as on GitHub) here. `NOTE`, `TIP`, `WARNING` and `CAUTION` give the same box in both: Confluence's note and warning macros are ADF's `warning` and `error` panels. A quote opening `Note:` (a colon marker) and `!!! note` stay a quote and a paragraph here |
 | Expand | `<details><summary>` | `!adf:expand {title="…"}` | `htmlToAdf` and the markdown readers refuse `<details>` as `unmappable-html` until items 137 and 138 |
-| Task list | `- [x]` | `- [x]` in the portable flavour; `!adf:taskList` in the lossless one | the same spelling; `commonMarkToAdf` reads a bullet list, as CommonMark has no task |
+| Task list | `- [x]` | `- [x]` in the portable flavour; `!adf:taskList` in the lossless one | the same spelling; `commonMarkToAdf` reads a bullet list, as CommonMark has no task list |
 | Date | `@date(2026-07-27)`, `<time datetime>` (behind `--features date`) | `!adf:date{timestamp=…}`; `<time class="adf-date">` in HTML | `<time datetime>` is refused as `unmappable-html`; `@date()` is text here (`docs/decisions.md` §Names stay text) |
-| Emoji | `:tada:` (behind `--features emoji`) | `!adf:emoji[🎉]{…}` | text here, same entry |
+| Emoji | `:tada:` (behind `--features emoji`) | `!adf:emoji[🎉]{…}` | `:tada:` is text here, same entry |
 | Link to a page | `[text](ac:Title)`, `./other.md` | a link with that destination | `mark` resolves it with Confluence; here it is a plain link |
-| Status, Jira ticket, table of contents | a macro template: `<!-- Macro: … -->`, `ac:status`, `ac:jira:ticket` | `!adf:status[…]{color=…}`, `!adf:inlineCard{url=…}` | its templates are Go text templates writing storage format; ours are node directives |
+| Status, Jira ticket | a macro template: `<!-- Macro: … -->`, `ac:status`, `ac:jira:ticket` | `!adf:status[…]{color=…}`, `!adf:inlineCard{url=…}` | its templates are Go text templates writing storage format; ours are node directives |
 | Mentions, panels with custom colours, media | storage format written by hand, or a template | `!adf:mention`, `!adf:panel custom`, `!adf:mediaSingle` | none in `mark`'s markdown |
 
-What `mark` spells and ADF has no node for, so nothing here corresponds: page metadata in header
+What `mark` spells and ADF holds no node for, so nothing here corresponds: page metadata in header
 comments or YAML front matter (`Space`, `Parent`, `Title`, `Label`, `Attachment`, `Layout`,
-restrictions, content properties), `<!-- Include: -->` and `<!-- Macro: -->`, attachments,
-footnotes, definition lists, math, and Mermaid, D2 and PlantUML diagrams drawn into images.
+restrictions, content properties), `<!-- Include: -->`, `<!-- Macro: -->` as a mechanism, the table
+of contents macro, attachments, footnotes, definition lists, math, and Mermaid, D2 and PlantUML
+diagrams drawn into images.
 
 Our directives written to `mark` come out as text: every `!adf:` line of the 14 fixtures is
 published as a paragraph holding it. `commonMarkToAdf` refuses a `mark` document that opens with
-`<!-- Space: DOCS -->`, as `unmappable-html`, because a comment is content ADF cannot hold
-(`docs/decisions.md` §Foreign HTML sorts three ways); so does `<!-- Include: -->`. Neither is a
-defect against that entry.
+`<!-- Space: DOCS -->` as `unmappable-html`, and refuses `<!-- Include: -->` the same way, because
+a comment is content ADF cannot hold (`docs/decisions.md` §Foreign HTML sorts three ways). Both
+refusals follow that entry.
 
-## Which the audience would expect
+## What the audience would expect
 
-`mark`'s spellings are the ones the README's people already write: GitHub alerts, `<details>`,
-`- [x]`. Ours agree for alerts and tasks in the portable flavour, and will for `<details>` once
-items 137 and 138 land. The lossless flavour's `!adf:` directives are for what no
-markdown spells, and `mark` spells none of those, so they never compete. The one divergence
-that reads either way is `[!IMPORTANT]`; the README states ours (`README.md` § Portable markdown).
+`mark`'s spellings for boxes, expands and tasks are ones the README's people already write: GitHub
+alerts, `<details>`, `- [x]`. Ours agree for alerts and tasks in the portable flavour, and will for
+`<details>` once items 137 and 138 land. For mentions, custom panels and media `mark` spells
+nothing, so the lossless flavour's directives meet no spelling of its. For a date, an emoji, a
+status and a card `mark` does spell something (`@date()`, `:tada:`, a macro template), and which
+spelling the audience would expect there is for a writer panel, not this report. The one divergence
+in a shared spelling is `[!IMPORTANT]`, which `README.md` §Portable markdown states for ours.
 
 ## Overlap
 
-Product managers, engineers and support agents who write markdown for Confluence are the README's
-second audience. `mark` serves them as a publishing pipeline for a repository of documents; this
-package serves the four developer personas who embed a converter. The bot persona (generated
-markdown to ADF) is the one overlap: both turn markdown into Confluence content, but `mark` needs
-an account and the REST API, this package takes none (Goal 8). A user of `mark` who needs ADF can
-publish with `mark` and fetch the page as ADF through the Confluence REST API, which converts
-storage format to ADF; a user of this package who needs storage format has to go to that same API
-(`README.md` § Other ADF converters).
+The people who write markdown for Confluence are the README's second audience. `mark` serves them
+with a publishing pipeline for a repository of documents; this package serves the four developer
+personas who embed a converter. Of those, the bot persona (generated markdown to ADF) is closest:
+both tools turn markdown into Confluence content. `mark` needs an account and the REST API; this
+package needs neither (Goal 8).
+
+A user of `mark` who needs ADF can fetch the page as ADF through the Confluence REST API, which
+converts storage format to ADF. A user of this package who needs storage format goes to that same
+API (`README.md` §Other ADF converters).
 
 ## Does it belong in the comparison table
 
 Neither table fits. The first lists npm packages that run in Node and convert ADF to or from
-markdown; the second lists converters this comparison does not run, and every row of it converts
-ADF. `mark` is a Go program that never touches ADF. Filed as item 177, a question to the maintainer, with the
-options: leave it out, or add a row to the second table saying it converts markdown to storage
-format and not ADF.
+markdown. The second lists converters the comparison does not run, and every library in it converts
+ADF. `mark` is a Go program that never touches ADF. Item 177 asks the maintainer: leave it out, or
+add a row to the second table saying it converts markdown to storage format and not ADF.
 
-## Filed
-
-Only item 177. The differences do not ask for a change to a spelling: `[!IMPORTANT]` is
-an entry's choice to reopen, not a defect, and only a writer panel changes one (`AGENTS.md` §7).
+No spelling changes follow: `[!IMPORTANT]` is the README's choice to reopen, not a defect, and only
+a writer panel changes a spelling (`AGENTS.md` §7).
diff --git a/todo.md b/todo.md
index 1fb07c8..500ebe3 100644
--- a/todo.md
+++ b/todo.md
@@ -65,11 +65,12 @@ files, with its `ci.sh` probe, extends the decision.
 
 ### 177. Decide whether `kovetskiy/mark`, a Go program that writes Confluence storage format and never touches ADF, gets a row in the README's second "Other ADF converters" table, and record the answer in §The comparison table lists every converter that starts and converts.
 
-The gap: §The comparison table lists every converter that starts and converts covers converters of
+The gap: the decision entry "The comparison table lists every converter that starts and converts"
+settles which npm packages and which other-ecosystem libraries are listed, and all of them convert
 ADF. The first table lists npm packages that run in Node and convert ADF to or from markdown; the
-second lists converters the comparison does not run, and every row of it converts ADF. `mark`
-converts markdown to storage format only (`docs/kovetskiy-mark.md` § Does it belong in the
-comparison table). The options: leave it out, or add a row saying it converts markdown to storage
+second lists converters the comparison does not run, and every library in it converts ADF. `mark`
+converts markdown to storage format only (`docs/kovetskiy-mark.md`, "Does it belong in the
+comparison table"). The options: leave it out, or add a row saying it converts markdown to storage
 format and not ADF.
 
 Candidate sentence for the entry: "A converter that never reads or writes ADF, such as one writing