diff --git a/README.md b/README.md
index b06ed37..092ccd5 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,57 @@
 # Impulse
 
-A JavaScript framework that leverages the Web Components API.
+A lightweight JavaScript framework that leverages the Web Components API. Unlike traditional frameworks, Impulse doesn't
+dictate how you render HTML. Instead, it's designed to augment your existing HTML with just the right amount of
+JavaScript to make it interactive and reactive.
+
+Write your HTML however you like, and let Impulse handle the behavior.
+
+## Installation
+
+```bash
+yarn add @ambiki/impulse
+```
+
+## Example: Simple counter
+
+```ts
+import { ImpulseElement, property, registerElement, target } from '@ambiki/impulse';
+
+@registerElement('counter-element')
+export default class CounterElement extends ImpulseElement {
+  @property({ type: Number }) count = 0;
+  @target() output: HTMLElement;
+
+  countChanged(newValue: number) {
+    this.output.textContent = String(newValue);
+  }
+
+  decrement() {
+    this.count--;
+  }
+
+  increment() {
+    this.count++;
+  }
+}
+```
+
+HTML:
+
+```html
+<counter-element count="0">
+  <h2>Count: <span data-target="counter-element.output">0</span></h2>
+  <button data-action="click->counter-element#decrement">-</button>
+  <button data-action="click->counter-element#increment">+</button>
+</counter-element>
+```
+
+The counter automatically syncs the `count` attribute with the component property, calling `countChanged()` whenever it
+updates. No virtual DOM, no JSX - just progressive enhancement of your HTML.
+
+## Learn more
+
+Check out the [full documentation](https://ambiki.github.io/impulse/) to explore more.
 
 ## License
 
diff --git a/packages/core/package.json b/packages/core/package.json
index 9cf13de..0cdaedd 100644
--- a/packages/core/package.json
+++ b/packages/core/package.json
@@ -32,7 +32,8 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "README.md"
   ],
   "keywords": [
     "web-components"
@@ -41,7 +42,7 @@
     "build": "rollup --config rollup.config.js",
     "build:watch": "rollup --config rollup.config.js --watch",
     "clean": "rm -fr dist",
-    "prepublishOnly": "yarn clean && yarn build",
+    "prepublishOnly": "cp ../../README.md . && yarn clean && yarn build",
     "test": "web-test-runner",
     "test:watch": "web-test-runner --watch"
   },