v5: align help and migration docs with lockfile-first scans and service-only vendoring #1289
Copy link
Copy link
Closed
Labels
agent:triagedcompatibilityPublic CLI/JSON, saved state, upgrades, or package-manager compatibility.Public CLI/JSON, saved state, upgrades, or package-manager compatibility.documentationImprovements or additions to documentationImprovements or additions to documentationpriority:p1uxCLI commands, help, diagnostics, output consistency, or actionable recovery instructions.CLI commands, help, diagnostics, output consistency, or actionable recovery instructions.v5-blockerMust resolve before v5: public interface/migration or ordinary patch-install-undo failure.Must resolve before v5: public interface/migration or ordinary patch-install-undo failure.
Description
Activity
- addeddocumentationImprovements or additions to documentationImprovements or additions to documentationv5-blockerMust resolve before v5: public interface/migration or ordinary patch-install-undo failure.Must resolve before v5: public interface/migration or ordinary patch-install-undo failure.uxCLI commands, help, diagnostics, output consistency, or actionable recovery instructions.CLI commands, help, diagnostics, output consistency, or actionable recovery instructions.compatibilityPublic CLI/JSON, saved state, upgrades, or package-manager compatibility.Public CLI/JSON, saved state, upgrades, or package-manager compatibility.
on Oct 9, 2026
Metadata
Metadata
Assignees
Labels
agent:triagedcompatibilityPublic CLI/JSON, saved state, upgrades, or package-manager compatibility.Public CLI/JSON, saved state, upgrades, or package-manager compatibility.documentationImprovements or additions to documentationImprovements or additions to documentationpriority:p1uxCLI commands, help, diagnostics, output consistency, or actionable recovery instructions.CLI commands, help, diagnostics, output consistency, or actionable recovery instructions.v5-blockerMust resolve before v5: public interface/migration or ordinary patch-install-undo failure.Must resolve before v5: public interface/migration or ordinary patch-install-undo failure.
The primary help text still teaches an installed-package/agent-first model, while v5's primary workflow is patching a fresh checkout's lockfiles and then installing.
Verified from the current source and local CLI help:
scan -hsay:Find patches for installed packages and apply them by rewriting lockfiles to Socket-hosted patched packages. A user with only a lockfile is led to think installation is required first.repairAgent mode: download missing patch artifacts and clean up unused ones, and groups it only under agent mode. The v5 usage guide also supports repairing missing/corrupt vendored artifacts.--vendor-source build/SOCKET_VENDOR_SOURCE=buildis now rejected, andautono longer falls back to local builds. The v4 argument parser defaulted toautoand offered local builds; the current usage guide documents service-only acquisition.Sources:
Commandshelp strings, vendored repair documentation.Before v5, make the first-run instructions match the supported workflow:
scanas discovering patches from project dependency/lockfiles, including fresh checkouts; installation is only required where the selected mode/ecosystem actually requires it.scanwrites hosted references andscan --dry-runpreviews them.repairas applicable to existing agent or vendored patch artifacts, while keeping the existing limitation that it cannot recreate a lost vendor ledger.buildvalue/environment configuration,autoalias semantics, no local fallback for missing/pending artifacts, and the distinction between reusing healthy committed artifacts offline and fetching new ones.Filed during the maintainer-requested v5 interface review. This is a small help correction for the normal lockfile workflow, independent of crash recovery or repeated invocation edge cases.