@valbuild/core 0.125.0 → 0.127.0

package/dist/{index-915dd675.esm.js → index-5a6e6398.esm.js}

@@ -161,19 +161,217 @@ function _inherits(t, e) {
 // import { SerializedI18nSchema } from "./future/i18n";
 // import { SerializedOneOfSchema } from "./future/oneOf";
 
+/**
+ * A locale scope's path, as something to read in a message.
+ *
+ * The walk names the item of an array or record `*`, which says nothing to
+ * whoever has to fix this. `[]` is the convention people already read as "each
+ * of these", and a path that is nothing BUT items has no field to name at all.
+ */
+function describeScopePath(path) {
+  if (path.every(function (segment) {
+    return segment === "*";
+  })) {
+    return "its entries";
+  }
+  var rendered = "";
+  var _iterator = _createForOfIteratorHelper(path),
+    _step;
+  try {
+    for (_iterator.s(); !(_step = _iterator.n()).done;) {
+      var segment = _step.value;
+      if (segment === "*") {
+        rendered += "[]";
+      } else {
+        rendered += rendered === "" ? segment : ".".concat(segment);
+      }
+    }
+  } catch (err) {
+    _iterator.e(err);
+  } finally {
+    _iterator.f();
+  }
+  return "'".concat(rendered, "'");
+}
 var Schema = /*#__PURE__*/function () {
   function Schema() {
     _classCallCheck(this, Schema);
+    /**
+     * The answer, computed once per schema.
+     *
+     * Memoised because the question is asked from `executeValidate`, which runs
+     * once per SOURCE instance: an array of five hundred blocks asks the item
+     * schema five hundred times, and each answer walks the schema below it
+     * looking for a nested scope. The answer cannot differ between two instances
+     * of the same schema — nothing here reads the source — so the walk is done
+     * once and the result handed back after that.
+     *
+     * The error is still reported at every instance's path. Val's validation
+     * errors are keyed by source path and that is where the Studio draws them, so
+     * a schema error on a row is a schema error on every row; reporting it on one
+     * arbitrary row would put it somewhere nobody was looking.
+     */
+    _defineProperty(this, "localeScopeErrorsMemo", void 0);
   }
   return _createClass(Schema, [{
+    key: "isLocaleField",
+    value:
+    /**
+     * Whether this node is a locale — the field that MARKS a scope, `s.locale()`.
+     *
+     * Only `LocaleSchema` overrides this. A base implementation rather than an
+     * abstract one on purpose: every other schema class answers no, and a
+     * question every class had to answer would be twenty edits for one yes.
+     *
+     * Not the same question as {@link opensLocaleScope}: a locale field marks the
+     * scope, the object AROUND it is the scope. See `localeScope.ts`.
+     */
+    function isLocaleField() {
+      return false;
+    }
+
+    /**
+     * Whether this node OPENS a locale scope, and what opens it.
+     *
+     * An object with a `s.locale()` field opens one; so does a record keyed by
+     * `s.locale()`. Everything below such a node is in that one language, which
+     * is why a scope may not contain another — see `localeScope.ts` for the rule
+     * and the reason it is validated rather than typed.
+     */
+  }, {
+    key: "opensLocaleScope",
+    value: function opensLocaleScope() {
+      return null;
+    }
+
+    /**
+     * The child schemas a locale scope reaches, by the path segment that reaches
+     * them.
+     *
+     * A structural walk that deliberately does NOT go through `executeSerialize`:
+     * serializing a subtree at every node to ask a question about its shape is
+     * quadratic, and this is asked during validation. `*` stands for the item of
+     * an array or record, which has no name of its own.
+     */
+  }, {
+    key: "localeScopeChildren",
+    value: function localeScopeChildren() {
+      return [];
+    }
+
+    /**
+     * Every locale scope opened strictly BELOW this node, by path.
+     *
+     * Stops descending at each one it finds, so a scope three deep is reported
+     * once, by the scope immediately enclosing it, rather than by every ancestor.
+     */
+  }, {
+    key: "localeScopesBelow",
+    value: function localeScopesBelow() {
+      var prefix = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : [];
+      var found = [];
+      var _iterator2 = _createForOfIteratorHelper(this.localeScopeChildren()),
+        _step2;
+      try {
+        for (_iterator2.s(); !(_step2 = _iterator2.n()).done;) {
+          var _step2$value = _step2.value,
+            key = _step2$value.key,
+            schema = _step2$value.schema;
+          var _path = [].concat(_toConsumableArray(prefix), [key]);
+          var opened = schema.opensLocaleScope();
+          if (opened !== null) {
+            found.push({
+              path: _path,
+              kind: opened
+            });
+            continue;
+          }
+          found.push.apply(found, _toConsumableArray(schema.localeScopesBelow(_path)));
+        }
+      } catch (err) {
+        _iterator2.e(err);
+      } finally {
+        _iterator2.f();
+      }
+      return found;
+    }
+
+    /**
+     * The scope rule, as errors at this node — or `false` if it is not broken.
+     *
+     * Two things are wrong and both are wrong in the SCHEMA rather than in the
+     * content, so both are `schemaError`s: an object with two locale fields (the
+     * subtree below it would be in two languages at once), and a locale scope
+     * inside another (the inner one would silently override the outer for part
+     * of a subtree that is supposed to be one language throughout).
+     *
+     * Validated rather than typed on purpose. Expressing "no scope below this
+     * one" as a constraint means threading it through every schema class's type
+     * parameter, and the errors that fall out of a recursive constraint like
+     * that name the whole tree — an unrelated typo in a `.val.ts` would print
+     * pages. See the design notes on the locales PR.
+     */
+  }, {
+    key: "localeScopeErrors",
+    value: function localeScopeErrors() {
+      if (this.localeScopeErrorsMemo === undefined) {
+        this.localeScopeErrorsMemo = this.computeLocaleScopeErrors();
+      }
+      return this.localeScopeErrorsMemo;
+    }
+  }, {
+    key: "computeLocaleScopeErrors",
+    value: function computeLocaleScopeErrors() {
+      var errors = [];
+      var localeFields = this.localeFieldNames();
+      if (localeFields.length > 1) {
+        errors.push({
+          message: "An object can be in one language, so it can have one locale field. Found ".concat(localeFields.map(function (each) {
+            return "'".concat(each, "'");
+          }).join(", "), "."),
+          schemaError: true
+        });
+      }
+      var opened = this.opensLocaleScope();
+      if (opened !== null) {
+        var _iterator3 = _createForOfIteratorHelper(this.localeScopesBelow()),
+          _step3;
+        try {
+          for (_iterator3.s(); !(_step3 = _iterator3.n()).done;) {
+            var nested = _step3.value;
+            errors.push({
+              message: "Everything here is already in one language, so ".concat(describeScopePath(nested.path), " cannot set another. Move the ").concat(nested.kind === "key" ? "locale-keyed record" : "locale field", " out of this ").concat(opened === "key" ? "locale-keyed record" : "object", ", or take the outer one away."),
+              schemaError: true
+            });
+          }
+        } catch (err) {
+          _iterator3.e(err);
+        } finally {
+          _iterator3.f();
+        }
+      }
+      return errors;
+    }
+
+    /**
+     * This node's own `s.locale()` fields, where it is an object that has any.
+     *
+     * Empty everywhere else, so `localeScopeErrors` can live on the base class.
+     */
+  }, {
+    key: "localeFieldNames",
+    value: function localeFieldNames() {
+      return [];
+    }
+  }, {
     key: "executeCustomValidateFunctions",
     value: function executeCustomValidateFunctions(src, customValidateFunctions, ctx) {
       var errors = [];
-      var _iterator = _createForOfIteratorHelper(customValidateFunctions),
-        _step;
+      var _iterator4 = _createForOfIteratorHelper(customValidateFunctions),
+        _step4;
       try {
-        for (_iterator.s(); !(_step = _iterator.n()).done;) {
-          var customValidateFunction = _step.value;
+        for (_iterator4.s(); !(_step4 = _iterator4.n()).done;) {
+          var customValidateFunction = _step4.value;
           try {
             var result = customValidateFunction(src, ctx);
             if (result) {
@@ -191,9 +389,9 @@ var Schema = /*#__PURE__*/function () {
           }
         }
       } catch (err) {
-        _iterator.e(err);
+        _iterator4.e(err);
       } finally {
-        _iterator.f();
+        _iterator4.f();
       }
       return errors;
     }
@@ -292,11 +490,11 @@ var Schema = /*#__PURE__*/function () {
         return incoming;
       }
       for (var pathS in incoming) {
-        var _path = pathS;
-        if (current[_path]) {
-          current[_path] = current[_path].concat(incoming[_path]);
+        var _path2 = pathS;
+        if (current[_path2]) {
+          current[_path2] = current[_path2].concat(incoming[_path2]);
         } else {
-          current[_path] = incoming[_path];
+          current[_path2] = incoming[_path2];
         }
       }
       return current;
@@ -331,6 +529,10 @@ var GetSource = Symbol["for"]("@valbuild/core/GetSource");
 var ValError = Symbol["for"]("@valbuild/core/ValError");
 var GenericSelector = /*#__PURE__*/_createClass(function GenericSelector(valOrExpr, path, schema, error) {
   _classCallCheck(this, GenericSelector);
+  _defineProperty(this, Path, void 0);
+  _defineProperty(this, GetSource, void 0);
+  _defineProperty(this, ValError, void 0);
+  _defineProperty(this, GetSchema, void 0);
   this[Path] = path;
   this[GetSource] = valOrExpr;
   this[ValError] = error;
@@ -462,6 +664,23 @@ var StringSchema = /*#__PURE__*/function (_Schema) {
     _this.isMultiline = isMultiline;
     return _this;
   }
+
+  /**
+   * Describe this field.
+   *
+   * The description is shown next to the field's label in the Val editor, so
+   * it is where you say what an editor needs to know but the field name cannot
+   * carry. It also travels in the serialized schema, which is what the AI
+   * assistant and the MCP tools read.
+   *
+   * Pass `null` to clear a description set earlier.
+   *
+   * @example
+   * const schema = s
+   *   .string()
+   *   .describe("Shown in the browser tab and in search results");
+   * export default c.define("/example.val.ts", schema, "Hello");
+   */
   _inherits(StringSchema, _Schema);
   return _createClass(StringSchema, [{
     key: "describe",
@@ -471,12 +690,24 @@ var StringSchema = /*#__PURE__*/function (_Schema) {
 
     /**
      * @deprecated Use `minLength` instead
+     *
+     * @example
+     * const schema = s.string().minLength(2);
+     * export default c.define("/example.val.ts", schema, "Hi");
      */
   }, {
     key: "min",
     value: function min(minLength) {
       return this.minLength(minLength);
     }
+
+    /**
+     * Validate that the string is at least `minLength` characters long.
+     *
+     * @example
+     * const schema = s.string().minLength(2);
+     * export default c.define("/example.val.ts", schema, "Hi");
+     */
   }, {
     key: "minLength",
     value: function minLength(_minLength) {
@@ -487,12 +718,24 @@ var StringSchema = /*#__PURE__*/function (_Schema) {
 
     /**
      * @deprecated Use `maxLength` instead
+     *
+     * @example
+     * const schema = s.string().maxLength(60);
+     * export default c.define("/example.val.ts", schema, "A title that fits");
      */
   }, {
     key: "max",
     value: function max(maxLength) {
       return this.maxLength(maxLength);
     }
+
+    /**
+     * Validate that the string is at most `maxLength` characters long.
+     *
+     * @example
+     * const schema = s.string().maxLength(60);
+     * export default c.define("/example.val.ts", schema, "A title that fits");
+     */
   }, {
     key: "maxLength",
     value: function maxLength(_maxLength) {
@@ -500,6 +743,19 @@ var StringSchema = /*#__PURE__*/function (_Schema) {
         maxLength: _maxLength
       }), this.opt, this.isRaw, this.customValidateFunctions, this.renderInput, this.isReadonly, this.isHidden, this.description, this.previewInput, this.isMultiline);
     }
+
+    /**
+     * Validate that the string matches `regexp`.
+     *
+     * `message` is what the editor is shown when it does not match. Without one
+     * the error names the pattern, which is rarely what a non-developer needs.
+     *
+     * @example
+     * const schema = s
+     *   .string()
+     *   .regexp(/^[a-z0-9-]+$/, "Lower case letters, digits and dashes only");
+     * export default c.define("/example.val.ts", schema, "my-slug");
+     */
   }, {
     key: "regexp",
     value: function regexp(_regexp, message) {
@@ -508,6 +764,27 @@ var StringSchema = /*#__PURE__*/function (_Schema) {
         regExpMessage: message
       }), this.opt, this.isRaw, this.customValidateFunctions, this.renderInput, this.isReadonly, this.isHidden, this.description, this.previewInput, this.isMultiline);
     }
+
+    /**
+     * Add a custom validation rule to this field.
+     *
+     * The function is called with the field's value and returns `false` when the
+     * value is fine, or a STRING with the message to show when it is not. Call it
+     * more than once to add more rules — they all run, and every message is
+     * reported.
+     *
+     * Write the check as a ternary, not as `ok || "message"`: that returns `true`
+     * when the value is fine, and `true` is not one of the two answers.
+     *
+     * Validation runs in the Studio as you type, in `npx val validate` and
+     * before a publish.
+     *
+     * @example
+     * const schema = s.string().validate((val) =>
+     *   val.trim() === val ? false : "Must not start or end with a space",
+     * );
+     * export default c.define("/example.val.ts", schema, "Hello");
+     */
   }, {
     key: "validate",
     value: function validate(validationFunction) {
@@ -598,6 +875,26 @@ var StringSchema = /*#__PURE__*/function (_Schema) {
       var isHidden = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : true;
       return new StringSchema(this.options, this.opt, this.isRaw, this.customValidateFunctions, this.renderInput, this.isReadonly, isHidden, this.description, this.previewInput, this.isMultiline);
     }
+
+    /**
+     * Do not stega encode this string.
+     *
+     * Val normally encodes an invisible pointer back to the source into every
+     * string it hands your app, which is what makes click-to-edit work. A raw
+     * string is handed over exactly as written — use it wherever the value is
+     * not rendered as visible text: a slug, a class name, an `id`, a URL,
+     * anything parsed or compared.
+     *
+     * @example
+     * const schema = s.object({
+     *   title: s.string(),
+     *   slug: s.string().raw(),
+     * });
+     * export default c.define("/example.val.ts", schema, {
+     *   title: "Hello",
+     *   slug: "hello",
+     * });
+     */
   }, {
     key: "raw",
     value: function raw() {
@@ -663,6 +960,10 @@ var StringSchema = /*#__PURE__*/function (_Schema) {
      *
      * Static configuration, not a callback — see `render.ts`. What a CONTAINER
      * shows for its items is a `preview`, which is a different thing entirely.
+     *
+     * @example
+     * const schema = s.array(s.string().render({ as: "inline" }));
+     * export default c.define("/example.val.ts", schema, ["First", "Second"]);
      */
   }, {
     key: "render",
@@ -674,6 +975,12 @@ var StringSchema = /*#__PURE__*/function (_Schema) {
      * How this VALUE is shown where a preview of it is needed — a row in a
      * sortable list, a reference dropdown, a search hit. Never how the field
      * itself is edited (that is `render`). See `preview.ts`.
+     *
+     * @example
+     * const schema = s.array(
+     *   s.string().preview(({ val }) => ({ title: val })),
+     * );
+     * export default c.define("/example.val.ts", schema, ["First", "Second"]);
      */
   }, {
     key: "preview",
@@ -734,12 +1041,59 @@ var ObjectSchema = /*#__PURE__*/function (_Schema) {
     _this.previewInput = previewInput;
     return _this;
   }
+
+  /**
+   * Describe this field.
+   *
+   * The description is shown next to the field's label in the Val editor, so
+   * it is where you say what an editor needs to know but the field name cannot
+   * carry. It also travels in the serialized schema, which is what the AI
+   * assistant and the MCP tools read.
+   *
+   * Pass `null` to clear a description set earlier.
+   *
+   * @example
+   * const schema = s
+   *   .object({ street: s.string(), city: s.string() })
+   *   .describe("Where the office is — shown on the contact page");
+   * export default c.define("/example.val.ts", schema, {
+   *   street: "Torggata 1",
+   *   city: "Oslo",
+   * });
+   */
   _inherits(ObjectSchema, _Schema);
   return _createClass(ObjectSchema, [{
     key: "describe",
     value: function describe(description) {
       return new ObjectSchema(this.items, this.opt, this.customValidateFunctions, this.isReadonly, this.isHidden, description !== null && description !== void 0 ? description : undefined, this.renderInput, this.previewInput);
     }
+
+    /**
+     * Add a custom validation rule to this field.
+     *
+     * The function is called with the field's value and returns `false` when the
+     * value is fine, or a STRING with the message to show when it is not. Call it
+     * more than once to add more rules — they all run, and every message is
+     * reported.
+     *
+     * Write the check as a ternary, not as `ok || "message"`: that returns `true`
+     * when the value is fine, and `true` is not one of the two answers.
+     *
+     * Validation runs in the Studio as you type, in `npx val validate` and
+     * before a publish.
+     *
+     * An object validator is the place for a rule that spans FIELDS — one field
+     * validated on its own belongs on that field's schema, where the error lands
+     * on the field itself.
+     *
+     * @example
+     * const schema = s
+     *   .object({ from: s.number(), to: s.number() })
+     *   .validate((val) =>
+     *     val.from <= val.to ? false : "'from' must not be after 'to'",
+     *   );
+     * export default c.define("/example.val.ts", schema, { from: 1, to: 4 });
+     */
   }, {
     key: "validate",
     value: function validate(validationFunction) {
@@ -781,6 +1135,18 @@ var ObjectSchema = /*#__PURE__*/function (_Schema) {
       } finally {
         _iterator.f();
       }
+      var _iterator2 = _createForOfIteratorHelper(this.localeScopeErrors()),
+        _step2;
+      try {
+        for (_iterator2.s(); !(_step2 = _iterator2.n()).done;) {
+          var scopeError = _step2.value;
+          error = this.appendValidationError(error, path, scopeError.message, src, scopeError.schemaError);
+        }
+      } catch (err) {
+        _iterator2.e(err);
+      } finally {
+        _iterator2.f();
+      }
       for (var _i = 0, _Object$entries = Object.entries(this.items); _i < _Object$entries.length; _i++) {
         var _Object$entries$_i = _slicedToArray(_Object$entries[_i], 2),
           _key = _Object$entries$_i[0],
@@ -864,7 +1230,7 @@ var ObjectSchema = /*#__PURE__*/function (_Schema) {
     key: "nullable",
     value: function nullable() {
       // Explicit type args: `previewInput` would otherwise pin inference to `Src`.
-      return new ObjectSchema(this.items, true, [], this.isReadonly, this.isHidden, this.description, this.renderInput, this.previewInput);
+      return new ObjectSchema(this.items, true, this.customValidateFunctions, this.isReadonly, this.isHidden, this.description, this.renderInput, this.previewInput);
     }
   }, {
     key: "readonly",
@@ -878,6 +1244,35 @@ var ObjectSchema = /*#__PURE__*/function (_Schema) {
       var isHidden = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : true;
       return new ObjectSchema(this.items, this.opt, this.customValidateFunctions, this.isReadonly, isHidden, this.description, this.renderInput, this.previewInput);
     }
+
+    /** The names of this object's `s.locale()` fields, in declaration order. */
+  }, {
+    key: "localeFieldNames",
+    value: function localeFieldNames() {
+      var _this2 = this;
+      return Object.keys(this.items).filter(function (key) {
+        return _this2.items[key]["isLocaleField"]();
+      });
+    }
+  }, {
+    key: "opensLocaleScope",
+    value: function opensLocaleScope() {
+      // More than one is itself the error, reported by `localeScopeErrors`. It
+      // still opens a scope: reporting "two locale fields" AND "a scope inside a
+      // scope" for the same object would be two errors about one mistake.
+      return this.localeFieldNames().length > 0 ? "field" : null;
+    }
+  }, {
+    key: "localeScopeChildren",
+    value: function localeScopeChildren() {
+      var _this3 = this;
+      return Object.keys(this.items).map(function (key) {
+        return {
+          key: key,
+          schema: _this3.items[key]
+        };
+      });
+    }
   }, {
     key: "executeCustomValidateAt",
     value: function executeCustomValidateAt(path, src) {
@@ -892,6 +1287,16 @@ var ObjectSchema = /*#__PURE__*/function (_Schema) {
      * instead of a preview row that navigates to it.
      *
      * Static configuration, not a callback — see `render.ts`.
+     *
+     * @example
+     * // A page builder: each row edits the object in place, instead of
+     * // navigating to it.
+     * const block = s
+     *   .object({ heading: s.string(), body: s.string() })
+     *   .render({ as: "inline" });
+     * export default c.define("/example.val.ts", s.array(block), [
+     *   { heading: "Hello", body: "World" },
+     * ]);
      */
   }, {
     key: "render",
@@ -903,6 +1308,14 @@ var ObjectSchema = /*#__PURE__*/function (_Schema) {
      * How this VALUE is shown where a preview of it is needed — a row in a
      * sortable list, a reference dropdown, a search hit. Never how the field
      * itself is edited (that is `render`). See `preview.ts`.
+     *
+     * @example
+     * const author = s
+     *   .object({ name: s.string(), role: s.string() })
+     *   .preview(({ val }) => ({ title: val.name, subtitle: val.role }));
+     * export default c.define("/example.val.ts", s.array(author), [
+     *   { name: "Ada", role: "Engineer" },
+     * ]);
      */
   }, {
     key: "preview",
@@ -1005,12 +1418,54 @@ var ArraySchema = /*#__PURE__*/function (_Schema) {
     _this.renderInput = renderInput;
     return _this;
   }
+
+  /**
+   * Describe this field.
+   *
+   * The description is shown next to the field's label in the Val editor, so
+   * it is where you say what an editor needs to know but the field name cannot
+   * carry. It also travels in the serialized schema, which is what the AI
+   * assistant and the MCP tools read.
+   *
+   * Pass `null` to clear a description set earlier.
+   *
+   * @example
+   * const schema = s
+   *   .array(s.string())
+   *   .describe("Bullet points shown under the heading");
+   * export default c.define("/example.val.ts", schema, ["First", "Second"]);
+   */
   _inherits(ArraySchema, _Schema);
   return _createClass(ArraySchema, [{
     key: "describe",
     value: function describe(description) {
       return new ArraySchema(this.item, this.opt, this.customValidateFunctions, this.isReadonly, this.isHidden, description !== null && description !== void 0 ? description : undefined, this.previewInput, this.renderInput);
     }
+
+    /**
+     * Add a custom validation rule to this field.
+     *
+     * The function is called with the field's value and returns `false` when the
+     * value is fine, or a STRING with the message to show when it is not. Call it
+     * more than once to add more rules — they all run, and every message is
+     * reported.
+     *
+     * Write the check as a ternary, not as `ok || "message"`: that returns `true`
+     * when the value is fine, and `true` is not one of the two answers.
+     *
+     * Validation runs in the Studio as you type, in `npx val validate` and
+     * before a publish.
+     *
+     * The function is given the whole array. To validate one item, put a
+     * `.validate(...)` on the ITEM schema instead — that reports the error on
+     * the item's own row.
+     *
+     * @example
+     * const schema = s.array(s.string()).validate((val) =>
+     *   val.length <= 3 ? false : "At most 3 items",
+     * );
+     * export default c.define("/example.val.ts", schema, ["First", "Second"]);
+     */
   }, {
     key: "validate",
     value: function validate(validationFunction) {
@@ -1082,7 +1537,7 @@ var ArraySchema = /*#__PURE__*/function (_Schema) {
     key: "nullable",
     value: function nullable() {
       // Explicit type args: `previewInput` would otherwise pin inference to `Src`.
-      return new ArraySchema(this.item, true, [], this.isReadonly, this.isHidden, this.description, this.previewInput, this.renderInput);
+      return new ArraySchema(this.item, true, this.customValidateFunctions, this.isReadonly, this.isHidden, this.description, this.previewInput, this.renderInput);
     }
   }, {
     key: "readonly",
@@ -1096,6 +1551,14 @@ var ArraySchema = /*#__PURE__*/function (_Schema) {
       var isHidden = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : true;
       return new ArraySchema(this.item, this.opt, this.customValidateFunctions, this.isReadonly, isHidden, this.description, this.previewInput, this.renderInput);
     }
+  }, {
+    key: "localeScopeChildren",
+    value: function localeScopeChildren() {
+      return [{
+        key: "*",
+        schema: this.item
+      }];
+    }
   }, {
     key: "executeCustomValidateAt",
     value: function executeCustomValidateAt(path, src) {
@@ -1218,6 +1681,25 @@ var ArraySchema = /*#__PURE__*/function (_Schema) {
      * is the item of another container, in search, in references. What its rows
      * show is the ITEM schema's `preview`, not this. Never how the field is
      * edited (that is `render`). See `preview.ts`.
+     *
+     * @example
+     * // The preview of the ARRAY, for where it is an item of something else.
+     * // What its own rows show is the ITEM schema's preview — see below.
+     * const tags = s.array(s.string()).preview(({ val }) => ({
+     *   title: `${val.length} tags`,
+     * }));
+     * export default c.define("/example.val.ts", s.record(tags), {
+     *   "a-post": ["news", "release"],
+     * });
+     *
+     * @example
+     * // Rows of an array come from the ITEM's preview, not the array's:
+     * const author = s
+     *   .object({ name: s.string(), role: s.string() })
+     *   .preview(({ val }) => ({ title: val.name, subtitle: val.role }));
+     * export default c.define("/example.val.ts", s.array(author), [
+     *   { name: "Ada", role: "Engineer" },
+     * ]);
      */
   }, {
     key: "preview",
@@ -1231,6 +1713,12 @@ var ArraySchema = /*#__PURE__*/function (_Schema) {
      * instead of a preview row that navigates to it.
      *
      * Static configuration, not a callback — see `render.ts`.
+     *
+     * @example
+     * const schema = s.record(s.array(s.string()).render({ as: "inline" }));
+     * export default c.define("/example.val.ts", schema, {
+     *   "a-post": ["news", "release"],
+     * });
      */
   }, {
     key: "render",
@@ -1244,6 +1732,8 @@ var array = function array(schema) {
 };
 
 var LiteralSchema = /*#__PURE__*/function (_Schema) {
+  /** Type-only marker: as a record key, this declares the key set. See `LocaleSchema`. */
+
   function LiteralSchema(value) {
     var _this;
     var opt = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : false;
@@ -1265,12 +1755,50 @@ var LiteralSchema = /*#__PURE__*/function (_Schema) {
     _this.previewInput = previewInput;
     return _this;
   }
+
+  /**
+   * Describe this field.
+   *
+   * The description is shown next to the field's label in the Val editor, so
+   * it is where you say what an editor needs to know but the field name cannot
+   * carry. It also travels in the serialized schema, which is what the AI
+   * assistant and the MCP tools read.
+   *
+   * Pass `null` to clear a description set earlier.
+   *
+   * @example
+   * const schema = s
+   *   .literal("hero")
+   *   .describe("The block type — it identifies the variant");
+   * export default c.define("/example.val.ts", schema, "hero");
+   */
   _inherits(LiteralSchema, _Schema);
   return _createClass(LiteralSchema, [{
     key: "describe",
     value: function describe(description) {
       return new LiteralSchema(this.value, this.opt, this.customValidateFunctions, this.isReadonly, this.isHidden, description !== null && description !== void 0 ? description : undefined, this.renderInput, this.previewInput);
     }
+
+    /**
+     * Add a custom validation rule to this field.
+     *
+     * The function is called with the field's value and returns `false` when the
+     * value is fine, or a STRING with the message to show when it is not. Call it
+     * more than once to add more rules — they all run, and every message is
+     * reported.
+     *
+     * Write the check as a ternary, not as `ok || "message"`: that returns `true`
+     * when the value is fine, and `true` is not one of the two answers.
+     *
+     * Validation runs in the Studio as you type, in `npx val validate` and
+     * before a publish.
+     *
+     * @example
+     * const schema = s.literal("hero").validate((val) =>
+     *   val === "hero" ? false : "Unknown block type",
+     * );
+     * export default c.define("/example.val.ts", schema, "hero");
+     */
   }, {
     key: "validate",
     value: function validate(validationFunction) {
@@ -1337,7 +1865,7 @@ var LiteralSchema = /*#__PURE__*/function (_Schema) {
   }, {
     key: "nullable",
     value: function nullable() {
-      return new LiteralSchema(this.value, true, [], this.isReadonly, this.isHidden, this.description, this.renderInput, this.previewInput);
+      return new LiteralSchema(this.value, true, this.customValidateFunctions, this.isReadonly, this.isHidden, this.description, this.renderInput, this.previewInput);
     }
   }, {
     key: "readonly",
@@ -1365,6 +1893,10 @@ var LiteralSchema = /*#__PURE__*/function (_Schema) {
      * instead of a preview row that navigates to it.
      *
      * Static configuration, not a callback — see `render.ts`.
+     *
+     * @example
+     * const schema = s.array(s.literal("hero").render({ as: "inline" }));
+     * export default c.define("/example.val.ts", schema, ["hero"]);
      */
   }, {
     key: "render",
@@ -1376,6 +1908,12 @@ var LiteralSchema = /*#__PURE__*/function (_Schema) {
      * How this VALUE is shown where a preview of it is needed — a row in a
      * sortable list, a reference dropdown, a search hit. Never how the field
      * itself is edited (that is `render`). See `preview.ts`.
+     *
+     * @example
+     * const schema = s.array(
+     *   s.literal("hero").preview(({ val }) => ({ title: val })),
+     * );
+     * export default c.define("/example.val.ts", schema, ["hero"]);
      */
   }, {
     key: "preview",
@@ -1424,8 +1962,30 @@ var literal = function literal(value) {
   return new LiteralSchema(value);
 };
 
-var UnionSchema = /*#__PURE__*/function (_Schema) {
-  function UnionSchema(key, items) {
+/** The variant objects a discriminated union on `Key` may be built from. */
+
+/**
+ * At least one variant, so a union with none cannot be written.
+ *
+ * Everything downstream reads the first one where it needs any — `emptyOf`
+ * takes `items[0]` for the value a new entry starts as — and a union with
+ * nothing to select is not a thing an author means. `s.enum` says the same
+ * about its values.
+ */
+
+/** The source type a discriminated union over `T` accepts. */
+
+/**
+ * One of several object shapes, told apart by a tag field.
+ *
+ * Every variant is an object with `key` set to a distinct `s.literal(...)`, and
+ * the value of that field decides which variant a value is. Unlike
+ * {@link EnumSchema} this is a CONTAINER: the variant's fields are the fields
+ * being edited, and everything that walks the schema tree has to descend
+ * through the matching variant.
+ */
+var DiscriminatedUnionSchema = /*#__PURE__*/function (_Schema) {
+  function DiscriminatedUnionSchema(key, items) {
     var _this;
     var opt = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : false;
     var customValidateFunctions = arguments.length > 3 && arguments[3] !== undefined ? arguments[3] : [];
@@ -1434,8 +1994,8 @@ var UnionSchema = /*#__PURE__*/function (_Schema) {
     var description = arguments.length > 6 ? arguments[6] : undefined;
     var renderInput = arguments.length > 7 && arguments[7] !== undefined ? arguments[7] : null;
     var previewInput = arguments.length > 8 && arguments[8] !== undefined ? arguments[8] : null;
-    _classCallCheck(this, UnionSchema);
-    _this = _callSuper(this, UnionSchema);
+    _classCallCheck(this, DiscriminatedUnionSchema);
+    _this = _callSuper(this, DiscriminatedUnionSchema);
     _this.key = key;
     _this.items = items;
     _this.opt = opt;
@@ -1447,16 +2007,66 @@ var UnionSchema = /*#__PURE__*/function (_Schema) {
     _this.previewInput = previewInput;
     return _this;
   }
-  _inherits(UnionSchema, _Schema);
-  return _createClass(UnionSchema, [{
+
+  /**
+   * Describe this field.
+   *
+   * The description is shown next to the field's label in the Val editor, so it is
+   * where you say what an editor needs to know but the field name cannot carry. It
+   * also travels in the serialized schema, which is what the AI assistant and the
+   * MCP tools read.
+   *
+   * Pass `null` to clear a description set earlier.
+   *
+   * @example
+   * const hero = s.object({ type: s.literal("hero"), title: s.string() });
+   * const text = s.object({ type: s.literal("text"), body: s.string() });
+   * const schema = s
+   *   .discriminatedUnion("type", hero, text)
+   *   .describe("What this section of the page is");
+   * export default c.define("/example.val.ts", schema, {
+   *   type: "hero",
+   *   title: "Hello",
+   * });
+   */
+  _inherits(DiscriminatedUnionSchema, _Schema);
+  return _createClass(DiscriminatedUnionSchema, [{
     key: "describe",
     value: function describe(description) {
-      return new UnionSchema(this.key, this.items, this.opt, this.customValidateFunctions, this.isReadonly, this.isHidden, description !== null && description !== void 0 ? description : undefined, this.renderInput, this.previewInput);
+      return new DiscriminatedUnionSchema(this.key, this.items, this.opt, this.customValidateFunctions, this.isReadonly, this.isHidden, description !== null && description !== void 0 ? description : undefined, this.renderInput, this.previewInput);
     }
+
+    /**
+     * Add a custom validation rule to this field.
+     *
+     * The function is called with the field's value and returns `false` when the
+     * value is fine, or a STRING with the message to show when it is not. Call it
+     * more than once to add more rules — they all run, and every message is
+     * reported.
+     *
+     * Validation runs in the Studio as you type, in `npx val validate` and before a
+     * publish.
+     *
+     * The function is given the whole value, whichever variant it took. A rule
+     * that only concerns one variant belongs on that variant's object schema.
+     *
+     * @example
+     * const hero = s.object({ type: s.literal("hero"), title: s.string() });
+     * const text = s.object({ type: s.literal("text"), body: s.string() });
+     * const schema = s
+     *   .discriminatedUnion("type", hero, text)
+     *   .validate((val) =>
+     *     val.type === "hero" && !val.title ? "A hero needs a title" : false,
+     *   );
+     * export default c.define("/example.val.ts", schema, {
+     *   type: "hero",
+     *   title: "Hello",
+     * });
+     */
   }, {
     key: "validate",
     value: function validate(validationFunction) {
-      return new UnionSchema(this.key, this.items, this.opt, this.customValidateFunctions.concat(validationFunction), this.isReadonly, this.isHidden, this.description, this.renderInput, this.previewInput);
+      return new DiscriminatedUnionSchema(this.key, this.items, this.opt, this.customValidateFunctions.concat(validationFunction), this.isReadonly, this.isHidden, this.description, this.renderInput, this.previewInput);
     }
   }, {
     key: "executeValidate",
@@ -1464,142 +2074,135 @@ var UnionSchema = /*#__PURE__*/function (_Schema) {
       var customValidationErrors = this.executeCustomValidateFunctions(src, this.customValidateFunctions, {
         path: path
       });
+      /**
+       * A structural error at this path, unless the custom validators already
+       * reported — in which case theirs are the answer and this one is dropped.
+       * Faithful to what `s.union` did; changing it is a separate decision.
+       */
+      var structural = function structural(error) {
+        return customValidationErrors.length > 0 ? _defineProperty({}, path, customValidationErrors) : _defineProperty({}, path, [error]);
+      };
       var unknownSrc = src;
       if (this.opt && unknownSrc === null) {
         return customValidationErrors.length > 0 ? _defineProperty({}, path, customValidationErrors) : false;
       }
       if (!this.key) {
-        return customValidationErrors.length > 0 ? _defineProperty({}, path, customValidationErrors) : _defineProperty({}, path, [].concat(_toConsumableArray(customValidationErrors), [{
-          message: "Missing required first argument in union",
+        return structural({
+          message: "Missing required first argument in discriminated union",
           schemaError: true
-        }]));
+        });
       }
       var key = this.key;
       if (!Array.isArray(this.items)) {
-        return customValidationErrors.length > 0 ? _defineProperty({}, path, customValidationErrors) : _defineProperty({}, path, [].concat(_toConsumableArray(customValidationErrors), [{
-          message: "A union schema must take more than 1 schema arguments",
+        return structural({
+          message: "A discriminated union schema must take more than 1 schema arguments",
           schemaError: true
-        }]));
+        });
       }
-      if (typeof key === "string") {
-        // tagged union
-        if (this.items.some(function (item) {
-          return !(item instanceof ObjectSchema);
-        })) {
-          return customValidationErrors.length > 0 ? _defineProperty({}, path, customValidationErrors) : _defineProperty({}, path, [].concat(_toConsumableArray(customValidationErrors), [{
-            message: "Key is a string, so all schema items must be objects",
-            schemaError: true
-          }]));
-        }
-        var objectSchemas = this.items;
-        var serializedSchemas = objectSchemas.map(function (schema) {
-          return schema["executeSerialize"]();
+      if (typeof key !== "string") {
+        return structural({
+          message: "The key of a discriminated union must be a string",
+          schemaError: true
         });
-        var illegalSchemas = serializedSchemas.filter(function (schema) {
-          return !(schema.type === "object") || !(schema.items[key].type === "literal");
+      }
+      if (this.items.some(function (item) {
+        return !(item instanceof ObjectSchema);
+      })) {
+        return structural({
+          message: "All schema items of a discriminated union must be objects",
+          schemaError: true
         });
-        if (illegalSchemas.length > 0) {
-          return customValidationErrors.length > 0 ? _defineProperty({}, path, customValidationErrors) : _defineProperty({}, path, [].concat(_toConsumableArray(customValidationErrors), [{
-            message: "All schema items must be objects with a key: ".concat(key, " that is a literal schema. Found: ").concat(JSON.stringify(illegalSchemas, null, 2)),
-            schemaError: true
-          }]));
-        }
-        var serializedObjectSchemas = serializedSchemas;
-        var optionalLiterals = serializedObjectSchemas.filter(function (schema) {
-          return schema.items[key].opt;
+      }
+      var objectSchemas = this.items;
+      var serializedSchemas = objectSchemas.map(function (schema) {
+        return schema["executeSerialize"]();
+      });
+      // `items[key]?` — a variant that OMITS the discriminator is exactly what
+      // this check exists to report, so it must not throw while finding it.
+      var illegalSchemas = serializedSchemas.filter(function (schema) {
+        var _schema$items$key;
+        return !(schema.type === "object") || ((_schema$items$key = schema.items[key]) === null || _schema$items$key === void 0 ? void 0 : _schema$items$key.type) !== "literal";
+      });
+      if (illegalSchemas.length > 0) {
+        return structural({
+          message: "All schema items must be objects with a key: ".concat(key, " that is a literal schema. Found: ").concat(JSON.stringify(illegalSchemas, null, 2)),
+          schemaError: true
         });
-        if (optionalLiterals.length > 1) {
-          return customValidationErrors.length > 0 ? _defineProperty({}, path, customValidationErrors) : _defineProperty({}, path, [].concat(_toConsumableArray(customValidationErrors), [{
-            message: "Schema cannot have an optional keys: ".concat(key),
-            schemaError: true
-          }]));
-        }
-        if (_typeof(unknownSrc) !== "object") {
-          return customValidationErrors.length > 0 ? _defineProperty({}, path, customValidationErrors) : _defineProperty({}, path, [].concat(_toConsumableArray(customValidationErrors), [{
-            message: "Expected an object",
-            typeError: true
-          }]));
-        }
-        var objectSrc = unknownSrc;
-        if (objectSrc[key] === undefined) {
-          return customValidationErrors.length > 0 ? _defineProperty({}, path, customValidationErrors) : _defineProperty({}, path, [].concat(_toConsumableArray(customValidationErrors), [{
-            message: "Missing required key: ".concat(key),
-            typeError: true
-          }]));
-        }
-        var foundSchemaLiterals = [];
-        var _iterator = _createForOfIteratorHelper(serializedObjectSchemas),
-          _step;
-        try {
-          for (_iterator.s(); !(_step = _iterator.n()).done;) {
-            var schema = _step.value;
-            var schemaKey = schema.items[key];
-            if (schemaKey.type === "literal") {
-              if (!foundSchemaLiterals.includes(schemaKey.value)) {
-                foundSchemaLiterals.push(schemaKey.value);
-              } else {
-                return customValidationErrors.length > 0 ? _defineProperty({}, path, customValidationErrors) : _defineProperty({}, path, [].concat(_toConsumableArray(customValidationErrors), [{
-                  message: "Found duplicate key in schema: ".concat(schemaKey.value),
-                  schemaError: true
-                }]));
-              }
-            }
-          }
-        } catch (err) {
-          _iterator.e(err);
-        } finally {
-          _iterator.f();
-        }
-        var objectSchemaAtKey = objectSchemas.find(function (schema) {
-          return !schema["items"][key]["executeValidate"](path, objectSrc[key]);
+      }
+      var serializedObjectSchemas = serializedSchemas;
+      var optionalLiterals = serializedObjectSchemas.filter(function (schema) {
+        return schema.items[key].opt;
+      });
+      if (optionalLiterals.length > 1) {
+        return structural({
+          message: "Schema cannot have an optional keys: ".concat(key),
+          schemaError: true
         });
-        if (!objectSchemaAtKey) {
-          var keyPath = createValPathOfItem(path, key);
-          if (!keyPath) {
-            throw new Error("Internal error: could not create path at ".concat(!path && typeof path === "string" ? "<empty string>" : path, " at key ").concat(key));
-          }
-          return _defineProperty({}, keyPath, [{
-            message: "Invalid key: \"".concat(key, "\". Value was: \"").concat(objectSrc[key], "\". Valid values: ").concat(serializedObjectSchemas.map(function (schema) {
-              var keySchema = schema.items[key];
-              if (keySchema.type === "literal" && keySchema.value) {
-                return "\"".concat(keySchema.value, "\"");
-              } else {
-                // should not happen here, we already checked this
-                throw new Error("Expected literal schema, got ".concat(JSON.stringify(keySchema, null, 2)));
-              }
-            }).join(", "))
-          }]);
-        }
-        var error = objectSchemaAtKey["executeValidate"](path, objectSrc);
-        if (error) {
-          return error;
-        }
-      } else if (key instanceof LiteralSchema) {
-        if (this.items.some(function (item) {
-          return !(item instanceof LiteralSchema);
-        })) {
-          return _defineProperty({}, path, [{
-            message: "Key is a literal schema, so all schema items must be literals",
-            typeError: true
-          }]);
-        }
-        var literalItems = [key].concat(_toConsumableArray(this.items));
-        if (typeof unknownSrc === "string") {
-          var isMatch = literalItems.some(function (item) {
-            return !item["executeValidate"](path, unknownSrc);
-          });
-          if (!isMatch) {
-            return customValidationErrors.length > 0 ? _defineProperty({}, path, customValidationErrors) : _defineProperty({}, path, [].concat(_toConsumableArray(customValidationErrors), [{
-              message: "Union must match one of the following: ".concat(literalItems.map(function (item) {
-                return "\"".concat(item["value"], "\"");
-              }).join(", "))
-            }]));
+      }
+
+      // `typeof null === "object"`, so null has to be named separately or it
+      // reaches `objectSrc[key]` below and throws instead of reporting.
+      if (unknownSrc === null || _typeof(unknownSrc) !== "object") {
+        return structural({
+          message: "Expected an object, got ".concat(unknownSrc === null ? "null" : _typeof(unknownSrc)),
+          typeError: true
+        });
+      }
+      var objectSrc = unknownSrc;
+      if (objectSrc[key] === undefined) {
+        return structural({
+          message: "Missing required key: ".concat(key),
+          typeError: true
+        });
+      }
+      var foundSchemaLiterals = [];
+      var _iterator = _createForOfIteratorHelper(serializedObjectSchemas),
+        _step;
+      try {
+        for (_iterator.s(); !(_step = _iterator.n()).done;) {
+          var schema = _step.value;
+          var schemaKey = schema.items[key];
+          if (schemaKey.type === "literal") {
+            if (!foundSchemaLiterals.includes(schemaKey.value)) {
+              foundSchemaLiterals.push(schemaKey.value);
+            } else {
+              return structural({
+                message: "Found duplicate key in schema: ".concat(schemaKey.value),
+                schemaError: true
+              });
+            }
           }
         }
-      } else {
-        return customValidationErrors.length > 0 ? _defineProperty({}, path, customValidationErrors) : _defineProperty({}, path, [].concat(_toConsumableArray(customValidationErrors), [{
-          message: "Expected a string or literal"
-        }]));
+      } catch (err) {
+        _iterator.e(err);
+      } finally {
+        _iterator.f();
+      }
+      var objectSchemaAtKey = objectSchemas.find(function (schema) {
+        return !schema["items"][key]["executeValidate"](path, objectSrc[key]);
+      });
+      if (!objectSchemaAtKey) {
+        var keyPath = createValPathOfItem(path, key);
+        if (!keyPath) {
+          throw new Error("Internal error: could not create path at ".concat(!path && typeof path === "string" ? "<empty string>" : path, " at key ").concat(key));
+        }
+        return _defineProperty({}, keyPath, [{
+          message: "Invalid key: \"".concat(key, "\". Value was: \"").concat(objectSrc[key], "\". Valid values: ").concat(serializedObjectSchemas.map(function (schema) {
+            var keySchema = schema.items[key];
+            // The TYPE is the whole test: `s.literal("")` is a valid
+            // discriminator, and a truthiness check threw on it here.
+            if (keySchema.type === "literal") {
+              return "\"".concat(keySchema.value, "\"");
+            } else {
+              // should not happen here, we already checked this
+              throw new Error("Expected literal schema, got ".concat(JSON.stringify(keySchema, null, 2)));
+            }
+          }).join(", "))
+        }]);
+      }
+      var error = objectSchemaAtKey["executeValidate"](path, objectSrc);
+      if (error) {
+        return error;
       }
       return customValidationErrors.length > 0 ? _defineProperty({}, path, customValidationErrors) : false;
     }
@@ -1621,11 +2224,11 @@ var UnionSchema = /*#__PURE__*/function (_Schema) {
           }])
         };
       }
-      if (!this.key) {
+      if (typeof this.key !== "string" || !this.key) {
         return {
           success: false,
           errors: _defineProperty({}, path, [{
-            message: "Missing required first argument in union schema",
+            message: "Missing required first argument in discriminated union schema",
             schemaError: true
           }])
         };
@@ -1634,135 +2237,82 @@ var UnionSchema = /*#__PURE__*/function (_Schema) {
         return {
           success: false,
           errors: _defineProperty({}, path, [{
-            message: "The schema of this value is wrong. Schema is neither a union of literals nor a tagged union (of objects)",
+            message: "The schema of this value is wrong. A discriminated union must have an array of object schemas",
             schemaError: true
           }])
         };
       }
-      if (this.key instanceof LiteralSchema) {
-        var _ref23;
-        var success = false;
-        var errors = {};
-        var _iterator2 = _createForOfIteratorHelper((_ref23 = [this.key]).concat.apply(_ref23, _toConsumableArray(this.items))),
-          _step2;
-        try {
-          for (_iterator2.s(); !(_step2 = _iterator2.n()).done;) {
-            var itemSchema = _step2.value;
-            if (!(itemSchema instanceof LiteralSchema)) {
-              return {
-                success: false,
-                errors: _defineProperty({}, path, [{
-                  message: "Schema of value is a union of string, so all schema items must be literals",
-                  schemaError: true
-                }])
-              };
-            }
-            if (typeof src !== "string") {
-              errors[path] = [{
-                message: "Expected 'string', got '".concat(_typeof(src), "'"),
-                typeError: true
-              }];
-              continue;
-            }
-            var res = itemSchema["executeAssert"](path, src);
-            if (res.success) {
-              success = true;
-              break;
-            } else {
-              for (var _i = 0, _Object$entries = Object.entries(res.errors); _i < _Object$entries.length; _i++) {
-                var _errors5;
-                var _Object$entries$_i = _slicedToArray(_Object$entries[_i], 2),
-                  _key = _Object$entries$_i[0],
-                  value = _Object$entries$_i[1];
-                if (!errors[_key]) {
-                  errors[_key] = [];
-                }
-                (_errors5 = errors[_key]).push.apply(_errors5, _toConsumableArray(value));
-              }
-            }
-          }
-        } catch (err) {
-          _iterator2.e(err);
-        } finally {
-          _iterator2.f();
-        }
-        if (!success) {
-          return {
-            success: false,
-            errors: errors
-          };
-        }
-        return {
-          success: true,
-          data: src
-        };
-      } else if (typeof this.key === "string") {
-        var _success = false;
-        var _errors6 = {};
-        var _iterator3 = _createForOfIteratorHelper(this.items),
-          _step3;
-        try {
-          for (_iterator3.s(); !(_step3 = _iterator3.n()).done;) {
-            var _itemSchema = _step3.value;
-            var _res = _itemSchema["executeAssert"](path, src);
-            if (_res.success) {
-              _success = true;
-              break;
-            } else {
-              for (var _i2 = 0, _Object$entries2 = Object.entries(_res.errors); _i2 < _Object$entries2.length; _i2++) {
-                var _errors7;
-                var _Object$entries2$_i = _slicedToArray(_Object$entries2[_i2], 2),
-                  _key2 = _Object$entries2$_i[0],
-                  _value = _Object$entries2$_i[1];
-                if (!_errors6[_key2]) {
-                  _errors6[_key2] = [];
-                }
-                (_errors7 = _errors6[_key2]).push.apply(_errors7, _toConsumableArray(_value)); // by appending all type errors, we most likely get a lot of duplicate errors. Currently we believe this is correct though, but should probably be handled in when showing the errors to users
+      var success = false;
+      var errors = {};
+      var _iterator2 = _createForOfIteratorHelper(this.items),
+        _step2;
+      try {
+        for (_iterator2.s(); !(_step2 = _iterator2.n()).done;) {
+          var itemSchema = _step2.value;
+          var res = itemSchema["executeAssert"](path, src);
+          if (res.success) {
+            success = true;
+            break;
+          } else {
+            for (var _i = 0, _Object$entries = Object.entries(res.errors); _i < _Object$entries.length; _i++) {
+              var _errors4;
+              var _Object$entries$_i = _slicedToArray(_Object$entries[_i], 2),
+                _key = _Object$entries$_i[0],
+                value = _Object$entries$_i[1];
+              if (!errors[_key]) {
+                errors[_key] = [];
               }
+              (_errors4 = errors[_key]).push.apply(_errors4, _toConsumableArray(value)); // by appending all type errors, we most likely get a lot of duplicate errors. Currently we believe this is correct though, but should probably be handled in when showing the errors to users
             }
           }
-        } catch (err) {
-          _iterator3.e(err);
-        } finally {
-          _iterator3.f();
-        }
-        if (!_success) {
-          return {
-            success: false,
-            errors: _errors6
-          };
         }
-        return {
-          success: true,
-          data: src
-        };
-      } else {
+      } catch (err) {
+        _iterator2.e(err);
+      } finally {
+        _iterator2.f();
+      }
+      if (!success) {
         return {
           success: false,
-          errors: _defineProperty({}, path, [{
-            message: "The schema of this value is wrong. Schema is neither a union of literals nor a tagged union (of objects)",
-            schemaError: true
-          }])
+          errors: errors
         };
       }
+      return {
+        success: true,
+        data: src
+      };
     }
   }, {
     key: "nullable",
     value: function nullable() {
       // Explicit type args: `previewInput` would otherwise pin inference to `Src`.
-      return new UnionSchema(this.key, this.items, true, [], this.isReadonly, this.isHidden, this.description, this.renderInput, this.previewInput);
+      return new DiscriminatedUnionSchema(this.key, this.items, true, this.customValidateFunctions, this.isReadonly, this.isHidden, this.description, this.renderInput, this.previewInput);
     }
   }, {
     key: "readonly",
     value: function readonly() {
       var isReadonly = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : true;
-      return new UnionSchema(this.key, this.items, this.opt, this.customValidateFunctions, isReadonly, this.isHidden, this.description, this.renderInput, this.previewInput);
+      return new DiscriminatedUnionSchema(this.key, this.items, this.opt, this.customValidateFunctions, isReadonly, this.isHidden, this.description, this.renderInput, this.previewInput);
     }
   }, {
     key: "hidden",
     value: function hidden() {
       var isHidden = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : true;
-      return new UnionSchema(this.key, this.items, this.opt, this.customValidateFunctions, this.isReadonly, isHidden, this.description, this.renderInput, this.previewInput);
+      return new DiscriminatedUnionSchema(this.key, this.items, this.opt, this.customValidateFunctions, this.isReadonly, isHidden, this.description, this.renderInput, this.previewInput);
+    }
+  }, {
+    key: "localeScopeChildren",
+    value: function localeScopeChildren() {
+      // Every variant is walked under the SAME path: whichever one the value
+      // takes, that is where it sits. `s.enum()` has no children at all — its
+      // values are strings, not schemas — which is why only this half of the old
+      // `s.union` has this.
+      return this.items.map(function (item) {
+        return {
+          key: "*",
+          schema: item
+        };
+      });
     }
   }, {
     key: "executeCustomValidateAt",
@@ -1770,10 +2320,10 @@ var UnionSchema = /*#__PURE__*/function (_Schema) {
       var errors = this.executeCustomValidateFunctions(src, this.customValidateFunctions, {
         path: path
       });
-      // A tagged union's variants share the union's path, so `Internal.resolvePath`
-      // stops here and a variant's OWN validator would never be reached. Dispatch
-      // into the variant this value takes — the union is the only node that knows
-      // which one that is.
+      // A discriminated union's variants share the union's path, so
+      // `Internal.resolvePath` stops here and a variant's OWN validator would
+      // never be reached. Dispatch into the variant this value takes — the union
+      // is the only node that knows which one that is.
       var matched = this.matchedVariant(src);
       if (matched) {
         errors.push.apply(errors, _toConsumableArray(matched["executeCustomValidateAt"](path, src)));
@@ -1782,10 +2332,8 @@ var UnionSchema = /*#__PURE__*/function (_Schema) {
     }
 
     /**
-     * The variant schema a value takes, for a TAGGED union (string `key`). `null`
-     * for a literal union (its variants are leaves with nothing to descend into) or
-     * when the value matches none of them — a structural error `executeValidate`
-     * already reports.
+     * The variant schema a value takes. `null` when the value matches none of
+     * them — a structural error `executeValidate` already reports.
      */
   }, {
     key: "matchedVariant",
@@ -1802,11 +2350,11 @@ var UnionSchema = /*#__PURE__*/function (_Schema) {
         return null;
       }
       var objectSchemas = this.items;
-      var _iterator4 = _createForOfIteratorHelper(objectSchemas),
-        _step4;
+      var _iterator3 = _createForOfIteratorHelper(objectSchemas),
+        _step3;
       try {
-        for (_iterator4.s(); !(_step4 = _iterator4.n()).done;) {
-          var item = _step4.value;
+        for (_iterator3.s(); !(_step3 = _iterator3.n()).done;) {
+          var item = _step3.value;
           if (!(item instanceof ObjectSchema)) {
             continue;
           }
@@ -1816,9 +2364,9 @@ var UnionSchema = /*#__PURE__*/function (_Schema) {
           }
         }
       } catch (err) {
-        _iterator4.e(err);
+        _iterator3.e(err);
       } finally {
-        _iterator4.f();
+        _iterator3.f();
       }
       return null;
     }
@@ -1829,11 +2377,21 @@ var UnionSchema = /*#__PURE__*/function (_Schema) {
      * instead of a preview row that navigates to it.
      *
      * Static configuration, not a callback — see `render.ts`.
+     *
+     * @example
+     * // A page builder: the row draws the tag selector and the matched
+     * // variant's fields.
+     * const hero = s.object({ type: s.literal("hero"), title: s.string() });
+     * const text = s.object({ type: s.literal("text"), body: s.string() });
+     * const block = s.discriminatedUnion("type", hero, text).render({ as: "inline" });
+     * export default c.define("/example.val.ts", s.array(block), [
+     *   { type: "hero", title: "Hello" },
+     * ]);
      */
   }, {
     key: "render",
     value: function render(input) {
-      return new UnionSchema(this.key, this.items, this.opt, this.customValidateFunctions, this.isReadonly, this.isHidden, this.description, input, this.previewInput);
+      return new DiscriminatedUnionSchema(this.key, this.items, this.opt, this.customValidateFunctions, this.isReadonly, this.isHidden, this.description, input, this.previewInput);
     }
 
     /**
@@ -1841,13 +2399,24 @@ var UnionSchema = /*#__PURE__*/function (_Schema) {
      * sortable list, a reference dropdown, a search hit. Never how the field
      * itself is edited (that is `render`). See `preview.ts`.
      *
-     * Without one of its own, a tagged union previews as the VARIANT the value
-     * takes — declare `preview` on the member objects and the union dispatches.
+     * Without one of its own, a discriminated union previews as the VARIANT the
+     * value takes — declare `preview` on the member objects and the union
+     * dispatches.
+     *
+     * @example
+     * const hero = s.object({ type: s.literal("hero"), title: s.string() });
+     * const text = s.object({ type: s.literal("text"), body: s.string() });
+     * const block = s
+     *   .discriminatedUnion("type", hero, text)
+     *   .preview(({ val }) => ({ title: val.type }));
+     * export default c.define("/example.val.ts", s.array(block), [
+     *   { type: "hero", title: "Hello" },
+     * ]);
      */
   }, {
     key: "preview",
     value: function preview(select) {
-      return new UnionSchema(this.key, this.items, this.opt, this.customValidateFunctions, this.isReadonly, this.isHidden, this.description, this.renderInput, select);
+      return new DiscriminatedUnionSchema(this.key, this.items, this.opt, this.customValidateFunctions, this.isReadonly, this.isHidden, this.description, this.renderInput, select);
     }
   }, {
     key: "executePreviewItem",
@@ -1878,34 +2447,19 @@ var UnionSchema = /*#__PURE__*/function (_Schema) {
   }, {
     key: "executeSerialize",
     value: function executeSerialize() {
-      var _this$renderInput2, _this$customValidateF2;
-      if (typeof this.key === "string") {
-        var _this$renderInput, _this$customValidateF;
-        return {
-          type: "union",
-          render: (_this$renderInput = this.renderInput) !== null && _this$renderInput !== void 0 ? _this$renderInput : undefined,
-          preview: this.previewInput ? true : undefined,
-          key: this.key,
-          items: this.items.map(function (o) {
-            return o["executeSerialize"]();
-          }),
-          opt: this.opt,
-          customValidate: this.customValidateFunctions && ((_this$customValidateF = this.customValidateFunctions) === null || _this$customValidateF === void 0 ? void 0 : _this$customValidateF.length) > 0,
-          readonly: this.isReadonly,
-          hidden: this.isHidden,
-          description: this.description
-        };
-      }
+      var _this$renderInput, _this$customValidateF;
       return {
-        type: "union",
-        render: (_this$renderInput2 = this.renderInput) !== null && _this$renderInput2 !== void 0 ? _this$renderInput2 : undefined,
+        type: "discriminated-union",
+        render: (_this$renderInput = this.renderInput) !== null && _this$renderInput !== void 0 ? _this$renderInput : undefined,
         preview: this.previewInput ? true : undefined,
-        key: this.key["executeSerialize"](),
+        key: this.key,
+        // Every item is an ObjectSchema — `executeValidate` reports a schema
+        // error for anything else, but the type of `T` cannot say so.
         items: this.items.map(function (o) {
           return o["executeSerialize"]();
         }),
         opt: this.opt,
-        customValidate: this.customValidateFunctions && ((_this$customValidateF2 = this.customValidateFunctions) === null || _this$customValidateF2 === void 0 ? void 0 : _this$customValidateF2.length) > 0,
+        customValidate: this.customValidateFunctions && ((_this$customValidateF = this.customValidateFunctions) === null || _this$customValidateF === void 0 ? void 0 : _this$customValidateF.length) > 0,
         readonly: this.isReadonly,
         hidden: this.isHidden,
         description: this.description
@@ -1918,48 +2472,46 @@ var UnionSchema = /*#__PURE__*/function (_Schema) {
       if (src === null) {
         return res;
       }
-      if (this.key instanceof LiteralSchema) {
-        return res;
-      }
       var unionKey = this.key;
-      if (typeof unionKey === "string") {
-        var thisSchema = this.items.find(
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        function (item) {
-          if (item instanceof ObjectSchema) {
-            var itemKey = item["items"][unionKey];
-            if (itemKey instanceof LiteralSchema) {
-              return _typeof(src) === "object" && unionKey in src && itemKey["value"] === src[unionKey];
-            }
-          }
-          return false;
-        });
-        if (thisSchema) {
-          var itemResult = thisSchema["executePreview"](sourcePath, src, scope);
-          for (var keyS in itemResult) {
-            var _key3 = keyS;
-            res[_key3] = itemResult[_key3];
-          }
-          return res;
-        }
+      if (typeof unionKey !== "string") {
         res[sourcePath] = {
           status: "error",
-          message: "Could not find a matching (object) schema for the union key: ".concat(unionKey)
+          message: "The schema of this value is wrong. Expected the key of a discriminated union to be a string. Got: '".concat(JSON.stringify(unionKey, null, 2), "'")
         };
+        return res;
+      }
+      var thisSchema = this.items.find(
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      function (item) {
+        if (item instanceof ObjectSchema) {
+          var itemKey = item["items"][unionKey];
+          if (itemKey instanceof LiteralSchema) {
+            return _typeof(src) === "object" && unionKey in src && itemKey["value"] === src[unionKey];
+          }
+        }
+        return false;
+      });
+      if (thisSchema) {
+        var itemResult = thisSchema["executePreview"](sourcePath, src, scope);
+        for (var keyS in itemResult) {
+          var _key2 = keyS;
+          res[_key2] = itemResult[_key2];
+        }
+        return res;
       }
       res[sourcePath] = {
         status: "error",
-        message: "The schema of this value is wrong. Expected a object union schema, but union key is not a string. Got: '".concat(JSON.stringify(unionKey, null, 2), "'")
+        message: "Could not find a matching (object) schema for the discriminated union key: ".concat(unionKey)
       };
       return res;
     }
   }]);
 }(Schema);
-var union = function union(key) {
-  for (var _len = arguments.length, objects = new Array(_len > 1 ? _len - 1 : 0), _key4 = 1; _key4 < _len; _key4++) {
-    objects[_key4 - 1] = arguments[_key4];
+var discriminatedUnion = function discriminatedUnion(key) {
+  for (var _len = arguments.length, objects = new Array(_len > 1 ? _len - 1 : 0), _key3 = 1; _key3 < _len; _key3++) {
+    objects[_key3 - 1] = arguments[_key3];
   }
-  return new UnionSchema(key, objects);
+  return new DiscriminatedUnionSchema(key, objects);
 };
 
 var RegEx$1 = /^(https?:\/\/[^/]+)\/file\/p\/([^/]+)\/b\/([^/]+)\/v\/([^/]+)\/h\/([^/]+)\/f\/([^/]+)\/p\/(.+)$/;
@@ -2930,17 +3482,94 @@ var ImageSchema = /*#__PURE__*/function (_Schema) {
     _this.previewInput = previewInput;
     return _this;
   }
+
+  /**
+   * Describe this field.
+   *
+   * The description is shown next to the field's label in the Val editor, so
+   * it is where you say what an editor needs to know but the field name cannot
+   * carry. It also travels in the serialized schema, which is what the AI
+   * assistant and the MCP tools read.
+   *
+   * Pass `null` to clear a description set earlier.
+   *
+   * @example
+   * const schema = s
+   *   .image()
+   *   .describe("Shown at the top of the page, 16:9 works best");
+   * export default c.define("/example.val.ts", schema, {
+   *   path: "/public/val/example.png",
+   *   width: 100,
+   *   height: 100,
+   *   mimeType: "image/png",
+   * });
+   */
   _inherits(ImageSchema, _Schema);
   return _createClass(ImageSchema, [{
     key: "describe",
     value: function describe(description) {
       return new ImageSchema(this.options, this.opt, this.isRemote, this.customValidateFunctions, this.moduleMetadata, this.isReadonly, this.isHidden, description !== null && description !== void 0 ? description : undefined, this.renderInput, this.previewInput);
     }
+
+    /**
+     * Store the image on Val's remote content host instead of in your repository.
+     *
+     * The bytes still go into the patch store when the image is uploaded — the
+     * push to the remote host happens at publish. What changes is where the
+     * published image lives: `path` becomes a remote URL rather than a path
+     * under `/public`, so the repository does not grow with every upload.
+     *
+     * The `path` of a remote image is a URL on the content host, and it is not
+     * something to write by hand: upload the image in the Studio, or write a
+     * local path and let `npx val validate --fix` upload it and rewrite the
+     * `path` to the ref below.
+     *
+     * @example
+     * const schema = s
+     *   .image({ accept: "image/webp", directory: "/public/val/images" })
+     *   .remote();
+     * export default c.define("/example.val.ts", schema, {
+     *   path: "https://remote.val.build/file/p/my-project/b/01/v/1.0.0/h/8f2a1c/f/3b9d70/p/public/val/images/example.webp",
+     *   width: 100,
+     *   height: 100,
+     *   mimeType: "image/webp",
+     * });
+     */
   }, {
     key: "remote",
     value: function remote() {
       return new ImageSchema(this.options, this.opt, true, this.customValidateFunctions, this.moduleMetadata, this.isReadonly, this.isHidden, this.description, this.renderInput, this.previewInput);
     }
+
+    /**
+     * Add a custom validation rule to this field.
+     *
+     * The function is called with the field's value and returns `false` when the
+     * value is fine, or a STRING with the message to show when it is not. Call it
+     * more than once to add more rules — they all run, and every message is
+     * reported.
+     *
+     * Write the check as a ternary, not as `ok || "message"`: that returns `true`
+     * when the value is fine, and `true` is not one of the two answers.
+     *
+     * Validation runs in the Studio as you type, in `npx val validate` and
+     * before a publish.
+     *
+     * The second argument carries the `path` of the field being validated, for
+     * when the message needs to say where the problem is.
+     *
+     * @example
+     * const schema = s.image().validate((val) =>
+     *   val.alt ? false : "Every image needs alt text",
+     * );
+     * export default c.define("/example.val.ts", schema, {
+     *   path: "/public/val/example.png",
+     *   width: 100,
+     *   height: 100,
+     *   mimeType: "image/png",
+     *   alt: "An example",
+     * });
+     */
   }, {
     key: "validate",
     value: function validate(validationFunction) {
@@ -3158,6 +3787,17 @@ var ImageSchema = /*#__PURE__*/function (_Schema) {
      * instead of a preview row that navigates to it.
      *
      * Static configuration, not a callback — see `render.ts`.
+     *
+     * @example
+     * const schema = s.array(s.image().render({ as: "inline" }));
+     * export default c.define("/example.val.ts", schema, [
+     *   {
+     *     path: "/public/val/example.png",
+     *     width: 100,
+     *     height: 100,
+     *     mimeType: "image/png",
+     *   },
+     * ]);
      */
   }, {
     key: "render",
@@ -3169,6 +3809,23 @@ var ImageSchema = /*#__PURE__*/function (_Schema) {
      * How this VALUE is shown where a preview of it is needed — a row in a
      * sortable list, a reference dropdown, a search hit. Never how the field
      * itself is edited (that is `render`). See `preview.ts`.
+     *
+     * @example
+     * const schema = s.array(
+     *   s.image().preview(({ val }) => ({
+     *     title: val.alt ?? "Image",
+     *     image: val,
+     *   })),
+     * );
+     * export default c.define("/example.val.ts", schema, [
+     *   {
+     *     path: "/public/val/example.png",
+     *     width: 100,
+     *     height: 100,
+     *     mimeType: "image/png",
+     *     alt: "An example",
+     *   },
+     * ]);
      */
   }, {
     key: "preview",
@@ -3265,6 +3922,21 @@ var RouteSchema = /*#__PURE__*/function (_Schema) {
     _this.previewInput = previewInput;
     return _this;
   }
+
+  /**
+   * Describe this field.
+   *
+   * The description is shown next to the field's label in the Val editor, so
+   * it is where you say what an editor needs to know but the field name cannot
+   * carry. It also travels in the serialized schema, which is what the AI
+   * assistant and the MCP tools read.
+   *
+   * Pass `null` to clear a description set earlier.
+   *
+   * @example
+   * const schema = s.route().describe("Where the button goes");
+   * export default c.define("/example.val.ts", schema, "/a-page-slug");
+   */
   _inherits(RouteSchema, _Schema);
   return _createClass(RouteSchema, [{
     key: "describe",
@@ -3311,6 +3983,27 @@ var RouteSchema = /*#__PURE__*/function (_Schema) {
         exclude: pattern
       }), this.opt, this.customValidateFunctions, this.isReadonly, this.isHidden, this.description, this.renderInput, this.previewInput);
     }
+
+    /**
+     * Add a custom validation rule to this field.
+     *
+     * The function is called with the field's value and returns `false` when the
+     * value is fine, or a STRING with the message to show when it is not. Call it
+     * more than once to add more rules — they all run, and every message is
+     * reported.
+     *
+     * Write the check as a ternary, not as `ok || "message"`: that returns `true`
+     * when the value is fine, and `true` is not one of the two answers.
+     *
+     * Validation runs in the Studio as you type, in `npx val validate` and
+     * before a publish.
+     *
+     * @example
+     * const schema = s.route().validate((val) =>
+     *   val.endsWith("/") ? "Leave off the trailing slash" : false,
+     * );
+     * export default c.define("/example.val.ts", schema, "/a-page-slug");
+     */
   }, {
     key: "validate",
     value: function validate(validationFunction) {
@@ -3397,6 +4090,10 @@ var RouteSchema = /*#__PURE__*/function (_Schema) {
      * instead of a preview row that navigates to it.
      *
      * Static configuration, not a callback — see `render.ts`.
+     *
+     * @example
+     * const schema = s.array(s.route().render({ as: "inline" }));
+     * export default c.define("/example.val.ts", schema, ["/a-page-slug"]);
      */
   }, {
     key: "render",
@@ -3408,6 +4105,12 @@ var RouteSchema = /*#__PURE__*/function (_Schema) {
      * How this VALUE is shown where a preview of it is needed — a row in a
      * sortable list, a reference dropdown, a search hit. Never how the field
      * itself is edited (that is `render`). See `preview.ts`.
+     *
+     * @example
+     * const schema = s.array(
+     *   s.route().preview(({ val }) => ({ title: val })),
+     * );
+     * export default c.define("/example.val.ts", schema, ["/a-page-slug"]);
      */
   }, {
     key: "preview",
@@ -3488,12 +4191,42 @@ var RichTextSchema = /*#__PURE__*/function (_Schema) {
     _this.previewInput = previewInput;
     return _this;
   }
+
+  /**
+   * Describe this field.
+   *
+   * The description is shown next to the field's label in the Val editor, so
+   * it is where you say what an editor needs to know but the field name cannot
+   * carry. It also travels in the serialized schema, which is what the AI
+   * assistant and the MCP tools read.
+   *
+   * Pass `null` to clear a description set earlier.
+   *
+   * @example
+   * const schema = s.richtext().describe("The body of the article");
+   * export default c.define("/example.val.ts", schema, [
+   *   { tag: "p", children: ["Hello"] },
+   * ]);
+   */
   _inherits(RichTextSchema, _Schema);
   return _createClass(RichTextSchema, [{
     key: "describe",
     value: function describe(description) {
       return new RichTextSchema(this.options, this.opt, this.customValidateFunctions, this.isReadonly, this.isHidden, description !== null && description !== void 0 ? description : undefined, this.renderInput, this.previewInput);
     }
+
+    /**
+     * Validate that the rich text holds at most `max` characters.
+     *
+     * Counted over the TEXT, not the markup: tags, attributes and the structure
+     * of the document do not add to it.
+     *
+     * @example
+     * const schema = s.richtext().maxLength(280);
+     * export default c.define("/example.val.ts", schema, [
+     *   { tag: "p", children: ["Hello"] },
+     * ]);
+     */
   }, {
     key: "maxLength",
     value: function maxLength(max) {
@@ -3501,6 +4234,19 @@ var RichTextSchema = /*#__PURE__*/function (_Schema) {
         maxLength: max
       }), this.opt, this.customValidateFunctions, this.isReadonly, this.isHidden, this.description, this.renderInput, this.previewInput);
     }
+
+    /**
+     * Validate that the rich text holds at least `min` characters.
+     *
+     * Counted over the TEXT, not the markup: tags, attributes and the structure
+     * of the document do not add to it.
+     *
+     * @example
+     * const schema = s.richtext().minLength(20).maxLength(280);
+     * export default c.define("/example.val.ts", schema, [
+     *   { tag: "p", children: ["Long enough to clear the minimum length."] },
+     * ]);
+     */
   }, {
     key: "minLength",
     value: function minLength(min) {
@@ -3508,6 +4254,29 @@ var RichTextSchema = /*#__PURE__*/function (_Schema) {
         minLength: min
       }), this.opt, this.customValidateFunctions, this.isReadonly, this.isHidden, this.description, this.renderInput, this.previewInput);
     }
+
+    /**
+     * Add a custom validation rule to this field.
+     *
+     * The function is called with the field's value and returns `false` when the
+     * value is fine, or a STRING with the message to show when it is not. Call it
+     * more than once to add more rules — they all run, and every message is
+     * reported.
+     *
+     * Write the check as a ternary, not as `ok || "message"`: that returns `true`
+     * when the value is fine, and `true` is not one of the two answers.
+     *
+     * Validation runs in the Studio as you type, in `npx val validate` and
+     * before a publish.
+     *
+     * @example
+     * const schema = s.richtext().validate((val) =>
+     *   val.length > 0 ? false : "Write something",
+     * );
+     * export default c.define("/example.val.ts", schema, [
+     *   { tag: "p", children: ["Hello"] },
+     * ]);
+     */
   }, {
     key: "validate",
     value: function validate(validationFunction) {
@@ -3955,7 +4724,7 @@ var RichTextSchema = /*#__PURE__*/function (_Schema) {
   }, {
     key: "nullable",
     value: function nullable() {
-      return new RichTextSchema(this.options, true, [], this.isReadonly, this.isHidden, this.description, this.renderInput, this.previewInput);
+      return new RichTextSchema(this.options, true, this.customValidateFunctions, this.isReadonly, this.isHidden, this.description, this.renderInput, this.previewInput);
     }
   }, {
     key: "readonly",
@@ -3983,6 +4752,12 @@ var RichTextSchema = /*#__PURE__*/function (_Schema) {
      * instead of a preview row that navigates to it.
      *
      * Static configuration, not a callback — see `render.ts`.
+     *
+     * @example
+     * const schema = s.array(s.richtext().render({ as: "inline" }));
+     * export default c.define("/example.val.ts", schema, [
+     *   [{ tag: "p", children: ["Hello"] }],
+     * ]);
      */
   }, {
     key: "render",
@@ -3994,6 +4769,16 @@ var RichTextSchema = /*#__PURE__*/function (_Schema) {
      * How this VALUE is shown where a preview of it is needed — a row in a
      * sortable list, a reference dropdown, a search hit. Never how the field
      * itself is edited (that is `render`). See `preview.ts`.
+     *
+     * @example
+     * const schema = s.array(
+     *   s.richtext().preview(({ val }) => ({
+     *     title: val.length > 0 ? "Rich text" : "Empty",
+     *   })),
+     * );
+     * export default c.define("/example.val.ts", schema, [
+     *   [{ tag: "p", children: ["Hello"] }],
+     * ]);
      */
   }, {
     key: "preview",
@@ -4456,6 +5241,68 @@ function hasInlineExternalEntries(source) {
   return _typeof(source) === "object" && source !== null && !Array.isArray(source) && !isExternal(source) && Object.keys(source).length > 0;
 }
 
+/**
+ * The keys a record is REQUIRED to hold, where its key schema says what they are.
+ *
+ * Most records have an open key set — `s.record(s.string(), item)` holds
+ * whatever anyone adds — and this returns `null` for those. A record keyed by
+ * something that enumerates its values is different in kind: the keys are part
+ * of the schema, so a missing one is a hole in the content rather than content
+ * nobody has written yet.
+ *
+ * Two key schemas enumerate. A union of literals does it locally, so its keys
+ * are here. `s.locale()` does it in the settings module, which is another file
+ * and so cannot be read from a serialized schema — that case says only which
+ * kind it is, and is resolved against `locales.available` by
+ * `resolveSchemaSourceFixes`, the same crossing `keyOf` and `route` make.
+ */
+
+/**
+ * What `key` requires a record to hold, or `null` where it requires nothing.
+ *
+ * Works from the SERIALIZED schema so that the Studio, the validation worker
+ * and the server all answer this the same way — none of them has the schema
+ * instance, and `SchemaStore` deliberately holds serialized schemas only.
+ */
+function declaredKeySetOf(key) {
+  if (key === undefined) {
+    return null;
+  }
+  if (key.type === "literal") {
+    return {
+      kind: "literals",
+      keys: [key.value]
+    };
+  }
+  if (key.type === "enum") {
+    // An enum names every value it may take, so those values ARE the key set.
+    // `discriminated-union` is deliberately absent: it discriminates objects
+    // and cannot be a record key at all.
+    return {
+      kind: "literals",
+      keys: _toConsumableArray(key.values)
+    };
+  }
+  if (key.type === "locale") {
+    return {
+      kind: "locale"
+    };
+  }
+  return null;
+}
+
+/**
+ * The declared keys a record is missing, in the order the schema declares them.
+ *
+ * Declaration order rather than the source's: this is read as "what is left to
+ * write", and the answer should not reshuffle itself as entries are added.
+ */
+function missingDeclaredKeys(declared, present) {
+  return declared.filter(function (key) {
+    return !present.includes(key);
+  });
+}
+
 /**
  * The source type of a `.jsonValues()` record: every entry value is EITHER a
  * lazily loaded {@link JsonSource} whose resolved content is the (loosened, see
@@ -4487,6 +5334,16 @@ var RecordSchema = /*#__PURE__*/function (_Schema) {
     var externalLabel = arguments.length > 12 && arguments[12] !== undefined ? arguments[12] : null;
     _classCallCheck(this, RecordSchema);
     _this = _callSuper(this, RecordSchema);
+    /**
+     * The key set this record's schema declares, computed once.
+     *
+     * `declaredKeySetOf` reads a SERIALIZED schema, and serializing the key
+     * schema walks it — twice per validate, and once per record instance, for an
+     * answer that is a property of the schema and cannot move between them. A
+     * schema is built once and validated against many times, so the walk happens
+     * on the first question and not on any after it.
+     */
+    _defineProperty(_this, "declaredKeys", void 0);
     _this.item = item;
     _this.opt = opt;
     _this.customValidateFunctions = customValidateFunctions;
@@ -4502,19 +5359,62 @@ var RecordSchema = /*#__PURE__*/function (_Schema) {
     _this.externalLabel = externalLabel;
     return _this;
   }
+
+  /**
+   * Describe this field.
+   *
+   * The description is shown next to the field's label in the Val editor, so
+   * it is where you say what an editor needs to know but the field name cannot
+   * carry. It also travels in the serialized schema, which is what the AI
+   * assistant and the MCP tools read.
+   *
+   * Pass `null` to clear a description set earlier.
+   *
+   * @example
+   * const schema = s
+   *   .record(s.string())
+   *   .describe("Button labels, keyed by locale");
+   * export default c.define("/example.val.ts", schema, { en: "Read more" });
+   */
   _inherits(RecordSchema, _Schema);
   return _createClass(RecordSchema, [{
     key: "describe",
     value: function describe(description) {
       return new RecordSchema(this.item, this.opt, this.customValidateFunctions, this.currentRouter, this.keySchema, this.mediaOptions, this.isReadonly, this.isHidden, description !== null && description !== void 0 ? description : undefined, this.isJsonValues, this.previewInput, this.renderInput, this.externalLabel);
     }
-  }, {
-    key: "validate",
-    value: function validate(validationFunction) {
-      return new RecordSchema(this.item, this.opt, [].concat(_toConsumableArray(this.customValidateFunctions), [validationFunction]), this.currentRouter, this.keySchema, this.mediaOptions, this.isReadonly, this.isHidden, this.description, this.isJsonValues, this.previewInput, this.renderInput, this.externalLabel);
-    }
-  }, {
-    key: "executeValidate",
+
+    /**
+     * Add a custom validation rule to this field.
+     *
+     * The function is called with the field's value and returns `false` when the
+     * value is fine, or a STRING with the message to show when it is not. Call it
+     * more than once to add more rules — they all run, and every message is
+     * reported.
+     *
+     * Write the check as a ternary, not as `ok || "message"`: that returns `true`
+     * when the value is fine, and `true` is not one of the two answers.
+     *
+     * Validation runs in the Studio as you type, in `npx val validate` and
+     * before a publish.
+     *
+     * The function is given the whole record. To validate one entry, put a
+     * `.validate(...)` on the ITEM schema instead — that reports the error on
+     * the entry's own row, and on a `.jsonValues()` record it does not force
+     * every entry to be loaded.
+     *
+     * @example
+     * const schema = s.record(s.string()).validate((val) =>
+     *   "en" in val ? false : "There has to be an 'en' entry",
+     * );
+     * export default c.define("/example.val.ts", schema, { en: "Read more" });
+     */
+  }, {
+    key: "validate",
+    value: function validate(validationFunction) {
+      return new RecordSchema(this.item, this.opt, [].concat(_toConsumableArray(this.customValidateFunctions), [validationFunction]), this.currentRouter, this.keySchema, this.mediaOptions, this.isReadonly, this.isHidden, this.description, this.isJsonValues, this.previewInput, this.renderInput, this.externalLabel);
+    }
+  }, {
+    key: "executeValidate",
     value: function executeValidate(path, src) {
       var _this2 = this;
       var error = false;
@@ -4590,6 +5490,11 @@ var RecordSchema = /*#__PURE__*/function (_Schema) {
           error = _objectSpread2(_objectSpread2({}, error), {}, _defineProperty({}, path, [allFilesCheckError]));
         }
       }
+      // A record whose keys are declared by its schema holds every one of them,
+      // and an entry nobody has written yet is `null` rather than absent — so
+      // `null` is a value here, not a value of the wrong type, and the item
+      // schema is not asked about it.
+      var hasDeclaredKeys = this.declaredKeySet() !== null;
       Object.entries(src).forEach(function (_ref5) {
         var _ref6 = _slicedToArray(_ref5, 2),
           key = _ref6[0],
@@ -4629,7 +5534,7 @@ var RecordSchema = /*#__PURE__*/function (_Schema) {
             _this2.markKeyErrorsAtPath(entryErr, subPath);
           }
           error = _this2.mergeValidationErrors(error, entryErr);
-        } else if (_this2.isJsonValues && isJson(elem)) ; else {
+        } else if (hasDeclaredKeys && elem === null) ; else if (_this2.isJsonValues && isJson(elem)) ; else {
           // Falls through for a jsonValues record whose entry content is inlined
           // (loaded in the UI, or hand-authored): same as a plain record — validate
           // the value against the item schema.
@@ -4637,8 +5542,79 @@ var RecordSchema = /*#__PURE__*/function (_Schema) {
           error = _this2.mergeValidationErrors(error, subError);
         }
       });
+      var declaredKeys = this.getDeclaredKeysValidation(path, src);
+      error = this.mergeValidationErrors(error, declaredKeys);
+      var _iterator2 = _createForOfIteratorHelper(this.localeScopeErrors()),
+        _step2;
+      try {
+        for (_iterator2.s(); !(_step2 = _iterator2.n()).done;) {
+          var scopeError = _step2.value;
+          error = this.appendValidationError(error, path, scopeError.message, src, scopeError.schemaError);
+        }
+      } catch (err) {
+        _iterator2.e(err);
+      } finally {
+        _iterator2.f();
+      }
       return error;
     }
+
+    /**
+     * The check that a record with a DECLARED key set holds every one of them.
+     *
+     * `s.record(s.locale(), item)` has one entry per language and
+     * `s.record(s.union(s.literal("a"), s.literal("b")), item)` has both — the
+     * keys are part of the schema either way, so a missing one is a hole in the
+     * content rather than content nobody has written yet. TypeScript already
+     * demanded both keys of the second; this is the validator catching up, which
+     * is why the two now behave the same.
+     *
+     * Deferred to `resolveSchemaSourceFixes` even for the literal case, where the
+     * keys are known right here: a locale record's keys are in another file, and
+     * one code path for both is one message, one fix and one thing to be wrong.
+     */
+  }, {
+    key: "getDeclaredKeysValidation",
+    value: function getDeclaredKeysValidation(path, src) {
+      if (this.keySchema === null) {
+        return false;
+      }
+      var declared = this.declaredKeySet();
+      if (declared === null) {
+        return false;
+      }
+      return _defineProperty({}, path, [{
+        fixes: ["record:fill-keys"],
+        message: "Did not validate record keys. This error (record:fill-keys) should typically be processed by Val internally. Seeing this error most likely means you have a Val version mismatch.",
+        value: {
+          present: Object.keys(src),
+          declared: declared.kind === "literals" ? declared.keys : null
+        }
+      }]);
+    }
+  }, {
+    key: "declaredKeySet",
+    value: function declaredKeySet() {
+      if (this.declaredKeys === undefined) {
+        this.declaredKeys = this.keySchema === null ? null : declaredKeySetOf(this.keySchema["executeSerialize"]());
+      }
+      return this.declaredKeys;
+    }
+  }, {
+    key: "opensLocaleScope",
+    value: function opensLocaleScope() {
+      return this.keySchema !== null && this.keySchema["isLocaleField"]() ? "key" : null;
+    }
+  }, {
+    key: "localeScopeChildren",
+    value: function localeScopeChildren() {
+      // The KEY schema is not a child here. A locale key is what opens this
+      // record's scope; it is not something inside the scope.
+      return [{
+        key: "*",
+        schema: this.item
+      }];
+    }
   }, {
     key: "isRemoteUrl",
     value: function isRemoteUrl(url) {
@@ -4869,6 +5845,10 @@ var RecordSchema = /*#__PURE__*/function (_Schema) {
      * must come BEFORE `.external()`: afterwards the value is a `Schema`, and
      * there is no `.readonly()` left to call — which is the error the compiler
      * gives, and a clearer one than a runtime throw.
+     *
+     * @example
+     * const schema = s.record(s.string()).readonly();
+     * export default c.define("/example.val.ts", schema, { en: "Read more" });
      */
   }, {
     key: "readonly",
@@ -4882,11 +5862,54 @@ var RecordSchema = /*#__PURE__*/function (_Schema) {
       var isHidden = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : true;
       return new RecordSchema(this.item, this.opt, this.customValidateFunctions, this.currentRouter, this.keySchema, this.mediaOptions, this.isReadonly, isHidden, this.description, this.isJsonValues, this.previewInput, this.renderInput, this.externalLabel);
     }
+
+    /**
+     * Turn this record into a page router: its keys are route paths of your
+     * application, and they are validated against the router's conventions.
+     *
+     * `s.router(router, item)` builds the same thing in one call and is what
+     * most code should use — this is for adding a router to a record that
+     * already exists.
+     *
+     * @example
+     * import { nextAppRouter } from "../val.config";
+     * const schema = s
+     *   .record(s.object({ title: s.string() }))
+     *   .router(nextAppRouter);
+     * export default c.define("/app/[slug]/page.val.ts", schema, {
+     *   "/a-page-slug": { title: "First Page" },
+     * });
+     */
   }, {
     key: "router",
     value: function router(_router) {
       return new RecordSchema(this.item, this.opt, this.customValidateFunctions, _router, this.keySchema, this.mediaOptions, this.isReadonly, this.isHidden, this.description, this.isJsonValues, this.previewInput, this.renderInput, this.externalLabel);
     }
+
+    /**
+     * Allow the files in this gallery to be stored on Val's remote content host
+     * instead of in your repository.
+     *
+     * For `s.images()` and `s.files()`, which are records of media. Remote is off
+     * until this is called.
+     *
+     * Each entry is then keyed by its URL on the content host rather than by a
+     * path under `/public`. That key is not something to write by hand: upload
+     * in the Studio, or add a local path and let `npx val validate --fix`
+     * upload it and rewrite the key.
+     *
+     * @example
+     * const schema = s.images({ directory: "/public/val/images" }).remote();
+     * export default c.define("/content/images.val.ts", schema, {
+     *   "https://remote.val.build/file/p/my-project/b/01/v/1.0.0/h/8f2a1c/f/3b9d70/p/public/val/images/hero.webp":
+     *     {
+     *       width: 1920,
+     *       height: 1080,
+     *       mimeType: "image/webp",
+     *       alt: "Hero image",
+     *     },
+     * });
+     */
   }, {
     key: "remote",
     value: function remote() {
@@ -4908,6 +5931,20 @@ var RecordSchema = /*#__PURE__*/function (_Schema) {
      * nested inside an object/array/record is rejected at startup with a module
      * error, because the single-entry fetch endpoint, the Studio's content
      * substitution and content validation are all root-only.
+     *
+     * Must come BEFORE `.validate()` and `.preview()`: those are typed against
+     * the un-lazy source shape, so a validator or preview declared first cannot
+     * be carried over, and declaring one first throws rather than silently
+     * dropping it.
+     *
+     * @example
+     * import { nextAppRouter } from "../val.config";
+     * const schema = s
+     *   .router(nextAppRouter, s.object({ title: s.string(), body: s.string() }))
+     *   .jsonValues();
+     * export default c.define("/app/support/[slug]/page.val.ts", schema, {
+     *   "/support/faq": c.json(() => import("./content/faq.val.json")),
+     * });
      */
   }, {
     key: "jsonValues",
@@ -4955,6 +5992,19 @@ var RecordSchema = /*#__PURE__*/function (_Schema) {
      * nested external record would leave a hole in the middle of a module's
      * source, and the Studio, patching and validation all assume a module's
      * source is complete apart from its entries.
+     *
+     * @example
+     * const schema = s.record(s.object({ title: s.string() })).external("posts");
+     * export default c.define("/content/posts.val.ts", schema, c.external());
+     *
+     * @example
+     * // A read-only external record: `.readonly()` must come FIRST, because
+     * // afterwards there is no `.readonly()` left on the type to call.
+     * const schema = s
+     *   .record(s.object({ title: s.string() }))
+     *   .readonly()
+     *   .external("posts");
+     * export default c.define("/content/posts.val.ts", schema, c.external());
      */
   }, {
     key: "external",
@@ -5214,6 +6264,25 @@ var RecordSchema = /*#__PURE__*/function (_Schema) {
      * is the item of another container, in search, in references. What its
      * entries show is the ITEM schema's `preview`, not this. Never how the field
      * is edited (that is `render`). See `preview.ts`.
+     *
+     * @example
+     * // The preview of the RECORD, for where it is an item of something else.
+     * // What its own rows show is the ITEM schema's preview — see below.
+     * const labels = s.record(s.string()).preview(({ val }) => ({
+     *   title: `${Object.keys(val).length} locales`,
+     * }));
+     * export default c.define("/example.val.ts", s.array(labels), [
+     *   { en: "Read more" },
+     * ]);
+     *
+     * @example
+     * // Rows of a record come from the ITEM's preview, not the record's:
+     * const author = s
+     *   .object({ name: s.string(), role: s.string() })
+     *   .preview(({ val }) => ({ title: val.name, subtitle: val.role }));
+     * export default c.define("/example.val.ts", s.record(author), {
+     *   ada: { name: "Ada", role: "Engineer" },
+     * });
      */
   }, {
     key: "preview",
@@ -5227,6 +6296,10 @@ var RecordSchema = /*#__PURE__*/function (_Schema) {
      * instead of a preview row that navigates to it.
      *
      * Static configuration, not a callback — see `render.ts`.
+     *
+     * @example
+     * const schema = s.array(s.record(s.string()).render({ as: "inline" }));
+     * export default c.define("/example.val.ts", schema, [{ en: "Read more" }]);
      */
   }, {
     key: "render",
@@ -5236,6 +6309,23 @@ var RecordSchema = /*#__PURE__*/function (_Schema) {
   }]);
 }(Schema);
 
+/**
+ * The source of a record, given what its key schema says about its keys.
+ *
+ * A key schema that ENUMERATES its keys (a union of literals, or `s.locale()`)
+ * makes every one of them an entry of the record, and an entry nobody has
+ * written yet is `null` rather than absent — so the value type widens by
+ * `null`. That is the whole of option F at the type level: a half-translated
+ * record is a record with nulls in it, which is data you can count, filter and
+ * see in a diff, rather than keys that are simply not there.
+ *
+ * For a union of literals TypeScript already required every key, since
+ * `SelectorOfSchema<K>` is the literal union itself. `s.locale()` is a flavoured
+ * string, so it requires nothing here and the requirement is the validator's —
+ * deliberately: which languages exist is in the settings module, where the
+ * project can change it without a deploy.
+ */
+
 // Overload: with key schema
 
 // Overload: without key schema
@@ -5274,6 +6364,31 @@ function record(keyOrSchema, schema) {
  * written without removing the key.
  */
 
+/**
+ * The languages this project publishes.
+ *
+ * Content rather than configuration, and deliberately: which languages a site
+ * has is a decision the people who write it make, and under a build-time
+ * constant it took a developer and a deploy. It is the same move `assistant`
+ * makes with `enabled`.
+ *
+ * Val ships no list of its own. A project with no `locales` section has not
+ * said it is translated, and nothing about locales appears anywhere — no picker
+ * in the Studio, no checks, nothing.
+ *
+ * **This list is a decision with a blast radius.** Every locale in content is
+ * checked against it, so removing one invalidates the content that uses it, and
+ * adding one leaves every locale-keyed record short of a language until it is
+ * filled in. That is the intended behaviour — a language that is declared and
+ * missing everywhere is worth being told about — but it is why the Studio warns
+ * before saving a removal rather than treating this as an ordinary field.
+ *
+ * There is no default language, deliberately. Every locale-specific field asks
+ * which language it is in, and a default is exactly the answer that lets that
+ * question go unanswered — content ends up filed under a language nobody chose,
+ * which is the state translation is meant to make visible.
+ */
+
 /**
  * The assistant: whether editors have one, and what it is told about the
  * project on every message.
@@ -5334,8 +6449,32 @@ settings) {
   return "unconfigured";
 }
 
-var BooleanSchema = /*#__PURE__*/function (_Schema) {
-  function BooleanSchema() {
+/**
+ * One of the languages the project publishes.
+ *
+ * The set is NOT here. It is declared in the settings module — `locales.available`
+ * — so that adding a language is something the people who write the content can
+ * do, and so that one list drives validation, the Studio's picker and the
+ * translation notes. This schema knows only that the value is one of them, which
+ * is checked cross-module through the `locale:check-locale` fix, exactly as
+ * `keyOf` and `route` check theirs.
+ *
+ * Never stega encoded (see `stegaEncode.ts`): a locale goes into `<html lang>`,
+ * into `hreflang` and into `Intl` constructors, none of which survive invisible
+ * characters.
+ */
+var LocaleSchema = /*#__PURE__*/function (_Schema) {
+  /**
+   * Type-only marker: as a record key, this schema DECLARES the key set.
+   *
+   * `declare` so it exists in the type and nowhere at runtime — reading it off
+   * an instance gives `undefined`, and nothing should. It is how `record()`
+   * knows to type entries as `Item | null`: a language nobody has translated
+   * into is a null entry, not an absent key. See `DeclaredKeySet` and
+   * `RecordSrcOf`.
+   */
+
+  function LocaleSchema() {
     var _this;
     var opt = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : false;
     var customValidateFunctions = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : [];
@@ -5344,8 +6483,8 @@ var BooleanSchema = /*#__PURE__*/function (_Schema) {
     var description = arguments.length > 4 ? arguments[4] : undefined;
     var renderInput = arguments.length > 5 && arguments[5] !== undefined ? arguments[5] : null;
     var previewInput = arguments.length > 6 && arguments[6] !== undefined ? arguments[6] : null;
-    _classCallCheck(this, BooleanSchema);
-    _this = _callSuper(this, BooleanSchema);
+    _classCallCheck(this, LocaleSchema);
+    _this = _callSuper(this, LocaleSchema);
     _this.opt = opt;
     _this.customValidateFunctions = customValidateFunctions;
     _this.isReadonly = isReadonly;
@@ -5355,30 +6494,80 @@ var BooleanSchema = /*#__PURE__*/function (_Schema) {
     _this.previewInput = previewInput;
     return _this;
   }
-  _inherits(BooleanSchema, _Schema);
-  return _createClass(BooleanSchema, [{
+
+  /**
+   * A note to whoever edits this field, shown under it in the Studio.
+   *
+   * Pass `null` to clear a description set earlier.
+   *
+   * @example
+   * const schema = s.object({
+   *   locale: s.locale().describe("The language everything below is written in"),
+   *   title: s.string(),
+   * });
+   * export default c.define("/example.val.ts", schema, {
+   *   locale: "nb-NO",
+   *   title: "Vinterjakke",
+   * });
+   */
+  _inherits(LocaleSchema, _Schema);
+  return _createClass(LocaleSchema, [{
     key: "describe",
     value: function describe(description) {
-      return new BooleanSchema(this.opt, this.customValidateFunctions, this.isReadonly, this.isHidden, description !== null && description !== void 0 ? description : undefined, this.renderInput, this.previewInput);
+      return new LocaleSchema(this.opt, this.customValidateFunctions, this.isReadonly, this.isHidden, description !== null && description !== void 0 ? description : undefined, this.renderInput, this.previewInput);
     }
+
+    /**
+     * A check of your own, on top of "is this one of the project's languages".
+     *
+     * Return a message when the value is WRONG and `false` when it is fine — the
+     * two answers are a complaint and no complaint, so write the check as a
+     * ternary rather than as `ok || "message"`, which returns `true` and `true`
+     * is neither.
+     *
+     * @example
+     * const schema = s.object({
+     *   locale: s.locale().validate((val) =>
+     *     val === "en-US" ? "This section is not translated into English yet" : false,
+     *   ),
+     *   title: s.string(),
+     * });
+     * export default c.define("/example.val.ts", schema, {
+     *   locale: "nb-NO",
+     *   title: "Vinterjakke",
+     * });
+     */
   }, {
     key: "validate",
     value: function validate(validationFunction) {
-      return new BooleanSchema(this.opt, [].concat(_toConsumableArray(this.customValidateFunctions), [validationFunction]), this.isReadonly, this.isHidden, this.description, this.renderInput, this.previewInput);
+      return new LocaleSchema(this.opt, this.customValidateFunctions.concat(validationFunction), this.isReadonly, this.isHidden, this.description, this.renderInput, this.previewInput);
     }
   }, {
     key: "executeValidate",
     value: function executeValidate(path, src) {
+      var customValidationErrors = this.executeCustomValidateFunctions(src, this.customValidateFunctions, {
+        path: path
+      });
       if (this.opt && (src === null || src === undefined)) {
-        return false;
+        return customValidationErrors.length > 0 ? _defineProperty({}, path, customValidationErrors) : false;
       }
-      if (typeof src !== "boolean") {
+      if (typeof src !== "string") {
         return _defineProperty({}, path, [{
-          message: "Expected 'boolean', got '".concat(_typeof(src), "'"),
+          message: "Expected 'string', got '".concat(_typeof(src), "'"),
           value: src
         }]);
       }
-      return false;
+      return _defineProperty({}, path, [].concat(_toConsumableArray(customValidationErrors), [{
+        // Which languages exist is in another module, so this cannot be
+        // answered here — the same shape `keyOf` and `route` use, resolved by
+        // `resolveSchemaSourceFixes` against the settings module.
+        fixes: ["locale:check-locale"],
+        message: "Did not validate locale. This error (locale:check-locale) should typically be processed by Val internally. Seeing this error most likely means you have a Val version mismatch.",
+        value: {
+          locale: src,
+          sourcePath: path
+        }
+      }]));
     }
   }, {
     key: "executeAssert",
@@ -5389,45 +6578,42 @@ var BooleanSchema = /*#__PURE__*/function (_Schema) {
           data: src
         };
       }
-      if (src === null) {
-        return {
-          success: false,
-          errors: _defineProperty({}, path, [{
-            message: "Expected 'boolean', got 'null'",
-            typeError: true
-          }])
-        };
-      }
-      if (typeof src !== "boolean") {
+      if (typeof src === "string") {
         return {
-          success: false,
-          errors: _defineProperty({}, path, [{
-            message: "Expected 'boolean', got '".concat(_typeof(src), "'"),
-            typeError: true
-          }])
+          success: true,
+          data: src
         };
       }
       return {
-        success: true,
-        data: src
+        success: false,
+        errors: _defineProperty({}, path, [{
+          message: "Expected 'string', got '".concat(_typeof(src), "'"),
+          typeError: true
+        }])
       };
     }
   }, {
     key: "nullable",
     value: function nullable() {
-      return new BooleanSchema(true, [], this.isReadonly, this.isHidden, this.description, this.renderInput, this.previewInput);
+      // Asserted whole, exactly as `RouteSchema.nullable` does: the source type
+      // widens by `null` while the caller's validators and preview stay typed
+      // against the value, and `executeValidate` returns before either sees one.
+      return new LocaleSchema(true, this.customValidateFunctions, this.isReadonly, this.isHidden, this.description, this.renderInput, this.previewInput);
     }
   }, {
     key: "readonly",
     value: function readonly() {
-      var isReadonly = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : true;
-      return new BooleanSchema(this.opt, this.customValidateFunctions, isReadonly, this.isHidden, this.description, this.renderInput, this.previewInput);
+      return new LocaleSchema(this.opt, this.customValidateFunctions, true, this.isHidden, this.description, this.renderInput, this.previewInput);
     }
   }, {
     key: "hidden",
     value: function hidden() {
-      var isHidden = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : true;
-      return new BooleanSchema(this.opt, this.customValidateFunctions, this.isReadonly, isHidden, this.description, this.renderInput, this.previewInput);
+      return new LocaleSchema(this.opt, this.customValidateFunctions, this.isReadonly, true, this.description, this.renderInput, this.previewInput);
+    }
+  }, {
+    key: "isLocaleField",
+    value: function isLocaleField() {
+      return true;
     }
   }, {
     key: "executeCustomValidateAt",
@@ -5438,27 +6624,33 @@ var BooleanSchema = /*#__PURE__*/function (_Schema) {
     }
 
     /**
-     * How this field is laid out in the editor when it is the item of an array
-     * or record: `{ as: "inline" }` renders the field itself inside each row,
-     * instead of a preview row that navigates to it.
-     *
+     * How this field is laid out where it is the item of an array or a record.
      * Static configuration, not a callback — see `render.ts`.
+     *
+     * @example
+     * const schema = s.array(s.locale().render({ as: "inline" }));
+     * export default c.define("/example.val.ts", schema, ["nb-NO", "en-US"]);
      */
   }, {
     key: "render",
     value: function render(input) {
-      return new BooleanSchema(this.opt, this.customValidateFunctions, this.isReadonly, this.isHidden, this.description, input, this.previewInput);
+      return new LocaleSchema(this.opt, this.customValidateFunctions, this.isReadonly, this.isHidden, this.description, input, this.previewInput);
     }
 
     /**
-     * How this VALUE is shown where a preview of it is needed — a row in a
-     * sortable list, a reference dropdown, a search hit. Never how the field
+     * How this VALUE is shown where a preview of it is needed. Never how the field
      * itself is edited (that is `render`). See `preview.ts`.
+     *
+     * @example
+     * const schema = s.array(
+     *   s.locale().preview(({ val }) => ({ title: val })),
+     * );
+     * export default c.define("/example.val.ts", schema, ["nb-NO", "en-US"]);
      */
   }, {
     key: "preview",
     value: function preview(select) {
-      return new BooleanSchema(this.opt, this.customValidateFunctions, this.isReadonly, this.isHidden, this.description, this.renderInput, select);
+      return new LocaleSchema(this.opt, this.customValidateFunctions, this.isReadonly, this.isHidden, this.description, this.renderInput, select);
     }
   }, {
     key: "executePreviewItem",
@@ -5480,7 +6672,7 @@ var BooleanSchema = /*#__PURE__*/function (_Schema) {
     value: function executeSerialize() {
       var _this$renderInput, _this$customValidateF;
       return {
-        type: "boolean",
+        type: "locale",
         render: (_this$renderInput = this.renderInput) !== null && _this$renderInput !== void 0 ? _this$renderInput : undefined,
         preview: this.previewInput ? true : undefined,
         opt: this.opt,
@@ -5497,71 +6689,421 @@ var BooleanSchema = /*#__PURE__*/function (_Schema) {
     }
   }]);
 }(Schema);
-var _boolean = function _boolean() {
-  return new BooleanSchema();
-};
 
 /**
- * An object whose keys are all optional: absent means unset.
+ * Define one of the project's languages.
  *
- * Both the settings module itself and each of its sections are this. See
- * {@link SettingsSource} for why settings cannot be an object schema, and
- * {@link settings} for what a settings module holds.
+ * The languages themselves are declared in the settings module, under
+ * `locales.available` — this says only that a value is one of them.
  *
- * There is no `describe`, `validate`, `render` or `preview` on purpose: the
- * shape is Val's, not the schema author's — `s.settings()` takes no arguments —
- * and the Studio renders each section with a UI built for it.
+ * @example // a field: everything under this object is in this language
+ * const schema = s.object({ locale: s.locale(), title: s.string() });
+ *
+ * @example // a key: one entry per language
+ * const schema = s.record(s.locale(), s.object({ title: s.string() }));
  */
-var SettingsSchema = /*#__PURE__*/function (_Schema) {
-  function SettingsSchema(items) {
+var locale = function locale() {
+  return new LocaleSchema();
+};
+
+var BooleanSchema = /*#__PURE__*/function (_Schema) {
+  function BooleanSchema() {
     var _this;
-    var opt = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : false;
+    var opt = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : false;
+    var customValidateFunctions = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : [];
     var isReadonly = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : false;
     var isHidden = arguments.length > 3 && arguments[3] !== undefined ? arguments[3] : false;
     var description = arguments.length > 4 ? arguments[4] : undefined;
-    _classCallCheck(this, SettingsSchema);
-    _this = _callSuper(this, SettingsSchema);
-    _this.items = items;
+    var renderInput = arguments.length > 5 && arguments[5] !== undefined ? arguments[5] : null;
+    var previewInput = arguments.length > 6 && arguments[6] !== undefined ? arguments[6] : null;
+    _classCallCheck(this, BooleanSchema);
+    _this = _callSuper(this, BooleanSchema);
     _this.opt = opt;
+    _this.customValidateFunctions = customValidateFunctions;
     _this.isReadonly = isReadonly;
     _this.isHidden = isHidden;
     _this.description = description;
+    _this.renderInput = renderInput;
+    _this.previewInput = previewInput;
     return _this;
   }
-  _inherits(SettingsSchema, _Schema);
-  return _createClass(SettingsSchema, [{
+
+  /**
+   * Describe this field.
+   *
+   * The description is shown next to the field's label in the Val editor, so
+   * it is where you say what an editor needs to know but the field name cannot
+   * carry. It also travels in the serialized schema, which is what the AI
+   * assistant and the MCP tools read.
+   *
+   * Pass `null` to clear a description set earlier.
+   *
+   * @example
+   * const schema = s.boolean().describe("Show this item in the main menu");
+   * export default c.define("/example.val.ts", schema, true);
+   */
+  _inherits(BooleanSchema, _Schema);
+  return _createClass(BooleanSchema, [{
+    key: "describe",
+    value: function describe(description) {
+      return new BooleanSchema(this.opt, this.customValidateFunctions, this.isReadonly, this.isHidden, description !== null && description !== void 0 ? description : undefined, this.renderInput, this.previewInput);
+    }
+
+    /**
+     * Add a custom validation rule to this field.
+     *
+     * The function is called with the field's value and returns `false` when the
+     * value is fine, or a STRING with the message to show when it is not. Call it
+     * more than once to add more rules — they all run, and every message is
+     * reported.
+     *
+     * Write the check as a ternary, not as `ok || "message"`: that returns `true`
+     * when the value is fine, and `true` is not one of the two answers.
+     *
+     * Validation runs in the Studio as you type, in `npx val validate` and
+     * before a publish.
+     *
+     * @example
+     * const schema = s.boolean().validate((val) =>
+     *   val === true ? false : "This has to be on for now",
+     * );
+     * export default c.define("/example.val.ts", schema, true);
+     */
+  }, {
+    key: "validate",
+    value: function validate(validationFunction) {
+      return new BooleanSchema(this.opt, [].concat(_toConsumableArray(this.customValidateFunctions), [validationFunction]), this.isReadonly, this.isHidden, this.description, this.renderInput, this.previewInput);
+    }
+  }, {
     key: "executeValidate",
     value: function executeValidate(path, src) {
-      var error = false;
-      if (src === null || src === undefined) {
-        if (this.opt) {
-          return false;
-        }
-        return _defineProperty({}, path, [{
-          message: "Expected 'object', got '".concat(src, "'")
-        }]);
+      if (this.opt && (src === null || src === undefined)) {
+        return false;
       }
-      if (_typeof(src) !== "object") {
+      if (typeof src !== "boolean") {
         return _defineProperty({}, path, [{
-          message: "Expected 'object', got '".concat(_typeof(src), "'")
+          message: "Expected 'boolean', got '".concat(_typeof(src), "'"),
+          value: src
         }]);
       }
-      if (Array.isArray(src)) {
-        return _defineProperty({}, path, [{
-          message: "Expected 'object', got 'array'"
-        }]);
+      return false;
+    }
+  }, {
+    key: "executeAssert",
+    value: function executeAssert(path, src) {
+      if (this.opt && src === null) {
+        return {
+          success: true,
+          data: src
+        };
       }
-      for (var _i = 0, _Object$entries = Object.entries(this.items); _i < _Object$entries.length; _i++) {
-        var _Object$entries$_i = _slicedToArray(_Object$entries[_i], 2),
-          _key = _Object$entries$_i[0],
-          schema = _Object$entries$_i[1];
-        // Absent is the unset value, so there is nothing to validate. A key that
-        // is present as `undefined` is the same statement written differently.
-        if (src[_key] === undefined) {
-          continue;
-        }
-        var subPath = createValPathOfItem(path, _key);
-        if (!subPath) {
+      if (src === null) {
+        return {
+          success: false,
+          errors: _defineProperty({}, path, [{
+            message: "Expected 'boolean', got 'null'",
+            typeError: true
+          }])
+        };
+      }
+      if (typeof src !== "boolean") {
+        return {
+          success: false,
+          errors: _defineProperty({}, path, [{
+            message: "Expected 'boolean', got '".concat(_typeof(src), "'"),
+            typeError: true
+          }])
+        };
+      }
+      return {
+        success: true,
+        data: src
+      };
+    }
+  }, {
+    key: "nullable",
+    value: function nullable() {
+      return new BooleanSchema(true, this.customValidateFunctions, this.isReadonly, this.isHidden, this.description, this.renderInput, this.previewInput);
+    }
+  }, {
+    key: "readonly",
+    value: function readonly() {
+      var isReadonly = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : true;
+      return new BooleanSchema(this.opt, this.customValidateFunctions, isReadonly, this.isHidden, this.description, this.renderInput, this.previewInput);
+    }
+  }, {
+    key: "hidden",
+    value: function hidden() {
+      var isHidden = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : true;
+      return new BooleanSchema(this.opt, this.customValidateFunctions, this.isReadonly, isHidden, this.description, this.renderInput, this.previewInput);
+    }
+  }, {
+    key: "executeCustomValidateAt",
+    value: function executeCustomValidateAt(path, src) {
+      return this.executeCustomValidateFunctions(src, this.customValidateFunctions, {
+        path: path
+      });
+    }
+
+    /**
+     * How this field is laid out in the editor when it is the item of an array
+     * or record: `{ as: "inline" }` renders the field itself inside each row,
+     * instead of a preview row that navigates to it.
+     *
+     * Static configuration, not a callback — see `render.ts`.
+     *
+     * @example
+     * const schema = s.array(s.boolean().render({ as: "inline" }));
+     * export default c.define("/example.val.ts", schema, [true, false]);
+     */
+  }, {
+    key: "render",
+    value: function render(input) {
+      return new BooleanSchema(this.opt, this.customValidateFunctions, this.isReadonly, this.isHidden, this.description, input, this.previewInput);
+    }
+
+    /**
+     * How this VALUE is shown where a preview of it is needed — a row in a
+     * sortable list, a reference dropdown, a search hit. Never how the field
+     * itself is edited (that is `render`). See `preview.ts`.
+     *
+     * @example
+     * const schema = s.array(
+     *   s.boolean().preview(({ val }) => ({ title: val ? "On" : "Off" })),
+     * );
+     * export default c.define("/example.val.ts", schema, [true, false]);
+     */
+  }, {
+    key: "preview",
+    value: function preview(select) {
+      return new BooleanSchema(this.opt, this.customValidateFunctions, this.isReadonly, this.isHidden, this.description, this.renderInput, select);
+    }
+  }, {
+    key: "executePreviewItem",
+    value: function executePreviewItem(src) {
+      if (this.previewInput === null) {
+        return null;
+      }
+      return this.previewInput({
+        val: src
+      });
+    }
+  }, {
+    key: "declaresItemPreview",
+    value: function declaresItemPreview() {
+      return this.previewInput !== null;
+    }
+  }, {
+    key: "executeSerialize",
+    value: function executeSerialize() {
+      var _this$renderInput, _this$customValidateF;
+      return {
+        type: "boolean",
+        render: (_this$renderInput = this.renderInput) !== null && _this$renderInput !== void 0 ? _this$renderInput : undefined,
+        preview: this.previewInput ? true : undefined,
+        opt: this.opt,
+        customValidate: this.customValidateFunctions && ((_this$customValidateF = this.customValidateFunctions) === null || _this$customValidateF === void 0 ? void 0 : _this$customValidateF.length) > 0,
+        readonly: this.isReadonly,
+        hidden: this.isHidden,
+        description: this.description
+      };
+    }
+  }, {
+    key: "executePreview",
+    value: function executePreview() {
+      return {};
+    }
+  }]);
+}(Schema);
+var _boolean = function _boolean() {
+  return new BooleanSchema();
+};
+
+/**
+ * Language tags, and what makes one wrong.
+ *
+ * Val does not ship a list of locales. Which languages a project publishes is a
+ * property of that project, so it is declared in the settings module — see
+ * `LocalesSettingsSource` — and everything downstream reads it from there.
+ *
+ * What Val does own is the SPELLING. A tag is checked against BCP 47
+ * (RFC 5646) through `Intl.getCanonicalLocales`, which is the same
+ * implementation the browser, `<html lang>` and every `Intl` constructor use.
+ * Delegating rather than writing a matcher is the point: a tag this accepts is
+ * a tag those accept.
+ */
+
+/**
+ * What is wrong with `tag` as a language tag, or `false` if nothing is.
+ *
+ * Canonical form, not merely parseable, and the difference is what makes this
+ * worth checking at all. `nb-no` parses; `Intl.DisplayNames` and a
+ * case-sensitive comparison against a stored key do not agree about it. Since a
+ * locale is compared as a string everywhere — a record key, a URL segment, a
+ * value in content — one spelling has to win, and the canonical one is the
+ * spelling every other tool already produces.
+ *
+ * The message names the canonical form where there is one, because "not
+ * canonical" is not an instruction and `nb-NO` is.
+ */
+function localeTagError(tag) {
+  var canonical;
+  try {
+    canonical = Intl.getCanonicalLocales(tag);
+  } catch (_unused) {
+    // RangeError, for anything the grammar rejects: an underscore instead of a
+    // hyphen (`nb_NO`, which is POSIX rather than BCP 47), an empty subtag, a
+    // subtag of the wrong length.
+    return "'".concat(tag, "' is not a language tag. Language then region, separated by a hyphen \u2014 'nb-NO', not 'nb_NO'");
+  }
+  if (canonical.length !== 1) {
+    // A comma-separated list, or something that canonicalised to nothing.
+    return "'".concat(tag, "' is not a single language tag");
+  }
+  if (canonical[0] !== tag) {
+    return "'".concat(tag, "' is not canonical. Write it as '").concat(canonical[0], "'");
+  }
+  return false;
+}
+
+/**
+ * A language tag, as content holds it.
+ *
+ * A *flavoured* string rather than a union or a strict brand. Which languages a
+ * project has is declared in its settings module, where the project can change
+ * it, so there is no set for a type to enumerate — and a strict brand would make
+ * `"nb-NO"` unassignable, which would mean writing every locale in a `.val.ts`
+ * through a constructor. Content stays plain data.
+ *
+ * So this carries no compile-time guarantee, and is not meant to. It names the
+ * concept where a bare `string` would say nothing, and the guarantee is the
+ * `locale:check-locale` validation against `locales.available`.
+ */
+
+/**
+ * The locale a stored value means, or `null` if it means none of them.
+ *
+ * A lookup against the project's languages, and today that is all it is. It
+ * stays a named function because it is the one place the question is asked —
+ * the Studio, the validation worker and the server all come here rather than
+ * comparing strings themselves, so they cannot disagree about what a stored
+ * value is.
+ */
+function localeOfValue(value, available) {
+  return available.includes(value) ? value : null;
+}
+
+/**
+ * A rule about a section that its individual fields cannot state.
+ *
+ * Paths are WITHIN the section, so an error lands on the value it is about —
+ * including a row of a list, which is what makes this different from a
+ * `.validate()` on the field.
+ */
+
+/**
+ * Every section's rules, by the name that travels in the serialized schema.
+ *
+ * Typed with `| undefined` on the value rather than as a `Partial`: the whole
+ * point is that a lookup can miss, because the name comes off a serialized
+ * schema that may have been written by a newer Val than the one reading it.
+ */
+var sectionValidators = {
+  locales: localesSectionErrors
+};
+
+/**
+ * An object whose keys are all optional: absent means unset.
+ *
+ * Both the settings module itself and each of its sections are this. See
+ * {@link SettingsSource} for why settings cannot be an object schema, and
+ * {@link settings} for what a settings module holds.
+ *
+ * There is no `describe`, `validate`, `render` or `preview` on purpose: the
+ * shape is Val's, not the schema author's — `s.settings()` takes no arguments —
+ * and the Studio renders each section with a UI built for it.
+ */
+var SettingsSchema = /*#__PURE__*/function (_Schema) {
+  function SettingsSchema(items) {
+    var _this;
+    var opt = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : false;
+    var isReadonly = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : false;
+    var isHidden = arguments.length > 3 && arguments[3] !== undefined ? arguments[3] : false;
+    var description = arguments.length > 4 ? arguments[4] : undefined;
+    var
+    /**
+     * Which section this is, where Val has rules about it beyond its keys.
+     *
+     * Not the `validate` the class deliberately does not offer: that one is the
+     * schema author's, and `s.settings()` takes no arguments to declare it
+     * with. This names a rule Val states about a shape Val owns — no language
+     * declared twice in `locales.available` is true of every project, and
+     * there is nowhere else it can be said. A single value's rules stay on its
+     * own schema; this is for the ones that need to see more than one value,
+     * or to report on a row of a list.
+     *
+     * A NAME rather than the function, so it survives serialization: the schema
+     * reaches the Studio's validation worker as JSON, and a closure would be
+     * dropped on the way — which is how these rules once went missing there.
+     */
+    section = arguments.length > 5 ? arguments[5] : undefined;
+    _classCallCheck(this, SettingsSchema);
+    _this = _callSuper(this, SettingsSchema);
+    _this.items = items;
+    _this.opt = opt;
+    _this.isReadonly = isReadonly;
+    _this.isHidden = isHidden;
+    _this.description = description;
+    _this.section = section;
+    return _this;
+  }
+
+  /**
+   * This section's rules, or `undefined` where there are none to run.
+   *
+   * A name this Val does not know means a schema written by a newer one. Its
+   * per-field validation still runs; only the section's own rule is missed,
+   * which is the mild half of the failure and better than refusing the schema.
+   */
+  _inherits(SettingsSchema, _Schema);
+  return _createClass(SettingsSchema, [{
+    key: "sectionValidate",
+    value: function sectionValidate() {
+      return this.section === undefined ? undefined : sectionValidators[this.section];
+    }
+  }, {
+    key: "executeValidate",
+    value: function executeValidate(path, src) {
+      var error = false;
+      if (src === null || src === undefined) {
+        if (this.opt) {
+          return false;
+        }
+        return _defineProperty({}, path, [{
+          message: "Expected 'object', got '".concat(src, "'")
+        }]);
+      }
+      if (_typeof(src) !== "object") {
+        return _defineProperty({}, path, [{
+          message: "Expected 'object', got '".concat(_typeof(src), "'")
+        }]);
+      }
+      if (Array.isArray(src)) {
+        return _defineProperty({}, path, [{
+          message: "Expected 'object', got 'array'"
+        }]);
+      }
+      for (var _i = 0, _Object$entries = Object.entries(this.items); _i < _Object$entries.length; _i++) {
+        var _Object$entries$_i = _slicedToArray(_Object$entries[_i], 2),
+          _key = _Object$entries$_i[0],
+          schema = _Object$entries$_i[1];
+        // Absent is the unset value, so there is nothing to validate. A key that
+        // is present as `undefined` is the same statement written differently.
+        if (src[_key] === undefined) {
+          continue;
+        }
+        var subPath = createValPathOfItem(path, _key);
+        if (!subPath) {
           error = this.appendValidationError(error, path, "Internal error: could not create path at ".concat(!path && typeof path === "string" ? "<empty string>" : path, " at key ").concat(_key),
           // Should! never happen
           src);
@@ -5582,6 +7124,39 @@ var SettingsSchema = /*#__PURE__*/function (_Schema) {
           }).join(", ")), src, true);
         }
       }
+      var sectionValidate = this.sectionValidate();
+      if (sectionValidate) {
+        var _iterator = _createForOfIteratorHelper(sectionValidate(src)),
+          _step;
+        try {
+          for (_iterator.s(); !(_step = _iterator.n()).done;) {
+            var _ref4;
+            var _step$value = _step.value,
+              keys = _step$value.path,
+              message = _step$value.message;
+            var _subPath = path;
+            var _iterator2 = _createForOfIteratorHelper(keys),
+              _step2;
+            try {
+              for (_iterator2.s(); !(_step2 = _iterator2.n()).done;) {
+                var _key3 = _step2.value;
+                _subPath = _subPath && createValPathOfItem(_subPath, _key3);
+              }
+            } catch (err) {
+              _iterator2.e(err);
+            } finally {
+              _iterator2.f();
+            }
+            error = this.appendValidationError(error, // Falls back to the section itself, which is where an error belongs
+            // when the value it is about is not addressable.
+            (_ref4 = _subPath) !== null && _ref4 !== void 0 ? _ref4 : path, message, src);
+          }
+        } catch (err) {
+          _iterator.e(err);
+        } finally {
+          _iterator.f();
+        }
+      }
       return error;
     }
   }, {
@@ -5627,17 +7202,17 @@ var SettingsSchema = /*#__PURE__*/function (_Schema) {
   }, {
     key: "nullable",
     value: function nullable() {
-      return new SettingsSchema(this.items, true, this.isReadonly, this.isHidden, this.description);
+      return new SettingsSchema(this.items, true, this.isReadonly, this.isHidden, this.description, this.section);
     }
   }, {
     key: "readonly",
     value: function readonly() {
-      return new SettingsSchema(this.items, this.opt, true, this.isHidden, this.description);
+      return new SettingsSchema(this.items, this.opt, true, this.isHidden, this.description, this.section);
     }
   }, {
     key: "hidden",
     value: function hidden() {
-      return new SettingsSchema(this.items, this.opt, this.isReadonly, true, this.description);
+      return new SettingsSchema(this.items, this.opt, this.isReadonly, true, this.description, this.section);
     }
   }, {
     key: "executeCustomValidateAt",
@@ -5652,16 +7227,17 @@ var SettingsSchema = /*#__PURE__*/function (_Schema) {
     value: function executeSerialize() {
       return {
         type: "settings",
-        items: Object.fromEntries(Object.entries(this.items).map(function (_ref4) {
-          var _ref5 = _slicedToArray(_ref4, 2),
-            key = _ref5[0],
-            schema = _ref5[1];
+        items: Object.fromEntries(Object.entries(this.items).map(function (_ref5) {
+          var _ref6 = _slicedToArray(_ref5, 2),
+            key = _ref6[0],
+            schema = _ref6[1];
           return [key, schema["executeSerialize"]()];
         })),
         opt: this.opt,
         readonly: this.isReadonly,
         hidden: this.isHidden,
-        description: this.description
+        description: this.description,
+        section: this.section
       };
     }
   }, {
@@ -5671,19 +7247,19 @@ var SettingsSchema = /*#__PURE__*/function (_Schema) {
       if (src === null) {
         return res;
       }
-      for (var _key3 in this.items) {
-        var itemSrc = src[_key3];
+      for (var _key4 in this.items) {
+        var itemSrc = src[_key4];
         if (itemSrc === null || itemSrc === undefined) {
           continue;
         }
-        var subPath = unsafeCreateSourcePath(sourcePath, _key3);
+        var subPath = unsafeCreateSourcePath(sourcePath, _key4);
         if (scope !== undefined && !scope.wantsUnder(subPath)) {
           continue;
         }
-        var itemResult = this.items[_key3]["executePreview"](subPath, itemSrc, scope);
+        var itemResult = this.items[_key4]["executePreview"](subPath, itemSrc, scope);
         for (var keyS in itemResult) {
-          var _key4 = keyS;
-          res[_key4] = itemResult[_key4];
+          var _key5 = keyS;
+          res[_key5] = itemResult[_key5];
         }
       }
       return res;
@@ -5727,11 +7303,58 @@ function settings() {
     assistant: new SettingsSchema({
       enabled: _boolean().nullable().describe("Whether editors have an assistant in this project. Unset means nobody has decided: it is offered, and turned on when someone accepts."),
       context: string().multiline().maxLength(ASSISTANT_SETTINGS_MAX_LENGTH).nullable().describe("Background the assistant would otherwise have to guess: what this site is, who runs it, names and spellings that matter."),
-      tone: string().multiline().maxLength(ASSISTANT_SETTINGS_MAX_LENGTH).nullable().describe("How the assistant should write when it writes content: formal or playful, British or American, how headings are cased.")
-    })
+      tone: string().multiline().maxLength(ASSISTANT_SETTINGS_MAX_LENGTH).nullable().describe("How the assistant should write when it writes content: formal or playful, British or American, how headings are cased."),
+      translation: record(locale(), string().multiline().maxLength(ASSISTANT_SETTINGS_MAX_LENGTH).nullable()).nullable().describe("How to translate into each language: dialect, formality, and the words that stay untranslated.")
+    }),
+    locales: new SettingsSchema({
+      // Nullable because the source type is, and because the Studio writes
+      // `null` for every sibling the first time a section is created.
+      available: array(string()).nullable().describe("The languages this project publishes, as BCP 47 tags: en-US, nb-NO. The order is kept: it is the order of the Studio's picker and of a locale-keyed record's rows.")
+    }, false, false, false, undefined, "locales")
   });
 }
 
+/**
+ * The rules about `locales` that need to see the whole list.
+ *
+ * Two of them, and both report on the ENTRY rather than the list: a tag has to
+ * be spelled canonically, and a language cannot be declared twice. Neither can
+ * live on the item schema — the item sees one string, and "twice" is a fact
+ * about its siblings — and neither can be a `.validate()` on the array either,
+ * since that reports one message on the array itself rather than on the row to
+ * delete.
+ *
+ * Reads defensively rather than asserting the source's type. A settings module
+ * is a file someone edits by hand, and validation runs against whatever is in
+ * it — including the shapes the per-key pass is, in the same breath, reporting.
+ */
+function localesSectionErrors(src) {
+  var errors = [];
+  var raw = Array.isArray(src["available"]) ? src["available"] : [];
+  var seen = new Set();
+  for (var i = 0; i < raw.length; i++) {
+    var tag = raw[i];
+    if (typeof tag !== "string") {
+      // The item's own schema has already said what is wrong with it.
+      continue;
+    }
+    var spelling = localeTagError(tag);
+    if (spelling !== false) {
+      errors.push({
+        path: ["available", i],
+        message: spelling
+      });
+    } else if (seen.has(tag)) {
+      errors.push({
+        path: ["available", i],
+        message: "'".concat(tag, "' is declared twice")
+      });
+    }
+    seen.add(tag);
+  }
+  return errors;
+}
+
 /**
  * What may be WRITTEN as an external record's source, on top of the marker.
  *
@@ -5812,10 +7435,8 @@ function isArraySchema(schema) {
 //   );
 // }
 
-function isUnionSchema(schema
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-) {
-  return schema instanceof UnionSchema || _typeof(schema) === "object" && "type" in schema && schema.type === "union";
+function isDiscriminatedUnionSchema(schema) {
+  return schema instanceof DiscriminatedUnionSchema || _typeof(schema) === "object" && "type" in schema && schema.type === "discriminated-union";
 }
 function isRichTextSchema(schema) {
   return schema instanceof RichTextSchema || _typeof(schema) === "object" && "type" in schema && schema.type === "richtext";
@@ -5921,27 +7542,18 @@ function resolvePath(path, valModule, schema) {
             source: resolvedSource
           }
         };
-      } else if (isUnionSchema(resolvedSchema)) {
-        var _key = resolvedSchema.key;
-        if (typeof _key !== "string") {
-          return {
-            v: {
-              path: origParts.map(function (p) {
-                if (!Number.isNaN(Number(p))) {
-                  return p;
-                } else {
-                  return JSON.stringify(p);
-                }
-              }).join("."),
-              // TODO: create a function generate path from parts (not sure if this always works)
-              schema: resolvedSchema,
-              source: resolvedSource
-            }
-          };
+      } else if (isDiscriminatedUnionSchema(resolvedSchema)) {
+        var _key = resolvedSchema instanceof DiscriminatedUnionSchema ? resolvedSchema["key"] : resolvedSchema.key;
+        // A nullable union holding `null` has no variant to descend into, and
+        // `null[key]` throws before any of the reporting below can run.
+        if (resolvedSource === null || _typeof(resolvedSource) !== "object") {
+          throw Error("Schema type error: expected discriminated union source to be an object, but got ".concat(resolvedSource === null ? "null" : _typeof(resolvedSource), " in path: ").concat(path));
         }
         var keyValue = resolvedSource[_key];
-        if (!keyValue) {
-          throw Error("Invalid path: union source ".concat(resolvedSchema, " did not have required key ").concat(_key, " in path: ").concat(path));
+        // `undefined`, not falsy: `s.literal("")` is a legal tag, and a variant
+        // carrying it was reported as a missing key.
+        if (keyValue === undefined) {
+          throw Error("Invalid path: discriminated union source ".concat(resolvedSchema, " did not have required key ").concat(_key, " in path: ").concat(path));
         }
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
         var schemaOfUnionKey = resolvedSchema.items.find(
@@ -5951,7 +7563,7 @@ function resolvePath(path, valModule, schema) {
           return (child === null || child === void 0 || (_child$items = child.items) === null || _child$items === void 0 || (_child$items = _child$items[_key]) === null || _child$items === void 0 ? void 0 : _child$items.value) === keyValue;
         });
         if (!schemaOfUnionKey) {
-          throw Error("Invalid path: union schema ".concat(resolvedSchema, " did not have a child object with ").concat(_key, " of value ").concat(keyValue, " in path: ").concat(path));
+          throw Error("Invalid path: discriminated union schema ".concat(resolvedSchema, " did not have a child object with ").concat(_key, " of value ").concat(keyValue, " in path: ").concat(path));
         }
         resolvedSchema = schemaOfUnionKey.items[part];
         resolvedSource = resolvedSource[part];
@@ -6171,31 +7783,25 @@ function safeResolvePath(path, valModule, schema) {
             source: resolvedSource
           }
         };
-      } else if (isUnionSchema(resolvedSchema)) {
-        var _key2 = resolvedSchema.key;
-        if (typeof _key2 !== "string") {
+      } else if (isDiscriminatedUnionSchema(resolvedSchema)) {
+        var _key2 = resolvedSchema instanceof DiscriminatedUnionSchema ? resolvedSchema["key"] : resolvedSchema.key;
+        // See the note in `resolvePath`: a null union has no variant to descend
+        // into, and this API promises a structured error rather than a throw.
+        if (resolvedSource === null || _typeof(resolvedSource) !== "object") {
           return {
             v: {
-              status: "ok",
-              path: origParts.map(function (p) {
-                if (!Number.isNaN(Number(p))) {
-                  return p;
-                } else {
-                  return JSON.stringify(p);
-                }
-              }).join("."),
-              // TODO: create a function generate path from parts (not sure if this always works)
-              schema: resolvedSchema,
-              source: resolvedSource
+              status: "error",
+              message: "Schema type error: expected discriminated union source to be an object, but got ".concat(resolvedSource === null ? "null" : _typeof(resolvedSource), " in path: ").concat(path)
             }
           };
         }
         var keyValue = resolvedSource[_key2];
-        if (!keyValue) {
+        // See the note in `resolvePath`: an empty-string tag is a present key.
+        if (keyValue === undefined) {
           return {
             v: {
               status: "error",
-              message: "Invalid path: union source ".concat(resolvedSchema, " did not have required key ").concat(_key2, " in path: ").concat(path)
+              message: "Invalid path: discriminated union source ".concat(resolvedSchema, " did not have required key ").concat(_key2, " in path: ").concat(path)
             }
           };
         }
@@ -6210,7 +7816,7 @@ function safeResolvePath(path, valModule, schema) {
           return {
             v: {
               status: "error",
-              message: "Invalid path: union schema ".concat(resolvedSchema, " did not have a child object with ").concat(_key2, " of value ").concat(keyValue, " in path: ").concat(path)
+              message: "Invalid path: discriminated union schema ".concat(resolvedSchema, " did not have a child object with ").concat(_key2, " of value ").concat(keyValue, " in path: ").concat(path)
             }
           };
         }
@@ -6347,12 +7953,48 @@ var NumberSchema = /*#__PURE__*/function (_Schema) {
     _this.previewInput = previewInput;
     return _this;
   }
+
+  /**
+   * Describe this field.
+   *
+   * The description is shown next to the field's label in the Val editor, so
+   * it is where you say what an editor needs to know but the field name cannot
+   * carry. It also travels in the serialized schema, which is what the AI
+   * assistant and the MCP tools read.
+   *
+   * Pass `null` to clear a description set earlier.
+   *
+   * @example
+   * const schema = s.number().describe("How many columns the grid uses");
+   * export default c.define("/example.val.ts", schema, 3);
+   */
   _inherits(NumberSchema, _Schema);
   return _createClass(NumberSchema, [{
     key: "describe",
     value: function describe(description) {
       return new NumberSchema(this.options, this.opt, this.customValidateFunctions, this.isReadonly, this.isHidden, description !== null && description !== void 0 ? description : undefined, this.renderInput, this.previewInput);
     }
+
+    /**
+     * Add a custom validation rule to this field.
+     *
+     * The function is called with the field's value and returns `false` when the
+     * value is fine, or a STRING with the message to show when it is not. Call it
+     * more than once to add more rules — they all run, and every message is
+     * reported.
+     *
+     * Write the check as a ternary, not as `ok || "message"`: that returns `true`
+     * when the value is fine, and `true` is not one of the two answers.
+     *
+     * Validation runs in the Studio as you type, in `npx val validate` and
+     * before a publish.
+     *
+     * @example
+     * const schema = s.number().validate((val) =>
+     *   Number.isInteger(val) ? false : "Must be a whole number",
+     * );
+     * export default c.define("/example.val.ts", schema, 3);
+     */
   }, {
     key: "validate",
     value: function validate(validationFunction) {
@@ -6396,63 +8038,348 @@ var NumberSchema = /*#__PURE__*/function (_Schema) {
     value: function executeAssert(path, src) {
       if (this.opt && src === null) {
         return {
-          success: true,
-          data: src
+          success: true,
+          data: src
+        };
+      }
+      if (src === null) {
+        return {
+          success: false,
+          errors: _defineProperty({}, path, [{
+            message: "Expected 'number', got 'null'",
+            typeError: true
+          }])
+        };
+      }
+      if (typeof src === "number") {
+        return {
+          success: true,
+          data: src
+        };
+      }
+      return {
+        success: false,
+        errors: _defineProperty({}, path, [{
+          message: "Expected 'number', got '".concat(_typeof(src), "'"),
+          typeError: true
+        }])
+      };
+    }
+  }, {
+    key: "nullable",
+    value: function nullable() {
+      return new NumberSchema(this.options, true, this.customValidateFunctions, this.isReadonly, this.isHidden, this.description, this.renderInput, this.previewInput);
+    }
+  }, {
+    key: "readonly",
+    value: function readonly() {
+      var isReadonly = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : true;
+      return new NumberSchema(this.options, this.opt, this.customValidateFunctions, isReadonly, this.isHidden, this.description, this.renderInput, this.previewInput);
+    }
+  }, {
+    key: "hidden",
+    value: function hidden() {
+      var isHidden = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : true;
+      return new NumberSchema(this.options, this.opt, this.customValidateFunctions, this.isReadonly, isHidden, this.description, this.renderInput, this.previewInput);
+    }
+
+    /**
+     * Validate that the number is at most `max` (inclusive).
+     *
+     * @example
+     * const schema = s.number().max(4);
+     * export default c.define("/example.val.ts", schema, 3);
+     */
+  }, {
+    key: "max",
+    value: function max(_max) {
+      return new NumberSchema(_objectSpread2(_objectSpread2({}, this.options), {}, {
+        max: _max
+      }), this.opt, this.customValidateFunctions, this.isReadonly, this.isHidden, this.description, this.renderInput, this.previewInput);
+    }
+
+    /**
+     * Validate that the number is at least `min` (inclusive).
+     *
+     * @example
+     * const schema = s.number().min(1).max(4);
+     * export default c.define("/example.val.ts", schema, 3);
+     */
+  }, {
+    key: "min",
+    value: function min(_min) {
+      return new NumberSchema(_objectSpread2(_objectSpread2({}, this.options), {}, {
+        min: _min
+      }), this.opt, this.customValidateFunctions, this.isReadonly, this.isHidden, this.description, this.renderInput, this.previewInput);
+    }
+  }, {
+    key: "executeCustomValidateAt",
+    value: function executeCustomValidateAt(path, src) {
+      return this.executeCustomValidateFunctions(src, this.customValidateFunctions, {
+        path: path
+      });
+    }
+
+    /**
+     * How this field is laid out in the editor when it is the item of an array
+     * or record: `{ as: "inline" }` renders the field itself inside each row,
+     * instead of a preview row that navigates to it.
+     *
+     * Static configuration, not a callback — see `render.ts`.
+     *
+     * @example
+     * const schema = s.array(s.number().render({ as: "inline" }));
+     * export default c.define("/example.val.ts", schema, [1, 2]);
+     */
+  }, {
+    key: "render",
+    value: function render(input) {
+      return new NumberSchema(this.options, this.opt, this.customValidateFunctions, this.isReadonly, this.isHidden, this.description, input, this.previewInput);
+    }
+
+    /**
+     * How this VALUE is shown where a preview of it is needed — a row in a
+     * sortable list, a reference dropdown, a search hit. Never how the field
+     * itself is edited (that is `render`). See `preview.ts`.
+     *
+     * @example
+     * const schema = s.array(
+     *   s.number().preview(({ val }) => ({ title: String(val) })),
+     * );
+     * export default c.define("/example.val.ts", schema, [1, 2]);
+     */
+  }, {
+    key: "preview",
+    value: function preview(select) {
+      return new NumberSchema(this.options, this.opt, this.customValidateFunctions, this.isReadonly, this.isHidden, this.description, this.renderInput, select);
+    }
+  }, {
+    key: "executePreviewItem",
+    value: function executePreviewItem(src) {
+      if (this.previewInput === null) {
+        return null;
+      }
+      return this.previewInput({
+        val: src
+      });
+    }
+  }, {
+    key: "declaresItemPreview",
+    value: function declaresItemPreview() {
+      return this.previewInput !== null;
+    }
+  }, {
+    key: "executeSerialize",
+    value: function executeSerialize() {
+      var _this$renderInput, _this$customValidateF;
+      return {
+        type: "number",
+        render: (_this$renderInput = this.renderInput) !== null && _this$renderInput !== void 0 ? _this$renderInput : undefined,
+        preview: this.previewInput ? true : undefined,
+        options: this.options,
+        opt: this.opt,
+        customValidate: this.customValidateFunctions && ((_this$customValidateF = this.customValidateFunctions) === null || _this$customValidateF === void 0 ? void 0 : _this$customValidateF.length) > 0,
+        readonly: this.isReadonly,
+        hidden: this.isHidden,
+        description: this.description
+      };
+    }
+  }, {
+    key: "executePreview",
+    value: function executePreview() {
+      return {};
+    }
+  }]);
+}(Schema);
+var number = function number(options) {
+  return new NumberSchema(options);
+};
+
+/**
+ * One of a fixed set of strings.
+ *
+ * The values are the schema — there are no member schemas to descend into, so
+ * this is a LEAF, like `s.string()` with a closed domain. That is the whole
+ * difference from {@link DiscriminatedUnionSchema}, and the reason the two are
+ * separate: everything that walks a schema tree has to recurse into a
+ * discriminated union's variants and must not try to recurse into these.
+ */
+var EnumSchema = /*#__PURE__*/function (_Schema) {
+  /**
+   * Type-only marker: as a record key, this declares the key set.
+   *
+   * An enum names every value it may take, so a record keyed by one holds
+   * exactly those keys — the same claim `s.literal()` and `s.locale()` make.
+   * `DiscriminatedUnionSchema` carries no marker: it discriminates objects and
+   * cannot be a record key at all. See `LocaleSchema`.
+   */
+
+  function EnumSchema(values) {
+    var _this;
+    var opt = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : false;
+    var customValidateFunctions = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : [];
+    var isReadonly = arguments.length > 3 && arguments[3] !== undefined ? arguments[3] : false;
+    var isHidden = arguments.length > 4 && arguments[4] !== undefined ? arguments[4] : false;
+    var description = arguments.length > 5 ? arguments[5] : undefined;
+    var renderInput = arguments.length > 6 && arguments[6] !== undefined ? arguments[6] : null;
+    var previewInput = arguments.length > 7 && arguments[7] !== undefined ? arguments[7] : null;
+    _classCallCheck(this, EnumSchema);
+    _this = _callSuper(this, EnumSchema);
+    _this.values = values;
+    _this.opt = opt;
+    _this.customValidateFunctions = customValidateFunctions;
+    _this.isReadonly = isReadonly;
+    _this.isHidden = isHidden;
+    _this.description = description;
+    _this.renderInput = renderInput;
+    _this.previewInput = previewInput;
+    return _this;
+  }
+
+  /**
+   * Describe this field.
+   *
+   * The description is shown next to the field's label in the Val editor, so it is
+   * where you say what an editor needs to know but the field name cannot carry. It
+   * also travels in the serialized schema, which is what the AI assistant and the
+   * MCP tools read.
+   *
+   * Pass `null` to clear a description set earlier.
+   *
+   * @example
+   * const schema = s
+   *   .enum("draft", "published")
+   *   .describe("Only published pages are built");
+   * export default c.define("/example.val.ts", schema, "draft");
+   */
+  _inherits(EnumSchema, _Schema);
+  return _createClass(EnumSchema, [{
+    key: "describe",
+    value: function describe(description) {
+      return new EnumSchema(this.values, this.opt, this.customValidateFunctions, this.isReadonly, this.isHidden, description !== null && description !== void 0 ? description : undefined, this.renderInput, this.previewInput);
+    }
+
+    /**
+     * Add a custom validation rule to this field.
+     *
+     * The function is called with the field's value and returns `false` when the
+     * value is fine, or a STRING with the message to show when it is not. Call it
+     * more than once to add more rules — they all run, and every message is
+     * reported.
+     *
+     * Validation runs in the Studio as you type, in `npx val validate` and before a
+     * publish.
+     *
+     * @example
+     * const schema = s
+     *   .enum("draft", "published")
+     *   .validate((val) =>
+     *     val === "published" ? "Publishing is frozen this week" : false,
+     *   );
+     * export default c.define("/example.val.ts", schema, "draft");
+     */
+  }, {
+    key: "validate",
+    value: function validate(validationFunction) {
+      return new EnumSchema(this.values, this.opt, this.customValidateFunctions.concat(validationFunction), this.isReadonly, this.isHidden, this.description, this.renderInput, this.previewInput);
+    }
+  }, {
+    key: "executeValidate",
+    value: function executeValidate(path, src) {
+      var customValidationErrors = this.executeCustomValidateFunctions(src, this.customValidateFunctions, {
+        path: path
+      });
+      // The custom validators always report, whatever the structural answer is.
+      var errors = customValidationErrors;
+      var unknownSrc = src;
+      if (this.opt && (unknownSrc === null || unknownSrc === undefined)) {
+        return errors.length > 0 ? _defineProperty({}, path, errors) : false;
+      }
+      if (!Array.isArray(this.values) || this.values.length === 0) {
+        errors.push({
+          message: "An enum schema must have at least one value",
+          schemaError: true
+        });
+      } else if (typeof unknownSrc !== "string") {
+        errors.push({
+          message: "Expected 'string', got '".concat(unknownSrc === null ? "null" : _typeof(unknownSrc), "'"),
+          value: src,
+          typeError: true
+        });
+      } else if (!this.values.includes(unknownSrc)) {
+        errors.push({
+          message: "Value must be one of the following: ".concat(this.values.map(function (value) {
+            return "\"".concat(value, "\"");
+          }).join(", ")),
+          value: src
+        });
+      }
+      return errors.length > 0 ? _defineProperty({}, path, errors) : false;
+    }
+  }, {
+    key: "executeAssert",
+    value: function executeAssert(path, src) {
+      if (this.opt && src === null) {
+        return {
+          success: true,
+          data: src
+        };
+      }
+      var errors = {};
+      if (typeof src !== "string") {
+        errors[path] = [{
+          message: "Expected 'string', got '".concat(src === null ? "null" : _typeof(src), "'"),
+          typeError: true
+        }];
+        return {
+          success: false,
+          errors: errors
         };
       }
-      if (src === null) {
+      if (!Array.isArray(this.values) || this.values.length === 0) {
+        errors[path] = [{
+          message: "An enum schema must have at least one value",
+          schemaError: true
+        }];
         return {
           success: false,
-          errors: _defineProperty({}, path, [{
-            message: "Expected 'number', got 'null'",
-            typeError: true
-          }])
+          errors: errors
         };
       }
-      if (typeof src === "number") {
+      if (!this.values.includes(src)) {
+        errors[path] = [{
+          message: "Expected one of ".concat(this.values.map(function (value) {
+            return "'".concat(value, "'");
+          }).join(", "), ", got '").concat(src, "'"),
+          typeError: true
+        }];
         return {
-          success: true,
-          data: src
+          success: false,
+          errors: errors
         };
       }
       return {
-        success: false,
-        errors: _defineProperty({}, path, [{
-          message: "Expected 'number', got '".concat(_typeof(src), "'"),
-          typeError: true
-        }])
+        success: true,
+        data: src
       };
     }
   }, {
     key: "nullable",
     value: function nullable() {
-      return new NumberSchema(this.options, true, [], this.isReadonly, this.isHidden, this.description, this.renderInput, this.previewInput);
+      // Explicit type args: `previewInput` would otherwise pin inference to `Src`.
+      return new EnumSchema(this.values, true, this.customValidateFunctions, this.isReadonly, this.isHidden, this.description, this.renderInput, this.previewInput);
     }
   }, {
     key: "readonly",
     value: function readonly() {
       var isReadonly = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : true;
-      return new NumberSchema(this.options, this.opt, this.customValidateFunctions, isReadonly, this.isHidden, this.description, this.renderInput, this.previewInput);
+      return new EnumSchema(this.values, this.opt, this.customValidateFunctions, isReadonly, this.isHidden, this.description, this.renderInput, this.previewInput);
     }
   }, {
     key: "hidden",
     value: function hidden() {
       var isHidden = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : true;
-      return new NumberSchema(this.options, this.opt, this.customValidateFunctions, this.isReadonly, isHidden, this.description, this.renderInput, this.previewInput);
-    }
-  }, {
-    key: "max",
-    value: function max(_max) {
-      return new NumberSchema(_objectSpread2(_objectSpread2({}, this.options), {}, {
-        max: _max
-      }), this.opt, this.customValidateFunctions, this.isReadonly, this.isHidden, this.description, this.renderInput, this.previewInput);
-    }
-  }, {
-    key: "min",
-    value: function min(_min) {
-      return new NumberSchema(_objectSpread2(_objectSpread2({}, this.options), {}, {
-        min: _min
-      }), this.opt, this.customValidateFunctions, this.isReadonly, this.isHidden, this.description, this.renderInput, this.previewInput);
+      return new EnumSchema(this.values, this.opt, this.customValidateFunctions, this.isReadonly, isHidden, this.description, this.renderInput, this.previewInput);
     }
   }, {
     key: "executeCustomValidateAt",
@@ -6468,22 +8395,34 @@ var NumberSchema = /*#__PURE__*/function (_Schema) {
      * instead of a preview row that navigates to it.
      *
      * Static configuration, not a callback — see `render.ts`.
+     *
+     * @example
+     * const schema = s.array(
+     *   s.enum("draft", "published").render({ as: "inline" }),
+     * );
+     * export default c.define("/example.val.ts", schema, ["draft"]);
      */
   }, {
     key: "render",
     value: function render(input) {
-      return new NumberSchema(this.options, this.opt, this.customValidateFunctions, this.isReadonly, this.isHidden, this.description, input, this.previewInput);
+      return new EnumSchema(this.values, this.opt, this.customValidateFunctions, this.isReadonly, this.isHidden, this.description, input, this.previewInput);
     }
 
     /**
      * How this VALUE is shown where a preview of it is needed — a row in a
      * sortable list, a reference dropdown, a search hit. Never how the field
      * itself is edited (that is `render`). See `preview.ts`.
+     *
+     * @example
+     * const schema = s.array(
+     *   s.enum("draft", "published").preview(({ val }) => ({ title: val })),
+     * );
+     * export default c.define("/example.val.ts", schema, ["draft"]);
      */
   }, {
     key: "preview",
     value: function preview(select) {
-      return new NumberSchema(this.options, this.opt, this.customValidateFunctions, this.isReadonly, this.isHidden, this.description, this.renderInput, select);
+      return new EnumSchema(this.values, this.opt, this.customValidateFunctions, this.isReadonly, this.isHidden, this.description, this.renderInput, select);
     }
   }, {
     key: "executePreviewItem",
@@ -6505,10 +8444,10 @@ var NumberSchema = /*#__PURE__*/function (_Schema) {
     value: function executeSerialize() {
       var _this$renderInput, _this$customValidateF;
       return {
-        type: "number",
+        type: "enum",
         render: (_this$renderInput = this.renderInput) !== null && _this$renderInput !== void 0 ? _this$renderInput : undefined,
         preview: this.previewInput ? true : undefined,
-        options: this.options,
+        values: _toConsumableArray(this.values),
         opt: this.opt,
         customValidate: this.customValidateFunctions && ((_this$customValidateF = this.customValidateFunctions) === null || _this$customValidateF === void 0 ? void 0 : _this$customValidateF.length) > 0,
         readonly: this.isReadonly,
@@ -6519,14 +8458,104 @@ var NumberSchema = /*#__PURE__*/function (_Schema) {
   }, {
     key: "executePreview",
     value: function executePreview() {
+      // A leaf: nothing below it to preview.
       return {};
     }
   }]);
 }(Schema);
-var number = function number(options) {
-  return new NumberSchema(options);
+
+/**
+ * Define a string that must be one of a fixed set of values.
+ *
+ * Named `enumSchema` rather than `enum` because `enum` is a reserved word and
+ * cannot be a binding name; it is exposed as `s.enum`.
+ */
+var enumSchema = function enumSchema() {
+  for (var _len = arguments.length, values = new Array(_len), _key = 0; _key < _len; _key++) {
+    values[_key] = arguments[_key];
+  }
+  return new EnumSchema(values);
 };
 
+/**
+ * @deprecated Use {@link SerializedDiscriminatedUnionSchema} or
+ * {@link SerializedEnumSchema}. A serialized union is now one or the other,
+ * distinguished by `type` rather than by the shape of `key`.
+ */
+
+/** @deprecated Use {@link SerializedEnumSchema}. */
+
+/** @deprecated Use {@link SerializedDiscriminatedUnionSchema}. */
+
+/**
+ * @deprecated There is no single union schema class any more: name
+ * {@link DiscriminatedUnionSchema} or {@link EnumSchema}. The type parameters
+ * are kept so existing annotations still compile, but only `Src` is used.
+ */
+
+/**
+ * The value type of a list of literal schemas — how `s.union` typed a union of
+ * literals. Inferred from `Schema<infer S>` rather than `LiteralSchema<infer S>`
+ * because a `LiteralSchema` is invariant in its source (its custom validate
+ * functions put it in a parameter position), so `LiteralSchema<"a">` is not
+ * assignable to `LiteralSchema<"a" | "b">`.
+ */
+
+/**
+ * @deprecated Use `s.discriminatedUnion(key, ...objects)` for a tagged union of
+ * objects, or `s.enum("a", "b")` for one of a fixed set of strings.
+ *
+ * One thing does NOT survive the literal form: an enum's values are strings,
+ * so a member literal's own `.validate()` and `.describe()` are dropped rather
+ * than carried over. `s.union(s.literal("a").validate(...), ...)` ran that
+ * validator as part of deciding whether the value matched; `s.enum` has no
+ * member to run. A validator on a single-valued literal could only accept or
+ * reject that one value, which the enum's own value list already decides — but
+ * if you rely on one, keep it by validating the enum itself.
+ *
+ * @example
+ * // was: s.union("type", s.object({ type: s.literal("a"), a: s.string() }))
+ * const schema = s.discriminatedUnion(
+ *   "type",
+ *   s.object({ type: s.literal("a"), a: s.string() }),
+ * );
+ * export default c.define("/example.val.ts", schema, { type: "a", a: "one" });
+ *
+ * @example
+ * // was: s.union(s.literal("a"), s.literal("b"))
+ * const schema = s.enum("a", "b");
+ * export default c.define("/example.val.ts", schema, "a");
+ */
+
+function union(keyOrFirstLiteral) {
+  for (var _len = arguments.length, rest = new Array(_len > 1 ? _len - 1 : 0), _key = 1; _key < _len; _key++) {
+    rest[_key - 1] = arguments[_key];
+  }
+  if (typeof keyOrFirstLiteral === "string") {
+    return new DiscriminatedUnionSchema(keyOrFirstLiteral, rest);
+  }
+  // A literal union is an enum: the values ARE the schema, so the literals are
+  // flattened into them. `key` was only ever the first member.
+  var literals = [keyOrFirstLiteral].concat(rest);
+  var values = [];
+  var _iterator = _createForOfIteratorHelper(literals),
+    _step;
+  try {
+    for (_iterator.s(); !(_step = _iterator.n()).done;) {
+      var literal = _step.value;
+      if (!(literal instanceof LiteralSchema)) {
+        throw new Error("s.union: expected either a string key followed by object schemas, or literal schemas. Got: ".concat(JSON.stringify(literal)));
+      }
+      values.push(literal["value"]);
+    }
+  } catch (err) {
+    _iterator.e(err);
+  } finally {
+    _iterator.f();
+  }
+  return new EnumSchema(values);
+}
+
 var KeyOfSchema = /*#__PURE__*/function (_Schema) {
   function KeyOfSchema(schema, sourcePath) {
     var _this;
@@ -6550,12 +8579,52 @@ var KeyOfSchema = /*#__PURE__*/function (_Schema) {
     _this.previewInput = previewInput;
     return _this;
   }
+
+  /**
+   * Describe this field.
+   *
+   * The description is shown next to the field's label in the Val editor, so
+   * it is where you say what an editor needs to know but the field name cannot
+   * carry. It also travels in the serialized schema, which is what the AI
+   * assistant and the MCP tools read.
+   *
+   * Pass `null` to clear a description set earlier.
+   *
+   * @example
+   * import authorsVal from "./authors.val"; // a record module
+   * const schema = s.keyOf(authorsVal).describe("Who wrote this post");
+   * export default c.define("/example.val.ts", schema, "ada");
+   */
   _inherits(KeyOfSchema, _Schema);
   return _createClass(KeyOfSchema, [{
     key: "describe",
     value: function describe(description) {
       return new KeyOfSchema(this.schema, this.sourcePath, this.opt, this.customValidateFunctions, this.isReadonly, this.isHidden, description !== null && description !== void 0 ? description : undefined, this.renderInput, this.previewInput);
     }
+
+    /**
+     * Add a custom validation rule to this field.
+     *
+     * The function is called with the field's value and returns `false` when the
+     * value is fine, or a STRING with the message to show when it is not. Call it
+     * more than once to add more rules — they all run, and every message is
+     * reported.
+     *
+     * Write the check as a ternary, not as `ok || "message"`: that returns `true`
+     * when the value is fine, and `true` is not one of the two answers.
+     *
+     * Validation runs in the Studio as you type, in `npx val validate` and
+     * before a publish.
+     *
+     * @example
+     * import authorsVal from "./authors.val"; // a record module
+     * const schema = s
+     *   .keyOf(authorsVal)
+     *   .validate((val) =>
+     *     val === "placeholder" ? "Pick a real author" : false,
+     *   );
+     * export default c.define("/example.val.ts", schema, "ada");
+     */
   }, {
     key: "validate",
     value: function validate(validationFunction) {
@@ -6689,7 +8758,7 @@ var KeyOfSchema = /*#__PURE__*/function (_Schema) {
   }, {
     key: "nullable",
     value: function nullable() {
-      return new KeyOfSchema(this.schema, this.sourcePath, true, [], this.isReadonly, this.isHidden, this.description, this.renderInput, this.previewInput);
+      return new KeyOfSchema(this.schema, this.sourcePath, true, this.customValidateFunctions, this.isReadonly, this.isHidden, this.description, this.renderInput, this.previewInput);
     }
   }, {
     key: "readonly",
@@ -6717,6 +8786,11 @@ var KeyOfSchema = /*#__PURE__*/function (_Schema) {
      * instead of a preview row that navigates to it.
      *
      * Static configuration, not a callback — see `render.ts`.
+     *
+     * @example
+     * import authorsVal from "./authors.val"; // a record module
+     * const schema = s.array(s.keyOf(authorsVal).render({ as: "inline" }));
+     * export default c.define("/example.val.ts", schema, ["ada"]);
      */
   }, {
     key: "render",
@@ -6728,6 +8802,13 @@ var KeyOfSchema = /*#__PURE__*/function (_Schema) {
      * How this VALUE is shown where a preview of it is needed — a row in a
      * sortable list, a reference dropdown, a search hit. Never how the field
      * itself is edited (that is `render`). See `preview.ts`.
+     *
+     * @example
+     * import authorsVal from "./authors.val"; // a record module
+     * const schema = s.array(
+     *   s.keyOf(authorsVal).preview(({ val }) => ({ title: val })),
+     * );
+     * export default c.define("/example.val.ts", schema, ["ada"]);
      */
   }, {
     key: "preview",
@@ -6844,17 +8925,83 @@ var FileSchema = /*#__PURE__*/function (_Schema) {
     _this.previewInput = previewInput;
     return _this;
   }
+
+  /**
+   * Describe this field.
+   *
+   * The description is shown next to the field's label in the Val editor, so
+   * it is where you say what an editor needs to know but the field name cannot
+   * carry. It also travels in the serialized schema, which is what the AI
+   * assistant and the MCP tools read.
+   *
+   * Pass `null` to clear a description set earlier.
+   *
+   * @example
+   * const schema = s.file().describe("The PDF offered for download");
+   * export default c.define("/example.val.ts", schema, {
+   *   path: "/public/val/example.pdf",
+   *   mimeType: "application/pdf",
+   * });
+   */
   _inherits(FileSchema, _Schema);
   return _createClass(FileSchema, [{
     key: "describe",
     value: function describe(description) {
       return new FileSchema(this.options, this.opt, this.isRemote, this.customValidateFunctions, this.moduleMetadata, this.isReadonly, this.isHidden, description !== null && description !== void 0 ? description : undefined, this.renderInput, this.previewInput);
     }
+
+    /**
+     * Store the file on Val's remote content host instead of in your repository.
+     *
+     * The bytes still go into the patch store when the file is uploaded — the
+     * push to the remote host happens at publish. What changes is where the
+     * published file lives: `path` becomes a remote URL rather than a path under
+     * `/public`, so the repository does not grow with every upload.
+     *
+     * The `path` of a remote file is a URL on the content host, and it is not
+     * something to write by hand: upload the file in the Studio, or write a
+     * local path and let `npx val validate --fix` upload it and rewrite the
+     * `path` to the ref below.
+     *
+     * @example
+     * const schema = s.file({ accept: "application/pdf" }).remote();
+     * export default c.define("/example.val.ts", schema, {
+     *   path: "https://remote.val.build/file/p/my-project/b/01/v/1.0.0/h/8f2a1c/f/3b9d70/p/public/val/example.pdf",
+     *   mimeType: "application/pdf",
+     * });
+     */
   }, {
     key: "remote",
     value: function remote() {
       return new FileSchema(this.options, this.opt, true, this.customValidateFunctions, this.moduleMetadata, this.isReadonly, this.isHidden, this.description, this.renderInput, this.previewInput);
     }
+
+    /**
+     * Add a custom validation rule to this field.
+     *
+     * The function is called with the field's value and returns `false` when the
+     * value is fine, or a STRING with the message to show when it is not. Call it
+     * more than once to add more rules — they all run, and every message is
+     * reported.
+     *
+     * Write the check as a ternary, not as `ok || "message"`: that returns `true`
+     * when the value is fine, and `true` is not one of the two answers.
+     *
+     * Validation runs in the Studio as you type, in `npx val validate` and
+     * before a publish.
+     *
+     * The second argument carries the `path` of the field being validated, for
+     * when the message needs to say where the problem is.
+     *
+     * @example
+     * const schema = s.file().validate((val) =>
+     *   val.path.endsWith(".pdf") ? false : "Must be a PDF",
+     * );
+     * export default c.define("/example.val.ts", schema, {
+     *   path: "/public/val/example.pdf",
+     *   mimeType: "application/pdf",
+     * });
+     */
   }, {
     key: "validate",
     value: function validate(validationFunction) {
@@ -7061,6 +9208,12 @@ var FileSchema = /*#__PURE__*/function (_Schema) {
      * instead of a preview row that navigates to it.
      *
      * Static configuration, not a callback — see `render.ts`.
+     *
+     * @example
+     * const schema = s.array(s.file().render({ as: "inline" }));
+     * export default c.define("/example.val.ts", schema, [
+     *   { path: "/public/val/example.pdf", mimeType: "application/pdf" },
+     * ]);
      */
   }, {
     key: "render",
@@ -7072,6 +9225,14 @@ var FileSchema = /*#__PURE__*/function (_Schema) {
      * How this VALUE is shown where a preview of it is needed — a row in a
      * sortable list, a reference dropdown, a search hit. Never how the field
      * itself is edited (that is `render`). See `preview.ts`.
+     *
+     * @example
+     * const schema = s.array(
+     *   s.file().preview(({ val }) => ({ title: val.path })),
+     * );
+     * export default c.define("/example.val.ts", schema, [
+     *   { path: "/public/val/example.pdf", mimeType: "application/pdf" },
+     * ]);
      */
   }, {
     key: "preview",
@@ -7205,12 +9366,48 @@ var DateSchema = /*#__PURE__*/function (_Schema) {
     _this.previewInput = previewInput;
     return _this;
   }
+
+  /**
+   * Describe this field.
+   *
+   * The description is shown next to the field's label in the Val editor, so
+   * it is where you say what an editor needs to know but the field name cannot
+   * carry. It also travels in the serialized schema, which is what the AI
+   * assistant and the MCP tools read.
+   *
+   * Pass `null` to clear a description set earlier.
+   *
+   * @example
+   * const schema = s.date().describe("First day the campaign is live");
+   * export default c.define("/example.val.ts", schema, "2025-06-01");
+   */
   _inherits(DateSchema, _Schema);
   return _createClass(DateSchema, [{
     key: "describe",
     value: function describe(description) {
       return new DateSchema(this.options, this.opt, this.customValidateFunctions, this.isReadonly, this.isHidden, description !== null && description !== void 0 ? description : undefined, this.renderInput, this.previewInput);
     }
+
+    /**
+     * Add a custom validation rule to this field.
+     *
+     * The function is called with the field's value and returns `false` when the
+     * value is fine, or a STRING with the message to show when it is not. Call it
+     * more than once to add more rules — they all run, and every message is
+     * reported.
+     *
+     * Write the check as a ternary, not as `ok || "message"`: that returns `true`
+     * when the value is fine, and `true` is not one of the two answers.
+     *
+     * Validation runs in the Studio as you type, in `npx val validate` and
+     * before a publish.
+     *
+     * @example
+     * const schema = s.date().validate((val) =>
+     *   val >= "2025-01-01" ? false : "Must be in 2025 or later",
+     * );
+     * export default c.define("/example.val.ts", schema, "2025-06-01");
+     */
   }, {
     key: "validate",
     value: function validate(validationFunction) {
@@ -7298,6 +9495,16 @@ var DateSchema = /*#__PURE__*/function (_Schema) {
         data: src
       };
     }
+
+    /**
+     * Validate that the date is this date or after (inclusive).
+     *
+     * Written as `YYYY-MM-DD`, the same shape the value has.
+     *
+     * @example
+     * const schema = s.date().from("2025-01-01");
+     * export default c.define("/example.val.ts", schema, "2025-06-01");
+     */
   }, {
     key: "from",
     value: function from(_from) {
@@ -7305,6 +9512,16 @@ var DateSchema = /*#__PURE__*/function (_Schema) {
         from: _from
       }), this.opt, this.customValidateFunctions, this.isReadonly, this.isHidden, this.description, this.renderInput, this.previewInput);
     }
+
+    /**
+     * Validate that the date is this date or before (inclusive).
+     *
+     * Written as `YYYY-MM-DD`, the same shape the value has.
+     *
+     * @example
+     * const schema = s.date().from("2025-01-01").to("2025-12-31");
+     * export default c.define("/example.val.ts", schema, "2025-06-01");
+     */
   }, {
     key: "to",
     value: function to(_to) {
@@ -7315,7 +9532,7 @@ var DateSchema = /*#__PURE__*/function (_Schema) {
   }, {
     key: "nullable",
     value: function nullable() {
-      return new DateSchema(this.options, true, [], this.isReadonly, this.isHidden, this.description, this.renderInput, this.previewInput);
+      return new DateSchema(this.options, true, this.customValidateFunctions, this.isReadonly, this.isHidden, this.description, this.renderInput, this.previewInput);
     }
   }, {
     key: "readonly",
@@ -7343,6 +9560,10 @@ var DateSchema = /*#__PURE__*/function (_Schema) {
      * instead of a preview row that navigates to it.
      *
      * Static configuration, not a callback — see `render.ts`.
+     *
+     * @example
+     * const schema = s.array(s.date().render({ as: "inline" }));
+     * export default c.define("/example.val.ts", schema, ["2025-06-01"]);
      */
   }, {
     key: "render",
@@ -7354,6 +9575,12 @@ var DateSchema = /*#__PURE__*/function (_Schema) {
      * How this VALUE is shown where a preview of it is needed — a row in a
      * sortable list, a reference dropdown, a search hit. Never how the field
      * itself is edited (that is `render`). See `preview.ts`.
+     *
+     * @example
+     * const schema = s.array(
+     *   s.date().preview(({ val }) => ({ title: val })),
+     * );
+     * export default c.define("/example.val.ts", schema, ["2025-06-01"]);
      */
   }, {
     key: "preview",
@@ -7424,12 +9651,56 @@ var DateTimeSchema = /*#__PURE__*/function (_Schema) {
     _this.previewInput = previewInput;
     return _this;
   }
+
+  /**
+   * Describe this field.
+   *
+   * The description is shown next to the field's label in the Val editor, so
+   * it is where you say what an editor needs to know but the field name cannot
+   * carry. It also travels in the serialized schema, which is what the AI
+   * assistant and the MCP tools read.
+   *
+   * Pass `null` to clear a description set earlier.
+   *
+   * @example
+   * const schema = s.datetime().describe("When the article goes live");
+   * export default c.define(
+   *   "/example.val.ts",
+   *   schema,
+   *   "2025-06-01T09:00:00.000Z",
+   * );
+   */
   _inherits(DateTimeSchema, _Schema);
   return _createClass(DateTimeSchema, [{
     key: "describe",
     value: function describe(description) {
       return new DateTimeSchema(this.options, this.opt, this.customValidateFunctions, this.isReadonly, this.isHidden, description !== null && description !== void 0 ? description : undefined, this.renderInput, this.previewInput);
     }
+
+    /**
+     * Add a custom validation rule to this field.
+     *
+     * The function is called with the field's value and returns `false` when the
+     * value is fine, or a STRING with the message to show when it is not. Call it
+     * more than once to add more rules — they all run, and every message is
+     * reported.
+     *
+     * Write the check as a ternary, not as `ok || "message"`: that returns `true`
+     * when the value is fine, and `true` is not one of the two answers.
+     *
+     * Validation runs in the Studio as you type, in `npx val validate` and
+     * before a publish.
+     *
+     * @example
+     * const schema = s.datetime().validate((val) =>
+     *   val.endsWith("Z") ? false : "Must be in UTC",
+     * );
+     * export default c.define(
+     *   "/example.val.ts",
+     *   schema,
+     *   "2025-06-01T09:00:00.000Z",
+     * );
+     */
   }, {
     key: "validate",
     value: function validate(validationFunction) {
@@ -7549,6 +9820,20 @@ var DateTimeSchema = /*#__PURE__*/function (_Schema) {
         data: src
       };
     }
+
+    /**
+     * Validate that the datetime is this datetime or after (inclusive).
+     *
+     * Any ISO 8601 datetime string `Date.parse` understands.
+     *
+     * @example
+     * const schema = s.datetime().from("2025-01-01T00:00:00Z");
+     * export default c.define(
+     *   "/example.val.ts",
+     *   schema,
+     *   "2025-06-01T09:00:00.000Z",
+     * );
+     */
   }, {
     key: "from",
     value: function from(_from) {
@@ -7556,6 +9841,23 @@ var DateTimeSchema = /*#__PURE__*/function (_Schema) {
         from: _from
       }), this.opt, this.customValidateFunctions, this.isReadonly, this.isHidden, this.description, this.renderInput, this.previewInput);
     }
+
+    /**
+     * Validate that the datetime is this datetime or before (inclusive).
+     *
+     * Any ISO 8601 datetime string `Date.parse` understands.
+     *
+     * @example
+     * const schema = s
+     *   .datetime()
+     *   .from("2025-01-01T00:00:00Z")
+     *   .to("2025-12-31T23:59:59Z");
+     * export default c.define(
+     *   "/example.val.ts",
+     *   schema,
+     *   "2025-06-01T09:00:00.000Z",
+     * );
+     */
   }, {
     key: "to",
     value: function to(_to) {
@@ -7566,7 +9868,7 @@ var DateTimeSchema = /*#__PURE__*/function (_Schema) {
   }, {
     key: "nullable",
     value: function nullable() {
-      return new DateTimeSchema(this.options, true, [], this.isReadonly, this.isHidden, this.description, this.renderInput, this.previewInput);
+      return new DateTimeSchema(this.options, true, this.customValidateFunctions, this.isReadonly, this.isHidden, this.description, this.renderInput, this.previewInput);
     }
   }, {
     key: "readonly",
@@ -7594,6 +9896,12 @@ var DateTimeSchema = /*#__PURE__*/function (_Schema) {
      * instead of a preview row that navigates to it.
      *
      * Static configuration, not a callback — see `render.ts`.
+     *
+     * @example
+     * const schema = s.array(s.datetime().render({ as: "inline" }));
+     * export default c.define("/example.val.ts", schema, [
+     *   "2025-06-01T09:00:00.000Z",
+     * ]);
      */
   }, {
     key: "render",
@@ -7605,6 +9913,14 @@ var DateTimeSchema = /*#__PURE__*/function (_Schema) {
      * How this VALUE is shown where a preview of it is needed — a row in a
      * sortable list, a reference dropdown, a search hit. Never how the field
      * itself is edited (that is `render`). See `preview.ts`.
+     *
+     * @example
+     * const schema = s.array(
+     *   s.datetime().preview(({ val }) => ({ title: val })),
+     * );
+     * export default c.define("/example.val.ts", schema, [
+     *   "2025-06-01T09:00:00.000Z",
+     * ]);
      */
   }, {
     key: "preview",
@@ -7689,12 +10005,59 @@ var CodeSchema = /*#__PURE__*/function (_Schema) {
     _this.previewInput = previewInput;
     return _this;
   }
+
+  /**
+   * Describe this field.
+   *
+   * The description is shown next to the field's label in the Val editor, so
+   * it is where you say what an editor needs to know but the field name cannot
+   * carry. It also travels in the serialized schema, which is what the AI
+   * assistant and the MCP tools read.
+   *
+   * Pass `null` to clear a description set earlier.
+   *
+   * @example
+   * const schema = s
+   *   .code({ language: "css" })
+   *   .describe("Injected into the page head — keep it small");
+   * export default c.define(
+   *   "/example.val.ts",
+   *   schema,
+   *   ".hero { color: red; }",
+   * );
+   */
   _inherits(CodeSchema, _Schema);
   return _createClass(CodeSchema, [{
     key: "describe",
     value: function describe(description) {
       return new CodeSchema(this.options, this.opt, this.customValidateFunctions, this.isReadonly, this.isHidden, description !== null && description !== void 0 ? description : undefined, this.renderInput, this.previewInput);
     }
+
+    /**
+     * Add a custom validation rule to this field.
+     *
+     * The function is called with the field's value and returns `false` when the
+     * value is fine, or a STRING with the message to show when it is not. Call it
+     * more than once to add more rules — they all run, and every message is
+     * reported.
+     *
+     * Write the check as a ternary, not as `ok || "message"`: that returns `true`
+     * when the value is fine, and `true` is not one of the two answers.
+     *
+     * Validation runs in the Studio as you type, in `npx val validate` and
+     * before a publish.
+     *
+     * @example
+     * const schema = s.code({ language: "json" }).validate((val) => {
+     *   try {
+     *     JSON.parse(val);
+     *     return false;
+     *   } catch {
+     *     return "Must be valid JSON";
+     *   }
+     * });
+     * export default c.define("/example.val.ts", schema, '{ "a": 1 }');
+     */
   }, {
     key: "validate",
     value: function validate(validationFunction) {
@@ -7753,7 +10116,7 @@ var CodeSchema = /*#__PURE__*/function (_Schema) {
   }, {
     key: "nullable",
     value: function nullable() {
-      return new CodeSchema(this.options, true, [], this.isReadonly, this.isHidden, this.description, this.renderInput, this.previewInput);
+      return new CodeSchema(this.options, true, this.customValidateFunctions, this.isReadonly, this.isHidden, this.description, this.renderInput, this.previewInput);
     }
   }, {
     key: "readonly",
@@ -7774,6 +10137,14 @@ var CodeSchema = /*#__PURE__*/function (_Schema) {
      * instead of a preview row that navigates to it.
      *
      * Static configuration, not a callback — see `render.ts`.
+     *
+     * @example
+     * const schema = s.array(
+     *   s.code({ language: "css" }).render({ as: "inline" }),
+     * );
+     * export default c.define("/example.val.ts", schema, [
+     *   ".hero { color: red; }",
+     * ]);
      */
   }, {
     key: "render",
@@ -7785,6 +10156,16 @@ var CodeSchema = /*#__PURE__*/function (_Schema) {
      * How this VALUE is shown where a preview of it is needed — a row in a
      * sortable list, a reference dropdown, a search hit. Never how the field
      * itself is edited (that is `render`). See `preview.ts`.
+     *
+     * @example
+     * const schema = s.array(
+     *   s.code({ language: "css" }).preview(({ val }) => ({
+     *     title: val.split("\n")[0],
+     *   })),
+     * );
+     * export default c.define("/example.val.ts", schema, [
+     *   ".hero { color: red; }",
+     * ]);
      */
   }, {
     key: "preview",
@@ -8335,12 +10716,54 @@ var ColorSchema = /*#__PURE__*/function (_Schema) {
     _this.previewInput = previewInput;
     return _this;
   }
+
+  /**
+   * Describe this field.
+   *
+   * The description is shown next to the field's label in the Val editor, so
+   * it is where you say what an editor needs to know but the field name cannot
+   * carry. It also travels in the serialized schema, which is what the AI
+   * assistant and the MCP tools read.
+   *
+   * Pass `null` to clear a description set earlier.
+   *
+   * @example
+   * const schema = s.color().describe("Background of the hero section");
+   * export default c.define(
+   *   "/example.val.ts",
+   *   schema,
+   *   "hsl(217.22 91.22% 59.8%)",
+   * );
+   */
   _inherits(ColorSchema, _Schema);
   return _createClass(ColorSchema, [{
     key: "describe",
     value: function describe(description) {
       return new ColorSchema(this.options, this.opt, this.customValidateFunctions, this.isReadonly, this.isHidden, description !== null && description !== void 0 ? description : undefined, this.renderInput, this.previewInput);
     }
+
+    /**
+     * Add a custom validation rule to this field.
+     *
+     * The function is called with the field's value and returns `false` when the
+     * value is fine, or a STRING with the message to show when it is not. Call it
+     * more than once to add more rules — they all run, and every message is
+     * reported.
+     *
+     * Write the check as a ternary, not as `ok || "message"`: that returns `true`
+     * when the value is fine, and `true` is not one of the two answers.
+     *
+     * Validation runs in the Studio as you type, in `npx val validate` and
+     * before a publish.
+     *
+     * @example
+     * const schema = s
+     *   .color({ format: "hex" })
+     *   .validate((val) =>
+     *     val === val.toLowerCase() ? false : "Write hex in lower case",
+     *   );
+     * export default c.define("/example.val.ts", schema, "#3b82f6");
+     */
   }, {
     key: "validate",
     value: function validate(validationFunction) {
@@ -8441,7 +10864,7 @@ var ColorSchema = /*#__PURE__*/function (_Schema) {
   }, {
     key: "nullable",
     value: function nullable() {
-      return new ColorSchema(this.options, true, [], this.isReadonly, this.isHidden, this.description, this.renderInput, this.previewInput);
+      return new ColorSchema(this.options, true, this.customValidateFunctions, this.isReadonly, this.isHidden, this.description, this.renderInput, this.previewInput);
     }
   }, {
     key: "readonly",
@@ -8462,6 +10885,12 @@ var ColorSchema = /*#__PURE__*/function (_Schema) {
      * instead of a preview row that navigates to it.
      *
      * Static configuration, not a callback — see `render.ts`.
+     *
+     * @example
+     * const schema = s.array(s.color().render({ as: "inline" }));
+     * export default c.define("/example.val.ts", schema, [
+     *   "hsl(217.22 91.22% 59.8%)",
+     * ]);
      */
   }, {
     key: "render",
@@ -8473,6 +10902,14 @@ var ColorSchema = /*#__PURE__*/function (_Schema) {
      * How this VALUE is shown where a preview of it is needed — a row in a
      * sortable list, a reference dropdown, a search hit. Never how the field
      * itself is edited (that is `render`). See `preview.ts`.
+     *
+     * @example
+     * const schema = s.array(
+     *   s.color().preview(({ val }) => ({ title: val })),
+     * );
+     * export default c.define("/example.val.ts", schema, [
+     *   "hsl(217.22 91.22% 59.8%)",
+     * ]);
      */
   }, {
     key: "preview",
@@ -8601,6 +11038,8 @@ function initSchema() {
     array: array,
     object: object,
     number: number,
+    discriminatedUnion: discriminatedUnion,
+    "enum": enumSchema,
     union: union,
     // oneOf,
     richtext: richtext,
@@ -8614,6 +11053,7 @@ function initSchema() {
     datetime: datetime,
     color: color,
     code: code,
+    locale: locale,
     route: route,
     router: router,
     images: images,
@@ -8752,6 +11192,8 @@ var Hash = /*#__PURE__*/function () {
     _defineProperty(this, "F", 0x9b05688c | 0);
     _defineProperty(this, "G", 0x1f83d9ab | 0);
     _defineProperty(this, "H", 0x5be0cd19 | 0);
+    _defineProperty(this, "_byte", void 0);
+    _defineProperty(this, "_word", void 0);
     _defineProperty(this, "_size", 0);
     _defineProperty(this, "_sp", 0);
     if (!sharedBuffer || sharedOffset >= N.allocTotal) {
@@ -9519,32 +11961,26 @@ function hasRemoteFileSchema(schema) {
       }
     }
     return false;
-  } else if (schema.type === "union") {
-    var unionStringSchema = _typeof(schema.key) === "object" && schema.key.type === "literal" ? schema : undefined;
-    var unionObjectSchema = typeof schema.key === "string" ? schema : undefined;
-    if (unionStringSchema) {
-      // A string union's items are literals, so there is nothing to look inside.
-      return false;
-    }
-    if (unionObjectSchema) {
-      var _iterator = _createForOfIteratorHelper(unionObjectSchema.items),
-        _step;
-      try {
-        for (_iterator.s(); !(_step = _iterator.n()).done;) {
-          var item = _step.value;
-          var _hasRemoteFile = hasRemoteFileSchema(item);
-          if (_hasRemoteFile) {
-            return true;
-          }
+  } else if (schema.type === "discriminated-union") {
+    var _iterator = _createForOfIteratorHelper(schema.items),
+      _step;
+    try {
+      for (_iterator.s(); !(_step = _iterator.n()).done;) {
+        var item = _step.value;
+        var _hasRemoteFile = hasRemoteFileSchema(item);
+        if (_hasRemoteFile) {
+          return true;
         }
-      } catch (err) {
-        _iterator.e(err);
-      } finally {
-        _iterator.f();
       }
+    } catch (err) {
+      _iterator.e(err);
+    } finally {
+      _iterator.f();
     }
     return false;
-  } else if (schema.type === "boolean" || schema.type === "number" || schema.type === "string" || schema.type === "literal" || schema.type === "date" || schema.type === "dateTime" || schema.type === "color" || schema.type === "code" || schema.type === "keyOf" || schema.type === "route") {
+  } else if (schema.type === "boolean" ||
+  // An enum's values are strings, so there is nothing to look inside.
+  schema.type === "enum" || schema.type === "number" || schema.type === "string" || schema.type === "literal" || schema.type === "date" || schema.type === "dateTime" || schema.type === "color" || schema.type === "code" || schema.type === "keyOf" || schema.type === "route" || schema.type === "locale") {
     return false;
   } else {
     var exhaustiveCheck = schema;
@@ -9598,27 +12034,25 @@ function hasMediaSchema(schema) {
       }
     }
     return false;
-  } else if (schema.type === "union") {
-    var unionObjectSchema = typeof schema.key === "string" ? schema : undefined;
-    if (unionObjectSchema) {
-      var _iterator2 = _createForOfIteratorHelper(unionObjectSchema.items),
-        _step2;
-      try {
-        for (_iterator2.s(); !(_step2 = _iterator2.n()).done;) {
-          var item = _step2.value;
-          if (hasMediaSchema(item)) {
-            return true;
-          }
+  } else if (schema.type === "discriminated-union") {
+    var _iterator2 = _createForOfIteratorHelper(schema.items),
+      _step2;
+    try {
+      for (_iterator2.s(); !(_step2 = _iterator2.n()).done;) {
+        var item = _step2.value;
+        if (hasMediaSchema(item)) {
+          return true;
         }
-      } catch (err) {
-        _iterator2.e(err);
-      } finally {
-        _iterator2.f();
       }
+    } catch (err) {
+      _iterator2.e(err);
+    } finally {
+      _iterator2.f();
     }
-    // A string union's items are literals, so there is nothing to look inside.
     return false;
-  } else if (schema.type === "boolean" || schema.type === "number" || schema.type === "string" || schema.type === "literal" || schema.type === "date" || schema.type === "dateTime" || schema.type === "color" || schema.type === "code" || schema.type === "keyOf" || schema.type === "route" ||
+  } else if (schema.type === "boolean" ||
+  // An enum's values are strings, so there is nothing to look inside.
+  schema.type === "enum" || schema.type === "number" || schema.type === "string" || schema.type === "literal" || schema.type === "date" || schema.type === "dateTime" || schema.type === "color" || schema.type === "code" || schema.type === "keyOf" || schema.type === "route" || schema.type === "locale" ||
   // A settings module holds the assistant's configuration, not content, and
   // nothing in it is media.
   schema.type === "settings") {
@@ -9897,6 +12331,46 @@ function getFileHash(text) {
   return hashToRemoteFileHash(getSHA256Hash(new Uint8Array(text)));
 }
 
+/**
+ * The variant of a discriminated union that a value takes, by its tag.
+ *
+ * A discriminated union is a fork rather than a level: the variant IS the node,
+ * and everything a caller wants to know about that node — its fields, its
+ * `locale` field, the schema to draw it with — is on the variant and not on the
+ * union. Resolving it takes the source, so it cannot be done from the schema
+ * alone, which is why every caller that has only the union ends up needing this.
+ *
+ * `undefined` where the tag matches nothing, rather than a fallback to the first
+ * variant: a value whose tag names no variant is not a member of the union,
+ * validation is already saying so, and reading fields out of the wrong shape
+ * would answer confidently and wrongly.
+ *
+ * `s.enum()` never reaches here — it is a leaf whose values are strings, with no
+ * variants to resolve — so anything that is not a discriminated union answers
+ * `undefined` too.
+ */
+function discriminatedUnionBranchOf(schema, tag) {
+  if ((schema === null || schema === void 0 ? void 0 : schema.type) !== "discriminated-union") {
+    return undefined;
+  }
+  var _iterator = _createForOfIteratorHelper(schema.items),
+    _step;
+  try {
+    for (_iterator.s(); !(_step = _iterator.n()).done;) {
+      var item = _step.value;
+      var discriminator = item.items[schema.key];
+      if ((discriminator === null || discriminator === void 0 ? void 0 : discriminator.type) === "literal" && discriminator.value === tag) {
+        return item;
+      }
+    }
+  } catch (err) {
+    _iterator.e(err);
+  } finally {
+    _iterator.f();
+  }
+  return undefined;
+}
+
 function deserializeSchema(serialized) {
   var schema = deserializeSchemaImpl(serialized);
   if (serialized.readonly) {
@@ -9908,7 +12382,7 @@ function deserializeSchema(serialized) {
   return schema;
 }
 function deserializeSchemaImpl(serialized) {
-  var _serialized$options, _serialized$options2, _serialized$render, _serialized$multiline, _serialized$render2, _serialized$render3, _serialized$render4, _serialized$render5, _serialized$render6, _serialized$render7, _serialized$accept, _serialized$directory, _serialized$remote, _serialized$jsonValue, _serialized$render9, _serialized$external, _serialized$render0, _serialized$render10, _serialized$render11, _serialized$render12, _serialized$render13, _serialized$render14, _serialized$render15;
+  var _serialized$options, _serialized$options2, _serialized$render, _serialized$multiline, _serialized$render2, _serialized$render3, _serialized$render4, _serialized$render5, _serialized$render6, _serialized$render7, _serialized$render8, _serialized$accept, _serialized$directory, _serialized$remote, _serialized$jsonValue, _serialized$render0, _serialized$external, _serialized$render1, _serialized$render12, _serialized$render13, _serialized$render14, _serialized$render15, _serialized$render16, _serialized$render17;
   switch (serialized.type) {
     case "string":
       return new StringSchema(_objectSpread2(_objectSpread2({}, serialized.options), {}, {
@@ -9937,28 +12411,32 @@ function deserializeSchemaImpl(serialized) {
           key = _ref4[0],
           item = _ref4[1];
         return [key, deserializeSchema(item)];
-      })), serialized.opt, false, false, serialized.description);
+      })), serialized.opt, false, false, serialized.description,
+      // Carried through, or the Studio's validation worker — which only ever
+      // sees the deserialized schema — would run every field's own rules and
+      // none of the section's, so a language declared twice would be reported
+      // by the CLI and silently accepted in the Studio.
+      serialized.section);
     case "array":
       return new ArraySchema(deserializeSchema(serialized.item), serialized.opt, [], false, false, serialized.description,
       // The preview closure cannot survive serialization; the render can.
       null, (_serialized$render6 = serialized.render) !== null && _serialized$render6 !== void 0 ? _serialized$render6 : null);
-    case "union":
-      return new UnionSchema(typeof serialized.key === "string" ? serialized.key :
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
-      deserializeSchema(serialized.key),
-      // TODO: we do not really need any here - right?
+    case "discriminated-union":
+      return new DiscriminatedUnionSchema(serialized.key,
       // eslint-disable-next-line @typescript-eslint/no-explicit-any
       serialized.items.map(deserializeSchema),
       // TODO: we do not really need any here - right?
       serialized.opt, [], false, false, serialized.description, (_serialized$render7 = serialized.render) !== null && _serialized$render7 !== void 0 ? _serialized$render7 : null);
+    case "enum":
+      return new EnumSchema(serialized.values, serialized.opt, [], false, false, serialized.description, (_serialized$render8 = serialized.render) !== null && _serialized$render8 !== void 0 ? _serialized$render8 : null);
     case "richtext":
       {
-        var _serialized$options3, _serialized$options4, _serialized$options5, _serialized$options6, _serialized$render8;
+        var _serialized$options3, _serialized$options4, _serialized$options5, _serialized$options6, _serialized$render9;
         var deserializedOptions = _objectSpread2(_objectSpread2({}, serialized.options || {}), {}, {
           a: _typeof((_serialized$options3 = serialized.options) === null || _serialized$options3 === void 0 ? void 0 : _serialized$options3.a) === "object" ? deserializeSchema(serialized.options.a) : (_serialized$options4 = serialized.options) === null || _serialized$options4 === void 0 ? void 0 : _serialized$options4.a,
           img: _typeof((_serialized$options5 = serialized.options) === null || _serialized$options5 === void 0 ? void 0 : _serialized$options5.img) === "object" ? deserializeSchema(serialized.options.img) : (_serialized$options6 = serialized.options) === null || _serialized$options6 === void 0 ? void 0 : _serialized$options6.img
         });
-        return new RichTextSchema(deserializedOptions, serialized.opt, [], false, false, serialized.description, (_serialized$render8 = serialized.render) !== null && _serialized$render8 !== void 0 ? _serialized$render8 : null);
+        return new RichTextSchema(deserializedOptions, serialized.opt, [], false, false, serialized.description, (_serialized$render9 = serialized.render) !== null && _serialized$render9 !== void 0 ? _serialized$render9 : null);
       }
     case "record":
       return new RecordSchema(deserializeSchema(serialized.item), serialized.opt, [], null, serialized.key ? deserializeSchema(serialized.key) : null, serialized.mediaType ? {
@@ -9969,33 +12447,38 @@ function deserializeSchemaImpl(serialized) {
         altSchema: serialized.alt ? deserializeSchema(serialized.alt) : undefined
       } : undefined, false, false, serialized.description, (_serialized$jsonValue = serialized.jsonValues) !== null && _serialized$jsonValue !== void 0 ? _serialized$jsonValue : false,
       // The preview closure cannot survive serialization; the render can.
-      null, (_serialized$render9 = serialized.render) !== null && _serialized$render9 !== void 0 ? _serialized$render9 : null, // The external label is static data, so it survives serialization and
+      null, (_serialized$render0 = serialized.render) !== null && _serialized$render0 !== void 0 ? _serialized$render0 : null, // The external label is static data, so it survives serialization and
       // must be carried back: a deserialized schema that forgot it would walk
       // an external record as if its entries were local.
       (_serialized$external = serialized.external) !== null && _serialized$external !== void 0 ? _serialized$external : null);
     case "keyOf":
-      return new KeyOfSchema(serialized.schema, serialized.path, serialized.opt, [], false, false, serialized.description, (_serialized$render0 = serialized.render) !== null && _serialized$render0 !== void 0 ? _serialized$render0 : null);
+      return new KeyOfSchema(serialized.schema, serialized.path, serialized.opt, [], false, false, serialized.description, (_serialized$render1 = serialized.render) !== null && _serialized$render1 !== void 0 ? _serialized$render1 : null);
+    case "locale":
+      {
+        var _serialized$render10;
+        return new LocaleSchema(serialized.opt, [], false, false, serialized.description, (_serialized$render10 = serialized.render) !== null && _serialized$render10 !== void 0 ? _serialized$render10 : null);
+      }
     case "route":
       {
-        var _serialized$render1;
+        var _serialized$render11;
         var routeOptions = serialized.options ? {
           include: serialized.options.include ? new RegExp(serialized.options.include.source, serialized.options.include.flags) : undefined,
           exclude: serialized.options.exclude ? new RegExp(serialized.options.exclude.source, serialized.options.exclude.flags) : undefined
         } : undefined;
-        return new RouteSchema(routeOptions, serialized.opt, [], false, false, serialized.description, (_serialized$render1 = serialized.render) !== null && _serialized$render1 !== void 0 ? _serialized$render1 : null);
+        return new RouteSchema(routeOptions, serialized.opt, [], false, false, serialized.description, (_serialized$render11 = serialized.render) !== null && _serialized$render11 !== void 0 ? _serialized$render11 : null);
       }
     case "file":
-      return new FileSchema(serialized.options, serialized.opt, serialized.remote, [], {}, false, false, serialized.description, (_serialized$render10 = serialized.render) !== null && _serialized$render10 !== void 0 ? _serialized$render10 : null);
+      return new FileSchema(serialized.options, serialized.opt, serialized.remote, [], {}, false, false, serialized.description, (_serialized$render12 = serialized.render) !== null && _serialized$render12 !== void 0 ? _serialized$render12 : null);
     case "image":
-      return new ImageSchema(serialized.options, serialized.opt, serialized.remote, [], {}, false, false, serialized.description, (_serialized$render11 = serialized.render) !== null && _serialized$render11 !== void 0 ? _serialized$render11 : null);
+      return new ImageSchema(serialized.options, serialized.opt, serialized.remote, [], {}, false, false, serialized.description, (_serialized$render13 = serialized.render) !== null && _serialized$render13 !== void 0 ? _serialized$render13 : null);
     case "date":
-      return new DateSchema(serialized.options, serialized.opt, [], false, false, serialized.description, (_serialized$render12 = serialized.render) !== null && _serialized$render12 !== void 0 ? _serialized$render12 : null);
+      return new DateSchema(serialized.options, serialized.opt, [], false, false, serialized.description, (_serialized$render14 = serialized.render) !== null && _serialized$render14 !== void 0 ? _serialized$render14 : null);
     case "dateTime":
-      return new DateTimeSchema(serialized.options, serialized.opt, [], false, false, serialized.description, (_serialized$render13 = serialized.render) !== null && _serialized$render13 !== void 0 ? _serialized$render13 : null);
+      return new DateTimeSchema(serialized.options, serialized.opt, [], false, false, serialized.description, (_serialized$render15 = serialized.render) !== null && _serialized$render15 !== void 0 ? _serialized$render15 : null);
     case "color":
-      return new ColorSchema(serialized.options, serialized.opt, [], false, false, serialized.description, (_serialized$render14 = serialized.render) !== null && _serialized$render14 !== void 0 ? _serialized$render14 : null);
+      return new ColorSchema(serialized.options, serialized.opt, [], false, false, serialized.description, (_serialized$render16 = serialized.render) !== null && _serialized$render16 !== void 0 ? _serialized$render16 : null);
     case "code":
-      return new CodeSchema(serialized.options, serialized.opt, [], false, false, serialized.description, (_serialized$render15 = serialized.render) !== null && _serialized$render15 !== void 0 ? _serialized$render15 : null);
+      return new CodeSchema(serialized.options, serialized.opt, [], false, false, serialized.description, (_serialized$render17 = serialized.render) !== null && _serialized$render17 !== void 0 ? _serialized$render17 : null);
     default:
       {
         var exhaustiveCheck = serialized;
@@ -10204,10 +12687,11 @@ function previewScope(paths) {
  * question, and a disagreement between them is a row you can edit in place but
  * that "add" navigates away from.
  *
- * A tagged union counts as inline when the union itself declares it OR when
- * ANY of its variants does. A page-builder list is `s.array(s.union("type",
- * block, block, ...))` and the natural place to write the render is on the
- * blocks, one per block type — the union is a dispatch, not something the
+ * A discriminated union counts as inline when the union itself declares it OR
+ * when ANY of its variants does. A page-builder list is
+ * `s.array(s.discriminatedUnion("type", block, block, ...))` and the natural
+ * place to write the render is on the blocks, one per block type — the union
+ * is a dispatch, not something the
  * author thinks of as the field. `some` rather than `every` because the row
  * draws the union's own editor (the tag selector plus the matched variant's
  * fields), which handles every variant either way: with `every`, adding one
@@ -10224,7 +12708,7 @@ function isInlineRender(schema) {
   if (((_schema$render = schema.render) === null || _schema$render === void 0 ? void 0 : _schema$render.as) === "inline") {
     return true;
   }
-  if (schema.type === "union") {
+  if (schema.type === "discriminated-union") {
     return schema.items.some(function (item) {
       var _item$render;
       return ((_item$render = item.render) === null || _item$render === void 0 ? void 0 : _item$render.as) === "inline";
@@ -10661,7 +13145,7 @@ function isPageRouter(routerId) {
 
 var corePackageJson = {
 	name: "@valbuild/core",
-	version: "0.125.0",
+	version: "0.127.0",
 	"private": false,
 	description: "Val - supercharged hard-coded content",
 	repository: {
@@ -10832,4 +13316,4 @@ function tryJsonParse(str) {
   }
 }
 
-export { parseTanStackRoutePattern as $, ArraySchema as A, BooleanSchema as B, ColorSchema as C, DEFAULT_CONTENT_HOST as D, COLOR_FORMATS as E, FATAL_ERROR_TYPES as F, GenericSelector as G, DEFAULT_COLOR_FORMAT as H, Internal as I, DateTimeSchema as J, KeyOfSchema as K, RouteSchema as L, ModuleFilePathSep as M, NumberSchema as N, ObjectSchema as O, PatchError as P, RichTextSchema as Q, RecordSchema as R, Schema as S, LiteralSchema as T, UnionSchema as U, VAL_EXTENSION as V, deserializeSchema as W, previewScope as X, isInlineRender as Y, parseNextJsRoutePattern as Z, _typeof as _, _slicedToArray as a, tanStackSegmentsOfRoutePath as a0, validateUrlAgainstPattern as a1, getSourcePathFromRoute as a2, isPageRouter as a3, _createClass as b, _classCallCheck as c, _toConsumableArray as d, DEFAULT_APP_HOST as e, extractValModules as f, computeValModuleShas as g, hasRemoteFileSchema as h, initVal as i, hasMediaSchema as j, DEFAULT_VAL_REMOTE_HOST as k, derefPatch as l, modules as m, StringSchema as n, ImageSchema as o, FileSchema as p, DateSchema as q, SettingsSchema as r, splitModuleFilePathAndModulePath as s, ASSISTANT_SETTINGS_MAX_LENGTH as t, assistantAvailability as u, SETTINGS_MODULE_CONVENTION as v, isRootModuleFilePath as w, resolveSettingsModule as x, CodeSchema as y, CODE_LANGUAGES as z };
+export { DiscriminatedUnionSchema as $, ArraySchema as A, BooleanSchema as B, declaredKeySetOf as C, DEFAULT_CONTENT_HOST as D, missingDeclaredKeys as E, FATAL_ERROR_TYPES as F, GenericSelector as G, discriminatedUnionBranchOf as H, Internal as I, ColorSchema as J, CodeSchema as K, LocaleSchema as L, ModuleFilePathSep as M, NumberSchema as N, ObjectSchema as O, PatchError as P, CODE_LANGUAGES as Q, RecordSchema as R, Schema as S, COLOR_FORMATS as T, DEFAULT_COLOR_FORMAT as U, VAL_EXTENSION as V, DateTimeSchema as W, KeyOfSchema as X, RouteSchema as Y, RichTextSchema as Z, _typeof as _, _slicedToArray as a, EnumSchema as a0, LiteralSchema as a1, deserializeSchema as a2, previewScope as a3, isInlineRender as a4, parseNextJsRoutePattern as a5, parseTanStackRoutePattern as a6, tanStackSegmentsOfRoutePath as a7, validateUrlAgainstPattern as a8, getSourcePathFromRoute as a9, isPageRouter as aa, _createClass as b, _classCallCheck as c, _toConsumableArray as d, DEFAULT_APP_HOST as e, extractValModules as f, computeValModuleShas as g, hasRemoteFileSchema as h, initVal as i, hasMediaSchema as j, DEFAULT_VAL_REMOTE_HOST as k, derefPatch as l, modules as m, StringSchema as n, ImageSchema as o, FileSchema as p, DateSchema as q, SettingsSchema as r, splitModuleFilePathAndModulePath as s, ASSISTANT_SETTINGS_MAX_LENGTH as t, assistantAvailability as u, SETTINGS_MODULE_CONVENTION as v, isRootModuleFilePath as w, resolveSettingsModule as x, localeTagError as y, localeOfValue as z };