documentation/specification.md

@@ -83,7 +83,47 @@ $ histui tui [options]
 +-------------------+
 ```
 
-#### Input
+### Modes
++ the reason why we have modes is to make both
+inspecting and selection entries,
+and searching/filtering entries piss easy
+
+##### Normal mode
+The user may move up and down freely on the list
+with any prefered binding (Vimlike by default),
+or repeat a motion by specifying a repeat count
+before any motion.
+
+**\[repeat\]\<motion\>**
+
+move around
+
+
+**:<int>**
+
+Jump to Nth entry.
+
+#### Result stack
+Everytime the user issues a search,
+or inspects an item
+the result stack is pushed.
+
+The top search frame can/will be
+overwritten.
+
+The user may pop or clear by hand.
+
+The result stack is NOT persistent between sessions.
+
+#### Command mode
+Every character entered narrows the list of results.
+The user may use altered {ctrl+n} or special {arrow} keys
+to navigate the results,
+but may be unable to issue repeats or jumps.
+
+#### Global input
+Do note that these actions may have
+different bindings in different modes.
 
 **<inspect>**
 
@@ -106,35 +146,23 @@ Pop result frame.
 
 Echo entry value and exit with success.
 
-### Result stack
-Everytime the user issues a search,
-or inspects an item
-the result stack is pushed.
-
-The top search frame can/will be
-overwritten.
-
-The user may pop or clear by hand.
-
-The result stack is NOT persistent between sessions.
-
 ## Format
 
 ```
 %[flags][width]<specifier>
 ```
 
-#### Flags
+#### flags
 
 ```
 -   : left-justify within [width]
-#  : relative (has effect on time specifiers)
+\#  : relative (has effect on time specifiers)
 ```
 
-#### Width
+#### width
 + number of characters to align to
 
-#### Specifiers
+#### specifiers
 These specifiers root mainly from the C stdlib.
 
 ```
@@ -160,14 +188,3 @@ T   : ISO 8601 time format ("HH:MM:SS")
 
 # Environment
 HISTUIFILE  : histuidb to be used
-
-
-+---+---------------+
-| p | ssh nigger    |
-| o | ssh hot@nigger|
-| s | ssh nigger1   |
-+---+---------------+
-|       ruler       |
-+-------------------+
-| ssh nigger        |
-+-------------------+