docs: add README screenshots and documentation images

README.md

@@ -12,9 +12,49 @@ Better Shulkers focuses specifically on shulker boxes and aims to stay lightweig
 - **Custom labels** — shows the shulker box's custom name on the lid
 - **Fill bar** — a durability-style bar indicating how full the shulker box is
 
-<!-- TODO: add screenshots
+## Screenshots
-![Features overview](docs/features.png)
+
--->
+### Tooltip grid preview
+
+Hovering over a shulker box shows its contents in a grid. The preview can appear when the box has items or always, depending on configuration.
+
+![Tooltip grid preview](docs/Tooltip.png)
+
+![Tooltip grid preview (filled shulker)](docs/TooltipFull.png)
+
+### In inventories and containers
+
+Flat top-down lid view with item hints inside a chest. The fill bar and the optional shulker-like background behind hints can each be toggled in settings.
+
+**With fill bar**
+
+![Item hints in a chest](docs/InChestPreview.png)
+
+![Item hints without background](docs/InChestPreviewNoBackground.png)
+
+**Without fill bar** (inventory slot / container — hints only, with or without background)
+
+![Item hints without fill bar](docs/InChestPreviewNoFillBar.png)
+
+![Item hints without fill bar or background](docs/InChestPreviewNoFillBarNoBackground.png)
+
+### Placed in the world
+
+Item hints appear on placed shulker boxes; custom names appear on the lid when renaming the box with an anvil.
+
+![Shulker lids in the world](docs/ShulkersLidsInWorld.png)
+
+![Shulker lid with custom label](docs/ShulkersLidWithLabelInWorld.png)
+
+### Configuration (Mod Menu)
+
+Settings are grouped under **Better Shulkers** in Mod Menu when [Cloth Config](https://modrinth.com/mod/cloth-config) is installed.
+
+![Mod Menu entry](docs/ModMenuEntry.png)
+
+![Tooltip preview options](docs/ModMenuTooltipTab.png)
+
+![Item hints and related options](docs/ModMenuItemHintsTab.png)
 
 ## Installation