diff --git a/extra_script.py b/extra_script.py
index 9b6661f..52ae393 100644
--- a/extra_script.py
+++ b/extra_script.py
@@ -1,12 +1,23 @@
 import os
-Import("env")
+from typing import Any
+
+# PlatformIO injects Import() and env at runtime. The editor does not know these
+# names at file-load time, so we keep a short, explicit guard and silence the
+# static-analysis warning for the SCons hook itself.
+try:
+    Import("env")  # type: ignore[name-defined]
+except NameError:
+    env: Any = None
+
+if env is None:
+    raise RuntimeError("This script must be run by PlatformIO's SCons environment.")
 
 # Access to global construction environment
-build_tag = env['PIOENV']
+build_tag = env["PIOENV"]
 version_tag = os.getenv("FIRMWARE_VERSION", "dev").strip()
 
 # CPPDEFINES ensures the macro expands to a valid C string literal instead of a bare identifier.
-env.Append(CPPDEFINES=[('FIRMWARE_VERSION', f'\\"{version_tag}\\"')])
+env.Append(CPPDEFINES=[("FIRMWARE_VERSION", f'\\"{version_tag}\\"')])
 env.Replace(PROGNAME="firmware_%s_%s" % (build_tag, version_tag))
 
 # include toolchain paths