Add hardcore action family metadata

docs/prompt-pool-routing-map.md

@@ -397,6 +397,9 @@ plain prompt text. When debugging, inspect these fields before editing pools.
 | `content_seed_axis` | `_build_custom_row` | Debug | Shows whether the item/action was driven by `content` or `pose`. Critical for hardcore pose categories. |
 | `item` | `_compose_item` or Insta override | Krea/SDXL/Naturalizer | Clothing item, category item, or sexual scene/action text. |
 | `item_axis_values` | `_compose_item` | Krea hardcore rewrite, SDXL tags | Filled template axes such as position/action/detail values. |
+| `action_family` | `hardcore_action_metadata.source_hardcore_action_family` | Krea hardcore rewrite, debug | Source-aware formatter semantic family such as `foreplay`, `outercourse`, `oral`, `penetration`, `toy_double`, or `climax`. |
+| `position_family` | `_hardcore_source_position_family` | Debug/filtering | Source/UI hardcore family selected by subcategory, such as `manual`, `interaction`, `oral`, `anal`, or `climax`. |
+| `position_key`, `position_keys` | `_hardcore_position_keys` | Debug/future filters | Concrete position tokens inferred from axes and role text, such as `kneeling`, `doggy`, `boobjob`, or `open_thighs`. |
 | `custom_item`, `item_label` | Category/pair route | Formatters and debug | Label/name for item route. |
 | `role_graph` | `_role_graph`, POV adapter | Krea/Naturalizer | Choreography/action relationship text after POV adaptation. |
 | `source_role_graph` | `_role_graph` before POV rewrite | Krea hardcore rewrite | Raw action graph used to infer position and contact. |
@@ -564,6 +567,7 @@ Key Krea2 ownership:
 
 - Cast descriptor naturalization: `krea_cast.cast_prose`,
   `krea_cast.natural_label_text`.
+- Shared action-family metadata: `hardcore_action_metadata.py`.
 - Action context and family predicates: `krea_action_context.py`.
 - Non-POV pose anchors and arrangements: `krea_action_positions.py`.
 - Non-climax item/detail cleanup: `krea_action_details.py`.
@@ -751,13 +755,15 @@ Use these traces to narrow a problem in one pass.
 ### Hardcore action keeps selecting the same family
 
 1. Check metadata `main_category`, `subcategory`, `content_seed_axis`,
-   `hardcore_position_config`, `item`, `role_graph`, and `item_axis_values`.
+   `action_family`, `position_family`, `position_key`, `hardcore_position_config`,
+   `item`, `role_graph`, and `item_axis_values`.
 2. If `hardcore_position_config` disabled most families, the repeated action may
    be the only compatible pool left.
 3. Inspect `categories/sexual_poses.json` for the selected subcategory,
    `item_templates`, `axes`, and `weight`.
 4. If raw `item` differs but Krea output looks identical, inspect
-   `krea_action_context.py` family predicates first, then
+   `hardcore_action_metadata.py` action-family metadata first, then
+   `krea_action_context.py` family predicates,
    `krea_action_positions.py` pose anchors/arrangements,
    `krea_action_details.py` item/detail cleanup, `krea_action_climax.py`
    climax cleanup, `krea_action_dispatch.py` family routing, and