diff --git a/AGENTS.md b/AGENTS.md
index 695972e..caf0023 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -57,6 +57,11 @@ CSS file (Gruvbox, light + dark, theme toggle without reload).
   `max-height:256px`, lazy-loaded. The generator auto-sets `shareHiddenFromTree` on matching
   thumb child notes so they never appear in the blog menu. **There is no server-side resizing** –
   see "Limitations".
+- **Inline images in article content**: pasted image attachments render as
+  `<img src="api/attachments/<attachmentId>/image/<filename>">`. The share only serves
+  attachments through that `/image/` path segment – without it the request 404s. Use image
+  **attachments** for inline images (no child note, no menu clutter) and keep the `thumb.<ext>`
+  child note as the only image child.
 - Regenerates `feed.xml`, `sitemap.xml`, `state_map` (garden states) and `blog_data`
   (search index: id/title/url/summary/tags/category). Sets `shareDescription` from `summary`.
 
diff --git a/README.md b/README.md
index 51cfcc8..a88f31f 100644
--- a/README.md
+++ b/README.md
@@ -31,8 +31,9 @@ no external dependencies (except `highlight.js`, vendored in `lib/`).
   (post cards, garden table, menu) include the weekday (`dateText` from the generator).
 - **Article thumbnails**: each post card shows the first image of the article on the left
   (bounded by the teaser height), summary on the right, lazy-loaded. If an article has a child
-  note named `*_thumb.*` (e.g. `ngc281_thumb.jpg`), that image is used instead – ideal for
-  serving small pre-made thumbnails.
+  note named `thumb.<ext>` **or** `*_thumb.<ext>` (e.g. `thumb.png`, `ngc281_thumb.jpg`), that
+  image is used instead – ideal for serving small pre-made thumbnails. Thumb child notes are
+  auto-hidden from the blog menu (`shareHiddenFromTree`).
 - **Pagination**: 10 posts per page on the index and category pages, with prev/next
   navigation between the pages; article prev/next links stay within the article's category.
 - Article metadata: date, category, summary, tags, prev/next navigation, reading time.