Document plan/optimization output column schema for consumers (Node-RED, EVCC adapters, HA cards)

[OptimalNothing90]

Motivation

Downstream consumers (Node-RED flows, EVCC adapters, HA Lovelace cards, troubleshoot skills) currently reverse-engineer the optimization-output column schema from command_line.py source. Each consumer ships its own column-name and sign-convention assumptions; divergence is invisible until something breaks (e.g. SOC 0..1 in CSV vs ×100 for HA display — easy to miss).

A schema audit (linked below) catalogued the 5 _publish_* helpers and their published columns, including units, conditional presence, HA-scaling notes, type_var tags, and a list of sign-convention questions that need maintainer confirmation before publication.

Proposal

Two additive changes in a single PR:

1. New file docs/plan_output_schema.md — listing each published column with: name, source helper, unit, sign convention (after your confirmation), conditional presence, HA-scaling note, type_var tag.
2. EMHASS_SCHEMA_VERSION = "1.0" constant in command_line.py, attached to the result envelope (or as a DataFrame attribute via opt_res.attrs[...]) so consumers can pin against breaking changes.

Semver rules:

• Patch — clarification only (sign confirmed, descriptions sharpened)
• Minor — additive columns
• Major — column removed/renamed, sign convention flipped, unit changed, HA-scaling factor changed

Sign-convention questions (please answer per-line)

The audit Section 4 flags these explicitly because mis-documenting a sign is worse than asking once. I deliberately didn't guess.

• P_grid sign — positive = import (grid → house) or positive = export (house → grid)?
• P_batt sign — positive = discharge (battery → house) or positive = charge (battery absorbing)?
• P_PV sign — positive = production. Confirm or correct?
• P_PV_curtailment — curtailed delta (positive subtracts from gross PV) or net post-curtailment PV?
• P_hybrid_inverter — DC-side or AC-side power? Direction sign?
• heating_demand_heater{k} — thermal demand (heat to deliver, kWh thermal) or electrical demand (electricity to compressor, kWh electrical)? For COP-based heat pumps these differ by ~factor 3.
• predicted_temp_heater{k} — room temperature, supply-water temperature, or storage-tank temperature?

Each open question is a one-line answer; the schema doc fills in immediately after.

Scope

Pure docs + 1-line constant. No behavior change. Backward-compat: consumers ignoring the version constant keep working as before.

Reference

Audit doc:
https://github.com/OptimalNothing90/loxonesmarthome/blob/master/docs/superpowers/specs/2026-04-28-plan-output-audit.md

Includes: per-helper line ranges (verified 2152-2405 + aggregator publish_data at 2408), column table with units + conditionals + type_var tags, reproducer script.

Status

Happy to PR the doc + version constant as a single additive change once sign conventions are confirmed.