feat(readme): First update to the readme

README.md

@@ -1,6 +1,7 @@
 # WARNING
-This is still beta.  We are getting there, but its not as fast as I would like.
-Therefore APIs are subject to change.
+This is not fully baked, though used by several people.  If you experience any
+issues, see some improvement you think would be amazing, or just have some
+feedback for harpoon (or me), make a ticket!
 
 ![Harpoon](harpoon.png)
 -- Image provided by Liberty_DevCap
@@ -14,9 +15,16 @@ yourself frequenting a small set of files (maybe it depends on task) and you
 are tired of using a fuzzy finder, :bnext/prev, alternate file doesn't quite
 cut it, etc etc.
 
+## The Other Problem
+You want to execute some project specific commands or have any number of
+persistent terminals that can be easily navigated to.
+
 ## The Solution
 The ability to specify, or on the fly, mark and create persisting key strokes
-to go to the files you want.  This includes terminal navigation.
+to go to the files you want.
+
+## The Other Solution
+Unlimited terminals and navigation.
 
 ## Installation
 Simply install via your favorite plugin manager.
@@ -26,12 +34,138 @@ Plug 'ThePrimeagen/harpoon'
 ```
 
 ## Harpooning
-TO BE DETERMINED
+There are two modes of harpoon.  File navigation and terminal navigation.
+Setup of harpoon configuration is at the bottom since its for more advanced use
+cases.
 
+### File Navigation
+#### Mark a file
+Marking a file is similar to vim global marks, but differ in a few key ways.
 
-Check out
+* They auto update their position
+* They are unique _per project_.
+* They can be hand edited vs replaced (swapping is easier)
+
+To mark a file simply call the following lua function
 
 ```lua
-// TODO: Fill this also in you pleb
+:lua require("harpoon.mark").add_file()
 ```
 
+This will mark the file and add it to the end of the mark list.
+
+#### Navigate to file
+To navigate to any of the marked files simply call the navigation function with
+which index.
+
+```lua
+:lua require("harpoon.ui").nav_file(3) -- This will navigate to file 3
+```
+
+#### Manipulating current marks
+There is a quick menu that will allow for you to edit your marks.  You can hand
+edit the name, its position within the list, or remove it from the list.  To
+bring up the quick list execute the following lua command.
+
+```lua
+:lua require("harpoon.ui").toggle_quick_menu()
+```
+
+You can simply edit this list as if it were a document in vim.  `:wq` to save
+the new edits or `:q` to ignore the edits.  There is to save upon call to
+toggle if you prefer that way.
+
+### Terminal Navigation
+#### Motivation for terminals in neovim
+I want to use the terminal since I can gF and <c-w>gF to any errors arising
+from execution that are within the terminal that are not appropriate for
+something like dispatch. (not just running tests but perhaps a server that runs
+for X amount of time before crashing).
+
+I want the terminal to be persistent and I can return to one of many terminals
+with some finger wizardry and reparse any of the execution information that was
+not necessarily error related.
+
+I would like to have commands that can be tied to terminals and sent them
+without much thinking. Some sort of middle ground between vim-test and just
+typing them into a terminal (configuring netflix's television project isn't
+quite building and there are tons of ways to configure).
+
+#### Navigating to a terminal
+To navigate to a terminal simply provide an index and it will go.  If there is
+no terminal in that index or the terminal has been closed by some means,
+harpoon will create a new terminal at that location.
+
+```lua
+lua require("harpoon.term").gotoTerminal(1)
+```
+
+You can provide as high of a number as you would like.  There  is no terminal
+count limitation though I personally find anything beyond two oft confusing.
+
+#### Commands to terminal
+Sometimes you wish to send commands to terminals that have been preconfigured
+for a project.  To make this work properly you must predefine a command or hard
+code it as part of the send process.
+
+```lua
+" This will send to terminal 1 either the predefined command 1 in the terminal
+" config or "ls -la"
+lua require("harpoon.term").sendCommand(1, 1)
+lua require("harpoon.term").sendCommand(1, "ls -la")
+```
+
+### Setup
+Setup should be called once.
+
+#### TODO: Make this callable more than once and just layer in the commands
+Yes... A todo in a readme.  Deal with it.
+
+#### The Configuration File
+You can configure harpoon via lua in your rc.  Here is a simple example that
+will add a specific command to a project.
+
+##### Global Settings
+
+```lua
+Here is the set of global settings and their default values.
+
+require("harpoon").setup({
+    global_settings = {
+        save_on_toggle = false
+    },
+    ... your other configs ...
+})
+```
+
+#### Preconfigured Terminal Commands
+These are project specific commands that you wish to execute on the regular.
+
+```lua
+require("harpoon").setup({
+    projects = {
+        -- Yes $HOME works
+        ["$HOME/personal/vim-with-me/server"] = {
+            term = {
+                cmds = {
+                    "./env && npx ts-node src/index.ts"
+                }
+            }
+        },
+
+        -- This uses the wildcard api, you can check it out via branch wildcards
+        -- not quite ready yet for mainline.
+        -- Wildcards are to be used in conjunction with git worktrees (at least
+        -- that is my goal)
+        ["/home/theprimeagen/personal/harpoon/{}"] = {
+            term = {
+                cmds = {
+                    "echo hello {}"
+                }
+            },
+        },
+
+```
+
+
+