autoreg-skills-max: initial public release (restored, redacted, hardened)

skills/reverse-proxy-gateway/references/grok2api-model-patching.md

@@ -0,0 +1,65 @@
+# grok2api Model Patching Pattern
+
+When adding a new Grok model to the grok2api codebase, 6 files across 3 layers must be updated.
+
+## Files to Patch
+
+### Layer 1: Control Plane — Model Registry
+
+**`app/control/model/enums.py`**
+- Add new `ModeId` enum value (e.g., `GROK_4_6 = 5`)
+- Add mapping in `to_api_str()` method
+- Add to `ALL_MODES_FULL` tuple
+
+**`app/control/model/registry.py`**
+- Add `ModelSpec` entries for the new model and its variants
+- Example pattern:
+```python
+ModelSpec("grok-4.6",           ModeId.GROK_4_6, Tier.SUPER, Capability.CHAT, True, "Grok 4.6"),
+ModelSpec("grok-4.6-super",     ModeId.GROK_4_6, Tier.SUPER, Capability.CHAT, True, "Grok 4.6 Super"),
+ModelSpec("grok-4.6-heavy",     ModeId.GROK_4_6, Tier.HEAVY, Capability.CHAT, True, "Grok 4.6 Heavy"),
+ModelSpec("grok-4.6-best",      ModeId.GROK_4_6, Tier.SUPER, Capability.CHAT, True, "Grok 4.6 Best", prefer_best=True),
+```
+
+### Layer 2: Control Plane — Account Models
+
+**`app/control/account/models.py`**
+- Add `grok_4_6: QuotaWindow | None = None` to `AccountQuotaSet`
+- Add `mode_id == 5` case in `get()` method
+- Add `mode_id == 5` case in `set()` method
+- Add `grok_4_6` to `to_dict()` and `from_dict()`
+
+**`app/control/account/commands.py`**
+- Add `quota_grok_4_6: dict[str, Any] | None = None` to `AccountPatch`
+
+### Layer 3: Data Plane — Runtime Tables
+
+**`app/dataplane/shared/enums.py`**
+- Add `GROK_4_6 = 5` to `ModeId`
+- Add to `ALL_MODE_IDS` tuple
+
+**`app/dataplane/account/table.py`**
+- Add `quota_grok_4_6_by_idx`, `total_grok_4_6_by_idx`, `window_grok_4_6_by_idx`, `reset_grok_4_6_at_by_idx` column arrays
+- Update `_quota_col()`, `_reset_col()`, `_total_col()`, `_window_col()` to handle `mode_id == 5`
+- Update `_append_slot()` signature and body with `grok_4_6` parameters
+- Update `_update_slot()` signature and body with `grok_4_6` parameters
+
+## Verification
+
+After patching, run syntax check:
+```bash
+cd C:\Users\User\grok2api\grok2api
+python -c "
+import ast, sys
+for f in ['app/control/model/enums.py','app/control/model/registry.py',
+          'app/control/account/models.py','app/control/account/commands.py',
+          'app/dataplane/shared/enums.py','app/dataplane/account/table.py']:
+    ast.parse(open(f).read()); print(f'OK: {f}')
+"
+```
+
+## Pitfalls
+
+- **Columnar arrays**: the table.py uses typed `array.array` columns. Each new mode needs 4 new columns (quota, total, window, reset). The `_append_slot` and `_update_slot` methods have long parameter lists that must match exactly.
+- **Mode ID consistency**: the control-plane `ModeId` and data-plane `ModeId` must have the same integer values. The data-plane enum is a separate copy in `dataplane/shared/enums.py`.
+- **The protocol layer (`xai_chat.py`) uses `mode_id.to_api_str()` generically** — no changes needed there if the mode_id mapping is correct.