Document class progression feat availability design

docs/superpowers/specs/2026-05-22-class-progression-feat-availability-design.md

@@ -0,0 +1,83 @@
+# Class Progression Feat Availability Design
+
+## Goal
+
+Class progression wiki rows should distinguish automatically granted class feats
+from level-gated selectable feats while also exposing bonus feat gains declared
+by class `bfeat` tables in the progression table.
+
+## Ownership
+
+The authored wiki page layout stays in `sow-module/topdata/wiki/`. The toolkit
+owns the progression row data assembled from class feat and bonus-feat tables.
+The change should stay inside those boundaries:
+
+- module page templates decide how progression row fields are rendered;
+- toolkit progression row assembly decides which feats are granted and which
+  level-gated selectable feats become notes.
+
+## Behavior
+
+Class feat rows with positive `GrantedOnLevel` values are not all equivalent.
+Rows in class feat tables with `List` value `3` are automatically granted feats.
+Rows with selectable list values such as `0` or `1` become available at the
+declared level but are not granted by the progression itself.
+
+For each class progression row:
+
+- keep automatically granted feats in `GrantedFeats`;
+- keep the per-level bonus feat count from the class `bfeat` table in
+  `BonusFeat`;
+- add level-gated selectable feat availability text to `Notes` in the form
+  `<feat link> becomes available.`;
+- combine multiple availability notes for the same level deterministically in
+  source table order.
+
+Selectable rows without a positive `GrantedOnLevel` remain available through
+the class feat listing and do not create progression notes.
+
+## Rendering
+
+The class progression template can render `BonusFeat` inline in its existing
+Feats cell rather than adding another progression column. It should emit the
+separator only when `GrantedFeats` already rendered content so bonus-only rows
+do not start with a comma.
+
+The existing Notes column renders the toolkit-generated `Notes` text with wiki
+links enabled. The lower class feat table remains useful for listing class feat
+membership and list metadata; its level label should not be interpreted as an
+automatic grant for selectable rows.
+
+## Data Flow
+
+The toolkit resolves the class `FeatsTable` while building progression rows.
+Each resolved feat row contributes to exactly one progression-facing bucket:
+
+- `List == 3` and positive level: resolved feat link in `GrantedFeats`;
+- positive level and selectable list: resolved availability note for that level;
+- non-positive or missing level: no progression-row contribution.
+
+The class `BonusFeatsTable` lookup continues to populate `BonusFeat` from the
+row whose id matches the progression level.
+
+## Errors And Compatibility
+
+The change should preserve current behavior for missing class feat tables,
+missing bonus feat tables, unresolved feat references, and classes without
+level-gated selectable feats. Existing module templates that only read
+`GrantedFeats`, `BonusFeat`, and `Notes` continue to use the same progression
+row fields.
+
+## Tests
+
+Toolkit coverage should verify:
+
+- automatically granted `List == 3` feats remain in progression feat output;
+- positive-level selectable feats are excluded from `GrantedFeats`;
+- positive-level selectable feats render availability notes with wiki links;
+- multiple notes on one level have deterministic order;
+- bonus feat counts remain available to the progression template.
+
+Module validation should rebuild the generated wiki output with the local
+toolkit binary after the toolkit change and inspect a class that has both
+granted feats and level-gated selectable feats, such as fighter.