Update READMEs

core/README.md

@@ -37,6 +37,141 @@ core/
 4. **Goal Check**: Currency changed → goals evaluated → buffs unlocked
 5. **Save**: `LevelGameState.save_game()` → JSON to `user://level_save.json`
 
+## Production Multiplier Chain
+
+All multipliers compose multiplicatively from callee to caller. The entry point is
+`_grant_cycle_income()` in `CurrencyGenerator`.
+
+### Entry: `CurrencyGenerator._grant_cycle_income()` (`currency_generator.gd:134`)
+
+```
+var effective = get_effective_auto_run_multiplier()
+var per_cycle = data.production_per_cycle(owned, effective, purchased_count)
+var produced  = per_cycle × cycle_count
+```
+
+### Layer 1 — `CurrencyGeneratorData.production_per_cycle()` (`currency_generator_data.gd:117`)
+
+```
+production_per_cycle = initial_productivity × owned × run_multiplier × milestone_mult × purchased_mult
+```
+
+| Sub-multiplier | Method | Formula |
+|---|---|---|
+| **milestone_mult** | `milestone_multiplier_total(owned)` | `milestone_multiplier ^ floor(owned / milestone_step)` |
+| **purchased_mult** | `purchased_multiplier(purchased)` | `1.0 + purchased × (purchased_boost_percent / 100)` |
+
+### Layer 2 — `CurrencyGenerator.get_effective_auto_run_multiplier()` (`currency_generator.gd:357`)
+
+This is the `run_multiplier` value passed into Layer 1 above:
+
+```
+effective_run_multiplier = run_multiplier × research_multiplier × auto_production_buffs × prestige_multiplier
+```
+
+#### 2a. `run_multiplier`
+
+Exported `float` on the `CurrencyGenerator` node. Default `1.0`. A scene-level tweak.
+
+#### 2b. `research_multiplier` → `LevelGameState.get_research_multiplier(id)` (`level_game_state.gd:488`) → `ResearchData.get_multiplier_for_level(level)` (`research/research_data.gd:52`)
+
+```
+research_multiplier = base_multiplier + (multiplier_per_level × research_level)
+```
+
+Level is auto-calculated from accumulated BigNumber XP. Both constants are exports on `ResearchData`.
+
+#### 2c. `auto_production_buffs` → `LevelGameState.get_effective_multiplier(generator_id, AUTO_PRODUCTION_MULTIPLIER)` (`level_game_state.gd:441`)
+
+```gdscript
+# For every active buff of kind AUTO_PRODUCTION_MULTIPLIER targeting this generator:
+mult = 1.0
+for buff in buffs:
+    if buff.active and buff.kind == AUTO_PRODUCTION_MULTIPLIER:
+        mult *= buff.get_effect_multiplier(level)
+```
+
+`GeneratorBuffData.get_effect_multiplier(level)` (`generator_buff_data.gd:97`):
+
+```
+buff_effect = base_effect + (effect_increment × level)
+```
+
+Multiple buffs of the same kind stack **multiplicatively**: `∏ (base_effect_i + increment_i × level_i)`.
+
+#### 2d. `prestige_multiplier` → `PrestigeManager.get_total_multiplier()` (`prestige_manager.gd:107`)
+
+Configured via `PrestigeConfig.multiplier_mode`:
+
+| Mode | Formula |
+|---|---|
+| `ADDITIVE` | `base + prestige_points × multiplier_per_prestige` |
+| `MULTIPLICATIVE_POWER` | `base × (1 + multiplier_per_prestige) ^ (prestige_points ^ exponent)` |
+
+### Layer 3 — Production per second
+
+```
+production_per_second = production_per_cycle / maxf(initial_time, 0.0001)
+```
+
+(`currency_generator_data.gd:128`)
+
+### Full Formula (one production cycle)
+
+```
+produced = initial_productivity × owned
+
+         # --- effective_run_multiplier ---
+         × run_multiplier
+         × (base_multiplier + multiplier_per_level × research_level)
+         × ∏(base_effect_i + effect_increment_i × buff_level_i)   [auto-production buffs]
+         × prestige_multiplier                                      [from PrestigeManager]
+
+         # --- milestone & purchased ---
+         × milestone_multiplier ^ floor(owned / milestone_step)
+         × (1.0 + purchased_count × purchased_boost_percent / 100)
+```
+
+### Manual Click Formula (separate path)
+
+`_try_grant_click_currency()` (`currency_generator.gd:460`):
+
+```
+click_reward = (click_mantissa × 10^click_exponent) × ∏ buff_effect_i   [MANUAL_CLICK_MULTIPLIER buffs]
+```
+
+Uses the same `get_effective_multiplier()` loop filtered to `BuffKind.MANUAL_CLICK_MULTIPLIER`.
+Research, prestige, milestone, and purchased multipliers are **not** applied to clicks.
+
+### Research XP Awarded (production side-effect)
+
+Awarded inside `_grant_cycle_income()` when the generator has an associated `ResearchData`:
+
+```
+base_xp   = produced_currency × xp_per_currency_produced
+scaled_xp = base_xp × (1.0 + research_workers × worker_scaling_factor)
+actual_xp = scaled_xp × ∏ buff_effect_i                              [RESEARCH_XP_MULTIPLIER buffs]
+```
+
+Buff multiplier for XP is applied later in `LevelGameState.add_research_xp()`
+via `ResearchBuffCalculator.apply_buffs()` (`core/generator/research_buff_calculator.gd`).
+
+### Cascade Diagram
+
+```
+                    ┌─────────────────────────────────┐
+                    │  run_multiplier (node export)   │
+                    │  research_multiplier (XP level) │─── effective_run_multiplier ──┐
+                    │  auto-production buffs (∏)      │                               │
+                    │  prestige_multiplier            │                               │
+                    └─────────────────────────────────┘                               │
+                                                                                       ▼
+production_per_cycle = initial_productivity × owned × effective_run_multiplier × milestone × purchased
+                                                                                       │
+                                                                                       ▼
+production_per_second = production_per_cycle / initial_time
+```
+
 ## Save Format
 
 **Version**: 5