docs: README overhaul on the Divio model + ecosystems doc split + auth/config alignment#127
Merged
Merged
Conversation
…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 <noreply@anthropic.com>
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 flatted@3.3.1 tutorial). CLI_CONTRACT.md maven service-coverage passage synced to SERVICE_ECOSYSTEMS. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
# 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 <noreply@anthropic.com>
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 <noreply@anthropic.com>
…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 <noreply@anthropic.com>
Wenxin Jiang (Wenxin-Jiang)
approved these changes
Jul 22, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Full documentation pass on the CLI docs, restructured on the Divio documentation model:
--ecosystemsslugs), npm hosted-mode + Rush notes, Maven & NuGet caveats, Cargo shared-registry-cache and Go go.sum sections, and the platform table — moved out of the README so the README stays focused on using the tool.SOCKET_*env >SOCKET_CLI_*alias > socket-cliconfig.json> default),socket loginpickup, and theSOCKET_NO_API_TOKEN/SOCKET_NO_CONFIGtoggles. The anonymous public-proxy path (auth optional for testing certified patches) stays front and center in the tutorial and token docs.SERVICE_ECOSYSTEMS(perservice_mode_gate_admits_maven), so the "not covered by fail-closedservice" sentence was outdated.How it was validated
Six rounds of a multi-agent adversarial review (7–8 independent lenses: fresh-user walkthrough, factual accuracy vs the built binary's
--help+ CLI_CONTRACT, Divio structure, completeness vs the old README, link/anchor integrity, prose, runnable examples, and a dedicated authentication lens), each finding adversarially verified before being fixed. 93+ confirmed defects fixed; raw findings converged 60 → 50 → 27 → 15 → 0 across rounds, with round 5 fully clean before the main merge.Notable factual fixes along the way: an inverted
--strictdefault description,.socket/blob/→blobs/, unimplemented--one-offflags now labeled as stubs, Deno restored to the supported set, the Python hook's PATH-fallback described honestly, a bot jq recipe that hard-failed on empty crawls, and the tutorial demo (flatted@3.3.1) smoke-tested live against the public proxy — every sample output in the docs is genuine binary output.A post-merge review round (including the auth lens) is in flight; any confirmed findings will be pushed to this branch.
🤖 Generated with Claude Code