GeezerVison

…eorder --help

v4 breaking CLI cleanup, part 1:

- Remove the `unlock` subcommand. A leftover apply.lock from a crashed
  run never blocks acquisition (the kernel releases a dead holder's
  advisory lock), so unlock's inspect path had no recovery scenario and
  its --release file deletion is now automatic in repair. The
  patch_unlocked/patch_unlock_failed telemetry events, Command::Unlock
  envelope variant, and SOCKET_UNLOCK_RELEASE are retired with it.

- Remove the global --break-lock flag and SOCKET_BREAK_LOCK. It never
  stole a live holder's lock (deliberately), and stale files never
  contend, so all it did was emit a lock_broken audit event for a
  reclaim plain acquisition performs anyway. acquire_or_emit now
  returns the LockGuard directly; the lock_held hint advises waiting /
  --lock-timeout. rollback's warnings[] stays present, now always
  empty. The never-unlink-while-live invariant survives, pinned by
  acquire_or_emit_preserves_mutual_exclusion.

- repair deletes the leftover apply.lock as its final housekeeping step
  on every completion path (after releasing its own guard; skipped on
  --dry-run; live holders still refused with lock_held exit 1).

- Reorder --help to workflow-first: scan, apply, vex, vendor, setup,
  rollback, get, list, remove, repair.

CHANGELOG carries migration notes under [Unreleased]; the 4.0.0
version-sync is deferred to batch with the remaining breaking changes.

Co-Authored-By: Claude Fable 5 <[email protected]>

README rewritten as pitch → install → five-minute tutorial → explanation →
how-to recipes → full command reference. Ecosystem/mode support matrix,
Maven/NuGet/Rush/Go/Cargo caveats, and platform table move to the new
docs/ecosystems.md. 83 defects fixed across a 5-round adversarial review
(stale claims, inverted --strict default, .socket/blobs/ path, unimplemented
--one-off stubs labeled, live-tested [email protected] tutorial). CLI_CONTRACT.md
maven service-coverage passage synced to SERVICE_ECOSYSTEMS.

Co-Authored-By: Claude Fable 5 <[email protected]>

# Conflicts:
#	README.md
#	crates/socket-patch-cli/tests/cli_parse_apply.rs

Configuration sources subsection under Global options (per-key precedence:
flag > SOCKET_* env > SOCKET_CLI_* alias > socket-cli config.json > default,
config-file locations, SOCKET_NO_API_TOKEN / SOCKET_NO_CONFIG toggles,
read-only + no-.env pledge), socket-login-first --api-token row, anonymous
public-proxy path kept prominent in the tutorial intro, configuration.md
linked from Further reading.

Co-Authored-By: Claude Fable 5 <[email protected]>

Re-nest Configuration sources as an H4 inside Global options after the flags
table (the insert had stranded the table inside the wrong section); fold the
SOCKET_CLI_* aliases into the env-var rung so the ladder matches the
contract's one-extra-layer model; XDG-first config paths on Linux+macOS;
labeled url default; CI authentication paragraph (SOCKET_API_TOKEN secret,
paidRequired fallback behavior, SOCKET_NO_API_TOKEN pin); slimmer --api-token
row; Maven/NuGet experimental-discovery breadcrumb in the tutorial;
socket-patch vs Socket CLI disambiguation and wrap fixes.

Co-Authored-By: Claude Fable 5 <[email protected]>

…ntry failure

Verified against repair.rs: offline mode prints a summary warning for
missing artifacts, records no download events, and exits success.

Co-Authored-By: Claude Fable 5 <[email protected]>