diff --git a/doc/1.21-notes.md b/doc/1.21-notes.md
new file mode 100644
index 0000000000..299987168f
--- /dev/null
+++ b/doc/1.21-notes.md
@@ -0,0 +1,80 @@
+### Mandatory porting tasks
+* Java 17 -> Java 21
+* switch item data from NBT to item components
+* codecs everywhere
+* Forge -> NeoForge checklist:
+  * toolchain, packages: https://neoforged.net/news/20.2release/
+  * events system: https://neoforged.net/news/20.2eventbus-changes/
+  * registries: https://neoforged.net/news/20.2registry-rework/
+  * mixins: https://neoforged.net/news/20.3release/
+  * capabilities: https://neoforged.net/news/20.3capability-rework/
+  * networking: https://neoforged.net/news/20.4networking-rework/
+  * major 1.20.5 changes (item components, Java 21, and more): https://neoforged.net/news/20.5release/
+  * 1.21: TODO
+* Fabric/vanilla update checklist:
+  * 1.20.2 (mostly networking): https://fabricmc.net/2023/09/12/1202.html
+  * 1.20.3/.4 (/tick support, block API changes, etc.): https://fabricmc.net/2023/11/30/1203.html
+  * 1.20.5/.6 (Java 21, item components, networking again): https://fabricmc.net/2024/04/19/1205.html
+  * 1.21 (enchantments, data pack paths, rendering): https://fabricmc.net/2024/05/31/121.html
+
+### Technical/internal changes
+* Add MixinExtras dependency to allow for less hacky feature/fix implementations, e.g.:
+  * zoom for Botania bows
+  * apothecary filling via dripstone
+* Use convention tags v2, since Fabric and NeoForge unified their tag systems
+  * ensure existing resources are tagged properly (e.g. manasteel ingots as `#c:ingots/manasteel`)
+  * remove platform-specific tags (except for mod compatibility where we know they stay on only one of the loaders)
+  * update recipes to preferably use item tags, where it makes sense
+  * update Vitreous Pickaxe to check for `#c:glass_blocks` and `#c:glass_panes`, ideally wrapped in a separate block tag
+    * maybe also set it as appropriate tool for glass blocks (in addition to the usual pickaxe blocks)
+    * maybe add other glass-like blocks without a vanilla tool to it (glowstone, sea lanterns, redstone lamp, beacon)
+* Transactional mana transfers and corporea requests
+  * Corporea requests should be operating within Fabric Transfer API transactions instead of defining top-level transactions per request
+  * Mana requests (and probably also block providers) should be transactional within a player's inventory to avoid awkward interactions in low-mana situations
+  * Can we maybe implement some kind of "attempt to put item back if transaction is rolled back" feature into NeoForge Corporea?
+* Move certain block entity attributes into block state properties
+  * floating flower island type (including a new type for enchanted soil)
+  * mana spreader scaffolding cover
+  * animated torch (target) direction (maybe, would make the initialization less weird, and allow observers to detect change in direction)
+* Flattern certain block entity attributes or block properties into block types
+  * mana spreader cover colors (to be able to tag them as `#c:dyed` and `#minecraft:dampens_vibrations`)
+  * mana pool dye colors (maybe even turn "fabulous" into a separate "color" somehow?)
+
+### Feature candidates (potentially breaking changes)
+* nice-to-have Patchouli features we could use, that are yet to be merged:
+  * generic advancement trigger for reading a book (PR #715)
+  * proper localization for book editions (PR #648)
+* Runic altar recipes:
+  * reagent definitions in recipe instead of hard-coded Livingrock
+    (recipe viewer support already exists, it just needs to be hooked up once the additional input is available)
+  * support generic catalyst items for altar recipes, i.e. items which are required but will be returned upon completion of the recipe
+    * change rune inputs to be catalysts
+  * Figure out a way to not just make a head for a player's current skin, but also allow historic skins somehow
+* Clayconia upgrade (somehow support mud, maybe even recipe support, but avoid becoming another Orechid variant)
+* pre/post mcfunction support for block-swapping recipes (Pure Daisy, Marimorphosis, Orechids)
+  * maybe even for item outputs? (petal apothecary, runic altar, mana infusion, terra plate, potentially clayconia)
+* Paintslinger Lens support for connected blocks, block entities, and generic entities
+  * replace hard-coded sheep/spark handling with registered painting functions for entity types
+    * needs to pick single entity or AoE radius (the latter should scale by burst size)
+    * default support: sheep, sparks, shulkers
+    * maybe default compat for Quark's dyed item frames?
+  * add support for connected blocks (e.g. beds, some kind of painted chests, modded maybe multi-blocks)
+  * add support for block entities (e.g. shulker boxes, beds, moving paintable blocks)
+    * won't support covered mana spreaders or dyed mana pools, since they capture the burst – unless…
+* switch more block/item processing flowers to use individual tags (or even recipes) instead of hard-coded block/item types or generic tags
+  * Hydroangeas (fluid tag `#botania:hydroangeas_consumable`, including just water by default)
+    (also upgrade infinite source detection to query the consumed fluid's actual spreading logic)
+  * Thermalily (fluid tag `#botania:thermalily_consumable`, includes only lava by default)
+  * Munchdew (block tag `#botania:munchdew_consumable`, includes only vanilla leaves tag by default)
+  * Clayconia (block tags `#botania:clayconia_converts_to_clayball` and `#botania:clayconia_converts_to_clay_block`, unless we decide to go the recipe route)
+  * Bubbell (switch to fluid tag `#botania:bubbell_displaceable`, maybe even support drying waterlogged blocks)
+    * fake air blocks will need to remember which fluid they actually displaced
+* armor trim support
+  * redesign of the Botania armor models to match UV mapping of vanilla armors, such that non-vanilla parts are moved to unused areas of the texture
+  * add Botania trim materials (probably manasteel, elementium, terrasteel, mana diamond, dragonstone, and the quartz variants)
+* Orechid recipe adjustments
+  * remove ancient debris from Orechid Ignem (replace with Loonium in Bastion Remnant)
+  * maybe extend biome bonus weight support from Marimorphosis to all Orechid-like recipes
+    * adjust Orechid stone recipes accordingly (more emeralds in mountains, more copper in dripstone caves, etc.)
+  * maybe add data-driven Orechid configurations to replace hard-coded GoG changes (mana cost per input item, operation speed)
+    * GoG could eventually become a data pack instead of having all kinds of exceptions hard-coded into Botania
\ No newline at end of file