diff --git a/README.md b/README.md
index 49e8762..f466eda 100644
--- a/README.md
+++ b/README.md
@@ -4,7 +4,7 @@
[](https://opensource.org/licenses/MIT)
[](https://github.com/eugenioenko/kasper-js/actions)
-A lightweight component framework with fine-grained Signal-based reactivity. No virtual DOM. No magic compiler. Just components, signals, and surgical DOM updates.
+A signal, a class, and an HTML template. That's all you need, whether you're writing the code yourself or working with an AI agent.
- **[Documentation](https://kasperjs.top)**
- **[Live Demos](https://stackblitz.com/github/eugenioenko/kasper-js/tree/main/demos)**
@@ -14,18 +14,49 @@ A lightweight component framework with fine-grained Signal-based reactivity. No
## Why Kasper.js
-Fine-grained signals are not new — SolidJS pioneered direct signal-to-DOM binding, Angular adopted signals in v17, and Vue's Composition API moves in the same direction. The signal primitive itself is a solved problem.
+Kasper exists because building reactive UIs shouldn't require understanding a compiler, a scheduler, a virtual DOM reconciler, and a hook dependency system.
-Kasper's position is different: it is a complete, self-contained framework — components, router, slots, lifecycle, expression evaluator, template parser — in under 4000 lines of TypeScript with zero runtime dependencies. No virtual DOM, no scheduler, no compiler that requires a dedicated language server. The entire dependency graph at runtime is the framework itself.
+**No build step required.** Drop a 16KB script tag and you have a complete reactive component framework — signals, router, slots, lazy loading, the works. The only thing a build pipeline adds is the `.kasper` single-file component format, which needs the Vite plugin to transform. Everything else runs directly in the browser.
-The design constraints are deliberate. Directives are valid HTML attributes, so templates parse as plain HTML without editor plugins or custom syntax highlighting. The expression evaluator is a custom recursive-descent parser — not `eval`, not `new Function`, not a third-party AST library — supporting arrow functions, optional chaining, nullish coalescing, pipeline operator, and spread without pulling in a single parse dependency. Each `{{expression}}`, `@if`, and `@each` binding registers its own effect directly against the DOM node it controls. When a signal changes, only that node is updated — no component re-render, no diffing pass, no scheduler queue.
+**Templates that read like HTML.** Kasper directives are standard HTML attributes: `@if`, `@each`, `@on:click`. Write `@if` where you'd write `if`, `@each` where you'd write a loop. Any template is readable by anyone who knows HTML, with no framework knowledge required. The expression evaluator is a custom recursive-descent parser, not `eval` and not `new Function`, so it works under strict Content Security Policies too.
-The result is a framework you can read in an afternoon, understand completely, and trust in production. It is not trying to replace React or Angular for large teams with complex tooling requirements. It is for projects where the right answer is fewer moving parts.
+**Components that clean up after themselves.** A component is a class. `this.watch()`, `this.effect()`, and `this.computed()` are all released automatically when the component is destroyed, via a single `AbortController` the class owns. No dependency arrays. No `return () => unsubscribe()`. No stale closure warnings. The component lifecycle is the class lifecycle.
+
+Under 4000 lines of TypeScript. 95% test coverage. Zero runtime dependencies. Built to stay that way.
---
## Quick Start
+**Option 1: Script tag, no build step.**
+
+```html
+
+
+
+
+
+
+
+```
+
+**Option 2: Vite project with single-file components.**
+
```bash
npm create kasper-app@latest my-project
cd my-project
@@ -37,6 +68,8 @@ npm run dev
## What it looks like
+With the Vite plugin, using single-file components:
+
```html
@@ -81,18 +114,19 @@ App({
## Features
+- **No build step** — runs from a CDN import or a local dist file. Signals, router, slots, and lazy loading all work without a bundler. The only thing a build adds is the `.kasper` single-file component format.
+- **HTML-first templates** — directives are standard HTML attributes: `@if`, `@elseif`, `@else`, `@each`, `@let`, `@on:event`, `@attr`, `@class`, `@style`, `@ref`. Structural directives use DOM boundaries — lightweight comment-node bookmarks that surgically replace only their own content when dependencies change.
+- **Automatic cleanup** — components are classes. `this.watch()`, `this.effect()`, and `this.computed()` are all released automatically when the component is destroyed via a shared `AbortController`. No dependency arrays, no manual unsubscribe.
- **Fine-grained signals** — `signal()`, `computed()`, `effect()`, `batch()`, `peek()`. Reactivity is tracked at the binding level, not the component level. When a signal changes, Kasper updates only the specific DOM text nodes, attributes, and structural boundaries that depend on it. Siblings, parent elements, and unrelated components are untouched.
-- **Single-file components** — ``, `
+
+