diff --git a/README.md b/README.md
index a3f635d..03fd021 100644
--- a/README.md
+++ b/README.md
@@ -189,8 +189,7 @@ Question            id (derived from the file's path - see routing
                     record_as (bucket), self_transition {bucket, to, label},
                     features[]
     Feature         name, description, color (CSS accent), icon
-                    (Iconify name, e.g. lucide:star), link (https URL
-                    the card's name points to), requirements[],
+                    (Iconify name, e.g. lucide:star), requirements[],
                     resource
       Requirement   name, label, type, optional, multiple, placeholder,
                     accept (file), resource + id_field (select options),
@@ -238,6 +237,12 @@ review resource's transitions — fireable by whoever holds one specific
 record's `?chain=` link plus its matching email (the unsubscribe
 pattern).
 
+**Descriptions are inline markdown** (alternative and feature):
+`[text](https://…)` links, `*emphasis*`, `**strong**`, `` `code` ``.
+One paragraph - block structure flattens; raw HTML is dropped; link
+targets may be https, mailto or a site-relative path, anything else
+renders as plain text.
+
 **Announced pages.** A question carrying an `event:` block
 
 ```yaml