feat(isac): add weapon mod data management

docs/DESIGN_SYSTEM.md

@@ -1171,3 +1171,40 @@ state in plain language. Show a share-page action only after a non-private
 build has been saved. Public and unlisted build pages are read-only tactical
 summaries; owner editing returns to the builder. On narrow layouts,
 persistence controls and shared-loadout columns stack vertically.
+
+### Tiered compatibility editors
+
+When compatibility depends on two independent dimensions, keep those
+dimensions explicit rather than presenting a flattened list. Weapon
+definitions configure their available Weapon Mod slots per tier. T0 requires
+four distinct slots; T1 and T2 require five. Weapon Mod definitions then
+configure one slot plus one or more compatible weapon categories. The UI and
+validation must require both dimensions to match.
+
+Weapon Mod definitions use the shared segmented-choice control for the bounded
+eight-slot vocabulary, with a full-width row on desktop and two columns on
+narrow screens. Weapon category compatibility uses the same control in
+checkbox mode with weapon icons and retained accessible names. Show configured
+versus required slot counts in text. Disabled tiers remain visibly unavailable
+and must not submit slot assignments.
+
+Quality-scaled registry editors use a compact matrix when the same numeric
+shape repeats across all four quality levels. Apply global quality colors only
+to the quality labels, retain textual quality names, and keep numeric fields
+neutral. On narrow screens the matrix may scroll horizontally while its
+surrounding editor and previews stack.
+
+When two item slots draw from the same canonical option pool, edit that pool
+once rather than rendering two duplicated selectors. Weapon Mods use a
+repeatable secondary-attribute row: one searchable attribute reference plus
+four quality range pairs. Show that the builder selects two distinct options
+from the pool. Primary core type is likewise builder-selected and is displayed
+as the three always-available core icons rather than a persisted ISAC choice.
+
+Exotic Weapon Mod status is a separate single-icon toggle using the exotic
+icon and the standard pressed, focus-visible, and selected states. Selecting
+it must switch the editor immediately, before a weapon is assigned. Exotic is
+its own unique quality: reveal only the required exotic-weapon assignment,
+remove weapon-category and regular-quality controls, and replace random ranges
+with fixed level-1 and level-20 attribute values. Keep an explicit Exotic
+Quality state panel visible so the change in data semantics is unmistakable.

docs/architecture.md

@@ -233,6 +233,34 @@ talent effects use `base × (1 + upgrades / 5)` for zero to five upgrades.
 Server actions validate all relationships and append the full owned graph to
 the existing `game_data` audit history.
 
+### Weapon Mods and tiered weapon slots
+
+`weapon_mod_slots` records each weapon's available slot vocabulary per tier.
+Canonical validation requires four unique slots for T0 and five for T1/T2 for
+every tier at or above the weapon's native tier. Regular Weapon Mods declare a
+single slot type and one or more compatible base weapon categories through
+`weapon_mod_compatible_categories`; eligibility requires both a category match
+and the slot to exist on the equipped weapon at its selected tier.
+
+Exotic Weapon Mods instead reference one `exotic_weapon_id`. They do not carry
+regular category compatibility, are considered permanently equipped, and may
+only be leveled. They do not use quality profiles, random primary rolls,
+secondary pools, or regular Mod Effects. Their canonical contributions are
+fixed attribute references with explicit level-1 and level-20 values in
+`weapon_mod_exotic_attributes`; intermediate values interpolate linearly.
+
+All regular Weapon Mods permit Firepower, Toughness, or Engineering as a
+builder-time primary choice. `weapon_mod_quality_values` stores the shared
+level-1 and level-20 primary roll endpoints for each quality; primary values
+interpolate linearly from levels 1–20.
+
+`weapon_mod_secondary_options` is the shared pool from which a build selects
+two distinct secondary attributes. Every option owns a minimum and maximum at
+each quality through `weapon_mod_secondary_quality_values`; secondary
+availability is not tied to a numbered slot in canonical data. Mod Effects are
+triggerless, hold one or two attribute references, and store fixed per-quality
+values in `weapon_mod_effect_quality_values`.
+
 # Skill Chip quality scaling
 
 Skill Chip sets support Superior and High-end chip instances. Each set owns one