diff --git a/README.md b/README.md
new file mode 100644
index 0000000..2fffdef
--- /dev/null
+++ b/README.md
@@ -0,0 +1,38 @@
+> **>>> TL;DR:** Simple Astro integration to use your own authored service-worker; by default, devs retain full control as opposed to getting generated sw code
+
+# Astro SW
+
+The integration `serviceWorker` accepts configuration with service worker path and automatically injects needed dynamic variables such as `assets` generated by Astro for caching
+
+## Usage
+
+Example `astro.config.mjs`
+
+```js
+import { defineConfig } from "astro/config";
+import node from "@astrojs/node";
+import serviceWorker from "@ayco/astro-sw";
+
+export default defineConfig({
+  output: "server",
+  adapter: node({
+    mode: "middleware"
+  }),
+  integrations: [
+    serviceWorker({
+      path: "./src/sw.js",
+      assetCachePrefix: 'cozy-reader',
+    })
+  ]
+});
+```
+
+## API
+
+The integration accepts a configuration object of type `ServiceWorkerConfig` with the following properties
+
+| property | type | required? |  notes |
+| --- | --- | --- | --- |
+| path | string | required | path to your *own* service worker script; no surprises & easy debugging |
+| assetCachePrefix | string | optional | cache storage name prefix; useful for debugging & invalidation |
+| assetCacheVersionID | string | optional | cache storage name versioning; by default, a random UUID is used but you can provide your own for easy debugging |
\ No newline at end of file
diff --git a/example_sw.js b/example_sw.js
index 7cd06cd..63f4ca7 100644
--- a/example_sw.js
+++ b/example_sw.js
@@ -1,6 +1,6 @@
 /**
  * Note: @ayco/astro-sw integration injects variables `__prefix`, `__version`, & `__assets`
- * -- find usage in `astro.config.mjs` integrations
+ * -- find usage in package readme; `astro.config.mjs` integrations
  * @see https://ayco.io/n/@ayco/astro-sw
  */
 const cacheName = `${__prefix ?? 'app'}-v${__version ?? '000'}`