diff --git a/.gitignore b/.gitignore
index 0d77166e..6d49a74a 100644
--- a/.gitignore
+++ b/.gitignore
@@ -48,3 +48,7 @@
 !CHANGELOG.md
 !CONTRIBUTING.md
 !CODE_OF_CONDUCT.md
+
+# Build artifacts
+site/
+.cache/
diff --git a/docs/home/quickstart.md b/docs/home/quickstart.md
index 9793c6ec..704266a0 100644
--- a/docs/home/quickstart.md
+++ b/docs/home/quickstart.md
@@ -13,130 +13,167 @@ description: Install socx-cli, verify the setup, and run your first commands.
 To start using SoCX CLI, follow these steps to install, verify, and run your
 first commands.
 
-## Installing SoCX CLI
+## Prerequisites
 
-???+ warning "Requirements"
+Before installing SoCX CLI, ensure you have the following:
 
-    In order to be able to use SoCX, the following requirements must be met:
+- **Python 3.12 or newer** - SoCX requires modern Python features
+- **Package manager** - Either [`uv`](https://github.com/astral-sh/uv) (recommended) or `pip`/`pipx`
+- **(Optional) Git workspace** - Access to your SoC workspace enables Git manifest and regression features with real project data
+- **(Optional) Shell access** - Script plugins require executable permissions and shell access
 
-    - [ ] Python 3.12 or newer
-    - [ ] `pip` or [`uv`](https://github.com/astral-sh/uv) for managing environments
-    - [ ] (optional) access to your SoC workspace so Git manifests and regressions have
-      real data to operate on
+## Installation
 
-??? info "Verifying Your Installation"
+Choose your preferred installation method:
 
-    Run the below commands to verify `socx` was properly installed.
+===! "uv (recommended)"
 
     ```bash title=""
-    socx --help
-    socx version
+    uv tool install socx-cli
     ```
 
-    If you see the top-level help and the current version, the CLI is ready to use.
+    This installs `socx` in an isolated environment managed by `uv`.
 
-??? info "Upgrading to the Latest Version"
+=== "pipx"
 
-    === "uv"
+    ```bash title=""
+    pipx install socx-cli
+    ```
 
-        ```bash title=""
-        uv tool update socx-cli
-        ```
+    Similar to `uv`, `pipx` installs `socx` in an isolated environment.
 
-    === "pip"
+=== "pip"
 
-        ```bash title=""
-        pip install --upgrade socx-cli
-        ```
+    ```bash title=""
+    pip install socx-cli
+    ```
 
-===! "uv"
+    !!! warning
+        Installing with `pip` may affect your global Python environment. Consider using `uv` or `pipx` instead.
 
-    ```bash title=""
-    uv tool install socx-cli
+## Verify Installation
+
+Run the following commands to verify that `socx` was installed correctly:
+
+```bash
+socx --help
+socx version
+```
+
+If you see the top-level help menu and the current version number, the CLI is ready to use.
+
+## Upgrade to Latest Version
+
+Keep your installation up to date:
+
+=== "uv"
+
+    ```bash
+    uv tool upgrade socx-cli
+    ```
+
+=== "pipx"
+
+    ```bash
+    pipx upgrade socx-cli
     ```
 
 === "pip"
 
-    ```bash title=""
-    pip install socx-cli
+    ```bash
+    pip install --upgrade socx-cli
     ```
 
-## Using the CLI
+## Basic Commands
 
-=== "Git"
+SoCX provides several built-in commands to help you get started. Here are the most commonly used commands:
 
-    Manage multiple git repositories at once using `socx git`
+### Git Management
 
-    ```bash title=""
-    # Display a manifest table of all repositories under the current path
-    socx git mfest
+Manage multiple Git repositories at once using `socx git`:
 
-    # Alternatively, display it in a one-liner format of 'ref - message, date'
-    socx git mfest -f ref
+```bash
+# Display a manifest table of all repositories under the current path
+socx git mfest
 
-    # Or in json format
-    socx git mfest -f json
+# Display in a one-liner format showing 'ref - message, date'
+socx git mfest -f ref
 
-    # You can also pass a path as argument to run it from a different path
-    socx git mfest /project/users/foo/workspace
+# Output in JSON format for scripting
+socx git mfest -f json
 
-    # Relative paths are also supported
-    socx git mfest ../../bar/bazz
-    ```
+# Scan a specific directory
+socx git mfest /project/users/foo/workspace
 
-=== "Config"
+# Relative paths are also supported
+socx git mfest ../../bar/bazz
+```
 
-    Print, edit, debug or inspect python API of configurations
+### Configuration Management
 
-    ```bash title=""
-    # Dump all configurations
-    socx config list
+View, edit, and debug configuration settings:
 
-    # Dump all configurations in a pretty tree format
-    socx config tree
+```bash
+# List all configuration values
+socx config list
 
-    # Dump a tree/value of a specific configuration
-    socx config get git.manifest.columns
+# Display configurations in a pretty tree format
+socx config tree
 
-    # Modify existing configurations interactively
-    socx config edit # will run a friendly interactive prompt
+# Get a specific configuration value
+socx config get git.manifest.columns
 
-    # Debug configuration values or check the loading order
-    socx config debug
+# Edit configurations interactively in your editor
+socx config edit
 
-    # Inspect settings methods and members (when using it as a python library)
-    socx config inspect
-    ```
+# Debug configuration loading and see override order
+socx config debug
 
-=== "Regression"
+# Inspect settings API (when using socx as a Python library)
+socx config inspect
+```
 
-    Parse and execute commands in parallel (e.g. a file of test 'run'
-    commands)
+### Regression Testing
 
-    ```bash title=""
-    socx rgr run -i ./sim/regressions/doa_commands.list # file can have any or no
-                                                        # extension
-    ```
+Run test commands in parallel:
 
-=== "Plugins"
+```bash
+# Run regression tests from a command list file
+socx rgr run -i ./sim/regressions/commands.list
 
-    Add any python script as a subcommand of `socx` through the power of
-    plugins
+# Specify custom output directory
+socx rgr run -i failed.log -o ./results
 
-    ```bash title=""
-    # add a function from a script as a subcommand (a.k.a plugin):
-    socx plugin add ./scripts/dv/generate_rals.py:main
+# Launch the interactive terminal UI
+socx rgr tui
+```
 
-    # you can also specify only a path to run the file itself (run as __main__)
-    socx plugin add ./scripts/dv/generate_rals.py
+### Plugin Management
 
-    # or specify a module path if it is installed on your system or on your active
-    # virtual environment
-    socx plugin add my.custom.package:run_test
+View plugin examples and documentation:
 
-    # show an example for using 'socx' as a library to create new scripts/plugins
-    socx plugin example
-    ```
+```bash
+# Display plugin quickstart guide
+socx plugin example
+```
+
+!!! tip
+    To add custom plugins, edit your configuration file. See the [Plugin Development](../user-guide/plugins.md) guide for details.
+
+### Global Options
+
+All commands support these global options:
+
+```bash
+# Enable debug logging
+socx --debug config list
+
+# Set logging verbosity (DEBUG, INFO, WARNING, ERROR)
+socx --verbosity DEBUG rgr run
+
+# Run without loading user/repo configuration
+socx --no-config config list
+```
 
 ## Next Steps
 
diff --git a/docs/reference/configuration.md b/docs/reference/configuration.md
new file mode 100644
index 00000000..82651989
--- /dev/null
+++ b/docs/reference/configuration.md
@@ -0,0 +1,532 @@
+---
+title: Configuration Reference
+description: Complete reference for all SoCX configuration options organized by category.
+---
+
+# Configuration Reference
+
+This page documents all available configuration options in SoCX, organized by category. All settings can be overridden via user config (`~/.config/socx/socx.yaml`), repository config (`.socx.yaml`), or environment variables.
+
+## CLI Configuration
+
+Controls command-line interface behavior and global options.
+
+```yaml
+cli:
+  # Enable debug logging (also: SOCX_CLI__DEBUG=1)
+  debug: false
+  
+  # Load user/repository configuration files
+  configure: true
+  
+  # Logging verbosity level
+  # Options: DEBUG, INFO, WARNING, ERROR, CRITICAL
+  verbosity: INFO
+  
+  # Context settings for Click commands
+  context_settings:
+    help_option_names:
+      - -h
+      - --help
+  
+  # Option panel configuration for help display
+  option-panels:
+    - name: Options
+      options:
+        - --help
+        - --configure/--no-configure
+        - --debug
+        - --verbosity
+```
+
+### Environment Variables
+
+- `SOCX_CLI__DEBUG=1` - Enable debug mode
+- `SOCX_CLI__VERBOSITY=DEBUG` - Set log level
+- `SOCX_CLI__CONFIGURE=false` - Disable config loading
+
+## Git Configuration
+
+Settings for Git repository management and manifest generation.
+
+```yaml
+git:
+  manifest:
+    # Root directory to start scanning for repositories
+    root: ~
+    
+    # Paths to include (glob patterns supported)
+    includes: []
+    
+    # Paths to exclude (glob patterns supported)
+    excludes: []
+    
+    # Reference mapping for specific repositories
+    references: {}
+  
+  log:
+    # Git log command flags
+    flags:
+      - --graph
+      - --branches
+      - --abbrev-commit
+      - --date=relative
+      - --decorate=full
+      - --max-count=12
+      - "--pretty=format: %C(red)%h%C(reset) %<(72,trunc)%s %C(bold blue)[%an]%C(reset) %C(yellow)%d%C(reset)%n"
+  
+  pull:
+    # Git pull command flags
+    flags:
+      - --tags
+      - --no-edit
+      - --autostash
+  
+  diff:
+    # Git diff command flags
+    flags:
+      - -M
+      - -C
+      - -B
+      - --ignore-blank-lines
+      - --default-prefix
+  
+  status:
+    # Git status command flags
+    flags:
+      - --short
+      - --branch
+      - --renames
+      - --ahead-behind
+  
+  summary:
+    # Output format: table, json, ref
+    format: table
+    
+    # Table styling
+    style:
+      headers: ~
+    
+    table:
+      # Box style for table borders
+      box: ROUNDED
+      title: ~
+      caption: ~
+      expand: true
+      highlight: true
+      show_lines: true
+      show_header: true
+      show_footer: false
+    
+    # Columns to display in manifest table
+    columns:
+      - name: Repository
+        func: socx_plugins.git.utils:get_repo_name
+        style: bright_blue
+      
+      - name: "[green]Ahead[/] [red]Behind[/]"
+        func: socx_plugins.git.utils:get_ahead_behind
+        style: ~
+      
+      - name: Branch / Tag
+        func: socx_plugins.git.utils:get_ref_name
+        style: yellow
+      
+      - name: Commit Hash
+        func: socx_plugins.git.utils:get_commit_hash
+        style: red
+      
+      - name: Commit Message
+        func: socx_plugins.git.utils:get_commit_message
+        style: white
+      
+      - name: Author Name
+        func: socx_plugins.git.utils:get_author_name
+        style: cyan
+      
+      - name: Author Date
+        func: socx_plugins.git.utils:get_author_date
+        style: cyan
+```
+
+### Environment Variables
+
+- `SOCX_GIT__MANIFEST__ROOT=~/workspace` - Set manifest root
+- `SOCX_GIT__SUMMARY__FORMAT=json` - Set output format
+
+## Regression Configuration
+
+Settings for parallel test execution and regression automation.
+
+```yaml
+regression:
+  # Working directory for regression operations
+  path: ~
+  
+  # Custom test wrapper class (advanced)
+  # Must inherit from socx.regression.test:Test
+  test_cls: "socx.regression.test:Test"
+  
+  # Maximum number of tests to run concurrently
+  # Default: 10
+  max_runs_in_parallel: 10
+  
+  run:
+    input:
+      # Default input filename
+      filename: small
+      
+      # Directory containing test command files
+      # Supports @path and @format directives
+      directory: "@path @format ./assets/rgr/inputs"
+    
+    output:
+      # Directory for result logs (timestamped subdirs created automatically)
+      # Supports @path directive
+      directory: "@path workrun/regression"
+```
+
+### Environment Variables
+
+- `SOCX_REGRESSION__MAX_RUNS_IN_PARALLEL=20` - Set parallelism
+- `SOCX_REGRESSION__RUN__INPUT__FILENAME=failed.log` - Set input file
+- `SOCX_REGRESSION__RUN__OUTPUT__DIRECTORY=/tmp/results` - Set output directory
+
+### Parallel Execution Tuning
+
+| Scenario | Recommended Value |
+|----------|-------------------|
+| CPU-bound tests | Number of CPU cores (4-8) |
+| I/O-bound tests | 2-3x CPU cores (16-24) |
+| Memory-intensive tests | Conservative (5-10) |
+| Quick unit tests | Aggressive (30-50) |
+| CI/CD environment | Moderate (10-20) |
+
+## Plugin Configuration
+
+Plugin metadata and registration settings.
+
+```yaml
+plugins:
+  # Built-in git plugin
+  - name: git
+    panel: Commands
+    help: Various common git command utilities to manage your environment.
+    command: "socx_plugins.git:cli"
+    enabled: true
+    aliases: []
+  
+  # Built-in regression plugin
+  - name: rgr
+    panel: Commands
+    help: Perform various regression related actions.
+    command: "socx_plugins.rgr:cli"
+    enabled: true
+    aliases: []
+  
+  # Built-in plugin management
+  - name: plugin
+    help: Add, create, inspect, and manage extension plugins.
+    panel: Commands
+    command: "socx_plugins.plugin:cli"
+    enabled: true
+    aliases: []
+  
+  # Built-in config management
+  - name: config
+    help: Get, set, list, or modify settings configuration values.
+    panel: Commands
+    command: "socx_plugins.config:cli"
+    enabled: true
+    aliases: []
+  
+  # Built-in convert plugin
+  - name: convert
+    help: Perform a conversion based on current configurations.
+    panel: Commands
+    command: "socx_plugins.convert:cli"
+    enabled: true
+    aliases: []
+  
+  # Built-in version plugin
+  - name: version
+    help: Print version information and exit.
+    panel: Commands
+    command: "socx_plugins.version:version"
+    enabled: true
+    aliases: []
+```
+
+### Plugin Field Reference
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `name` | string | Yes | Command name (what users type) |
+| `command` | string | No* | Python import path (e.g., `module:function`) |
+| `script` | string | No* | Executable script path |
+| `help` | string | No | Short description for help output |
+| `panel` | string | No | Group name in help display (default: "Commands") |
+| `enabled` | boolean | No | Enable/disable plugin (default: true) |
+| `aliases` | list | No | Alternative command names |
+
+\* Either `command` or `script` must be provided, but not both.
+
+### Adding Custom Plugins
+
+#### Python Plugin Example
+
+```yaml
+plugins:
+  - name: my-tool
+    command: "my_package.tools:cli"
+    help: "Custom development tool"
+    panel: "Custom Tools"
+    enabled: true
+```
+
+#### Script Plugin Example
+
+```yaml
+plugins:
+  - name: build
+    script: "./scripts/build.sh"
+    help: "Build the project"
+    enabled: true
+```
+
+## Convert Configuration
+
+Settings for file conversion operations (e.g., LST to SystemVerilog).
+
+```yaml
+convert:
+  lst:
+    # Converter class (advanced)
+    # Supports @symbol directive for dynamic imports
+    cls: "@symbol socx_plugins.convert.converter:LstConverter"
+    
+    # Source directory for input files
+    # Supports @path and @jinja directives
+    source: "@path @jinja <template expression>"
+    
+    # Target directory for output files
+    # Supports @path and @jinja directives
+    target: "@path @jinja <template expression>"
+    
+    # Base address map JSON file
+    base_addr_map: "memLd.json"
+    
+    # Numeric base for addresses (16=hex, 10=decimal, 8=octal)
+    base_addr_base: 16
+    
+    # File patterns to include
+    includes:
+      - "*.lst"
+      - SPUList.list
+    
+    # File patterns to exclude
+    excludes: []
+    
+    # Input to output filename mappings
+    # % is a wildcard match character
+    mappings:
+      - input: "%.lst"
+        output: "%.svh"
+      - input: "%.list"
+        output: "%.sv"
+      - input: hwsList.lst
+        output: pixie_hws_cgs.svh
+    
+    # Options for path/file handling
+    options:
+      # How to handle existing output files
+      # Options: skip, backup, overwrite
+      collision: "overwrite"
+```
+
+### Environment Variables
+
+- `SOCX_CONVERT__LST__SOURCE=/path/to/inputs` - Set source directory
+- `SOCX_CONVERT__LST__TARGET=/path/to/outputs` - Set output directory
+
+## Rich Click UI Configuration
+
+Settings for terminal UI appearance and behavior.
+
+```yaml
+rich_click:
+  # UI theme (affects colors and styling)
+  THEME: cargo-modern
+  
+  # Enable markdown formatting in help text
+  TEXT_MARKUP: markdown
+  
+  # Show commands before options in help
+  COMMANDS_BEFORE_OPTIONS: false
+  
+  # Footer text displayed in help
+  FOOTER_TEXT: >-
+    Documentation is available at <https://sagikimhi.github.io/socx-cli>
+  
+  # Error suggestion text
+  ERRORS_SUGGESTION: |
+    Try running with '-h' or '--help' for more information.
+  
+  # Error epilogue with link
+  ERRORS_EPILOGUE: >-
+    Documentation is available at [link]https://sagikimhi.github.io/socx-cli[/link]
+```
+
+## Language Configuration
+
+Language-specific settings for file conversion and processing.
+
+```yaml
+lang:
+  systemverilog:
+    name: "systemverilog"
+    extensions:
+      - .sv
+      - .svh
+    syntax:
+      indent: 4
+      comments:
+        line: "//"
+        block:
+          begin: "/*"
+          end: "*/"
+  
+  lst:
+    name: "lst"
+    extensions:
+      - ".lst"
+      - ".list"
+    syntax:
+      indent: 4
+      comments:
+        line: "//"
+        block:
+          begin: "/*"
+          end: "*/"
+    # Token processing rules (advanced - see source for details)
+    tokens:
+      - name: "comment"
+        starts_scope: false
+        expr: '<regex pattern>'
+        subst: '<substitution template>'
+      
+      - name: "group"  
+        starts_scope: true
+        expr: '<regex pattern>'
+        subst: '<substitution template>'
+        scope_ender: '<scope closing template>'
+      
+      - name: "statement"
+        starts_scope: false
+        expr: '<regex pattern>'
+        subst: '<substitution template>'
+```
+
+## Configuration Directives
+
+SoCX uses special directives to process configuration values dynamically.
+
+### Available Directives
+
+| Directive | Purpose | Example |
+|-----------|---------|---------|
+| `@path` | Convert to Path object | `@path ~/workspace` |
+| `@symbol` | Import Python symbol | `@symbol module.path:function` |
+| `@command` | Convert to Click command | `@command module:cli` |
+| `@compile` | Compile Python source | `@compile script.py` |
+| `@jinja` | Process Jinja2 template | `@jinja {% raw %}{{ var | filter }}{% endraw %}` |
+| `@format` | Format string substitution | `@format ./path/{var}` |
+
+### Jinja2 Templates
+
+Some values support Jinja2 templating:
+
+```yaml
+custom:
+  path: "@jinja {% raw %}{{ this.paths.APP_ROOT_DIR / 'custom' | abspath }}{% endraw %}"
+  name: "@jinja {% raw %}{{ env.USER }}{% endraw %}_workspace"
+```
+
+Available variables:
+
+- `this` - Current configuration object
+- `env` - Environment variables
+- Built-in Jinja2 filters (e.g., `abspath`, `basename`)
+
+## Configuration Best Practices
+
+### 1. Use Appropriate Levels
+
+```yaml
+# Package defaults - Don't modify (edit user/repo config instead)
+# Location: src/socx/static/settings/*.yaml
+
+# User config - Personal preferences
+# Location: ~/.config/socx/socx.yaml
+cli:
+  verbosity: DEBUG
+
+# Repository config - Team settings
+# Location: .socx.yaml (commit to version control)
+regression:
+  max_runs_in_parallel: 20
+  run:
+    input:
+      directory: ${PROJECT_ROOT}/ci/logs
+```
+
+### 2. Environment Variables for CI
+
+```bash
+# In CI/CD pipeline
+export SOCX_REGRESSION__MAX_RUNS_IN_PARALLEL=50
+export SOCX_REGRESSION__RUN__OUTPUT__DIRECTORY=/tmp/results
+socx rgr run
+```
+
+### 3. Use Variable Substitution
+
+```yaml
+regression:
+  run:
+    input:
+      directory: ${PROJECT_ROOT}/logs
+      filename: ${BUILD_TAG:-default}.log
+```
+
+### 4. Document Your Overrides
+
+```yaml
+regression:
+  # Increased for powerful CI machines with 32 cores
+  max_runs_in_parallel: 30
+  
+  run:
+    output:
+      # Results must go to /shared for archiving
+      directory: /shared/regression-results
+```
+
+### 5. Test Configuration Changes
+
+```bash
+# Verify configuration loads correctly
+socx config tree
+
+# Test specific setting
+socx config get regression.max_runs_in_parallel
+
+# Debug loading order
+socx config debug
+```
+
+## See Also
+
+- [Configuration Guide](../user-guide/configuration.md) - How to use configuration
+- [Plugin Development](../user-guide/plugins.md) - Creating custom plugins
+- [Regression Guide](../user-guide/regression.md) - Running tests in parallel
diff --git a/docs/user-guide/configuration.md b/docs/user-guide/configuration.md
index 7cccbca3..7ff6044a 100644
--- a/docs/user-guide/configuration.md
+++ b/docs/user-guide/configuration.md
@@ -3,98 +3,301 @@ title: Configuration
 description: Understand how Dynaconf settings drive socx-cli and how to override them.
 ---
 
-SoCX layers configuration with [Dynaconf](https://www.dynaconf.com/). Every
-command reads from the merged settings object which combines defaults, user
-preferences, repository overrides, and environment variables.
+# Configuration
+
+SoCX uses [Dynaconf](https://www.dynaconf.com/) for flexible, layered configuration management. Every command reads from a merged settings object that combines defaults, user preferences, repository overrides, and environment variables.
 
 ## Configuration Sources
 
-1. **Package defaults** live under `src/socx/static/settings/` and ship with the
-   wheel. These cover core plugin registrations and sensible regression paths.
-2. **User configuration** resides at `~/.config/socx/socx.yaml`. SoCX creates the
-   file lazily when you save changes via `socx config edit`.
-3. **Repository overrides** are discovered by walking up from the current
-   working directory until a `.socx.yaml` file is found.
-4. **Environment variables** prefixed with `SOCX_` take the highest precedence
-   (e.g. `SOCX_REGRESSION__RUN__INPUT__FILENAME` overrides the input file).
+Configuration is loaded from multiple sources with a clear precedence hierarchy:
+
+### 1. Package Defaults (Lowest Priority)
+
+Located in `src/socx/static/settings/` and shipped with the package. These include:
+
+- `settings.yaml` - Main configuration loader
+- `plugins.yaml` - Built-in plugin registrations
+- `cli.yaml` - CLI behavior and global options
+- `git.yaml` - Git manifest and command defaults
+- `regression.yaml` - Regression runner configuration
+- `convert.yaml` - File conversion settings
+- `rich_click.yaml` - UI theme and formatting
+
+### 2. User Configuration
+
+Located at `~/.config/socx/socx.yaml` (or `$XDG_CONFIG_HOME/socx/socx.yaml`).
+
+- Created lazily when you run `socx config edit`
+- Persists across all projects for this user
+- Good for personal preferences and common overrides
+
+### 3. Repository Configuration
+
+Found by walking up from the current directory until a `.socx.yaml` file is found.
+
+- Project-specific settings
+- Shared across all team members via version control
+- Overrides user configuration for this project
+
+### 4. Environment Variables (Highest Priority)
+
+Prefixed with `SOCX_` and using double underscores for nesting.
+
+- Takes precedence over all file-based configuration
+- Useful for CI/CD or temporary overrides
+- Example: `SOCX_REGRESSION__RUN__INPUT__FILENAME=failed.log`
+
+### Variable Interpolation
+
+YAML files support `${ENVVAR}` style substitutions:
+
+```yaml
+regression:
+  run:
+    output:
+      directory: ${PROJECT_ROOT}/results
+```
 
-`${ENVVAR}` style substitutions are also supported inside YAML files because
 Dynaconf performs environment interpolation before values reach the CLI.
 
-## Inspecting Settings
+## Inspecting Configuration
+
+Use the built-in `config` commands to understand what settings are active:
+
+```bash
+# Display all settings in a visual tree format
+socx config tree
+
+# List all settings as key/value pairs (good for scripting)
+socx config list
+
+# Get a specific configuration value or branch
+socx config get cli.verbosity
+socx config get regression.run
+
+# Debug configuration loading order and sources
+socx config debug
+
+# Inspect the settings API (for Python library usage)
+socx config inspect
+```
+
+### Troubleshooting
+
+To test with only package defaults (ignore user/repo config):
+
+```bash
+socx --no-config config tree
+socx --no-config rgr run
+```
 
-Use the configuration plugin to understand what the CLI will use at runtime:
+This is useful when debugging unexpected behavior from configuration overrides.
+
+## Editing Configuration
+
+### User Configuration
+
+Open your user configuration file:
 
 ```bash
-socx config tree     # pretty Rich tree of the merged settings
-socx config list     # plain key/value list for scripting
-socx config get log  # focus on a single branch
-socx config debug    # show loader diagnostics and override order
+socx config edit
 ```
 
-Add `--no-config` to any command to temporarily ignore user and repo overrides
-if you need to troubleshoot default behaviour.
+This opens `~/.config/socx/socx.yaml` in your `$EDITOR` (falls back to `nano`, `vim`, or `gvim`).
 
-## Editing Settings
+Example user configuration:
 
-`socx config edit` opens the user configuration file in your `$EDITOR` (falls
-back to `nano`, `vim`, or `gvim`). Save an empty file to keep the defaults but
-retain the path for later edits.
+```yaml title="~/.config/socx/socx.yaml"
+cli:
+  verbosity: DEBUG
+  debug: true
 
-To provide repository-specific values, place a `.socx.yaml` file at the root of
-your project:
+plugins:
+  - name: my-tool
+    command: "my_scripts.tool:cli"
+    help: "My personal development tool"
+    enabled: true
+```
+
+### Repository Configuration
+
+Create a `.socx.yaml` file at the root of your project:
 
 ```yaml title=".socx.yaml"
 regression:
   run:
     input:
       directory: ${PROJECT_ROOT}/ci/failures
-      filename: last-run.log
+      filename: failed-tests.log
     output:
       directory: ${PROJECT_ROOT}/ci/results
-    filters:
-      tags:
-        - smoke
-        - nightly
+  max_runs_in_parallel: 20
+
+git:
+  manifest:
+    root: ${PROJECT_ROOT}/repos
+    excludes:
+      - "*/temp/*"
+      - "*/build/*"
 ```
 
-The example uses environment substitution so you can export `PROJECT_ROOT`
-before running the CLI:
+Commit this file to version control so the entire team uses the same settings.
+
+### Environment Variables
+
+For temporary or CI-specific overrides:
 
 ```bash
-export PROJECT_ROOT=$PWD
+# Enable debug mode
+export SOCX_DEBUG=1
+
+# Override regression input file
+export SOCX_REGRESSION__RUN__INPUT__FILENAME=failed.log
+
+# Set parallel execution limit
+export SOCX_REGRESSION__MAX_RUNS_IN_PARALLEL=50
+
 socx rgr run
 ```
 
-## Environment Variable Cheatsheet
+## Common Configuration Tasks
 
-Dynaconf converts nested keys to uppercase names separated with double
-underscores. Some useful overrides:
+### Modify CLI Behavior
 
-| Purpose | Environment variable |
-| --- | --- |
-| Toggle debug logging | `SOCX_DEBUG=1` |
-| Set logging verbosity | `SOCX_VERBOSITY=DEBUG` |
-| Change regression input filename | `SOCX_REGRESSION__RUN__INPUT__FILENAME=failed.log` |
-| Redirect regression output directory | `SOCX_REGRESSION__RUN__OUTPUT__DIRECTORY=/tmp/socx` |
-| Swap the LST converter implementation | `SOCX_CONVERT__LST__CLS=my_pkg.tools:CustomConverter` |
+Control debug logging and output verbosity:
 
-## Configuration for Plugins
+```yaml
+cli:
+  debug: true              # Enable debug logging
+  verbosity: DEBUG         # Set log level (DEBUG, INFO, WARNING, ERROR)
+  configure: true          # Load user/repo configuration
+```
 
-Plugin metadata lives under the `plugins` key. Each plugin entry contains the
-name exposed on the CLI, the `command` import path, and optional help text or
-aliases. Disable a plugin by setting `enabled: false`.
+Or via environment:
 
-```yaml title="~/.config/socx/socx.yaml"
+```bash
+SOCX_DEBUG=1 socx config tree
+SOCX_VERBOSITY=DEBUG socx rgr run
+```
+
+### Configure Git Manifest
+
+Customize Git repository scanning:
+
+```yaml
+git:
+  manifest:
+    root: ~/workspace           # Root directory to scan
+    excludes:
+      - "*/build/*"             # Skip build directories
+      - "*/.cache/*"            # Skip cache directories
+    includes:
+      - "*/repos/*"             # Only scan specific paths
+    
+  summary:
+    format: table               # Output format (table, json, ref)
+```
+
+### Adjust Regression Settings
+
+Control parallel test execution:
+
+```yaml
+regression:
+  max_runs_in_parallel: 20      # Number of concurrent tests
+  run:
+    input:
+      directory: ./sim/logs     # Where to find test lists
+      filename: failed.log      # Default input file
+    output:
+      directory: ./results      # Where to save results
+```
+
+### Manage Plugins
+
+Add or configure plugins:
+
+```yaml
 plugins:
+  # Enable a built-in plugin with custom settings
   - name: rgr
     command: "socx_plugins.rgr:cli"
-    help: "Regression tooling"
     enabled: true
-  - name: dashboards
-    command: "my_project.dashboards:cli"
-    enabled: ${ENABLE_DASHBOARDS:true}
+    
+  # Add custom Python plugin
+  - name: custom-tool
+    command: "my_project.tools:cli"
+    help: "Custom project tool"
+    panel: "Project Tools"
+    enabled: ${ENABLE_CUSTOM_TOOL:true}
+    
+  # Add script plugin
+  - name: build-hw
+    script: "./scripts/build.sh"
+    help: "Build hardware"
+    enabled: true
+```
+
+## Environment Variable Reference
+
+Dynaconf converts nested keys to uppercase with double underscores:
+
+| Configuration Path | Environment Variable | Example Value |
+|--------------------|---------------------|---------------|
+| `cli.debug` | `SOCX_CLI__DEBUG` | `1` or `true` |
+| `cli.verbosity` | `SOCX_CLI__VERBOSITY` | `DEBUG` |
+| `regression.max_runs_in_parallel` | `SOCX_REGRESSION__MAX_RUNS_IN_PARALLEL` | `20` |
+| `regression.run.input.filename` | `SOCX_REGRESSION__RUN__INPUT__FILENAME` | `failed.log` |
+| `regression.run.output.directory` | `SOCX_REGRESSION__RUN__OUTPUT__DIRECTORY` | `/tmp/results` |
+| `git.manifest.root` | `SOCX_GIT__MANIFEST__ROOT` | `~/workspace` |
+| `convert.lst.cls` | `SOCX_CONVERT__LST__CLS` | `my_pkg:Converter` |
+
+## Advanced Topics
+
+### Dynamic Values with Jinja2
+
+Some configuration values support Jinja2 templating for dynamic content:
+
+```yaml
+convert:
+  lst:
+    source: "{% raw %}{{ this.paths.APP_ROOT_DIR / 'assets/inputs' | abspath }}{% endraw %}"
+    target: "{% raw %}{{ this.paths.APP_ROOT_DIR / 'outputs' | abspath }}{% endraw %}"
+```
+
+### Custom Converters
+
+SoCX uses Dynaconf converters to transform configuration values. Available converters:
+
+- `@path` - Convert strings to `Path` objects
+- `@symbol` - Import Python symbols from dotted paths
+- `@compile` - Compile Python source files
+- `@command` - Convert to Click commands
+- `@jinja` - Process Jinja2 templates
+
+Example:
+
+```yaml
+custom:
+  script_path: "@path /home/user/scripts"
+  handler: "@symbol my_module.tools:handler"
+  command_tool: "@command my_package.cli:main"
 ```
 
-Changes take effect the next time you run the CLI—there is no background daemon
-to restart.
+### Configuration Validation
+
+SoCX validates configuration against Pydantic models. Invalid configuration will produce clear error messages:
+
+```bash
+$ socx config tree
+Error: Invalid configuration for 'plugins[0].name': must match pattern \w+
+```
+
+### Best Practices
+
+1. **Keep defaults in package** - Don't override unless necessary
+2. **Use repository config for team settings** - Commit `.socx.yaml` to version control
+3. **Use user config for personal preferences** - Keep local workflow customizations
+4. **Use environment variables for CI** - Temporary overrides without file changes
+5. **Document your overrides** - Add comments explaining non-obvious settings
+6. **Test with `--no-config`** - Verify behavior without your overrides
diff --git a/docs/user-guide/plugins.md b/docs/user-guide/plugins.md
index 7d72b504..789ce4ef 100644
--- a/docs/user-guide/plugins.md
+++ b/docs/user-guide/plugins.md
@@ -3,10 +3,44 @@ title: Plugin Development
 description: Extend socx-cli with your own commands and share them across teams.
 ---
 
+# Plugin Development
+
 Every subcommand that appears under `socx` comes from an entry in the
-`settings.plugins` list. Adding your own plugin is as simple as shipping a
-callable that returns a [`click.Command`](https://click.palletsprojects.com/) or
-`click.Group`, then referencing it in configuration.
+`settings.plugins` list. SoCX supports two types of plugins: **Python plugins** and **script plugins**, each with different capabilities and use cases.
+
+## Plugin Types
+
+### Python Plugins
+
+Python plugins are Click commands defined in Python modules that run **in-process** within the SoCX runtime. They have full access to:
+
+- The entire SoCX configuration via `from socx import settings`
+- All SoCX utilities and helper functions
+- The global and local namespace of the SoCX CLI
+- Runtime configuration values and state
+
+**Best for:**
+
+- Commands that need to access SoCX configuration
+- Tools that integrate deeply with SoCX features
+- Commands that benefit from Python's rich ecosystem
+- Plugins that need to be fast (no subprocess overhead)
+
+### Script Plugins
+
+Script plugins are executable scripts that run **as subprocesses** using the `sh` library. They:
+
+- Execute in a separate process with their own environment
+- Do **not** have direct access to SoCX internal state
+- Can be any executable script (shell, Python, Ruby, etc.)
+- Receive arguments from the command line
+
+**Best for:**
+
+- Wrapping existing shell scripts or binaries
+- Commands that need complete process isolation
+- Tools written in languages other than Python
+- Legacy scripts you want to integrate without modification
 
 ## Anatomy of a Plugin Entry
 
@@ -18,49 +52,173 @@ plugins:
     enabled: true
 ```
 
-- `name` – the word users type after `socx`.
-- `command` – dotted import path to the callable that returns a Click command or
-  group.
-- `help` – optional description shown in `socx --help`.
-- `enabled` – disable the plugin without deleting its metadata.
-- `aliases` – extra command names (see `plugins.yaml` in the sources for
-  examples).
+### Plugin Fields
 
-## Creating a Plugin
+- `name` – The command name users type after `socx` (e.g., `socx git`)
+- `command` – Dotted import path to a Click command or group (Python plugins)
+- `script` – Path to an executable script (script plugins)
+- `help` – Optional description shown in `socx --help`
+- `enabled` – Set to `false` to disable without deleting the entry
+- `panel` – Group name for organizing commands in help output
+- `aliases` – Additional command names for the same plugin
 
-1. Author a Click command or group. The example below prints "hello" and the
-   current user.
+!!! note
+    Use either `command` for Python plugins **or** `script` for script plugins, not both.
 
-    ```python title="my_plugins/hello.py"
-    import click
-    import getpass
+## Creating a Python Plugin
 
+Python plugins provide deep integration with SoCX. Here's how to create one:
 
-    @click.command()
-    @click.option("--name", default=None, help="Override the user name")
-    def cli(name: str | None) -> None:
-        """Say hello from a plugin."""
-        who = name or getpass.getuser()
-        click.echo(f"Hello {who}!")
-    ```
+### Step 1: Write a Click Command
 
-2. Expose it in your configuration:
+Create a Python file with a Click command or group:
 
-    ```yaml title="~/.config/socx/socx.yaml"
-    plugins:
-      - name: hello
-        command: "my_plugins.hello:cli"
-        help: "Demo plugin that prints a friendly greeting."
-        enabled: true
-    ```
+```python title="my_plugins/hello.py"
+import click
+import getpass
+from socx import settings  # Access to SoCX configuration
 
-3. Run `socx --help` to confirm the new command appears, then execute `socx
-   hello`.
 
-!!! note
-    The built-in `socx plugin example` command prints a Markdown guide inside the
-    terminal. It expands on these steps and walks through distributing plugins as
-    Python packages.
+@click.command()
+@click.option("--name", default=None, help="Override the user name")
+@click.option("--show-config", is_flag=True, help="Show current verbosity setting")
+def cli(name: str | None, show_config: bool) -> None:
+    """Say hello from a plugin with access to SoCX configuration."""
+    who = name or getpass.getuser()
+    click.echo(f"Hello {who}!")
+    
+    if show_config:
+        # Access SoCX configuration directly
+        click.echo(f"Current log level: {settings.cli.verbosity}")
+```
+
+### Step 2: Register in Configuration
+
+Add the plugin to your configuration file:
+
+```yaml title="~/.config/socx/socx.yaml"
+plugins:
+  - name: hello
+    command: "my_plugins.hello:cli"
+    help: "Demo plugin that prints a friendly greeting."
+    panel: "Custom Commands"
+    enabled: true
+```
+
+### Step 3: Verify and Use
+
+Run `socx --help` to confirm the new command appears, then execute:
+
+```bash
+socx hello
+socx hello --name Alice
+socx hello --show-config
+```
+
+### Using Module Paths
+
+You can reference any importable module:
+
+```yaml
+plugins:
+  # Local file (must be in Python path)
+  - name: local-tool
+    command: "scripts.tools:run"
+    
+  # Installed package
+  - name: company-tool
+    command: "company_toolkit.socx_plugin:cli"
+    
+  # Direct file path with function
+  - name: script-tool
+    command: "/path/to/script.py:main"
+```
+
+## Creating a Script Plugin
+
+Script plugins allow you to integrate any executable as a SoCX command:
+
+### Step 1: Create an Executable Script
+
+```bash title="scripts/deploy.sh"
+#!/bin/bash
+# Simple deployment script
+
+echo "Deploying with args: $@"
+
+if [ "$1" = "--help" ]; then
+    echo "Usage: socx deploy [options]"
+    echo "Options:"
+    echo "  --target TARGET    Deployment target"
+    echo "  --dry-run          Don't actually deploy"
+    exit 0
+fi
+
+# Your deployment logic here
+echo "Deployment complete!"
+```
+
+Make it executable:
+
+```bash
+chmod +x scripts/deploy.sh
+```
+
+### Step 2: Register as Script Plugin
+
+```yaml title=".socx.yaml"
+plugins:
+  - name: deploy
+    script: "./scripts/deploy.sh"
+    help: "Deploy the current build"
+    enabled: true
+```
+
+### Step 3: Use the Plugin
+
+```bash
+socx deploy --target production
+socx deploy --help
+```
+
+### Script Plugin Examples
+
+Script plugins work with any executable:
+
+```yaml
+plugins:
+  # Shell script
+  - name: build
+    script: "./scripts/build.sh"
+    help: "Build the project"
+    
+  # Python script (executed as subprocess)
+  - name: analyze
+    script: "/usr/local/bin/analyze-tool"
+    help: "Run static analysis"
+    
+  # Any binary
+  - name: external-tool
+    script: "tool-binary"
+    help: "Wrapper for external tool"
+```
+
+!!! warning "Script vs Python Execution"
+    Even if your script is a Python file, using the `script` field runs it as a subprocess. Use `command` if you need access to SoCX internals.
+
+## Key Differences Summary
+
+| Feature | Python Plugin | Script Plugin |
+|---------|---------------|---------------|
+| Execution | In-process | Subprocess |
+| Configuration Access | Full access via `settings` | No direct access |
+| Performance | Fast (no process overhead) | Slower (process spawn) |
+| SoCX Utilities | Available | Not available |
+| Language | Python only | Any executable |
+| Typical Use | Deep SoCX integration | Wrapping existing tools |
+
+!!! tip
+    Use Python plugins when you need SoCX integration, script plugins when wrapping existing executables.
 
 ## Packaging and Distribution
 
diff --git a/docs/user-guide/regression.md b/docs/user-guide/regression.md
index 5e72e982..d8c72800 100644
--- a/docs/user-guide/regression.md
+++ b/docs/user-guide/regression.md
@@ -3,98 +3,331 @@ title: Regression Automation
 description: Learn how socx-cli replays failure logs, records results, and exposes a terminal UI.
 ---
 
-The regression rerun plugin (`socx rgr`) is designed to take the text files your
-simulations or tests produce and feed them back into your execution pipeline. It
-pairs a non-interactive CLI with a Textual-powered terminal UI (TUI).
+# Regression Automation
+
+The regression plugin (`socx rgr`) automates re-running test commands from log files. It executes commands in parallel using `uvloop` for high performance and provides both a CLI and a terminal UI (TUI) for monitoring progress.
+
+## Overview
+
+SoCX regression automation is designed to:
+
+- Parse plain text files containing test commands
+- Execute commands in parallel with configurable concurrency
+- Track pass/fail outcomes for each test
+- Generate timestamped result logs
+- Provide real-time feedback via terminal UI
 
 ## Command File Format
 
-The CLI expects a plain text file where each line is an executable command. The
-`Regression` model inside SoCX parses the file and tracks pass/fail outcomes for
-each line.
+The CLI expects a **plain text file** where each line is an executable command:
 
 ```text title="failed.log"
-vcs -full64 +acc +cover top.tb
-python tools/run_smoke.py --seed 4142
-make -C ips/pci build
+vcs -full64 +acc +cover top.tb +seed=1234
+python tools/run_smoke.py --seed 4142 --config=debug
+make -C ips/pci build && make test
+./run_test.sh test_case_42
 ```
 
-The default location of the failure log is controlled via configuration under
-`regression.run.input`. The CLI resolves the path in this order:
+### File Format Rules
+
+- One command per line
+- Empty lines are ignored
+- No special formatting required
+- Commands are executed as shell commands
+- Exit code determines pass/fail status
+
+### Input File Location
 
-1. `--input /path/to/file`
-2. `SOCX_REGRESSION__RUN__INPUT__FILENAME`
-3. Configured `regression.run.input.directory` + `filename`
+SoCX resolves the input file in this order (highest priority first):
+
+1. **Command line**: `socx rgr run --input /path/to/file`
+2. **Environment variable**: `SOCX_REGRESSION__RUN__INPUT__FILENAME`
+3. **Configuration**: `regression.run.input.directory` + `regression.run.input.filename`
+
+Default configuration:
+
+```yaml
+regression:
+  run:
+    input:
+      directory: ./assets/rgr/inputs
+      filename: small
+```
 
 ## Running Regressions
 
+### Basic Usage
+
+Run a regression with the default configuration:
+
+```bash
+socx rgr run
+```
+
+### Command Options
+
+View all available options:
+
 ```bash
 socx rgr run --help
 ```
 
-Important options:
+Key options:
+
+- `--input / -i FILE` – Specify input file path
+- `--output / -o DIRECTORY` – Set output directory for results
+
+### Examples
+
+```bash
+# Run with specific input file
+socx rgr run -i ci/failures/failed.log
+
+# Custom output directory
+socx rgr run -o ci/results
+
+# Both custom input and output
+socx rgr run -i failed.log -o ./results
+```
+
+### Execution Process
+
+When you run `socx rgr run`, the following happens:
+
+1. **Load** - Input file is parsed into a `Regression` model
+2. **Wrap** - Each command is wrapped in a `Test` object to track state
+3. **Execute** - Commands run asynchronously using `uvloop` for parallelism
+4. **Monitor** - Progress is tracked and displayed in real-time
+5. **Save** - Results are written to timestamped output files
+
+### Output Files
+
+Two files are generated per run:
 
-- `--input / -i FILE` – read a specific failure log instead of the configured
-  default.
-- `--output / -o DIRECTORY` – persist pass/fail command logs to a custom
-  directory. SoCX appends a timestamped suffix so multiple runs can coexist.
+- `<timestamp>_passed.log` - Commands that completed successfully (exit code 0)
+- `<timestamp>_failed.log` - Commands that failed (non-zero exit code)
+
+Files are written atomically so they can be safely consumed by other tools, dashboards, or log processors.
+
+## Parallel Execution
+
+### Configuring Parallelism
+
+Control the number of concurrent test executions:
+
+```yaml title=".socx.yaml"
+regression:
+  max_runs_in_parallel: 20  # Default: 10
+```
 
-Example:
+Or via environment variable:
 
 ```bash
-socx rgr run -i ci/failures/failed.log -o ci/results
+SOCX_REGRESSION__MAX_RUNS_IN_PARALLEL=30 socx rgr run
 ```
 
-Behind the scenes the CLI:
+### Parallel Execution Behavior
+
+- Commands are executed concurrently up to the `max_runs_in_parallel` limit
+- Each command runs in its own subprocess
+- Commands are independent - no execution order dependencies
+- Failed commands don't affect other running commands
+- Results are collected asynchronously
 
-1. Loads the failure log into a `Regression` model (with typed `PixieTest`
-   wrappers around each command).
-2. Runs the regression asynchronously with `uvloop` so commands can execute in
-   parallel according to their definition.
-3. Writes two files, `<timestamp>_passed.log` and `<timestamp>_failed.log`, using
-   atomic writes so dashboards or log shippers can consume the results.
+### Performance Tuning
 
-## Using the Terminal UI
+Choose the right parallelism level:
+
+```bash
+# Conservative (good for resource-intensive tests)
+socx rgr run  # Uses default: 10
 
+# Moderate (balanced)
+SOCX_REGRESSION__MAX_RUNS_IN_PARALLEL=20 socx rgr run
+
+# Aggressive (for fast tests on powerful machines)
+SOCX_REGRESSION__MAX_RUNS_IN_PARALLEL=50 socx rgr run
 ```
+
+!!! tip "Tuning Guidelines"
+    - **CPU-bound tests**: Set to number of CPU cores
+    - **I/O-bound tests**: Can exceed CPU cores (2-3x)
+    - **Memory-intensive tests**: Reduce to avoid OOM
+    - **Quick tests**: Higher parallelism for faster completion
+
+## Terminal UI (TUI)
+
+### Launching the TUI
+
+```bash
 socx rgr tui
 ```
 
-The TUI provides a live view of command execution, progress bars, and quick
-links to failures. It uses the same configuration as the CLI, so you can switch
-between them without reconfiguring paths.
+The TUI provides:
+
+- **Live view** of command execution
+- **Progress bars** showing completion status
+- **Real-time updates** as tests complete
+- **Quick links** to failed tests
+- **Interactive controls** for managing runs
+
+### TUI Features
+
+The terminal UI uses the same configuration as the CLI, so you can switch between them seamlessly.
 
 ### Keyboard Shortcuts
 
-- `q` – quit the application
-- `r` – reload the current failure log and start a fresh run
-- `o` – open the directory containing the latest run outputs
+| Key | Action |
+|-----|--------|
+| `q` | Quit the application |
+| `r` | Reload input and start fresh run |
+| `o` | Open output directory |
+| `?` | Show help panel with all shortcuts |
+| `Esc` | Cancel current operation |
 
-Shortcuts vary slightly depending on the active view—press `?` inside the TUI to
-see the full help panel.
+!!! note
+    Shortcuts may vary depending on the active view. Press `?` inside the TUI to see context-specific help.
 
-## Interpreting Outputs
+## Configuration Reference
 
-The regression write step mirrors the configuration inside
-`regression.run.output`:
+### Complete Configuration Example
+
+```yaml title=".socx.yaml"
+regression:
+  # Maximum number of tests to run in parallel
+  max_runs_in_parallel: 20
+  
+  # Custom test wrapper class (advanced)
+  test_cls: "socx.regression.test:Test"
+  
+  # Working directory for regression runs
+  path: ~/workspace/regression
+  
+  run:
+    input:
+      # Directory containing test command files
+      directory: ./sim/logs
+      
+      # Default input filename
+      filename: failed.log
+    
+    output:
+      # Directory for results (timestamped subdirs created automatically)
+      directory: ./results
+```
+
+### Input Configuration
+
+```yaml
+regression:
+  run:
+    input:
+      directory: "${PROJECT_ROOT}/ci/failures"
+      filename: "failed-${BUILD_ID}.log"
+```
+
+Supports environment variable substitution for dynamic paths.
+
+### Output Configuration
 
 ```yaml
 regression:
   run:
     output:
-      directory: ~/socx/results
+      directory: "${PROJECT_ROOT}/ci/results"
 ```
 
-SoCX creates the directory if necessary and places a dated folder inside (for
-example `~/socx/results/09-03-2025/12-45_failed.log`). Each line in the files is
-the original command; there is no additional metadata so that the logs can be
-consumed by other scripts.
+SoCX creates timestamped subdirectories automatically:
+
+```
+results/
+├── 2025-03-09/
+│   ├── 12-45_passed.log
+│   └── 12-45_failed.log
+└── 2025-03-10/
+    ├── 08-30_passed.log
+    └── 08-30_failed.log
+```
+
+### Custom Test Classes (Advanced)
+
+Override the test wrapper class for custom behavior:
+
+```yaml
+regression:
+  test_cls: "my_company.testing:CustomTest"
+```
+
+The custom class must inherit from `socx.regression.test:Test`.
+
+## Output Format
+
+Result files contain one command per line (no metadata):
+
+```text title="2025-03-09/12-45_passed.log"
+vcs -full64 +acc +cover top.tb +seed=1234
+python tools/run_smoke.py --seed 4142
+```
+
+```text title="2025-03-09/12-45_failed.log"
+make -C ips/pci build && make test
+./run_test.sh test_case_42
+```
+
+This simple format allows easy consumption by other scripts and tools.
 
 ## Troubleshooting
 
-- `SOCX_DEBUG=1 socx rgr run` turns on debug logging for the regression
-  pipeline and configuration loader.
-- Use `--no-config` if you suspect a repository override is injecting an
-  unexpected command file.
-- Inspect runtime settings with `socx config get regression` to confirm which
-  directories and filenames are in play.
+### Enable Debug Logging
+
+```bash
+SOCX_DEBUG=1 socx rgr run
+```
+
+Shows detailed logging for:
+
+- Configuration loading
+- File parsing
+- Command execution
+- Result writing
+
+### Ignore Configuration Overrides
+
+```bash
+socx --no-config rgr run
+```
+
+Use this if you suspect a repository or user configuration is causing issues.
+
+### Inspect Active Configuration
+
+```bash
+# View all regression settings
+socx config get regression
+
+# View specific setting
+socx config get regression.max_runs_in_parallel
+
+# Debug configuration loading
+socx config debug
+```
+
+### Common Issues
+
+| Issue | Solution |
+|-------|----------|
+| "File not found" | Check `regression.run.input.directory` and `filename` settings |
+| "Permission denied" | Ensure output directory is writable |
+| Commands not running in parallel | Increase `max_runs_in_parallel` |
+| Out of memory | Decrease `max_runs_in_parallel` |
+| Commands stuck | Check if individual commands hang (test outside socx) |
+
+## Best Practices
+
+1. **Start with low parallelism** - Test with `max_runs_in_parallel: 5` first
+2. **Use version control** - Commit `.socx.yaml` with project-specific settings
+3. **Monitor resources** - Watch CPU/memory usage during parallel runs
+4. **Keep commands idempotent** - Tests should be rerunnable without side effects
+5. **Use absolute paths** - Or relative to a known environment variable
+6. **Timestamp results** - SoCX does this automatically, don't override
+7. **Test locally first** - Verify regression setup before running in CI
diff --git a/mkdocs.yml b/mkdocs.yml
index 1005e073..0caebceb 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -35,8 +35,9 @@ nav:
       - Regression Automation: user-guide/regression.md
       - Plugin Development: user-guide/plugins.md
   - Reference:
+      - Configuration: reference/configuration.md
       - API: reference/api.md
-  - Conepts:
+  - Concepts:
       - Plugins: concepts/plugins.md
   - Development:
       - Contributing: development/contributing.md