add claude skills

.claude/skills/native-monad-result/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: native-monad-result
+description: "Result<T,E> API reference. ALWAYS invoke when using Ok, Err, Result, ResultPromise, Result.from, Result.all, Result.partition, result.map, result.flatMap, result.match(2 args), result.filter(needs errorFactory). Do not guess Result methods — consult this skill."
+---
+
+# Result<T, E> Usage Guide
+
+## Quick Reference
+
+| Method                       | Signature (on Ok)            | Signature (on Err)            |
+|------------------------------|------------------------------|-------------------------------|
+| `isOk()`                     | `this is Ok<T>`              | `this is never`               |
+| `isErr()`                    | `this is never`              | `this is Err<E>`              |
+| `map(fn)`                    | `(fn: (v: T) => U) => Ok<U>` | `() => Err<E>`                |
+| `mapErr(fn)`                 | `(fn: (e: E) => F) => Ok<T>` | `(fn: (e: E) => F) => Err<F>` |
+| `flatMap(fn)`                | `(fn: (v: T) => R) => R`     | `() => this`                  |
+| `flatMapErr(fn)`             | `() => this`                 | `(fn: (e: E) => R) => R`      |
+| `match(onOk, onErr)`         | 2 callbacks                  | 2 callbacks                   |
+| `filter(pred, errorFactory)` | requires `errorFactory`      | `() => Err<E>`                |
+| `toNullable()`               | `T`                          | `null`                        |
+| `toUndefined()`              | `T`                          | `undefined`                   |
+| `toString()`                 | `string`                     | `string`                      |
+
+## Critical Rules
+
+1. `match()` takes exactly **2 callbacks**: `(onOk, onErr)`.
+2. `filter()` REQUIRES an `errorFactory` parameter — it produces `Err<F>` when the predicate fails.
+3. `flatMap` constraint: `R extends Result<any, any>` — the callback must return a Result.
+4. `flatMapErr` constraint: `R extends Result<any, any>` — the callback must return a Result.
+5. Type guard: after `isOk()`, access `.value`. After `isErr()`, access `.err`.
+6. `Ok` stores `.value`. `Err` stores `.err` (not `.error`, not `.value`).
+
+## Anti-Patterns
+
+```typescript
+// WRONG — filter without errorFactory
+result.filter((v) => v > 0);
+
+// CORRECT — filter always needs errorFactory
+result.filter((v) => v > 0, (v) => new Error(`Invalid: ${v}`));
+```
+
+```typescript
+// WRONG — match with 3 callbacks (that's Query, not Result)
+result.match(onOk, onNone, onErr);
+
+// CORRECT — Result.match takes exactly 2
+result.match(onOk, onErr);
+```
+
+## Namespace & Async Methods
+
+Read `references/api-surface.md` for the complete Result namespace (`.from`, `.all`, `.partition`, `.compact`, `.some`,
+`.every`) and ResultPromise namespace.

.claude/skills/native-monad-result/references/api-surface.md

@@ -0,0 +1,98 @@
+# Result API Surface
+
+These are ALL available methods for Result. Do not use any method not listed here.
+
+## Types
+
+```typescript
+type Result<T, E> = Ok<T> | Err<E>
+type ResultPromise<T, E> = Promise<Result<T, E>>
+type OkPromise<T> = Promise<Ok<T>>
+type ErrPromise<E> = Promise<Err<E>>
+type ResultPartitionResult<T, E> = { values: T[]; errors: E[] }
+```
+
+## Factory Functions
+
+```typescript
+function ok<T>(value: T): Ok<T>
+function err<E>(error: E): Err<E>
+```
+
+## Ok<T> Instance Methods
+
+```typescript
+class Ok<T> {
+  readonly value: T
+
+  isOk(): this is Ok<T>
+  isErr(): this is never
+
+  map<U>(fn: (value: T) => U): Ok<U>
+  mapErr<F>(fn: (error: never) => F): Ok<T>
+
+  flatMap<R extends Result<any, any>>(fn: (value: T) => R): R
+  flatMapErr(): this
+
+  match<U>(onOk: (value: T) => U, onErr: (error: never) => U): U
+
+  // Overload 1: type-narrowing predicate
+  filter<U extends T, F>(predicate: (value: T) => value is U, errorFactory: (value: T) => F): Ok<U> | Err<F>
+  // Overload 2: boolean predicate
+  filter<F>(predicate: (value: T) => boolean, errorFactory: (value: T) => F): Ok<T> | Err<F>
+
+  toNullable(): T
+  toUndefined(): T
+  toString(): string
+}
+```
+
+## Err<E> Instance Methods
+
+```typescript
+class Err<E> {
+  readonly err: E
+
+  isOk(): this is never
+  isErr(): this is Err<E>
+
+  map<U>(): Err<E>
+  mapErr<F>(fn: (error: E) => F): Err<F>
+
+  flatMap(): this
+  flatMapErr<R extends Result<any, any>>(fn: (error: E) => R): R
+
+  match<U>(onOk: (value: never) => U, onErr: (error: E) => U): U
+
+  filter(): Err<E>
+
+  toNullable(): null
+  toUndefined(): undefined
+  toString(): string
+}
+```
+
+## Result Namespace (Static Methods)
+
+```typescript
+Result.from<T, E = unknown>(fn: () => T, errorMap?: (error: unknown) => E): Result<T, E>
+Result.isResult<T, E>(value: unknown): value is Result<T, E>
+Result.all<T>(results: Ok<T>[]): Ok<T[]>
+Result.all<T, E>(results: Result<T, E>[]): Result<T[], E>
+Result.partition<T, E>(results: Result<T, E>[]): ResultPartitionResult<T, E>
+Result.compact<T, E>(results: Result<T, E>[]): T[]
+Result.some<T, E>(results: Result<T, E>[]): boolean
+Result.every<T, E>(results: Result<T, E>[]): boolean
+```
+
+## ResultPromise Namespace (Async Methods)
+
+```typescript
+ResultPromise.from<T, E = unknown>(fn: () => Promise<T>, errorMap?: (error: unknown) => E): ResultPromise<T, E>
+ResultPromise.all<T>(promises: Promise<Ok<T>>[]): Promise<Ok<T[]>>
+ResultPromise.all<T, E>(promises: Promise<Result<T, E>>[]): Promise<Result<T[], E>>
+ResultPromise.partition<T, E>(promises: Promise<Result<T, E>>[]): Promise<ResultPartitionResult<T, E>>
+ResultPromise.compact<T, E>(promises: Promise<Result<T, E>>[]): Promise<T[]>
+ResultPromise.some<T, E>(promises: Promise<Result<T, E>>[]): Promise<boolean>
+ResultPromise.every<T, E>(promises: Promise<Result<T, E>>[]): Promise<boolean>
+```