feat(plan): "why" tooltips on the plan table (#4310)

[chalfontchubby]

Summary

Adds a plain-English "why" tooltip on each plan-table cell, so non-technical users can self-diagnose common "why did it charge/hold/export here" questions without reading plan.py - raised in #4310.

Shape settled through review from @springfall2008 and @farfromexact on the earlier draft:

• Reason text is captured inline at the exact point publish_html_plan() already decides each slot's Chrg/HoldChrg/FrzChrg/Exp/HoldExp/FrzExp state - no re-derivation of optimizer logic, no changes to the optimizer itself.
• json_row["reasons"] is a list of {code, params} entries per row - no baked sentence. The actual template text lives once in raw_plan["reason_templates"] (published per response, not duplicated per row) and gets rendered client-side by substituting each entry's params into its template (renderReasonText() in web_helper.py).
• Always on - confirmed with @springfall2008 this doesn't touch the C++ prediction kernel path (output.py's per-row narration is pure Python regardless of prediction_kernel_enable), so there's no switch/opt-in.
• Reason codes are strings (e.g. "charge_low_rate") rather than numeric IDs - a string can't silently collide with a different meaning if entries are added over time, where a numeric ID needs active "never renumber, only append" discipline for the same safety.
• Hover-only title= tooltip for now - deliberately not mobile/touch-friendly yet. That's planned as a separate follow-up PR (stacked on this branch) rather than in scope here, since the data (reasons/reason_templates) and the rendering are already cleanly decoupled.

Test plan

• test_plan_why_reason.py - covers every state category (Chrg/HoldChrg/FrzChrg/Exp/HoldExp/FrzExp), both manual-override variants, the demand default, the reasons/reason_templates code+params contract, the client-side title= wiring (including split cells).
• ./run_pre_commit clean.
• Manually verified against a real predbat_debug.yaml replay (not synthetic fixtures) - tooltips render correctly on live data.

🤖 Generated with Claude Code

[springfall2008]

I like the concept, I think the only downside is it could make the HTML and JSON quite a bit bigger.

My suggestion would be:

1. Don't add it to the HTML (I'm trying to phase that out)
   2.Add the data to the JSON but don't duplicate the full text on each cell, just put a reason number e.g. REASON_CODE: "1". Then put a table of reason codes and their text in the JSON
2. Render the HTML with the reason data in web.py
3. Leave on all the time (unless we can think of a problem with this)

Thoughts?

[chalfontchubby]

Reusing comments would prevent embedding values - x>y so doing z

That might be fine but it feels quite nice having them there.

On all the time implies it is in the c++ path as well which might increase maintenance keeping them in step - I've not really dug into how much it touches both paths yet. Again, not a problem so long as it doesn't add too much to compute load when we start extending it.

Not trying to push back - I'm very open to taking advice.

[springfall2008]

AFAIK the C++ is not impacted as that is just prediction.py
I suppose the numbers arguments could be in the json and the template rendered?

[chalfontchubby]

That would work. I don't have it clear in my head yet which bits get accelerated - if there is no impact there and it's just touching one code path that's ideal. It's not adding compute so performance impact should be minimal.

Good.

[chalfontchubby]

Implemented per your suggestion:

• Dropped the per-row baked sentence entirely - json_row["reasons"] is now a list of {code, params} only, no text.
• The templates live once in raw_plan["reason_templates"] (published per response, not per row) and get rendered client-side by substituting each entry's params into its template - so the sentence isn't duplicated across every row.
• Confirmed the C++ kernel point and dropped the plan_why_explanations switch entirely - this is always on now.

One tweak from your suggestion: kept string reason codes (e.g. "charge_low_rate") rather than a numeric ID. Reasoning: a string can't silently collide with a different meaning even if entries get added/reordered over time, where a numeric ID needs active "never renumber, only append" discipline to keep that same safety - and the JSON size difference between the two is a few bytes a row, so not worth trading away the structural safety for. Happy to switch to numeric if you'd still prefer it for a different reason (e.g. matching a convention elsewhere in the codebase).

Pushed to the PR branch.