Family Expansions

internal/topdata/FAMILY_EXPANSION_CONTRACT.md

@@ -31,6 +31,24 @@ Canonical generated families declare:
   "family": "weapon_focus",
   "family_key": "weaponfocus",
   "template": "masterfeats:weaponfocus",
+  "name_prefix": "Weapon Focus",
+  "label_prefix": "FEAT_WEAPON_FOCUS",
+  "constant_prefix": "FEAT_WEAPON_FOCUS",
+  "default_fields": {
+    "DESCRIPTION": {
+      "tlk": {
+        "key": "masterfeats:weaponfocus.description",
+        "text": "..."
+      }
+    },
+    "MINATTACKBONUS": "1",
+    "TOOLSCATEGORIES": "1"
+  },
+  "apply_after_modules": true,
+  "identity_source": "child_source_value",
+  "auto_prereq_fields": {
+    "PREREQFEAT1": "weaponfocus"
+  },
   "child_source": {
     "dataset": "baseitems",
     "column": "WeaponFocusFeat"
@@ -40,10 +58,27 @@ Canonical generated families declare:
 
 Rules:
 
-- `family` is the authored family type
+- `family` is an authored label and is not a hardcoded switch key
 - `family_key` is the structural parent identity used in generated child keys
 - `template` is optional for the primitive in general, but required by current
   masterfeat-backed `feat` families
+- `name_prefix`, `label_prefix`, and `constant_prefix` define how new child rows are
+  named when they are not already authored
+- `template_fields` lists template-backed fields copied from the referenced template row
+  when authored; it is optional if the family owns its shared values directly
+- `default_fields` applies authored shared/default values to every generated family row
+  and can be used to move family-wide shared values out of the template row
+- `apply_after_modules: true` re-applies the generated family after normal module files,
+  so authored family-shared values remain authoritative even for legacy explicitly
+  authored child rows
+- `child_ref_field` binds the generated child row back to the source row key, e.g.
+  `REQSKILL`
+- `identity_source: "child_source_value"` tells the builder to reuse IDs/keys from the
+  source column when that column already carries feat identity
+- `auto_prereq_fields` binds prerequisite fields to other authored families by
+  `family_key`, without code changes
+- `allow_existing_only` limits expansion to already-authored child rows when a family is
+  intentionally partial
 - `child_source.dataset` identifies the canonical dataset driving expansion
 - `child_source.column` is used when expansion is gated by a non-null source field
 - `child_source.predicate` is used when expansion depends on a named rule such as