add docs on hooks/actions

Signed-off-by: shmck <shawn.j.mckay@gmail.com>

docs/docs/how-it-works.md

@@ -4,9 +4,19 @@ title: How CodeRoad Works
 sidebar_label: How CodeRoad Works
 ---
 
-### Running Tests
+There are really a few major pieces to understand how CodeRoad works.
 
-In CodeRoad, the user is given a set of directions for a **task**.
+1. [How Tests Work](#how-tests-work)
+
+2. [How CodeRoad is Built on Git](#built-on-git)
+
+3. [How CodeRoad Hooks & Actions work](#how-hooks-and-actions-work)
+
+### How Tests Work
+
+In CodeRoad, the user is given a set of **levels** composed of one more **tasks**.
+
+![Level / Task Flow](../images/level-task-flow.png)
 
 Each task is judged to pass (✔) or fail (✘) by the result of code tests that runs in the background. Tests can be triggered by saving a file, or by a trigger that listens to specific files for changes.
 
@@ -50,8 +60,29 @@ Git provides a number of benefits:
 
 #### Reset
 
-If at some point the user is a bit too “off-road” of the solution, they call always return to the “golden path” by pressing the "reset" button. The reset button reloads the commits up to that point entirely from the tutorial.
+If at some point the user is a bit too “off-road” from the solution, the user can always return to the “golden path” by pressing the **reset** button. The reset button reloads the commits up to that point entirely from the tutorial.
 
 ![Tutorial commits reset example](../images/tutorial-commits-reset.png)
 
 In the example above you can see the user is “reset” back to the original tutorial answers, and back to the second task.
+
+### How Hooks and Actions Work
+
+To make a functional tutorial, tutorial creators need a bit more control over what can be run and when. For example, a test runner wouldn't really work if the package dependencies for that test runner weren't installed.
+
+An **action** is a piece of functionality that can be run. These include:
+
+- `commands` - a list of cli commands to run. For example, "npm install"
+- `vscodeCommands` - a list of vscode API commands to run. For example, "setLayout" to change the layout of windows
+- `watchers` - a list of files to listen to. If a file changes, the test runner will run automatically
+- `files` - a list of files to open in the users workspace to drive the users attention.
+- `subtasks` - a task made up of multiple other tests where all must pass to continue
+- `filter` - a regex passed into the test runner to limit the tests returned
+
+A **hook** in CodeRoad is a place where a tutorial creator can tap in to run an action. Hooks include:
+
+- `config.setup` - when the tutorial setup. This is a great place to setup your test runner.
+- `task.setup` - when a task is started
+- `task.solution` - when a solution is loaded from a [reset](#reset)
+
+Hooks and actions combined provide a flexible environment for tutorial development.