diff --git a/firmware/keyboard.h b/firmware/keyboard.h
index e43d315..3521cd6 100644
--- a/firmware/keyboard.h
+++ b/firmware/keyboard.h
@@ -25,22 +25,18 @@
 
 // ----------------------------------------------------------------------------
 
-#if MAKE__KEYBOARD == 'ergodox'
-
-    #define  KB__ROWS      6
-    #define  KB__COLUMNS  14
-
-#else
-
-    #error "Keyboard dimensions must be defined"
-
+#ifndef OPT__KB__ROWS
+    #error  "OPT__KB__ROWS not defined"
+#endif
+#ifndef OPT__KB__COLUMNS
+    #error  "OPT__KB__COLUMNS not defined"
 #endif
 
 // ----------------------------------------------------------------------------
 
 // controller
 uint8_t kb__init          (void);
-uint8_t kb__update_matrix (bool matrix[KB__ROWS][KB__COLUMNS]);
+uint8_t kb__update_matrix (bool matrix[OPT__KB__ROWS][OPT__KB__COLUMNS]);
 
 // LED
 void kb__led__on  (uint8_t led);
@@ -59,8 +55,7 @@ void kb__led__delay__usb_init (void);
 void kb__led__logical_on  (char led);
 void kb__led__logical_off (char led);
 // -------
-void kb__layout__exec_key_pointer  (bool pressed, void * pointer);
-void kb__layout__exec_key_location (bool pressed, uint8_t row, uint8_t column);
+void kb__layout__exec_key (bool pressed, uint8_t row, uint8_t column);
 
 
 // ----------------------------------------------------------------------------
@@ -78,13 +73,13 @@ void kb__layout__exec_key_location (bool pressed, uint8_t row, uint8_t column);
 // macros ---------------------------------------------------------------------
 // ----------------------------------------------------------------------------
 
-// === KB__ROWS ===
-/**                                                 macros/KB__ROWS/description
+// === OPT__KB__ROWS ===
+/**                                            macros/OPT__KB__ROWS/description
  * The number of rows in a given keyboard's matrix
  */
 
-// === KB__COLUMNS ===
-/**                                              macros/KB__COLUMNS/description
+// === OPT__KB__COLUMNS ===
+/**                                         macros/OPT__KB__COLUMNS/description
  * The number of columns in a given keyboard's matrix
  */
 
@@ -239,25 +234,8 @@ void kb__layout__exec_key_location (bool pressed, uint8_t row, uint8_t column);
 
 // ----------------------------------------------------------------------------
 
-// === kb__layout__exec_key_pointer ===
-/**                          functions/kb__layout__exec_key_pointer/description
- * Perform a "press" or "release" of the key pointed to
- *
- * Arguments:
- * - `pressed`:
- *     - `true`: Indicates that the key to be "executed" has been pressed
- *     - `false`: Indicates that the key to be "executed" has been released
- * - `pointer`: A pointer to the key to execute
- *
- * Notes:
- * - The pointer may be of any type, and to a value in any address space.  It
- *   is up to the keyboard implementation to define this.  Since this is the
- *   only `exec_key_pointer` function though, all the keys should probably be
- *   in the same address space, wherever they are.
- */
-
-// === kb__layout__exec_key_location ===
-/**                         functions/kb__layout__exec_key_location/description
+// === kb__layout__exec_key ===
+/**                                  functions/kb__layout__exec_key/description
  * Perform the appropriate actions for a "press" or "release" of the key at the
  * given position.
  *
diff --git a/firmware/keyboard/ergodox/controller.c b/firmware/keyboard/ergodox/controller.c
index 26a8cbd..8e36770 100644
--- a/firmware/keyboard/ergodox/controller.c
+++ b/firmware/keyboard/ergodox/controller.c
@@ -25,7 +25,7 @@ uint8_t kb__init(void) {
     return 0;  // success
 }
 
-uint8_t kb__update_matrix(bool matrix[KB__ROWS][KB__COLUMNS]) {
+uint8_t kb__update_matrix(bool matrix[OPT__KB__ROWS][OPT__KB__COLUMNS]) {
     if (teensy__update_matrix(matrix))
         return 1;
     if (mcp23018__update_matrix(matrix))
diff --git a/firmware/keyboard/ergodox/controller/mcp23018.c b/firmware/keyboard/ergodox/controller/mcp23018.c
index 6db3fe3..d328598 100644
--- a/firmware/keyboard/ergodox/controller/mcp23018.c
+++ b/firmware/keyboard/ergodox/controller/mcp23018.c
@@ -18,7 +18,7 @@
 
 // ----------------------------------------------------------------------------
 
-#if KB__ROWS != 6 || KB__COLUMNS != 14
+#if OPT__KB__ROWS != 6 || OPT__KB__COLUMNS != 14
     #error "Expecting different keyboard dimensions"
 #endif
 
@@ -135,7 +135,7 @@ out:
  * - success: `0`
  * - failure: twi status code
  */
-uint8_t mcp23018__update_matrix(bool matrix[KB__ROWS][KB__COLUMNS]) {
+uint8_t mcp23018__update_matrix(bool matrix[OPT__KB__ROWS][OPT__KB__COLUMNS]) {
     uint8_t ret, data;
 
     // initialize things, just to make sure
diff --git a/firmware/keyboard/ergodox/controller/mcp23018.h b/firmware/keyboard/ergodox/controller/mcp23018.h
index 1bf4765..b863af7 100644
--- a/firmware/keyboard/ergodox/controller/mcp23018.h
+++ b/firmware/keyboard/ergodox/controller/mcp23018.h
@@ -22,7 +22,7 @@
 // ----------------------------------------------------------------------------
 
 uint8_t mcp23018__init          (void);
-uint8_t mcp23018__update_matrix (bool matrix[KB__ROWS][KB__COLUMNS]);
+uint8_t mcp23018__update_matrix (bool matrix[OPT__KB__ROWS][OPT__KB__COLUMNS]);
 
 
 // ----------------------------------------------------------------------------
diff --git a/firmware/keyboard/ergodox/controller/teensy-2-0.c b/firmware/keyboard/ergodox/controller/teensy-2-0.c
index 5e0e9c1..6f9372f 100644
--- a/firmware/keyboard/ergodox/controller/teensy-2-0.c
+++ b/firmware/keyboard/ergodox/controller/teensy-2-0.c
@@ -23,7 +23,7 @@
     #error "Expecting different CPU frequency"
 #endif
 
-#if KB__ROWS != 6 || KB__COLUMNS != 14
+#if OPT__KB__ROWS != 6 || OPT__KB__COLUMNS != 14
 	#error "Expecting different keyboard dimensions"
 #endif
 
@@ -236,7 +236,7 @@ uint8_t teensy__init(void) {
  * Returns:
  * - success: `0`
  */
-uint8_t teensy__update_matrix(bool matrix[KB__ROWS][KB__COLUMNS]) {
+uint8_t teensy__update_matrix(bool matrix[OPT__KB__ROWS][OPT__KB__COLUMNS]) {
     #if OPT__TEENSY__DRIVE_ROWS
         update_columns_for_row(matrix, 0);
         update_columns_for_row(matrix, 1);
diff --git a/firmware/keyboard/ergodox/controller/teensy-2-0.h b/firmware/keyboard/ergodox/controller/teensy-2-0.h
index cb69953..bc805dd 100644
--- a/firmware/keyboard/ergodox/controller/teensy-2-0.h
+++ b/firmware/keyboard/ergodox/controller/teensy-2-0.h
@@ -22,7 +22,7 @@
 // ----------------------------------------------------------------------------
 
 uint8_t teensy__init          (void);
-uint8_t teensy__update_matrix (bool matrix[KB__ROWS][KB__COLUMNS])
+uint8_t teensy__update_matrix (bool matrix[OPT__KB__ROWS][OPT__KB__COLUMNS])
 
 
 // ----------------------------------------------------------------------------
diff --git a/firmware/keyboard/ergodox/layout/colemak-symbol-mod.c b/firmware/keyboard/ergodox/layout/colemak-symbol-mod.c
index 4cc2da2..47bc698 100644
--- a/firmware/keyboard/ergodox/layout/colemak-symbol-mod.c
+++ b/firmware/keyboard/ergodox/layout/colemak-symbol-mod.c
@@ -9,29 +9,21 @@
  *
  * Implements the "layout" section of '.../firmware/keyboard.h'
  *
- * Notes:
- * - This layout *does not* contain a key mapped to the bootloader function.
- *   To reflash from this layout, you will need to physically press the button
- *   on the top right of the Teensy.
- *
  * History:
  * - Originally submitted by Jason Trill [jjt] (https://github.com/jjt) (who
  *   declined to be added to the copyright above).
- * - Transcribed by Ben Blazak when the layout format changed.
- *
- * TODO: fix this file, after the qwerty layout is done
- * TODO: rearrange things to put a btldr key somewhere
+ * - Various changes have been made since (see git history)
  */
 
 
-#include "./default/common.h"
+#include "./common/definitions.h"
 
 
 // ----------------------------------------------------------------------------
 // matrix control
 // ----------------------------------------------------------------------------
 
-#include "./default/exec_key.c.h"
+#include "./common/exec_key.c.h"
 
 
 // ----------------------------------------------------------------------------
@@ -39,7 +31,7 @@
 // ----------------------------------------------------------------------------
 
 void kb__led__logical_on(char led) {
-    switch led {
+    switch(led) {
         case 'N': kb__led__on(1); break;  // numlock
         case 'C': kb__led__on(2); break;  // capslock
         case 'S': kb__led__on(3); break;  // scroll lock
@@ -49,7 +41,7 @@ void kb__led__logical_on(char led) {
 }
 
 void kb__led__logical_off(char led) {
-    switch led {
+    switch(led) {
         case 'N': kb__led__off(1); break;  // numlock
         case 'C': kb__led__off(2); break;  // capslock
         case 'S': kb__led__off(3); break;  // scroll lock
@@ -63,144 +55,142 @@ void kb__led__logical_off(char led) {
 // keys
 // ----------------------------------------------------------------------------
 
-#include "./default/keys.h"
+#include "./common/keys.c.h"
 
-// layer
-key_t L0pu1po  = { &kf__layer__push, 0x0001, &kf__layer__pop, 0x0001 };
-key_t L1pu2    = { &kf__layer__push, 0x0102, NULL,                 0 };
-key_t L1po     = { &kf__layer__pop,  0x0100, NULL,                 0 };
-key_t L1pu2po  = { &kf__layer__push, 0x0102, &kf__layer__pop, 0x0102 };
-
-// --- NumPush
-const uint16_t PROGMEM NumPush__press[] = {
-    2, &kf__layer__push, 0x0203,
-       &kf__press, KEY__LockingNumLock };
-key_t NumPush = { &kf__macro__progmem, &NumPush__press,
-                  &kf__release, KEY__LockingNumLock };
-
-// --- NumPop
-const uint16_t PROGMEM NumPop__press[] = {
-    2, &kf__layer__pop, 0x0203,
-       &kf__press, KEY__LockingNumLock };
-key_t NumPop = { &kf__macro__progmem, &NumPop__press,
-                 &kf__release, KEY__LockingNumLock };
-
-// --- NumPuPo
-const uint16_t PROGMEM NumPuPo__press[] = {
-    3, &kf__layer__push, 0x0203,
-       &kf__press,   KEY__LockingNumLock,
-       &kf__release, KEY__LockingNumLock };
-const uint16_t PROGMEM NumPuPo__release[] = {
-    3, &kf__layer__pop, 0x0203,
-       &kf__press,   KEY__LockingNumLock,
-       &kf__release, KEY__LockingNumLock };
-key_t NumPuPo = { &kf__macro__progmem, &NumPuPo__press,
-                  &kf__macro__progmem, &NumPuPo__release };
+KEYS__LAYER__NUM_PU_PO(10, 4);
+KEYS__LAYER__NUM_PUSH(10, 4);
+KEYS__LAYER__NUM_POP(10);
 
 
 // ----------------------------------------------------------------------------
 // layout
 // ----------------------------------------------------------------------------
 
-key_t layout[][KB__ROWS][KB__COLUMNS] = {
+#include "./common/matrix.h"
+
+
+layout_t _layout = {
 
 // ............................................................................
 
     MATRIX_LAYER(  // layer 0 : default (colemak)
-
-// unused
-NA,
+// macro, unused,
+       K,    nop,
 // left hand ...... ......... ......... ......... ......... ......... .........
-   Equal,       K1,       K2,       K3,       K4,       K5,    L1pu2,
-     Tab,        Q,        W,        F,        P,        G,      Esc,
-   CtrlL,        A,        R,        S,        T,        D,
-Sh2KCapL,        Z,        X,        C,        V,        B,  L1pu2po,
-    GUIL,    Grave,  Bkslash,     AltL,  L0pu1po,
-                                                               CtrlL,     AltL,
-                                                        NA,       NA,     Home,
-                                                     Space,    Enter,      End,
+   equal,        1,        2,        3,        4,        5,   lpu2l2,
+     tab,        q,        w,        f,        p,        g,      esc,
+   ctrlL,        a,        r,        s,        t,        d,
+shL2kcap,        z,        x,        c,        v,        b, lpupo2l2,
+    guiL,    grave,  bkslash,     altL, lpupo1l1,
+                                                               ctrlL,     altL,
+                                                       nop,      nop,     home,
+                                                     space,    enter,      end,
 // right hand ..... ......... ......... ......... ......... ......... .........
-           NumPush,       K6,       K7,       K8,       K9,       K0,     Dash,
-               Esc,        J,        L,        U,        Y,  Semicol,  Bkslash,
-                           H,        N,        E,        I,        O,    Quote,
-           NumPuPo,        K,        M,    Comma,   Period,    Slash, Sh2KCapR,
-                               L0pu1po,   ArrowL,   ArrowD,   ArrowU,   ArrowR,
-    AltR,    CtrlR,
-   PageU,       NA,       NA,
-   PageD,      Del,       Bs  ),
+           numPush,        6,        7,        8,        9,        0,     dash,
+               esc,        j,        l,        u,        y,  semicol,  bkslash,
+                           h,        n,        e,        i,        o,    quote,
+           numPuPo,        k,        m,    comma,   period,    slash, shR2kcap,
+                              lpupo1l1,   arrowL,   arrowD,   arrowU,   arrowR,
+    altR,    ctrlR,
+   pageU,      nop,      nop,
+   pageD,      del,       bs  ),
 
 // ............................................................................
 
     MATRIX_LAYER(  // layer 1 : function and symbol keys
-// unused
-NA,
+// macro, unused,
+       K,    nop,
 // left hand ...... ......... ......... ......... ......... ......... .........
-  Transp,       F1,       F2,       F3,       F4,       F5,      F11,
-  Transp,   BraceL,   BraceR,    BrktL,    BrktR,    Colon,   Transp,
-  Transp,  Bkslash,    Slash,   ParenL,   ParenR,  Semicol,
-  Transp,   Exclam,       At,    Pound,   Dollar,  Percent,   Transp,
-  Transp,   Transp,   Transp,   Transp,   Transp,
-                                                              Transp,   Transp,
-                                                    Transp,   Transp,   Transp,
-                                                    Transp,   Transp,   Transp,
+  transp,       F1,       F2,       F3,       F4,       F5,      F11,
+  transp,   braceL,   braceR,    brktL,    brktR,    colon,   transp,
+  transp,  bkslash,    slash,   parenL,   parenR,  semicol,
+  transp,   exclam,       at,    pound,   dollar,  percent,   transp,
+  transp,   transp,   transp,   transp, lpupo3l3,
+                                                              transp,   transp,
+                                                    transp,   transp,   transp,
+                                                    transp,   transp,   transp,
 // right hand ..... ......... ......... ......... ......... ......... .........
-               F12,       F6,       F7,       F8,       F9,      F10,    Power,
-            Transp,       NA,    Equal,     Plus,     Dash,  Undersc,       NA,
-                      ArrowL,   ArrowD,   ArrowU,   ArrowR,       NA,       NA,
-            Transp,    Caret,      Amp, Asterisk,   ParenL,   ParenR,   Transp,
-                                Transp,   Transp,   Transp,   Transp,   Transp,
-  Transp,   Transp,
-  Transp,   Transp,   Transp,
-  Transp,   Transp,   Transp  ),
+               F12,       F6,       F7,       F8,       F9,      F10,    power,
+            transp,      nop,    equal,     plus,     dash,  undersc,      nop,
+                      arrowL,   arrowD,   arrowU,   arrowR,      nop,      nop,
+            transp,    caret,      amp, asterisk,   parenL,   parenR,   transp,
+                              lpupo3l3,   transp,   transp,   transp,   transp,
+  transp,   transp,
+  transp,   transp,   transp,
+  transp,   transp,   transp  ),
 
 // ............................................................................
 
     MATRIX_LAYER(  // layer 2 : QWERTY alphanum
-// unused
-NA,
+// macro, unused,
+       K,    nop,
 // left hand ...... ......... ......... ......... ......... ......... .........
-  Transp,       K1,       K2,       K3,       K4,       K5,     L1po,
-  Transp,        Q,        W,        E,        R,        T,   Transp,
-  Transp,        A,        S,        D,        F,        G,
-  Transp,        Z,        X,        C,        V,        B,   Transp,
-  Transp,   Transp,   Transp,   Transp,   Transp,   Transp,
-                                                              Transp,   Transp,
-                                                    Transp,   Transp,   Transp,
-                                                    Transp,   Transp,   Transp,
+  transp,        1,        2,        3,        4,        5,   lpo2l2,
+  transp,        q,        w,        e,        r,        t,   transp,
+  transp,        a,        s,        d,        f,        g,
+  transp,        z,        x,        c,        v,        b,   transp,
+  transp,   transp,   transp,   transp,   transp,   transp,
+                                                              transp,   transp,
+                                                    transp,   transp,   transp,
+                                                    transp,   transp,   transp,
 // right hand ..... ......... ......... ......... ......... ......... .........
-            Transp,       K6,       K7,       K8,       K9,       K0,   Transp,
-            Transp,        Y,        U,        I,        O,        P,   Transp,
-                           H,        J,        K,        L,  Semicol,   Transp,
-            Transp,        N,        M,    Comma,   Period,    Slash,   Transp,
-                                Transp,   Transp,   Transp,   Transp,   Transp,
-  Transp,   Transp,
-  Transp,   Transp,   Transp,
-  Transp,   Transp,   Transp  ),
+            transp,        6,        7,        8,        9,        0,   transp,
+            transp,        y,        u,        i,        o,        p,   transp,
+                           h,        j,        k,        l,  semicol,   transp,
+            transp,        n,        m,    comma,   period,    slash,   transp,
+                                transp,   transp,   transp,   transp,   transp,
+  transp,   transp,
+  transp,   transp,   transp,
+  transp,   transp,   transp  ),
 
 
 // ............................................................................
 
-    MATRIX_LAYER(  // layer 3 : numpad
-// unused
-NA,
+    MATRIX_LAYER(  // layer 3 : keyboard functions
+// macro, unused,
+       K,    nop,
 // left hand ...... ......... ......... ......... ......... ......... .........
-  Transp,   Transp,   Transp,   Transp,   Transp,   Transp,   Transp,
-  Transp,   Transp,   Transp,   Transp,   Transp,   Transp,   Transp,
-  Transp,   Transp,   Transp,   Transp,   Transp,   Transp,
-  Transp,   Transp,   Transp,   Transp,   Transp,   Transp,   Transp,
-  Transp,      Ins,   Transp,   Transp,   Transp,
-                                                              Transp,   Transp,
-                                                    Transp,   Transp,   Transp,
-                                                    Transp,   Transp,   Transp,
+   btldr,      nop,      nop,      nop,      nop,      nop,      nop,
+     nop,      nop,      nop,      nop,      nop,      nop,      nop,
+     nop,      nop,      nop,      nop,      nop,      nop,
+     nop,      nop,      nop,      nop,      nop,      nop,      nop,
+     nop,      nop,      nop,      nop,      nop,
+                                                                 nop,      nop,
+                                                       nop,      nop,      nop,
+                                                       nop,      nop,      nop,
 // right hand ..... ......... ......... ......... ......... ......... .........
-            NumPop,   Transp,   NumPop,    Equal,    KPDiv,    KPMul,   Transp,
-            Transp,   Transp,      KP7,      KP8,      KP9,    KPSub,   Transp,
-                      Transp,      KP4,      KP5,      KP6,    KPAdd,   Transp,
-            Transp,   Transp,      KP1,      KP2,      KP3,  KPEnter,   Transp,
-                                Transp,   Transp,   Period,  KPEnter,   Transp,
-  Transp,   Transp,
-  Transp,   Transp,   Transp,
-  Transp,   Transp,      KP0  ),
+               nop,      nop,      nop,      nop,      nop,      nop,      nop,
+               nop,      nop,      nop,      nop,      nop,      nop,      nop,
+                         nop,      nop,      nop,      nop,      nop,      nop,
+               nop,      nop,      nop,      nop,      nop,      nop,      nop,
+                                   nop,      nop,      nop,      nop,      nop,
+     nop,      nop,
+     nop,      nop,      nop,
+     nop,      nop,      nop  ),
+
+// ............................................................................
+
+    MATRIX_LAYER(  // layer 4 : numpad
+// macro, unused,
+       K,    nop,
+// left hand ...... ......... ......... ......... ......... ......... .........
+  transp,   transp,   transp,   transp,   transp,   transp,   transp,
+  transp,   transp,   transp,   transp,   transp,   transp,   transp,
+  transp,   transp,   transp,   transp,   transp,   transp,
+  transp,   transp,   transp,   transp,   transp,   transp,   transp,
+  transp,      ins,   transp,   transp,   transp,
+                                                              transp,   transp,
+                                                    transp,   transp,   transp,
+                                                    transp,   transp,   transp,
+// right hand ..... ......... ......... ......... ......... ......... .........
+            numPop,   transp,   numPop,    equal,    kpDiv,    kpMul,   transp,
+            transp,   transp,      kp7,      kp8,      kp9,    kpSub,   transp,
+                      transp,      kp4,      kp5,      kp6,    kpAdd,   transp,
+            transp,   transp,      kp1,      kp2,      kp3,  kpEnter,   transp,
+                                transp,   transp,   period,  kpEnter,   transp,
+  transp,   transp,
+  transp,   transp,   transp,
+  transp,   transp,      kp0  ),
 
 // ............................................................................
 };
diff --git a/firmware/keyboard/ergodox/layout/common/definitions.h b/firmware/keyboard/ergodox/layout/common/definitions.h
index e5956f8..fd1ea38 100644
--- a/firmware/keyboard/ergodox/layout/common/definitions.h
+++ b/firmware/keyboard/ergodox/layout/common/definitions.h
@@ -23,6 +23,7 @@
 #include "../../../../../firmware/lib/usb.h"
 #include "../../../../../firmware/lib/usb/usage-page/keyboard.h"
 #include "../../../../../firmware/lib/layout/key-functions.h"
+#include "../../../../../firmware/lib/layout/layer-stack.h"
 
 // ----------------------------------------------------------------------------
 
@@ -32,6 +33,10 @@
  * Notes:
  * - Keys will be of the form
  *   `key_t key = { &press_function, &release_function };`
+ *
+ * - The fact that keys are of this type (composed of two
+ *   `void (*function)(void)` pointers) is assumed throughout most of these
+ *   layout files
  */
 typedef  void (*key_t[2])(void);
 
@@ -42,7 +47,28 @@ typedef  void (*key_t[2])(void);
  * - The first dimension of the matrix (left blank in the typedef since it
  *   varies between layouts) is "layers"
  */
-typedef  key_t PROGMEM layout_t[][KB__ROWS][KB__COLUMNS];
+typedef  const key_t PROGMEM layout_t[][OPT__KB__ROWS][OPT__KB__COLUMNS];
+
+/**                                                variables/layout/description
+ * The variable containing our layout matrix
+ */
+layout_t _layout;
+
+/**                                            variables/sticky_key/description
+ * A pointer to the release function of the last sticky key pressed
+ *
+ * The function pointed to by this should be executed directly after executing
+ * the "press" function of the next key pressed.
+ *
+ * Notes:
+ * - In order for things to work right, sticky keys should either execute this
+ *   stored function themselves before placing their own "release" function
+ *   value here, or else save the value that's here and call it as part of
+ *   their own "release" function.  If this isn't done, and the key pressed
+ *   directly before this was a sticky key as well, then the previous sticky
+ *   key will never be released.
+ */
+void (*_sticky_key)(void);
 
 
 // ----------------------------------------------------------------------------
diff --git a/firmware/keyboard/ergodox/layout/common/exec_key.c.h b/firmware/keyboard/ergodox/layout/common/exec_key.c.h
index 5691cb6..1ea567a 100644
--- a/firmware/keyboard/ergodox/layout/common/exec_key.c.h
+++ b/firmware/keyboard/ergodox/layout/common/exec_key.c.h
@@ -16,25 +16,32 @@
 // ----------------------------------------------------------------------------
 // ----------------------------------------------------------------------------
 
+
 #include "./definitions.h"
 
 // ----------------------------------------------------------------------------
 
-void kb__layout__exec_key_pointer(key_t * pointer) {  // TODO
-}
+void kb__layout__exec_key(bool pressed, int8_t row, int8_t column) {
+    void (*function)(void);
 
-void kb__layout__exec_key_location( bool   pressed,  // TODO
-                                    int8_t layer,
-                                    int8_t row,
-                                    int8_t column ) {
-    // - check for key redefinition in the EEPROM
-    //   - if there is one, execute it, according to the appropriate rules
-    // - lookup key in PROGMEM
-    //   - if it's transparent, look up the one below it, and so on
-    //     - NULL key pointers are transparent
-    //     - { NULL, 0, NULL, 0 } keys do nothing; this is the default, if no
-    //       key can be found
-    //   - call the press or release function, with the appropriate argument
+    for(uint8_t i=0; i<layer_stack__size(); i++) {
+        function = _layout[ layer_stack__peek(i) ]
+                          [ row                  ]
+                          [ column               ]
+                          [ (pressed) ? 0 : 1    ];
+        if (function) {
+            (*function)();
+
+            if (pressed && _sticky_key) {
+                (*_sticky_key)();
+                _sticky_key = NULL;
+            }
+
+            return;
+        }
+    }
+
+    // if we get here, there was a transparent key in layer 0; do nothing
 }
 
 
diff --git a/firmware/keyboard/ergodox/layout/common/keys.c.h b/firmware/keyboard/ergodox/layout/common/keys.c.h
index f298309..d0276d7 100644
--- a/firmware/keyboard/ergodox/layout/common/keys.c.h
+++ b/firmware/keyboard/ergodox/layout/common/keys.c.h
@@ -9,15 +9,24 @@
  * and extends the definitions in ".../lib/layout/key-functions.h"
  *
  * Meant to be included *only* by the layout using it.
- *
- * TODO: put a note about where to look for more information if people are
- * trying to learn more about how to make key functions (probably, the usb,
- * key_functions, and keys headers; and others?)
  */
 
 // TODO: implement chords (as in, for a chorded key layout)
 // TODO: implement sticky keys
 
+// TODO: write tutorials
+// - about 
+//   - basic key functions
+//     - mention where people should look for more information; probably, the
+//       usb, key_functions, and keys headers; and others?
+//   - sticky keys
+//   - macros
+//   - chorded keys
+//   - layers
+//   - making layouts
+// - put the tutorials in the readme.md of
+//   ".../firmware/keyboard/ergodox/layout"
+
 #ifndef ERGODOX_FIRMWARE__KEYBOARD__ERGODOX__LAYOUT__COMMON__KEYS__C__H
 #define ERGODOX_FIRMWARE__KEYBOARD__ERGODOX__LAYOUT__COMMON__KEYS__C__H
 // ----------------------------------------------------------------------------
@@ -92,6 +101,9 @@
  *   push the layer onto the stack, not pop anything out of it.  A key with
  *   only `po` should *only* pop the layer out of the stack.
  *
+ * - If the function *only* pops the layer-element, the `layer_number` is not
+ *   important: layers are popped based only on their `layer_id`.
+ *
  * Notes:
  * - To save space, if you define a push-pop function, the push (only) and pop
  *   (only) functions may be defined as follows (using the example `lpupo1l1`
@@ -101,10 +113,6 @@
  *       #define  keys__release__lpu1l1  P(nop)
  *       #define  keys__press__lpo1l1    R(lpupo1l1)
  *       #define  keys__release__lpo1l1  P(nop)
- *
- * - It is recommended (as a general rule) to allocate `layer_id`s as follows:
- *     - 0-9   : leave alone (for use in default layer key definitions)
- *     - 10-19 : for custom things like 'numPush' and 'numPop'
  */
 #define  KEYS__LAYER__PUSH_POP(ID, LAYER)                                   \
     void P(l##ID##pupo##LAYER) (void) { layer_stack__push(ID, LAYER); }     \
@@ -150,8 +158,7 @@
  * Press the given keycode, and also press "capslock" if this is the second
  * consecutive time this function has been called with `pressed == true`.
  *
- * Notes:
- * - Meant to be used with the left and right "shift" keys.
+ * Meant to be used with the left and right "shift" keys.
  */
 void KF(2_keys_capslock)(bool pressed, uint8_t keycode) {
     static counter = 0;
@@ -212,23 +219,23 @@ KEYS__DEFAULT( mute,    KEY__Mute       );
 
 // --- special function -------------------------------------------------------
 
-/**                                                  keys/shL2kcaps/description
+/**                                                   keys/shL2kcap/description
  * left shift + toggle capslock (if both shifts are pressed)
  *
- * This key always generates a left shift.  If the `shR2kcaps` is pressed at
+ * This key always generates a left shift.  If the `shR2kcap` is pressed at
  * the same time, "capslock" will be toggled.
  */
-void P(shL2kcaps) (void) { KF(2_keys_capslock)(true, KEY__LeftShift); }
-void R(shL2kcaps) (void) { KF(2_keys_capslock)(false, KEY__LeftShift); }
+void P(shL2kcap) (void) { KF(2_keys_capslock)(true, KEY__LeftShift); }
+void R(shL2kcap) (void) { KF(2_keys_capslock)(false, KEY__LeftShift); }
 
-/**                                                  keys/shR2kcaps/description
+/**                                                   keys/shR2kcap/description
  * right shift + toggle capslock (if both shifts are pressed)
  *
  * This key always generates a right shift.  If the `shL2kcaps` is pressed at
  * the same time, "capslock" will be toggled.
  */
-void P(shR2kcaps) (void) { KF(2_keys_capslock)(true, KEY__RightShift); }
-void R(shR2kcaps) (void) { KF(2_keys_capslock)(false, KEY__RightShift); }
+void P(shR2kcap) (void) { KF(2_keys_capslock)(true, KEY__RightShift); }
+void R(shR2kcap) (void) { KF(2_keys_capslock)(false, KEY__RightShift); }
 
 /**                                                      keys/btldr/description
  * jump to the bootloader
@@ -295,6 +302,18 @@ KEYS__LAYER__PUSH_POP(7, 7);
 #define  keys__press__lpo7l7    R(lpupo7l7)
 #define  keys__release__lpo7l7  P(nop)
 
+KEYS__LAYER__PUSH_POP(8, 8);
+#define  keys__press__lpu8l8    P(lpupo8l8)
+#define  keys__release__lpu8l8  P(nop)
+#define  keys__press__lpo8l8    R(lpupo8l8)
+#define  keys__release__lpo8l8  P(nop)
+
+KEYS__LAYER__PUSH_POP(9, 9);
+#define  keys__press__lpu9l9    P(lpupo9l9)
+#define  keys__release__lpu9l9  P(nop)
+#define  keys__press__lpo9l9    R(lpupo9l9)
+#define  keys__release__lpo9l9  P(nop)
+
 
 // ----------------------------------------------------------------------------
 // ----------------------------------------------------------------------------
diff --git a/firmware/keyboard/ergodox/layout/dvorak-kinesis-mod.c b/firmware/keyboard/ergodox/layout/dvorak-kinesis-mod.c
index a439118..3a8345c 100644
--- a/firmware/keyboard/ergodox/layout/dvorak-kinesis-mod.c
+++ b/firmware/keyboard/ergodox/layout/dvorak-kinesis-mod.c
@@ -6,22 +6,21 @@
 
 /**                                                                 description
  * A Dvorak layout adapted from the default Kinesis layout.  The position of
- * the symbol keys on the function layer was taken from the Arensito layout.
+ * the symbol keys on the function layer was (roughly) taken from the Arensito
+ * layout.
  *
  * Implements the "layout" section of '.../firmware/keyboard.h'
- *
- * TODO: fix this file, after the qwerty layout is done
  */
 
 
-#include "./default/common.h"
+#include "./common/definitions.h"
 
 
 // ----------------------------------------------------------------------------
 // matrix control
 // ----------------------------------------------------------------------------
 
-#include "./default/exec_key.c.h"
+#include "./common/exec_key.c.h"
 
 
 // ----------------------------------------------------------------------------
@@ -29,7 +28,7 @@
 // ----------------------------------------------------------------------------
 
 void kb__led__logical_on(char led) {
-    switch led {
+    switch(led) {
         case 'N': kb__led__on(1); break;  // numlock
         case 'C': kb__led__on(2); break;  // capslock
         case 'S': kb__led__on(3); break;  // scroll lock
@@ -39,7 +38,7 @@ void kb__led__logical_on(char led) {
 }
 
 void kb__led__logical_off(char led) {
-    switch led {
+    switch(led) {
         case 'N': kb__led__off(1); break;  // numlock
         case 'C': kb__led__off(2); break;  // capslock
         case 'S': kb__led__off(3); break;  // scroll lock
@@ -53,131 +52,116 @@ void kb__led__logical_off(char led) {
 // keys
 // ----------------------------------------------------------------------------
 
-#include "./default/keys.h"
+#include "./common/keys.c.h"
 
-// layer
-key_t L0pu1    = { &kf__layer__push, 0x0001, NULL,                 0 };
-key_t L0po     = { &kf__layer__pop,  0x0000, NULL,                 0 };
-key_t L0pu1po  = { &kf__layer__push, 0x0001, &kf__layer__pop, 0x0001 };
-key_t L1pu2po  = { &kf__layer__push, 0x0102, &kf__layer__pop, 0x0102 };
-
-// --- NumPush
-const uint16_t PROGMEM NumPush__press[] = {
-    2, &kf__layer__push, 0x0203,
-       &kf__press, KEY__LockingNumLock };
-key_t NumPush = { &kf__macro__progmem, &NumPush__press,
-                  &kf__release, KEY__LockingNumLock };
-
-// --- NumPop
-const uint16_t PROGMEM NumPop__press[] = {
-    2, &kf__layer__pop, 0x0203,
-       &kf__press, KEY__LockingNumLock };
-key_t NumPop = { &kf__macro__progmem, &NumPop__press,
-                 &kf__release, KEY__LockingNumLock };
+KEYS__LAYER__NUM_PUSH(10, 3);
+KEYS__LAYER__NUM_POP(10);
 
 
 // ----------------------------------------------------------------------------
 // layout
 // ----------------------------------------------------------------------------
 
-key_t layout[][KB__ROWS][KB__COLUMNS] = {
+#include "./common/matrix.h"
+
+
+layout_t _layout = {
 
 // ............................................................................
 
     MATRIX_LAYER(  // layer 0 : default
-
-// unused
-NA,
+// macro, unused,
+       K,    nop,
 // left hand ...... ......... ......... ......... ......... ......... .........
-   Equal,       K1,       K2,       K3,       K4,       K5,      Esc,
- Bkslash,    Quote,    Comma,   Period,        P,        Y,    L0pu1,
-     Tab,        A,        O,        E,        U,        I,
-Sh2KCapL,  Semicol,        Q,        J,        K,        X,  L0pu1po,
-    GUIL,    Grave,  Bkslash,   ArrowL,   ArrowR,
-                                                               CtrlL,     AltL,
-                                                        NA,       NA,     Home,
-                                                        Bs,      Del,      End,
+   equal,        1,        2,        3,        4,        5,      esc,
+ bkslash,    quote,    comma,   period,        p,        y,   lpu1l1,
+     tab,        a,        o,        e,        u,        i,
+shL2kcap,  semicol,        q,        j,        k,        x, lpupo1l1,
+    guiL,    grave,  bkslash,   arrowL,   arrowR,
+                                                               ctrlL,     altL,
+                                                       nop,      nop,     home,
+                                                        bs,      del,      end,
 // right hand ..... ......... ......... ......... ......... ......... .........
-           NumPush,       K6,       K7,       K8,       K9,       K0,     Dash,
-             BrktL,        F,        G,        C,        R,        L,    BrktR,
-                           D,        H,        T,        N,        S,    Slash,
-           L0pu1po,        B,        M,        W,        V,        Z, Sh2KCapR,
-                                ArrowL,   ArrowD,   ArrowU,   ArrowR,     GUIR,
-    AltR,    CtrlR,
-   PageU,       NA,       NA,
-   PageD,    Enter,    Space  ),
+           numPush,        6,        7,        8,        9,        0,     dash,
+             brktL,        f,        g,        c,        r,        l,    brktR,
+                           d,        h,        t,        n,        s,    slash,
+          lpupo1l1,        b,        m,        w,        v,        z, shR2kcap,
+                                arrowL,   arrowD,   arrowU,   arrowR,     guiR,
+    altR,    ctrlR,
+   pageU,      nop,      nop,
+   pageD,    enter,    space  ),
 
 // ............................................................................
 
     MATRIX_LAYER(  // layer 1 : function and symbol keys
-// unused
-NA,
+// macro, unused,
+       K,    nop,
 // left hand ...... ......... ......... ......... ......... ......... .........
-      NA,       F1,       F2,       F3,       F4,       F5,      F11,
-  Transp,   BraceL,   BraceR,    BrktL,    BrktR,       NA,     L0po,
-  Transp,  Semicol,    Slash,     Dash,      KP0,    Colon,
-  Transp,      KP6,      KP7,      KP8,      KP9,     Plus,  L1pu2po,
-  Transp,   Transp,   Transp,   Transp,   Transp,
-                                                              Transp,   Transp,
-                                                    Transp,   Transp,   Transp,
-                                                    Transp,   Transp,   Transp,
+     nop,       F1,       F2,       F3,       F4,       F5,      F11,
+  transp,   braceL,   braceR,    brktL,    brktR,      nop,   lpo1l1,
+  transp,  semicol,    slash,     dash,      kp0,    colon,
+  transp,      kp6,      kp7,      kp8,      kp9,     plus, lpupo2l2,
+  transp,   transp,   transp,   transp,   transp,
+                                                              transp,   transp,
+                                                    transp,   transp,   transp,
+                                                    transp,   transp,   transp,
 // right hand ..... ......... ......... ......... ......... ......... .........
-               F12,       F6,       F7,       F8,       F9,      F10,    Power,
-            Transp,       NA,  Undersc, LessThan, GrtrThan,   Dollar,  VolumeU,
-                     Bkslash,      KP1,   ParenL,   ParenR,    Equal,  VolumeD,
-           L1pu2po, Asterisk,      KP2,      KP3,      KP4,      KP5,     Mute,
-                                Transp,   Transp,   Transp,   Transp,   Transp,
-  Transp,   Transp,
-  Transp,   Transp,   Transp,
-  Transp,   Transp,   Transp  ),
+               F12,       F6,       F7,       F8,       F9,      F10,    power,
+            transp,      nop,  undersc, lessThan, grtrThan,   dollar,  volumeU,
+                     bkslash,      kp1,   parenL,   parenR,    equal,  volumeD,
+          lpupo2l2, asterisk,      kp2,      kp3,      kp4,      kp5,     mute,
+                                transp,   transp,   transp,   transp,   transp,
+  transp,   transp,
+  transp,   transp,   transp,
+  transp,   transp,   transp  ),
 
 // ............................................................................
 
     MATRIX_LAYER(  // layer 2 : keyboard functions
-// unused
-NA,
+// macro, unused,
+       K,    nop,
 // left hand ...... ......... ......... ......... ......... ......... .........
-   Btldr,       NA,       NA,       NA,       NA,       NA,       NA,
-      NA,       NA,       NA,       NA,       NA,       NA,       NA,
-      NA,       NA,       NA,       NA,       NA,       NA,
-      NA,       NA,       NA,       NA,       NA,       NA,       NA,
-      NA,       NA,       NA,       NA,       NA,
-                                                                  NA,       NA,
-                                                        NA,       NA,       NA,
-                                                        NA,       NA,       NA,
+   btldr,      nop,      nop,      nop,      nop,      nop,      nop,
+     nop,      nop,      nop,      nop,      nop,      nop,      nop,
+     nop,      nop,      nop,      nop,      nop,      nop,
+     nop,      nop,      nop,      nop,      nop,      nop,      nop,
+     nop,      nop,      nop,      nop,      nop,
+                                                                 nop,      nop,
+                                                       nop,      nop,      nop,
+                                                       nop,      nop,      nop,
 // right hand ..... ......... ......... ......... ......... ......... .........
-                NA,       NA,       NA,       NA,       NA,       NA,       NA,
-                NA,       NA,       NA,       NA,       NA,       NA,       NA,
-                          NA,       NA,       NA,       NA,       NA,       NA,
-                NA,       NA,       NA,       NA,       NA,       NA,       NA,
-                                    NA,       NA,       NA,       NA,       NA,
-      NA,       NA,
-      NA,       NA,       NA,
-      NA,       NA,       NA  ),
+               nop,      nop,      nop,      nop,      nop,      nop,      nop,
+               nop,      nop,      nop,      nop,      nop,      nop,      nop,
+                         nop,      nop,      nop,      nop,      nop,      nop,
+               nop,      nop,      nop,      nop,      nop,      nop,      nop,
+                                   nop,      nop,      nop,      nop,      nop,
+     nop,      nop,
+     nop,      nop,      nop,
+     nop,      nop,      nop  ),
 
 // ............................................................................
 
     MATRIX_LAYER(  // layer 3 : numpad
-// unused
-NA,
+// macro, unused,
+       K,    nop,
 // left hand ...... ......... ......... ......... ......... ......... .........
-  Transp,   Transp,   Transp,   Transp,   Transp,   Transp,   Transp,
-  Transp,   Transp,   Transp,   Transp,   Transp,   Transp,   Transp,
-  Transp,   Transp,   Transp,   Transp,   Transp,   Transp,
-  Transp,   Transp,   Transp,   Transp,   Transp,   Transp,   Transp,
-  Transp,      Ins,   Transp,   Transp,   Transp,
-                                                              Transp,   Transp,
-                                                    Transp,   Transp,   Transp,
-                                                    Transp,   Transp,   Transp,
+  transp,   transp,   transp,   transp,   transp,   transp,   transp,
+  transp,   transp,   transp,   transp,   transp,   transp,   transp,
+  transp,   transp,   transp,   transp,   transp,   transp,
+  transp,   transp,   transp,   transp,   transp,   transp,   transp,
+  transp,      ins,   transp,   transp,   transp,
+                                                              transp,   transp,
+                                                    transp,   transp,   transp,
+                                                    transp,   transp,   transp,
 // right hand ..... ......... ......... ......... ......... ......... .........
-            NumPop,   Transp,   NumPop,    Equal,    KPDiv,    KPMul,   Transp,
-            Transp,   Transp,      KP7,      KP8,      KP9,    KPSub,   Transp,
-                      Transp,      KP4,      KP5,      KP6,    KPAdd,   Transp,
-            Transp,   Transp,      KP1,      KP2,      KP3,  KPEnter,   Transp,
-                                Transp,   Transp,   Period,  KPEnter,   Transp,
-  Transp,   Transp,
-  Transp,   Transp,   Transp,
-  Transp,   Transp,      KP0  ),
+            numPop,   transp,   numPop,    equal,    kpDiv,    kpMul,   transp,
+            transp,   transp,      kp7,      kp8,      kp9,    kpSub,   transp,
+                      transp,      kp4,      kp5,      kp6,    kpAdd,   transp,
+            transp,   transp,      kp1,      kp2,      kp3,  kpEnter,   transp,
+                                transp,   transp,   period,  kpEnter,   transp,
+  transp,   transp,
+  transp,   transp,   transp,
+  transp,   transp,      kp0  ),
 
 // ............................................................................
 };
diff --git a/firmware/keyboard/ergodox/layout/qwerty-kinesis-mod.c b/firmware/keyboard/ergodox/layout/qwerty-kinesis-mod.c
index dd98ba9..9c40a36 100644
--- a/firmware/keyboard/ergodox/layout/qwerty-kinesis-mod.c
+++ b/firmware/keyboard/ergodox/layout/qwerty-kinesis-mod.c
@@ -6,12 +6,10 @@
 
 /**                                                                 description
  * A QWERTY layout adapted from the default Kinesis layout.  The position of
- * the symbol keys on the function layer was taken from the Arensito layout.
+ * the symbol keys on the function layer was (roughly) taken from the Arensito
+ * layout.
  *
  * Implements the "layout" section of '.../firmware/keyboard.h'
- *
- * TODO: put a note about where to look for more information if people are
- * trying to make their own layout
  */
 
 
@@ -22,7 +20,7 @@
 // matrix control
 // ----------------------------------------------------------------------------
 
-#include "./default/exec_key.c.h"
+#include "./common/exec_key.c.h"
 
 
 // ----------------------------------------------------------------------------
@@ -67,7 +65,7 @@ KEYS__LAYER__NUM_POP(10);
 #include "./common/matrix.h"
 
 
-layout_t layout = {
+layout_t _layout = {
 
 // ............................................................................
 
@@ -78,7 +76,7 @@ layout_t layout = {
    equal,        1,        2,        3,        4,        5,      esc,
  bkslash,        q,        w,        e,        r,        t,   lpu1l1,
      tab,        a,        s,        d,        f,        g,
-sh2KCapL,        z,        x,        c,        v,        b, lpupo1l1,
+shL2kcap,        z,        x,        c,        v,        b, lpupo1l1,
     guiL,    grave,  bkslash,   arrowL,   arrowR,
                                                                ctrlL,     altL,
                                                        nop,      nop,     home,
@@ -87,7 +85,7 @@ sh2KCapL,        z,        x,        c,        v,        b, lpupo1l1,
            numPush,        6,        7,        8,        9,        0,     dash,
              brktL,        y,        u,        i,        o,        p,    brktR,
                            h,        j,        k,        l,  semicol,    quote,
-          lpupo1l1,        n,        m,    comma,   period,    slash, sh2KCapR,
+          lpupo1l1,        n,        m,    comma,   period,    slash, shR2kcap,
                                 arrowL,   arrowD,   arrowU,   arrowR,     guiR,
     altR,    ctrlR,
    pageU,      nop,      nop,
diff --git a/firmware/keyboard/ergodox/options.h b/firmware/keyboard/ergodox/options.h
index f5b57c4..fc06232 100644
--- a/firmware/keyboard/ergodox/options.h
+++ b/firmware/keyboard/ergodox/options.h
@@ -60,6 +60,14 @@
 // a multiplier, with '1' being max
 
 
+// ----------------------------------------------------------------------------
+// firmware/keyboard
+// ----------------------------------------------------------------------------
+
+#define  OPT__KB__ROWS     6
+#define  OPT__KB__COLUMNS  14
+
+
 // ----------------------------------------------------------------------------
 // firmware/lib/...
 // ----------------------------------------------------------------------------
diff --git a/firmware/lib/layout/layer-stack.h b/firmware/lib/layout/layer-stack.h
index 8039d77..43a4128 100644
--- a/firmware/lib/layout/layer-stack.h
+++ b/firmware/lib/layout/layer-stack.h
@@ -23,6 +23,7 @@
 uint8_t layer_stack__peek   (uint8_t offset);
 uint8_t layer_stack__push   (uint8_t layer_id, uint8_t layer_number);
 uint8_t layer_stack__pop_id (uint8_t layer_id);
+uint8_t layer_stack__size   (void);
 
 
 // ----------------------------------------------------------------------------
@@ -78,3 +79,11 @@ uint8_t layer_stack__pop_id (uint8_t layer_id);
  * - success: the offset of the element that was pushed (or pudated)
  */
 
+// === layer_stack__size ===
+/**                                     functions/layer_stack__size/description
+ * Return the current size (height) of the layer stack
+ *
+ * Returns:
+ * - success: the current size (height) of the layer stack (`0` if empty)
+ */
+
diff --git a/firmware/main.c b/firmware/main.c
index 8626cce..b234a7a 100644
--- a/firmware/main.c
+++ b/firmware/main.c
@@ -5,11 +5,11 @@
  * ------------------------------------------------------------------------- */
 
 /**                                                                 description
- * `main()`: tying it all together
+ * `main()`: tying it all together  // TODO
  */
 
 
-// TODO: includes
+#include "./main.h"
 
 // ----------------------------------------------------------------------------
 
@@ -26,7 +26,20 @@
 
 // ----------------------------------------------------------------------------
 
-// TODO: macros, if any
+#define  main__is_pressed   is_pressed
+#define  main__was_pressed  was_pressed
+#define  main__row          row
+#define  main__col          col
+
+// ----------------------------------------------------------------------------
+
+bool _pressed_1[OPT__KB__ROWS][OPT__KB__COLUMNS];
+bool _pressed_2[OPT__KB__ROWS][OPT__KB__COLUMNS];
+
+bool (* is_pressed) [OPT__KB__ROWS][OPT__KB__COLUMNS] = &_pressed_1;
+bool (* was_pressed) [OPT__KB__ROWS][OPT__KB__COLUMNS] = &_pressed_2;
+uint8_t row;
+uint8_t col;
 
 // ----------------------------------------------------------------------------
 
diff --git a/firmware/main.h b/firmware/main.h
new file mode 100644
index 0000000..ccd179a
--- /dev/null
+++ b/firmware/main.h
@@ -0,0 +1,57 @@
+/* ----------------------------------------------------------------------------
+ * Copyright (c) 2013 Ben Blazak <benblazak.dev@gmail.com>
+ * Released under The MIT License (see "doc/licenses/MIT.md")
+ * Project located at <https://github.com/benblazak/ergodox-firmware>
+ * ------------------------------------------------------------------------- */
+
+/**                                                                 description
+ * The `main()` interface for the rest of the program
+ *
+ * Prefix: `main__`
+ *
+ * Certain variables are declared here so that other functions can see (and
+ * perhaps modify) them, to accomplish things that may be difficult otherwise.
+ * If, for instance, a key-function needed to be called on every scan while
+ * they key was pressed instead of just on state-change: it could set its entry
+ * in `main__was_pressed` to `false` on every run.
+ */
+
+
+#ifndef ERGODOX_FIRMWARE__FIRMWARE__MAIN__H
+#define ERGODOX_FIRMWARE__FIRMWARE__MAIN__H
+// ----------------------------------------------------------------------------
+// ----------------------------------------------------------------------------
+
+
+#include <stdbool.h>
+#include <stdint.h>
+
+// ----------------------------------------------------------------------------
+
+/**                                      variables/main__is_pressed/description
+ * A matrix of `bool`s indicating whether the key at a given position is
+ * currently pressed
+ */
+extern bool (* main__is_pressed) [OPT__KB__ROWS][OPT__KB__COLUMNS];
+
+/**                                     variables/main__was_pressed/description
+ * A matrix of `bool`s indicating whether the key at a given position was
+ * pressed on the previous scan
+ */
+extern bool (* main__was_pressed) [OPT__KB__ROWS][OPT__KB__COLUMNS];
+
+/**                                             variables/main__row/description
+ * Indicates which row is currently being tested for changes of key state
+ */
+extern uint8_t main__row;
+
+/**                                             variables/main__col/description
+ * Indicates which column is currently being tested for changes of key state
+ */
+extern uint8_t main__col;
+
+
+// ----------------------------------------------------------------------------
+// ----------------------------------------------------------------------------
+#endif  // ERGODOX_FIRMWARE__FIRMWARE__MAIN__H
+