Refactor docs to reduce README complexity, create dedicated CLI and CI/CD guides

Signed-off-by: lelia <lelia@socket.dev>

Author: lelia

README.md

@@ -0,0 +1,105 @@
+# CI/CD guide
+
+Use this guide for pipeline-focused CLI usage across platforms.
+
+## Recommended patterns
+
+### Dashboard-style reachable SARIF
+
+```bash
+socketcli \
+  --reach \
+  --sarif-file results.sarif \
+  --sarif-scope full \
+  --sarif-grouping alert \
+  --sarif-reachability reachable \
+  --disable-blocking
+```
+
+### Diff-based gating on new reachable findings
+
+```bash
+socketcli \
+  --reach \
+  --sarif-file results.sarif \
+  --sarif-scope diff \
+  --sarif-reachability reachable \
+  --strict-blocking
+```
+
+## Config file usage in CI
+
+Use `--config .socketcli.toml` to keep pipeline commands small.
+
+Precedence order:
+
+`CLI flags` > `environment variables` > `config file` > `built-in defaults`
+
+Example:
+
+```toml
+[socketcli]
+reach = true
+sarif_scope = "full"
+sarif_grouping = "alert"
+sarif_reachability = "reachable"
+sarif_file = "results.sarif"
+```
+
+## Platform examples
+
+### GitHub Actions
+
+```yaml
+- name: Run Socket CLI
+  run: socketcli --config .socketcli.toml --target-path .
+  env:
+    SOCKET_SECURITY_API_TOKEN: ${{ secrets.SOCKET_SECURITY_API_TOKEN }}
+```
+
+### Buildkite
+
+```yaml
+steps:
+  - label: "Socket scan"
+    command: "socketcli --config .socketcli.toml --target-path ."
+    env:
+      SOCKET_SECURITY_API_TOKEN: "${SOCKET_SECURITY_API_TOKEN}"
+```
+
+### GitLab CI
+
+```yaml
+socket_scan:
+  script:
+    - socketcli --config .socketcli.toml --target-path .
+  variables:
+    SOCKET_SECURITY_API_TOKEN: $SOCKET_SECURITY_API_TOKEN
+```
+
+### Bitbucket Pipelines
+
+```yaml
+pipelines:
+  default:
+    - step:
+        script:
+          - socketcli --config .socketcli.toml --target-path .
+```
+
+## Workflow templates
+
+Prebuilt examples in this repo:
+
+- [`../workflows/github-actions.yml`](../workflows/github-actions.yml)
+- [`../workflows/buildkite.yml`](../workflows/buildkite.yml)
+- [`../workflows/gitlab-ci.yml`](../workflows/gitlab-ci.yml)
+- [`../workflows/bitbucket-pipelines.yml`](../workflows/bitbucket-pipelines.yml)
+
+## CI gotchas
+
+- `--strict-blocking` changes pass/fail policy, not SARIF dataset semantics.
+- `--sarif-scope full` requires `--reach`.
+- `--sarif-grouping alert` currently applies to `--sarif-scope full`.
+- Diff-based SARIF can validly be empty when there are no matching net-new alerts.
+- Keep API tokens in secret stores (`SOCKET_SECURITY_API_TOKEN`), not in config files.

docs/README.md

@@ -0,0 +1,95 @@
+# Development guide
+
+## Local setup
+
+This project uses `pyproject.toml` and `uv.lock` for dependency management.
+
+### Standard setup (PyPI dependencies)
+
+```bash
+pyenv local 3.11
+make first-time-setup
+```
+
+### Local SDK development setup
+
+```bash
+pyenv local 3.11
+SOCKET_SDK_PATH=~/path/to/socketdev make first-time-local-setup
+```
+
+Default local SDK path is `../socketdev` when `SOCKET_SDK_PATH` is not set.
+
+## Ongoing workflows
+
+After dependency changes:
+
+```bash
+make update-deps
+```
+
+After pulling latest changes:
+
+```bash
+make sync-all
+```
+
+Run tests:
+
+```bash
+make test
+```
+
+Run lint/format checks:
+
+```bash
+make lint
+```
+
+## Make targets
+
+High-level:
+
+- `make first-time-setup`
+- `make first-time-local-setup`
+- `make update-lock`
+- `make sync-all`
+- `make dev-setup`
+
+Implementation:
+
+- `make local-dev`
+- `make setup`
+- `make sync`
+- `make clean`
+- `make test`
+- `make lint`
+
+## Environment variables
+
+Core:
+
+- `SOCKET_SECURITY_API_TOKEN` (also supports `SOCKET_SECURITY_API_KEY`, `SOCKET_API_KEY`, `SOCKET_API_TOKEN`)
+- `SOCKET_SDK_PATH` (default `../socketdev`)
+
+GitLab:
+
+- `GITLAB_TOKEN`
+- `CI_JOB_TOKEN`
+
+## Manual setup (without `make`)
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+uv sync
+uv add --dev pre-commit
+pre-commit install
+```
+
+## Related docs
+
+- CLI quick start: [`../README.md`](../README.md)
+- CI/CD usage: [`ci-cd.md`](ci-cd.md)
+- Full CLI reference: [`cli-reference.md`](cli-reference.md)
+- Troubleshooting: [`troubleshooting.md`](troubleshooting.md)

docs/ci-cd.md

@@ -0,0 +1,58 @@
+# Troubleshooting
+
+## Common gotchas
+
+- `--strict-blocking` changes pass/fail policy, not SARIF dataset source.
+- `--sarif-scope full` requires `--reach`.
+- In `--sarif-scope full` with `--sarif-file`, SARIF JSON is written to file and stdout JSON is suppressed.
+- `--sarif-grouping alert` currently applies to `--sarif-scope full`.
+
+## Save submitted file list
+
+Use `--save-submitted-files-list` to inspect exactly what was sent for scanning.
+
+```bash
+socketcli --save-submitted-files-list submitted_files.json
+```
+
+Output includes:
+
+- timestamp
+- total file count
+- total size
+- complete submitted file list
+
+## Save manifest archive
+
+Use `--save-manifest-tar` to export discovered manifest files as `.tar.gz`.
+
+```bash
+socketcli --save-manifest-tar manifest_files.tar.gz
+```
+
+Combined example:
+
+```bash
+socketcli --save-submitted-files-list files.json --save-manifest-tar backup.tar.gz
+```
+
+## Octopus merge note
+
+For octopus merges (3+ parents), Git can report incomplete changed-file sets because default diff compares against the first parent.
+
+If needed, force full scan behavior with:
+
+- `--ignore-commit-files`
+
+## GitLab report troubleshooting
+
+If report is not visible in GitLab Security Dashboard:
+
+- verify `dependency_scanning` artifact is configured in `.gitlab-ci.yml`
+- verify job completed and artifact uploaded
+- verify report file schema is valid
+
+If vulnerabilities array is empty:
+
+- this can be expected when no actionable security issues are present in the result scope
+- confirm expected scope/flags and compare with Socket dashboard data

docs/cli-reference.md

@@ -0,0 +1,13 @@
+# Socket Security Buildkite pipeline example
+# Runs Socket CLI in a Buildkite step using repository-level environment variables.
+
+steps:
+  - label: "Socket Security Scan"
+    command: |
+      socketcli \
+        --target-path . \
+        --scm api \
+        --pr-number 0
+    env:
+      # Configure this in Buildkite pipeline/repo settings.
+      SOCKET_SECURITY_API_TOKEN: "${SOCKET_SECURITY_API_TOKEN}"