diff --git a/papers/doc/1-intro/README.md b/papers/doc/1-intro/README.md
new file mode 100644
index 00000000..b6c884a8
--- /dev/null
+++ b/papers/doc/1-intro/README.md
@@ -0,0 +1,5 @@
+# introduction
+
+furnace is a tool which allows you to compose music using the sound chips of several video game consoles from the 8/16-bit era.
+
+the motivation behind this project is the fact that TODO!
diff --git a/papers/doc/README.md b/papers/doc/README.md
new file mode 100644
index 00000000..d440323c
--- /dev/null
+++ b/papers/doc/README.md
@@ -0,0 +1,3 @@
+# Furnace user manual
+
+TOOOODOOOOOOOO
diff --git a/papers/format.md b/papers/format.md
new file mode 100644
index 00000000..bd829516
--- /dev/null
+++ b/papers/format.md
@@ -0,0 +1,207 @@
+# the Furnace file format (.fur)
+
+while Furnace works directly with the .dmf format, I had to create a new format to handle future additions to the program.
+
+this document has the goal of detailing the format.
+
+# header
+
+the header is 32 bytes long.
+
+size | description
+-----|------------------------------------
+ 16  | "-Furnace module-" format magic
+  2  | format version
+     | - should be 1 for Furnace 0.2
+  2  | reserved
+  4  | song info pointer
+  8  | reserved
+
+# song info
+
+size | description
+-----|------------------------------------
+  4  | "INFO" block ID
+  4  | length of this block
+  1  | time base
+  1  | speed 1
+  1  | speed 2
+  1  | initial arpeggio time
+  4f | ticks per second
+     | - 60 is NTSC
+     | - 50 is PAL
+  2  | pattern length
+  2  | orders length
+  1  | highlight A
+  1  | highlight B
+  2  | instrument count
+  2  | wavetable count
+  2  | sample count
+  4  | pattern count
+  1  | sound chip count
+ 31  | list of sound chips
+     | - possible soundchips:
+     |   - 0x00: invalid - 0 channels
+     |   - 0x01: YMU759 - 17 channels
+     |   - 0x02: Genesis - 10 channels
+     |   - 0x03: SMS (SN76489) - 4 channels
+     |   - 0x04: Game Boy - 4 channels
+     |   - 0x05: PC Engine - 6 channels
+     |   - 0x06: NES - 5 channels
+     |   - 0x07: C64 (8580) - 3 channels
+     |   - 0x08: Arcade (YM2151) - 13 channels
+     |   - 0x09: Neo Geo (YM2610) - 13 channels
+     |   - bit 6 enables alternate mode:
+     |     - 0x42: Genesis extended - 13 channels
+     |     - 0x47: C64 (6581) - 3 channels
+     |     - 0x49: Neo Geo extended - 16 channels
+  4  | reserved
+ 124 | sound chip parameters (TODO)
+  4  | pointer song name
+  4  | pointer to song author
+ 24  | reserved for compatibility flags
+ 4?? | pointers to instruments
+ 4?? | pointers to wavetables
+ 4?? | pointers to samples
+ 4?? | pointers to patterns
+ ??? | orders
+     | - a table of shorts
+     | - size=channels*ordLen
+ ??? | effect columns
+     | - size=channels
+
+# instrument
+
+size | description
+-----|------------------------------------
+  4  | "INST" block ID
+  4  | length of this block
+  2  | format version (see header)
+  1  | instrument type
+     | - 0: standard
+     | - 1: FM
+     | - 2: Game Boy
+     | - 3: C64
+     | - 4: Amiga/sample
+  1  | reserved
+  4  | pointer to instrument name
+ --- | **FM instrument data**
+  1  | alg
+  1  | feedback
+  1  | fms
+  1  | ams
+  1  | operator count (always 4)
+  3  | reserved
+ --- | **FM operator data** × 4
+  1  | am
+  1  | ar
+  1  | dr
+  1  | mult
+  1  | rr
+  1  | sl
+  1  | tl
+  1  | dt2
+  1  | rs
+  1  | dt
+  1  | d2r
+  1  | ssgEnv
+  1  | dam
+  1  | dvb
+  1  | egt
+  1  | ksl
+  1  | sus
+  1  | vib
+  1  | ws
+  1  | ksr
+ 12  | reserved
+ --- | **Game Boy instrument data**
+  1  | volume
+  1  | direction
+  1  | length
+  1  | sound length
+ --- | **C64 instrument data**
+  1  | triangle
+  1  | saw
+  1  | pulse
+  1  | noise
+  1  | attack
+  1  | decay
+  1  | sustain
+  1  | release
+  2  | duty
+  1  | ring mod
+  1  | osc sync
+  1  | to filter
+  1  | init filter
+  1  | vol macro is cutoff
+  1  | resonance
+  1  | low pass
+  1  | band pass
+  1  | high pass
+  1  | channel 3 off
+  2  | cutoff
+  1  | duty macro is absolute
+  1  | filter macro is absolute
+ --- | **Amiga instrument data**
+  2  | initial sample
+ 14  | reserved
+ --- | **standard instrument data**
+  4  | volume macro length
+  4  | arp macro length
+  4  | duty macro length
+  4  | wave macro length
+  4  | volume macro loop
+  4  | arp macro loop
+  4  | duty macro loop
+  4  | wave macro loop
+  1  | arp macro mode
+  3  | reserved
+ 4?? | volume macro
+ 4?? | arp macro
+ 4?? | duty macro
+ 4?? | wave macro
+
+# wavetable
+
+size | description
+-----|------------------------------------
+  4  | "WAVE" block ID
+  4  | length of this block
+  4  | pointer to wavetable name
+  4  | wavetable size
+  4  | wavetable min
+  4  | wavetable max
+ 4?? | wavetable data
+
+# sample
+
+size | description
+-----|------------------------------------
+  4  | "SMPL" block ID
+  4  | length of this block
+  4  | pointer to sample name
+  4  | length
+  4  | rate
+  2  | volume
+  2  | pitch
+  1  | depth
+  7  | reserved
+ 2?? | sample data (always 16-bit)
+
+# pattern
+
+size | description
+-----|------------------------------------
+  4  | "PATR" block ID
+  4  | length of this block
+  2  | channel
+  2  | pattern index
+  4  | reserved
+ ??? | pattern data
+     | - size: rows*(4+effectColumns*2)*2
+     | - read shorts in this order:
+     |   - note
+     |   - octave
+     |   - instrument
+     |   - volume
+     |   - effect and effect data...