@varde-flyt/vfac 0.14.1 → 0.15.2

package/dist/vfac.mjs

@@ -12081,11 +12081,13 @@ function leafShapes(bounds) {
      * particular value could not say so, so `vfac plan`'s `requiredSecrets`
      * could not warn before a deploy, and the refusal arrived at apply.
      *
-     * ON A SECRET ONLY, and that is narrower than the mechanism could be. A
-     * value-conditioned requirement for an ORDINARY setting is a real gap too,
-     * but it changes what every door accepts for every property; this changes
-     * what `requiredSecrets` reports, which is one answer with one reader.
-     * Opening it wider is a separate decision with its own blast radius.
+     * IT BEGAN ON A ROOT SECRET ONLY, and was widened twice, each time as a
+     * decision of its own: to every ROOT setting, which the number shape below
+     * records, and then to a setting in a GROUP at any depth, which is where a
+     * credential belonging to one sign-in method actually lives. It is still
+     * refused on a setting BELOW A LIST, structurally — the leaf set the chain
+     * uses there does not declare the key — because a setting there has one
+     * path per row, and a condition makes one setting required.
      */
     "x-required-when": ValueConditionSchema.optional(),
     /**
@@ -12109,11 +12111,12 @@ function leafShapes(bounds) {
     maximum: external_exports.number(),
     default: external_exports.number().optional(),
     /**
-     * WIDENED FROM SECRETS TO EVERY ROOT SETTING, which this shape's own
-     * comment on the string leaf used to record as a known gap: "a
-     * value-conditioned requirement for an ORDINARY setting is a real gap
-     * too". It is the same keyword, the same evaluator and the same publish
-     * rules; what changes is which settings may carry it.
+     * WIDENED FROM SECRETS TO EVERY ROOT SETTING, which the string leaf's
+     * comment used to record as a known gap: "a value-conditioned requirement
+     * for an ORDINARY setting is a real gap too". It is the same keyword, the
+     * same evaluator and the same publish rules; what changes is which
+     * settings may carry it — and a setting in a group may too, since the
+     * chain's group leaf set keeps this key and only its list set omits it.
      */
     "x-required-when": ValueConditionSchema.optional()
   }).strict();
@@ -12158,14 +12161,33 @@ var ConfigurationPropertySchema = external_exports.discriminatedUnion("type", [
   BooleanPropertySchema,
   ArrayPropertySchema
 ]);
-var NestedStringPropertySchema = V2_LEAVES.string.omit({ "x-secret": true, writeOnly: true, "x-required-when": true }).extend({ group: ConfigurationGroupSchema.optional() });
-var V2_NESTED_LEAVES = {
-  string: NestedStringPropertySchema,
-  number: V2_LEAVES.number.omit({ "x-required-when": true }).extend({ group: ConfigurationGroupSchema.optional() }),
-  boolean: V2_LEAVES.boolean.omit({ "x-required-when": true }).extend({ group: ConfigurationGroupSchema.optional() }),
-  array: V2_LEAVES.array.omit({ "x-required-when": true }).extend({ group: ConfigurationGroupSchema.optional() }),
+var INHERITED_GROUP = { group: ConfigurationGroupSchema.optional() };
+var V2_GROUP_LEAVES = {
+  string: withJsonSchemaAnnex(V2_LEAVES.string.extend(INHERITED_GROUP), SECRET_COUPLING_ANNEX),
+  number: V2_LEAVES.number.extend(INHERITED_GROUP),
+  boolean: V2_LEAVES.boolean.extend(INHERITED_GROUP),
+  array: V2_LEAVES.array.extend(INHERITED_GROUP),
   items: V2_LEAVES.items
 };
+var V2_LIST_LEAVES = {
+  string: withJsonSchemaAnnex(V2_LEAVES.string.omit({ "x-required-when": true }).extend(INHERITED_GROUP), SECRET_COUPLING_ANNEX),
+  number: V2_LEAVES.number.omit({ "x-required-when": true }).extend(INHERITED_GROUP),
+  boolean: V2_LEAVES.boolean.omit({ "x-required-when": true }).extend(INHERITED_GROUP),
+  array: V2_LEAVES.array.omit({ "x-required-when": true }).extend(INHERITED_GROUP),
+  items: V2_LEAVES.items
+};
+var LIST_OF_GROUPS_CONDITION_ANNEX = {
+  allOf: [
+    {
+      $comment: "A list of groups inside a group may not carry x-required-when: the condition makes a setting required, and a list of groups is not one.",
+      if: {
+        properties: { items: { properties: { type: { const: "object" } }, required: ["type"] } },
+        required: ["items"]
+      },
+      then: { not: { required: ["x-required-when"] } }
+    }
+  ]
+};
 function childBagShape(child) {
   return {
     properties: external_exports.record(PropertyNameSchema, child),
@@ -12190,41 +12212,49 @@ function childBagShape(child) {
     additionalProperties: external_exports.literal(false)
   };
 }
-function propertyUnion(levelsBelow, leafSet) {
+var LEAF_SETS = { root: V2_LEAVES, group: V2_GROUP_LEAVES, list: V2_LIST_LEAVES };
+var LEVELS = /* @__PURE__ */ new Map();
+function levelUnion(levelsBelow, position) {
+  const key = `${position}:${levelsBelow}`;
+  const built = LEVELS.get(key);
+  if (built !== void 0)
+    return built;
+  const level = MAX_CONFIGURATION_DEPTH - levelsBelow;
+  const union = withJsonSchemaDefinition(external_exports.discriminatedUnion("type", propertyUnion(levelsBelow, position)), position === "group" ? `configurationPropertyLevel${level}` : `configurationListPropertyLevel${level}`);
+  LEVELS.set(key, union);
+  return union;
+}
+function propertyUnion(levelsBelow, position) {
+  const leafSet = LEAF_SETS[position];
   const leaves = [leafSet.string, leafSet.number, leafSet.boolean];
   if (levelsBelow <= 0) {
     return [...leaves, leafSet.array];
   }
-  const level = MAX_CONFIGURATION_DEPTH - levelsBelow + 1;
-  const child = withJsonSchemaDefinition(external_exports.discriminatedUnion("type", propertyUnion(levelsBelow - 1, V2_NESTED_LEAVES)), `configurationPropertyLevel${level}`);
-  const bag = childBagShape(child);
-  const groupItems = external_exports.object({ type: external_exports.literal("object"), ...bag }).strict();
+  const groupChild = levelUnion(levelsBelow - 1, position === "list" ? "list" : "group");
+  const rowChild = levelUnion(levelsBelow - 1, "list");
+  const groupItems = external_exports.object({ type: external_exports.literal("object"), ...childBagShape(rowChild) }).strict();
+  const list = leafSet.array.extend({
+    items: external_exports.discriminatedUnion("type", [V2_LEAVES.items, groupItems]),
+    /**
+     * Rules over the ROWS of this list — see {@link RowRulesSchema}.
+     *
+     * HERE RATHER THAN ON THE LEAF SHAPE, and that placement is the whole
+     * enforcement. `leafShapes().array` is also a v1 list and a last-level
+     * list, both of which hold STRINGS: a rule naming a field of a row would
+     * name nothing there, and `uniqueItems` is already the right keyword for
+     * comparing whole scalar entries. This branch is the only one in the chain
+     * where a list can hold groups, so declaring the keyword here makes "rows
+     * have fields" a property of the shape rather than a rule to remember.
+     *
+     * The refinement still has to refuse a rule on a list of STRINGS, because
+     * `items` is a discriminated union INSIDE this branch — the shape narrows
+     * where a row can exist, not whether this particular list has one.
+     */
+    "x-row-rules": RowRulesSchema.optional()
+  });
   return [
     ...leaves,
-    // ONE `array` BRANCH, NOT TWO, because a discriminated union may not carry
-    // two options with the same discriminator value ("duplicate value array" —
-    // zod refuses it at construction). The item shape is the inner
-    // discriminator, which is also what keeps a v1 document's
-    // `items: {type: 'string'}` reading exactly as it always did.
-    leafSet.array.extend({
-      items: external_exports.discriminatedUnion("type", [V2_LEAVES.items, groupItems]),
-      /**
-       * Rules over the ROWS of this list — see {@link RowRulesSchema}.
-       *
-       * HERE RATHER THAN ON THE LEAF SHAPE, and that placement is the whole
-       * enforcement. `leafShapes().array` is also a v1 list and a last-level
-       * list, both of which hold STRINGS: a rule naming a field of a row would
-       * name nothing there, and `uniqueItems` is already the right keyword for
-       * comparing whole scalar entries. This branch is the only one in the chain
-       * where a list can hold groups, so declaring the keyword here makes "rows
-       * have fields" a property of the shape rather than a rule to remember.
-       *
-       * The refinement still has to refuse a rule on a list of STRINGS, because
-       * `items` is a discriminated union INSIDE this branch — the shape narrows
-       * where a row can exist, not whether this particular list has one.
-       */
-      "x-row-rules": RowRulesSchema.optional()
-    }),
+    position === "group" ? withJsonSchemaAnnex(list, LIST_OF_GROUPS_CONDITION_ANNEX) : list,
     /**
      * A group of related settings.
      *
@@ -12235,20 +12265,23 @@ function propertyUnion(levelsBelow, leafSet) {
      * load-bearing "a defaulted setting is never absent", and what
      * `seedConfiguration` should write into a served example and a file on
      * disk. Defaults are a LEAF concept here.
+     *
+     * NO `x-required-when` EITHER, at any position: it makes a setting required,
+     * and a group is not a setting.
      */
     external_exports.object({
       type: external_exports.literal("object"),
       title: TitleSchema,
       description: helpTextSchema(V2_LEAF_BOUNDS).optional(),
-      // INHERITED BELOW THE ROOT, for the reason `V2_NESTED_LEAVES` states: a
+      // INHERITED BELOW THE ROOT, for the reason `INHERITED_GROUP` states: a
       // group is a bucket for a whole subtree, and repeating it is the only
       // value that could be written.
-      group: levelsBelow === MAX_CONFIGURATION_DEPTH - 1 ? ConfigurationGroupSchema : ConfigurationGroupSchema.optional(),
-      ...bag
+      group: position === "root" ? ConfigurationGroupSchema : ConfigurationGroupSchema.optional(),
+      ...childBagShape(groupChild)
     }).strict()
   ];
 }
-var RootConfigurationPropertySchema = external_exports.discriminatedUnion("type", propertyUnion(MAX_CONFIGURATION_DEPTH - 1, V2_LEAVES));
+var RootConfigurationPropertySchema = external_exports.discriminatedUnion("type", propertyUnion(MAX_CONFIGURATION_DEPTH - 1, "root"));
 var CustomerConfigurationObjectSchema = external_exports.object({
   type: external_exports.literal("object"),
   properties: external_exports.record(PropertyNameSchema, ConfigurationPropertySchema).describe("Customer-editable settings, keyed by camelCase property name."),
@@ -12314,7 +12347,7 @@ var CustomerConfigurationSchema = CustomerConfigurationObjectSchema.superRefine(
   }
   checkDependentRequired(config, ctx);
 });
-function checkDeclaredProperty(name, property, path, ctx, atRoot) {
+function checkDeclaredProperty(name, property, path, ctx, atRoot, underList2 = false) {
   const infrastructure = infrastructureVocabularyViolation(name);
   if (infrastructure) {
     ctx.addIssue({
@@ -12348,13 +12381,20 @@ function checkDeclaredProperty(name, property, path, ctx, atRoot) {
       ctx.addIssue({
         code: external_exports.ZodIssueCode.custom,
         path,
-        // THE REMEDIATION HAS TO BE ONE THE CONTRACT ALLOWS. At the root, the
-        // answer is to declare the two markers. Below it, that answer is
-        // IMPOSSIBLE — the nested shape omits both keys and `.strict()` refuses
-        // them — so telling a publisher to add them sends them to write a
-        // second invalid document, and an agent following the validator loops.
-        // A validator's errors are part of the agent-facing contract.
-        message: atRoot ? `${credential} and must be declared "x-secret": true with "writeOnly": true, or renamed if it is not one.` : `${credential}, and a credential must be a TOP-LEVEL setting in this contract format \u2014 move it out of the group and declare it "x-secret": true with "writeOnly": true, or rename it if it is not one.`
+        // THE REMEDIATION HAS TO BE ONE THE CONTRACT ALLOWS. In a group, as at
+        // the root, the answer is to declare the two markers. Below a LIST that
+        // answer is impossible — a secret is refused there, below — so telling a
+        // publisher to add them sends them to write a second invalid document,
+        // and an agent following the validator loops. A validator's errors are
+        // part of the agent-facing contract.
+        message: underList2 ? `${credential}, and a secret cannot be declared inside a list in this contract format \u2014 move it out of the list and declare it "x-secret": true with "writeOnly": true, or rename it if it is not one.` : `${credential} and must be declared "x-secret": true with "writeOnly": true, or renamed if it is not one.`
+      });
+    }
+    if (underList2 && (secret || property.writeOnly === true)) {
+      ctx.addIssue({
+        code: external_exports.ZodIssueCode.custom,
+        path,
+        message: `"${name}": a secret cannot be declared inside a list in this contract format. Declare it in a group or at the root.`
       });
     }
     if (secret && property.writeOnly !== true) {
@@ -12549,9 +12589,9 @@ function checkDependentRequired(config, ctx, at = []) {
       }
     }
   }
-  checkOneSecretPerGroup(config, ctx);
+  checkOneSecretPerGroup(config, ctx, at);
 }
-function checkOneSecretPerGroup(config, ctx) {
+function checkOneSecretPerGroup(config, ctx, at = []) {
   const clauses = Object.entries(config.dependentRequired ?? {});
   if (clauses.length === 0)
     return;
@@ -12595,11 +12635,238 @@ function checkOneSecretPerGroup(config, ctx) {
       code: external_exports.ZodIssueCode.custom,
       // The component has no single name, so the issue is reported against the
       // map rather than against whichever member happened to be visited first.
-      path: ["dependentRequired"],
+      path: [...at, "dependentRequired"],
       message: `These settings are configured together and include more than one secret (${secrets.join(", ")}). Only one secret can be supplied per change, so a group must ask for at most one \u2014 otherwise completing it on a running resource takes several, in an order the customer has to work out.`
     });
   }
 }
+function checkOptionalGroupActivation(config, ctx) {
+  const context = { root: config, acceptsOutside: /* @__PURE__ */ new Map() };
+  const check = (container, at, segments) => {
+    const required = new Set(container.required ?? []);
+    for (const [name, property] of Object.entries(container.properties)) {
+      if (property.type !== "object")
+        continue;
+      const path = [...at, "properties", name];
+      const inner = [...segments, name];
+      if (!required.has(name)) {
+        const { secrets, conditional } = activationSecrets(context, property, inner);
+        if (secrets.length > 1) {
+          ctx.addIssue({
+            code: external_exports.ZodIssueCode.custom,
+            path,
+            message: `"${name}" is optional, and adding it to a resource that already exists requires more than one secret (${secrets.join(", ")}). Only one secret can be supplied per change, so an optional group must ask for at most one \u2014 otherwise a resource created without it can never add it. Require at most one of them, or make the group required, with every group above it, so it is supplied when the resource is created.` + conditionalActivationSentence(conditional)
+          });
+        }
+      }
+      check(property, path, inner);
+    }
+  };
+  check(config, [], []);
+}
+function conditionalActivationSentence(conditional) {
+  if (conditional.length === 0)
+    return "";
+  const one = conditional.length === 1;
+  return ` ${conditional.join(", ")} ${one ? "is" : "are"} counted although ${one ? "it is" : "they are"} conditional: adding the group always turns ${one ? "its" : "their"} "x-required-when" on, because the setting ${one ? "that condition reads" : "each condition reads"} is then present and no value it accepts outside "anyOf" was found. Let ${one ? "that" : "such a"} setting be left out, or declare an "enum" for it that includes a value outside "anyOf".`;
+}
+function declarationKey(segments) {
+  return `/${segments.join("/")}`;
+}
+function activationSecrets(context, group, segments) {
+  const carriers = conditionCarriersBelow(group, segments);
+  const unavoidable = /* @__PURE__ */ new Set();
+  const unconditioned = walkActivation(group, segments, unavoidable);
+  let walk = unconditioned;
+  for (; ; ) {
+    const found = carriers.filter((carrier) => !unavoidable.has(carrier.key) && conditionUnavoidable(context, segments, carrier.condition, walk));
+    if (found.length === 0)
+      break;
+    for (const carrier of found)
+      unavoidable.add(carrier.key);
+    walk = walkActivation(group, segments, unavoidable);
+  }
+  const secrets = [...walk.secrets].sort();
+  return {
+    secrets,
+    conditional: secrets.filter((path) => unavoidable.has(path) && !unconditioned.secrets.has(path))
+  };
+}
+function walkActivation(group, segments, unavoidable) {
+  const secrets = /* @__PURE__ */ new Set();
+  const demanded = /* @__PURE__ */ new Set();
+  const sent = /* @__PURE__ */ new Set();
+  const onTheWay = /* @__PURE__ */ new Set();
+  for (const carrier of unavoidable) {
+    const parts = carrier.slice(1).split("/");
+    for (let depth = segments.length + 1; depth <= parts.length; depth += 1) {
+      onTheWay.add(declarationKey(parts.slice(0, depth)));
+    }
+  }
+  const visit = (node, nodeSegments) => {
+    sent.add(declarationKey(nodeSegments));
+    const pending = [
+      ...node.required ?? [],
+      ...Object.keys(node.properties).filter((name) => onTheWay.has(declarationKey([...nodeSegments, name])))
+    ];
+    const seen = /* @__PURE__ */ new Set();
+    while (pending.length > 0) {
+      const name = pending.pop();
+      if (seen.has(name))
+        continue;
+      seen.add(name);
+      if (!Object.hasOwn(node.properties, name))
+        continue;
+      const property = node.properties[name];
+      const key = declarationKey([...nodeSegments, name]);
+      demanded.add(key);
+      if (isSecretProperty(property)) {
+        secrets.add(key);
+      } else if (property.type === "object") {
+        visit(property, [...nodeSegments, name]);
+      }
+      const clauses = node.dependentRequired;
+      if (clauses !== void 0 && Object.hasOwn(clauses, name))
+        pending.push(...clauses[name]);
+    }
+  };
+  visit(group, segments);
+  return { secrets, demanded, sent };
+}
+function conditionCarriersBelow(group, segments) {
+  const out = [];
+  const collect = (node, nodeSegments) => {
+    for (const [name, property] of Object.entries(node.properties)) {
+      const here = [...nodeSegments, name];
+      if (property.type === "object") {
+        collect(property, here);
+        continue;
+      }
+      const condition = property["x-required-when"];
+      if (condition !== void 0)
+        out.push({ key: declarationKey(here), condition });
+    }
+  };
+  collect(group, segments);
+  return out;
+}
+function conditionUnavoidable(context, group, condition, walk) {
+  const target = resolveConditionTarget(context.root, condition.path);
+  if (target === null)
+    return false;
+  const { property } = target;
+  if (property.type !== "string" || isSecretProperty(property))
+    return false;
+  const groupOrAbove = (segments) => segments.length <= group.length && segments.every((segment, i) => group[i] === segment);
+  const inside = (segments) => segments.length > group.length && group.every((segment, i) => segments[i] === segment);
+  let belowList = false;
+  for (const container of target.containers) {
+    if (container.kind === "group" && groupOrAbove(container.segments))
+      continue;
+    if (container.kind === "list" && condition.anyRow !== true)
+      return false;
+    const key = declarationKey(container.segments);
+    const present2 = !belowList && inside(container.segments) ? container.kind === "group" ? walk.sent.has(key) : walk.demanded.has(key) : container.required;
+    if (!present2)
+      return false;
+    if (container.kind === "list") {
+      if (container.minItems < 1)
+        return false;
+      belowList = true;
+    }
+  }
+  const defaulted = property.default !== void 0;
+  const present = !belowList && inside(target.segments) ? walk.demanded.has(declarationKey(target.segments)) || defaulted && walk.sent.has(declarationKey(target.segments.slice(0, -1))) : target.required || defaulted;
+  if (!present)
+    return false;
+  let outside = context.acceptsOutside.get(condition);
+  if (outside === void 0) {
+    outside = acceptsValueOutside(property, condition.anyOf);
+    context.acceptsOutside.set(condition, outside);
+  }
+  return !outside;
+}
+function resolveConditionTarget(root, path) {
+  const pointer = path.startsWith("/");
+  const segments = pointer ? path.slice(1).split("/") : [path];
+  if (pointer && segments.length < 2)
+    return null;
+  if (!segments.every((segment) => CONFIGURATION_PROPERTY_NAME_REGEX.test(segment)))
+    return null;
+  const containers = [];
+  let holder = root;
+  for (const [index, name] of segments.entries()) {
+    if (!Object.hasOwn(holder.properties, name))
+      return null;
+    const property = holder.properties[name];
+    const here = segments.slice(0, index + 1);
+    const required = (holder.required ?? []).includes(name);
+    const last = index === segments.length - 1;
+    if (property.type === "object") {
+      if (last)
+        return null;
+      containers.push({ segments: here, kind: "group", required, minItems: 0 });
+      holder = property;
+    } else if (property.type === "array" && property.items.type === "object") {
+      if (last)
+        return null;
+      containers.push({ segments: here, kind: "list", required, minItems: property.minItems ?? 0 });
+      holder = property.items;
+    } else {
+      return last ? { segments, containers, property, required } : null;
+    }
+  }
+  return null;
+}
+function acceptsValueOutside(property, anyOf) {
+  let pattern = null;
+  if (property.pattern !== void 0) {
+    try {
+      pattern = new RegExp(property.pattern);
+    } catch {
+      return false;
+    }
+  }
+  const accepts = (value) => !anyOf.includes(value) && value.trim().length > 0 && (property.enum === void 0 || property.enum.includes(value)) && (property.minLength === void 0 || value.length >= property.minLength) && (property.maxLength === void 0 || value.length <= property.maxLength) && (pattern === null || pattern.test(value));
+  if (property.enum !== void 0)
+    return property.enum.some(accepts);
+  if (property.default !== void 0 && accepts(property.default))
+    return true;
+  const floor = property.minLength ?? 0;
+  const ceiling = Math.min(property.maxLength ?? floor + 3, floor + 3);
+  for (let length = Math.max(floor, 1); length <= ceiling; length += 1) {
+    for (const fill of ["x", "a", "0"]) {
+      if (accepts(fill.repeat(length)))
+        return true;
+    }
+  }
+  for (const word of property.pattern?.match(/[A-Za-z0-9_-]+/g) ?? []) {
+    if (accepts(word))
+      return true;
+  }
+  for (const value of anyOf) {
+    for (let index = 0; index < value.length; index += 1) {
+      const variant = value.slice(0, index) + sameClassCharacter(value.charAt(index)) + value.slice(index + 1);
+      if (accepts(variant))
+        return true;
+    }
+  }
+  return false;
+}
+function sameClassCharacter(character) {
+  const code = character.charCodeAt(0);
+  for (const [first, last] of [
+    ["0", "9"],
+    ["a", "z"],
+    ["A", "Z"]
+  ]) {
+    const start = first.charCodeAt(0);
+    const end = last.charCodeAt(0);
+    if (code >= start && code <= end)
+      return String.fromCharCode(code === end ? start : code + 1);
+  }
+  return "x";
+}
 var CustomerConfigurationV2ObjectSchema = external_exports.object({
   type: external_exports.literal("object"),
   properties: external_exports.record(PropertyNameSchema, RootConfigurationPropertySchema).describe("Customer-editable settings, keyed by camelCase property name."),
@@ -12683,10 +12950,10 @@ function minimumPropertyBytes(property) {
 function declaredLeafDefault(property) {
   return property.type === "object" ? void 0 : property.default;
 }
-function checkPropertyDeclaration(name, property, path, ctx, atRoot) {
+function checkPropertyDeclaration(name, property, path, ctx, atRoot, underList2 = false) {
   const children = childrenOf(property);
   if (children === null) {
-    checkDeclaredProperty(name, property, path, ctx, atRoot);
+    checkDeclaredProperty(name, property, path, ctx, atRoot, underList2);
     return;
   }
   const infrastructure = infrastructureVocabularyViolation(name);
@@ -12732,8 +12999,15 @@ function checkPropertyDeclaration(name, property, path, ctx, atRoot) {
       message: `"${name}" has minItems greater than maxItems.`
     });
   }
+  if (!atRoot && property.type === "array" && property["x-required-when"] !== void 0) {
+    ctx.addIssue({
+      code: external_exports.ZodIssueCode.custom,
+      path: [...path, "x-required-when"],
+      message: `"${name}" is a list of groups, and "x-required-when" may not be declared on one inside a group. The condition makes one setting required, and a list of groups is not a setting \u2014 declare the condition on a setting instead.`
+    });
+  }
   for (const childName of childNames) {
-    checkPropertyDeclaration(childName, children.properties[childName], [...path, "properties", childName], ctx, false);
+    checkPropertyDeclaration(childName, children.properties[childName], [...path, "properties", childName], ctx, false, underList2 || property.type === "array");
   }
   for (const required of children.required ?? []) {
     if (!Object.hasOwn(children.properties, required)) {
@@ -12816,6 +13090,7 @@ var CustomerConfigurationV2Schema = CustomerConfigurationV2ObjectSchema.superRef
   }
   checkDependentRequired(config, ctx);
   checkOneSecretPerGroup(config, ctx);
+  checkOptionalGroupActivation(config, ctx);
 });
 function enumerableValues(property) {
   const out = [];
@@ -12876,13 +13151,16 @@ function parseConfigurationPath(raw) {
     return null;
   return configurationPath(...segments);
 }
+function secretPathOf(raw) {
+  const path = parseConfigurationPath(raw);
+  if (path === null)
+    return null;
+  return pathSegments(path).some((segment) => typeof segment === "number") ? null : path;
+}
 function pathSegments(path) {
   const raw = path.startsWith("/") ? path.slice(1).split("/") : [path];
   return raw.map((segment) => isIndexSegment(segment) ? Number(segment) : segment);
 }
-function rootSegment(path) {
-  return String(pathSegments(path)[0]);
-}
 function declarationPathOf(path) {
   const segments = pathSegments(path).filter((segment) => typeof segment !== "number");
   return configurationPath(...segments) ?? path;
@@ -12929,9 +13207,29 @@ function canonicalJson(value) {
 function immediateContainer(node) {
   return node.containers[node.containers.length - 1] ?? null;
 }
+function resolvedGroup(node) {
+  for (const container of node.containers) {
+    const declared = container.property.group;
+    if (declared !== void 0)
+      return declared;
+  }
+  return node.property.group;
+}
 function underList(node) {
   return node.containers.some((container) => container.kind === "array");
 }
+function containersRequiredToRoot(schema, node) {
+  const rootRequired = schema.required ?? [];
+  return node.containers.every((container, index) => {
+    const parent = node.containers[index - 1];
+    return (parent === void 0 ? rootRequired : parent.required).includes(container.name);
+  });
+}
+function requiredToRoot(schema, node) {
+  const parent = immediateContainer(node);
+  const declared = parent === null ? schema.required ?? [] : parent.required;
+  return declared.includes(node.name) && containersRequiredToRoot(schema, node);
+}
 function containerChildren(property) {
   if (property.type === "object" && property.properties !== void 0) {
     return {
@@ -12990,6 +13288,9 @@ function walkDeclarations(properties, ancestors, base, onLeaf, onContainer = ()
     walkDeclarations(children.properties, [...ancestors, container], segments, onLeaf, onContainer);
   }
 }
+function declaredSecretPaths(schema) {
+  return configurationLeaves(schema).filter((leaf) => isSecretProperty(leaf.property) && !underList(leaf)).map((leaf) => leaf.path).sort();
+}
 function declaredDefault(property) {
   if (property.type === "object")
     return void 0;
@@ -13025,7 +13326,8 @@ function expandDeclarationPath(configuration, declaration) {
     const [head, ...rest] = remaining;
     if (head === void 0)
       return;
-    walk(cursor[String(head)], rest, [...soFar, head]);
+    const key = String(head);
+    walk(Object.hasOwn(cursor, key) ? cursor[key] : void 0, rest, [...soFar, head]);
   };
   walk(configuration, segmentsOf(declaration), []);
   return out;
@@ -13039,7 +13341,7 @@ function valueAt(configuration, path) {
       cursor = cursor[segment];
       continue;
     }
-    if (!isPlainObject(cursor))
+    if (!isPlainObject(cursor) || !Object.hasOwn(cursor, segment))
       return void 0;
     cursor = cursor[segment];
   }
@@ -13055,7 +13357,7 @@ function valuesAt(configuration, path) {
           next.push(cursor[segment]);
         continue;
       }
-      if (!isPlainObject(cursor))
+      if (!isPlainObject(cursor) || !Object.hasOwn(cursor, segment))
         continue;
       const value = cursor[segment];
       if (Array.isArray(value))
@@ -13076,10 +13378,6 @@ function segmentsOf(path) {
 function conditionSetting(condition) {
   return "path" in condition ? condition.path : condition.property;
 }
-function conditionRoot(condition) {
-  const path = parseConfigurationPath(conditionSetting(condition));
-  return path === null ? conditionSetting(condition) : rootSegment(path);
-}
 function conditionHolds(condition, configuration) {
   const path = parseConfigurationPath(conditionSetting(condition));
   if (path === null)
@@ -13087,6 +13385,28 @@ function conditionHolds(condition, configuration) {
   const matches2 = (held) => typeof held === "string" && condition.anyOf.includes(held);
   return "anyRow" in condition && condition.anyRow === true ? valuesAt(configuration, path).some(matches2) : matches2(valueAt(configuration, path));
 }
+function conditionOf(property) {
+  return property?.["x-required-when"];
+}
+function conditionCarriers(schema) {
+  const settings = configurationLeaves(schema).flatMap((leaf) => {
+    const condition = conditionOf(leaf.property);
+    if (condition === void 0 || underList(leaf))
+      return [];
+    const { path, name, containers, property } = leaf;
+    return [{ kind: "leaf", path, name, containers, property, condition }];
+  });
+  const lists = configurationContainers(schema).flatMap((container) => {
+    const condition = conditionOf(container.property);
+    if (condition === void 0 || container.kind !== "array" || container.containers.length > 0)
+      return [];
+    const { path, name, containers, property } = container;
+    return [{ kind: "container", path, name, containers, property, condition }];
+  });
+  const roots = Object.keys(schema.properties);
+  const rootIndex = (carrier) => roots.indexOf(carrier.containers[0]?.name ?? carrier.name);
+  return [...settings, ...lists].sort((a, b) => rootIndex(a) - rootIndex(b));
+}
 
 // ../product-configuration/dist/customer-configuration-input.js
 var ABSOLUTE_MAX_STRING = MAX_DECLARABLE_STRING_LENGTH;
@@ -13096,6 +13416,7 @@ function isPlainObject2(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function report(walk, field, message) {
+  walk.reported.add(field);
   if (walk.issues.length >= MAX_CONFIGURATION_ISSUES) {
     walk.suppressed += 1;
     return;
@@ -13111,7 +13432,10 @@ function validateSubmittedConfiguration(schema, submitted, presence = {}) {
     issues: [],
     suppressed: 0,
     leaves: 0,
-    referenced: new Set(presence.referenced ?? [])
+    referenced: new Set(presence.referenced ?? []),
+    present: new Set(presence.present ?? []),
+    unknown: new Set(presence.unknown ?? []),
+    reported: /* @__PURE__ */ new Set()
   };
   const supplied = /* @__PURE__ */ new Set();
   if (submitted !== void 0 && submitted !== null && !isPlainObject2(submitted)) {
@@ -13124,7 +13448,7 @@ function validateSubmittedConfiguration(schema, submitted, presence = {}) {
   const input = isPlainObject2(submitted) ? submitted : {};
   const secrets = {};
   const configuration = validateObject({ properties: schema.properties, required: schema.required }, input, null, walk, { secrets, supplied });
-  drain(walk, crossFieldIssues(schema, supplied, presence, configuration));
+  drain(walk, crossFieldIssues(schema, supplied, presence, configuration, walk.reported));
   drain(walk, rowAndReferenceIssues(schema, presence, configuration));
   if (walk.suppressed > 0) {
     walk.issues.push({
@@ -13149,13 +13473,17 @@ function declaresContainer(schema) {
   return Object.values(schema.properties).some((property) => isConfigurationContainer(property));
 }
 function containsReferenced(walk, container) {
-  if (walk.referenced.size === 0)
-    return false;
+  return containsAny(walk.referenced, container);
+}
+function referencedAtOrInside(walk, path) {
+  return walk.referenced.has(path) || containsReferenced(walk, path);
+}
+function containsAny(candidates, container) {
   const parsedOuter = parseConfigurationPath(container);
   if (parsedOuter === null)
     return false;
   const outer = pathSegments(parsedOuter);
-  for (const candidate of walk.referenced) {
+  for (const candidate of candidates) {
     const parsed = parseConfigurationPath(candidate);
     if (parsed === null)
       continue;
@@ -13167,7 +13495,7 @@ function containsReferenced(walk, container) {
   }
   return false;
 }
-function validateObject(declaration, input, container, walk, root) {
+function validateObject(declaration, input, container, walk, sink) {
   const required = new Set(declaration.required ?? []);
   const out = {};
   const fieldFor = (name) => {
@@ -13185,11 +13513,13 @@ function validateObject(declaration, input, container, walk, root) {
     const field = fieldFor(name);
     const children = containerDeclaration(property);
     if (children !== null) {
-      const value = input[name];
-      const filled = validateContainer(name, property, children, value, field, walk);
+      const value = Object.hasOwn(input, name) ? input[name] : void 0;
+      const filled = validateContainer(name, property, children, value, field, walk, sink);
+      if (value === void 0)
+        absentGroupRuleIssues(children, field, walk, sink, required.has(name));
       if (filled !== void 0)
         out[name] = filled;
-      else if (required.has(name) && !containsReferenced(walk, field))
+      else if (required.has(name) && !((containsReferenced(walk, field) || containsAny(walk.present, field) || sink !== null && containsAny(Object.keys(sink.secrets), field)) && (value !== void 0 || absentGroupAnswered(children, field, walk))))
         report(walk, field, "This setting is required.");
       continue;
     }
@@ -13204,9 +13534,13 @@ function validateObject(declaration, input, container, walk, root) {
     const raw = input[name];
     const blank = typeof raw === "string" && raw.trim().length === 0;
     const present = Object.hasOwn(input, name) && raw !== void 0 && !blank;
-    const secret = root !== null && isSecretProperty(leaf);
-    if (present && root !== null && container === null)
-      root.supplied.add(name);
+    const secret = isSecretProperty(leaf);
+    if (secret && sink === null) {
+      report(walk, field, "This Product declares a secret inside a list, which this contract format does not support.");
+      continue;
+    }
+    if (present && sink !== null && field !== "")
+      sink.supplied.add(field);
     if (!present) {
       const fallback = secret ? void 0 : defaultOf(leaf);
       if (fallback !== void 0) {
@@ -13225,27 +13559,96 @@ function validateObject(declaration, input, container, walk, root) {
       continue;
     }
     if (secret) {
-      if (typeof checked === "string" && checked.length > 0)
-        root.secrets[name] = checked;
+      if (typeof checked === "string" && checked.length > 0 && field !== "")
+        sink.secrets[field] = checked;
       else if (required.has(name))
         report(walk, field, "This setting is required.");
       continue;
     }
     out[name] = checked;
   }
-  if (declaration.dependentRequired !== void 0) {
-    const suppliedHere = new Set(Object.keys(out));
-    for (const [trigger, dependents] of Object.entries(declaration.dependentRequired)) {
-      if (!suppliedHere.has(trigger) && !containsReferenced(walk, fieldFor(trigger)))
+  groupRuleIssues(declaration, new Set(Object.keys(out)), container, walk, sink);
+  return out;
+}
+function groupRuleIssues(declaration, suppliedHere, container, walk, sink) {
+  if (declaration.dependentRequired === void 0)
+    return;
+  const fieldFor = (name) => (container === null ? configurationPath(name) : configurationPath(...pathSegments(container), name)) ?? "";
+  const answered = (name) => {
+    const path = fieldFor(name);
+    return suppliedHere.has(name) || // A MEMBER, NOT A CONTAINER: a referenced leaf is recorded at this very
+    // path, and a member group is answered by a reference inside it. Asking
+    // only "inside" never counted a referenced leaf, so a referenced trigger
+    // turned nothing on and a referenced dependent was reported missing.
+    referencedAtOrInside(walk, path) || walk.present.has(path) || sink !== null && Object.hasOwn(sink.secrets, path);
+  };
+  const unseen = (name) => walk.unknown.has(fieldFor(name));
+  const reported = /* @__PURE__ */ new Set();
+  for (const [trigger, dependents] of Object.entries(declaration.dependentRequired)) {
+    if (unseen(trigger) || !answered(trigger))
+      continue;
+    for (const dependent of dependents) {
+      if (unseen(dependent) || answered(dependent) || reported.has(dependent))
         continue;
-      for (const dependent of dependents) {
-        if (suppliedHere.has(dependent) || containsReferenced(walk, fieldFor(dependent)))
-          continue;
-        report(walk, fieldFor(dependent), `This setting is required when ${labelOf(declaration, trigger)} is configured.`);
-      }
+      reported.add(dependent);
+      report(walk, fieldFor(dependent), `This setting is required when ${labelOf(declaration, trigger)} is configured.`);
     }
   }
-  return out;
+}
+function absentGroupRuleIssues(children, field, walk, sink, coveredByParent) {
+  if (children.kind !== "object" || sink === null)
+    return;
+  const path = parseConfigurationPath(field);
+  if (path === null)
+    return;
+  groupRuleIssues(children, /* @__PURE__ */ new Set(), path, walk, sink);
+  const configured = containsReferenced(walk, field) || containsAny(walk.present, field);
+  const required = new Set(children.required ?? []);
+  for (const [name, property] of Object.entries(children.properties)) {
+    const memberField = configurationPath(...pathSegments(path), name);
+    if (memberField === null)
+      continue;
+    const demanded = configured && !coveredByParent && required.has(name) && !walk.unknown.has(memberField);
+    const inner = containerDeclaration(property);
+    if (inner === null) {
+      if (!demanded || walk.referenced.has(memberField) || walk.present.has(memberField))
+        continue;
+      if (!isSecretProperty(property) && defaultOf(property) !== void 0)
+        continue;
+      report(walk, memberField, "This setting is required.");
+      continue;
+    }
+    if (demanded && inner.kind === "object" && !(containsReferenced(walk, memberField) || containsAny(walk.present, memberField))) {
+      report(walk, memberField, "This setting is required.");
+      continue;
+    }
+    absentGroupRuleIssues(inner, memberField, walk, sink, coveredByParent && required.has(name));
+  }
+}
+function absentGroupAnswered(children, field, walk) {
+  if (children.kind !== "object")
+    return true;
+  const parent = parseConfigurationPath(field);
+  if (parent === null)
+    return false;
+  for (const name of children.required ?? []) {
+    const property = children.properties[name];
+    const path = configurationPath(...pathSegments(parent), name);
+    if (property === void 0 || path === null)
+      return false;
+    const inner = containerDeclaration(property);
+    if (inner !== null) {
+      if (!(containsReferenced(walk, path) || containsAny(walk.present, path)) || !absentGroupAnswered(inner, path, walk))
+        return false;
+      continue;
+    }
+    if (walk.referenced.has(path) || walk.present.has(path))
+      continue;
+    if (!isSecretProperty(property) && defaultOf(property) !== void 0)
+      continue;
+    return false;
+  }
+  return true;
 }
 function containerDeclaration(property) {
   if (property.type === "object" && property.properties !== void 0) {
@@ -13275,7 +13678,7 @@ function containerDeclaration(property) {
   }
   return null;
 }
-function validateContainer(name, property, children, value, field, walk) {
+function validateContainer(name, property, children, value, field, walk, sink) {
   const path = parseConfigurationPath(field);
   if (children.kind === "object") {
     if (value === void 0)
@@ -13284,7 +13687,7 @@ function validateContainer(name, property, children, value, field, walk) {
       report(walk, field, "Expected a group of settings.");
       return void 0;
     }
-    const filled = validateObject(children, value, path, walk, null);
+    const filled = validateObject(children, value, path, walk, sink);
     return Object.keys(filled).length === 0 ? void 0 : filled;
   }
   if (value === void 0)
@@ -13323,10 +13726,10 @@ function validateContainer(name, property, children, value, field, walk) {
   }
   return out;
 }
-function crossFieldIssues(schema, supplied, presence, configuration = {}) {
+function crossFieldIssues(schema, supplied, presence, configuration, reportedByWalk) {
   const clauses = Object.entries(schema.dependentRequired ?? {});
-  const conditional = Object.entries(schema.properties).filter(([, property]) => conditionOf(property) !== void 0);
-  if (clauses.length === 0 && conditional.length === 0)
+  const carriers = conditionCarriers(schema);
+  if (clauses.length === 0 && carriers.length === 0)
     return [];
   const alsoPresent = /* @__PURE__ */ new Set([...presence.present ?? [], ...presence.referenced ?? []]);
   const unknown = new Set(presence.unknown ?? []);
@@ -13349,22 +13752,28 @@ function crossFieldIssues(schema, supplied, presence, configuration = {}) {
       });
     }
   }
-  for (const [name, property] of conditional) {
-    const condition = conditionOf(property);
-    if (condition === void 0 || !known(name) || held(name))
+  for (const { path, condition } of carriers) {
+    if (!known(path) || held(path))
       continue;
-    if (!conditionHolds(condition, configuration))
+    const target = parseConfigurationPath(conditionSetting(condition));
+    if (target === null || !conditionHolds(condition, configuration))
       continue;
-    if (reported.has(name))
+    if (reported.has(path) || reportedByWalk.has(path))
       continue;
-    reported.add(name);
+    reported.add(path);
     issues.push({
-      field: name,
+      field: path,
       // THE SETTING THAT MADE IT NECESSARY, never the value it holds. A message
       // naming the value would be fine here and wrong one refactor later, when
       // somebody conditions a secret on another secret — which the publish rules
       // refuse precisely because nothing may read one.
-      message: `This setting is required because of what ${labelOf(schema, conditionRoot(condition))} is set to.`
+      //
+      // THE SETTING THE CONDITION READS, not the root it descends from. The two
+      // were one string while a condition could only name a root setting or a
+      // row of a root list; naming a setting in a group by its root would tell
+      // the customer to look at a whole section. A root scalar reads exactly as
+      // it always did, and a row's setting now names its list beside it.
+      message: `This setting is required because of what ${labelOfPath(schema, target)} is set to.`
     });
   }
   return issues;
@@ -13469,9 +13878,6 @@ function labelOfChild(container, name) {
   const title = items?.properties?.[name]?.title;
   return title === void 0 ? `"${name}"` : `"${title}"`;
 }
-function conditionOf(property) {
-  return property?.["x-required-when"];
-}
 function labelOf(schema, name) {
   const property = schema.properties[name];
   return property?.title === void 0 ? `"${name}"` : `"${property.title}"`;
@@ -13516,9 +13922,6 @@ function withoutPropertyRules(properties) {
   }
   return out;
 }
-function declaredSecretNames(schema) {
-  return Object.entries(schema.properties).filter(([, property]) => isSecretProperty(property)).map(([name]) => name).sort();
-}
 function defaultOf(property) {
   switch (property.type) {
     case "string":
@@ -13675,23 +14078,52 @@ function seedConfiguration(configuration) {
   const required = new Set(configuration?.required ?? []);
   const open = [];
   const requiredSecrets = [];
-  const groups = Object.entries(configuration?.dependentRequired ?? {}).map(([trigger, dependents]) => {
+  const groups = [];
+  collectGroups(configuration ?? {}, [], groups);
+  const values = seedProperties(properties, required, [], open, requiredSecrets);
+  return { values, open, requiredSecrets, groups };
+}
+function collectGroups(node, ancestors, groups) {
+  const properties = node.properties ?? {};
+  const pathOf = (name) => ancestors.length === 0 ? name : configurationPath(...ancestors, name) ?? name;
+  const labelOf2 = (name) => {
+    const path = configurationPath(...ancestors, name);
+    return path === null ? name : printableConfigurationPath(path);
+  };
+  const container = ancestors.length === 0 ? null : configurationPath(...ancestors);
+  const within = container === null ? null : printableConfigurationPath(container);
+  const clauses = Object.entries(node.dependentRequired ?? {}).map(([trigger, dependents]) => {
     const members = [trigger, ...dependents];
+    const settings = members.filter((name) => !isSecret(properties[name] ?? {}));
     return {
       trigger,
-      settings: members.filter((name) => !isSecret(properties[name] ?? {})),
-      secrets: members.filter((name) => isSecret(properties[name] ?? {}))
+      group: {
+        trigger: pathOf(trigger),
+        settings: settings.map(pathOf),
+        labels: settings.map(labelOf2),
+        secrets: members.filter((name) => isSecret(properties[name] ?? {})).map(pathOf),
+        within
+      }
     };
   }).sort((a, b) => a.trigger.localeCompare(b.trigger));
-  const values = seedProperties(properties, required, [], open, requiredSecrets);
-  return { values, open, requiredSecrets, groups };
+  groups.push(...clauses.map((clause) => clause.group));
+  for (const [name, declaration] of Object.entries(properties)) {
+    if (isSecret(declaration))
+      continue;
+    const children = containerChildren2(declaration);
+    if (children === null)
+      continue;
+    collectGroups(children, [...ancestors, name], groups);
+  }
 }
 function seedProperties(properties, required, ancestors, open, requiredSecrets) {
   const values = {};
   for (const [name, declaration] of Object.entries(properties)) {
-    if (requiredSecrets !== null && isSecret(declaration)) {
-      if (required.has(name))
-        requiredSecrets.push(name);
+    if (isSecret(declaration)) {
+      const path = ancestors.length === 0 ? name : configurationPath(...ancestors, name);
+      if (requiredSecrets !== null && required.has(name) && path !== null) {
+        requiredSecrets.push(path);
+      }
       continue;
     }
     const children = containerChildren2(declaration);
@@ -13701,7 +14133,7 @@ function seedProperties(properties, required, ancestors, open, requiredSecrets)
       const childRequired = new Set(children.required);
       const inner = [...ancestors, name];
       if (children.kind === "object") {
-        values[name] = seedProperties(children.properties, childRequired, inner, open, null);
+        values[name] = seedProperties(children.properties, childRequired, inner, open, requiredSecrets);
         continue;
       }
       const count = children.minItems ?? 0;
@@ -13732,7 +14164,8 @@ function containerChildren2(declaration) {
     return {
       kind: "object",
       properties: node.properties,
-      required: node.required ?? []
+      required: node.required ?? [],
+      ...dependentRequiredOf(node.dependentRequired)
     };
   }
   if (node.type === "array" && node.items !== void 0) {
@@ -13743,11 +14176,15 @@ function containerChildren2(declaration) {
       kind: "array",
       properties: items.properties,
       required: items.required ?? [],
+      ...dependentRequiredOf(items.dependentRequired),
       ...typeof node.minItems === "number" ? { minItems: node.minItems } : {}
     };
   }
   return null;
 }
+function dependentRequiredOf(raw) {
+  return typeof raw === "object" && raw !== null && !Array.isArray(raw) ? { dependentRequired: raw } : {};
+}
 function dedupeOpen(open) {
   const seen = /* @__PURE__ */ new Set();
   const unique = open.filter((entry) => {
@@ -13779,6 +14216,117 @@ function exampleResourceKey(name) {
   const slug = name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^[^a-z]+/, "").replace(/-+$/, "").slice(0, 63);
   return RESOURCE_KEY_PATTERN.test(slug) ? slug : "";
 }
+var DEPLOYMENT_EXAMPLE_GUARANTEE = "Product-owned configuration is complete and E2E-proven; tenant-specific secrets and Resource/provider selections are supplied by the tenant.";
+
+// ../product-configuration/dist/configuration-requirements.js
+function configurationRequirements(configuration) {
+  if (configuration === void 0 || configuration === null)
+    return [];
+  const schema = configuration;
+  const rootRequired = new Set(schema.required ?? []);
+  const carriers = new Map(conditionCarriers(schema).map((carrier) => [carrier.path, carrier]));
+  const secretPaths = new Set(configurationLeaves(schema).filter((leaf) => isSecretProperty(leaf.property)).map((leaf) => String(leaf.path)));
+  return configurationLeaves(schema).map((leaf) => {
+    const parent = immediateContainer(leaf);
+    const immediatelyRequired = parent === null ? rootRequired.has(leaf.name) : parent.required.includes(leaf.name);
+    const chainRequired = containersRequiredToRoot(schema, leaf);
+    const always = requiredToRoot(schema, leaf);
+    const secret = isSecretProperty(leaf.property);
+    const condition = conditionFor(schema, leaf.path, leaf.containers, carriers);
+    const clause = clauseEdges(schema, leaf, secretPaths);
+    const requiredness = always ? "always" : condition !== null && condition.carrier === "setting" ? "when-value" : immediatelyRequired && !chainRequired ? "when-group" : clause.requiredBy.length > 0 ? "with-siblings" : "optional";
+    const containers = leaf.containers.map((container, index) => settingContainer(container, index === 0 ? rootRequired : new Set(leaf.containers[index - 1]?.required ?? [])));
+    const list = [...containers].reverse().find((container) => container.kind === "array") ?? null;
+    return {
+      path: leaf.path,
+      printablePath: printableConfigurationPath(leaf.path),
+      title: leaf.property.title,
+      description: leaf.property.description,
+      type: leaf.property.type,
+      secret,
+      requiredness,
+      // NEVER A SECRET'S, even though the declaration rules already refuse one.
+      // Being wrong in that direction prints a credential, which is the same
+      // paranoia `product-instance-example.ts` documents for its own reader.
+      defaultValue: secret ? void 0 : declaredDefault(leaf.property),
+      allowed: secret ? [] : allowedValues(leaf.property),
+      condition,
+      requires: clause.requires,
+      requiredBy: clause.requiredBy,
+      containers,
+      perRow: underList(leaf),
+      list,
+      group: resolvedGroup(leaf)
+    };
+  });
+}
+function allowedValues(property) {
+  const leaf = property;
+  return [...leaf.enum ?? leaf.items?.enum ?? []];
+}
+function conditionFor(schema, path, containers, carriers) {
+  const own = carriers.get(path);
+  const ancestor = [...containers].reverse().map((container) => carriers.get(container.path)).find((carrier2) => carrier2 !== void 0 && carrier2.kind === "container");
+  const carrier = own?.kind === "leaf" ? own : ancestor;
+  if (carrier === void 0)
+    return null;
+  const setting = parseConfigurationPath(conditionSetting(carrier.condition));
+  if (setting === null)
+    return null;
+  return {
+    carrier: carrier.kind === "leaf" ? "setting" : "container",
+    carrierPath: carrier.path,
+    setting,
+    printableSetting: printableConfigurationPath(setting),
+    settingLabel: labelOfPath(schema, setting),
+    anyOf: [...carrier.condition.anyOf],
+    anyRow: "path" in carrier.condition && carrier.condition.anyRow === true
+  };
+}
+function clauseEdges(schema, leaf, secretPaths) {
+  const parent = immediateContainer(leaf);
+  const scope = parent === null ? schema : parent.kind === "array" ? parent.property.items ?? parent.property : parent.property;
+  const requires = /* @__PURE__ */ new Set();
+  const requiredBy = /* @__PURE__ */ new Set();
+  for (const [trigger, dependents] of Object.entries(scope.dependentRequired ?? {})) {
+    if (trigger === leaf.name)
+      for (const dependent of dependents)
+        requires.add(dependent);
+    else if (dependents.includes(leaf.name))
+      requiredBy.add(trigger);
+  }
+  const order = Object.keys(scope.properties ?? {});
+  const members = (names) => [...names].sort((a, b) => order.indexOf(a) - order.indexOf(b)).flatMap((name) => {
+    const path = memberPath(leaf, name);
+    return path === null ? [] : [
+      {
+        path,
+        printablePath: printableConfigurationPath(path),
+        secret: secretPaths.has(String(path))
+      }
+    ];
+  });
+  return { requires: members(requires), requiredBy: members(requiredBy) };
+}
+function memberPath(leaf, name) {
+  const parent = immediateContainer(leaf);
+  return parent === null ? configurationPath(name) : configurationPath(...pathSegments(parent.path), name);
+}
+function settingContainer(container, requiredByParent) {
+  return {
+    path: container.path,
+    printablePath: printableConfigurationPath(container.path),
+    title: container.property.title,
+    kind: container.kind,
+    required: requiredByParent.has(container.name)
+  };
+}
+
+// ../product-configuration/dist/manifest-yaml.js
+var import_yaml = __toESM(require_dist(), 1);
+function manifestYaml(document) {
+  return (0, import_yaml.stringify)(document, { compat: "yaml-1.1" });
+}
 
 // ../platform-schemas/dist/index.js
 var TENANT_KEY_REGEX = /^[a-z][a-z0-9-]{2,23}[a-z0-9]$/;
@@ -13921,6 +14469,53 @@ function isBlockedHost(hostname) {
   return BLOCKED_HOSTS.some((pattern) => pattern.test(hostname));
 }
 
+// ../product-contracts/dist/deployment-example.schema.js
+var DeploymentExampleSchema = external_exports.object({
+  /** The heading a customer reads above the example. */
+  title: external_exports.string().min(3).max(80),
+  /** What this deployment gives the customer, in a sentence or two. */
+  description: external_exports.string().min(20).max(400),
+  /**
+   * A PLAIN STRING, for the reason the Product Instance Template's is: an
+   * unsupported value then reaches the check that names the regions THIS
+   * Product offers, rather than a zod enum error naming the platform's.
+   */
+  region: external_exports.string().min(1).max(32),
+  /** Plain string, same reasoning as `region`. */
+  profile: external_exports.string().min(1).max(40),
+  /**
+   * The Product's own settings, in the shape `spec.configuration` takes —
+   * nested for a v2 Product. Validated at publish against this release's
+   * configuration schema by the same function a customer's manifest meets.
+   */
+  configuration: external_exports.record(external_exports.unknown()),
+  /**
+   * The secret settings a deployment of this example supplies, BY NAME.
+   *
+   * Every secret the example's configuration makes required must be named
+   * here, so a reader knows every `--secret` flag the create needs before
+   * running it. The values are the tenant's — sent when the Resource is
+   * created and again only to set a new one — and never written into a
+   * manifest. A secret resent on an unchanged re-apply is written again.
+   */
+  secretInputs: external_exports.array(external_exports.string().regex(CONFIGURATION_PROPERTY_NAME_REGEX)).max(MAX_CONFIGURATION_CHILDREN).optional()
+}).strict().describe("The recommended deployment for this release. Required for a NEW release; optional in the schema because releases published before the field existed are immutable. " + DEPLOYMENT_EXAMPLE_GUARANTEE + " Secret settings are named in secretInputs and never given a value here.");
+var SECRET_INPUT_SEGMENT = CONFIGURATION_PROPERTY_NAME_REGEX.source.slice(1, -1);
+var SecretInputV2Schema = external_exports.string().regex(new RegExp(`^(?:${SECRET_INPUT_SEGMENT}|(?:/${SECRET_INPUT_SEGMENT}){2,${MAX_CONFIGURATION_DEPTH}})$`)).refine((raw) => secretPathOf(raw) !== null, {
+  message: 'A secret input is a root setting name, or a configuration path such as "/group/setting" with no list index.'
+});
+var DeploymentExampleV2Schema = DeploymentExampleSchema.extend({
+  /**
+   * The secret settings a deployment of this example supplies, BY CANONICAL
+   * PATH — a bare name at the root, a pointer inside a group.
+   *
+   * Every secret the example's configuration makes required must be named
+   * here, so a reader knows every `--secret` flag the create needs before
+   * running it. The values are the tenant's and never written into a manifest.
+   */
+  secretInputs: external_exports.array(SecretInputV2Schema).max(MAX_CONFIGURATION_CHILDREN).optional()
+});
+
 // ../product-contracts/dist/portfolio.js
 var PORTFOLIO_CATEGORY_IDS = [
   "clients",
@@ -14507,6 +15102,15 @@ var ProductDefinitionObjectSchema = external_exports.object({
   // --- Customer choices -------------------------------------------------
   profiles: external_exports.array(ServiceProfileSchema).min(1).max(SERVICE_PROFILE_IDS.length),
   configuration: CustomerConfigurationSchema,
+  /**
+   * The publisher's recommended deployment of this release. See
+   * `deployment-example.schema.ts`.
+   *
+   * `.optional()`, NEVER `.default(...)`, for the digest reason `conditions`
+   * gives below — and required for a NEW release by `publish-rules.ts`, which
+   * is the only place a rule added after releases were frozen may live.
+   */
+  deploymentExample: DeploymentExampleSchema.optional(),
   // --- Results, relationships, operations -------------------------------
   outputs: external_exports.array(ProductOutputSchema).min(1).max(MAX_PRODUCT_OUTPUTS),
   dependencies: external_exports.array(ProductDependencySchema).max(8),
@@ -14543,7 +15147,10 @@ var ProductDefinitionSchema = ProductDefinitionObjectSchema.superRefine(checkPro
 var ProductDefinitionV2ObjectSchema = ProductDefinitionObjectSchema.extend({
   apiVersion: ProductApiVersionV2Schema,
   configuration: CustomerConfigurationV2Schema,
-  dependencies: external_exports.array(ProductDependencyV2Schema).max(8)
+  dependencies: external_exports.array(ProductDependencyV2Schema).max(8),
+  // A v2 secret may sit inside a group, so the example names it by PATH. The v1
+  // example keeps its root-name rule, and the v1 artifact its bytes.
+  deploymentExample: DeploymentExampleV2Schema.optional()
 });
 var ProductDefinitionV2Schema = ProductDefinitionV2ObjectSchema.superRefine(checkProductDefinition);
 function checkProductDefinition(definition, ctx) {
@@ -14720,12 +15327,13 @@ function checkProductDefinition(definition, ctx) {
       });
     }
   });
-  for (const [name, property] of Object.entries(definition.configuration.properties ?? {})) {
-    const condition = property["x-required-when"];
-    if (condition === void 0)
-      continue;
-    const at = ["configuration", "properties", name, "x-required-when"];
-    if ((definition.configuration.required ?? []).includes(name)) {
+  for (const carrier of conditionCarriers(definition.configuration)) {
+    const { condition } = carrier;
+    const name = printableConfigurationPath(carrier.path);
+    const named = conditionSetting(condition);
+    const anyRow = "anyRow" in condition && condition.anyRow === true;
+    const at = [...declarationIssuePath(carrier), "x-required-when"];
+    if (requiredToRoot(definition.configuration, carrier)) {
       ctx.addIssue({
         code: external_exports.ZodIssueCode.custom,
         path: [...at],
@@ -14733,7 +15341,7 @@ function checkProductDefinition(definition, ctx) {
       });
       continue;
     }
-    if (declaredDefault(property) !== void 0) {
+    if (declaredDefault(carrier.property) !== void 0) {
       ctx.addIssue({
         code: external_exports.ZodIssueCode.custom,
         path: [...at],
@@ -14748,7 +15356,7 @@ function checkProductDefinition(definition, ctx) {
         message: "Repeated values in `anyOf`."
       });
     }
-    if (condition.path === name) {
+    if (named === carrier.path) {
       ctx.addIssue({
         code: external_exports.ZodIssueCode.custom,
         path: [...at, "path"],
@@ -14756,30 +15364,30 @@ function checkProductDefinition(definition, ctx) {
       });
       continue;
     }
-    const parsed = parseConfigurationPath(condition.path);
+    const parsed = parseConfigurationPath(named);
     const leaf = parsed === null ? null : leafAt(definition.configuration, parsed);
     if (leaf === null) {
       const isGroup = parsed !== null && declaresPath(definition.configuration, parsed);
       ctx.addIssue({
         code: external_exports.ZodIssueCode.custom,
         path: [...at, "path"],
-        message: isGroup ? `"${condition.path}" is a group of settings, which holds no single value to compare. Name one setting inside it.` : `"${condition.path}" is not a declared customer configuration property.`
+        message: isGroup ? `"${named}" is a group of settings, which holds no single value to compare. Name one setting inside it.` : `"${named}" is not a declared customer configuration property.`
       });
       continue;
     }
-    if (underList(leaf) && condition.anyRow !== true) {
+    if (underList(leaf) && !anyRow) {
       ctx.addIssue({
         code: external_exports.ZodIssueCode.custom,
         path: [...at, "path"],
-        message: `"${condition.path}" is inside a list, so it names one value per item rather than one value. Add "anyRow": true to require the secret when ANY row chose one of these values, or name a setting the instance holds exactly once.`
+        message: `"${named}" is inside a list, so it names one value per item rather than one value. Add "anyRow": true to require the secret when ANY row chose one of these values, or name a setting the instance holds exactly once.`
       });
       continue;
     }
-    if (!underList(leaf) && condition.anyRow === true) {
+    if (!underList(leaf) && anyRow) {
       ctx.addIssue({
         code: external_exports.ZodIssueCode.custom,
         path: [...at, "anyRow"],
-        message: `"${condition.path}" is not inside a list, so there are no rows to quantify over.`
+        message: `"${named}" is not inside a list, so there are no rows to quantify over.`
       });
     }
     const target = leaf.property;
@@ -14787,7 +15395,7 @@ function checkProductDefinition(definition, ctx) {
       ctx.addIssue({
         code: external_exports.ZodIssueCode.custom,
         path: [...at, "path"],
-        message: `"${condition.path}" is a ${target.type} setting; a condition compares string values.`
+        message: `"${named}" is a ${target.type} setting; a condition compares string values.`
       });
       continue;
     }
@@ -14795,21 +15403,16 @@ function checkProductDefinition(definition, ctx) {
       ctx.addIssue({
         code: external_exports.ZodIssueCode.custom,
         path: [...at, "path"],
-        message: `"${condition.path}" is a secret. The platform never reads a secret's value, so a condition on one could never be evaluated.`
+        message: `"${named}" is a secret. The platform never reads a secret's value, so a condition on one could never be evaluated.`
       });
       continue;
     }
-    const single = withoutCrossFieldRules({
-      ...definition.configuration,
-      properties: { [leaf.name]: target },
-      required: [leaf.name]
-    });
-    const outside = condition.anyOf.filter((value) => !validateSubmittedConfiguration(single, { [leaf.name]: value }).ok);
+    const outside = valuesOutsideSpace(definition.configuration, leaf, condition.anyOf);
     if (outside.length > 0) {
       ctx.addIssue({
         code: external_exports.ZodIssueCode.custom,
         path: [...at, "anyOf"],
-        message: `"${condition.path}" never accepts ${outside.map((v) => `"${v}"`).join(", ")}, so this condition could never make the secret required.`
+        message: `"${named}" never accepts ${outside.map((v) => `"${v}"`).join(", ")}, so this condition could never make the secret required.`
       });
     }
   }
@@ -15142,6 +15745,225 @@ var ANNOUNCED_PRODUCTS = Object.freeze([
   }
 ]);
 
+// ../product-contracts/dist/contract-issue.js
+var PATH_SEGMENT = /^[A-Za-z_][A-Za-z0-9_-]{0,63}$/;
+var UNPRINTABLE_SEGMENT = "<unprintable>";
+var MAX_SEGMENTS = MAX_CONFIGURATION_PATH_SEGMENTS + 2;
+function printableContractPath(path) {
+  const printable = path.slice(0, MAX_SEGMENTS).map((segment) => typeof segment === "number" || PATH_SEGMENT.test(segment) ? String(segment) : UNPRINTABLE_SEGMENT);
+  return printable.join(".") || "(document)";
+}
+function manifestConfigurationField(field) {
+  if (field === "")
+    return "spec.configuration";
+  const parsed = parseConfigurationPath(field);
+  return printableContractPath([
+    "spec",
+    "configuration",
+    ...parsed === null ? [field] : pathSegments(parsed)
+  ]);
+}
+
+// ../product-contracts/dist/resource-output-reference.js
+var OUTPUT_KEY_RULE = "Output keys are camelCase.";
+var ResourceOutputReferenceSchema = external_exports.object({
+  valueFrom: external_exports.object({
+    resourceOutput: external_exports.object({
+      /** The producing Resource's `metadata.key`, in the same Project. */
+      resourceKey: ResourceKeySchema,
+      /** The key of an output that Resource's Product declares. */
+      output: external_exports.string().regex(/^[a-z][a-zA-Z0-9]{1,47}$/, OUTPUT_KEY_RULE)
+    }).strict()
+  }).strict()
+}).strict();
+function looksLikeReference(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value) && "valueFrom" in value;
+}
+
+// ../product-contracts/dist/dependency-binding.js
+var DependencyBindingSelectorSchema = external_exports.object({
+  /** The providing Resource's `metadata.key`. */
+  resourceKey: ResourceKeySchema,
+  /**
+   * The Project that Resource lives in. Absent means the consumer's own.
+   *
+   * PRESENT BECAUSE A BINDING IS TENANT-SCOPED AND A PROJECT IS NOT A RUNTIME
+   * BOUNDARY: a provider anywhere in the Tenant can satisfy a consumer
+   * anywhere in it, and that has been true since bindings existed. What the
+   * field does NOT do is grant anything — the Control Plane opens that
+   * Project from the caller's own assertion, and a Project the caller holds
+   * nothing in answers exactly as a Project that does not exist.
+   *
+   * A plain bounded string, exactly as `spec.projectId` is: an id that does
+   * not name a readable Project is refused where the refusal can be phrased
+   * without leaking, which is not here.
+   */
+  projectId: external_exports.string().min(1).max(64).optional()
+}).strict();
+var DependencyBindingsSchema = external_exports.record(ServiceBindingKeySchema, DependencyBindingSelectorSchema);
+
+// ../product-contracts/dist/product-instance-template.schema.js
+var ProductInstanceTemplateSchema = external_exports.object({
+  apiVersion: ResourceApiVersionSchema,
+  kind: kindSchema(PRODUCT_INSTANCE_KIND),
+  metadata: external_exports.object({
+    /**
+     * The customer-facing Resource name — "Local service".
+     *
+     * Maps to `ProductInstance.displayName`, and deliberately introduces NO
+     * new identity concept. `pri_…` remains the stable identity and
+     * `instanceKey` remains the cloud resource key; adding a third name here
+     * would mean a fourth thing to keep unique and a fifth to explain.
+     * Bounded exactly as the create envelope bounds `displayName`.
+     */
+    // NOT `.trim()`: this schema is PUBLISHED as JSON Schema so a customer
+    // can validate the file before sending it, and a trim is a transform
+    // that JSON Schema cannot express. The value is trimmed when it becomes
+    // a create command instead, so the published document and the platform
+    // agree on what is valid.
+    name: external_exports.string().min(1).max(80).regex(/\S/, "The resource name must contain a non-whitespace character. A name of only spaces trims to nothing, and an empty display name is not a name."),
+    /**
+     * THE STABLE IDENTITY OF THIS RESOURCE INSIDE ITS PROJECT — and the one
+     * thing that makes applying a document twice different from creating
+     * two resources.
+     *
+     * THIS IS THE FOURTH NAME, AND THE HEADER ABOVE ARGUES AGAINST ONE.
+     * That argument stands and is answered rather than ignored: a
+     * declarative apply is not expressible without a key the AUTHOR knows
+     * before the platform has created anything, and nothing that already
+     * exists is one.
+     *
+     *   `metadata.name`   mutable, not unique, and rule 1 above says it is
+     *                     display copy rather than identity.
+     *   `pri_…`           minted by the server. It does not exist when the
+     *                     first apply is written, which is the only moment
+     *                     that matters.
+     *   `instanceKey`     derived from `pri_…` and then frozen — the same
+     *                     problem one step removed.
+     *   idempotency key   a de-duplication token that "names nothing,
+     *                     grants nothing, and selects nothing". Making it
+     *                     select a resource would falsify the security
+     *                     argument the signed-request layer rests on.
+     *
+     * So it gets exactly ONE job: to say which resource in this Project the
+     * document is about. It is NEVER authorization — the Project comes from
+     * the request, the row is loaded inside it, and a key naming nothing
+     * there is a not-found rather than a create. And it NEVER becomes a
+     * provider resource name; `instanceKey` owns that, and coupling the two
+     * would let a customer's chosen string reach Scaleway.
+     *
+     * OPTIONAL HERE, REQUIRED AT APPLY. The document is a published `v1`
+     * contract and validating one on its own is a legitimate thing to do
+     * with no Project in sight — the same asymmetry `resolveTemplate`
+     * already has for `routeProjectId`. What refuses a document without a
+     * key is the apply path, because a create that cannot be run again is
+     * not deployment as code.
+     *
+     * Shaped like a DNS label: it becomes a database predicate and a log
+     * field, and neither wants free text.
+     */
+    key: ResourceKeySchema.optional()
+  }).strict(),
+  spec: external_exports.object({
+    productId: external_exports.string().min(1).max(64),
+    /**
+     * REQUIRED, unlike the create envelope's, which may be omitted to take
+     * the newest deployable release.
+     *
+     * A template is a record of a decision, and "newest" is not one. An
+     * optional version would mean the same document produced 1.0.0 today and
+     * 1.1.0 after an unrelated promotion — so re-applying an exported
+     * template would not reproduce what was exported, which is the single
+     * property that makes templates worth having.
+     */
+    productVersion: external_exports.string().min(1).max(64),
+    /** Round-trip only — see rule 3 above. Never authorization. */
+    projectId: external_exports.string().min(1).max(64).optional(),
+    region: external_exports.string().min(1).max(32),
+    profile: external_exports.string().min(1).max(40),
+    /**
+     * The Product's own settings.
+     *
+     * An OBJECT with product-specific keys, not `unknown`: the published
+     * JSON Schema has to say at least that much, and the converter refuses
+     * `unknown` precisely so a published contract cannot silently widen.
+     * The keys themselves are validated against the pinned Definition's
+     * configuration schema by `resolveTemplate`, which is where the real
+     * shape lives — it differs per Product, so it cannot be stated here.
+     */
+    configuration: external_exports.record(external_exports.unknown()).optional(),
+    /**
+     * Which Resource satisfies each declared service dependency.
+     *
+     * A RESOURCE RELATION, NOT A SETTING, which is why it is a sibling of
+     * `configuration` rather than a key inside it. `configuration` is the
+     * Product's own settings and is validated against the Definition's
+     * schema; this names another Resource, and the create envelope made the
+     * identical split for the identical reason.
+     *
+     * OPTIONAL, PERMANENTLY. Every manifest written before this field
+     * existed omits it, and absence has to keep meaning "leave the
+     * connections alone" — otherwise re-applying an unchanged file would
+     * release a binding somebody made in the portal.
+     *
+     * The keys the platform will ACCEPT here are narrower than the shape:
+     * only a dependency whose interface the registry calls
+     * `tenant-multiple` is one a customer chooses. `resolveTemplate` says
+     * so against the pinned Definition, so the refusal names the field.
+     */
+    dependencyBindings: DependencyBindingsSchema.optional()
+  }).strict()
+}).strict();
+function secretValuesInDocument(schema, configuration) {
+  if (!isPlainRecord(configuration) || !isPlainRecord(schema.properties))
+    return [];
+  const declarations = plainDeclarations(schema.properties);
+  return declaredSecretPaths({
+    properties: declarations
+  }).filter((path) => {
+    const segments = pathSegments(path).map(String);
+    let parent = configuration;
+    for (const segment of segments.slice(0, -1)) {
+      parent = isPlainRecord(parent) ? parent[segment] : void 0;
+    }
+    const name = segments[segments.length - 1];
+    return isPlainRecord(parent) && Object.hasOwn(parent, name) && !looksLikeReference(parent[name]);
+  });
+}
+function plainDeclarations(properties) {
+  const out = {};
+  for (const [name, property] of Object.entries(properties)) {
+    if (!isPlainRecord(property) || typeof property["type"] !== "string")
+      continue;
+    const copy = { ...property };
+    if (Object.hasOwn(copy, "properties")) {
+      if (isPlainRecord(copy["properties"]))
+        copy["properties"] = plainDeclarations(copy["properties"]);
+      else
+        delete copy["properties"];
+    }
+    if (Object.hasOwn(copy, "items")) {
+      const items = copy["items"];
+      if (!isPlainRecord(items) || typeof items["type"] !== "string")
+        delete copy["items"];
+      else if (Object.hasOwn(items, "properties")) {
+        copy["items"] = isPlainRecord(items["properties"]) ? { ...items, properties: plainDeclarations(items["properties"]) } : (({ properties: _dropped, ...rest }) => rest)(items);
+      }
+    }
+    out[name] = copy;
+  }
+  return out;
+}
+function secretValueIssue(name) {
+  return {
+    field: manifestConfigurationField(name),
+    message: `"${name}" is secret input and must never appear in a template. Supply it separately when applying, so it goes to the secret manager rather than into a document.`
+  };
+}
+function isPlainRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
 // ../product-contracts/dist/publish-rules.js
 var PRODUCT_DISPLAY_NAME_PATTERN = "^[^\\u2014\\s](?:[^\\u2014]*[^\\u2014\\s])? \\u2014 [^\\u2014\\s](?:[^\\u2014]*[^\\u2014\\s])?$";
 var PRODUCT_DISPLAY_NAME_REGEX = new RegExp(PRODUCT_DISPLAY_NAME_PATTERN, "u");
@@ -15464,8 +16286,12 @@ var EnvBindingV2Schema = external_exports.discriminatedUnion("source", [
      *
      * WHAT IT CARRIES: validated, non-secret configuration with resolved
      * ORDINARY resource references materialised in place. Never a secret
-     * value — secrets are root-only and travel through `secrets[]`, and a
-     * subtree cannot contain one. Serialised with `canonicalJson`, so the same
+     * value — a secret travels through `secrets[]`, and its value is split out
+     * of the configuration before anything is stored. A secret may sit inside
+     * a group, so `validateProductContracts` refuses a `path` naming a secret
+     * or a group that contains one anywhere below it: a component bound to
+     * that group would read it as complete while its credential is absent.
+     * Serialised with `canonicalJson`, so the same
      * logical configuration is the same bytes and the environment fingerprint
      * does not move on key order alone.
      *
@@ -15815,6 +16641,20 @@ var SecretWiringSchema = external_exports.object({
     envVar: EnvVarNameSchema
   }).strict()).min(1).max(12)
 }).strict();
+var SecretWiringV2Schema = SecretWiringSchema.extend({
+  /**
+   * LEGACY SPELLING of a ROOT secret's path, kept so released v2 Blueprints
+   * still read. Described here rather than in the declaration table, whose note
+   * is what the v1 artifact publishes for the same field.
+   */
+  configurationProperty: external_exports.string().regex(/^[a-z][a-zA-Z0-9]{1,47}$/).describe("Accepted only so releases published before `configurationPath` existed still read. It names a root secret and means the same as `configurationPath` with that name; a new release must use `configurationPath`, and a Blueprint may not name both.").optional(),
+  /**
+   * Set only for `customer-configuration`: the canonical path of the `x-secret`
+   * setting in the Product Definition whose write-only submission populates
+   * this secret — a bare name at the root, a pointer inside a group.
+   */
+  configurationPath: ConfigurationBindingPathSchema.optional()
+}).strict();
 var DataCategorySchema = external_exports.enum([
   "prompt-content",
   "model-response",
@@ -16244,7 +17084,8 @@ var DeploymentBlueprintV1ObjectSchema = DeploymentBlueprintObjectSchema.extend({
 });
 var DeploymentBlueprintV2ObjectSchema = DeploymentBlueprintObjectSchema.extend({
   apiVersion: ProductApiVersionV2Schema,
-  components: external_exports.array(RuntimeComponentV2Schema).min(1).max(MAX_RUNTIME_COMPONENTS)
+  components: external_exports.array(RuntimeComponentV2Schema).min(1).max(MAX_RUNTIME_COMPONENTS),
+  secrets: external_exports.array(SecretWiringV2Schema).max(20)
 });
 var DeploymentBlueprintV1Schema = DeploymentBlueprintV1ObjectSchema.superRefine(checkDeploymentBlueprint);
 var DeploymentBlueprintV2Schema = DeploymentBlueprintV2ObjectSchema.superRefine(checkDeploymentBlueprint);
@@ -16628,18 +17469,28 @@ function checkDeploymentBlueprint(blueprint, ctx) {
         });
       }
     }
-    if (secret.source === "customer-configuration" && secret.configurationProperty === void 0) {
+    const pathField = "configurationPath" in secret ? secret.configurationPath : void 0;
+    const namesSetting = secret.configurationProperty !== void 0 || pathField !== void 0;
+    const settingField = blueprint.apiVersion === PRODUCT_API_VERSION ? "configurationProperty" : "configurationPath";
+    if (secret.configurationProperty !== void 0 && pathField !== void 0) {
+      ctx.addIssue({
+        code: external_exports.ZodIssueCode.custom,
+        path,
+        message: `Secret "${secret.key}" names both configurationProperty and configurationPath. Name the setting once, with configurationPath.`
+      });
+    }
+    if (secret.source === "customer-configuration" && !namesSetting) {
       ctx.addIssue({
         code: external_exports.ZodIssueCode.custom,
         path,
-        message: `Secret "${secret.key}" is sourced from customer configuration but names no configurationProperty.`
+        message: `Secret "${secret.key}" is sourced from customer configuration but names no ${settingField}.`
       });
     }
-    if (secret.source !== "customer-configuration" && secret.configurationProperty !== void 0) {
+    if (secret.source !== "customer-configuration" && namesSetting) {
       ctx.addIssue({
         code: external_exports.ZodIssueCode.custom,
         path,
-        message: `Secret "${secret.key}" names a configurationProperty but is not customer-sourced.`
+        message: `Secret "${secret.key}" names a ${pathField !== void 0 ? "configurationPath" : "configurationProperty"} but is not customer-sourced.`
       });
     }
     if (secret.source === "service-binding" && secret.serviceBinding === void 0) {
@@ -17017,193 +17868,6 @@ function isTerminalAction(action) {
 }
 var ManifestActionSchema = external_exports.enum(MANIFEST_ACTIONS);
 
-// ../product-contracts/dist/contract-issue.js
-var PATH_SEGMENT = /^[A-Za-z_][A-Za-z0-9_-]{0,63}$/;
-var UNPRINTABLE_SEGMENT = "<unprintable>";
-var MAX_SEGMENTS = MAX_CONFIGURATION_PATH_SEGMENTS + 2;
-function printableContractPath(path) {
-  const printable = path.slice(0, MAX_SEGMENTS).map((segment) => typeof segment === "number" || PATH_SEGMENT.test(segment) ? String(segment) : UNPRINTABLE_SEGMENT);
-  return printable.join(".") || "(document)";
-}
-function manifestConfigurationField(field) {
-  if (field === "")
-    return "spec.configuration";
-  const parsed = parseConfigurationPath(field);
-  return printableContractPath([
-    "spec",
-    "configuration",
-    ...parsed === null ? [field] : pathSegments(parsed)
-  ]);
-}
-
-// ../product-contracts/dist/resource-output-reference.js
-var OUTPUT_KEY_RULE = "Output keys are camelCase.";
-var ResourceOutputReferenceSchema = external_exports.object({
-  valueFrom: external_exports.object({
-    resourceOutput: external_exports.object({
-      /** The producing Resource's `metadata.key`, in the same Project. */
-      resourceKey: ResourceKeySchema,
-      /** The key of an output that Resource's Product declares. */
-      output: external_exports.string().regex(/^[a-z][a-zA-Z0-9]{1,47}$/, OUTPUT_KEY_RULE)
-    }).strict()
-  }).strict()
-}).strict();
-function looksLikeReference(value) {
-  return typeof value === "object" && value !== null && !Array.isArray(value) && "valueFrom" in value;
-}
-
-// ../product-contracts/dist/dependency-binding.js
-var DependencyBindingSelectorSchema = external_exports.object({
-  /** The providing Resource's `metadata.key`. */
-  resourceKey: ResourceKeySchema,
-  /**
-   * The Project that Resource lives in. Absent means the consumer's own.
-   *
-   * PRESENT BECAUSE A BINDING IS TENANT-SCOPED AND A PROJECT IS NOT A RUNTIME
-   * BOUNDARY: a provider anywhere in the Tenant can satisfy a consumer
-   * anywhere in it, and that has been true since bindings existed. What the
-   * field does NOT do is grant anything — the Control Plane opens that
-   * Project from the caller's own assertion, and a Project the caller holds
-   * nothing in answers exactly as a Project that does not exist.
-   *
-   * A plain bounded string, exactly as `spec.projectId` is: an id that does
-   * not name a readable Project is refused where the refusal can be phrased
-   * without leaking, which is not here.
-   */
-  projectId: external_exports.string().min(1).max(64).optional()
-}).strict();
-var DependencyBindingsSchema = external_exports.record(ServiceBindingKeySchema, DependencyBindingSelectorSchema);
-
-// ../product-contracts/dist/product-instance-template.schema.js
-var ProductInstanceTemplateSchema = external_exports.object({
-  apiVersion: ResourceApiVersionSchema,
-  kind: kindSchema(PRODUCT_INSTANCE_KIND),
-  metadata: external_exports.object({
-    /**
-     * The customer-facing Resource name — "Local service".
-     *
-     * Maps to `ProductInstance.displayName`, and deliberately introduces NO
-     * new identity concept. `pri_…` remains the stable identity and
-     * `instanceKey` remains the cloud resource key; adding a third name here
-     * would mean a fourth thing to keep unique and a fifth to explain.
-     * Bounded exactly as the create envelope bounds `displayName`.
-     */
-    // NOT `.trim()`: this schema is PUBLISHED as JSON Schema so a customer
-    // can validate the file before sending it, and a trim is a transform
-    // that JSON Schema cannot express. The value is trimmed when it becomes
-    // a create command instead, so the published document and the platform
-    // agree on what is valid.
-    name: external_exports.string().min(1).max(80).regex(/\S/, "The resource name must contain a non-whitespace character. A name of only spaces trims to nothing, and an empty display name is not a name."),
-    /**
-     * THE STABLE IDENTITY OF THIS RESOURCE INSIDE ITS PROJECT — and the one
-     * thing that makes applying a document twice different from creating
-     * two resources.
-     *
-     * THIS IS THE FOURTH NAME, AND THE HEADER ABOVE ARGUES AGAINST ONE.
-     * That argument stands and is answered rather than ignored: a
-     * declarative apply is not expressible without a key the AUTHOR knows
-     * before the platform has created anything, and nothing that already
-     * exists is one.
-     *
-     *   `metadata.name`   mutable, not unique, and rule 1 above says it is
-     *                     display copy rather than identity.
-     *   `pri_…`           minted by the server. It does not exist when the
-     *                     first apply is written, which is the only moment
-     *                     that matters.
-     *   `instanceKey`     derived from `pri_…` and then frozen — the same
-     *                     problem one step removed.
-     *   idempotency key   a de-duplication token that "names nothing,
-     *                     grants nothing, and selects nothing". Making it
-     *                     select a resource would falsify the security
-     *                     argument the signed-request layer rests on.
-     *
-     * So it gets exactly ONE job: to say which resource in this Project the
-     * document is about. It is NEVER authorization — the Project comes from
-     * the request, the row is loaded inside it, and a key naming nothing
-     * there is a not-found rather than a create. And it NEVER becomes a
-     * provider resource name; `instanceKey` owns that, and coupling the two
-     * would let a customer's chosen string reach Scaleway.
-     *
-     * OPTIONAL HERE, REQUIRED AT APPLY. The document is a published `v1`
-     * contract and validating one on its own is a legitimate thing to do
-     * with no Project in sight — the same asymmetry `resolveTemplate`
-     * already has for `routeProjectId`. What refuses a document without a
-     * key is the apply path, because a create that cannot be run again is
-     * not deployment as code.
-     *
-     * Shaped like a DNS label: it becomes a database predicate and a log
-     * field, and neither wants free text.
-     */
-    key: ResourceKeySchema.optional()
-  }).strict(),
-  spec: external_exports.object({
-    productId: external_exports.string().min(1).max(64),
-    /**
-     * REQUIRED, unlike the create envelope's, which may be omitted to take
-     * the newest deployable release.
-     *
-     * A template is a record of a decision, and "newest" is not one. An
-     * optional version would mean the same document produced 1.0.0 today and
-     * 1.1.0 after an unrelated promotion — so re-applying an exported
-     * template would not reproduce what was exported, which is the single
-     * property that makes templates worth having.
-     */
-    productVersion: external_exports.string().min(1).max(64),
-    /** Round-trip only — see rule 3 above. Never authorization. */
-    projectId: external_exports.string().min(1).max(64).optional(),
-    region: external_exports.string().min(1).max(32),
-    profile: external_exports.string().min(1).max(40),
-    /**
-     * The Product's own settings.
-     *
-     * An OBJECT with product-specific keys, not `unknown`: the published
-     * JSON Schema has to say at least that much, and the converter refuses
-     * `unknown` precisely so a published contract cannot silently widen.
-     * The keys themselves are validated against the pinned Definition's
-     * configuration schema by `resolveTemplate`, which is where the real
-     * shape lives — it differs per Product, so it cannot be stated here.
-     */
-    configuration: external_exports.record(external_exports.unknown()).optional(),
-    /**
-     * Which Resource satisfies each declared service dependency.
-     *
-     * A RESOURCE RELATION, NOT A SETTING, which is why it is a sibling of
-     * `configuration` rather than a key inside it. `configuration` is the
-     * Product's own settings and is validated against the Definition's
-     * schema; this names another Resource, and the create envelope made the
-     * identical split for the identical reason.
-     *
-     * OPTIONAL, PERMANENTLY. Every manifest written before this field
-     * existed omits it, and absence has to keep meaning "leave the
-     * connections alone" — otherwise re-applying an unchanged file would
-     * release a binding somebody made in the portal.
-     *
-     * The keys the platform will ACCEPT here are narrower than the shape:
-     * only a dependency whose interface the registry calls
-     * `tenant-multiple` is one a customer chooses. `resolveTemplate` says
-     * so against the pinned Definition, so the refusal names the field.
-     */
-    dependencyBindings: DependencyBindingsSchema.optional()
-  }).strict()
-}).strict();
-function secretValuesInDocument(schema, configuration) {
-  if (!isPlainRecord(configuration) || !isPlainRecord(schema.properties))
-    return [];
-  const declarations = Object.fromEntries(Object.entries(schema.properties).filter(([, property]) => isPlainRecord(property)));
-  return declaredSecretNames({
-    properties: declarations
-  }).filter((name) => Object.hasOwn(configuration, name) && !looksLikeReference(configuration[name]));
-}
-function secretValueIssue(name) {
-  return {
-    field: manifestConfigurationField(name),
-    message: `"${name}" is secret input and must never appear in a template. Supply it separately when applying, so it goes to the secret manager rather than into a document.`
-  };
-}
-function isPlainRecord(value) {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
 // ../product-contracts/dist/product-submission.schema.js
 var PRODUCT_SUBMISSION_KIND = "ProductSubmission";
 var SubmissionPublisherSchema = external_exports.object({
@@ -17297,13 +17961,32 @@ var PUBLISH_RULE_ANNEX = {
           }
         }
       }
+    },
+    {
+      // THE SAME ASYMMETRY, a third time. Presence and shape are all JSON Schema
+      // can say: whether the region and profile are this Product's, whether the
+      // configuration fills every required setting and whether every required
+      // secret is named are questions about the rest of the document, answered
+      // by preflight.
+      $comment: "A new release must declare definition.deploymentExample: one recommended deployment, with region, profile and configuration. Preflight also checks the region and profile are this Product's, the configuration is complete against its schema, no secret carries a value, and every required secret is named in secretInputs.",
+      properties: {
+        definition: {
+          required: ["deploymentExample"],
+          properties: {
+            deploymentExample: {
+              required: ["title", "description", "region", "profile", "configuration"]
+            }
+          }
+        }
+      }
     }
   ]
 };
 withJsonSchemaAnnex(ProductSubmissionSchema, PUBLISH_RULE_ANNEX);
+withJsonSchemaAnnex(ProductSubmissionV2Schema, PUBLISH_RULE_ANNEX);
 
 // src/manifest.ts
-var import_yaml = __toESM(require_dist(), 1);
+var import_yaml2 = __toESM(require_dist(), 1);
 function readManifest(path) {
   let text;
   try {
@@ -17313,7 +17996,7 @@ function readManifest(path) {
   }
   let parsed;
   try {
-    parsed = (0, import_yaml.parse)(text, { prettyErrors: false });
+    parsed = (0, import_yaml2.parse)(text, { prettyErrors: false });
   } catch (error) {
     return {
       ok: false,
@@ -17333,15 +18016,21 @@ function resolveSecrets(pairs, environment = process.env) {
     if (separator <= 0) {
       return {
         ok: false,
-        message: `${label} expects name=env:VARIABLE, and there is no name before "=".`
+        message: `${label} expects NAME=env:VARIABLE, and there is no name before "=".`
       };
     }
-    const name = pair.slice(0, separator);
+    const name = secretPathOf(pair.slice(0, separator));
     const source = pair.slice(separator + 1);
+    if (name === null) {
+      return {
+        ok: false,
+        message: `${label} expects a setting name before "=", or a /group/setting path for a setting inside a group. A path names no list item and does not end in "/".`
+      };
+    }
     if (!source.startsWith("env:")) {
       return {
         ok: false,
-        message: `${label} must read from the environment: --secret <name>=env:VARIABLE. A value on the command line is in your shell history and in the process table.`
+        message: `${label} must read from the environment: --secret <name-or-path>=env:VARIABLE. A value on the command line is in your shell history and in the process table.`
       };
     }
     const variable = source.slice("env:".length);
@@ -17349,10 +18038,10 @@ function resolveSecrets(pairs, environment = process.env) {
       return { ok: false, message: `${label} names no variable after "env:".` };
     }
     const value = environment[variable];
-    if (value === void 0 || value === "") {
+    if (value === void 0 || value.trim() === "") {
       return {
         ok: false,
-        message: `${label} reads an environment variable that is not set, or is empty.`
+        message: `${label} reads an environment variable that is not set, or holds nothing but whitespace.`
       };
     }
     secrets[name] = value;
@@ -17470,8 +18159,14 @@ async function ensureSession(args) {
     }
   };
 }
+function resolveProjectWithSource(flag, stored) {
+  if (flag !== void 0) return { value: flag, source: "--project" };
+  const selected = stored.context?.projectId;
+  if (selected !== void 0) return { value: selected, source: "the stored context" };
+  return null;
+}
 function resolveProject(flag, stored) {
-  return flag ?? stored.context?.projectId ?? null;
+  return resolveProjectWithSource(flag, stored)?.value ?? null;
 }
 
 // src/operations.ts
@@ -17650,6 +18345,9 @@ function secretWriteConsequence(plan) {
   }
   return lines;
 }
+function requiredSecretLines(names) {
+  return names.length === 0 ? [] : ["  required secrets:", ...names.map((name) => `    ${name}`)];
+}
 function printPlan(plan, json) {
   if (json) {
     process.stdout.write(`${JSON.stringify(plan)}
@@ -17682,11 +18380,7 @@ function printPlan(plan, json) {
       }
     }
   }
-  const required = plan.requiredSecrets ?? [];
-  if (required.length > 0) {
-    lines.push("  required secrets:");
-    for (const name of required) lines.push(`    ${name}`);
-  }
+  lines.push(...requiredSecretLines(plan.requiredSecrets ?? []));
   if ((plan.secretsToWrite ?? []).length > 0) {
     lines.push(`  secrets to set: ${plan.secretsToWrite.join(", ")}`);
     for (const line of secretWriteConsequence(plan)) lines.push(`      ${line}`);
@@ -17770,10 +18464,15 @@ async function runApply(verb, parsed, deps = {}) {
       body: { verb: "validate", payload: manifest2.document }
     });
     if (!result.ok) return printError(result.error, json);
+    if (json) {
+      process.stdout.write(`${JSON.stringify(result.data)}
+`);
+      return 0;
+    }
+    const required = result.data["requiredSecrets"];
+    const names = Array.isArray(required) ? required.filter((name) => typeof name === "string") : [];
     process.stdout.write(
-      json ? `${JSON.stringify(result.data)}
-` : `${file} is a valid manifest.
-`
+      [`${file} is a valid manifest.`, ...requiredSecretLines(names)].join("\n") + "\n"
     );
     return 0;
   }
@@ -18117,13 +18816,18 @@ async function runDoctor(parsed) {
     detail: `${endpoint}   (from ${resolved.source})`,
     facts: { endpoint, source: resolved.source }
   });
-  const selected = stored.context?.projectId ?? null;
+  const project = resolveProjectWithSource(parsed.flags["project"], stored);
+  const storedProjectId = stored.context?.projectId ?? null;
   checks.push({
     name: "Project",
     ok: true,
-    note: selected === null,
-    detail: selected === null ? "none selected. Commands need `--project prj_\u2026`, or run `vfac context set --project prj_\u2026` once. This is not a fault \u2014 it is what a pipeline that names the Project per command looks like \u2014 but it is NOT the same thing as which Projects your credential reaches." : `${selected}   (selected in this context; which Projects the credential reaches is a separate question)`,
-    facts: { selectedProjectId: selected }
+    note: storedProjectId === null,
+    detail: project === null ? "none selected. Commands need `--project prj_\u2026`, or run `vfac context set --project prj_\u2026` once. This is not a fault \u2014 it is what a pipeline that names the Project per command looks like \u2014 but it is NOT the same thing as which Projects your credential reaches." : project.source === "--project" ? `${project.value}   (from --project, for this command only). ` + (storedProjectId === null ? "Nothing is selected in this context, so every other command needs the flag too. " : `The stored context still selects ${storedProjectId}, which is what a command with no --project uses. `) + "Which Projects the credential reaches is a separate question." : `${project.value}   (from the stored context; a command with no --project uses it, and which Projects the credential reaches is a separate question)`,
+    facts: {
+      selectedProjectId: project?.value ?? null,
+      source: project?.source ?? null,
+      storedProjectId
+    }
   });
   const probe = await probeMachineApi({ endpoint });
   if (!probe.ok) {
@@ -18158,13 +18862,13 @@ async function runDoctor(parsed) {
     return report2(checks, json);
   }
   const access = who.data.access;
-  const projects = access.projects.map((project) => project.projectId);
+  const projects = access.projects.map((project2) => project2.projectId);
   const mutating = access.projects.filter(
-    (project) => project.permissions.some((permission) => !permission.endsWith(".read"))
+    (project2) => project2.permissions.some((permission) => !permission.endsWith(".read"))
   );
   const organizationWide = access.tenantPermissions.includes("project.read");
   const alsoOrganizationWide = access.tenantPermissions.length > 0 ? `Organization-wide it holds ${access.tenantPermissions.join(", ")}, which reaches no Project. ` : "";
-  const perProject = projects.length === 0 ? "" : `. Granted per Project: ${projects.join(", ")}` + (mutating.length > 0 ? ` \u2014 you can deploy in ${mutating.map((project) => project.projectId).join(", ")}` : " \u2014 read-only there");
+  const perProject = projects.length === 0 ? "" : `. Granted per Project: ${projects.join(", ")}` + (mutating.length > 0 ? ` \u2014 you can deploy in ${mutating.map((project2) => project2.projectId).join(", ")}` : " \u2014 read-only there");
   checks.push(
     organizationWide ? {
       name: "Access",
@@ -18323,7 +19027,6 @@ function report2(checks, json) {
 }
 
 // src/commands/export.ts
-var import_yaml2 = __toESM(require_dist(), 1);
 async function runExport(parsed) {
   if (parsed.command[1] !== "product-instance" && parsed.command[1] !== "resource") {
     process.stderr.write("Usage: vfac export product-instance pri_\u2026\n");
@@ -18351,7 +19054,7 @@ async function runExport(parsed) {
   if (!result.ok) return printError(result.error, parsed.flags["output"] === "json");
   process.stdout.write(
     parsed.flags["output"] === "json" ? `${JSON.stringify(result.data, null, 2)}
-` : (0, import_yaml2.stringify)(result.data)
+` : manifestYaml(result.data)
   );
   const metadata = result.data["metadata"];
   const hasKey = typeof metadata === "object" && metadata !== null && "key" in metadata;
@@ -18763,14 +19466,57 @@ function renderProduct(product) {
     (profile) => `${profile.id}${profile.default ? " (default)" : ""}`
   );
   lines.push(`  profile         ${profiles.join(", ") || "(none declared)"}`);
-  const seed = seedConfiguration(product.configuration);
-  if (seed.open.length > 0 || seed.requiredSecrets.length > 0) {
-    lines.push("", "  Required configuration");
-    for (const name of seed.requiredSecrets) {
-      lines.push(`    ${name}  (secret \u2014 pass --secret ${name}=env:VAR)`);
+  const settings = configurationRequirements(product.configuration);
+  if (settings.length > 0) {
+    lines.push("", `  Settings (${settings.length})`);
+    for (const setting of settings) {
+      lines.push(
+        `    ${identityOf(setting)}  ${setting.secret ? "secret" : setting.type}  ${TOKEN[setting.requiredness]}`
+      );
+      const requirement = requirementOf(setting);
+      if (requirement !== null) lines.push(...continuation(requirement));
+      if (setting.requires.length > 0 && !mutualClause(setting)) {
+        lines.push(
+          ...continuation(
+            `answering it also requires ${listOf(
+              setting.requires.map((member) => identityOf(member)),
+              "and"
+            )}`
+          )
+        );
+      }
+      if (setting.condition?.carrier === "container") {
+        lines.push(
+          ...continuation(
+            `${printableConfigurationPath(setting.condition.carrierPath)} is required when ${setting.condition.printableSetting} is ${valueList(setting.condition.anyOf)}`
+          )
+        );
+      }
+      if (setting.secret) {
+        lines.push(...continuation(`--secret ${String(setting.path)}=env:VAR`));
+      }
+      if (setting.allowed.length > 0) {
+        lines.push(...continuation(`one of ${valueList(setting.allowed)}`));
+      }
+      if (setting.defaultValue !== void 0) {
+        lines.push(...continuation(`default ${JSON.stringify(setting.defaultValue)}`));
+      }
     }
-    for (const setting of seed.open) {
-      lines.push(`    ${setting.label}  ${setting.type ?? ""}`.trimEnd());
+  }
+  const seed = seedConfiguration(product.configuration);
+  const together = seed.groups.filter((group) => group.within !== null);
+  if (together.length > 0) {
+    lines.push("", "  Settings that go together");
+    for (const group of together) {
+      const index = group.settings.indexOf(group.trigger);
+      const trigger = index === -1 ? `${group.trigger} (secret)` : group.labels[index] ?? group.trigger;
+      const needs = [
+        ...group.labels.filter((_, at) => at !== index),
+        ...group.secrets.filter((path) => path !== group.trigger).map((path) => `--secret ${path}=env:VAR`)
+      ];
+      lines.push(
+        `    ${trigger}  also needs ${needs.join(" + ")}  (if ${group.within} is configured)`
+      );
     }
   }
   const dependencies = product.dependencies ?? [];
@@ -18807,9 +19553,66 @@ function renderProduct(product) {
       lines.push(`    ${condition.key ?? ""}  ${condition.displayName ?? ""}`.trimEnd());
     }
   }
-  lines.push("", "  `--output json` carries the whole declaration, this is a readable subset.");
+  lines.push(
+    "",
+    "  `--output json` carries the whole declaration. Every setting is listed above;",
+    "  descriptions and value constraints are in the JSON form."
+  );
+  if (settings.some((setting) => setting.secret)) {
+    lines.push("  A credential is supplied per apply and never written into a manifest.");
+  }
   return lines.join("\n");
 }
+var TOKEN = {
+  always: "required",
+  "when-value": "required-when",
+  "when-group": "required-if",
+  "with-siblings": "required-with",
+  optional: "optional"
+};
+var MAX_LISTED_VALUES = 8;
+var identityOf = (setting) => setting.secret ? String(setting.path) : setting.printablePath;
+function valueList(values) {
+  const shown = values.slice(0, MAX_LISTED_VALUES).map((value) => JSON.stringify(value));
+  const rest = values.length - shown.length;
+  const joined = shown.length === 2 ? shown.join(" or ") : shown.join(", ");
+  return rest > 0 ? `${joined} and ${rest} more` : joined;
+}
+function requirementOf(setting) {
+  const list = setting.list === null ? "" : ` ${setting.list.printablePath}`;
+  switch (setting.requiredness) {
+    case "always":
+      return setting.perRow ? `in every${list} entry` : null;
+    case "when-value": {
+      const condition = setting.condition;
+      if (condition === null) return null;
+      const rows = condition.anyRow ? " in any entry" : "";
+      return `when ${condition.printableSetting} is ${valueList(condition.anyOf)}${rows}`;
+    }
+    case "when-group": {
+      const owner = setting.containers[setting.containers.length - 1];
+      const base = `once ${owner?.printablePath ?? ""} is configured`;
+      return setting.perRow ? `${base}, in every${list} entry` : base;
+    }
+    case "with-siblings": {
+      const names = (members) => members.map((member) => identityOf(member));
+      const triggers = names(setting.requiredBy);
+      return mutualClause(setting) ? `with ${names(setting.requires).join(", ")}` : `once ${listOf(triggers, "or")} is set`;
+    }
+    case "optional":
+      return setting.perRow ? `one per${list} entry` : null;
+  }
+}
+function mutualClause(setting) {
+  const requires = setting.requires.map((member) => String(member.path)).sort();
+  const requiredBy = setting.requiredBy.map((member) => String(member.path)).sort();
+  return requires.length > 0 && requires.join("\0") === requiredBy.join("\0");
+}
+function listOf(items, conjunction) {
+  if (items.length <= 1) return items[0] ?? "";
+  return `${items.slice(0, -1).join(", ")} ${conjunction} ${items[items.length - 1]}`;
+}
+var continuation = (sentence) => wrap(sentence, 72).map((line) => `      ${line}`);
 function wrap(text, width) {
   const lines = [];
   for (const paragraph of text.split(/\n\s*\n/)) {
@@ -18992,7 +19795,6 @@ Only approve a code you are looking at right now. Waiting\u2026
 }
 
 // src/commands/manifest-init.ts
-var import_yaml3 = __toESM(require_dist(), 1);
 async function runManifestInit(parsed) {
   const verb = parsed.command[1];
   if (verb !== "init") {
@@ -19074,7 +19876,7 @@ async function runManifestInit(parsed) {
     );
   }
   for (const group of seed.groups) {
-    const settings = group.settings.map((name2) => `spec.configuration.${name2}`);
+    const settings = group.labels.map((label) => `spec.configuration.${label}`);
     const secrets = group.secrets.map((name2) => `--secret ${name2}=env:VAR`);
     notes.push(
       `${[...settings, ...secrets].join(" + ")}  \u2014 all of these together, or none of them`
@@ -19097,7 +19899,7 @@ ${where}`);
   }
   process.stdout.write(
     parsed.flags["output"] === "json" ? `${JSON.stringify(document, null, 2)}
-` : (0, import_yaml3.stringify)(document)
+` : manifestYaml(document)
   );
   if (notes.length > 0) {
     process.stderr.write("\nStill yours to fill in:\n");
@@ -19290,7 +20092,9 @@ Options
       --endpoint  your organization's portal. Defaults to VFAC_ENDPOINT, then the
                   stored context
       --secret    plan and apply: NAME=env:VARIABLE \u2014 the value is read from the
-                  environment. Plan a run that sets a secret with the same
+                  environment. NAME is the setting's name, or its path when it
+                  sits inside a group: --secret /upstreamAuth/clientSecret=env:VAR.
+                  Plan a run that sets a secret with the same
                   --secret inputs the apply will carry; without them the plan
                   answers about a different request. A value on the command line
                   is in your shell history and in the process table, so it is
@@ -19309,12 +20113,16 @@ Options
       --output    json, for a pipeline that reads the answer
 
 Diagnosing
-  vfac doctor   checks the endpoint, the machine API, whether this client is new
-                enough for that platform, the credential and what that credential
-                can reach \u2014 in that order, so the first thing that is actually
-                wrong is the thing it reports. It ends by asking npm whether a
-                newer vfac has been published, which is a note and never a
-                failure. Set VFAC_NO_UPDATE_CHECK to skip that one request
+  vfac doctor   checks the config it could read, the endpoint, which Project this
+                terminal has selected and which one the command will act in, the
+                machine API, whether this client is new enough for that platform,
+                how this terminal is signed in and what that credential can reach
+                \u2014 in that order, so the first thing that is actually wrong is the
+                thing it reports. Pass --project to ask about the Project a
+                command would name, which changes nothing on disk. It ends by
+                asking npm whether a newer vfac has been published, which is a
+                note and never a failure. Set VFAC_NO_UPDATE_CHECK to skip that
+                one request
   vfac whoami   what this credential is, and which Project scopes it has been
                 GRANTED. A credential scoped to one Project deploys fine and
                 cannot make organization-wide reads \u2014 this is where that is said.