docs: Update AGENTS.md with comprehensive feature documentation

AGENTS.md

@@ -9,8 +9,18 @@ The unified `scl_lsp` project provides:
 - **Linter** - Diagnostics and code validation
 - **Formatter** - Document formatting
 - **Syntax Highlighting** - Tree-sitter based
-- **Auto-completion** - blink.cmp integration
+- **Auto-completion** - blink.cmp integration with smart context-aware completions
 - **Auto-prefix** - Automatic `#` prefixing for variables
+- **Workspace Scanning** - Automatic scanning of UDTs (.udt) and Global DBs (.db)
+
+## Reference Project for Testing
+
+For testing and referencing SCL, UDT, DB, and XML files, use the reference project at:
+```
+~/dev/siemens/projects/scl_lang_support_lazyvim_ref_project
+```
+
+This project contains example SCL files, UDT definitions, and global data blocks.
 
 ## Project Structure
 
@@ -25,14 +35,16 @@ scl_lsp/
 │   ├── json.lua               # JSON encoder/decoder
 │   └── plc_json.lua           # External UDT loading
 ├── lua/
-│   ├── scl/                  # Neovim plugin modules (from scl_syntax_nvim)
+│   ├── scl/                   # Neovim plugin modules
-│   │   ├── init.lua
+│   │   ├── init.lua          # Main plugin setup
-│   │   ├── auto_prefix.lua
+│   │   ├── auto_prefix.lua    # Auto-prefix variables with #
-│   │   ├── blink_cmp_source.lua
+│   │   ├── blink_cmp_source.lua    # blink.cmp completion source
-│   │   ├── fb_parser.lua
+│   │   ├── db_parser.lua           # Global DB (.db) parser
-│   │   ├── udt_parser.lua
+│   │   ├── fb_parser.lua           # Function Block parser
-│   │   ├── variables.lua
+│   │   ├── udt_parser.lua         # UDT (.udt) parser
-│   │   └── workspace_types.lua
+│   │   ├── variables.lua          # Local variable extraction
+│   │   ├── workspace_types.lua     # Workspace scanning (UDTs, DBs, FBs)
+│   │   └── multiline_params.lua   # Multiline parameter filling
 │   └── scl_lsp/
 │       ├── init.lua           # Unified plugin setup
 │       └── plugins/
@@ -47,6 +59,77 @@ scl_lsp/
 └── tree-sitter.json         # Parser config
 ```
 
+## Key Modules
+
+### Parser Modules
+
+| Module | Purpose |
+|--------|---------|
+| `udt_parser.lua` | Parses `.udt` files to extract TYPE definitions and STRUCT members |
+| `db_parser.lua` | Parses `.db` files to extract DATA_BLOCK definitions and VAR members |
+| `fb_parser.lua` | Parses `.scl` files to extract FUNCTION_BLOCK and FUNCTION interfaces |
+| `variables.lua` | Extracts local variables from VAR sections |
+
+### Completion System
+
+| Module | Purpose |
+|--------|---------|
+| `blink_cmp_source.lua` | Main completion source for blink.cmp. Handles: |
+| | - Local variables (with # prefix after BEGIN) |
+| | - UDT types (quoted: "MyUDT") |
+| | - UDT members (after dot: #var.member) |
+| | - Global DB names (available in general completion) |
+| | - Global DB members (after quote+dot: "DBName".member) |
+| | - FB parameter completions (inside FB calls) |
+| | - Basic SCL types |
+
+### Workspace Scanner
+
+| Module | Purpose |
+|--------|---------|
+| `workspace_types.lua` | Scans project for: |
+| | - `.udt` files (UDT types) |
+| | - `.db` files (Global Data Blocks) |
+| | - `.scl` files (Function Blocks/Functions) |
+| | - Uses project markers to find project root |
+
+## Auto-Completion Features
+
+### Trigger Characters
+- `#` - Local variables (after BEGIN)
+- `.` - Member access (UDT/DB members)
+- `"` - Global DB names and member access
+- `(` - FB/Function parameter completion
+- ` ` (space) - General completion (variables, UDTs, DBs, types)
+
+### Completion Contexts
+
+1. **Variable Completion** (after space or at start)
+   - Local variables from VAR sections
+   - UDT type names (quoted)
+   - Global DB names (wrapped in quotes automatically)
+   - Basic SCL types
+
+2. **Member Completion** (after `.`)
+   - UDT members (resolves through nested types)
+   - DB members (resolves through nested types)
+   - Supports multi-level nesting: `#var.member.submember`
+
+3. **Global DB Completion**
+   - Type `"` then select DB → shows DB members
+   - Or type space → select DB from list → automatically wrapped in quotes
+
+4. **FB Parameter Completion** (after `fbName(`)
+   - Input parameters (`:=`)
+   - InOut parameters (`:=`)
+   - Output parameters (`=>`)
+
+### Special Features
+
+- **Auto-Prefix**: Adds `#` to variables automatically after BEGIN
+- **Quote Wrapping**: DB names selected from general completion are automatically wrapped in quotes
+- **Nested Resolution**: Multi-level member path resolution for both UDTs and DBs
+
 ## Development
 
 ### Running the LSP Server
@@ -84,3 +167,15 @@ tree-sitter parse corpus/test/main_org_block.scl
 ## Configuration
 
 See `README.md` for configuration options and usage.
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `:SCLShowVariables` | Show local variables in current file |
+| `:SCLShowWorkspaceTypes` | Show workspace UDTs, FBs, and Global DBs count |
+| `:SCLRescanWorkspaceTypes` | Rescan workspace for types and DBs |
+| `:SCLPrefixWord` | Manually prefix current word with `#` |
+| `:SCLMultilineParams` | Fill multiline parameters for FB/Function call |
+| `:LspSCLFormat` | Format current SCL file |
+| `:SCLGeneratePlcJson` | Generate plc.data.json from data_types/ |