Skip to content

v5: align help and migration docs with lockfile-first scans and service-only vendoring #1289

Description

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:

  • Root help and scan -h say: 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.
  • Root help calls repair Agent 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.
  • The migration guide omits an actual v4 compatibility break: --vendor-source build / SOCKET_VENDOR_SOURCE=build is now rejected, and auto no longer falls back to local builds. The v4 argument parser defaulted to auto and offered local builds; the current usage guide documents service-only acquisition.

Sources: Commands help strings, vendored repair documentation.

Before v5, make the first-run instructions match the supported workflow:

  • Describe scan as discovering patches from project dependency/lockfiles, including fresh checkouts; installation is only required where the selected mode/ecosystem actually requires it.
  • Make it immediately clear that bare scan writes hosted references and scan --dry-run previews them.
  • Describe repair as applicable to existing agent or vendored patch artifacts, while keeping the existing limitation that it cannot recreate a lost vendor ledger.
  • Keep root, short, and long help consistent with the README/migration guide. No command renaming or new behavior is required.
  • Add service-only vendoring to the v5 migration guide: removed build value/environment configuration, auto alias 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.

Activity

  1. added
    documentationImprovements or additions to documentation
    v5-blockerMust resolve before v5: public interface/migration or ordinary patch-install-undo failure.
    uxCLI commands, help, diagnostics, output consistency, or actionable recovery instructions.
    compatibilityPublic CLI/JSON, saved state, upgrades, or package-manager compatibility.
    on Oct 9, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    agent:triagedcompatibilityPublic CLI/JSON, saved state, upgrades, or package-manager compatibility.documentationImprovements or additions to documentationpriority:p1uxCLI commands, help, diagnostics, output consistency, or actionable recovery instructions.v5-blockerMust resolve before v5: public interface/migration or ordinary patch-install-undo failure.

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions