diff --git a/src/surplus/README.md b/src/surplus/README.md
new file mode 100644
index 0000000..28dccc8
--- /dev/null
+++ b/src/surplus/README.md
@@ -0,0 +1,8 @@
+# surplus
+
+surplus (s+) is a Python script to convert [Google Maps Plus Codes](https://maps.google.com/pluscodes/)
+to iOS Shortcuts-like shareable text
+
+see <https://surplus.joshwel.co/>
+or [/docs/index.md](../../docs/index.md)
+for more information and documentation