From 43f8799d4860b03c109b5918fc82bf619ba3d76b Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Wed, 18 Feb 2026 11:14:24 +0000
Subject: [PATCH] Add promotional introduction to README

Rewrites the top of README.md to lead with a compelling value proposition:
- Explains the "define once, validate everywhere" core benefit up front
- Lists key selling points (built-in validators, recursive types, caching, etc.)
- Shows a minimal but complete code snippet immediately

https://claude.ai/code/session_01AfxKyjrKBq9cT5698HAZxF
---
 README.md | 24 +++++++++++++++++++++++-
 1 file changed, 23 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 52ca361d..7092666f 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,28 @@
 # @nlib/typing
 
-A tool for generating and managing TypeScript type definitions efficiently.
+**TypeScript types that actually work at runtime.**
+
+Stop writing your types twice. `@nlib/typing` lets you define the shape of your data **once** — and use it for both compile-time type safety and runtime validation. No more keeping Zod schemas in sync with your interfaces. No more manual type guards that go stale.
+
+```typescript
+// Define once...
+const isUser = typeChecker({ id: isPositiveSafeInteger, name: isString });
+
+// ...use as a type guard
+if (isUser(data)) { /* data is User here */ }
+
+// ...use for safe API responses
+const user = ensure(await response.json(), isUser); // throws with a clear message if invalid
+```
+
+**Why @nlib/typing?**
+
+- **Single source of truth** — One definition drives both TypeScript types and runtime checks
+- **Rich built-in validators** — Email addresses, UUIDs, IPv4/IPv6, HTTP methods, Base64, URLs, and more — all with branded types for extra compile-time safety
+- **Recursive types** — Model trees and self-referencing structures with a simple getter pattern
+- **Works everywhere** — Node.js, Deno, and browsers (via esm.sh CDN)
+- **Zero runtime overhead** — Results are cached via `WeakMap`; the same definition always returns the same checker instance
+- **Descriptive errors** — `ensure()` throws with the exact property path that failed validation
 
 [![NPM Version](https://img.shields.io/npm/v/%40nlib%2Ftyping)](https://www.npmjs.com/package/@nlib/typing)
 [![JSR](https://jsr.io/badges/@nlib/typing)](https://jsr.io/@nlib/typing)