add claude skills

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

@@ -0,0 +1,60 @@
+---
+name: native-monad-option
+description: "Option<T> API reference. ALWAYS invoke when using Some, None, Option, OptionPromise, Option.from, Option.all, Option.partition, option.map, option.flatMap, option.match(2 args), option.filter(NO errorFactory). Do not guess Option methods — consult this skill."
+---
+
+# Option<T> Usage Guide
+
+## Quick Reference
+
+| Method                  | Signature (on Some)            | Signature (on None) |
+|-------------------------|--------------------------------|---------------------|
+| `isSome()`              | `this is Some<T>`              | `this is never`     |
+| `isNone()`              | `this is never`                | `this is None`      |
+| `map(fn)`               | `(fn: (v: T) => U) => Some<U>` | `() => None`        |
+| `flatMap(fn)`           | `(fn: (v: T) => R) => R`       | `() => this`        |
+| `match(onSome, onNone)` | 2 callbacks                    | 2 callbacks         |
+| `filter(pred)`          | NO errorFactory                | `() => None`        |
+| `toNullable()`          | `T`                            | `null`              |
+| `toUndefined()`         | `T`                            | `undefined`         |
+| `toString()`            | `string`                       | `string`            |
+
+## Critical Rules
+
+1. `match()` takes exactly **2 callbacks**: `(onSome, onNone)`.
+2. `filter()` takes ONLY a predicate — NO `errorFactory` (unlike Result).
+3. Option has **NO** `mapErr()` or `flatMapErr()` — those are Result/Query only.
+4. `flatMap` constraint: `R extends Option<any>` — callback must return an Option.
+5. Type guard: after `isSome()`, access `.value`. None has no `.value`.
+6. `none()` returns a frozen singleton — do not try to construct `new None()`.
+7. `Option.from()` treats only `null | undefined` as None. `0`, `false`, `""` become `Some`.
+
+## Anti-Patterns
+
+```typescript
+// WRONG — Option.filter does NOT take errorFactory
+option.filter((v) => v > 0, () => new Error("bad"));
+
+// CORRECT — just a predicate
+option.filter((v) => v > 0);
+```
+
+```typescript
+// WRONG — mapErr does not exist on Option
+option.mapErr((e) => new Error(e));
+
+// CORRECT — Option has no error channel. Use Result if you need errors.
+```
+
+```typescript
+// WRONG — fromNullable does not exist
+Option.fromNullable(value);
+
+// CORRECT
+Option.from(value);
+```
+
+## Namespace & Async Methods
+
+Read `references/api-surface.md` for the complete Option namespace (`.from`, `.all`, `.partition`, `.compact`, `.some`,
+`.every`) and OptionPromise namespace.

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

@@ -0,0 +1,101 @@
+# Option API Surface
+
+These are ALL available methods for Option. Do not use any method not listed here.
+
+## Types
+
+```typescript
+type Option<T> = Some<T> | None
+type OptionPromise<T> = Promise<Option<T>>
+type SomePromise<T> = Promise<Some<T>>
+type NonePromise = Promise<None>
+type OptionPartitionResult<T> = { values: T[]; noneCount: number }
+type OptionFromType<T> = /* conditional: Some<NonNullable<T>> if T excludes null|undefined, else Option<NonNullable<T>> */
+```
+
+## Factory Functions
+
+```typescript
+function some<T>(value: T): Some<T>
+function none(): None  // returns frozen singleton
+```
+
+## Some<T> Instance Methods
+
+```typescript
+class Some<T> {
+  readonly value: T
+
+  isSome(): this is Some<T>
+  isNone(): this is never
+
+  map<U>(fn: (value: T) => U): Some<U>
+
+  flatMap<R extends Option<any>>(fn: (value: T) => R): R
+
+  match<U>(onSome: (value: T) => U, onNone: () => U): U
+
+  // Overload 1: type-narrowing predicate
+  filter<U extends T>(predicate: (value: T) => value is U): Option<U>
+  // Overload 2: boolean predicate
+  filter(predicate: (value: T) => boolean): Option<T>
+
+  toNullable(): T
+  toUndefined(): T
+  toString(): string
+}
+```
+
+## None Instance Methods
+
+```typescript
+class None {
+  // None has no .value property
+
+  isSome(): this is never
+  isNone(): this is None
+
+  map<U>(): None
+
+  flatMap(): this
+
+  match<U>(onSome: (value: never) => U, onNone: () => U): U
+
+  filter(): None
+
+  toNullable(): null
+  toUndefined(): undefined
+  toString(): string
+}
+```
+
+## NOT available on Option (Result/Query only)
+
+- `mapErr()` — does not exist
+- `flatMapErr()` — does not exist
+
+## Option Namespace (Static Methods)
+
+```typescript
+Option.from<T>(value: T): OptionFromType<T>
+Option.from<T>(fn: () => T): OptionFromType<T>
+Option.isOption<T>(value: unknown): value is Option<T>
+Option.all<T>(options: Some<T>[]): Some<T[]>
+Option.all<T>(options: Option<T>[]): Option<T[]>
+Option.partition<T>(options: Option<T>[]): OptionPartitionResult<T>
+Option.compact<T>(options: Option<T>[]): T[]
+Option.some<T>(options: Option<T>[]): boolean
+Option.every<T>(options: Option<T>[]): boolean
+```
+
+## OptionPromise Namespace (Async Methods)
+
+```typescript
+OptionPromise.from<T>(fn: () => Promise<T>): Promise<OptionFromType<T>>
+OptionPromise.all<T>(promises: Promise<Some<T>>[]): Promise<Some<T[]>>
+OptionPromise.all<T>(promises: Promise<Option<T>>[]): Promise<Option<T[]>>
+OptionPromise.partition<T>(promises: Promise<Option<T>>[]): Promise<OptionPartitionResult<T>>
+OptionPromise.compact<T>(promises: Promise<Option<T>>[]): Promise<T[]>
+OptionPromise.some<T>(promises: Promise<Option<T>>[]): Promise<boolean>
+OptionPromise.every<T>(promises: Promise<Option<T>>[]): Promise<boolean>
+```