add claude skills

.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>
+```