is-kit 1.11.0 → 1.11.1

package/README.md

@@ -111,6 +111,69 @@ This is the core idea of `is-kit`:
 2. Compose them.
 3. Reuse them anywhere TypeScript narrowing matters.
 
+## 🧭 Guard Composition Guide
+
+When writing reusable guards with `is-kit`, start from the library primitives:
+use `define` for custom runtime checks, and use logic combinators such as
+`and`, `or`, and `not` when combining existing guards. This keeps the result
+reusable as a named guard and preserves the type-level intent in hover,
+completion, and generated declarations.
+
+```ts
+import {
+  and,
+  define,
+  isNil,
+  isNumber,
+  isString,
+  nullish,
+  or,
+  predicateToRefine
+} from 'is-kit';
+
+const isId = or(isString, isNumber);
+const isNullishString = nullish(isString);
+
+const isSlug = define<string>(
+  (value) => isString(value) && /^[a-z0-9-]+$/.test(value)
+);
+
+const isPositiveNumber = and(
+  isNumber,
+  predicateToRefine<number>((value) => value > 0)
+);
+
+isNil(null); // true
+isNil(undefined); // true
+isId('user-1'); // true
+isNullishString(undefined); // true
+isSlug('release-110'); // true
+isPositiveNumber(1); // true
+```
+
+Prefer these forms when generating or reviewing code:
+
+```ts
+declare const value: unknown;
+
+// Prefer
+const isId = or(isString, isNumber);
+const isMaybeName = nullish(isString);
+const isSlug = define<string>(
+  (value) => isString(value) && /^[a-z0-9-]+$/.test(value)
+);
+
+// Avoid
+const isId = (value: unknown) => isString(value) || isNumber(value);
+const isMaybeName = (value: unknown) => value == null || isString(value);
+const isSlug = (value: unknown): value is string =>
+  isString(value) && /^[a-z0-9-]+$/.test(value);
+```
+
+For AI agents or repository-wide conventions, copy
+[docs/agent-rules.md](./docs/agent-rules.md) into the consumer repository's
+agent instructions.
+
 ## ⌚ A 30-second Mental Model
 
 If you are new to the library, these are the pieces to remember:

package/dist/index.d.mts

@@ -1,3 +1,11 @@
+/**
+ * is-kit guard authoring guide:
+ * - Use define<T>(...) for reusable custom runtime checks.
+ * - Use and, andAll, or, and not to compose existing guards instead of
+ *   hand-written boolean wrappers.
+ * - Use nullable, optional, or nullish to widen guards for nullish values.
+ * - Use struct or typedStruct for object-shape guards.
+ */
 type Predicate<T> = (value: unknown) => value is T;
 type Refinement<A, B extends A> = (value: A) => value is B;
 type Guard<T> = Predicate<T>;
@@ -69,12 +77,18 @@ declare function assert<A, B extends A>(refine: Refine<A, B>, value: A, message?
 
 /**
  * Wraps a user function as a typed predicate.
+ * Prefer `define<T>(...)` when creating a reusable custom guard from a runtime
+ * boolean check.
  *
  * Note: The correctness of the predicate is the caller's responsibility.
  * Its result is coerced to a boolean using `!!` for consistent guard behavior.
  *
  * @param fn Function that returns truthy when the value matches the target shape.
  * @returns Predicate narrowing to the intended type when it returns true.
+ * @example
+ * const isSlug = define<string>(
+ *   (value) => isString(value) && /^[a-z0-9-]+$/.test(value)
+ * );
  */
 declare function define<T>(fn: (value: unknown) => value is T): Predicate<T>;
 declare function define<T>(fn: (value: unknown) => boolean): Predicate<T>;
@@ -146,49 +160,76 @@ declare function lazy<T>(factory: () => Predicate<T>): Predicate<T>;
 
 /**
  * Combines a precondition guard with an additional refinement to narrow the type.
+ * Prefer this over hand-written `precondition(x) && condition(x)` when the
+ * composed predicate should be reused as a guard.
  *
  * @param precondition Broad guard evaluated first; short-circuits on failure.
  * @param condition Refinement evaluated only when `precondition` passes.
  * @returns Predicate that narrows the input to a subtype.
+ * @example
+ * const isPositiveNumber = and(
+ *   isNumber,
+ *   predicateToRefine<number>((value) => value > 0)
+ * );
+ * @see andAll
  */
 declare function and<A, B extends A>(precondition: Guard<A>, condition: Refine<A, B>): Predicate<B>;
 /**
  * Chains a sequence of refinements after a precondition, returning the final guard type.
+ * Use this instead of nested `&&` checks when each step should keep narrowing
+ * the next refinement.
  *
  * @param precondition Initial guard applied first.
  * @param steps Subsequent refinements applied in order.
  * @returns Guard reflecting the result of the refinement chain.
+ * @example
+ * const isPublicTitle = andAll(isString, minLength(4), startsWithPublic);
+ * @see and
  */
 declare function andAll<A>(precondition: Guard<A>): Guard<A>;
 declare function andAll<A, B extends A>(precondition: Guard<A>, step1: Refine<A, B>): Guard<B>;
 declare function andAll<A, B extends A, C extends B>(precondition: Guard<A>, step1: Refine<A, B>, step2: Refine<B, C>): Guard<C>;
 /**
  * Logical OR over multiple guards.
+ * Prefer this over hand-written `guardA(x) || guardB(x)` when the composed
+ * predicate should be reused as a guard.
  *
  * @param guards Guards to evaluate; passes if any guard passes.
  * @returns Guard for the union of all guarded types.
+ * @example
+ * const isId = or(isString, isNumber);
+ * @see oneOf
  */
 declare function or<P extends readonly Guard<unknown>[]>(...guards: P): Guard<OutOfGuards<P>>;
 /**
  * Adapts a guard so it can be used as a refinement within a known supertype.
  *
  * @returns Function that converts a `Guard<T>` into a `Refine<A, T>` when `T extends A`.
+ * @see and
  */
 declare function guardIn<A>(): <T extends A>(guard: Guard<T>) => Refine<A, T>;
 /**
  * Logical negation of a guard/refinement.
+ * Use this when a negated predicate should be named and reused.
  *
  * @param guard Guard or refinement to negate.
  * @returns Refinement excluding the guarded subtype from the input type.
+ * @example
+ * const isPresent = not(isNil);
  */
 declare function not<A, T>(guard: Guard<T>): Refine<A, Exclude<A, Extract<A, T>>>;
 declare function not<A, B extends A>(refine: Refine<A, B>): Refine<A, Exclude<A, B>>;
 
 /**
  * Allows `null` in addition to values accepted by the given guard/refinement.
+ * Use this instead of hand-writing `value === null || guard(value)` when the
+ * widened predicate should stay reusable.
  *
  * @param guard Guard/refinement for the base type.
  * @returns Guard/refinement widened to include `null`.
+ * @example
+ * const isNullableString = nullable(isString);
+ * @see nullish
  */
 declare function nullable<T>(guard: Guard<T>): Guard<T | null>;
 declare function nullable<A, B extends A>(refine: Refine<A, B>): Refine<A | null, B | null>;
@@ -197,22 +238,33 @@ declare function nullable<A, B extends A>(refine: Refine<A, B>): Refine<A | null
  *
  * @param guard Guard/refinement possibly including `null`.
  * @returns Guard/refinement with `null` excluded.
+ * @example
+ * const isNonNullString = nonNull(nullable(isString));
  */
 declare function nonNull<T>(guard: Guard<T>): Guard<Exclude<T, null>>;
 declare function nonNull<A, B extends A>(refine: Refine<A, B>): Refine<Exclude<A, null>, Exclude<B, null>>;
 /**
  * Allows `null` or `undefined` in addition to values accepted by the guard.
+ * Use this instead of hand-writing `isNil(value) || guard(value)` when widening
+ * another guard.
  *
  * @param guard Guard/refinement for the base type.
  * @returns Guard/refinement widened to include `null | undefined`.
+ * @example
+ * const isNullishString = nullish(isString);
+ * @see isNil
  */
 declare function nullish<T>(guard: Guard<T>): Guard<T | null | undefined>;
 declare function nullish<A, B extends A>(refine: Refine<A, B>): Refine<A | null | undefined, B | null | undefined>;
 /**
  * Allows `undefined` in addition to values accepted by the guard.
+ * Use this for value-level optionality. For optional object keys in `struct`,
+ * use `optionalKey(...)`.
  *
  * @param guard Guard/refinement for the base type.
  * @returns Guard/refinement widened to include `undefined`.
+ * @example
+ * const isOptionalString = optional(isString);
  */
 declare function optional<T>(guard: Guard<T>): Guard<T | undefined>;
 declare function optional<A, B extends A>(refine: Refine<A, B>): Refine<A | undefined, B | undefined>;
@@ -221,6 +273,8 @@ declare function optional<A, B extends A>(refine: Refine<A, B>): Refine<A | unde
  *
  * @param guard Guard/refinement that may accept `undefined`.
  * @returns Guard/refinement with `undefined` removed.
+ * @example
+ * const isRequiredString = required(optional(isString));
  */
 declare function required<T>(guard: Guard<T | undefined>): Guard<T>;
 declare function required<A, B extends A>(refine: Refine<A | undefined, B | undefined>): Refine<A, B>;
@@ -351,17 +405,21 @@ declare const isSymbol: Predicate<symbol>;
 /**
  * Checks whether a value is exactly `undefined`.
  *
- * To accept `null` as well, use {@link isNil}.
+ * For reusable nullish checks, use {@link isNil} or compose a named guard with
+ * {@link or} once and reuse it.
  *
  * @returns Predicate narrowing to `undefined`.
+ * @see isNil
  */
 declare const isUndefined: Predicate<undefined>;
 /**
  * Checks whether a value is exactly `null`.
  *
- * To accept `undefined` as well, use {@link isNil}.
+ * For reusable nullish checks, use {@link isNil} or compose a named guard with
+ * {@link or} once and reuse it.
  *
  * @returns Predicate narrowing to `null`.
+ * @see isNil
  */
 declare const isNull: Predicate<null>;
 /**

package/dist/index.d.ts

@@ -1,3 +1,11 @@
+/**
+ * is-kit guard authoring guide:
+ * - Use define<T>(...) for reusable custom runtime checks.
+ * - Use and, andAll, or, and not to compose existing guards instead of
+ *   hand-written boolean wrappers.
+ * - Use nullable, optional, or nullish to widen guards for nullish values.
+ * - Use struct or typedStruct for object-shape guards.
+ */
 type Predicate<T> = (value: unknown) => value is T;
 type Refinement<A, B extends A> = (value: A) => value is B;
 type Guard<T> = Predicate<T>;
@@ -69,12 +77,18 @@ declare function assert<A, B extends A>(refine: Refine<A, B>, value: A, message?
 
 /**
  * Wraps a user function as a typed predicate.
+ * Prefer `define<T>(...)` when creating a reusable custom guard from a runtime
+ * boolean check.
  *
  * Note: The correctness of the predicate is the caller's responsibility.
  * Its result is coerced to a boolean using `!!` for consistent guard behavior.
  *
  * @param fn Function that returns truthy when the value matches the target shape.
  * @returns Predicate narrowing to the intended type when it returns true.
+ * @example
+ * const isSlug = define<string>(
+ *   (value) => isString(value) && /^[a-z0-9-]+$/.test(value)
+ * );
  */
 declare function define<T>(fn: (value: unknown) => value is T): Predicate<T>;
 declare function define<T>(fn: (value: unknown) => boolean): Predicate<T>;
@@ -146,49 +160,76 @@ declare function lazy<T>(factory: () => Predicate<T>): Predicate<T>;
 
 /**
  * Combines a precondition guard with an additional refinement to narrow the type.
+ * Prefer this over hand-written `precondition(x) && condition(x)` when the
+ * composed predicate should be reused as a guard.
  *
  * @param precondition Broad guard evaluated first; short-circuits on failure.
  * @param condition Refinement evaluated only when `precondition` passes.
  * @returns Predicate that narrows the input to a subtype.
+ * @example
+ * const isPositiveNumber = and(
+ *   isNumber,
+ *   predicateToRefine<number>((value) => value > 0)
+ * );
+ * @see andAll
  */
 declare function and<A, B extends A>(precondition: Guard<A>, condition: Refine<A, B>): Predicate<B>;
 /**
  * Chains a sequence of refinements after a precondition, returning the final guard type.
+ * Use this instead of nested `&&` checks when each step should keep narrowing
+ * the next refinement.
  *
  * @param precondition Initial guard applied first.
  * @param steps Subsequent refinements applied in order.
  * @returns Guard reflecting the result of the refinement chain.
+ * @example
+ * const isPublicTitle = andAll(isString, minLength(4), startsWithPublic);
+ * @see and
  */
 declare function andAll<A>(precondition: Guard<A>): Guard<A>;
 declare function andAll<A, B extends A>(precondition: Guard<A>, step1: Refine<A, B>): Guard<B>;
 declare function andAll<A, B extends A, C extends B>(precondition: Guard<A>, step1: Refine<A, B>, step2: Refine<B, C>): Guard<C>;
 /**
  * Logical OR over multiple guards.
+ * Prefer this over hand-written `guardA(x) || guardB(x)` when the composed
+ * predicate should be reused as a guard.
  *
  * @param guards Guards to evaluate; passes if any guard passes.
  * @returns Guard for the union of all guarded types.
+ * @example
+ * const isId = or(isString, isNumber);
+ * @see oneOf
  */
 declare function or<P extends readonly Guard<unknown>[]>(...guards: P): Guard<OutOfGuards<P>>;
 /**
  * Adapts a guard so it can be used as a refinement within a known supertype.
  *
  * @returns Function that converts a `Guard<T>` into a `Refine<A, T>` when `T extends A`.
+ * @see and
  */
 declare function guardIn<A>(): <T extends A>(guard: Guard<T>) => Refine<A, T>;
 /**
  * Logical negation of a guard/refinement.
+ * Use this when a negated predicate should be named and reused.
  *
  * @param guard Guard or refinement to negate.
  * @returns Refinement excluding the guarded subtype from the input type.
+ * @example
+ * const isPresent = not(isNil);
  */
 declare function not<A, T>(guard: Guard<T>): Refine<A, Exclude<A, Extract<A, T>>>;
 declare function not<A, B extends A>(refine: Refine<A, B>): Refine<A, Exclude<A, B>>;
 
 /**
  * Allows `null` in addition to values accepted by the given guard/refinement.
+ * Use this instead of hand-writing `value === null || guard(value)` when the
+ * widened predicate should stay reusable.
  *
  * @param guard Guard/refinement for the base type.
  * @returns Guard/refinement widened to include `null`.
+ * @example
+ * const isNullableString = nullable(isString);
+ * @see nullish
  */
 declare function nullable<T>(guard: Guard<T>): Guard<T | null>;
 declare function nullable<A, B extends A>(refine: Refine<A, B>): Refine<A | null, B | null>;
@@ -197,22 +238,33 @@ declare function nullable<A, B extends A>(refine: Refine<A, B>): Refine<A | null
  *
  * @param guard Guard/refinement possibly including `null`.
  * @returns Guard/refinement with `null` excluded.
+ * @example
+ * const isNonNullString = nonNull(nullable(isString));
  */
 declare function nonNull<T>(guard: Guard<T>): Guard<Exclude<T, null>>;
 declare function nonNull<A, B extends A>(refine: Refine<A, B>): Refine<Exclude<A, null>, Exclude<B, null>>;
 /**
  * Allows `null` or `undefined` in addition to values accepted by the guard.
+ * Use this instead of hand-writing `isNil(value) || guard(value)` when widening
+ * another guard.
  *
  * @param guard Guard/refinement for the base type.
  * @returns Guard/refinement widened to include `null | undefined`.
+ * @example
+ * const isNullishString = nullish(isString);
+ * @see isNil
  */
 declare function nullish<T>(guard: Guard<T>): Guard<T | null | undefined>;
 declare function nullish<A, B extends A>(refine: Refine<A, B>): Refine<A | null | undefined, B | null | undefined>;
 /**
  * Allows `undefined` in addition to values accepted by the guard.
+ * Use this for value-level optionality. For optional object keys in `struct`,
+ * use `optionalKey(...)`.
  *
  * @param guard Guard/refinement for the base type.
  * @returns Guard/refinement widened to include `undefined`.
+ * @example
+ * const isOptionalString = optional(isString);
  */
 declare function optional<T>(guard: Guard<T>): Guard<T | undefined>;
 declare function optional<A, B extends A>(refine: Refine<A, B>): Refine<A | undefined, B | undefined>;
@@ -221,6 +273,8 @@ declare function optional<A, B extends A>(refine: Refine<A, B>): Refine<A | unde
  *
  * @param guard Guard/refinement that may accept `undefined`.
  * @returns Guard/refinement with `undefined` removed.
+ * @example
+ * const isRequiredString = required(optional(isString));
  */
 declare function required<T>(guard: Guard<T | undefined>): Guard<T>;
 declare function required<A, B extends A>(refine: Refine<A | undefined, B | undefined>): Refine<A, B>;
@@ -351,17 +405,21 @@ declare const isSymbol: Predicate<symbol>;
 /**
  * Checks whether a value is exactly `undefined`.
  *
- * To accept `null` as well, use {@link isNil}.
+ * For reusable nullish checks, use {@link isNil} or compose a named guard with
+ * {@link or} once and reuse it.
  *
  * @returns Predicate narrowing to `undefined`.
+ * @see isNil
  */
 declare const isUndefined: Predicate<undefined>;
 /**
  * Checks whether a value is exactly `null`.
  *
- * To accept `undefined` as well, use {@link isNil}.
+ * For reusable nullish checks, use {@link isNil} or compose a named guard with
+ * {@link or} once and reuse it.
  *
  * @returns Predicate narrowing to `null`.
+ * @see isNil
  */
 declare const isNull: Predicate<null>;
 /**

package/dist/index.js

@@ -114,6 +114,10 @@ function define(fn) {
   return (value) => !!fn(value);
 }
 
+// src/utils/own-properties.ts
+var hasOwnPropertyKey = (value, key) => Object.hasOwn(value, key);
+var hasOwnPropertyKeys = (value, keys) => keys.every((key) => hasOwnPropertyKey(value, key));
+
 // src/utils/guard-collections.ts
 var everyIterableValue = (values, predicate) => {
   for (const value of values) {
@@ -237,19 +241,19 @@ function equalsBy(guard, selector) {
 }
 function equalsKey(key, target) {
   const hasMatchingKey = define((input) => {
-    return isObject(input) && Object.hasOwn(input, key) && Object.is(input[key], target);
+    return isObject(input) && hasOwnPropertyKey(input, key) && Object.is(input[key], target);
   });
   return (input) => hasMatchingKey(input);
 }
 
 // src/core/key.ts
-var hasKey = (key) => define((input) => isObject(input) && Object.hasOwn(input, key));
+var hasKey = (key) => define((input) => isObject(input) && hasOwnPropertyKey(input, key));
 var hasKeys = (...keys) => {
   if (keys.length === 0) {
     return define(() => false);
   }
   return define(
-    (input) => isObject(input) && keys.every((key) => Object.hasOwn(input, key))
+    (input) => isObject(input) && hasOwnPropertyKeys(input, keys)
   );
 };
 function narrowKeyTo(guard, key) {
@@ -469,12 +473,14 @@ var isOptionalSchemaField = define(
 var hasRequiredKeys = (obj, entries) => (
   // WHY: Required fields must be own properties; inherited values should not
   // satisfy a schema because `struct` models object payload shape, not prototype chains.
-  entries.every(([key, guard]) => Object.hasOwn(obj, key) && guard(obj[key]))
+  entries.every(([key, guard]) => hasOwnPropertyKey(obj, key) && guard(obj[key]))
 );
 var hasValidOptionalKeys = (obj, entries) => (
   // WHY: Optional keys are validated only when present. Missing keys stay valid
   // without forcing callers to encode `undefined` into the value guard.
-  entries.every(([key, guard]) => !Object.hasOwn(obj, key) || guard(obj[key]))
+  entries.every(
+    ([key, guard]) => !hasOwnPropertyKey(obj, key) || guard(obj[key])
+  )
 );
 var hasOnlyAllowedKeys = (obj, allowed) => Object.keys(obj).every((key) => allowed.has(key));
 function optionalKey(guard) {
@@ -485,7 +491,7 @@ function struct(schema, options) {
   const optionalEntries = [];
   const schemaKeys = [];
   for (const key in schema) {
-    if (!Object.hasOwn(schema, key)) continue;
+    if (!hasOwnPropertyKey(schema, key)) continue;
     const field = schema[key];
     schemaKeys.push(key);
     if (isOptionalSchemaField(field)) {

package/dist/index.mjs

@@ -10,6 +10,10 @@ function define(fn) {
   return (value) => !!fn(value);
 }
 
+// src/utils/own-properties.ts
+var hasOwnPropertyKey = (value, key) => Object.hasOwn(value, key);
+var hasOwnPropertyKeys = (value, keys) => keys.every((key) => hasOwnPropertyKey(value, key));
+
 // src/utils/guard-collections.ts
 var everyIterableValue = (values, predicate) => {
   for (const value of values) {
@@ -133,19 +137,19 @@ function equalsBy(guard, selector) {
 }
 function equalsKey(key, target) {
   const hasMatchingKey = define((input) => {
-    return isObject(input) && Object.hasOwn(input, key) && Object.is(input[key], target);
+    return isObject(input) && hasOwnPropertyKey(input, key) && Object.is(input[key], target);
   });
   return (input) => hasMatchingKey(input);
 }
 
 // src/core/key.ts
-var hasKey = (key) => define((input) => isObject(input) && Object.hasOwn(input, key));
+var hasKey = (key) => define((input) => isObject(input) && hasOwnPropertyKey(input, key));
 var hasKeys = (...keys) => {
   if (keys.length === 0) {
     return define(() => false);
   }
   return define(
-    (input) => isObject(input) && keys.every((key) => Object.hasOwn(input, key))
+    (input) => isObject(input) && hasOwnPropertyKeys(input, keys)
   );
 };
 function narrowKeyTo(guard, key) {
@@ -365,12 +369,14 @@ var isOptionalSchemaField = define(
 var hasRequiredKeys = (obj, entries) => (
   // WHY: Required fields must be own properties; inherited values should not
   // satisfy a schema because `struct` models object payload shape, not prototype chains.
-  entries.every(([key, guard]) => Object.hasOwn(obj, key) && guard(obj[key]))
+  entries.every(([key, guard]) => hasOwnPropertyKey(obj, key) && guard(obj[key]))
 );
 var hasValidOptionalKeys = (obj, entries) => (
   // WHY: Optional keys are validated only when present. Missing keys stay valid
   // without forcing callers to encode `undefined` into the value guard.
-  entries.every(([key, guard]) => !Object.hasOwn(obj, key) || guard(obj[key]))
+  entries.every(
+    ([key, guard]) => !hasOwnPropertyKey(obj, key) || guard(obj[key])
+  )
 );
 var hasOnlyAllowedKeys = (obj, allowed) => Object.keys(obj).every((key) => allowed.has(key));
 function optionalKey(guard) {
@@ -381,7 +387,7 @@ function struct(schema, options) {
   const optionalEntries = [];
   const schemaKeys = [];
   for (const key in schema) {
-    if (!Object.hasOwn(schema, key)) continue;
+    if (!hasOwnPropertyKey(schema, key)) continue;
     const field = schema[key];
     schemaKeys.push(key);
     if (isOptionalSchemaField(field)) {

package/docs/README.md

@@ -0,0 +1,101 @@
+# is-kit docs
+
+This directory contains the public documentation site for `is-kit`.
+
+The site is built with Next.js and shadcn/ui. It serves the marketing pages, hand-written API guides, and the generated TypeDoc output.
+
+## What lives here
+
+- `app/` - Next.js routes and page entry points
+- `components/` - reusable docs-site UI and page sections
+- `constants/` - site navigation and page metadata
+- `lib/` - docs-specific helpers and data shaping
+- `public/` - static assets and generated API output
+
+## Local development
+
+From the repository root:
+
+```bash
+pnpm --filter ./docs dev
+```
+
+Other common commands:
+
+```bash
+pnpm --filter ./docs build
+pnpm --filter ./docs start
+```
+
+If you use `mise`, run the same commands through `mise exec`.
+
+## Generated API reference
+
+The API reference is generated from the library source with TypeDoc and written to `docs/public/api`.
+
+From the repository root:
+
+```bash
+pnpm typedoc
+```
+
+After generation, the docs site serves that static output under `/api`.
+
+## Common editing workflow
+
+### Update a guide or landing page
+
+Edit the relevant route in `app/` and the supporting components in `components/`.
+
+### Update navigation or docs metadata
+
+Check the files under `constants/` and `lib/`.
+
+### Refresh generated API docs
+
+Run:
+
+```bash
+pnpm typedoc
+```
+
+### Add or update static assets
+
+Place them under `public/`.
+
+## shadcn/ui
+
+The docs app is already configured for shadcn/ui with the `@/*` alias.
+
+List available components:
+
+```bash
+pnpm --filter ./docs run shadcn:list
+```
+
+Add a component:
+
+```bash
+pnpm --filter ./docs run shadcn:add button
+```
+
+If you need to reinitialize shadcn:
+
+```bash
+pnpm --filter ./docs run shadcn:init
+```
+
+## Example
+
+```tsx
+import { Button } from '@/components/ui/button';
+
+export default function Example() {
+  return (
+    <div className='space-x-2'>
+      <Button>Default</Button>
+      <Button variant='secondary'>Secondary</Button>
+    </div>
+  );
+}
+```

package/docs/agent-rules.md

@@ -0,0 +1,63 @@
+# is-kit Agent Rules
+
+Copy this into a consumer repository's `AGENTS.md`, `CLAUDE.md`, or
+`.agents/rules/is-kit.md` when AI agents generate or review code that uses
+`is-kit`.
+
+## Usage Rules
+
+- Build reusable custom guards with `define<T>(...)` instead of writing
+  standalone type-predicate functions by hand.
+- Prefer `is-kit` combinators over hand-written boolean composition when
+  combining existing guards.
+- Use `or(isA, isB)` instead of `(value) => isA(value) || isB(value)` when the
+  result should be a reusable guard.
+- Use `and(baseGuard, refinement)` or `andAll(...)` instead of hand-written
+  `&&` checks when narrowing should be preserved.
+- Use `not(guard)` for reusable negated guards.
+- Use `nullable(guard)`, `optional(guard)`, or `nullish(guard)` when widening an
+  existing guard to accept `null` and/or `undefined`.
+- Use `isNil(value)` when checking a value directly for `null | undefined`.
+- Use `optionalKey(guard)` for optional object keys inside `struct`.
+
+## Preferred Examples
+
+```ts
+import {
+  and,
+  define,
+  isNil,
+  isNumber,
+  isString,
+  nullish,
+  or,
+  predicateToRefine
+} from 'is-kit';
+
+const isId = or(isString, isNumber);
+const isMaybeName = nullish(isString);
+const isSlug = define<string>(
+  (value) => isString(value) && /^[a-z0-9-]+$/.test(value)
+);
+const isPositiveNumber = and(
+  isNumber,
+  predicateToRefine<number>((value) => value > 0)
+);
+
+declare const value: unknown;
+
+if (isNil(value)) {
+  return;
+}
+```
+
+## Avoid
+
+```ts
+declare const value: unknown;
+
+const isId = (value: unknown) => isString(value) || isNumber(value);
+const isMaybeName = (value: unknown) => value == null || isString(value);
+const isSlug = (value: unknown): value is string =>
+  isString(value) && /^[a-z0-9-]+$/.test(value);
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "is-kit",
-  "version": "1.11.0",
+  "version": "1.11.1",
   "description": "Make 'isXXX' easier. Let's make your code type safe and more readable!",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -22,6 +22,7 @@
   ],
   "files": [
     "dist",
+    "docs/agent-rules.md",
     "README.md",
     "LICENSE"
   ],