diff --git a/README.md b/README.md
new file mode 100644
index 0000000..a08bec2
--- /dev/null
+++ b/README.md
@@ -0,0 +1,55 @@
+# aoc-2022
+
+don't look in `src/bin/day_*.rs` if you don't want spoilers.
+
+yes some of this setup is needlessly overengineered
+
+## magic rust macros (tm)
+
+yes
+
+i thought teehee i could make a proc macro for this
+
+## using this
+
+just don't
+
+### ok alright
+
+Make a solution for a day:
+
+```rust
+// Some useful things, including macros + color_eyre
+use aoc_2022::prelude::*;
+
+type Input = String; // some mildly useful structure for the input data
+
+fn parse(s: &str) -> Result<Input> {
+    // implement whatever scary string manipulation you like
+    Ok(s.to_owned())
+}
+
+ // heres some macro magic ✨
+#[aoc(
+    day = 100, // used to fetch the challenge stuff from AOC directly
+    parse = parse, // so I can reuse parsers if needed
+    test_cases = ["day_100.txt"] // loaded from `test_cases/`
+)]
+fn day_100(mut input: Input) -> Result<()> {
+    // do something remotely awful to solve the challenge
+
+    // probably should println!() the results or something
+
+    Ok(())
+}
+
+// macro: a wild main function appears!
+```
+
+### auto-fetching
+
+steal your session cookie from the browser devtools
+
+make `.env` and add `AOC_SESSION=<your massive long session token>`
+
+maybe use direnv to make it easier to load the `.env` file? (and the nix flake (yes theres one of those too uwu))