@warlock.js/seal 4.0.174 → 4.1.2

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

@@ -0,0 +1,143 @@
+---
+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

@@ -0,0 +1,148 @@
+---
+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/overview/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: overview
+description: 'Front-door orientation for `@warlock.js/seal` — framework-agnostic, type-safe validation. The `v` factory builds schemas, `validate(schema, data)` runs them, `Infer<typeof schema>` extracts the type. Primitives, structural shapes (object/array/record/tuple/union/discriminatedUnion/lazy), modifiers, mutators, a plugin system, JSON-Schema export, and a Standard Schema bridge. TRIGGER when: code imports `v`, `validate`, or `Infer` from `@warlock.js/seal`; user asks "what does @warlock.js/seal do", "validation library for Warlock", "compare seal with zod / yup / valibot", "infer a type from a schema", "JSON schema from a validator", "Standard Schema interop"; package.json adds `@warlock.js/seal`. Skip: specific task already known — load the matching task skill directly (`seal-basics`, `pick-seal-primitive`, `define-structural-shape`, `compose-seal-modifiers`, `handle-seal-errors`, `generate-json-schema`, `bridge-standard-schema`, `extend-seal-with-plugins`); framework-specific validators (FileValidator, database rules) live in `@warlock.js/core/v`, not here.'
+---
+
+# `@warlock.js/seal` — overview
+
+A type-safe, framework-agnostic validation library. You build a schema with the `v` factory, run it with `validate(schema, data)`, and pull the static type out with `Infer<typeof schema>`. One schema is the runtime check *and* the TypeScript type *and* (optionally) a JSON Schema.
+
+Standalone — no framework required. Ships built-in with `@warlock.js/core`, which adds framework-specific validators (file uploads, database existence/uniqueness rules) on top.
+
+## When to reach for it
+
+- You want a single source of truth for a shape — runtime validation, the TS type, and JSON Schema all from one declaration.
+- You'd reach for **zod** / **yup** / **valibot** but want the library the rest of Warlock already speaks (request validation, AI tool inputs, Cascade model schemas).
+- You need **JSON Schema output** for OpenAI structured outputs or an OpenAPI spec.
+
+Skip if you only need framework-bound validators (file uploads, DB rules) — those live in `@warlock.js/core/v`, which extends this package.
+
+## The mental model in one paragraph
+
+`v` is a builder: `v.string()`, `v.int()`, `v.object({...})`, `v.array(...)`, and so on, chained with modifiers (`.optional()`, `.nullable()`, `.default(...)`, `.min(...)`). `validate(schema, data)` returns a `ValidationResult` with `isValid`, `data` (the validated value), and `errors[]`. `Infer<typeof schema>` gives you the static type (with `Infer.Input` / `Infer.Output` distinguishing pre- and post-transform shapes). Because every schema implements Standard Schema, it slots into any `StandardSchemaV1<T>` consumer — and `schema.toJsonSchema(target)` emits JSON Schema for external tools.
+
+## Skills index
+
+Eight task skills. Most schemas only need `seal-basics` + `pick-seal-primitive` + `define-structural-shape`.
+
+### Foundations
+
+#### [`seal-basics/`](../seal-basics/SKILL.md)
+Start here. The `v` factory, `validate(schema, data)`, and `Infer<typeof schema>`.
+
+### Building schemas
+
+#### [`pick-seal-primitive/`](../pick-seal-primitive/SKILL.md)
+Choose the right primitive — `string` / `int` / `literal` / `date` / `enum` / `computed` / `managed` / `instanceof` / `any`. Covers the close calls (`string` vs `scalar`, `int` vs `number`, `literal` vs `enum`).
+
+#### [`define-structural-shape/`](../define-structural-shape/SKILL.md)
+Compose `v.object` / `v.array` / `v.record` / `v.tuple` / `v.union` / `v.discriminatedUnion` / `v.lazy` — object schemas, dynamic-keyed records, tagged unions, recursive shapes.
+
+#### [`compose-seal-modifiers/`](../compose-seal-modifiers/SKILL.md)
+Cross-cutting modifiers — `.optional` / `.nullable` / `.default` / `.catch` / `.omit` / membership rules — plus the mutator-vs-transformer pipeline and `Infer.Input` vs `Infer.Output`.
+
+### Output + interop
+
+#### [`handle-seal-errors/`](../handle-seal-errors/SKILL.md)
+Read a `ValidationResult` — `isValid`, `errors[]`, `data`. Branch on `error.type`, customize messages, hook translation.
+
+#### [`generate-json-schema/`](../generate-json-schema/SKILL.md)
+`schema.toJsonSchema(target)` — draft-2020-12 / draft-07 / openapi-3.0 / openai-strict. For OpenAI structured outputs, OpenAPI specs, any JSON-Schema consumer.
+
+#### [`bridge-standard-schema/`](../bridge-standard-schema/SKILL.md)
+Standard Schema interop — why a `StandardSchemaV1<T>` slot might reject a schema, the phantom-intersection at the `v` factory return, Cascade `Model<TSchema>` variance. For migrating off `as unknown as` casts.
+
+#### [`extend-seal-with-plugins/`](../extend-seal-with-plugins/SKILL.md)
+Author a plugin to add validator methods (`.slug`, `.postalCode`, …) — the `SealPlugin` shape, `registerPlugin` lifecycle, TS prototype augmentation.
+
+## Configuration
+
+`configureSeal({ ... })` sets global behavior (translation hooks, first-error-only mode); `getSealConfig()` reads it; `resetSealConfig()` clears it. Most apps call `configureSeal` once at boot to wire i18n.
+
+## What this package deliberately doesn't do
+
+- **Framework-bound validation.** File-upload and database (exists/unique) rules live in `@warlock.js/core/v`, which builds on this package.
+- **Coercion by default.** Seal validates the shape you declare; reshaping is explicit via mutators/transformers, not silent coercion.
+- **Async-everywhere.** `validate()` is async to support rules that need it, but the core primitives are synchronous checks.
+
+## See also
+
+- [`@warlock.js/cascade`](../../cascade/skills/overview/SKILL.md) — uses seal schemas as `Model.schema`.
+- [`@warlock.js/core`](../../core/skills/overview/SKILL.md) — re-exports `v` (aliased) and adds framework validators in `core/v`.
+- [`mongez-agent-kit-authoring-skills`](../../../../domains/shared/skills/) (load via agent-kit sync) — how this becomes `.claude/skills/warlock-js-seal-overview/`.

package/skills/pick-seal-primitive/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: pick-seal-primitive
+description: 'Pick the right `v` factory primitive — string / int / literal / date / enum / computed / managed / instanceof / any. Triggers: `v.string`, `v.email`, `v.number`, `v.int`, `v.float`, `v.numeric`, `v.boolean`, `v.scalar`, `v.date`, `v.literal`, `v.enum`, `v.instanceof`, `v.computed`, `v.managed`, `v.any`; "v.string vs v.scalar", "v.literal vs v.enum", "v.date vs v.instanceof(Date)", "what is v.computed"; typical import `import { v } from "@warlock.js/seal"`. Skip: structural shapes — `@warlock.js/seal/define-structural-shape/SKILL.md`; modifiers — `@warlock.js/seal/compose-seal-modifiers/SKILL.md`; competing libs `zod`, `valibot`, `yup`.'
+---
+
+# Picking the right primitive
+
+This is the orientation skill — *which* primitive for *which* job. For the chainable methods on each (`.email()`, `.min()`, `.between()`, etc.), load the matching `*-methods.md` reference file in this skill folder.
+
+## Strings
+
+```ts
+v.string()              // type: string — full surface in string-methods.md
+v.email()               // shorthand for v.string().email()
+v.enum(["a", "b"])      // type: "a" | "b" — runs as v.string().oneOf, but the factory overload preserves the literal union
+```
+
+Reach for `v.string()` for any text input. `v.email()` is just sugar — switch back to `v.string().email().min(...)` when you need extra rules.
+
+## Numbers — pick by what you accept
+
+| Validator | Accepts | When |
+|---|---|---|
+| `v.number()` | any finite number | accepts both integers and floats |
+| `v.int()` | integers only | rejects `1.5` |
+| `v.float()` | finite, non-integer | rejects `1` |
+| `v.numeric()` | numeric strings + numbers | form/query inputs that arrive as `"42"` — coerces to number |
+
+All four share the same chain surface (see [`number-methods.md`](./number-methods.md)). Picking is about input acceptance, not chain power.
+
+## Booleans & scalars
+
+```ts
+v.boolean()  // type: boolean — adds .accepted() / .declined() for form-style inputs
+v.scalar()   // type: string | number | boolean — usually a smell pointing at a missing discriminator
+```
+
+Use `v.scalar()` only when the field truly accepts any of the three primitives. If it's "one of N specific values across types", `v.literal(...)` is cleaner.
+
+## Dates
+
+```ts
+v.date()                  // type: Date — normalizes strings/timestamps to Date, rich rule surface
+v.instanceof(Date)        // type: Date — raw instanceof, no normalization, no rules
+```
+
+`v.date()` is the right tool 99% of the time — it ships `.min/.max/.before/.after/.weekDay/.minAge/...` and a built-in mutator that parses strings. `v.instanceof(Date)` is the escape hatch when you specifically need strict instance identity with zero coercion.
+
+## Literals & instances
+
+```ts
+v.literal("items")                          // type: "items"
+v.literal("draft", "published", "archived") // type: "draft" | "published" | "archived"
+v.literal(1, 2, 3)                          // type: 1 | 2 | 3
+v.literal(true)                             // type: true
+
+v.instanceof(File)                          // type: File
+v.instanceof(Buffer)                        // type: Buffer
+v.instanceof(MyClass)                       // type: MyClass
+```
+
+**`v.literal` vs `v.string().oneOf([...])` vs `v.enum([...])`:**
+
+- `v.literal("a", "b")` infers as `"a" | "b"` (literal narrowing). **Use this for discriminator fields.**
+- `v.string().oneOf(["a", "b"])` infers as `string` (loses literal types). Use when broad type is fine.
+- `v.enum(["a", "b"])` runs the same `oneOf` rule at runtime (it builds a `StringValidator().oneOf(...)`), but the `v.enum` factory overload **preserves the literal union** — it infers `"a" | "b"`, not `string`. Pass a TS enum object (`v.enum(Direction)`) and it uses `Object.values`, inferring `Direction[keyof Direction]`.
+
+`v.instanceof(Ctor)` for File/Buffer/Uint8Array/custom classes. Returns `{}` from `toJsonSchema()` (not representable). For OpenAPI `File`, attach `{ type: "string", format: "binary" }` manually after generation.
+
+## `v.any` — escape hatch
+
+```ts
+v.any()  // type: any — skips validation entirely
+```
+
+Reach for it when you genuinely don't care about the shape. Usually a smell — search PRs for it and ask whether a real schema would catch a class of bugs.
+
+## Derived: `v.computed` and `v.managed`
+
+These two **don't validate input** — they produce a value as part of validation.
+
+```ts
+v.object({
+  firstName: v.string(),
+  lastName: v.string(),
+  fullName: v.computed<string>((data) => `${data.firstName} ${data.lastName}`),
+  createdAt: v.managed<Date>(() => new Date()),
+  createdBy: v.managed<string>((context) => context.context?.userId),
+});
+```
+
+- **`v.computed`** runs after sibling validation; callback signature is `(data, context)` — `data` is the validated sibling object. Use for derived values (full name, hash of fields, computed totals). An optional second arg validates the result: `v.computed<string>(cb, v.string().min(3))`.
+- **`v.managed`** runs from `SchemaContext` only — callback signature is `(context)`. Caller-supplied extras passed to `validate(schema, data, { context })` land on `context.context`. Use for framework-injected values — timestamps, current user, request id. The callback is optional (`v.managed()`) for values the framework injects without a generator.
+
+Both are **skipped** when their parent `v.object` generates JSON Schema — they never appear in `properties`, since they're runtime-only and not part of the JSON contract an LLM or external API consumer reads. Calling `.toJsonSchema()` *directly* on a `v.computed` / `v.managed` validator **throws** (it's a programming error — let the parent object skip them).
+
+## Quick map — "I need to validate…"
+
+| Need | Reach for |
+|---|---|
+| Email | `v.string().email()` or `v.email()` |
+| URL | `v.string().url()` |
+| UUID | `v.string().uuid()` (see [`string-methods.md`](./string-methods.md)) |
+| Number 0–100 | `v.number().between(0, 100)` |
+| Positive integer | `v.int().positive()` |
+| One of N constants | `v.literal(...values)` |
+| One of TS enum values | `v.enum(MyEnum)` |
+| Date in the past | `v.date().past()` |
+| File upload | `v.instanceof(File)` |
+| Class instance (not Date) | `v.instanceof(Ctor)` |
+| Discriminated union | see [`@warlock.js/seal/define-structural-shape/SKILL.md`](@warlock.js/seal/define-structural-shape/SKILL.md) |
+| Derived value (computed from siblings) | `v.computed<T>(callback)` |
+| Framework-injected value | `v.managed<T>(callback)` |
+| Free-form / pass-through | `v.any()` (only when you've thought about it) |
+
+## Method-surface reference
+
+Each primitive's full method list lives in a sibling file:
+
+- [`string-methods.md`](./string-methods.md) — `.email` / `.url` / `.uuid` / `.pattern` / `.startsWith` / `.alpha` / `.trim` / `.slug` / `.mask` / `.base64Encode` / …
+- [`number-methods.md`](./number-methods.md) — `.min` / `.max` / `.between` / `.greaterThan` / `.positive` / `.even` / `.multipleOf` / `.minSibling` / `.round` / …
+- [`date-methods.md`](./date-methods.md) — `.min` / `.before` / `.after` / `.today` / `.past` / `.future` / `.weekDay` / `.minAge` / `.year` / `.quarter` / `.toISOString` / …
+- [`boolean-methods.md`](./boolean-methods.md) — `.accepted` / `.declined` / `.mustBeTrue` / `.mustBeFalse` / `.acceptedIf` / `.declinedWithout` / …
+
+For cross-cutting modifiers (`.optional`/`.nullable`/`.default`/`.catch`/`.in`/`.oneOf`), see [`@warlock.js/seal/compose-seal-modifiers/SKILL.md`](@warlock.js/seal/compose-seal-modifiers/SKILL.md). For containers (object/array/record/tuple/union), see [`@warlock.js/seal/define-structural-shape/SKILL.md`](@warlock.js/seal/define-structural-shape/SKILL.md).
+
+## Things NOT to do
+
+- Don't `new ObjectValidator()` (or any class) directly — factory returns carry the StandardSchema bridge that bare instantiation loses.
+- Don't pick `v.scalar` because "it's flexible". Flexibility at this layer usually means a missing discriminator — try `v.literal` or `v.union` first.
+- Don't reach for `v.instanceof(Date)` when `v.date()` works. The latter is purpose-built.
+- Don't use `v.string().oneOf(["a", "b"])` for discriminator fields where you need the literal type — use `v.literal("a", "b")`.
+- Don't expect `v.computed` / `v.managed` to validate input — they ignore input shape entirely. Reach for them only when *producing* a value.

package/skills/pick-seal-primitive/boolean-methods.md

@@ -0,0 +1,71 @@
+# `v.boolean()` — method reference
+
+Picking guide is in [`@warlock.js/seal/pick-seal-primitive/SKILL.md`](@warlock.js/seal/pick-seal-primitive/SKILL.md). Membership rules (`.in`/`.oneOf`) inherited from PrimitiveValidator — see [`@warlock.js/seal/compose-seal-modifiers/SKILL.md`](@warlock.js/seal/compose-seal-modifiers/SKILL.md).
+
+## Strict equality
+
+| Method | Effect |
+|---|---|
+| `.mustBeTrue(msg?)` | strictly `=== true` (rejects `"yes"`, `1`, `"on"`) |
+| `.mustBeFalse(msg?)` | strictly `=== false` |
+
+Use these when the field is a real boolean checkbox value — e.g. "agree to terms" must be exactly `true`, not a truthy string.
+
+## Form-style coercion — `accepted` / `declined`
+
+The "accepted" rules treat `true`, `"yes"`, `"on"`, `1`, `"1"`, `"true"` as accepted. "Declined" treats their counterparts (`false`, `"no"`, `"off"`, `0`, etc.) as declined. Designed for form inputs where a checkbox/radio arrives as a string.
+
+| Method | Effect |
+|---|---|
+| `.accepted(msg?)` | value must be accepted |
+| `.declined(msg?)` | value must be declined |
+
+## Conditional variants — accepted
+
+| Method | Args | Effect |
+|---|---|---|
+| `.acceptedIf(field, value, msg?)` | sibling field equals value | must be accepted in that case |
+| `.acceptedUnless(field, value, msg?)` | sibling field equals value | must be accepted unless that's true |
+| `.acceptedIfRequired(field, msg?)` | sibling field is required | — |
+| `.acceptedIfPresent(field, msg?)` | sibling field is present | — |
+| `.acceptedWithout(field, msg?)` | sibling field is absent | — |
+
+## Conditional variants — declined
+
+| Method | Args | Effect |
+|---|---|---|
+| `.declinedIf(field, value, msg?)` | sibling field equals value | must be declined in that case |
+| `.declinedUnless(field, value, msg?)` | sibling field equals value | must be declined unless that's true |
+| `.declinedIfRequired(field, msg?)` | — | — |
+| `.declinedIfPresent(field, msg?)` | — | — |
+| `.declinedWithout(field, msg?)` | — | — |
+
+All conditional variants only run inside `v.object` — sibling resolution silently passes otherwise.
+
+## JSON Schema mapping
+
+- `v.boolean()` → `{ type: "boolean" }`
+- `.mustBeTrue()` / `.mustBeFalse()` — not currently emitted (could add `const: true/false` in the future)
+- `.accepted()` / `.declined()` and their conditional variants — runtime coercion concerns, not representable
+
+## Common chains
+
+```ts
+// Strict consent checkbox
+v.boolean().mustBeTrue("You must accept the terms")
+
+// Form-style "remember me" — accepts "on" / true / 1
+v.boolean().accepted().optional()
+
+// Cross-field — newsletter must be accepted if subscriptionType = "premium"
+v.object({
+  subscriptionType: v.string().oneOf(["free", "premium"]),
+  newsletter: v.boolean().acceptedIf("subscriptionType", "premium"),
+})
+
+// Marketing opt-in — declined unless region is GDPR-exempt
+v.object({
+  region: v.string(),
+  marketingOptIn: v.boolean().declinedUnless("region", "US"),
+})
+```