docs(scan): document --prune/--sync/--dry-run + un-deprecate gc

CLI_CONTRACT.md:
  * Scan flag table: replace --no-prune row with three new rows —
    --prune, --sync, -d/--dry-run. Add a paragraph explaining each
    plus the canonical bot-mode invocation.
  * JSON output shape: drop the --no-prune-emits-{skipped:true} note.
    Clarify that `gc` is omitted ENTIRELY when --prune/--sync isn't
    set. Document --dry-run behavior including the explicit
    `apply.dryRun: true` marker for bots.
  * New "scan — --sync (bot mode)" section with the canonical
    `scan --json --sync --yes | jq '{applied, pruned, bytes_freed}'`
    recipe.
  * New "scan — --dry-run" section explaining that --dry-run is a
    no-op without one of the mutating flags.
  * Restore the `repair` section's normal heading (drop the
    "*(deprecated since v3.0)*" suffix and the deprecation paragraph).
    Note that the `gc` visible_alias is now contract-guarded.
  * Semver-policy table: drop the GC-default row, add explicit rows
    for "flipping --prune to opt-out" and "demoting `gc` from
    visible_alias" — both MAJOR.

README.md:
  * Restore the `### repair` / `gc` section that was removed during
    the deprecation iteration. Wording clarifies that `repair`/`gc` is
    the right answer for cleanup-without-apply and points users at
    `scan --sync` for the combined workflow.
  * `### scan` section: replace --no-prune row with --prune, --sync,
    --dry-run, --yes. Bot-mode example becomes `scan --json --sync --yes`
    (the user's "one or two flags" target). Add a `scan --json --sync
    --yes --dry-run` example.
  * `## Scripting & CI/CD`: lead with the new `--sync` recipe piped
    through jq into `peter-evans/create-pull-request`. Keep the old
    `scan --json --ecosystems npm` read-only example as the second
    use case.

Assisted-by: Claude Code:claude-opus-4-7

Author: mikolalysenko

README.md

@@ -137,7 +137,7 @@ socket-patch get CVE-2024-12345 --json -y
 
 ### `scan`
 
-Scan installed packages for available security patches. Since v3.0 `scan` is the single command bots need: it discovers patches, optionally applies them, and garbage-collects orphan blob files plus manifest entries for uninstalled packages.
+Scan installed packages for available security patches. Since v3.0 `scan --sync` is the single command bots need for full auto-update: it discovers patches, applies them, and garbage-collects orphan blob files plus manifest entries for uninstalled packages — all in one invocation.
 
 **Usage:**
 ```bash
@@ -148,7 +148,9 @@ socket-patch scan [options]
 | Flag | Description |
 |------|-------------|
 | `--apply` | Download and apply selected patches in JSON mode (non-interactive). Without it, `scan --json` is read-only. |
-| `--no-prune` | Disable garbage collection. By default `scan` removes manifest entries for uninstalled packages and orphan blob/diff/package-archive files. |
+| `--prune` | Garbage-collect after the scan: remove manifest entries for uninstalled packages and orphan blob/diff/package-archive files. Off by default. |
+| `--sync` | Sugar for `--apply --prune`. The canonical bot-mode flag. |
+| `-d, --dry-run` | Preview what `--apply`/`--prune`/`--sync` would do without mutating disk. |
 | `--org <slug>` | Organization slug |
 | `--json` | Output results as JSON |
 | `-y, --yes` | Skip confirmation prompts |
@@ -166,14 +168,20 @@ socket-patch scan [options]
 # Scan local project (interactive prompt to apply)
 socket-patch scan
 
-# Scan with JSON output (read-only: discover + updates + GC preview)
+# Scan with JSON output (discover + updates, no mutation)
 socket-patch scan --json
 
 # Bot mode: discover, apply, prune, sweep — all in one
-socket-patch scan --json --apply --yes
+socket-patch scan --json --sync --yes
 
-# Apply without pruning (preserve manifest entries for uninstalled packages)
-socket-patch scan --apply --yes --no-prune
+# Apply without pruning manifest entries (default)
+socket-patch scan --apply --yes
+
+# Apply + prune explicitly (equivalent to --sync)
+socket-patch scan --json --apply --prune --yes
+
+# Preview a full sync without mutating disk
+socket-patch scan --json --sync --yes --dry-run
 
 # Scan only npm packages
 socket-patch scan --ecosystems npm
@@ -347,6 +355,45 @@ socket-patch remove "pkg:npm/lodash@4.17.20" --skip-rollback
 socket-patch remove "pkg:npm/lodash@4.17.20" --json
 ```
 
+### `repair`
+
+Download missing blobs and clean up unused blobs.
+
+Alias: `gc`
+
+`repair` cleans up the `.socket/` directory without running a scan — useful when you've manually adjusted the manifest, recovered from a partial-failure state, or just want to free space. For the combined workflow (discover + apply + GC in one pass), use `scan --sync --json --yes` instead.
+
+**Usage:**
+```bash
+socket-patch repair [options]
+```
+
+**Options:**
+| Flag | Description |
+|------|-------------|
+| `-d, --dry-run` | Show what would be done without doing it |
+| `--offline` | Skip network operations (cleanup only) |
+| `--download-only` | Only download missing blobs, do not clean up |
+| `--json` | Output results as JSON |
+| `-m, --manifest-path <path>` | Path to manifest (default: `.socket/manifest.json`) |
+| `--cwd <dir>` | Working directory (default: `.`) |
+| `--download-mode <mode>` | `file` (default), `diff`, or `package` |
+
+**Examples:**
+```bash
+# Full repair (download missing + clean up unused)
+socket-patch repair
+
+# Cleanup only, no downloads
+socket-patch repair --offline
+
+# Download missing blobs only
+socket-patch repair --download-only
+
+# JSON output for scripting
+socket-patch repair --json
+```
+
 ### `setup`
 
 Configure `package.json` postinstall scripts to automatically apply patches after `npm install`.
@@ -384,10 +431,18 @@ socket-patch setup --json -y
 All commands support `--json` for machine-readable output. JSON responses always include a `"status"` field for easy error detection:
 
 ```bash
-# Check for available patches in CI
+# Check for available patches in CI (read-only)
 result=$(socket-patch scan --json --ecosystems npm)
 patches=$(echo "$result" | jq '.totalPatches')
 
+# Auto-update bot mode: discover, apply, prune, sweep in one pass
+socket-patch scan --json --sync --yes | jq '{
+  applied:     [.apply.patches[] | select(.action == "added" or .action == "updated") | .purl],
+  pruned:      .gc.prunedManifestEntries,
+  bytes_freed: .gc.bytesFreed
+}'
+# Pipe this into peter-evans/create-pull-request to open a PR with the changes.
+
 # Apply patches and check result
 socket-patch apply --json | jq '.status'
 # "success", "partial_failure", "no_manifest", or "error"

crates/socket-patch-cli/CLI_CONTRACT.md

@@ -84,11 +84,17 @@ The hidden alias `--no-apply` on `--save-only` is **part of the contract** — i
 | `--ecosystems` | — | (none) | CSV → `Vec<String>` |
 | `--download-mode` | — | **`diff`** | string |
 | `--apply` | — | `false` | bool |
-| `--no-prune` | — | `false` | bool |
+| `--prune` | — | `false` | bool |
+| `--sync` | — | `false` | bool |
+| `--dry-run` | `-d` | `false` | bool |
+
+`--apply` opts JSON callers into the full discover → select → apply pipeline. Without it, `scan --json` stays read-only (discovery + `updates` array only). No effect outside `--json` mode — the non-JSON path always prompts the user interactively. Designed for unattended workflows (cron jobs, bots that open PRs).
 
-`--apply` opts JSON callers into the full discover → select → apply pipeline. Without it, `scan --json` stays read-only (discovery + `updates` array + `gc` preview only). No effect outside `--json` mode — the non-JSON path always prompts the user interactively. Designed for unattended workflows (cron jobs, bots that open PRs).
+`--prune` opts into garbage collection. When set, `scan` removes manifest entries for packages no longer present in the crawl, then deletes orphan blob, diff, and package-archive files from `.socket/`. Off by default (v3.0) so a temporary uninstall doesn't silently destroy manifest state. Pair with `--apply` (or use `--sync`) for the auto-update workflow.
 
-`--no-prune` disables garbage collection. By default (since v3.0) `scan` removes manifest entries for packages no longer present in the crawl and deletes orphan blob, diff, and package-archive files from `.socket/`. Pass `--no-prune` to leave the manifest and `.socket/` directory untouched.
+`--sync` is sugar for `--apply --prune` — the canonical single-flag bot invocation. `scan --json --sync --yes` discovers, applies, and reconciles state in one pass.
+
+`--dry-run` (`-d`) previews what `--apply` / `--prune` / `--sync` would do without mutating disk. In JSON mode, `apply.patches[*]` is populated with would-be actions (computed via `decide_patch_action` against the current manifest) and `gc.prunable*` / `gc.orphan*` fields report counts via the cleanup helpers' built-in dry-run mode. No effect without at least one of `--apply`, `--prune`, or `--sync`.
 
 ### `list`
 
@@ -121,9 +127,9 @@ Required positional `identifier`. Flags:
 | `--yes` | `-y` | `false` | bool |
 | `--json` | — | `false` | bool |
 
-### `repair` *(deprecated since v3.0)*
+### `repair`
 
-`scan` now performs garbage collection by default (manifest pruning + orphan file cleanup); prefer `scan` or `scan --no-prune`. `repair` and its `gc` alias remain available for direct invocation but no longer appear in `socket-patch --help`. The subcommand itself is hidden via `clap`'s `hide = true`, and `gc` is demoted from `visible_alias` to `alias`. **Removing `repair` entirely or unhiding it requires a MAJOR bump.**
+`repair` (alias `gc`) is a first-class command for cleaning up the `.socket/` directory without running a scan. For the combined discover-and-apply workflow with GC, use `scan --sync --json --yes`; for cleanup alone, use `repair` (or `gc`) directly. The `gc` visible alias is part of the contract — removing or demoting it is a MAJOR bump.
 
 | Long | Short | Default | Type |
 |---|---|---|---|
@@ -241,24 +247,17 @@ When `--json` is set, commands print a single JSON object to stdout. The schemas
   ],
   "updates": [
     { "purl": "pkg:npm/foo@1.0", "oldUuid": "<previous>", "newUuid": "<newest>" }
-  ],
-  "gc": {
-    "prunableManifestEntries": ["pkg:npm/uninstalled@1.0"],
-    "orphanBlobs": 3,
-    "orphanDiffArchives": 1,
-    "orphanPackageArchives": 0,
-    "bytesReclaimable": 8421
-  }
+  ]
 }
 ```
 
 The `updates` array lists PURLs where the newest available patch UUID differs from the one currently recorded in `.socket/manifest.json`. Bots use this to drive "what would change" summaries without mutating anything.
 
-The `gc` sub-object in read-only mode is a *preview*: it reports what `scan --apply` *would* prune and clean up, without touching disk. When `scan` runs with no crawl results (e.g., empty project, `node_modules` missing), GC is intentionally skipped and `gc` is emitted as `{ "skipped": true }` to prevent destroying a manifest the user may still want.
+**The `gc` sub-object is omitted entirely when `--prune` (or `--sync`) is not set.** GC information is opt-in — `scan --json` alone is purely about patch discovery and update detection.
 
 ### `scan` — `--apply` mode
 
-When invoked as `scan --json --apply`, the discovery object above is augmented with a top-level `apply` sub-object reporting per-patch outcomes from the download + manifest write, and the `gc` sub-object switches from preview to actual results:
+When invoked as `scan --json --apply`, the discovery object above is augmented with a top-level `apply` sub-object reporting per-patch outcomes from the download + manifest write. The `gc` sub-object is added only when `--prune` (or `--sync`, which implies it) is also set:
 
 ```json
 {
@@ -290,7 +289,25 @@ When invoked as `scan --json --apply`, the discovery object above is augmented w
 }
 ```
 
-With `--no-prune`, the `gc` sub-object is emitted as `{ "skipped": true }` in both read-only and `--apply` modes. GC field names differ between preview (`prunable*`/`orphan*`/`bytesReclaimable`) and apply (`pruned*`/`removed*`/`bytesFreed`) modes — bots should check `gc.prunedManifestEntries` vs `gc.prunableManifestEntries` accordingly.
+Without `--prune` or `--sync`, the `gc` field is **omitted entirely** from the output. When `--prune` is set without `--dry-run`, `gc` uses the apply-mode field names (`prunedManifestEntries`, `removedBlobs`, `removedDiffArchives`, `removedPackageArchives`, `bytesFreed`). With `--dry-run`, it uses preview-mode field names (`prunableManifestEntries`, `orphanBlobs`, `orphanDiffArchives`, `orphanPackageArchives`, `bytesReclaimable`) and nothing is mutated. Bots should branch on which field set is present, not assume a single shape.
+
+### `scan` — `--sync` (bot mode)
+
+`scan --json --sync --yes` is sugar for `scan --json --apply --prune --yes` — the canonical single-command auto-update workflow. Output is the full discovery + `apply` + `gc` shape above. Pipe it into PR-creation tooling:
+
+```bash
+socket-patch scan --json --sync --yes | jq '{
+  applied: [.apply.patches[] | select(.action == "added" or .action == "updated") | .purl],
+  pruned:  .gc.prunedManifestEntries,
+  bytes_freed: .gc.bytesFreed
+}'
+```
+
+Exit `0` on success, `1` if any `apply.patches[*].action == "failed"` (top-level `status` becomes `"partial_failure"`).
+
+### `scan` — `--dry-run`
+
+When combined with `--apply`, `--prune`, or `--sync`, `--dry-run` (`-d`) populates `apply.patches[*]` and `gc.prunable*` / `gc.orphan*` fields with the *would-be* actions without touching disk. The `apply` sub-object in dry-run mode includes a `"dryRun": true` field for bots that need an explicit signal. Without one of the mutating flags, `--dry-run` is a no-op (discovery is already non-mutating).
 
 Per-patch `action` vocabulary is stable:
 
@@ -327,7 +344,8 @@ Versioning lives in **`Cargo.toml`** at the workspace root (`version = "..."`) a
 | Rename a JSON output key or change a `status` string | **MAJOR** |
 | Remove a JSON output key | **MAJOR** |
 | Rename or remove a per-patch `action` value (`added`/`updated`/`skipped`/`failed`) | **MAJOR** |
-| Change `scan`'s default behavior (e.g. pruning, GC, apply) | **MAJOR** — done once in v3.0; future flips also MAJOR. |
+| Change `scan`'s default behavior (e.g. flipping `--prune` to opt-out, or making `--apply` default) | **MAJOR** |
+| Demote `repair`'s `gc` from `visible_alias` to hidden, or remove the `repair` subcommand | **MAJOR** |
 | Drop the bare-UUID fallback | **MAJOR** |
 | Add a *required* new flag | **MAJOR** |
 | Add a new subcommand | **MINOR** |