2 files changed, 65 insertions, 0 deletions
diff --git a/docs/assembly_programming.md b/docs/assembly_programming.md
new file mode 100644
index 00000000..ca6cb9e3
--- /dev/null
+++ b/docs/assembly_programming.md
@@ -0,0 +1,25 @@
+# Assembly Programming
+
+- [**RGBDS documentation**][rgbds-doc]: Includes information on the RGBDS tools and the assembly language syntax.
+   - [**GBZ80 instructions**][gbz80-instructions]: List of CPU instructions and their effects.
+   - [**RGBASM features**][rgbasm-features]: How to use the assembler features: constants, labels, sections, macros, etc.
+   - [**RGBLINK features**][rgblink-features]: How to use the linker, including the [pokecrystal.link](/pokecrystal.link) linkerscript.
+- [**ASMSchool**][asmschool]: A gameboy assembly tutorial.
+- [**GB ASM Tutorial**][gb-asm-tutorial]: A newer but still in-progress asm tutorial.
+- [**Pan Docs**][pan-docs]: Everything You Always Wanted To Know About GAMEBOY (but were afraid to ask).
+- [**GameBoy Programming Manual**][gb-manual]: The official GameBoy programming and hardware manual by Nintendo.
+- [**GameBoy Opcode Summary**][gb-opcodes]: Describes the opcodes of GameBoy assembly language.
+- [**GameBoy Memory Map**][gb-memory-map]: Describes the GameBoy Color address space.
+- [**awesome-gbdev**][awesome-gbdev]: A curated list of Game Boy development resources such as tools, docs, emulators, related projects and open-source ROMs.
+
+[rgbds-doc]: https://rednex.github.io/rgbds/
+[rgbasm-features]: https://rednex.github.io/rgbds/rgbasm.5.html
+[rgblink-features]: https://rednex.github.io/rgbds/rgblink.5.html
+[gbz80-instructions]: https://rednex.github.io/rgbds/gbz80.7.html
+[asmschool]: http://gameboy.mongenel.com/asmschool.html
+[gb-asm-tutorial]: https://eldred.fr/gb-asm-tutorial/
+[pan-docs]: http://bgb.bircd.org/pandocs.htm
+[gb-manual]: https://ia801906.us.archive.org/19/items/GameBoyProgManVer1.1/GameBoyProgManVer1.1.pdf
+[gb-opcodes]: http://www.devrs.com/gb/files/opcodes.html
+[gb-memory-map]: http://gameboy.mongenel.com/dmg/asmmemmap.html
+[awesome-gbdev]: https://github.com/avivace/awesome-gbdev
+\ No newline at end of file
diff --git a/docs/bugs_and_glitches.md b/docs/bugs_and_glitches.md
new file mode 100644
index 00000000..db564bda
--- /dev/null
+++ b/docs/bugs_and_glitches.md
@@ -0,0 +1,40 @@
+# Bugs and Glitches
+
+These are known bugs and glitches in the original Pokémon Yellow game: code that clearly does not work as intended, or that only works in limited circumstances but has the possibility to fail or crash.
+
+Fixes are written in the `diff` format. If you've used Git before, this should look familiar:
+
+```diff
+ this is some code
+-delete red - lines
++add green + lines
+```
+
+
+## Contents
+
+- [Options Menu Code Fails to Clear Joypad State on Initialization](#options-menu-code-fails-to-clear-joypad-state-on-initialization)
+- [Battle Transitions Fail to Account for Scripted Battles](#battle-transitions-fail-to-account-for-scripted-battles)
+
+
+## Options Menu Code Fails to Clear Joypad State on Initialization
+
+This bug (or feature!) results in all options being shifted left or right if the respective direction is pressed on the same frame the options menu is opened.
+The bug also exists in pokegold and pokecrystal.
+
+**Fix:** Update [engine/menu/options.asm](/engine/menu/options.asm)
+
+```diff
+ DisplayOptionMenu_:
+ +  call JoypadLowSensitivity
+    call InitOptions
+```
+
+## Battle Transitions Fail to Account for Scripted Battles
+
+When Oak Catches Pikachu in the Pallet Town cutscenes you don't yet have any Pokemon in Party.
+The Battle Transitions code has no error handling for this and reads wPartyMon1HP from wRivalName+6.
+This means you can manipulate this first transition to be faster by choosing a default rival name or writing and deleting 6 characters in a custom rival name.
+A similar series of bugs appears to exist in pokecrystal.
+
+**Fix:** TBD in [engine/battle/battle_transitions.asm](/engine/battle/battle_transitions.asm)
+\ No newline at end of file