From 27cd98d60cdace436c44aac363b36e798eecd1b9 Mon Sep 17 00:00:00 2001
From: kjg <kimjg2477@gmail.com>
Date: Tue, 17 Mar 2026 16:20:29 +0900
Subject: [PATCH] =?UTF-8?q?docs:=20simplify=20README=20=E2=80=94=20remove?=
 =?UTF-8?q?=20advanced=20patterns,=20fix=20Kotlin=20examples?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Remove Usage Patterns section (mapError, recover, Validated zip) — advanced patterns belong in docs/
- Remove Violation internal structure description from API section
- Fix Kotlin Support: split duplicate val age into separate code blocks
- Move Installation before Quick Start for natural flow
- Add Docs section with links to type-matrix, compatibility, kotlin-support-policy
- Deduplicate ofOrElse between Quick Start and Usage Patterns
---
 README.md | 87 ++++++++++++++++++++++---------------------------------
 1 file changed, 34 insertions(+), 53 deletions(-)

diff --git a/README.md b/README.md
index 8ec89fd..391139d 100644
--- a/README.md
+++ b/README.md
@@ -35,24 +35,6 @@ public void createUser(NonBlankString name, PositiveInt age, NonEmptyList<String
 
 Types replace scattered `if`-checks. Invalid data cannot even reach your method.
 
-## Quick Start
-
-```java
-// Trusted data — just unwrap
-PositiveInt confirmedAge = PositiveInt.unsafeOf(18);
-
-// Untrusted input — safe fallback
-PositiveInt safeAge = PositiveInt.ofOrElse(userInput, 1);
-```
-
-```java
-// Branch on success/failure
-EmailString.of(email).fold(
-    error -> badRequest(error.message()),
-    valid -> ok(register(valid))
-);
-```
-
 ## Installation
 
 > *"I can just implement this myself. Why add a dependency?"*
@@ -83,6 +65,24 @@ dependencies {
 </dependency>
 ```
 
+## Quick Start
+
+```java
+// Trusted data — just unwrap
+PositiveInt confirmedAge = PositiveInt.unsafeOf(18);
+
+// Untrusted input — safe fallback
+PositiveInt safeAge = PositiveInt.ofOrElse(userInput, 1);
+```
+
+```java
+// Branch on success/failure
+EmailString.of(email).fold(
+    error -> badRequest(error.message()),
+    valid -> ok(register(valid))
+);
+```
+
 ## Kotlin Support
 
 Optional module with Kotlin-idiomatic extensions:
@@ -90,46 +90,23 @@ Optional module with Kotlin-idiomatic extensions:
 ```kotlin
 import io.github.junggikim.refined.kotlin.*
 
-// Scalar extensions
 val name = "Ada".toNonBlankStringOrThrow()
 val tags = listOf("java", "fp").toNonEmptyListOrThrow()
-
-// Validation extensions
-val age = PositiveInt.ofOrElse(input, 1)
-val age = PositiveInt.of(input).getOrNull() ?: PositiveInt.unsafeOf(1)
-val result: Result<PositiveInt> = PositiveInt.of(input).toResult()
-```
-
-## Usage Patterns
-
-```java
-// validate and get — most common
-PositiveInt age = PositiveInt.ofOrElse(input, 1);
 ```
 
-```java
-// to Optional
-Optional<PositiveInt> maybeAge = PositiveInt.of(input).toOptional();
-```
-
-```java
-// transform error type
-Validation<String, PositiveInt> mapped = PositiveInt.of(input)
-    .mapError(Violation::message);
+```kotlin
+// Safe fallback
+val safeAge = PositiveInt.ofOrElse(input, 1)
 ```
 
-```java
-// recover from error
-Validation<Violation, PositiveInt> recovered = PositiveInt.of(input)
-    .recover(err -> PositiveInt.unsafeOf(1));
+```kotlin
+// Kotlin-idiomatic nullable
+val age = PositiveInt.of(input).getOrNull() ?: PositiveInt.unsafeOf(1)
 ```
 
-```java
-// error-accumulating (multiple fields at once)
-Validated<String, Integer> left = Validated.invalid(Arrays.asList("age"));
-Validated<String, Integer> right = Validated.invalid(Arrays.asList("name"));
-List<String> errors = left.zip(right, Integer::sum).getErrors();
-// errors = ["age", "name"]
+```kotlin
+// Convert to kotlin.Result
+val result: Result<PositiveInt> = PositiveInt.of(input).toResult()
 ```
 
 ## API
@@ -143,8 +120,6 @@ All refined wrappers follow the same pattern:
 
 Collection refined types implement JDK interfaces directly — `NonEmptyList<T>` is a `List<T>`, `NonEmptyMap<K,V>` is a `Map<K,V>`. No unwrapping needed.
 
-`Violation` carries a stable `code`, human-readable `message`, and immutable `metadata` map.
-
 ## Supported Types
 
 | Category | Examples | Count |
@@ -158,9 +133,15 @@ Collection refined types implement JDK interfaces directly — `NonEmptyList<T>`
 
 Full list: [docs/type-matrix.md](docs/type-matrix.md)
 
+## Docs
+
+- [Type Matrix](docs/type-matrix.md)
+- [Compatibility](docs/compatibility.md)
+- [Kotlin Support Policy](docs/kotlin-support-policy.md)
+
 ## Contributing
 
-[CONTRIBUTING.md](CONTRIBUTING.md) · [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) · [SECURITY.md](SECURITY.md) · [docs/compatibility.md](docs/compatibility.md) · [docs/kotlin-support-policy.md](docs/kotlin-support-policy.md)
+[CONTRIBUTING.md](CONTRIBUTING.md) · [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) · [SECURITY.md](SECURITY.md)
 
 ## License