diff --git a/AGENTS.md b/AGENTS.md
index 45d16a1fe..45eb3d96e 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -18,8 +18,8 @@ bytes ─▶ magic / open_strategy ─▶ DecodedFile ─▶ Document ─▶ Ele
 ```
 
 1. Detect. `internal/magic.cpp` sniffs the head of the file.
-   `internal/open_strategy.cpp` picks a `FileType` and a `DecoderEngine` and
-   builds the `abstract::DecodedFile`. Only bytes can claim a file. A name adds
+   `internal/open_strategy.cpp` picks a `FileType` and constructs the
+   `abstract::DecodedFile`. Only bytes can claim a file. A name adds
    a candidate that the bytes allow. That is the only way in for a format with
    no signature (markdown).
 2. Decode. A document file yields an `abstract::Document`.
diff --git a/README.md b/README.md
index 870ba6768..d7bf00657 100644
--- a/README.md
+++ b/README.md
@@ -16,14 +16,14 @@ and [OpenDocument.ios](https://github.com/opendocument-app/OpenDocument.ios).
 | pdf | yes | no | Own parser. Encrypted files are decrypted. Supports annotation. |
 | pages, key, numbers | yes | no | Apple iWork. Text and tables. No styles, images, masters, presenter notes, number formats or merged cells. |
 | rtf | yes | no | Body text only. |
-| md | yes | no | CommonMark plus GitHub extensions. No raw html, images or horizontal rules. Detected by name only, so open it as `FileType::markdown`. |
+| md | yes | no | CommonMark plus GitHub extensions. No raw html, images or horizontal rules. A `.md` or `.markdown` name selects it for text input; unnamed bytes need `FileType::markdown`. |
 | txt | yes | yes | |
 | csv | yes | yes | Cell values only. Saves as UTF-8. |
 | json, xml | yes | no | |
 | zip, cfb | yes | no | Archive listing. |
 | png, gif, jpeg, bmp, webp, tiff, heif, avif, jxl, ico, svg, svm | yes | no | Images. |
 | ttf, otf | yes | no | Font specimen page. |
-| mp3, m4a, ogg, wav, flac, mp4, mov, 3gp, mkv, avi | passthrough | no | The bytes go to the browser as they are, in an html media page. Not detected by content. |
+| mp3, m4a, ogg, wav, flac, mp4, mov, 3gp, mkv, avi | passthrough | no | Detected by content; the browser plays the original bytes in an html media page. |
 
 Detected but not decoded: wpd, xlsb and html. A caller can name them, but
 opening one throws. Saving with a password is not supported for any format.