@@ -5,13 +5,43 @@
 #              No Indigo, no Claude — plain Python, runs anywhere.
 # Author:      CliveS & Claude Opus 4.8
 # Date:        15-06-2026
-# Version:     0.1
+# Version:     0.2
+#
+# v0.2 (20-09-2026) — two ways a config could look fine and not work:
+#   * a token pasted with a trailing newline passed is_configured() and then got
+#     a 401 from Axle. Trimming is done ON LOAD, not at the check, because
+#     trimming only at the check would make setup say yes while the daemon still
+#     sent the untrimmed value.
+#   * a corrupt config.json raised a bare JSONDecodeError out of load_config()
+#     naming no file. It now raises ConfigError with the path, the line and
+#     column, and what to do about it.
 
 import json
 import os
 
 CONFIG_FILENAME = "config.json"
 
+
+class ConfigError(Exception):
+    """A config.json that exists but cannot be used.
+
+    Carries the path and a plain-English reason so the daemon prints one line
+    rather than a traceback. Deliberately NOT a fall back to defaults: running
+    on DEFAULTS after failing to read the user's file would drive the inverter
+    to a 4 kW export target and a 10% reserve that nobody chose, and the only
+    sign would be a log line nobody reads. Refusing to start is the safe answer.
+    """
+
+
+# Values people paste by hand, which routinely arrive with a trailing newline or
+# a leading space when copied out of a browser or a password manager.
+_TRIM_FIELDS = (
+    ("inverter", "ip"),
+    ("vpp",      "axle_token"),
+    ("notify",   "pushover_token"),
+    ("notify",   "pushover_user"),
+)
+
 # Defaults. The setup wizard fills inverter.ip + vpp.axle_token (the only two the
 # user must supply) and auto-detects vpp.export_target_kw from the inverter where
 # it can. Everything else has a sensible default and is rarely touched.
@@ -60,20 +90,66 @@ def _deep_merge(base, override):
     return out
 
 
+def _trim_pasted_fields(cfg):
+    """Strip surrounding whitespace from the hand-pasted values, in place.
+
+    Done on LOAD so every consumer sees the clean value. Doing it in
+    is_configured() instead would fix only the check: setup would report the
+    daemon ready and Axle would still answer 401 for the untrimmed token.
+    """
+    for section, key in _TRIM_FIELDS:
+        sect = cfg.get(section)
+        if isinstance(sect, dict) and isinstance(sect.get(key), str):
+            sect[key] = sect[key].strip()
+    return cfg
+
+
 def config_path(directory=None):
     """Absolute path to config.json next to this script (or in `directory`)."""
     base = directory or os.path.dirname(os.path.abspath(__file__))
     return os.path.join(base, CONFIG_FILENAME)
 
 
 def load_config(path=None):
-    """Load config.json merged over DEFAULTS. Returns (config_dict, exists_bool)."""
+    """Load config.json merged over DEFAULTS. Returns (config_dict, exists_bool).
+
+    A MISSING file is normal — that is the (defaults, False) case the wizard
+    starts from. A file that exists and cannot be used raises ConfigError, which
+    names the path and says what to do; see that class for why this never falls
+    back to defaults.
+    """
     path = path or config_path()
     if not os.path.exists(path):
-        return _deep_merge(DEFAULTS, {}), False
-    with open(path, encoding="utf-8") as fh:
-        user = json.load(fh)
-    return _deep_merge(DEFAULTS, user), True
+        return _trim_pasted_fields(_deep_merge(DEFAULTS, {})), False
+
+    try:
+        with open(path, encoding="utf-8") as fh:
+            user = json.load(fh)
+    except json.JSONDecodeError as exc:
+        raise ConfigError(
+            f"{path} is not valid JSON — {exc.msg}, line {exc.lineno} column {exc.colno}. "
+            f"Fix it by hand, or delete it and run:  python3 sigen_vpp.py --setup"
+        ) from exc
+    except UnicodeDecodeError as exc:
+        raise ConfigError(
+            f"{path} is not readable as UTF-8 text ({exc.reason}). "
+            f"Delete it and run:  python3 sigen_vpp.py --setup"
+        ) from exc
+    except OSError as exc:
+        raise ConfigError(
+            f"{path} could not be read — {exc.strerror}."
+        ) from exc
+
+    # Valid JSON is not necessarily a config: a bare list or string would reach
+    # _deep_merge and die on .items() with a message about neither the file nor
+    # the problem.
+    if not isinstance(user, dict):
+        raise ConfigError(
+            f"{path} must hold a JSON object, not a {type(user).__name__}. "
+            f"Delete it and run:  python3 sigen_vpp.py --setup"
+        )
+
+    return _trim_pasted_fields(_deep_merge(DEFAULTS, user)), True
 
 
 def save_config(cfg, path=None):
@@ -91,5 +167,16 @@ def save_config(cfg, path=None):
 
 
 def is_configured(cfg):
-    """True once the two required fields are present."""
-    return bool(cfg["inverter"]["ip"]) and bool(cfg["vpp"]["axle_token"])
+    """True once the two required fields hold something other than whitespace.
+
+    load_config() has already trimmed them; this strips again so a config built
+    by hand in a test or a script gets the same answer, and tolerates a section
+    that a hand-edited file replaced with a scalar.
+    """
+    def _filled(section, key):
+        sect = cfg.get(section)
+        if not isinstance(sect, dict):
+            return False
+        return bool(str(sect.get(key) or "").strip())
+
+    return _filled("inverter", "ip") and _filled("vpp", "axle_token")
@@ -473,14 +473,23 @@ def main():
     args = p.parse_args()
 
     _setup_logging(args.verbose)
-    if args.setup:
-        return cmd_setup(args)
-    if args.status:
-        return cmd_status(args)
-    if getattr(args, "test_export"):
-        return cmd_test_export(args)
-    if args.run:
-        return cmd_run(args)
+
+    # Every command starts by loading config.json, so catch a bad one ONCE here
+    # rather than in each of the four. ConfigError already reads as a finished
+    # sentence naming the file and the fix, so it is printed as-is — a traceback
+    # would bury it.
+    try:
+        if args.setup:
+            return cmd_setup(args)
+        if args.status:
+            return cmd_status(args)
+        if getattr(args, "test_export"):
+            return cmd_test_export(args)
+        if args.run:
+            return cmd_run(args)
+    except cfgmod.ConfigError as exc:
+        print(f"Configuration problem: {exc}")
+        return 1
     return 1
 
 
 
@@ -0,0 +1,70 @@
+#! /usr/bin/env python
+# -*- coding: utf-8 -*-
+# Filename:    tests/test_cli_reports_bad_config.py
+# Description: main() must turn a ConfigError into one readable line and exit 1,
+#              for every command. The exception being raised is only half the fix;
+#              this is the half the user actually sees.
+# Author:      CliveS & Claude Opus 5
+# Date:        20-09-2026
+# Version:     1.0
+
+import io
+import os
+import tempfile
+import unittest
+from contextlib import redirect_stdout
+from unittest.mock import patch
+
+import config as cfgmod
+import sigen_vpp
+
+
+class TestCliReportsBadConfig(unittest.TestCase):
+    def _run(self, argv):
+        out = io.StringIO()
+        with patch.object(sigen_vpp.sys, "argv", ["sigen_vpp.py"] + argv), \
+             redirect_stdout(out):
+            rc = sigen_vpp.main()
+        return rc, out.getvalue()
+
+    def test_every_command_reports_it_rather_than_raising(self):
+        # One try/except in main() covers all four; this is what proves it, and
+        # what would fail if a fifth command were added outside the block.
+        d = tempfile.mkdtemp()
+        path = os.path.join(d, "config.json")
+        with open(path, "w", encoding="utf-8") as fh:
+            fh.write("{ not json")
+
+        with patch.object(cfgmod, "config_path", return_value=path):
+            for cmd in ("--status", "--run", "--test-export", "--setup"):
+                with self.subTest(cmd):
+                    rc, out = self._run([cmd])
+                    self.assertEqual(rc, 1)
+                    self.assertIn("Configuration problem", out)
+                    self.assertIn(path, out)
+                    self.assertNotIn("Traceback", out)
+
+    def test_the_message_tells_the_user_what_to_do(self):
+        d = tempfile.mkdtemp()
+        path = os.path.join(d, "config.json")
+        with open(path, "w", encoding="utf-8") as fh:
+            fh.write("[1, 2]")
+        with patch.object(cfgmod, "config_path", return_value=path):
+            rc, out = self._run(["--status"])
+        self.assertEqual(rc, 1)
+        self.assertIn("--setup", out)
+
+    def test_a_missing_config_still_gets_its_own_friendlier_message(self):
+        # Absent is not corrupt — it must keep saying "run --setup", not
+        # "Configuration problem".
+        d = tempfile.mkdtemp()
+        path = os.path.join(d, "config.json")
+        with patch.object(cfgmod, "config_path", return_value=path):
+            rc, out = self._run(["--status"])
+        self.assertEqual(rc, 1)
+        self.assertNotIn("Configuration problem", out)
+        self.assertIn("--setup", out)
+
+
+if __name__ == "__main__":
+    unittest.main()
@@ -2,10 +2,11 @@
 # -*- coding: utf-8 -*-
 # Filename:    tests/test_config.py
 # Description: Unit tests for config.py — defaults, deep merge, load/save round trip
-#              and the 0600 permissions that protect the Axle token.
+#              the 0600 permissions that protect the Axle token, and the two
+#              v0.2 fixes: whitespace trimming and a named ConfigError.
 # Author:      CliveS & Claude Opus 5
 # Date:        20-09-2026
-# Version:     1.0
+# Version:     1.1
 
 import json
 import os
@@ -84,6 +85,112 @@ def test_a_partial_file_never_loses_a_required_key(self):
             self.assertIn(key, cfg[section], f"{section}.{key} lost by the merge")
 
 
+class TestTrimsPastedFields(unittest.TestCase):
+    """A token copied out of a browser routinely carries a trailing newline.
+    Trimming happens on LOAD, not at the check — trimming only at the check would
+    let setup report ready while the daemon still sent the untrimmed value."""
+
+    def _loaded(self, user):
+        with tempfile.TemporaryDirectory() as d:
+            p = os.path.join(d, "config.json")
+            with open(p, "w", encoding="utf-8") as fh:
+                json.dump(user, fh)
+            return cfgmod.load_config(p)[0]
+
+    def test_the_token_and_ip_are_trimmed(self):
+        cfg = self._loaded({"inverter": {"ip": "  192.168.1.50\n"},
+                            "vpp": {"axle_token": "\ttok  "}})
+        self.assertEqual(cfg["inverter"]["ip"], "192.168.1.50")
+        self.assertEqual(cfg["vpp"]["axle_token"], "tok")
+
+    def test_pushover_keys_are_trimmed_too(self):
+        cfg = self._loaded({"notify": {"pushover_token": " a\n", "pushover_user": "b "}})
+        self.assertEqual(cfg["notify"]["pushover_token"], "a")
+        self.assertEqual(cfg["notify"]["pushover_user"], "b")
+
+    def test_a_whitespace_only_token_becomes_empty_so_the_check_fails(self):
+        cfg = self._loaded({"inverter": {"ip": "192.168.1.50"},
+                            "vpp": {"axle_token": "   \n"}})
+        self.assertEqual(cfg["vpp"]["axle_token"], "")
+        self.assertFalse(cfgmod.is_configured(cfg))
+
+    def test_non_string_values_are_left_alone(self):
+        cfg = self._loaded({"inverter": {"ip": 123}})
+        self.assertEqual(cfg["inverter"]["ip"], 123)
+
+    def test_other_fields_are_not_trimmed(self):
+        # Only the hand-pasted ones. A deliberate trailing space elsewhere is the
+        # user's business.
+        cfg = self._loaded({"web": {"bind": " 0.0.0.0 "}})
+        self.assertEqual(cfg["web"]["bind"], " 0.0.0.0 ")
+
+
+class TestConfigError(unittest.TestCase):
+    """A config that exists but cannot be used must name itself and refuse to
+    start. It must NEVER fall back to DEFAULTS — that would silently drive the
+    inverter to a 4 kW target and a 10% reserve nobody chose."""
+
+    def _load(self, text, mode="w"):
+        d = tempfile.mkdtemp()
+        p = os.path.join(d, "config.json")
+        with open(p, mode) as fh:
+            fh.write(text)
+        return p
+
+    def test_malformed_json_names_the_file_and_the_place(self):
+        p = self._load('{"vpp": {"axle_token": "abc",}')
+        with self.assertRaises(cfgmod.ConfigError) as cm:
+            cfgmod.load_config(p)
+        msg = str(cm.exception)
+        self.assertIn(p, msg)
+        self.assertIn("line 1", msg)
+        self.assertIn("--setup", msg)
+
+    def test_the_original_error_is_kept_as_the_cause(self):
+        p = self._load("{not json")
+        with self.assertRaises(cfgmod.ConfigError) as cm:
+            cfgmod.load_config(p)
+        self.assertIsInstance(cm.exception.__cause__, json.JSONDecodeError)
+
+    def test_valid_json_that_is_not_an_object_is_refused(self):
+        for label, text in (("a list", "[1, 2]"), ("a string", '"hello"'),
+                            ("null", "null"), ("a number", "42")):
+            with self.subTest(label):
+                p = self._load(text)
+                with self.assertRaises(cfgmod.ConfigError) as cm:
+                    cfgmod.load_config(p)
+                self.assertIn("JSON object", str(cm.exception))
+
+    def test_a_file_that_is_not_utf8_is_refused(self):
+        p = self._load(b"\xff\xfe{}", mode="wb")
+        with self.assertRaises(cfgmod.ConfigError) as cm:
+            cfgmod.load_config(p)
+        self.assertIn("UTF-8", str(cm.exception))
+
+    def test_an_unreadable_file_is_refused_with_its_reason(self):
+        p = self._load("{}")
+        os.chmod(p, 0o000)
+        self.addCleanup(os.chmod, p, 0o600)
+        if os.geteuid() == 0:
+            self.skipTest("running as root — permissions are not enforced")
+        with self.assertRaises(cfgmod.ConfigError) as cm:
+            cfgmod.load_config(p)
+        self.assertIn(p, str(cm.exception))
+
+    def test_it_never_silently_falls_back_to_defaults(self):
+        # THE point. A corrupt file returning (DEFAULTS, True) would start the
+        # daemon on an export target and reserve floor the user never chose.
+        p = self._load("{ broken")
+        with self.assertRaises(cfgmod.ConfigError):
+            cfgmod.load_config(p)
+
+    def test_a_missing_file_is_still_not_an_error(self):
+        with tempfile.TemporaryDirectory() as d:
+            cfg, existed = cfgmod.load_config(os.path.join(d, "absent.json"))
+        self.assertFalse(existed)
+        self.assertEqual(cfg["vpp"]["export_target_kw"], 4.0)
+
+
 class TestSaveConfig(unittest.TestCase):
     def test_round_trip(self):
         with tempfile.TemporaryDirectory() as d:
@@ -132,10 +239,25 @@ def test_needs_both(self):
                 self.assertEqual(cfgmod.is_configured(self._cfg(ip, token)), want)
 
     def test_whitespace_is_not_a_token(self):
-        # Documents CURRENT behaviour: a config whose token is a stray space passes
-        # is_configured() and then fails at Axle with a 401. Flagged, not silently
-        # "fixed" here — changing it is a behaviour change, not a test.
-        self.assertTrue(cfgmod.is_configured(self._cfg("192.168.1.50", " ")))
+        # Was a real flaw until v0.2: a token of stray whitespace passed the check
+        # and then got a 401 from Axle, so setup said ready and nothing worked.
+        for label, ip, token in (
+            ("space token",   "192.168.1.50", " "),
+            ("newline token", "192.168.1.50", "\n"),
+            ("tab ip",        "\t",           "tok"),
+        ):
+            with self.subTest(label):
+                self.assertFalse(cfgmod.is_configured(self._cfg(ip, token)))
+
+    def test_a_non_dict_section_is_not_configured(self):
+        # A hand-edited file can replace a whole section with a scalar. Indexing
+        # it would raise AttributeError out of a boolean check.
+        self.assertFalse(cfgmod.is_configured({"inverter": "", "vpp": {"axle_token": "t"}}))
+        self.assertFalse(cfgmod.is_configured({}))
+
+    def test_a_non_string_value_does_not_explode(self):
+        self.assertTrue(cfgmod.is_configured(
+            {"inverter": {"ip": 19216815}, "vpp": {"axle_token": "tok"}}))
 
 
 if __name__ == "__main__":