1 files changed, 42 insertions, 0 deletions
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..b27ef08
--- /dev/null
+++ b/README.md
@@ -0,0 +1,42 @@
+# snowflake
+
+Generate random, URL-safe identifiers in Go.
+
+Each ID is 16 bytes of cryptographically secure randomness, encoded as a base62 string.
+
+## install
+
+```bash
+go get git.ethanwerner.com/snowflake
+```
+
+## usage
+
+```go
+package main
+
+import (
+    "fmt"
+
+    "git.ethanwerner.com/snowflake"
+)
+
+func main() {
+    id, _ := snowflake.New()
+    fmt.Println(id)       // e.g. "7Kx9mQ2pL4nR8wYv"
+    fmt.Println(id.Hex()) // e.g. "a1b2c3..."
+
+    parsed, _ := snowflake.FromString(id.String())
+}
+```
+
+## features
+
+- Cryptographically secure random IDs
+- Base62 and hex encoding/decoding
+- `encoding.TextMarshaler` / `json.Marshaler` support
+- `database/sql.Scanner` / `driver.Valuer` support
+
+## license
+
+MIT