docs: encourage adding comments; fix nested IF/ELSIF indentation

- Update AGENTS.md to encourage comments instead of forbidding them
- Add docstrings to all public functions in src/ modules
- Add module headers and function comments to lua/scl/ modules
- Fix formatter to properly indent multi-line IF/ELSIF conditions
- Fix FB call detection to not match IF statements with parentheses

src/diagnostics.lua

@@ -1,4 +1,6 @@
 -- SCL Diagnostics - Linter functionality for the LSP server
+-- Validates SCL code for undefined variables, unknown types, and syntax errors
+
 local M = {}
 
 -- Get script path for loading parser (same pattern as main.lua)
@@ -18,6 +20,7 @@ package.path = package.path .. ";" .. script_path .. "/?.lua"
 local parser = dofile(script_path .. "/parser.lua")
 local builtin = dofile(script_path .. "/builtin_instructions.lua")
 
+-- LSP diagnostic severity levels
 local DiagnosticSeverity = {
   Error = 1,
   Warning = 2,
@@ -25,6 +28,10 @@ local DiagnosticSeverity = {
   Hint = 4,
 }
 
+--- Convert line/character to LSP position format
+--- @param line number Zero-based line number
+--- @param character number Zero-based character offset
+--- @return table LSP Position object
 local function position_to_lsp(line, character)
   return {
     line = line,
@@ -32,6 +39,12 @@ local function position_to_lsp(line, character)
   }
 end
 
+--- Create LSP Range object from start and end positions
+--- @param start_line number Start line (zero-based)
+--- @param start_char number Start character (zero-based)
+--- @param end_line number End line (zero-based)
+--- @param end_char number End character (zero-based)
+--- @return table LSP Range object
 local function range_to_lsp(start_line, start_char, end_line, end_char)
   return {
     start = position_to_lsp(start_line, start_char),
@@ -39,6 +52,12 @@ local function range_to_lsp(start_line, start_char, end_line, end_char)
   }
 end
 
+--- Validate SCL content and generate diagnostics
+--- Checks for: undefined variables, invalid # prefix, unknown data types
+--- @param content string The SCL source code to validate
+--- @param workspace_types table Known types from workspace scanning
+--- @param root_dir string Project root directory for additional type lookup
+--- @return table Array of LSP Diagnostic objects
 function M.validate_diagnostics(content, workspace_types, root_dir)
   local diagnostics = {}
   local lines = {}