Update AGENTS.md with current pipeline and gotchas

AGENTS.md

@@ -10,20 +10,16 @@ Arma 3 config export and rebalance tool. Exports ammo/armor/weapons/magazines to
 - **`weapons.sqf`** — Weapon export with ACE barrel properties (`ACE_barrelLength`, `ACE_barrelTwist`).
 - **`magazines.sqf`** — Magazine export linking to ammo classes with `initSpeed`.
 
-### Legacy scripts (kept for reference)
-- **`sheet1.sqf`** — Weapons + magazines (old format).
-- **`sheet2.sqf`** — Items/gear (old format).
-- **`sheet3_ammo.sqf`** — Ammo (old format, no ACE properties).
-- **`classesExport.sqf`** — Original monolithic script.
-
 ### Processing pipeline (Python)
-- **`scripts/split_by_mod.py`** — Reads raw CSVs from `.rpt`, splits into per-mod folders under `data/`.
+- **`scripts/extract_csvs.py`** — Parses Arma `.rpt` log, extracts CSVs between `--- START/END ---` markers.
-- **`scripts/generate_patches.py`** — Compares all mods to RHS baseline, generates `output/config.cpp`.
+- **`scripts/split_by_mod.py`** — Splits raw CSVs into per-mod folders under `data/`.
+- **`scripts/generate_patches.py`** — Compares all mods to RHS baseline, generates per-mod `output/<mod>/config.cpp` + `debug/<mod>/` before/after CSVs.
+- **`scripts/package_mod.py`** — Packages output into `@mod` folder with PBOs via armake2. Reads settings from `package_mod.ini`.
 
 ### Reference
 - **`REFERENCE.md`** — Quick reference for all config values (vanilla + ACE3).
 
-## Workflow
+## Pipeline (exact commands)
 
 ### Step 1: Run extraction scripts in Arma 3
 Run each script in debug console (or `execVM`). Each outputs CSV via `diag_log` to `.rpt`:
@@ -38,13 +34,13 @@ execVM "magazines.sqf"
 ```bash
 python scripts/extract_csvs.py "path/to/arma3.rpt"
 ```
-Parses the `.rpt` log and extracts CSVs between `--- ... START/END ---` markers into `ammo_raw.csv`, `armor_raw.csv`, `weapons_raw.csv`, `magazines_raw.csv`.
+Produces `ammo_raw.csv`, `armor_raw.csv`, `weapons_raw.csv`, `magazines_raw.csv` in repo root.
 
 ### Step 3: Split by mod
 ```bash
 python scripts/split_by_mod.py
 ```
-Creates `data/[mod_name]/` folders with per-mod CSVs. Baseline mods (`_rhs`, `_vanilla`, `_ace`) sort first.
+Creates `data/[mod_name]/` folders with per-mod CSVs. Baseline folders are prefixed `_` (`_rhs`, `_vanilla`, `_ace`).
 
 ### Step 4: Generate rebalance mod
 ```bash
@@ -52,18 +48,31 @@ python scripts/generate_patches.py
 ```
 Produces:
 - `output/<mod>/config.cpp` — Per-mod CfgPatches config with overrides
-- `output/unmatched.csv` — Items with no RHS equivalent (review manually)
+- `output/unmatched.csv` — Items with no RHS equivalent
+- `debug/<mod>/ammo.csv` — Before/after debug tables for ammo overrides
+- `debug/<mod>/armor.csv` — Before/after debug tables for armor overrides
 
-### Step 5: Load in Arma
+### Step 5: Package and install mod
-Drop the `output/` folder contents into `@mod/addons/<mod>/config.cpp` structure and load it. Each subfolder is an independent addon with its own CfgPatches dependency.
+```bash
+python scripts/package_mod.py
+```
+Reads `package_mod.ini` for mod name, author, version, output path. Produces `@<mod_name>/addons/<mod>_<folder>.pbo` in your Arma mods directory.
 
-## How the scripts work
+## Key gotchas
 
-- Each SQF script takes optional arguments: `[name, CfgPatches name]` for a mod, `[name]` for vanilla BIS.
+- **SQF scripts output to `.rpt` log**, not directly to a file. Must extract from log.
-- Uses `diag_log text(...)` for CSV output — extract from `.rpt` log.
+- **CSV delimiter is `;`** (semicolon), no quoting.
-- Separator is `;` (semicolon). No quoting.
+- **`ammo.sqf` uses `sleep`** — requires scheduled environment (`execVM` or `spawn`).
-- `configSourceAddonList` tags each entry with its source CfgPatches class.
+- **CfgAmmo BFS depth limit** of 8 levels prevents exponential blowup.
-- `ammo.sqf` uses iterative BFS with combined traversal+extraction and `sleep 0` every 200 entries.
+- **`configSourceAddonList` returns CfgPatches class names** (e.g. `rhs_c_troops`), not display names. These are used as folder names in `data/`.
+- **`caliber` is a penetration coefficient**, not actual bullet caliber. Classification uses class name patterns, not caliber value ranges.
+- **RHS baseline**: folders prefixed `_` are baseline. Matching uses `(caliber_tier, subtype)` for ammo, `(item_type, tier)` for armor.
+- **Arma config uses `{}` for arrays**, not `[]`. The generator handles this conversion.
+- **`requiredAddons[]` must use original CfgPatches class names**, not sanitized folder names. `unknown` source_mod entries are skipped.
+- **PBO names use mod name from `package_mod.ini`** (e.g. `a3rebalancer_jca.pbo`).
+- **Debug CSVs go to `debug/`**, not `output/` — they must not be packed into PBOs.
+- **armake2 must be installed** (`cargo install armake2`) and available in PATH or `tools/`.
+- **Arma locks PBO files** when running. Close Arma before repacking.
 
 ## Conventions
 
@@ -71,12 +80,4 @@ Drop the `output/` folder contents into `@mod/addons/<mod>/config.cpp` structure
 - CSVs use `;` delimiter.
 - Python scripts use UTF-8 encoding.
 - Per-mod folders use the CfgPatches class name as folder name.
-
+- `continue` keyword avoided in SQF for pre-2.14 Arma compatibility.
-## Gotchas
-
-- Scripts output to Arma's `.rpt` log, not directly to a file.
-- `ammo.sqf` uses `sleep` which requires scheduled environment (`execVM` or `spawn`).
-- CfgAmmo BFS depth limit of 8 levels prevents exponential blowup.
-- `continue` keyword avoided for pre-2.14 Arma compatibility.
-- `generate_patches.py` classifies ammo by (caliber_tier, subtype). Items with no RHS tier match appear in `unmatched.csv`.
-- Armor matching uses (type, mass_tier). Soft armor items (chest_armor=0) are in their own tier.