docs: clarify custom SAST config, predence, rule-path semantics

Signed-off-by: lelia <2418071+lelia@users.noreply.github.com>

Author: lelia

docs/github-action.md

@@ -603,8 +603,12 @@ jobs:
 
 ### Custom Rule Configuration
 
+Use custom rules from your repository by setting `use_custom_sast_rules` and
+`custom_sast_rule_path`. This path is resolved relative to `GITHUB_WORKSPACE`
+in GitHub Actions.
+
 ```yaml
-name: Security Scan with Custom Rules
+name: Security Scan with Custom SAST Rules
 on:
   pull_request:
     types: [opened, synchronize, reopened]
@@ -625,21 +629,25 @@ jobs:
           GITHUB_PR_NUMBER: ${{ github.event.pull_request.number || github.event.issue.number }}
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
-          
-          # Enable Python SAST
+
+          # Enable SAST languages you expect to run.
           python_sast_enabled: 'true'
-          
-          # Enable specific Python rules
-          python_enabled_rules: 'sql-injection,xss,hardcoded-credentials'
-          
-          # Disable noisy rules
-          python_disabled_rules: 'unused-import,line-too-long'
-          
-          # JavaScript with custom rules
           javascript_sast_enabled: 'true'
-          javascript_enabled_rules: 'eval-usage,prototype-pollution'
+
+          # Enable custom rules from repository path.
+          use_custom_sast_rules: 'true'
+          custom_sast_rule_path: '.socket/rules'
+
+          # Optional: to avoid allowlist exclusions, run all rules for enabled languages.
+          all_rules_enabled: 'true'
 ```
 
+Important behavior:
+- `socket_security_api_key` + `socket_org` enables dashboard config loading.
+- Dashboard/API settings override overlapping `with:` values.
+- `<language>_enabled_rules` is an allowlist and can suppress custom rule IDs.
+- `all_rules_enabled: 'true'` disables allowlist filtering for enabled languages.
+
 ## Configuration Reference
 
 ### All Available Inputs
@@ -667,6 +675,8 @@ See [`action.yml`](../action.yml) for the complete list of inputs.
 **Rule Configuration (per language):**
 - `<language>_enabled_rules` — Comma-separated rules to enable
 - `<language>_disabled_rules` — Comma-separated rules to disable
+- `use_custom_sast_rules` — Enable custom SAST rule discovery from repo files
+- `custom_sast_rule_path` — Relative path to custom SAST rule directory
 
 **Security Scanning:**
 - `secret_scanning_enabled` — Enable secret scanning

docs/parameters.md

@@ -194,6 +194,10 @@ Use custom SAST rules instead of bundled rules (falls back to bundled rules for
 socket-basics --python --use-custom-sast-rules
 ```
 
+When this is enabled, custom rules are loaded from YAML files under
+`--custom-sast-rule-path`. Each rule must include a `languages` list so Socket
+Basics can map it to the correct OpenGrep language rule file.
+
 ### `--custom-sast-rule-path CUSTOM_SAST_RULE_PATH`
 Relative path to custom SAST rules directory (relative to workspace if set, otherwise cwd).
 
@@ -206,6 +210,11 @@ Relative path to custom SAST rules directory (relative to workspace if set, othe
 socket-basics --python --use-custom-sast-rules --custom-sast-rule-path "my_custom_rules"
 ```
 
+Custom rule file notes:
+- `.yml` and `.yaml` files are discovered recursively.
+- Files ending in `.test.yml` or `.test.yaml` are ignored.
+- Rules without `languages` are skipped.
+
 ### Language-Specific Rule Configuration
 
 For each language, you can enable or disable specific rules:
@@ -519,7 +528,9 @@ All notification integrations support environment variables as alternatives to C
 
 | Variable | Description |
 |----------|-------------|
-| `INPUT_OPENGREP_RULES_DIR` | Custom directory containing SAST rules |
+| `INPUT_OPENGREP_RULES_DIR` | Override directory for bundled OpenGrep rule files (`*.yml`) |
+| `INPUT_USE_CUSTOM_SAST_RULES` | Enable repository custom SAST rules |
+| `INPUT_CUSTOM_SAST_RULE_PATH` | Relative directory path for repository custom SAST rules |
 
 ## Configuration File
 
@@ -536,6 +547,8 @@ You can provide configuration via a JSON file using `--config`:
 
   "python_sast_enabled": true,
   "javascript_sast_enabled": true,
+  "use_custom_sast_rules": true,
+  "custom_sast_rule_path": ".socket/rules",
   "go_sast_enabled": true,
 
   "secrets_enabled": true,
@@ -559,17 +572,18 @@ You can provide configuration via a JSON file using `--config`:
 Configuration is merged in the following order (later sources override earlier ones):
 
 1. Default values
-2. JSON configuration file (via `--config`)
-3. Environment variables
-4. Command-line arguments
+2. Environment variables
+3. Socket Basics API configuration (when available and no `--config` file is used)
+4. JSON configuration file (via `--config`)
+5. Command-line arguments
 
 **Example:**
 ```bash
-# JSON file sets python_sast_enabled: true
-# Environment has PYTHON_SAST_ENABLED=false
+# Environment sets python_sast_enabled=true
+# Dashboard/API sets python_sast_enabled=false
 # CLI has --javascript
-# Result: JavaScript enabled, Python disabled (env override), other settings from JSON
-socket-basics --config config.json --javascript
+# Result: JavaScript enabled, Python follows dashboard/API value, other settings from env/API
+socket-basics --javascript
 ```
 
 ## Common Usage Patterns