diff --git a/Code Exercise.pdf b/Code Exercise.pdf
new file mode 100644
index 0000000..d19cb3c
Binary files /dev/null and b/Code Exercise.pdf differ
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..24cf33c
--- /dev/null
+++ b/README.md
@@ -0,0 +1,65 @@
+# Genius Deck
+
+## Specification
+
+A simple web API that manages an in-memory deck of cards.
+
+On starting the API, or after sorting, the default sort order from top to bottom is:
+```
+Suits: Spades > Hearts > Clubs > Diamonds
+Face Values: 2 > 10 > Jack > Queen > King > Ace
+```
+Two of Spades is on top, Ace of Diamonds is at the bottom.
+
+Source code location where the routes are defined: [here](https://git.fosscat.com/n8r/genius_deck/src/commit/653b309825d2f3d9687126536c70a9124fceaf3b/src/main.zig#L67)
+
+Permitted operations are as follows:
+
+### GET `/deal`
+Takes the top card off the deck and returns it as json
+
+### GET `/cheat`
+Peaks at the top card of the deck and returns it as json
+
+### POST `/discard`
+Discards a card previously dealt
+Expects data in json in the form 
+```json
+{
+  "face_value": "Seven",
+  "suite": "Spades"
+}
+```
+
+### POST `/cut`
+Cuts the deck at the index provided, either as query params (`/cut?index=10`) or json
+```json
+{
+  "index": 10
+}
+```
+
+### POST `/rebuild`
+Puts the discard pile back into the deck and sorts the resulting deck
+
+### POST `/sort`
+Orders the deck in the default sort order (see [Specification](#Specification))
+
+### POST `/shuffle`
+Shuffles the current deck of cards in random order
+
+## Running
+
+You can navigate to the releases to download a prebuilt binary for your platform, or you can run it locally
+yourself with Zig.
+
+You will need to download Zig 0.13.0 from Zig's [releases page](https://ziglang.org/download/), or from your
+package manager. If you use Nix flakes, a working config with direnv is already present in the repository.
+
+### Deck Method Tests
+
+The tests can be run with Zig by running the following command in the root of the project:
+
+```sh
+zig test src/deck.zig
+```