ADD/UPD documentation and MIT license

docs/developers/troubleshooting.md

@@ -0,0 +1,48 @@
+# Troubleshooting
+
+## CLI Build Error (ModuleNotFoundError)
+
+### Issue Description
+When compiling the project via an external system terminal (Command Line Interface) using `pio run`, the build might crash during the final linking stage with the following error:
+```text
+*** [.pio/build/ttgo-lora32-v21/firmware.elf] ModuleNotFoundError: No module named 'SCons.Tool.FortranCommon'
+```
+Interestingly, this error **does not occur** when triggering the build inside the integrated VS Code PlatformIO IDE.
+
+### Root Cause
+This behavior is caused by a **Python environment collision** on your local Linux system. 
+
+* **Inside the IDE (Success):** VS Code automatically sandboxes the execution path. It activates PlatformIO's isolated virtual environment (located at `~/.platformio/penv/`), ensuring that only the internally shipped, compatible dependencies are used.
+* **Inside the System Terminal (Failure):** When calling `pio` globally, your shell utilizes the system's global Python environment.
+If global Python packages or system-wide SCons modules are present (e.g., installed via `apt`, `dnf`, or `pacman`), they collide with the PlatformIO Core engine.
+This breaks internal lookup paths, causing the compilation to miss the required `FortranCommon` module during the binary linking process.
+
+### Solution
+
+To resolve this issue permanently and ensure the CLI operates with the exact same isolation as the IDE, you must force your terminal to use PlatformIO's dedicated virtual environment binary.
+
+#### Option 1: Configure Shell Aliases (Recommended)
+Add an explicit alias to your shell configuration file to redirect global calls to the virtual environment binary.
+
+1. Open your shell configuration file (e.g., `~/.bashrc` or `~/.zshrc`):
+   ```bash
+   nano ~/.bashrc
+   ```
+2. Append the following lines at the very bottom of the file:
+   ```bash
+   # Force the pio command to use PlatformIO's isolated virtual environment
+   alias pio="~/.platformio/penv/bin/pio"
+   alias platformio="~/.platformio/penv/bin/platformio"
+   ```
+3. Save the file and reload your current terminal session to apply the changes:
+   ```bash
+   source ~/.bashrc
+   ```
+
+#### Option 2: Manually Activate the Virtual Environment
+Alternatively, you can manually bootstrap the PlatformIO virtual environment inside your active terminal instance before running build tasks:
+
+```bash
+source ~/.platformio/penv/bin/activate
+```
+*(Once activated, your terminal prompt will typically show a `(penv)` prefix, indicating that the isolated environment is active).*