add claude skills

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

@@ -0,0 +1,130 @@
+# Query API Surface
+
+These are ALL available methods for Query. Do not use any method not listed here.
+
+## Types
+
+```typescript
+type Query<T, E> = OkSome<T> | OkNone | ErrNone<E>
+type QueryPromise<T, E> = Promise<Query<T, E>>
+type OkSomePromise<T> = Promise<OkSome<T>>
+type OkNonePromise = Promise<OkNone>
+type ErrNonePromise<E> = Promise<ErrNone<E>>
+type QueryPartitionResult<T, E> = { values: T[]; noneCount: number; errors: E[] }
+type QueryFromType<T> = /* conditional: OkSome<NonNullable<T>> if T excludes null|undefined, else OkSome<NonNullable<T>> | OkNone */
+```
+
+## Factory Functions
+
+```typescript
+function okSome<T>(value: T): OkSome<T>
+function okNone(): OkNone  // returns frozen singleton
+function errNone<E>(error: E): ErrNone<E>
+```
+
+## OkSome<T> Instance Methods
+
+```typescript
+class OkSome<T> {
+  readonly value: T
+
+  isSome(): this is OkSome<T>
+  isNone(): this is never
+  isErr(): this is never
+
+  map<U>(fn: (value: T) => U): OkSome<U>
+  mapErr<F>(): OkSome<T>
+
+  flatMap<R extends Query<any, any>>(fn: (value: T) => R): R
+  flatMapErr(): this
+
+  match<U>(onSome: (value: T) => U, onNone: () => U, onErr: (error: never) => U): U
+
+  // Overload 1: type-narrowing predicate
+  filter<U extends T>(predicate: (value: T) => value is U): OkSome<U> | OkNone
+  // Overload 2: boolean predicate
+  filter(predicate: (value: T) => boolean): OkSome<T> | OkNone
+
+  toNullable(): T
+  toUndefined(): T
+  toString(): string
+}
+```
+
+## OkNone Instance Methods
+
+```typescript
+class OkNone {
+  // OkNone has no .value or .err property
+
+  isSome(): this is never
+  isNone(): this is OkNone
+  isErr(): this is never
+
+  map<U>(): OkNone
+  mapErr<F>(): OkNone
+
+  flatMap(): this
+  flatMapErr(): this
+
+  match<U>(onSome: (value: never) => U, onNone: () => U, onErr: (error: never) => U): U
+
+  filter(): OkNone
+
+  toNullable(): null
+  toUndefined(): undefined
+  toString(): string
+}
+```
+
+## ErrNone<E> Instance Methods
+
+```typescript
+class ErrNone<E> {
+  readonly err: E
+
+  isSome(): this is never
+  isNone(): this is never
+  isErr(): this is ErrNone<E>
+
+  map<U>(): ErrNone<E>
+  mapErr<F>(fn: (error: E) => F): ErrNone<F>
+
+  flatMap(): this
+  flatMapErr<R extends Query<any, any>>(fn: (error: E) => R): R
+
+  match<U>(onSome: (value: never) => U, onNone: () => U, onErr: (error: E) => U): U
+
+  filter(): ErrNone<E>
+
+  toNullable(): null
+  toUndefined(): undefined
+  toString(): string
+}
+```
+
+## Query Namespace (Static Methods)
+
+```typescript
+Query.from<T>(value: T): QueryFromType<T>
+Query.from<T, E = unknown>(fn: () => T, errorMap?: (error: unknown) => E): QueryFromType<T> | ErrNone<E>
+Query.isQuery<T, E>(value: unknown): value is Query<T, E>
+Query.all<T>(queries: OkSome<T>[]): OkSome<T[]>
+Query.all<T, E>(queries: Query<T, E>[]): Query<T[], E>
+Query.partition<T, E>(queries: Query<T, E>[]): QueryPartitionResult<T, E>
+Query.compact<T, E>(queries: Query<T, E>[]): T[]
+Query.some<T, E>(queries: Query<T, E>[]): boolean
+Query.every<T, E>(queries: Query<T, E>[]): boolean
+```
+
+## QueryPromise Namespace (Async Methods)
+
+```typescript
+QueryPromise.from<T, E = unknown>(fn: () => Promise<T>, errorMap?: (error: unknown) => E): Promise<QueryFromType<T> | ErrNone<E>>
+QueryPromise.all<T>(promises: Promise<OkSome<T>>[]): Promise<OkSome<T[]>>
+QueryPromise.all<T, E>(promises: Promise<Query<T, E>>[]): Promise<Query<T[], E>>
+QueryPromise.partition<T, E>(promises: Promise<Query<T, E>>[]): Promise<QueryPartitionResult<T, E>>
+QueryPromise.compact<T, E>(promises: Promise<Query<T, E>>[]): Promise<T[]>
+QueryPromise.some<T, E>(promises: Promise<Query<T, E>>[]): Promise<boolean>
+QueryPromise.every<T, E>(promises: Promise<Query<T, E>>[]): Promise<boolean>
+```