@warlock.js/seal 5.19.1 → 5.20.0

package/skills/generate-json-schema/SKILL.md

@@ -1,143 +1,143 @@
----
-name: generate-json-schema
-description: "JSON Schema generation in @warlock.js/seal; use when you need to generate json schema."
----
-
-# JSON Schema generation
-
-Every seal validator exposes `toJsonSchema(target)`. The result is a plain object — pass it straight to OpenAI's `response_format`, an OpenAPI spec, a UI form builder, or anywhere else JSON Schema is the contract.
-
-```ts
-const userSchema = v.object({
-  email: v.string().email(),
-  age: v.int().min(13).optional(),
-});
-
-userSchema.toJsonSchema("draft-2020-12");
-// {
-//   type: "object",
-//   properties: {
-//     email: { type: "string", format: "email" },
-//     age: { type: "integer", minimum: 13 },
-//   },
-//   required: ["email"],
-//   additionalProperties: false,
-// }
-```
-
-## The four targets
-
-```ts
-type JsonSchemaTarget =
-  | "draft-2020-12"  // default — modern JSON Schema
-  | "draft-07"       // older tooling, Swagger 2.0
-  | "openapi-3.0"    // uses { nullable: true } instead of type unions
-  | "openai-strict"  // OpenAI Structured Outputs strict mode
-```
-
-Pick by consumer:
-
-| Consumer | Target |
-| --- | --- |
-| Modern tooling, no specific reason otherwise | `"draft-2020-12"` |
-| Swagger 2.0 / older OpenAPI / older form builders | `"draft-07"` |
-| OpenAPI 3.0 spec (uses `nullable: true`) | `"openapi-3.0"` |
-| OpenAI `response_format: { type: "json_schema", strict: true }` | `"openai-strict"` |
-
-## OpenAI structured outputs (`openai-strict`)
-
-This target encodes the quirks of OpenAI's strict mode:
-
-- **Every field listed in `required`** — strict mode forbids leaving fields out.
-- **Optional fields encoded as `type: ["T", "null"]`** instead of being omitted from `required`.
-- **`additionalProperties: false` on every object.**
-
-```ts
-const schema = v.object({
-  reply: v.string(),
-  citations: v.array(v.string()).optional(),
-});
-
-schema.toJsonSchema("openai-strict");
-// {
-//   type: "object",
-//   properties: {
-//     reply: { type: "string" },
-//     citations: { type: ["array", "null"], items: { type: "string" } },
-//   },
-//   required: ["reply", "citations"],   // every field listed
-//   additionalProperties: false,
-// }
-```
-
-Hand to OpenAI:
-
-```ts
-import OpenAI from "openai";
-
-const completion = await openai.chat.completions.create({
-  model: "gpt-4o",
-  messages: [...],
-  response_format: {
-    type: "json_schema",
-    json_schema: {
-      name: "user_reply",
-      strict: true,
-      schema: schema.toJsonSchema("openai-strict"),
-    },
-  },
-});
-```
-
-In `@warlock.js/ai`, this happens automatically when you set `output: schema` on a supervisor / agent — the runtime picks `openai-strict` for OpenAI providers. You only call `toJsonSchema()` directly when integrating with a non-warlock OpenAI usage.
-
-## OpenAPI 3.0 nullable
-
-```ts
-v.string().nullable().toJsonSchema("openapi-3.0");
-// { type: "string", nullable: true }
-
-v.string().nullable().toJsonSchema("draft-2020-12");
-// { type: ["string", "null"] }
-```
-
-OpenAPI 3.0 uses the boolean `nullable` keyword instead of a type union. Use this target when generating a `paths.openapi.yaml` consumed by Swagger UI or codegen tools.
-
-## What's representable
-
-Cleanly mapped:
-
-- `v.string()` — `{ type: "string" }` (with `format: email/url/uuid`, `pattern`, `minLength`, `maxLength`, `enum`)
-- `v.int()` / `v.float()` — `{ type: "integer" | "number" }` (with `minimum`, `maximum`, `multipleOf`)
-- `v.boolean()` — `{ type: "boolean" }`
-- `v.date()` — `{ type: "string", format: "date-time" | "date" | "time" }` (format derived from transformer if applicable)
-- `v.literal(values)` — `{ const: value }` (single) or `{ enum: [...] }` (multiple)
-- `v.array(item)` — `{ type: "array", items: ... }` (with `minItems`, `maxItems` from length rules; `.unique()`/`.sorted()` are runtime-only and not emitted)
-- `v.object({...})` — `{ type: "object", properties, required, additionalProperties }`
-- `v.union([...])` — `{ oneOf: [...] }`
-- `v.tuple([...])` — `{ type: "array", prefixItems: [...] }` (draft-2020-12) or `{ type: "array", items: [...] }` (draft-07)
-- `v.nullable()` — type union or `nullable: true` per target
-
-## What's silently dropped
-
-Some seal constructs have no JSON Schema representation:
-
-- **Cross-field rules** (`sameAs`, `requiredIf`, `requiredWith`, etc.) — runtime-only. The generated schema describes the *shape*, not the inter-field invariants.
-- **Transformers and mutators** — output reshaping doesn't appear in the schema; the schema reflects *post-mutator, pre-transformer* shape (since that's what rules see and what the LLM is asked to produce for `openai-strict`).
-- **`v.computed` / `v.managed`** — **skipped** entirely by the parent `v.object`; they never appear in `properties`. They aren't part of the data contract. (Calling `.toJsonSchema()` directly on one throws — the parent object is responsible for skipping them.)
-- **`v.instanceof(Ctor)`** — produces `{}`. Class identity isn't expressible. For `File`, attach `{ type: "string", format: "binary" }` manually after generation if needed for OpenAPI.
-- **`v.any()`** — produces `{}` deliberately (any value is valid).
-
-Boolean rules `accepted` / `declined` and similar coercion-style rules are also dropped — JSON Schema doesn't have a notion of "yes/no/on/off" beyond `enum`.
-
-## When the generated schema rejects valid data
-
-If the schema validator itself accepts data but the *generated* JSON Schema rejects the same data downstream, the cause is usually one of:
-
-- **Cross-field rule.** The generated schema doesn't enforce it, but a separate consumer might. (Or the runtime check fired at a different stage.)
-- **Transformer running on the wrong side.** The schema describes the input shape (or strict-mode normalized form). If your transformer reshapes `Date` to ISO string for `data`, the *input* still needs to be a Date-parseable thing.
-- **`openai-strict` quirk.** Optional fields show as `["T", "null"]` rather than omitted — if the model omits them entirely (without sending `null`), strict mode fails. The fix is on the prompt side: tell the model to send `null` for unused fields.
-
-## Cost note
-
-Generating JSON Schema is cheap (pure-function tree walk), so don't worry about caching the result for schemas that change at startup. For dynamic schemas built per-request, generate per-request — there's no shared mutable state.
+---
+name: generate-json-schema
+description: 'Generate JSON Schema via `schema.toJsonSchema(target)` — `draft-2020-12` / `draft-07` / `openapi-3.0` / `openai-strict`. Triggers: `toJsonSchema`, `JsonSchemaTarget`, `draft-2020-12`, `draft-07`, `openapi-3.0`, `openai-strict`, `response_format`, `additionalProperties`, `nullable`; "how do I generate JSON Schema from seal", "OpenAI structured outputs from schema", "OpenAPI 3.0 nullable", "json_schema strict mode"; typical import `import { v } from "@warlock.js/seal"`. Skip: foundations — `@warlock.js/seal/seal-basics/SKILL.md`; bridge typing — `@warlock.js/seal/bridge-standard-schema/SKILL.md`; competing libs `zod-to-json-schema`, `ajv`, `@anatine/zod-openapi`.'
+---
+
+# JSON Schema generation
+
+Every seal validator exposes `toJsonSchema(target)`. The result is a plain object — pass it straight to OpenAI's `response_format`, an OpenAPI spec, a UI form builder, or anywhere else JSON Schema is the contract.
+
+```ts
+const userSchema = v.object({
+  email: v.string().email(),
+  age: v.int().min(13).optional(),
+});
+
+userSchema.toJsonSchema("draft-2020-12");
+// {
+//   type: "object",
+//   properties: {
+//     email: { type: "string", format: "email" },
+//     age: { type: "integer", minimum: 13 },
+//   },
+//   required: ["email"],
+//   additionalProperties: false,
+// }
+```
+
+## The four targets
+
+```ts
+type JsonSchemaTarget =
+  | "draft-2020-12"  // default — modern JSON Schema
+  | "draft-07"       // older tooling, Swagger 2.0
+  | "openapi-3.0"    // uses { nullable: true } instead of type unions
+  | "openai-strict"  // OpenAI Structured Outputs strict mode
+```
+
+Pick by consumer:
+
+| Consumer | Target |
+| --- | --- |
+| Modern tooling, no specific reason otherwise | `"draft-2020-12"` |
+| Swagger 2.0 / older OpenAPI / older form builders | `"draft-07"` |
+| OpenAPI 3.0 spec (uses `nullable: true`) | `"openapi-3.0"` |
+| OpenAI `response_format: { type: "json_schema", strict: true }` | `"openai-strict"` |
+
+## OpenAI structured outputs (`openai-strict`)
+
+This target encodes the quirks of OpenAI's strict mode:
+
+- **Every field listed in `required`** — strict mode forbids leaving fields out.
+- **Optional fields encoded as `type: ["T", "null"]`** instead of being omitted from `required`.
+- **`additionalProperties: false` on every object.**
+
+```ts
+const schema = v.object({
+  reply: v.string(),
+  citations: v.array(v.string()).optional(),
+});
+
+schema.toJsonSchema("openai-strict");
+// {
+//   type: "object",
+//   properties: {
+//     reply: { type: "string" },
+//     citations: { type: ["array", "null"], items: { type: "string" } },
+//   },
+//   required: ["reply", "citations"],   // every field listed
+//   additionalProperties: false,
+// }
+```
+
+Hand to OpenAI:
+
+```ts
+import OpenAI from "openai";
+
+const completion = await openai.chat.completions.create({
+  model: "gpt-4o",
+  messages: [...],
+  response_format: {
+    type: "json_schema",
+    json_schema: {
+      name: "user_reply",
+      strict: true,
+      schema: schema.toJsonSchema("openai-strict"),
+    },
+  },
+});
+```
+
+In `@warlock.js/ai`, this happens automatically when you set `output: schema` on a supervisor / agent — the runtime picks `openai-strict` for OpenAI providers. You only call `toJsonSchema()` directly when integrating with a non-warlock OpenAI usage.
+
+## OpenAPI 3.0 nullable
+
+```ts
+v.string().nullable().toJsonSchema("openapi-3.0");
+// { type: "string", nullable: true }
+
+v.string().nullable().toJsonSchema("draft-2020-12");
+// { type: ["string", "null"] }
+```
+
+OpenAPI 3.0 uses the boolean `nullable` keyword instead of a type union. Use this target when generating a `paths.openapi.yaml` consumed by Swagger UI or codegen tools.
+
+## What's representable
+
+Cleanly mapped:
+
+- `v.string()` — `{ type: "string" }` (with `format: email/url/uuid`, `pattern`, `minLength`, `maxLength`, `enum`)
+- `v.int()` / `v.float()` — `{ type: "integer" | "number" }` (with `minimum`, `maximum`, `multipleOf`)
+- `v.boolean()` — `{ type: "boolean" }`
+- `v.date()` — `{ type: "string", format: "date-time" | "date" | "time" }` (format derived from transformer if applicable)
+- `v.literal(values)` — `{ const: value }` (single) or `{ enum: [...] }` (multiple)
+- `v.array(item)` — `{ type: "array", items: ... }` (with `minItems`, `maxItems` from length rules; `.unique()`/`.sorted()` are runtime-only and not emitted)
+- `v.object({...})` — `{ type: "object", properties, required, additionalProperties }`
+- `v.union([...])` — `{ oneOf: [...] }`
+- `v.tuple([...])` — `{ type: "array", prefixItems: [...] }` (draft-2020-12) or `{ type: "array", items: [...] }` (draft-07)
+- `v.nullable()` — type union or `nullable: true` per target
+
+## What's silently dropped
+
+Some seal constructs have no JSON Schema representation:
+
+- **Cross-field rules** (`sameAs`, `requiredIf`, `requiredWith`, etc.) — runtime-only. The generated schema describes the *shape*, not the inter-field invariants.
+- **Transformers and mutators** — output reshaping doesn't appear in the schema; the schema reflects *post-mutator, pre-transformer* shape (since that's what rules see and what the LLM is asked to produce for `openai-strict`).
+- **`v.computed` / `v.managed`** — **skipped** entirely by the parent `v.object`; they never appear in `properties`. They aren't part of the data contract. (Calling `.toJsonSchema()` directly on one throws — the parent object is responsible for skipping them.)
+- **`v.instanceof(Ctor)`** — produces `{}`. Class identity isn't expressible. For `File`, attach `{ type: "string", format: "binary" }` manually after generation if needed for OpenAPI.
+- **`v.any()`** — produces `{}` deliberately (any value is valid).
+
+Boolean rules `accepted` / `declined` and similar coercion-style rules are also dropped — JSON Schema doesn't have a notion of "yes/no/on/off" beyond `enum`.
+
+## When the generated schema rejects valid data
+
+If the schema validator itself accepts data but the *generated* JSON Schema rejects the same data downstream, the cause is usually one of:
+
+- **Cross-field rule.** The generated schema doesn't enforce it, but a separate consumer might. (Or the runtime check fired at a different stage.)
+- **Transformer running on the wrong side.** The schema describes the input shape (or strict-mode normalized form). If your transformer reshapes `Date` to ISO string for `data`, the *input* still needs to be a Date-parseable thing.
+- **`openai-strict` quirk.** Optional fields show as `["T", "null"]` rather than omitted — if the model omits them entirely (without sending `null`), strict mode fails. The fix is on the prompt side: tell the model to send `null` for unused fields.
+
+## Cost note
+
+Generating JSON Schema is cheap (pure-function tree walk), so don't worry about caching the result for schemas that change at startup. For dynamic schemas built per-request, generate per-request — there's no shared mutable state.

package/skills/handle-seal-errors/SKILL.md

@@ -1,148 +1,148 @@
----
-name: handle-seal-errors
-description: "ValidationResult — reading errors in @warlock.js/seal; use when you need to handle seal errors."
----
-
-# `ValidationResult` — reading errors
-
-`validate(schema, data)` never throws. It returns a `ValidationResult`:
-
-```ts
-type ValidationResult = {
-  isValid: boolean;
-  data: any;             // shape after mutators + transformers (the validated value)
-  errors: ValidationError[];
-};
-
-type ValidationError = {
-  type: string;          // rule type that failed — "required", "email", "min", "string", ...
-  error: string;         // resolved message (translated, with attribute substitution)
-  input: string;         // input field name — "email" or "address.city"
-};
-```
-
-Branch on `isValid` first; reach for `errors[]` only when you need to act on a specific failure.
-
-## Basic flow
-
-```ts
-import { validate, v } from "@warlock.js/seal";
-
-const schema = v.object({
-  email: v.string().email(),
-  age: v.int().min(13).optional(),
-});
-
-const result = await validate(schema, input);
-
-if (result.isValid) {
-  return result.data;  // typed as the inferred shape (post-transformer)
-}
-
-return {
-  status: 422,
-  body: { errors: result.errors },
-};
-```
-
-## Branching on a specific rule
-
-```ts
-const result = await validate(schema, input);
-
-if (!result.isValid) {
-  const emailMissing = result.errors.find(
-    e => e.input === "email" && e.type === "required",
-  );
-  if (emailMissing) {
-    return { redirect: "/signup", reason: "no email" };
-  }
-
-  const ageInvalid = result.errors.find(
-    e => e.input === "age" && (e.type === "int" || e.type === "min"),
-  );
-  if (ageInvalid) {
-    return { error: "Age must be 13 or older" };
-  }
-}
-```
-
-The `type` field is the **stable** identifier — the message is human-facing and may be localized. Branch on `type`, never on the message string.
-
-## Common rule type names
-
-These are the strings you'll see in `error.type`:
-
-The `type` is the rule's own `name` field — not the method you called. Several methods map to one shared rule name (e.g. `.min()` / `.minLength()` on a string both surface as `minLength`; `.sameAs()` surfaces as `equalsField`). The table below lists the actual `type` strings:
-
-| Type | Produced by |
-| --- | --- |
-| `required`, `present` | `.required()`, `.present()` (note: `.optional()` has no error type — it clears the required rule) |
-| `requiredIf`, `requiredWith`, `requiredWithout`, `requiredUnless` | conditional required methods |
-| `string`, `number`, `int`, `float`, `boolean`, `scalar`, `object`, `array`, `date` | type guards from `matchesType` |
-| `minLength`, `maxLength`, `betweenLength`, `length` | string / array length rules (`.min`/`.max` on a string alias to `minLength`/`maxLength`) |
-| `min`, `max`, `betweenNumbers` | number range rules (`.min`/`.max`/`.between` on a number) |
-| `email`, `url`, `uuid`, `pattern`, `matches` | string format rules (`.pattern()` → `pattern`) |
-| `literal`, `enum`, `in`, `allowedValues`, `notAllowedValues` | value-membership rules (`.oneOf` aliases `in`; `.notIn`/`.forbids` → `notAllowedValues`; `.allowsOnly` → `allowedValues`) |
-| `instanceof` | `v.instanceof(Ctor)` |
-| `equalsField`, `notEqualsField` | cross-field equality (`.sameAs` → `equalsField`; `.differentFrom` → `notEqualsField`) |
-| `minDate`, `maxDate`, `beforeField`, `afterField`, `today`, `past`, `future`, `weekDay`, `weekend`, `businessDay`, `birthday` | date rules (`.min`/`.max` → `minDate`/`maxDate`; `.before`/`.after` → `beforeField`/`afterField`) |
-
-If you write custom rules, the `type` name you set on the rule object is what shows up here. Pick stable, kebab-or-camel-case names — they become a public API.
-
-## Customizing error messages
-
-Two layers:
-
-```ts
-v.string().email("Please enter a valid email address").required("Email is required");
-//                ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^                ^^^^^^^^^^^^^^^^
-//                per-rule override                                  per-rule override
-```
-
-Each chain method takes an optional `errorMessage` as its last argument. That overrides the rule's `defaultErrorMessage`. Use it when a single rule needs a tailored message in a specific schema.
-
-For project-wide message overrides, hook into the translation layer (the framework calls `resolveTranslation` with the rule context — wire up your own `t()` function via `SealConfig`).
-
-## Translation params
-
-Rules can stash dynamic substitution params on the context. The default messages reference them:
-
-```
-"The :input must be at least :min characters"
-```
-
-`:input` is the field name (or its translated display name); `:min` and others come from rule-specific metadata. If you need to render the message yourself in a custom UI, the params are available on the rule's context.
-
-For attribute display names ("email" → "Email Address"), use `.attributes({ email: "Email Address" })` on the parent `v.object` or pass via the `validate()` options. The `:input` placeholder picks up the configured display name.
-
-## When to throw
-
-Don't wrap `validate()` in try/catch for *validation* failures — those land in `result.errors`. The only thing that *throws* is a programming bug:
-
-- A rule's callback threw (e.g. you wrote `async validate() { throw new Error(...) }`).
-- A transformer threw on output.
-- A mutator threw on input.
-
-Those are bugs — fix them. Don't try/catch them in app code as a way to handle bad input.
-
-## At the framework boundary
-
-If you're surfacing seal errors through HTTP / RPC, the typical shape is:
-
-```ts
-if (!result.isValid) {
-  return reply.code(422).send({
-    error: "validation_failed",
-    fields: result.errors.map(e => ({
-      field: e.input,
-      type: e.type,
-      message: e.error,
-    })),
-  });
-}
-```
-
-Avoid leaking `result.data` back to the client when rejecting — it might contain transformed sensitive fields.
-
-For server-side logs, log `errors[]` with the field paths and rule types; redact values unless you're certain the field isn't sensitive. The `@warlock.js/logger` redaction layer is the right place to enforce that.
+---
+name: handle-seal-errors
+description: 'Read `ValidationResult` — `isValid`, `errors[]`, `data`. Branch on `error.type`, customize messages, hook translation. Triggers: `ValidationResult`, `ValidationError`, `validate`, `isValid`, `errors`, `data`, `error.type`, `error.input`, `error.error`, `translationParams`, `.attribute`, `SealConfig`; "how to read seal errors", "branch on a specific rule failure", "customize validation error message", "translate seal error", "surface validation errors as 422"; typical import `import { validate, v } from "@warlock.js/seal"`. Skip: modifiers — `@warlock.js/seal/compose-seal-modifiers/SKILL.md`; structural shapes — `@warlock.js/seal/define-structural-shape/SKILL.md`; competing libs `zod` `.safeParse`, `yup` `ValidationError`, `joi`.'
+---
+
+# `ValidationResult` — reading errors
+
+`validate(schema, data)` never throws. It returns a `ValidationResult`:
+
+```ts
+type ValidationResult = {
+  isValid: boolean;
+  data: any;             // shape after mutators + transformers (the validated value)
+  errors: ValidationError[];
+};
+
+type ValidationError = {
+  type: string;          // rule type that failed — "required", "email", "min", "string", ...
+  error: string;         // resolved message (translated, with attribute substitution)
+  input: string;         // input field name — "email" or "address.city"
+};
+```
+
+Branch on `isValid` first; reach for `errors[]` only when you need to act on a specific failure.
+
+## Basic flow
+
+```ts
+import { validate, v } from "@warlock.js/seal";
+
+const schema = v.object({
+  email: v.string().email(),
+  age: v.int().min(13).optional(),
+});
+
+const result = await validate(schema, input);
+
+if (result.isValid) {
+  return result.data;  // typed as the inferred shape (post-transformer)
+}
+
+return {
+  status: 422,
+  body: { errors: result.errors },
+};
+```
+
+## Branching on a specific rule
+
+```ts
+const result = await validate(schema, input);
+
+if (!result.isValid) {
+  const emailMissing = result.errors.find(
+    e => e.input === "email" && e.type === "required",
+  );
+  if (emailMissing) {
+    return { redirect: "/signup", reason: "no email" };
+  }
+
+  const ageInvalid = result.errors.find(
+    e => e.input === "age" && (e.type === "int" || e.type === "min"),
+  );
+  if (ageInvalid) {
+    return { error: "Age must be 13 or older" };
+  }
+}
+```
+
+The `type` field is the **stable** identifier — the message is human-facing and may be localized. Branch on `type`, never on the message string.
+
+## Common rule type names
+
+These are the strings you'll see in `error.type`:
+
+The `type` is the rule's own `name` field — not the method you called. Several methods map to one shared rule name (e.g. `.min()` / `.minLength()` on a string both surface as `minLength`; `.sameAs()` surfaces as `equalsField`). The table below lists the actual `type` strings:
+
+| Type | Produced by |
+| --- | --- |
+| `required`, `present` | `.required()`, `.present()` (note: `.optional()` has no error type — it clears the required rule) |
+| `requiredIf`, `requiredWith`, `requiredWithout`, `requiredUnless` | conditional required methods |
+| `string`, `number`, `int`, `float`, `boolean`, `scalar`, `object`, `array`, `date` | type guards from `matchesType` |
+| `minLength`, `maxLength`, `betweenLength`, `length` | string / array length rules (`.min`/`.max` on a string alias to `minLength`/`maxLength`) |
+| `min`, `max`, `betweenNumbers` | number range rules (`.min`/`.max`/`.between` on a number) |
+| `email`, `url`, `uuid`, `pattern`, `matches` | string format rules (`.pattern()` → `pattern`) |
+| `literal`, `enum`, `in`, `allowedValues`, `notAllowedValues` | value-membership rules (`.oneOf` aliases `in`; `.notIn`/`.forbids` → `notAllowedValues`; `.allowsOnly` → `allowedValues`) |
+| `instanceof` | `v.instanceof(Ctor)` |
+| `equalsField`, `notEqualsField` | cross-field equality (`.sameAs` → `equalsField`; `.differentFrom` → `notEqualsField`) |
+| `minDate`, `maxDate`, `beforeField`, `afterField`, `today`, `past`, `future`, `weekDay`, `weekend`, `businessDay`, `birthday` | date rules (`.min`/`.max` → `minDate`/`maxDate`; `.before`/`.after` → `beforeField`/`afterField`) |
+
+If you write custom rules, the `type` name you set on the rule object is what shows up here. Pick stable, kebab-or-camel-case names — they become a public API.
+
+## Customizing error messages
+
+Two layers:
+
+```ts
+v.string().email("Please enter a valid email address").required("Email is required");
+//                ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^                ^^^^^^^^^^^^^^^^
+//                per-rule override                                  per-rule override
+```
+
+Each chain method takes an optional `errorMessage` as its last argument. That overrides the rule's `defaultErrorMessage`. Use it when a single rule needs a tailored message in a specific schema.
+
+For project-wide message overrides, hook into the translation layer (the framework calls `resolveTranslation` with the rule context — wire up your own `t()` function via `SealConfig`).
+
+## Translation params
+
+Rules can stash dynamic substitution params on the context. The default messages reference them:
+
+```
+"The :input must be at least :min characters"
+```
+
+`:input` is the field name (or its translated display name); `:min` and others come from rule-specific metadata. If you need to render the message yourself in a custom UI, the params are available on the rule's context.
+
+For attribute display names ("email" → "Email Address"), use `.attributes({ email: "Email Address" })` on the parent `v.object` or pass via the `validate()` options. The `:input` placeholder picks up the configured display name.
+
+## When to throw
+
+Don't wrap `validate()` in try/catch for *validation* failures — those land in `result.errors`. The only thing that *throws* is a programming bug:
+
+- A rule's callback threw (e.g. you wrote `async validate() { throw new Error(...) }`).
+- A transformer threw on output.
+- A mutator threw on input.
+
+Those are bugs — fix them. Don't try/catch them in app code as a way to handle bad input.
+
+## At the framework boundary
+
+If you're surfacing seal errors through HTTP / RPC, the typical shape is:
+
+```ts
+if (!result.isValid) {
+  return reply.code(422).send({
+    error: "validation_failed",
+    fields: result.errors.map(e => ({
+      field: e.input,
+      type: e.type,
+      message: e.error,
+    })),
+  });
+}
+```
+
+Avoid leaking `result.data` back to the client when rejecting — it might contain transformed sensitive fields.
+
+For server-side logs, log `errors[]` with the field paths and rule types; redact values unless you're certain the field isn't sensitive. The `@warlock.js/logger` redaction layer is the right place to enforce that.

package/skills/index.md

@@ -0,0 +1,21 @@
+---
+description: "Type-safe, framework-agnostic validation for Warlock.js: schemas, coercion, modifiers, JSON Schema, Standard Schema. Exports `v`, `validate`, `ObjectValidator`, `StringValidator`, `Infer`, reached as `v.object`, `v.string`, `v.array`, `v.enum`, `v.union`. Use for: \"validate this request body\", \"require an email and a min-length password\", \"infer the TypeScript type from a schema\", \"make a field optional or give it a default\", \"generate JSON Schema\", \"write a custom rule\". Not this package: database rules and file validators live in @warlock.js/core; model schemas and persistence are @warlock.js/cascade."
+---
+# @warlock.js/seal
+
+Compose validators from the `v` factory (`v.object({ email: v.string().email() })`), run them with `validate(schema, data)`, and infer static types with `Infer`. Validators chain rules, mutators (transforms) and modifiers; the same schema works as a Standard Schema.
+
+## The 80% path
+1. Orient: `overview.md`, `seal-basics.md`.
+2. Choose the right primitive: `pick-seal-primitive.md`.
+3. Shape nested data: `define-structural-shape.md`.
+4. Refine with optional, defaults, nullable and transforms: `compose-seal-modifiers.md`.
+5. Handle failures and messages: `handle-seal-errors.md`.
+6. Interop: `bridge-standard-schema.md`, `generate-json-schema.md`; extend via `extend-seal-with-plugins.md`.
+
+## Conventions and pitfalls
+- Validation is async; always `await validate(...)`.
+- The package root is framework-agnostic; database-backed rules (unique, exists) and `FileValidator` come from `@warlock.js/core`, not here.
+- Derive types with `Infer` instead of hand-writing parallel interfaces.
+- Mutators change the data (trim, cast); order in the chain matters.
+- Keep reusable schemas in shared modules so controllers and clients agree.