feat: align install guides with the CLI and declare the documented action inputs

CHANGELOG.md

@@ -8,6 +8,56 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+### Added
+- `--version` CLI flag. (CE-445)
+- `--socket-org` CLI flag, the command-line equivalent of the `socket_org`
+  action input and the `SOCKET_ORG` environment variable. The API key remains
+  environment-only. (CE-445)
+- GitHub Action inputs `verbose`, `console_tabular_enabled` and
+  `console_json_enabled`, delivered as `INPUT_VERBOSE`,
+  `INPUT_CONSOLE_TABULAR_ENABLED` and `INPUT_CONSOLE_JSON_ENABLED` and honored
+  from the environment the same way as the matching CLI flags. (CE-445)
+- GitHub Action inputs `jira_url` and `jira_project`, matching the names used in
+  the documentation; `server` and `project` remain as aliases. Also added
+  `ms_sentinel_shared_key` (alias of `ms_sentinel_key`),
+  `opengrep_notification_method` and `trufflehog_notification_method`
+  (`notification_method` remains as an alias). (CE-445)
+- `docs/parameters.md` gains a **Name Mapping** section listing every setting as
+  CLI flag, GitHub Action input, environment variable and JSON key, generated
+  from `connectors.yaml`, `notifications.yaml` and `action.yml`. A new test
+  keeps `action.yml` and the parameter declarations in step. (CE-445)
+- `scripts/check_release_docs.py` now also checks that action references use an
+  exact release tag and that the bundled scanner versions quoted in the guides
+  match the Dockerfile pins; `--write` updates both. (CE-445)
+- Documentation for the `-heavy` image variant and for when the standard image
+  is the right choice. (CE-445)
+
+### Removed
+- The `workspace` and `GITHUB_API_URL` GitHub Action inputs. Neither had an
+  effect: the action always scans `GITHUB_WORKSPACE`, and `GITHUB_API_URL` is
+  provided by the runner. Workflows that still set them receive an
+  "Unexpected input" warning and otherwise behave as before. (CE-445)
+- `docs/alert-quality-improvement-plan.md`, a draft working document from a
+  hackathon branch. The plan itself is now tracked in Linear as CE-447. (CE-445)
+
+### Fixed
+- The Sentinel and Sumo Logic notifiers now read `ms_sentinel_workspace_id`,
+  `ms_sentinel_key` and `sumologic_endpoint` from CLI flags, action inputs and
+  dashboard configuration, in addition to the `MS_SENTINEL_*` and
+  `SUMO_LOGIC_HTTP_SOURCE_URL` environment variables. (CE-445)
+- Documentation consistency pass across the GitHub Action, Docker and local
+  installation guides (CE-445). CLI examples use the flag names that
+  `socket-basics --help` prints. Docker examples keep the facts file inside the
+  workspace so the dashboard upload succeeds, and show the environment variables
+  needed for PR comments outside GitHub Actions. The GitHub Action guide reflects
+  the bundled Trivy scanner, lists only declared inputs, and passes discovered
+  Dockerfiles through in the auto-discovery example. JSON configuration examples
+  use the keys the loader reads, the S3 variable names and `--config` precedence
+  match the code, GitLab and Jenkins examples override the image entrypoint,
+  pre-commit hook examples use the published image name, and the installation
+  guide states the Python 3.10 requirement and the npm install path for the
+  Socket CLI. New guidance covers large repositories and facts-file size.
+
 ## [3.1.0] - 2026-09-02
 
 ### Added

README.md

@@ -97,7 +97,7 @@ Socket Basics can also run locally or in other CI/CD environments:
 **Flexible Configuration:**
 - Configure via CLI flags, environment variables, JSON files, or the Socket Dashboard
 - Auto-enablement for container scanning when images or Dockerfiles are specified
-- Support for both standard and GitHub Actions `INPUT_*` environment variables
+- Every setting is reachable as an `INPUT_*` environment variable (the GitHub Action input name, upper-cased); credentials and notifier endpoints also accept plain names such as `SOCKET_ORG` and `SLACK_WEBHOOK_URL`
 
 ## 🎨 Enhanced PR Comments
 
@@ -129,9 +129,9 @@ All configuration can be managed through:
 1. **Socket Dashboard** (Enterprise) — Centralized policy management
 2. **CLI Arguments** — Direct command-line flags
 3. **Environment Variables** — Standard or `INPUT_*` prefixed for GitHub Actions
-4. **JSON Configuration File** — Structured configuration (see `socket_config_example.json`)
+4. **JSON Configuration File** — Structured configuration passed with `--config` (see [Configuration File](docs/parameters.md#configuration-file))
 
-See [Parameters Reference](docs/parameters.md) for the full list of CLI options and environment variables.
+See [Parameters Reference](docs/parameters.md) for the full list of CLI options and environment variables, including the [name mapping](docs/parameters.md#name-mapping) between CLI flags, GitHub Action inputs, environment variables and JSON keys. The names differ between interfaces (for example `--python` on the CLI is `python_sast_enabled` in the action and `INPUT_PYTHON_SAST_ENABLED` in the environment), and the CLI rejects unknown flags.
 
 #### Integration Environment Variables
 
@@ -184,21 +184,25 @@ docker pull ghcr.io/socketdev/socket-basics:3.1.0
 # Run scan
 docker run --rm -v "$PWD:/workspace" ghcr.io/socketdev/socket-basics:3.1.0 \
   --workspace /workspace \
-  --python-sast-enabled \
-  --secret-scanning-enabled \
+  --python \
+  --secrets \
   --console-tabular-enabled
 ```
 
 The pre-built image is versioned and intended to be pinned exactly. Avoid floating tags like `:latest` in CI.
 
+Use the standard image. The registries also carry a `-heavy` variant that exists for one specific deployment constraint and adds nothing to Socket Basics itself; see [Image variants](docs/local-install-docker.md#image-variants) before choosing it.
+
 📖 **[View Docker Installation Guide](docs/local-install-docker.md)**
 
 ### CLI
 
 ```bash
-socket-basics --python --secrets --containers --verbose
+socket-basics --python --secrets --dockerfiles Dockerfile --verbose
 ```
 
+The API key is read from the environment (`SOCKET_SECURITY_API_KEY`; there is deliberately no flag for it) and the organization from `SOCKET_ORG` or `--socket-org`. The same flag names work inside the Docker image. The [name mapping table](docs/parameters.md#name-mapping) shows how every CLI flag corresponds to a GitHub Action input and an environment variable.
+
 📖 **[View Local Installation Guide](docs/local-installation.md)**
 
 ## 🔧 Requirements
@@ -259,8 +263,10 @@ Add new connectors by:
 **Connector fails to load:**
 - Verify `module_path` and `class` in `socket_basics/connectors.yaml`
 
-**Socket API errors:**
+**Socket API errors / results missing from the dashboard:**
 - Ensure `SOCKET_SECURITY_API_KEY` and `SOCKET_ORG` are set correctly
+- `No Socket organization configured` in the log means nothing was uploaded: set `SOCKET_ORG`, or use a key with the `socket-basics` scope so the organization can be discovered
+- `Need at least one file to be uploaded` means the facts file was written outside the scanned workspace; keep `--output` inside it (see [Save Results to File](docs/local-install-docker.md#save-results-to-file))
 - Verify your Socket Enterprise subscription is active
 - If you see `Insufficient permissions`, confirm your API token has the scopes required for your configuration mode (see [Required API Token Scopes](#required-api-token-scopes))
 
@@ -348,13 +354,13 @@ The `app_tests/` directory contains deliberately vulnerable applications (git su
 ```bash
 # Scan a vulnerable Node.js app
 socket-basics --workspace app_tests/juice-shop \
-  --javascript-sast-enabled \
-  --secret-scanning-enabled
+  --javascript \
+  --secrets
 
 # Scan a vulnerable Python app
 socket-basics --workspace app_tests/pygoat \
-  --python-sast-enabled \
-  --secret-scanning-enabled
+  --python \
+  --secrets
 
 # Compare results against known vulnerabilities
 # (Manual verification of findings)

action.yml

@@ -8,7 +8,10 @@ runs:
   env:
     # Core GitHub variables (these are automatically available, but we explicitly pass GITHUB_TOKEN)
     GITHUB_TOKEN: ${{ inputs.github_token }}
-    INPUT_WORKSPACE: ${{ inputs.workspace }}
+    # Output and logging (same behavior as the --verbose / --console-*-enabled CLI flags)
+    INPUT_VERBOSE: ${{ inputs.verbose }}
+    INPUT_CONSOLE_TABULAR_ENABLED: ${{ inputs.console_tabular_enabled }}
+    INPUT_CONSOLE_JSON_ENABLED: ${{ inputs.console_json_enabled }}
     # Scan scope
     INPUT_CHANGED_FILES: ${{ inputs.changed_files }}
     INPUT_SCAN_ALL: ${{ inputs.scan_all }}
@@ -50,13 +53,14 @@ runs:
     INPUT_JAVA_SAST_ENABLED: ${{ inputs.java_sast_enabled }}
     INPUT_JIRA_API_TOKEN: ${{ inputs.jira_api_token }}
     INPUT_JIRA_EMAIL: ${{ inputs.jira_email }}
-    INPUT_JIRA_PROJECT: ${{ inputs.project }}
-    INPUT_JIRA_URL: ${{ inputs.server }}
+    INPUT_JIRA_PROJECT: ${{ inputs.jira_project || inputs.project }}
+    INPUT_JIRA_URL: ${{ inputs.jira_url || inputs.server }}
     INPUT_KOTLIN_DISABLED_RULES: ${{ inputs.kotlin_disabled_rules }}
     INPUT_KOTLIN_ENABLED_RULES: ${{ inputs.kotlin_enabled_rules }}
     INPUT_KOTLIN_SAST_ENABLED: ${{ inputs.kotlin_sast_enabled }}
     INPUT_MSTEAMS_WEBHOOK_URL: ${{ inputs.msteams_webhook_url }}
-    INPUT_MS_SENTINEL_KEY: ${{ inputs.ms_sentinel_key }}
+    INPUT_MS_SENTINEL_KEY: ${{ inputs.ms_sentinel_key || inputs.ms_sentinel_shared_key }}
+    INPUT_MS_SENTINEL_SHARED_KEY: ${{ inputs.ms_sentinel_shared_key || inputs.ms_sentinel_key }}
     INPUT_MS_SENTINEL_WORKSPACE_ID: ${{ inputs.ms_sentinel_workspace_id }}
     INPUT_PHP_DISABLED_RULES: ${{ inputs.php_disabled_rules }}
     INPUT_PHP_ENABLED_RULES: ${{ inputs.php_enabled_rules }}
@@ -86,7 +90,8 @@ runs:
     INPUT_TRIVY_NOTIFICATION_METHOD: ${{ inputs.trivy_notification_method }}
     INPUT_TRIVY_VULN_ENABLED: ${{ inputs.trivy_vuln_enabled }}
     INPUT_TRUFFLEHOG_EXCLUDE_DIR: ${{ inputs.trufflehog_exclude_dir }}
-    INPUT_TRUFFLEHOG_NOTIFICATION_METHOD: ${{ inputs.notification_method }}
+    INPUT_TRUFFLEHOG_NOTIFICATION_METHOD: ${{ inputs.trufflehog_notification_method || inputs.notification_method }}
+    INPUT_OPENGREP_NOTIFICATION_METHOD: ${{ inputs.opengrep_notification_method }}
     INPUT_TRUFFLEHOG_SHOW_UNVERIFIED: ${{ inputs.trufflehog_show_unverified }}
     INPUT_USE_CUSTOM_SAST_RULES: ${{ inputs.use_custom_sast_rules }}
     INPUT_WEBHOOK_URL: ${{ inputs.webhook_url }}
@@ -106,10 +111,6 @@ runs:
     INPUT_PR_LABEL_LOW: ${{ inputs.pr_label_low }}
 
 inputs:
-  workspace:
-    description: "Workspace directory to scan (defaults to GITHUB_WORKSPACE)"
-    required: false
-    default: ""
   changed_files:
     description: >-
       Diff-only mode: scope every scanner (SAST/OpenGrep, secrets, containers)
@@ -151,10 +152,18 @@ inputs:
     description: "GitHub token for PR comments and API access"
     required: false
     default: ""
-  GITHUB_API_URL:
-    description: "Github Api Url"
+  verbose:
+    description: "Enable verbose (DEBUG) logging in the step log. Same as the --verbose CLI flag."
     required: false
-    default: ""
+    default: "false"
+  console_tabular_enabled:
+    description: "Print consolidated findings as tables in the step log. Same as the --console-tabular-enabled CLI flag."
+    required: false
+    default: "false"
+  console_json_enabled:
+    description: "Print consolidated findings as JSON in the step log. Same as the --console-json-enabled CLI flag."
+    required: false
+    default: "false"
   all_languages_enabled:
     description: "Enable SAST for all supported languages"
     required: false
@@ -288,11 +297,19 @@ inputs:
     required: false
     default: ""
   jira_api_token:
-    description: "Jira Api Token"
+    description: "Jira API token (also reads JIRA_API_TOKEN or INPUT_JIRA_API_TOKEN)"
     required: false
     default: ""
   jira_email:
-    description: "Jira Email"
+    description: "Jira account email (also reads JIRA_EMAIL or INPUT_JIRA_EMAIL)"
+    required: false
+    default: ""
+  jira_url:
+    description: "Jira base URL, e.g. https://your-org.atlassian.net (also reads JIRA_URL or INPUT_JIRA_URL)"
+    required: false
+    default: ""
+  jira_project:
+    description: "Jira project key, e.g. SEC (also reads JIRA_PROJECT or INPUT_JIRA_PROJECT)"
     required: false
     default: ""
   kotlin_disabled_rules:
@@ -308,19 +325,31 @@ inputs:
     required: false
     default: "false"
   ms_sentinel_key:
-    description: "Ms Sentinel Key"
+    description: "Microsoft Sentinel shared key (also reads MS_SENTINEL_SHARED_KEY or INPUT_MS_SENTINEL_SHARED_KEY)"
+    required: false
+    default: ""
+  ms_sentinel_shared_key:
+    description: "Alias for ms_sentinel_key, matching the MS_SENTINEL_SHARED_KEY environment variable name"
     required: false
     default: ""
   ms_sentinel_workspace_id:
-    description: "Ms Sentinel Workspace Id"
+    description: "Microsoft Sentinel workspace ID (also reads MS_SENTINEL_WORKSPACE_ID or INPUT_MS_SENTINEL_WORKSPACE_ID)"
     required: false
     default: ""
   msteams_webhook_url:
     description: "MS Teams incoming webhook URL (also reads MSTEAMS_WEBHOOK_URL or INPUT_MSTEAMS_WEBHOOK_URL)"
     required: false
     default: ""
   notification_method:
-    description: "Notification method for TruffleHog (e.g., console, slack)"
+    description: "Deprecated alias for trufflehog_notification_method; kept for existing workflows"
+    required: false
+    default: ""
+  trufflehog_notification_method:
+    description: "Notification method for TruffleHog secret findings (e.g., console, slack). Same as --trufflehog-notify."
+    required: false
+    default: ""
+  opengrep_notification_method:
+    description: "Notification method for OpenGrep SAST findings (e.g., console, slack). Same as --opengrep-notify."
     required: false
     default: ""
   php_disabled_rules:
@@ -336,7 +365,7 @@ inputs:
     required: false
     default: "false"
   project:
-    description: "Project"
+    description: "Deprecated alias for jira_project; kept for existing workflows"
     required: false
     default: ""
   python_disabled_rules:
@@ -392,7 +421,7 @@ inputs:
     required: false
     default: "false"
   server:
-    description: "Server"
+    description: "Deprecated alias for jira_url; kept for existing workflows"
     required: false
     default: ""
   slack_webhook_url: