From 6e96a97a1d63c7126d307aacb3f11759e9f4db48 Mon Sep 17 00:00:00 2001
From: jettwang <jamiesun.net@gmail.com>
Date: Wed, 23 Sep 2026 15:16:44 +0800
Subject: [PATCH 1/4] ci(lint): pin golangci-lint v2.13.2 and use v2 exclusions
 schema

The Lint gate aborted inside `golangci-lint config verify` before analysing any
Go file: `.golangci.yml` kept the v1-era `issues.exclude-rules` key while
declaring `version: "2"`, and `golangci-lint-action@v7` floated on
`version: latest`, so the schema that rejected the file was whatever the runner
downloaded that day. The job has been failing since 25a45f3 (2026-09-16).

- `.golangci.yml`: move the exclusion to the v2 location
  (`linters.exclusions.rules`), keeping the same `text`/`linters` fields and the
  enabled linter set unchanged.
- `.github/workflows/ci.yml`: pin the linter to the released v2.13.2 so an
  upstream release cannot flip this gate on its own.

Verified with the pinned binary and the local one (2.12.2): `config verify`
exits 0 and `golangci-lint run --timeout=5m` reports 0 issues.

Fixes #82

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 .github/workflows/ci.yml | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 8bf39f2..538538d 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -251,7 +251,9 @@ jobs:
       - name: Run golangci-lint
         uses: golangci/golangci-lint-action@v7
         with:
-          version: latest
+          # Pinned deliberately: `latest` silently changed the linter and broke
+          # this gate (see issue #82). Bump this together with .golangci.yml.
+          version: v2.13.2
           args: --timeout=5m
 
   security:

From 953aeeaf6097fbd78f41a86257b7fcbe53e4bc5b Mon Sep 17 00:00:00 2001
From: jettwang <jamiesun.net@gmail.com>
Date: Wed, 23 Sep 2026 15:17:50 +0800
Subject: [PATCH 2/4] test(sshclient): make the privileged apply fixture
 deterministic

`TestApplySudoScriptEvidenceAndCleanup` failed at different assertion sites on
different runs in some environments (15/16 package runs reported): nil-pointer
panics on `*outcome.Executed`, digest mismatches, and wrong error kinds, with
`sh: line 25: printf: write error: Broken pipe` in the fixture output.

The fixture piped the generated script through the child's stdin and captured
stdout/stderr into `bytes.Buffer` values, which makes `os/exec` add pipes and
copier goroutines; a child that finishes while a copier unwinds can see
EPIPE/SIGPIPE and report a truncated privileged result instead of the behavior
under test.

- Run the script from a file (`sh <script>`) with stdout/stderr going to real
  files in the owned fixture directory, then read them back. No stdin pipe, no
  copier goroutines.
- Add `requireApplyOutcome` / `requireApplyExecuted`, which print the captured
  evidence and the parse error, and route every `*outcome.Executed` dereference
  through them, so a truncated report fails readably instead of panicking.
- Keep all nine subtests and the truncated-report manipulation; the "rename"
  subtest still asserts unknown (`nil`) publication evidence explicitly.

Verified: `go test ./internal/sshclient/ -count=20`,
`-count=5 -short -race`, and the isolated `after` subtest repeated.

Fixes #83

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 internal/sshclient/apply_sudo_test.go | 79 +++++++++++++++++++++------
 1 file changed, 62 insertions(+), 17 deletions(-)

diff --git a/internal/sshclient/apply_sudo_test.go b/internal/sshclient/apply_sudo_test.go
index b195e37..1d85a43 100644
--- a/internal/sshclient/apply_sudo_test.go
+++ b/internal/sshclient/apply_sudo_test.go
@@ -1,7 +1,6 @@
 package sshclient
 
 import (
-	"bytes"
 	"encoding/json"
 	"errors"
 	"os"
@@ -66,44 +65,46 @@ func TestApplySudoScriptEvidenceAndCleanup(t *testing.T) {
 			}
 			result := runApplyScriptFixture(t, script, env)
 			outcome, applyErr := parseApplyScriptReport(result)
-			require.NotNil(t, outcome, "%s; %s; %v", result.Stdout, result.Stderr, applyErr)
+			requireApplyOutcome(t, test, result, outcome, applyErr)
 			require.Equal(t, SHA256Hex(before), outcome.BeforeSHA256)
 			require.Equal(t, SHA256Hex(payload), outcome.PayloadSHA256)
-			require.NotNil(t, outcome.UID)
-			require.NotNil(t, outcome.GID)
+			require.NotNil(t, outcome.UID, "%s: uid evidence missing: %s", test, result.Stdout)
+			require.NotNil(t, outcome.GID, "%s: gid evidence missing: %s", test, result.Stdout)
 			require.Equal(t, "640", outcome.Mode)
 			switch test {
 			case "precondition":
 				require.ErrorIs(t, applyErr, ErrPrecondition)
-				require.False(t, *outcome.Executed)
+				require.False(t, requireApplyExecuted(t, test, result, outcome, applyErr))
 				require.Empty(t, outcome.BackupPath)
 			case "before":
 				require.Error(t, applyErr)
-				require.False(t, *outcome.Executed)
+				require.False(t, requireApplyExecuted(t, test, result, outcome, applyErr))
 				require.Equal(t, "unchanged", outcome.ChangeState)
 				require.True(t, outcome.BackupVerified)
 			case "after":
 				require.ErrorIs(t, applyErr, ErrApplyVerification)
-				require.True(t, *outcome.Executed)
+				require.True(t, requireApplyExecuted(t, test, result, outcome, applyErr))
 				require.Equal(t, "changed", outcome.ChangeState)
 				require.Equal(t, SHA256Hex([]byte("other writer\n")), outcome.AfterSHA256)
 				require.False(t, outcome.Verified)
 			case "rename":
 				require.ErrorIs(t, applyErr, ErrApplyVerification)
-				require.Nil(t, outcome.Executed)
+				// Publication was attempted without acknowledgement, so the report must
+				// stay unknown rather than claim the target was never published.
+				require.Nil(t, outcome.Executed, "%s: publication evidence must be unknown: %s", test, result.Stdout)
 				require.Equal(t, "unknown", outcome.ChangeState)
 			case "recheck":
 				require.ErrorIs(t, applyErr, ErrPrecondition)
 				require.Equal(t, "failed", outcome.PreconditionStatus)
 				require.Equal(t, SHA256Hex([]byte("other writer\n")), outcome.PreconditionSHA256)
-				require.False(t, *outcome.Executed)
+				require.False(t, requireApplyExecuted(t, test, result, outcome, applyErr))
 				require.True(t, outcome.BackupVerified)
 				require.Equal(t, "unchanged", outcome.ChangeState)
 			default:
 				require.NoError(t, applyErr, "%s", result.Stderr)
 				require.True(t, outcome.Verified)
 				require.Equal(t, SHA256Hex(payload), outcome.AfterSHA256)
-				require.Equal(t, test != "noop", *outcome.Executed)
+				require.Equal(t, test != "noop", requireApplyExecuted(t, test, result, outcome, applyErr))
 			}
 			if test != "precondition" && test != "noop" {
 				require.True(t, outcome.BackupVerified)
@@ -129,7 +130,7 @@ func TestApplySudoScriptEvidenceAndCleanup(t *testing.T) {
 				result.Stdout, result.ExitCode = strings.Join(lines[:len(lines)-1], "\n"), -1
 				partial, lostErr := parseApplyScriptReport(result)
 				require.ErrorIs(t, lostErr, ErrApplyVerification)
-				require.True(t, *partial.Executed)
+				require.True(t, requireApplyExecuted(t, "replace (truncated report)", result, partial, lostErr))
 				require.Equal(t, "changed", partial.ChangeState)
 				require.True(t, partial.BackupVerified)
 				require.False(t, partial.Verified)
@@ -165,19 +166,56 @@ func applyScriptEnv(env []string) []string {
 	return out
 }
 
+// runApplyScriptFixture runs the generated privileged script the way the remote
+// host does: as a script file, with the child's stdout and stderr going to real
+// files. Piping the script through the child's stdin or capturing it into
+// bytes.Buffer values makes os/exec add pipes and copier goroutines, and a child
+// that finishes while a copier unwinds can then observe EPIPE/SIGPIPE and report
+// a truncated privileged result instead of the behavior under test (issue #83).
 func runApplyScriptFixture(t *testing.T, script []byte, env []string) ExecResult {
 	t.Helper()
-	var stdout, stderr bytes.Buffer
-	cmd := exec.Command("sh") // #nosec G204 -- executes only the generated apply script in the owned fixture directory.
-	cmd.Stdin, cmd.Stdout, cmd.Stderr, cmd.Env = bytes.NewReader(script), &stdout, &stderr, applyScriptEnv(env)
+	dir := t.TempDir()
+	scriptPath := filepath.Join(dir, "apply.sh")
+	require.NoError(t, os.WriteFile(scriptPath, script, 0o700)) // #nosec G306 -- owned fixture script.
+	stdoutPath, stderrPath := filepath.Join(dir, "stdout"), filepath.Join(dir, "stderr")
+	stdout, createErr := os.Create(stdoutPath) // #nosec G304 -- path is confined to the owned fixture directory.
+	require.NoError(t, createErr)
+	stderr, createErr := os.Create(stderrPath) // #nosec G304 -- path is confined to the owned fixture directory.
+	require.NoError(t, createErr)
+	cmd := exec.Command("sh", scriptPath) // #nosec G204 -- executes only the generated apply script in the owned fixture directory.
+	cmd.Stdout, cmd.Stderr, cmd.Env = stdout, stderr, applyScriptEnv(env)
 	err := cmd.Run()
+	require.NoError(t, stdout.Close())
+	require.NoError(t, stderr.Close())
 	code := 0
 	if err != nil {
 		var exit *exec.ExitError
 		require.True(t, errors.As(err, &exit), "%v", err)
 		code = exit.ExitCode()
 	}
-	return ExecResult{ExitCode: code, Stdout: stdout.String(), Stderr: stderr.String(), Started: true, ExitObserved: true}
+	out, readErr := os.ReadFile(stdoutPath) // #nosec G304 -- path is confined to the owned fixture directory.
+	require.NoError(t, readErr)
+	errOut, readErr := os.ReadFile(stderrPath) // #nosec G304 -- path is confined to the owned fixture directory.
+	require.NoError(t, readErr)
+	return ExecResult{ExitCode: code, Stdout: string(out), Stderr: string(errOut), Started: true, ExitObserved: true}
+}
+
+// requireApplyOutcome reports a missing privileged report with the fixture's
+// captured evidence instead of panicking on a nil pointer: a truncated report
+// must fail the subtest readably, not abort the package run (issue #83).
+func requireApplyOutcome(t *testing.T, stage string, result ExecResult, outcome *ApplyOutcome, parseErr error) *ApplyOutcome {
+	t.Helper()
+	require.NotNil(t, outcome, "%s: no privileged report: exit %d; stdout %q; stderr %q; parse error %v", stage, result.ExitCode, result.Stdout, result.Stderr, parseErr)
+	return outcome
+}
+
+// requireApplyExecuted returns the publication evidence without dereferencing a
+// nil pointer: an absent or truncated report must fail the subtest readably.
+func requireApplyExecuted(t *testing.T, stage string, result ExecResult, outcome *ApplyOutcome, parseErr error) bool {
+	t.Helper()
+	requireApplyOutcome(t, stage, result, outcome, parseErr)
+	require.NotNil(t, outcome.Executed, "%s: publication evidence missing: exit %d; stdout %q; stderr %q; parse error %v", stage, result.ExitCode, result.Stdout, result.Stderr, parseErr)
+	return *outcome.Executed
 }
 
 func TestApplySudoCreatesEmptyAndDoesNotRemoveUnownedTemp(t *testing.T) {
@@ -193,6 +231,7 @@ func TestApplySudoCreatesEmptyAndDoesNotRemoveUnownedTemp(t *testing.T) {
 	require.NoError(t, err)
 	result := runApplyScriptFixture(t, script, os.Environ())
 	outcome, parseErr := parseApplyScriptReport(result)
+	requireApplyOutcome(t, "empty", result, outcome, parseErr)
 	require.NoError(t, parseErr, "%s", result.Stderr)
 	require.True(t, outcome.Created)
 	require.True(t, outcome.Verified)
@@ -210,8 +249,9 @@ func TestApplySudoCreatesEmptyAndDoesNotRemoveUnownedTemp(t *testing.T) {
 	require.NoError(t, err)
 	result = runApplyScriptFixture(t, script, os.Environ())
 	outcome, parseErr = parseApplyScriptReport(result)
+	requireApplyOutcome(t, "unowned temp", result, outcome, parseErr)
 	require.Error(t, parseErr)
-	require.False(t, *outcome.Executed)
+	require.False(t, requireApplyExecuted(t, "unowned temp", result, outcome, parseErr))
 	retained, readErr := os.ReadFile(unowned) // #nosec G304 -- path is confined to the owned test fixture.
 	require.NoError(t, readErr)
 	require.Equal(t, "do not remove", string(retained))
@@ -247,6 +287,7 @@ func TestApplySudoReportStrictValidation(t *testing.T) {
 	}
 	partial, nonzeroErr := parseApplyScriptReport(ExecResult{ExitCode: 1, Stdout: string(valid)})
 	require.ErrorIs(t, nonzeroErr, ErrApplyVerification)
+	require.NotNil(t, partial, "%v", nonzeroErr)
 	require.Equal(t, report.Before, partial.BeforeSHA256)
 	require.Equal(t, report.After, partial.AfterSHA256)
 	require.False(t, partial.Verified)
@@ -255,8 +296,10 @@ func TestApplySudoReportStrictValidation(t *testing.T) {
 	require.NoError(t, err)
 	partial, parseErr := parseApplyScriptReport(ExecResult{ExitCode: -1, Stdout: string(progress) + "\n{\"status\":"})
 	require.ErrorIs(t, parseErr, ErrApplyVerification)
+	require.NotNil(t, partial, "%v", parseErr)
 	require.Equal(t, report.Before, partial.BeforeSHA256)
 	require.Equal(t, report.After, partial.AfterSHA256)
+	require.NotNil(t, partial.Executed, "%v", parseErr)
 	require.True(t, *partial.Executed)
 }
 
@@ -264,6 +307,7 @@ func TestApplySudoUnacknowledgedScriptStartIsUnknown(t *testing.T) {
 	req := ApplyRequest{RemotePath: "/app.conf", Payload: []byte("new")}
 	outcome, err := applySudoOutcome(req, ExecResult{ExitCode: -1, StartAttempted: true})
 	require.ErrorIs(t, err, ErrApplyVerification)
+	require.NotNil(t, outcome, "%v", err)
 	require.Nil(t, outcome.Executed)
 	require.Equal(t, "unknown", outcome.ChangeState)
 	require.Equal(t, "unknown", outcome.Verification)
@@ -271,7 +315,8 @@ func TestApplySudoUnacknowledgedScriptStartIsUnknown(t *testing.T) {
 
 	outcome, err = applySudoOutcome(req, ExecResult{ExitCode: -1})
 	require.Error(t, err)
-	require.NotNil(t, outcome.Executed)
+	require.NotNil(t, outcome, "%v", err)
+	require.NotNil(t, outcome.Executed, "%v", err)
 	require.False(t, *outcome.Executed)
 	require.Equal(t, "unchanged", outcome.ChangeState)
 }

From fa19ef886932e23a9a415cc6aa6799808e77acfe Mon Sep 17 00:00:00 2001
From: jettwang <jamiesun.net@gmail.com>
Date: Wed, 23 Sep 2026 15:17:50 +0800
Subject: [PATCH 3/4] fix(sshclient): remove apply temps without a
 PATH-resolved rm

`sshx apply` cleaned its staging payload, publication temp, and unverified
backup with a bare `rm -f`. On a host where `rm` resolves to a wrapper earlier
in PATH that moves files to the Trash (routinely done on macOS), every apply
leaked a byte-identical copy of the payload while the privileged report still
claimed a clean run.

- Try an absolute remover (`/bin/rm`, `/usr/bin/rm`, `/usr/local/bin/rm`), then
  POSIX `unlink`, and only then PATH `rm`, so a shim cannot absorb the artifact
  when an absolute remover exists.
- Success now means the path is gone (`[ ! -e ] && [ ! -L ]`), not that some
  remover returned 0.
- Unchanged evidence semantics: a removal that cannot complete still reports
  `cleanup_pending`, exit 4, and `status=remote_io` / "artifact cleanup failed",
  and only sshx-created paths are ever removed.

New `TestApplyCleanupDoesNotDependOnPathRm` shadows `rm` with a fake trash-mover
and covers a published apply, a failed publication temp, an unverified backup,
and an unremovable artifact. It fails against the previous helper on all three
leak subtests.

Fixes #79

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 internal/sshclient/apply.go              |  18 +-
 internal/sshclient/apply_cleanup_test.go | 228 +++++++++++++++++++++++
 2 files changed, 242 insertions(+), 4 deletions(-)
 create mode 100644 internal/sshclient/apply_cleanup_test.go

diff --git a/internal/sshclient/apply.go b/internal/sshclient/apply.go
index aef5a3d..762e474 100644
--- a/internal/sshclient/apply.go
+++ b/internal/sshclient/apply.go
@@ -774,11 +774,21 @@ if [ -n "$EXPECT" ] && [ "$FORCE" = "1" ]; then precondition_status=bypassed; fi
 report() {
   printf '{"status":"%%s","changed":%%s,"created":%%s,"before":"%%s","after":"%%s","backup":"%%s","mode":"%%s","payload":"%%s","executed":%%s,"change_state":"%%s","verified":%%s,"verification":"%%s","backup_verified":%%s,"uid":%%s,"gid":%%s,"cleanup_pending":[%%s],"error":"%%s","replace_method":"%%s","precondition_status":"%%s","precondition_sha256":"%%s"}\n' "$status" "$changed" "$created" "$before" "$after" "$backup" "$mode" "$PAYLOAD_SHA" "$executed" "$change_state" "$verified" "$verification" "$backup_verified" "$uid" "$gid" "$cleanup_pending" "$error" "$replace_method" "$precondition_status" "$precondition_sha256"
 }
+# remove_owned deletes one sshx-owned artifact without trusting a PATH rm: a
+# wrapper named rm earlier in PATH could keep a copy of the payload behind (for
+# example one that moves files to the Trash). An absolute remover is tried
+# first so such a wrapper is bypassed on hosts that have one; POSIX unlink and
+# PATH rm remain as fallbacks, and success means the path is gone rather than
+# merely claimed removed.
 remove_owned() {
-  if ! rm -f "$1"; then
-    cleanup_pending="$cleanup_pending${cleanup_pending:+,}\"$1\""
-    return 1
-  fi
+  if [ ! -e "$1" ] && [ ! -L "$1" ]; then return 0; fi
+  for remover in /bin/rm /usr/bin/rm /usr/local/bin/rm; do
+    if [ -x "$remover" ] && "$remover" -f "$1" && [ ! -e "$1" ] && [ ! -L "$1" ]; then return 0; fi
+  done
+  if command -v unlink >/dev/null 2>&1 && unlink "$1" && [ ! -e "$1" ] && [ ! -L "$1" ]; then return 0; fi
+  if command -v rm >/dev/null 2>&1 && rm -f "$1" && [ ! -e "$1" ] && [ ! -L "$1" ]; then return 0; fi
+  cleanup_pending="$cleanup_pending${cleanup_pending:+,}\"$1\""
+  return 1
 }
 finish() {
   rc=$?
diff --git a/internal/sshclient/apply_cleanup_test.go b/internal/sshclient/apply_cleanup_test.go
new file mode 100644
index 0000000..3f5f028
--- /dev/null
+++ b/internal/sshclient/apply_cleanup_test.go
@@ -0,0 +1,228 @@
+package sshclient
+
+import (
+	"os"
+	"os/exec"
+	"path/filepath"
+	"runtime"
+	"strings"
+	"testing"
+
+	"github.com/stretchr/testify/require"
+)
+
+// TestApplyCleanupDoesNotDependOnPathRm reproduces the reported leak where a host
+// resolves rm through a wrapper earlier in PATH that moves files to the Trash
+// instead of unlinking them: every apply left a byte-identical copy of the
+// applied payload in the target user's Trash while the privileged report still
+// claimed a clean run, because remove_owned() deleted sshx-owned artifacts with
+// a bare `rm -f`.
+//
+// buildApplySudoScript is the only apply script builder in this package. The SFTP
+// apply path (applySFTPFile) removes its temporaries over SFTP rather than through
+// a remote shell, so it has no PATH-dependent cleanup to cover here.
+func TestApplyCleanupDoesNotDependOnPathRm(t *testing.T) {
+	if runtime.GOOS == "windows" {
+		t.Skip("the privileged remote script requires a POSIX shell")
+	}
+	requireAbsoluteRemover(t)
+
+	t.Run("published", func(t *testing.T) {
+		fixture := newApplyCleanupFixture(t)
+		result := fixture.run(t, fixture.env())
+		outcome, applyErr := parseApplyScriptReport(result)
+		requireApplyOutcome(t, "published", result, outcome, applyErr)
+		require.NoError(t, applyErr, "%s", result.Stderr)
+		require.True(t, outcome.Verified)
+		require.NoFileExists(t, fixture.staging, "the staging payload must be removed")
+		fixture.requireNoOwnedTemp(t)
+		fixture.requireNoTrashLeak(t)
+		require.NotEmpty(t, outcome.BackupPath)
+		require.FileExists(t, outcome.BackupPath, "a verified backup must be preserved")
+	})
+
+	t.Run("temp candidate", func(t *testing.T) {
+		fixture := newApplyCleanupFixture(t)
+		fixture.shadow(t, "chmod", "case \"$2\" in *.sshx.*) exit 9;; esac\nexec '"+realCommand(t, "chmod")+"' \"$@\"\n")
+		result := fixture.run(t, fixture.env())
+		outcome, applyErr := parseApplyScriptReport(result)
+		requireApplyOutcome(t, "temp candidate", result, outcome, applyErr)
+		require.Error(t, applyErr, "%s", result.Stderr)
+		require.NotZero(t, result.ExitCode, "%s", result.Stderr)
+		require.NoFileExists(t, fixture.tempCandidate(), "the publication temp candidate must be removed")
+		require.NoFileExists(t, fixture.staging, "the staging payload must be removed")
+		fixture.requireNoOwnedTemp(t)
+		fixture.requireNoTrashLeak(t)
+		require.Empty(t, outcome.CleanupPending, "a successful cleanup must not be reported as pending")
+		require.NotEmpty(t, outcome.BackupPath)
+		require.FileExists(t, outcome.BackupPath, "a verified backup must be preserved")
+	})
+
+	t.Run("unverified backup", func(t *testing.T) {
+		fixture := newApplyCleanupFixture(t)
+		fixture.shadow(t, "chmod", "case \"$2\" in '"+fixture.backupDir+"'/*) exit 9;; esac\nexec '"+realCommand(t, "chmod")+"' \"$@\"\n")
+		result := fixture.run(t, fixture.env())
+		outcome, applyErr := parseApplyScriptReport(result)
+		requireApplyOutcome(t, "unverified backup", result, outcome, applyErr)
+		require.Error(t, applyErr, "%s", result.Stderr)
+		require.NotZero(t, result.ExitCode, "%s", result.Stderr)
+		require.NotEmpty(t, outcome.BackupPath)
+		require.NoFileExists(t, outcome.BackupPath, "an unverified backup must be removed")
+		entries, listErr := os.ReadDir(fixture.backupDir)
+		require.NoError(t, listErr)
+		require.Empty(t, entries)
+		require.NoFileExists(t, fixture.staging, "the staging payload must be removed")
+		fixture.requireNoOwnedTemp(t)
+		fixture.requireNoTrashLeak(t)
+		require.Empty(t, outcome.CleanupPending, "a successful cleanup must not be reported as pending")
+	})
+
+	t.Run("unremovable artifact", func(t *testing.T) {
+		if os.Geteuid() == 0 {
+			t.Skip("running as root: directory permissions do not prevent removal")
+		}
+		fixture := newApplyCleanupFixture(t)
+		stagingDir := filepath.Dir(fixture.staging)
+		require.NoError(t, os.Chmod(stagingDir, 0o500)) // #nosec G302 -- directory fixture, not a secret file.
+		t.Cleanup(func() {
+			_ = os.Chmod(stagingDir, 0o700) //nolint:errcheck,gosec // restore so t.TempDir cleanup can remove the tree.
+		})
+		result := fixture.run(t, fixture.env())
+		outcome, applyErr := parseApplyScriptReport(result)
+		requireApplyOutcome(t, "unremovable artifact", result, outcome, applyErr)
+		require.Equal(t, 4, result.ExitCode, "%s", result.Stderr)
+		require.ErrorContains(t, applyErr, "artifact cleanup failed")
+		require.Equal(t, []string{fixture.staging}, outcome.CleanupPending,
+			"an artifact that cannot be removed must be reported instead of hidden")
+		require.FileExists(t, fixture.staging, "a failed removal must leave the artifact in place")
+		// The payload itself was published and verified; the invocation still fails
+		// because an owned artifact leaked.
+		published, readErr := os.ReadFile(fixture.target) // #nosec G304 -- path is confined to the owned test fixture.
+		require.NoError(t, readErr)
+		require.Equal(t, fixture.payload, published)
+		require.True(t, outcome.Verified)
+		fixture.requireNoTrashLeak(t)
+	})
+}
+
+// applyCleanupFixture is an apply fixture whose PATH resolves rm to a wrapper that
+// moves every argument into a fake Trash directory and never unlinks anything.
+type applyCleanupFixture struct {
+	dir       string
+	binDir    string
+	trashDir  string
+	staging   string
+	target    string
+	backupDir string
+	before    []byte
+	payload   []byte
+}
+
+func newApplyCleanupFixture(t *testing.T) *applyCleanupFixture {
+	t.Helper()
+	fixture := &applyCleanupFixture{
+		dir:     t.TempDir(),
+		before:  []byte("before\n"),
+		payload: []byte("after\n"),
+	}
+	fixture.binDir = filepath.Join(fixture.dir, "bin")
+	fixture.trashDir = filepath.Join(fixture.dir, "trash")
+	fixture.staging = filepath.Join(fixture.dir, "staging", "stage.new")
+	fixture.target = filepath.Join(fixture.dir, "app.conf")
+	fixture.backupDir = filepath.Join(fixture.dir, "backups")
+	for _, dir := range []string{fixture.binDir, fixture.trashDir, filepath.Dir(fixture.staging)} {
+		require.NoError(t, os.MkdirAll(dir, 0o700))
+	}
+	require.NoError(t, os.WriteFile(fixture.target, fixture.before, 0o640)) // #nosec G306 -- fixture mirrors a group-readable config file.
+	require.NoError(t, os.WriteFile(fixture.staging, fixture.payload, 0o600))
+	fixture.shadow(t, "rm", "mkdir -p '"+fixture.trashDir+"'\n"+
+		"for argument in \"$@\"; do\n"+
+		"  case \"$argument\" in -*) continue ;; esac\n"+
+		"  if [ -e \"$argument\" ] || [ -L \"$argument\" ]; then mv \"$argument\" \""+fixture.trashDir+"/${argument##*/}.new\" || exit 1; fi\n"+
+		"done\n"+
+		"exit 0\n")
+	// The fixture only proves anything while the wrapper really is the rm the
+	// generated script resolves through PATH.
+	require.Equal(t, filepath.Join(fixture.binDir, "rm"), fixture.resolvedRm(t))
+	return fixture
+}
+
+// shadow installs an executable stand-in for one command ahead of PATH.
+func (f *applyCleanupFixture) shadow(t *testing.T, name, body string) {
+	t.Helper()
+	require.NoError(t, os.WriteFile(filepath.Join(f.binDir, name), []byte("#!/bin/sh\n"+body), 0o700)) // #nosec G306 -- owned executable fault fixture.
+}
+
+// env is the environment the generated script runs with: the shadowing directory
+// first, exactly like a host whose PATH prefers a wrapper over /bin/rm.
+func (f *applyCleanupFixture) env() []string {
+	return append(os.Environ(), "PATH="+f.binDir+string(os.PathListSeparator)+os.Getenv("PATH"))
+}
+
+func (f *applyCleanupFixture) resolvedRm(t *testing.T) string {
+	t.Helper()
+	cmd := exec.Command("sh", "-c", "command -v rm") // #nosec G204 -- fixed command string, no caller input.
+	cmd.Env = applyScriptEnv(f.env())
+	out, err := cmd.Output()
+	require.NoError(t, err)
+	return strings.TrimSpace(string(out))
+}
+
+func (f *applyCleanupFixture) run(t *testing.T, env []string) ExecResult {
+	t.Helper()
+	req := ApplyRequest{RemotePath: f.target, Payload: f.payload, Backup: true, ExpectSHA256: SHA256Hex(f.before)}
+	script, err := buildApplySudoScript(req, f.staging, f.backupDir)
+	require.NoError(t, err)
+	return runApplyScriptFixture(t, script, env)
+}
+
+// tempCandidate mirrors the script's same-directory publication temp.
+func (f *applyCleanupFixture) tempCandidate() string {
+	return filepath.Join(f.dir, "."+filepath.Base(f.target)+".sshx."+filepath.Base(f.staging)+".tmp")
+}
+
+func (f *applyCleanupFixture) requireNoOwnedTemp(t *testing.T) {
+	t.Helper()
+	entries, err := os.ReadDir(f.dir)
+	require.NoError(t, err)
+	for _, entry := range entries {
+		require.NotContains(t, entry.Name(), ".sshx.", "owned temp must be cleaned")
+	}
+}
+
+// requireNoTrashLeak is the regression assertion: cleanup must not resolve rm
+// through PATH, so the wrapper must never be handed an owned artifact.
+func (f *applyCleanupFixture) requireNoTrashLeak(t *testing.T) {
+	t.Helper()
+	entries, err := os.ReadDir(f.trashDir)
+	require.NoError(t, err)
+	leaked := make([]string, 0, len(entries))
+	for _, entry := range entries {
+		leaked = append(leaked, entry.Name())
+	}
+	require.Empty(t, leaked, "cleanup resolved rm through PATH and moved owned artifacts to the Trash: %v", leaked)
+}
+
+// realCommand resolves a command without the fixture's shadowing directory.
+func realCommand(t *testing.T, name string) string {
+	t.Helper()
+	resolved, err := exec.LookPath(name)
+	require.NoError(t, err)
+	return resolved
+}
+
+// requireAbsoluteRemover skips when this host offers neither the absolute rm
+// candidates nor unlink that the generated script relies on: without either, a
+// PATH-independent cleanup cannot be exercised at all.
+func requireAbsoluteRemover(t *testing.T) {
+	t.Helper()
+	for _, candidate := range []string{"/bin/rm", "/usr/bin/rm", "/usr/local/bin/rm"} {
+		if info, err := os.Stat(candidate); err == nil && !info.IsDir() && info.Mode()&0o111 != 0 {
+			return
+		}
+	}
+	if _, err := exec.LookPath("unlink"); err == nil {
+		return
+	}
+	t.Skip("no absolute rm and no unlink on this host: PATH-independent cleanup cannot be exercised")
+}

From e5bf6440aa309324d1df4e6e244540d6256f7b64 Mon Sep 17 00:00:00 2001
From: jettwang <jamiesun.net@gmail.com>
Date: Wed, 23 Sep 2026 15:18:24 +0800
Subject: [PATCH 4/4] feat(cli): per-verb help, notice policy, SQL input, and
 plugin install

A batch of CLI-contract fixes and one provisioning feature, all on the
execution surface Agents use.

- #84 Per-verb help: every subcommand answers `sshx <verb> --help` instead of
  reporting `--help` as an unknown option, and `--help --json` emits the same
  blocks as an `sshx.help.v1` document (`sshx text --help --json` keeps its
  structured `sshx.text.help.v1` document). The help text now lives once in
  `internal/app/usage_sections.go` and is composed for both the global and the
  per-verb surface, so the two cannot drift. `--help` is answered in option
  position in any order, before any host resolution, connection, or trust-store
  write (a usage request previously connected and could record a host key).
- #85 Compatibility mode rejects an unrecognized option instead of forwarding it
  as part of the remote command, names the offending token, suggests the
  intended option when one is close, and explains the `--` separator. The
  guessed `--local`/`--remote` transfer options name the real surface
  (`--upload=<local> --to=<remote>`), a missing upload/download destination
  names `--to`, and the documented `--ssh-password-key=` is now accepted.
- #86 `--quiet` (`--no-notices`) suppresses human notices on stderr, so a caller
  that merges streams (`2>&1`) under `--json` still reads exactly one parseable
  document in both the success and the failure path. stdout, the exit code, and
  the JSON result are unchanged. Documented in docs/contract.md.
- #87 `sshx sql` takes the statement from a positional argument, after `--`,
  from `--statement-file=PATH`, or from piped stdin, and a statement that opens
  with a SQL comment is statement text rather than an "unknown option".
  Option-shaped typos are still rejected, and the SQL guard stays fail-closed:
  a statement from a file or stdin goes through the identical classifier.
- #78 `sshx run --target=` resolves the sudo keyring reference per host, exactly
  as single-target verbs do: an explicit `-pk` still wins, but the built-in
  `master` default no longer shadows a host's `sudo_password_key`. The rule is
  expressed once (`execution.SudoKeyForTarget`) and used by the plan, the SSH
  client, the keyring lookup, and the audit trail; each target's audit event
  names the credential it used, and the run summary records only a caller-level
  choice instead of misreporting the default.
- #88 `sshx plugin install <dir> [--replace] [--trust]` provisions an existing
  local plugin directory through the audited CLI: it stages the source with
  sshx's own modes, validates it through the executor's loader before touching
  the published plugin, refuses symlinks and non-regular entries, bounds the
  copy (8MiB, 128 files), and can record the published digest in the same step.
  `plugin list` groups built-in capabilities and local plugins, always names the
  local plugin root (so "none installed" is visible), reports provenance/trust/
  validity/digest, skips staging directories left by an interrupted install, and
  a missing plugin names the directory that was searched. A publication that
  cannot be renamed swaps the previous plugin back in or reports where the
  recovery copy was kept.

Docs stay in lock-step: usage text, README.md, README_CN.md,
CHANGELOG [Unreleased], docs/contract.md, docs/roadmap.md, and the bundled Agent
skill.

Verification: make check (fmt, vet, full suite including the compiled-binary
E2E), go test -race ./internal/... ./pkg/..., make test-e2e,
golangci-lint run --timeout=5m (0 issues), plus a behavioural sweep that
reproduces each issue's original symptom.

Fixes #78
Fixes #84
Fixes #85
Fixes #86
Fixes #87
Fixes #88

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 CHANGELOG.md                          |  86 ++-
 README.md                             |  22 +-
 README_CN.md                          |   8 +-
 docs/contract.md                      |  18 +-
 docs/roadmap.md                       |   4 +-
 internal/app/agentmode_test.go        |  53 ++
 internal/app/app.go                   |  19 +-
 internal/app/audit.go                 |   7 +-
 internal/app/cli_surface_test.go      | 202 ++++++
 internal/app/config.go                | 363 +++++++++-
 internal/app/config_test.go           |   2 +-
 internal/app/diagnostics.go           |  13 +
 internal/app/dryrun.go                |  64 +-
 internal/app/lifecycle.go             |   6 +-
 internal/app/lifecycle_policy_test.go |  27 +
 internal/app/mcp.go                   |   7 +-
 internal/app/plan.go                  |   2 +-
 internal/app/plan_admission_test.go   |  14 +-
 internal/app/plugin.go                |  89 ++-
 internal/app/run.go                   |  39 +-
 internal/app/sql.go                   |   2 +-
 internal/app/text.go                  |   3 +-
 internal/app/text_progress_test.go    |  13 +-
 internal/app/usage.go                 | 914 +++++---------------------
 internal/app/usage_sections.go        | 884 +++++++++++++++++++++++++
 internal/app/usage_test.go            |  72 ++
 internal/execution/executor.go        |  17 +-
 internal/execution/selector_test.go   |  27 +
 internal/plugin/install.go            | 225 +++++++
 internal/plugin/install_test.go       | 310 +++++++++
 internal/plugin/store.go              |  32 +-
 internal/plugin/templates.go          |  34 +-
 internal/plugin/types.go              |   3 +
 internal/sshclient/client.go          |  26 +-
 skills/sshx/SKILL.md                  |  25 +
 tests/e2e/host_audit_e2e_test.go      |  85 +++
 tests/e2e/inspect_plugin_e2e_test.go  | 159 +++++
 37 files changed, 3018 insertions(+), 858 deletions(-)
 create mode 100644 internal/app/cli_surface_test.go
 create mode 100644 internal/app/usage_sections.go
 create mode 100644 internal/plugin/install.go
 create mode 100644 internal/plugin/install_test.go

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 13a46ab..25d011a 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,16 +7,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-### Changed
-
-- `sshx text` reads remote files through a pipelined SFTP path: read-ahead
-  aperture plus `UseConcurrentReads`, so the SFTP layer keeps multiple requests
-  in flight for one file instead of one round trip per read. On the reporting
-  host the same 8 MiB window went from a median 83.0 s to 26.5 s (88.0/77.9 s →
-  23.8/29.1 s, alternating runs, identical bytes and lines scanned). `--max-scan-bytes`
-  still bounds both the scan and the read-ahead, and the truncation probe reads
-  exactly one byte past the budget.
-
 ### Added
 
 - `sshx text` narrates scan progress on stderr after a short grace period
@@ -38,6 +28,61 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   a leading `sudo`, so it announces the boundary before connecting and explains
   the refusal afterwards, suggesting `sudo sh -c "<command>"`. The auto-fill
   scope is unchanged.
+- Per-verb help: every subcommand now answers `sshx <verb> --help` with its own
+  usage document instead of rejecting `--help` as an unknown option. `--help
+  --json` emits the same blocks as an `sshx.help.v1` document (`sshx text
+  --help --json` keeps its structured `sshx.text.help.v1` document), and the
+  help text is defined once and shared with the global `sshx --help` surface.
+- `--quiet` (alias `--no-notices`): suppresses human notices on stderr
+  (deprecation warnings, policy-block mirrors, sudo-boundary hints, scan
+  progress, narration) so a caller that merges the streams
+  (`2>&1`) under `--json` still reads exactly one parseable document. stdout,
+  the exit code, and the JSON result are unchanged. Like `--help`, it is
+  recognized in option position in any order, so it works before or after other
+  sshx options and never reaches the remote command.
+- `sshx sql --statement-file=PATH` and statement input on stdin: a query no
+  longer has to be assembled as a shell string. `sshx sql` also accepts a
+  statement that opens with a SQL comment (`-- header`) as statement text
+  instead of rejecting it as an unknown option. Reading stdin waits for EOF
+  (like `psql`), so a caller whose stdin pipe stays open should pass
+  `--statement-file` instead.
+- `sshx plugin install <dir> [--replace] [--trust]`: provision an existing local
+  plugin directory through the audited CLI instead of hand-placing files under
+  the runtime plugin root. The source is staged with sshx's own modes, validated
+  through the executor's loader before publishing, and `--trust` records the
+  published digest in the same step. `--replace` preserves the previous plugin
+  as a backup, symlinks and non-regular entries are refused, and the copy is
+  bounded (8MiB, 128 files).
+
+### Changed
+
+- `sshx text` reads remote files through a pipelined SFTP path: read-ahead
+  aperture plus `UseConcurrentReads`, so the SFTP layer keeps multiple requests
+  in flight for one file instead of one round trip per read. On the reporting
+  host the same 8 MiB window went from a median 83.0 s to 26.5 s (88.0/77.9 s →
+  23.8/29.1 s, alternating runs, identical bytes and lines scanned). `--max-scan-bytes`
+  still bounds both the scan and the read-ahead, and the truncation probe reads
+  exactly one byte past the budget.
+
+- `sshx plugin list` groups built-in capabilities and local plugins and always
+  names the local plugin root, so "no local plugins installed" is visible
+  instead of inferred; local entries report provenance, trust, validity, and
+  digest, and `plugin show`/`trust`/`install` report the same state line. A
+  staging directory left by an interrupted install is skipped instead of being
+  reported as an invalid plugin, and a publication that cannot be renamed swaps
+  the previous plugin back in (or reports where the recovery copy was kept).
+- Compatibility mode (`sshx -h=<host> ...`) now accepts the documented
+  `--ssh-password-key=KEY` option instead of forwarding it as part of the remote
+  command, and rejects an unrecognized option instead of forwarding it, naming
+  the offending token and suggesting the intended option when one is close. The guessed
+  `--local`/`--remote` transfer options name the real surface
+  (`--upload=<local> --to=<remote>`), and a missing upload/download destination
+  names `--to` explicitly. Remote command arguments after the first command
+  token, and after `--`, are unchanged.
+- A missing plugin, `--list=`, `--mkdir=`, `--rm=`, `--upload=` or
+  `--download=` now names the searched directory or the option that supplies the
+  missing value (`remote path is required` / `local path is required` diagnosed
+  the wrong cause).
 
 ### Fixed
 
@@ -45,6 +90,27 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   nothing at all, and a budget-limited scan returned partial results without
   saying so.
 
+- `sshx run --target=<name>` resolves the sudo keyring reference per host, the
+  same way single-target verbs do: an explicit `-pk` still wins, but the
+  built-in default (`master`) no longer shadows a host's configured
+  `sudo_password_key`. The plan, the SSH client, the keyring lookup, and the
+  audit trail all resolve the same reference, so the plan reports the key that
+  will be used and each target's audit event names the credential it used (the
+  run summary records only a caller-level choice).
+- `sshx apply` removes its staging temp, publication temp, and unverified backup
+  with an absolute remover or POSIX `unlink` before falling back to `PATH rm`, so
+  a host whose `rm` is a trash-move wrapper no longer collects leaked copies of
+  the applied payload. Cleanup success now means the path is gone, and an
+  artifact that cannot be removed still reports `cleanup_pending` with exit 4.
+- `TestApplySudoScriptEvidenceAndCleanup` no longer pipes the generated
+  privileged script through the child's stdin or captures its output through
+  `os/exec` copier goroutines; the fixture runs the script from a file with
+  file-backed streams and reports a truncated report readably instead of
+  panicking on a nil pointer.
+- The CI `Lint` gate is pinned to golangci-lint `v2.13.2` and `.golangci.yml`
+  uses the v2 `linters.exclusions.rules` schema, so an upstream release or the
+  v1-era key can no longer fail the job before any Go file is analysed.
+
 ## [0.17.0] - 2026-09-16
 
 ### Added
diff --git a/README.md b/README.md
index 5b753c2..4696b89 100644
--- a/README.md
+++ b/README.md
@@ -280,7 +280,9 @@ replacement.
 ### `--json` structured output
 
 Add `--json` to get a single JSON object on stdout (diagnostics still go to
-stderr, so stdout stays pure):
+stderr, so stdout stays pure). Human notices such as deprecation warnings and
+narration never touch stdout, and `--quiet` suppresses them on stderr, so a
+caller that merges the streams (`2>&1`) still reads one parseable document:
 
 ```bash
 sshx -h=prod-web --json "systemctl is-active nginx"
@@ -434,7 +436,11 @@ Use `sshx sql` instead of sending raw `psql` or `sqlite3` commands through
 `sshx run`. It accepts exactly one statement, classifies it locally, blocks
 unbounded or unsupported forms, backs up affected data, and records a
 structured audit event. Direct `psql`/`pgcli`/`sqlite3` invocations in
-run/command mode are blocked.
+run/command mode are blocked. The statement may be a positional argument,
+everything after `--`, a local file (`--statement-file=PATH`), or piped stdin;
+a statement that opens with a SQL comment is statement text, not an option.
+Reading stdin waits for EOF, so close stdin (or use `--statement-file`) when
+another process holds the pipe open.
 
 For PostgreSQL, sshx runs `EXPLAIN (FORMAT JSON)` before DML. Psql backslash
 commands, data-modifying CTE bodies, `EXPLAIN ANALYZE`, `SELECT INTO`, `CALL`,
@@ -454,6 +460,10 @@ sshx sql -h=prod-db --db=app --dry-run --json \
 sshx sql -h=prod-db --db=app --db-user=app \
   --db-password-key=app-db --json \
   "UPDATE users SET active=false WHERE id=42"
+
+# Hand over a .sql file, or pipe the statement in
+sshx sql -h=prod-db --db=app --json --statement-file=./query.sql
+printf '%s' 'SELECT count(*) FROM users' | sshx sql -h=prod-db --db=app --json
 ```
 
 `UPDATE`/`DELETE` without a top-level `WHERE` requires
@@ -568,6 +578,14 @@ sshx plugin trust docker.environment --json
 sshx inspect -h=prod-web docker.environment --json
 ```
 
+An existing plugin directory is provisioned through the CLI instead of by hand:
+`sshx plugin install <dir>` stages the source with sshx's own modes, validates it
+through the same loader the executor uses, publishes it only when it is valid,
+and `--trust` records the digest in the same step (`--replace` keeps the previous
+plugin as a backup). `sshx plugin list` groups built-in capabilities and local
+plugins and always names the local plugin root, so "none installed" is visible,
+and a missing plugin names the directory that was searched.
+
 New and edited plugins are untrusted until their current manifest/collector/schema
 digest is explicitly trusted. `inspect` checks that trust before opening SSH,
 streams the collector through stdin for that session only, validates one JSON
diff --git a/README_CN.md b/README_CN.md
index a5b4920..0de6d00 100644
--- a/README_CN.md
+++ b/README_CN.md
@@ -271,7 +271,7 @@ sshx: block reason: ⚠️  Dangerous command blocked | ... | Reason: Direct Pos
 
 ### `--json` 结构化输出
 
-加上 `--json` 即可在 stdout 得到单个 JSON 对象（诊断日志仍走 stderr，保证 stdout 纯净）：
+加上 `--json` 即可在 stdout 得到单个 JSON 对象（诊断日志仍走 stderr，保证 stdout 纯净）。人工notice（弃用警告、进度叙述）只会出现在 stderr，`--quiet` 可将其静默：这样把两个流合并（`2>&1`）的调用方在成功与失败路径下都只会读到一份可解析文档：
 
 ```bash
 sshx -h=prod-web --json "systemctl is-active nginx"
@@ -420,6 +420,12 @@ sshx plugin trust docker.environment --json
 sshx inspect -h=prod-web docker.environment --json
 ```
 
+已存在的插件目录请通过 CLI 安装，不要手工放置文件：`sshx plugin install <dir>`
+会用 sshx 自己的权限写入暂存副本、用执行器同一套 loader 校验、只有校验通过才发布；
+`--trust` 在同一步记录摘要，`--replace` 保留旧插件作为备份。`sshx plugin list`
+会区分内置能力与本地插件并始终打印本地插件根目录（因此"未安装"是可见状态），
+插件缺失时的报错也会指出实际搜索的目录。
+
 新建或修改后的插件默认不可信。`plugin trust` 显式记录 manifest、collector
 和 schema 的当前摘要；`inspect` 在联网前检查摘要信任，然后只在本次 SSH
 会话中通过 stdin 临时执行采集器，校验唯一 JSON 输出并脱敏。插件信任不是
diff --git a/docs/contract.md b/docs/contract.md
index 4382161..f59af3f 100644
--- a/docs/contract.md
+++ b/docs/contract.md
@@ -36,7 +36,23 @@ not be introduced for an existing invocation shape.
 - A breaking change requires a new schema (`sshx.result.v2`, …) and an N-1
   support window: the previous schema remains emitted or accepted until the
   next major sshx release after the new schema ships.
-- `--json` stdout stays a machine document. Human logs belong on stderr.
+- `--json` stdout stays a machine document. Human logs belong on stderr, and
+  sshx never writes human text to stdout, including on failure.
+- stderr carries human notices (deprecation warnings, narration, progress) and,
+  outside `--json`, the diagnostic for a failed invocation. `--quiet`
+  (`--no-notices`) suppresses the notices; with it, a caller that merges the
+  streams (`2>&1`) under `--json` still reads exactly one document, in both the
+  success and the failure path. Merging stderr without `--quiet` is not
+  supported for parsing.
+- Per-verb discovery is part of the contract: every subcommand answers
+  `sshx <verb> --help`, and `sshx <verb> --help --json` emits the same blocks as
+  an `sshx.help.v1` document (`sshx text --help --json` keeps its structured
+  `sshx.text.help.v1` document).
+- `--help` and `--quiet` are recognized in option position, in any order:
+  `sshx -h=<host> -p=22 --help` prints the global usage without resolving a host,
+  connecting, or touching the trust store. Once the remote command, SQL
+  statement, or `--` separator starts, a later `--help`/`--quiet` belongs to the
+  payload.
 - MCP tools return the CLI JSON verbatim. MCP does not grow a parallel schema.
 
 ## Additive execution hardening
diff --git a/docs/roadmap.md b/docs/roadmap.md
index c66f0fe..5bccf2e 100644
--- a/docs/roadmap.md
+++ b/docs/roadmap.md
@@ -143,7 +143,7 @@ Agent / 自动化 / 人类运维者
 
 - **sshx 本地插件生命周期**
 
-  Agent 可通过 `sshx plugin create` 在 `~/.sshx/plugins/`（或 `$SSHX_HOME/plugins/`）创建 Docker、Nginx 或自定义应用探测插件，并完成 list/show/validate/test/trust/remove。插件脚本不由 Agent skill 维护；摘要变化会使信任失效。证据：`internal/app/plugin.go`、`internal/plugin/`、`tests/e2e/inspect_plugin_e2e_test.go`。
+  Agent 可通过 `sshx plugin create` 在 `~/.sshx/plugins/`（或 `$SSHX_HOME/plugins/`）创建 Docker、Nginx 或自定义应用探测插件，也可用 `sshx plugin install <dir>` 在 CLI 内完成已有插件目录的暂存、校验、发布与 `--trust`，并完成 list/show/validate/test/trust/remove。`plugin list` 区分内置能力与本地插件并始终打印本地插件根目录；插件缺失时报错指出实际搜索目录。插件脚本不由 Agent skill 维护；摘要变化会使信任失效。证据：`internal/app/plugin.go`、`internal/plugin/`、`tests/e2e/inspect_plugin_e2e_test.go`。
 
 - **有界远端观察快照**
 
@@ -255,7 +255,7 @@ issue #71 的新增边界、验证状态及外部前提单列在后面的证据
 | host-key 校验 | 高 | 是，信任状态 | 可能修改 `known_hosts` | ✅ 显式信任后严格复用 | ✅ 未知/变更 key | ✅ strict/accept-unknown | ✅ 首次写入后重新严格连接 | `tests/e2e/cli_e2e_test.go` |
 | 危险动作阻断与显式绕过 | 高 | 是 | 否，仅控制执行准入 | ✅ 显式 `--force` | ✅ 默认阻断且零连接 | ✅ 默认阻断/显式绕过 | 不适用：策略门本身不修改状态 | `tests/e2e/cli_e2e_test.go` |
 | 本地结构化审计 | 高 | 否 | 是，本地 | ✅ | ✅ 不可写目标可观测 | 不适用：本地调用者同权 | ✅ 修复目标后单事件写入 | `tests/e2e/host_audit_e2e_test.go` |
-| 本地探测插件生命周期 | 高 | 本地调用者权限 | 是，本地 | ✅ create/list/show/validate/test/trust/remove | ✅ 路径逃逸、重复创建、manifest/entrypoint/schema/fixture 分类失败 | ✅ 私有目录/文件权限 | ✅ replace/remove 保留可恢复备份 | `tests/e2e/inspect_plugin_e2e_test.go` |
+| 本地探测插件生命周期 | 高 | 本地调用者权限 | 是，本地 | ✅ create/install/list/show/validate/test/trust/remove | ✅ 路径逃逸、重复创建、symlink/非普通文件源、安装前校验失败、manifest/entrypoint/schema/fixture 分类失败 | ✅ 私有目录/文件权限 | ✅ replace/remove 保留可恢复备份；安装校验失败不触碰已发布插件 | `tests/e2e/inspect_plugin_e2e_test.go`、`internal/plugin/install_test.go` |
 | Agent Skill 安装 | 高 | 本地调用者权限 | 是，本地 Agent 信任目录 | ✅ 编译后二进制离线安装/幂等复用 | ✅ 内容冲突与 symlink 目标拒绝 | ✅ 默认目录/显式目录 | ✅ 冲突不覆盖，显式 force 后恢复官方版本 | `tests/e2e/skill_e2e_test.go` |
 | 单主机探测与内置基线 | 高 | 是 | 否，cache off | ✅ 自定义插件与 `system.baseline` | ✅ 未信任、污染/超限输出、超时、非零退出、不支持平台 | ✅ operator/reader/sudo-required | 不适用：不修改远端状态 | `tests/e2e/inspect_plugin_e2e_test.go`、`tests/e2e/keyring_e2e_test.go` |
 | 远端观察缓存 | 高 | 是 | 是，远端 JSON | ✅ 冷写入/热复用/并发原子替换 | ✅ TTL/boot ID、格式、大小、属主、权限、symlink、只读端 | ✅ 可写/只读 SFTP | ✅ 失败写入保留原有效快照 | `tests/e2e/inspect_plugin_e2e_test.go` |
diff --git a/internal/app/agentmode_test.go b/internal/app/agentmode_test.go
index efb7535..6d88278 100644
--- a/internal/app/agentmode_test.go
+++ b/internal/app/agentmode_test.go
@@ -427,6 +427,59 @@ func TestRun_DryRunResolvesNamedHostAndSudoKey(t *testing.T) {
 	}
 }
 
+// `sshx run --target=` resolves the sudo keyring reference per host, exactly as
+// the single-target verbs do: the built-in default key must not shadow the
+// host's sudo_password_key, and an explicit -pk still wins (issue #78).
+func TestRun_DryRunTargetResolvesHostSudoKey(t *testing.T) {
+	home := t.TempDir()
+	setTestHome(t, home)
+	sudoKeyName := "prod-web-sudo" //nolint:gosec // G101: keyring key name used in a test, not secret material.
+	err := SaveSettings(&Settings{
+		Hosts: []HostConfig{{
+			Name:            "prod-web",
+			Host:            "10.0.0.5",
+			Port:            "2222",
+			User:            "root",
+			SudoPasswordKey: sudoKeyName,
+		}},
+	})
+	if err != nil {
+		t.Fatalf("SaveSettings() error = %v", err)
+	}
+
+	targetSudoKey := func(t *testing.T, args []string) string {
+		t.Helper()
+		result := runDryRunJSON(t, args)
+		plan, ok := result["plan"].(map[string]any)
+		if !ok {
+			t.Fatalf("expected nested plan object, got %T", result["plan"])
+		}
+		targets, ok := plan["targets"].([]any)
+		if !ok || len(targets) != 1 {
+			t.Fatalf("expected one planned target, got %v", plan["targets"])
+		}
+		target, ok := targets[0].(map[string]any)
+		if !ok {
+			t.Fatalf("expected target object, got %T", targets[0])
+		}
+		key, ok := target["sudo_key"].(string)
+		if !ok {
+			t.Fatalf("planned target has no sudo_key string: %v", target)
+		}
+		return key
+	}
+
+	configured := targetSudoKey(t, []string{"sshx", "run", "--target=prod-web", "--dry-run", "--json", "--", "sudo whoami"})
+	if configured != sudoKeyName {
+		t.Errorf("expected the host's sudo key %q in the plan, got %q", sudoKeyName, configured)
+	}
+
+	override := targetSudoKey(t, []string{"sshx", "run", "--target=prod-web", "-pk=explicit-sudo", "--dry-run", "--json", "--", "sudo whoami"})
+	if override != "explicit-sudo" {
+		t.Errorf("expected an explicit -pk to win, got %q", override)
+	}
+}
+
 func TestRun_DryRunHostTestUsesConfiguredKeyAndPasswordKey(t *testing.T) {
 	home := t.TempDir()
 	setTestHome(t, home)
diff --git a/internal/app/app.go b/internal/app/app.go
index 651788a..6a60fef 100644
--- a/internal/app/app.go
+++ b/internal/app/app.go
@@ -86,6 +86,11 @@ func RunContext(ctx context.Context, args []string) (err error) {
 	config := ParseArgs(args)
 	config.Context = ctx
 	config.ExecutionID = execution.NewRunID()
+	if config.Quiet {
+		// Notices are advisory narration. --quiet keeps stderr free of them so a
+		// caller that merges streams under --json still reads one document.
+		logger.GetLogger().SetLevel(logger.LogLevelError)
+	}
 	if config.ArgumentError != "" {
 		if config.Mode == "run" {
 			return reportRunRequestFailure(config, nil, fmt.Errorf("%w: %s", execution.ErrConfig, config.ArgumentError))
@@ -106,8 +111,14 @@ func RunContext(ctx context.Context, args []string) (err error) {
 	if config.Mode == "mcp" {
 		return RunMCPServerContext(ctx)
 	}
-	if config.Mode == "text" && config.TextHelp {
-		return HandleTextHelp(config)
+	// A usage request is answered before any mode runs: `sshx <verb> --help` prints
+	// that verb's document and `sshx --help` prints the global surface.
+	if config.ShowUsage {
+		PrintUsage()
+		return nil
+	}
+	if config.HelpVerb != "" {
+		return PrintVerbUsage(config)
 	}
 
 	audit := newAuditRecorder(config)
@@ -382,7 +393,7 @@ func runCommand(client *sshclient.SSHClient, config *sshclient.Config, audit *au
 	res, execErr := client.RunCommand(config.JSONOutput)
 	dur := time.Since(start)
 	audit.recordCommandResult(config, client.AuthMethodUsed(), res, dur, classifyError(execErr), execErr)
-	reportSudoPromptFailure(os.Stderr, config.Command, res.Stderr+res.Stdout)
+	reportSudoPromptFailure(noticeWriter(config), config.Command, res.Stderr+res.Stdout)
 
 	if config.JSONOutput {
 		if outputErr := emitCommandJSON(config, client.AuthMethodUsed(), res, dur, classifyError(execErr), execErr); outputErr != nil {
@@ -590,7 +601,7 @@ func resolveHostFromSettings(config *sshclient.Config) error {
 
 	// Use configured sudo password key if available (legacy password_key is sudo-only).
 	sudoKey := hostConfig.EffectiveSudoPasswordKey()
-	if sudoKey != "" && config.SudoKey == sshclient.DefaultSudoKey {
+	if sudoKey != "" && !sudoKeyChosen(config) {
 		config.SudoKey = sudoKey
 		logger.GetLogger().Success("Using sudo password key: %s", sudoKey)
 	}
diff --git a/internal/app/audit.go b/internal/app/audit.go
index 101d691..876df35 100644
--- a/internal/app/audit.go
+++ b/internal/app/audit.go
@@ -176,6 +176,9 @@ type auditRecorder struct {
 	completed      bool
 	persisted      bool
 	persistenceErr error
+	// sudoKeyResolved marks an event whose sudo key was resolved per target, so
+	// finish() does not overwrite it with the caller-level value.
+	sudoKeyResolved bool
 }
 
 var (
@@ -531,7 +534,9 @@ func (r *auditRecorder) refresh(config *sshclient.Config) {
 		r.event.UsesSudo = config.LoginUseSudo
 		r.event.Command = ""
 	}
-	r.event.SudoKey = config.SudoKey
+	if !r.sudoKeyResolved {
+		r.event.SudoKey = config.SudoKey
+	}
 	if config.Timeout > 0 {
 		r.event.Timeout = config.Timeout.String()
 	}
diff --git a/internal/app/cli_surface_test.go b/internal/app/cli_surface_test.go
new file mode 100644
index 0000000..2cce405
--- /dev/null
+++ b/internal/app/cli_surface_test.go
@@ -0,0 +1,202 @@
+package app
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/stretchr/testify/require"
+)
+
+// Every subcommand answers `sshx <verb> --help` with its own usage document
+// instead of rejecting --help as an unknown option.
+func TestParseArgsVerbHelp(t *testing.T) {
+	for _, verb := range helpVerbs {
+		t.Run(verb, func(t *testing.T) {
+			config := ParseArgs([]string{"sshx", verb, "--help"})
+			require.Empty(t, config.ArgumentError)
+			require.Equal(t, verb, config.HelpVerb)
+			require.False(t, config.JSONOutput)
+		})
+	}
+
+	jsonHelp := ParseArgs([]string{"sshx", "apply", "--help", "--json"})
+	require.Equal(t, "apply", jsonHelp.HelpVerb)
+	require.True(t, jsonHelp.JSONOutput)
+}
+
+// A usage request is answered in every option position, including after other
+// sshx options in compatibility mode: it must never fall through to a connection
+// or a trust-store write, and it must never be mistaken for an unknown option.
+func TestParseArgsHelpInEveryOptionPosition(t *testing.T) {
+	for _, args := range [][]string{
+		{"sshx", "-h=host", "--help"},
+		{"sshx", "-h=host", "-p=1", "--json", "--help"},
+		{"sshx", "--timeout=5s", "--help"},
+		{"sshx", "-f", "--help"},
+		{"sshx", "--quiet", "--help"},
+		{"sshx", "--help"},
+	} {
+		t.Run(strings.Join(args, " "), func(t *testing.T) {
+			config := ParseArgs(args)
+			require.Empty(t, config.ArgumentError)
+			require.Empty(t, config.HelpVerb, "compatibility mode answers with the global usage")
+			require.True(t, config.ShowUsage)
+			require.NotEqual(t, "sftp", config.Mode)
+		})
+	}
+
+	// A subcommand answers with its own document in the same positions.
+	apply := ParseArgs([]string{"sshx", "apply", "-h=host", "--path=/a", "--from=/b", "--help"})
+	require.Equal(t, "apply", apply.HelpVerb)
+	require.Empty(t, apply.ArgumentError)
+}
+
+// The notice flag is accepted in first position too; a first-position option is
+// an sshx option, not a remote command.
+func TestParseArgsQuietFlagInFirstPosition(t *testing.T) {
+	for _, args := range [][]string{
+		{"sshx", "--quiet", "-h=host", "uptime"},
+		{"sshx", "--no-notices", "-h=host", "uptime"},
+		{"sshx", "--quiet", "run", "--target=prod", "--", "true"},
+	} {
+		t.Run(strings.Join(args, " "), func(t *testing.T) {
+			config := ParseArgs(args)
+			require.Empty(t, config.ArgumentError)
+			require.True(t, config.Quiet)
+		})
+	}
+}
+
+// --help is an sshx option only while the payload has not started: once the
+// remote command or SQL statement begins, the token belongs to that payload.
+func TestParseArgsHelpStopsAtPayload(t *testing.T) {
+	run := ParseArgs([]string{"sshx", "run", "--target=prod", "--", "--help"})
+	require.Empty(t, run.HelpVerb)
+	require.Equal(t, "--help", run.Command)
+
+	sql := ParseArgs([]string{"sshx", "sql", "-h=db", "--db=app", "select 1", "--help"})
+	require.Empty(t, sql.HelpVerb)
+	require.Equal(t, "select 1 --help", sql.SQLStatement)
+
+	compat := ParseArgs([]string{"sshx", "-h=host", "grep", "--help", "x"})
+	require.Empty(t, compat.HelpVerb)
+	require.Equal(t, "grep --help x", compat.Command)
+}
+
+// Compatibility mode rejects an option-shaped token it does not know. Before
+// this rule the token was forwarded as part of the remote command, so a typo
+// ran with defaults and the failure named the wrong cause.
+func TestCompatModeRejectsUnknownOptions(t *testing.T) {
+	tests := []struct {
+		name    string
+		args    []string
+		message string
+	}{
+		{"unknown long option", []string{"-h=host", "--bogus-flag=1"}, `unknown option "--bogus-flag=1"`},
+		{"near miss suggests the option", []string{"-h=host", "--dwnload=/tmp/x"}, `did you mean "--download"`},
+		{"guessed transfer option names the real surface", []string{"--local=/tmp/x", "--remote=/tmp/y"}, "--upload=<local-file>"},
+		{"unknown short option", []string{"-h=host", "-j=x"}, `unknown option "-j=x"`},
+		{"short near miss suggests the option", []string{"-h=host", "-pj=x", "uptime"}, `did you mean "-pk"`},
+		{"bare -h is not a host selector", []string{"-h", "host", "uptime"}, `unknown option "-h"`},
+	}
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			config := ParseArgs(append([]string{"sshx"}, test.args...))
+			require.Contains(t, config.ArgumentError, "unknown option")
+			require.Contains(t, config.ArgumentError, test.message)
+		})
+	}
+}
+
+// Option position ends where the payload starts: everything after the first
+// command token (or the -- separator) belongs to the remote command.
+func TestCompatModeKeepsPayloadTokens(t *testing.T) {
+	payload := ParseArgs([]string{"sshx", "-h=host", "grep", "-v", "foo"})
+	require.Empty(t, payload.ArgumentError)
+	require.Equal(t, "grep -v foo", payload.Command)
+
+	afterSeparator := ParseArgs([]string{"sshx", "-h=host", "--", "-la"})
+	require.Empty(t, afterSeparator.ArgumentError)
+	require.Equal(t, "-la", afterSeparator.Command)
+
+	sftp := ParseArgs([]string{"sshx", "-h=host", "--upload=/tmp/x", "--to=/tmp/y"})
+	require.Empty(t, sftp.ArgumentError)
+	require.Equal(t, "sftp", sftp.Mode)
+}
+
+// --quiet suppresses human notices without changing the parsed payload, and it
+// is likewise recognized in option position only.
+func TestParseArgsQuietFlag(t *testing.T) {
+	compat := ParseArgs([]string{"sshx", "-h=host", "--quiet", "uptime"})
+	require.True(t, compat.Quiet)
+	require.Equal(t, "uptime", compat.Command)
+
+	alias := ParseArgs([]string{"sshx", "run", "--no-notices", "--target=prod", "--", "true"})
+	require.True(t, alias.Quiet)
+	require.Equal(t, []string{"prod"}, alias.RunTargets)
+
+	verb := ParseArgs([]string{"sshx", "apply", "-h=host", "--quiet", "--path=/a", "--from=/b"})
+	require.True(t, verb.Quiet)
+	require.Empty(t, verb.ArgumentError)
+
+	payload := ParseArgs([]string{"sshx", "-h=host", "grep", "--quiet", "x"})
+	require.False(t, payload.Quiet)
+	require.Equal(t, "grep --quiet x", payload.Command)
+}
+
+// A statement that opens with a comment cannot be an option token, so sql takes
+// it as statement text; option-shaped typos are still rejected.
+func TestParseArgsSQLStatementSources(t *testing.T) {
+	comment := ParseArgs([]string{"sshx", "sql", "-h=db", "--db=app", "-- SELECT 1"})
+	require.Empty(t, comment.ArgumentError)
+	require.Equal(t, "-- SELECT 1", comment.SQLStatement)
+
+	multiLine := ParseArgs([]string{"sshx", "sql", "-h=db", "--db=app", "-- header\nselect 1;\n"})
+	require.Empty(t, multiLine.ArgumentError)
+	require.Equal(t, "-- header\nselect 1;", multiLine.SQLStatement)
+
+	path := filepath.Join(t.TempDir(), "query.sql")
+	require.NoError(t, os.WriteFile(path, []byte("-- header\nselect 2;\n"), 0o600))
+	fromFile := ParseArgs([]string{"sshx", "sql", "-h=db", "--db=app", "--statement-file=" + path})
+	require.Empty(t, fromFile.ArgumentError)
+	require.Equal(t, "-- header\nselect 2;", fromFile.SQLStatement)
+
+	conflict := ParseArgs([]string{"sshx", "sql", "-h=db", "--db=app", "--statement-file=" + path, "select 3"})
+	require.Contains(t, conflict.ArgumentError, "--statement-file cannot be combined")
+
+	typo := ParseArgs([]string{"sshx", "sql", "-h=db", "--dbb=app", "select 1"})
+	require.Contains(t, typo.ArgumentError, `did you mean "--db"`)
+
+	missing := ParseArgs([]string{"sshx", "sql", "-h=db", "--statement-file=/nonexistent/query.sql"})
+	require.Contains(t, missing.ArgumentError, "read --statement-file")
+}
+
+// The suggestion lists must describe options the parser really accepts, so a
+// typo never points at a name that does not exist.
+func TestCompatOptionNamesAreRecognized(t *testing.T) {
+	for _, name := range compatOptionNames {
+		t.Run(name, func(t *testing.T) {
+			for _, arg := range []string{name, name + "=x"} {
+				if !strings.Contains(ParseArgs([]string{"sshx", "-h=host", arg}).ArgumentError, "unknown option") {
+					return
+				}
+			}
+			t.Fatalf("compatOptionNames entry %q is not parsed", name)
+		})
+	}
+}
+
+func TestSQLOptionNamesAreRecognized(t *testing.T) {
+	for _, name := range sqlOptionNames {
+		t.Run(name, func(t *testing.T) {
+			for _, arg := range []string{name, name + "=x"} {
+				if !strings.Contains(ParseArgs([]string{"sshx", "sql", "-h=db", arg, "select 1"}).ArgumentError, "unknown sql option") {
+					return
+				}
+			}
+			t.Fatalf("sqlOptionNames entry %q is not parsed", name)
+		})
+	}
+}
diff --git a/internal/app/config.go b/internal/app/config.go
index d9a201b..cb10551 100644
--- a/internal/app/config.go
+++ b/internal/app/config.go
@@ -2,6 +2,7 @@ package app
 
 import (
 	"fmt"
+	"io"
 	"os"
 	"strconv"
 	"strings"
@@ -76,6 +77,23 @@ func applySudoKeyFlag(config *sshclient.Config, arg string) bool {
 	}
 }
 
+// sudoKeyChosen reports whether the caller chose the sudo keyring reference:
+// -pk/--password-key/--sudo-password-key, or a non-default SSH_SUDO_KEY. The
+// built-in default ("master") is not a choice, so a host's configured
+// sudo_password_key applies until the caller overrides it.
+func sudoKeyChosen(config *sshclient.Config) bool {
+	return config.SudoKeySet || config.SudoKey != sshclient.DefaultSudoKey
+}
+
+// sudoKeyChoice returns the caller's explicit sudo key, or "" when the key is
+// still the built-in default.
+func sudoKeyChoice(config *sshclient.Config) string {
+	if sudoKeyChosen(config) {
+		return config.SudoKey
+	}
+	return ""
+}
+
 func applyLifecycleFlag(config *sshclient.Config, arg string) bool {
 	key, value, found := strings.Cut(arg, "=")
 	if !found {
@@ -102,6 +120,150 @@ func applyLifecycleFlag(config *sshclient.Config, arg string) bool {
 	return true
 }
 
+// scanVerbFlags scans sshx's own options in a verb invocation before the
+// payload starts. It stops at the `--` separator and, for verbs whose first
+// positional token begins a remote payload (compatibility mode, run, sql, ros),
+// at that token: from there on every argument belongs to the payload, including
+// tokens that look like sshx flags (see AGENT.md "Boundary Contracts").
+//
+// It returns the arguments with the notice flags removed, plus the requested
+// --help / --json / --quiet state. --quiet is stripped because the CLI answers
+// it before any parser runs; --help and --json stay in the list, so a global
+// usage request still reaches the compatibility-mode parser and every parser
+// keeps owning --json.
+func scanVerbFlags(verb string, args []string) (rest []string, help, jsonOutput, quiet bool) {
+	stopAtPayload := verb == "" || verb == "run" || verb == "sql" || verb == "ros"
+	rest = make([]string, 0, len(args))
+	for i, arg := range args {
+		if arg == "--" || stopAtPayload && !strings.HasPrefix(arg, "-") {
+			rest = append(rest, args[i:]...)
+			break
+		}
+		switch arg {
+		case "--help":
+			help = true
+			rest = append(rest, arg)
+		case "--quiet", "--no-notices":
+			quiet = true
+		default:
+			if arg == "--json" {
+				jsonOutput = true
+			}
+			rest = append(rest, arg)
+		}
+	}
+	return rest, help, jsonOutput, quiet
+}
+
+// knownVerb reports whether the first argument selects a subcommand parser
+// rather than compatibility mode.
+func knownVerb(verb string) string {
+	if containsString(helpVerbs, verb) {
+		return verb
+	}
+	return ""
+}
+
+// compatOptionNames are the sshx-owned options accepted in compatibility mode
+// before the remote command starts. It feeds the "did you mean" suggestion for
+// an unrecognized option; TestCompatOptionNamesAreRecognized fails when an entry
+// is not actually parsed, so the list cannot drift into fiction.
+var compatOptionNames = []string{
+	"-h", "--host", "-p", "--port", "-u", "--user", "-i", "--key",
+	"-pk", "--password-key", "--sudo-password-key", "--ssh-password-key",
+	"--no-key", "--password-only", "--key-auth", "--force", "-f",
+	"--bypass-reason", "--accept-unknown-host", "--insecure-hostkey",
+	"--strict-host-key", "--known-hosts", "--no-safety-check", "--dry-run",
+	"--audit-output", "--no-audit", "--json", "--pty", "--timeout",
+	"--expect-plan", "--host-timeout", "--global-timeout", "--bind", "--via",
+	"--sftp", "--upload", "--download", "--transfer", "--to", "--list", "--ls",
+	"--mkdir", "--rm", "--password-set", "--password-get", "--password-delete",
+	"--password-del", "--password-check", "--password-exists", "--password-list",
+	"--password-ls", "--host-add", "--host-import", "--ssh-config",
+	"--host-update", "--host-list", "--host-ls", "--host-test", "--host-test-all",
+	"--host-remove", "--host-rm", "--host-name", "--host-desc", "--host-type",
+}
+
+// compatOptionHints explains the options callers most often guess at. They are
+// not aliases: the upload/download surface is --upload=<local> or
+// --download=<remote> plus --to=<destination>, and the guessed --local/--remote
+// pair is silently useless, so name the real surface instead of only the typo.
+var compatOptionHints = map[string]string{
+	"--local":  "use --upload=<local-file> --to=<remote-path> (or --download=<remote-file> --to=<local-path>)",
+	"--remote": "use --download=<remote-file> --to=<local-path> (or --upload=<local-file> --to=<remote-path>)",
+}
+
+// unknownCompatOption describes an option-shaped token that compatibility mode
+// does not recognize. Before this rule the token was forwarded as part of the
+// remote command, so a misspelled option ran something the caller never asked
+// for and the resulting failure named the wrong cause.
+func unknownCompatOption(token string) string {
+	name := token
+	if index := strings.Index(name, "="); index >= 0 {
+		name = name[:index]
+	}
+	if hint, ok := compatOptionHints[name]; ok {
+		return fmt.Sprintf("unknown option %q: %s", token, hint)
+	}
+	if suggestion := closestCompatOption(name); suggestion != "" {
+		return fmt.Sprintf("unknown option %q (did you mean %q?); sshx options come before the remote command, and a command that starts with \"-\" must follow --", token, suggestion)
+	}
+	return fmt.Sprintf("unknown option %q; sshx options come before the remote command, and a command that starts with \"-\" must follow --", token)
+}
+
+// closestCompatOption returns the compatibility option nearest to an
+// unrecognized one, or "" when nothing is close enough to suggest.
+func closestCompatOption(name string) string {
+	return closestOptionName(name, compatOptionNames)
+}
+
+// closestOptionName returns the known option nearest to an unrecognized token.
+// Short names are specific, so they tolerate only one wrong character while
+// longer names tolerate two, and one-character options are never suggested:
+// each of them is one edit away from every other.
+func closestOptionName(name string, candidates []string) string {
+	long := strings.HasPrefix(name, "--")
+	best, bestDistance := "", 3
+	for _, candidate := range candidates {
+		if strings.HasPrefix(candidate, "--") != long {
+			continue
+		}
+		bare := strings.TrimLeft(candidate, "-")
+		if len(bare) < 2 {
+			continue
+		}
+		limit := 2
+		if len(bare) <= 3 {
+			limit = 1
+		}
+		if distance := levenshtein(name, candidate); distance <= limit && distance < bestDistance {
+			best, bestDistance = candidate, distance
+		}
+	}
+	return best
+}
+
+// levenshtein returns the edit distance between two option names.
+func levenshtein(a, b string) int {
+	previous := make([]int, len(b)+1)
+	current := make([]int, len(b)+1)
+	for j := range previous {
+		previous[j] = j
+	}
+	for i := 1; i <= len(a); i++ {
+		current[0] = i
+		for j := 1; j <= len(b); j++ {
+			substitution := previous[j-1]
+			if a[i-1] != b[j-1] {
+				substitution++
+			}
+			current[j] = min(previous[j]+1, current[j-1]+1, substitution)
+		}
+		previous, current = current, previous
+	}
+	return previous[len(b)]
+}
+
 // ParseArgs parses command-line arguments and returns a Config.
 func ParseArgs(args []string) *sshclient.Config {
 	config := &sshclient.Config{
@@ -113,6 +275,25 @@ func ParseArgs(args []string) *sshclient.Config {
 		RunTags:      map[string]string{},
 	}
 
+	// sshx's own flags come before the payload, so scan them once here: --quiet
+	// must be known before the first notice is emitted, and --help must answer
+	// before any parser can reject it as an unknown option. Compatibility mode
+	// starts at the first argument (an sshx option or the remote command); a
+	// subcommand starts after its verb.
+	verb := ""
+	scanFrom := 1
+	if len(args) > 1 {
+		verb = args[1]
+		if knownVerb(verb) != "" {
+			scanFrom = 2
+		}
+	}
+	verbArgs := []string(nil)
+	var help, jsonOutput bool
+	if len(args) > scanFrom {
+		verbArgs, help, jsonOutput, config.Quiet = scanVerbFlags(knownVerb(verb), args[scanFrom:])
+	}
+
 	if password := os.Getenv("SSH_PASSWORD"); password != "" {
 		config.Password = password
 	}
@@ -134,10 +315,10 @@ func ParseArgs(args []string) *sshclient.Config {
 	}
 	// High-risk trust relaxations must be explicit CLI/request fields. Inherited
 	// environment values and repository-local .env files must not authorize them.
-	warnDeprecatedTrustEnv("SSH_ACCEPT_UNKNOWN_HOST")
-	warnDeprecatedTrustEnv("SSH_INSECURE_HOST_KEY")
-	warnDeprecatedTrustEnv("SSH_NO_SAFETY_CHECK")
-	warnDeprecatedTrustEnv("SSH_FORCE")
+	warnDeprecatedTrustEnv(config, "SSH_ACCEPT_UNKNOWN_HOST")
+	warnDeprecatedTrustEnv(config, "SSH_INSECURE_HOST_KEY")
+	warnDeprecatedTrustEnv(config, "SSH_NO_SAFETY_CHECK")
+	warnDeprecatedTrustEnv(config, "SSH_FORCE")
 
 	if timeoutStr := os.Getenv("SSH_TIMEOUT"); timeoutStr != "" {
 		if d, err := parseTimeout(timeoutStr); err == nil {
@@ -157,41 +338,53 @@ func ParseArgs(args []string) *sshclient.Config {
 	}
 
 	if len(args) > 1 {
-		switch args[1] {
+		if help {
+			if verb = knownVerb(verb); verb != "" {
+				config.HelpVerb = verb
+				config.JSONOutput = jsonOutput
+			} else {
+				config.ShowUsage = true
+			}
+			return config
+		}
+		switch verb {
 		case "plugin":
-			parsePluginArgs(config, args[2:])
+			parsePluginArgs(config, verbArgs)
 			return config
 		case "skill":
-			parseSkillArgs(config, args[2:])
+			parseSkillArgs(config, verbArgs)
 			return config
 		case "mcp":
-			parseMCPArgs(config, args[2:])
+			parseMCPArgs(config, verbArgs)
 			return config
 		case "inspect":
-			parseInspectArgs(config, args[2:])
+			parseInspectArgs(config, verbArgs)
 			return config
 		case "run":
-			parseRunArgs(config, args[2:])
+			parseRunArgs(config, verbArgs)
 			return config
 		case "sql":
-			parseSQLArgs(config, args[2:])
+			parseSQLArgs(config, verbArgs)
 			return config
 		case "apply":
-			parseApplyArgs(config, args[2:])
+			parseApplyArgs(config, verbArgs)
 			return config
 		case "text":
-			parseTextArgs(config, args[2:])
+			parseTextArgs(config, verbArgs)
 			return config
 		case "audit":
-			parseAuditArgs(config, args[2:])
+			parseAuditArgs(config, verbArgs)
 			return config
 		case "login":
-			parseLoginArgs(config, args[2:])
+			parseLoginArgs(config, verbArgs)
 			return config
 		case "ros":
-			parseROSArgs(config, args[2:])
+			parseROSArgs(config, verbArgs)
 			return config
 		}
+		// Compatibility mode: the scanned list already carries the first
+		// argument unless it was an sshx notice flag.
+		args = append([]string{args[0]}, verbArgs...)
 	}
 
 	commandParts := []string{}
@@ -214,6 +407,8 @@ func ParseArgs(args []string) *sshclient.Config {
 			config.KeyPath = strings.SplitN(arg, "=", 2)[1]
 			config.UseKeyAuth = true
 		case applySudoKeyFlag(config, arg):
+		case strings.HasPrefix(arg, "--ssh-password-key="):
+			config.SSHPasswordKey = strings.SplitN(arg, "=", 2)[1]
 		case arg == "--no-key", arg == "--password-only":
 			config.UseKeyAuth = false
 			config.KeyPath = ""
@@ -351,8 +546,16 @@ func ParseArgs(args []string) *sshclient.Config {
 		case strings.HasPrefix(arg, "--host-type="):
 			config.HostType = strings.SplitN(arg, "=", 2)[1]
 		case arg == "--help":
-			PrintUsage()
-			os.Exit(0)
+			// Unreachable through ParseArgs (the pre-scan answers --help in option
+			// position), kept for callers that build a compatibility argument list.
+			config.ShowUsage = true
+			return config
+		case strings.HasPrefix(arg, "-"):
+			// Option position: everything here must be an sshx option. Forwarding
+			// an unrecognized token as a command made typos execute with defaults
+			// and produced an error that named the wrong cause.
+			config.ArgumentError = unknownCompatOption(arg)
+			return config
 		default:
 			if config.Mode == "ssh" {
 				commandParts = append(commandParts, args[i:]...)
@@ -416,6 +619,8 @@ func parsePluginArgs(config *sshclient.Config, args []string) {
 			config.DryRun = true
 		case arg == "--replace":
 			config.PluginReplace = true
+		case arg == "--trust":
+			config.PluginTrust = true
 		case strings.HasPrefix(arg, "--runner="):
 			config.PluginRunner = strings.SplitN(arg, "=", 2)[1]
 		case strings.HasPrefix(arg, "--platform="):
@@ -430,8 +635,14 @@ func parsePluginArgs(config *sshclient.Config, args []string) {
 			config.AuditOutput = strings.SplitN(arg, "=", 2)[1]
 		case arg == "--no-audit":
 			config.AuditEnabled = false
-		case !strings.HasPrefix(arg, "-") && config.PluginID == "":
-			config.PluginID = arg
+		case !strings.HasPrefix(arg, "-") && config.PluginID == "" && config.PluginSource == "":
+			// The install positional names the source directory; every other
+			// action takes a plugin id.
+			if config.PluginAction == "install" {
+				config.PluginSource = arg
+			} else {
+				config.PluginID = arg
+			}
 		case !strings.HasPrefix(arg, "-"):
 			config.ArgumentError = fmt.Sprintf("unexpected plugin argument %q", arg)
 		default:
@@ -442,9 +653,9 @@ func parsePluginArgs(config *sshclient.Config, args []string) {
 
 // warnDeprecatedTrustEnv emits a diagnostic when a high-risk env switch is set
 // without applying it. Explicit CLI flags remain the only authorization path.
-func warnDeprecatedTrustEnv(name string) {
+func warnDeprecatedTrustEnv(config *sshclient.Config, name string) {
 	val := os.Getenv(name)
-	if val == "" {
+	if val == "" || config != nil && config.Quiet {
 		return
 	}
 	if strings.EqualFold(val, "true") || val == "1" {
@@ -620,6 +831,85 @@ func parseRunArgs(config *sshclient.Config, args []string) {
 	}
 }
 
+// sqlOptionNames are the options accepted by `sshx sql` before the statement
+// starts. It feeds the "did you mean" suggestion for an unrecognized option;
+// TestSQLOptionNamesAreRecognized fails when an entry is not actually parsed.
+var sqlOptionNames = []string{
+	"-h", "--host", "-p", "--port", "-u", "--user", "-i", "--key", "-pk",
+	"--password-key", "--sudo-password-key", "--ssh-password-key", "--no-key",
+	"--password-only", "--key-auth", "--accept-unknown-host", "--insecure-hostkey",
+	"--strict-host-key", "--known-hosts", "--engine", "--db", "--database",
+	"--db-file", "--db-user", "--db-host", "--db-port", "--db-password-key",
+	"--statement-file", "--row-threshold", "--allow-full-table", "--no-backup",
+	"--explain", "--backup-dir", "--docker", "--db-cred-from", "--cred-cache",
+	"--cred-refresh", "--sudo", "--force", "-f", "--dry-run", "--json",
+	"--timeout", "--bind", "--via", "--audit-output", "--no-audit",
+	"--bypass-reason", "--expect-plan", "--host-timeout", "--global-timeout",
+}
+
+// sqlStatementToken reports whether an argument can only be statement text
+// rather than an sshx option. SQL files, migrations, and dumps conventionally
+// open with a comment header ("-- ..."), which is exactly a token that starts
+// with "--" but cannot be an option because its name part contains whitespace.
+func sqlStatementToken(arg string) bool {
+	if !strings.HasPrefix(arg, "--") {
+		return false
+	}
+	name, _, _ := strings.Cut(arg, "=")
+	return strings.ContainsAny(name, " \t\r\n")
+}
+
+// unknownSQLOption describes an option-shaped SQL token. A statement that opens
+// with a comment can look like an option, so the message names every way to pass
+// a statement that begins with "-".
+func unknownSQLOption(token string) string {
+	name, _, _ := strings.Cut(token, "=")
+	if suggestion := closestSQLOption(name); suggestion != "" {
+		return fmt.Sprintf("unknown sql option %q (did you mean %q?); a statement is accepted as a positional argument, after --, via --statement-file=PATH, or on stdin", token, suggestion)
+	}
+	return fmt.Sprintf("unknown sql option %q; a statement is accepted as a positional argument, after --, via --statement-file=PATH, or on stdin", token)
+}
+
+// closestSQLOption returns the known sql option nearest to an unrecognized one.
+func closestSQLOption(name string) string {
+	return closestOptionName(name, sqlOptionNames)
+}
+
+// maxSQLStatementBytes bounds a statement read from a file or stdin so a stray
+// stream cannot be buffered into memory.
+const maxSQLStatementBytes = 1 << 20
+
+// readSQLStatement loads one statement from a local file or, when stdin is
+// piped rather than a terminal, from stdin. An empty pipe returns "" so the
+// caller keeps its "statement is required" diagnostic.
+func readSQLStatement(path string) (string, error) {
+	if path != "" {
+		data, err := os.ReadFile(path) // #nosec G304 -- caller-selected local statement file.
+		if err != nil {
+			return "", fmt.Errorf("read --statement-file: %w", err)
+		}
+		if len(data) > maxSQLStatementBytes {
+			return "", fmt.Errorf("--statement-file %s exceeds %d bytes", path, maxSQLStatementBytes)
+		}
+		return string(data), nil
+	}
+	info, err := os.Stdin.Stat()
+	if err != nil {
+		return "", nil
+	}
+	if info.Mode()&os.ModeCharDevice != 0 {
+		return "", nil
+	}
+	data, err := io.ReadAll(io.LimitReader(os.Stdin, maxSQLStatementBytes+1))
+	if err != nil {
+		return "", fmt.Errorf("read SQL statement from stdin: %w", err)
+	}
+	if len(data) > maxSQLStatementBytes {
+		return "", fmt.Errorf("SQL statement on stdin exceeds %d bytes", maxSQLStatementBytes)
+	}
+	return string(data), nil
+}
+
 // parseSQLArgs parses the `sshx sql` guarded SQL execution subcommand. The
 // SQL statement is the positional argument (or everything after `--`).
 func parseSQLArgs(config *sshclient.Config, args []string) {
@@ -667,6 +957,8 @@ func parseSQLArgs(config *sshclient.Config, args []string) {
 			config.SQLDatabase = strings.SplitN(arg, "=", 2)[1]
 		case strings.HasPrefix(arg, "--db-file="):
 			config.SQLFile = strings.SplitN(arg, "=", 2)[1]
+		case strings.HasPrefix(arg, "--statement-file="):
+			config.SQLStatementFile = strings.SplitN(arg, "=", 2)[1]
 		case strings.HasPrefix(arg, "--db-user="):
 			config.SQLUser = strings.SplitN(arg, "=", 2)[1]
 		case strings.HasPrefix(arg, "--db-host="):
@@ -727,14 +1019,37 @@ func parseSQLArgs(config *sshclient.Config, args []string) {
 			config.AuditOutput = strings.SplitN(arg, "=", 2)[1]
 		case arg == "--no-audit":
 			config.AuditEnabled = false
+		case strings.HasPrefix(arg, "--") && sqlStatementToken(arg):
+			// A comment-leading statement is statement text, not an option.
+			sqlParts = append(sqlParts, args[i:]...)
+			i = len(args)
 		case !strings.HasPrefix(arg, "-"):
 			sqlParts = append(sqlParts, args[i:]...)
 			i = len(args)
 		default:
-			config.ArgumentError = fmt.Sprintf("unknown sql option %q", arg)
+			config.ArgumentError = unknownSQLOption(arg)
 		}
 	}
 	config.SQLStatement = strings.TrimSpace(strings.Join(sqlParts, " "))
+	switch {
+	case config.ArgumentError != "":
+	case config.SQLStatement != "" && config.SQLStatementFile != "":
+		config.ArgumentError = "--statement-file cannot be combined with a positional SQL statement"
+	case config.SQLStatementFile != "":
+		statement, readErr := readSQLStatement(config.SQLStatementFile)
+		if readErr != nil {
+			config.ArgumentError = readErr.Error()
+		} else {
+			config.SQLStatement = strings.TrimSpace(statement)
+		}
+	case config.SQLStatement == "":
+		statement, readErr := readSQLStatement("")
+		if readErr != nil {
+			config.ArgumentError = readErr.Error()
+		} else {
+			config.SQLStatement = strings.TrimSpace(statement)
+		}
+	}
 
 	// Password auth implies TCP: peer/ident auth on the local socket ignores
 	// PGPASSWORD, so default the database host to loopback in that case.
@@ -930,8 +1245,6 @@ func parseTextArgs(config *sshclient.Config, args []string) {
 			config.TextUseSudo = true
 		case arg == "--no-redact":
 			config.TextRedact = false
-		case arg == "--help":
-			config.TextHelp = true
 		case arg == "--dry-run":
 			config.DryRun = true
 		case arg == "--json":
diff --git a/internal/app/config_test.go b/internal/app/config_test.go
index 3b0623d..bb74fcc 100644
--- a/internal/app/config_test.go
+++ b/internal/app/config_test.go
@@ -100,7 +100,7 @@ func TestParseArgs_TextSubcommand(t *testing.T) {
 		t.Fatalf("unexpected text flags: %#v", config)
 	}
 	help := ParseArgs([]string{"sshx", "text", "--help", "--json"})
-	if !help.TextHelp || !help.JSONOutput {
+	if help.HelpVerb != "text" || !help.JSONOutput {
 		t.Fatalf("text help not parsed: %#v", help)
 	}
 	denied := ParseArgs([]string{"sshx", "text", "-h=prod", "--command=grep foo"})
diff --git a/internal/app/diagnostics.go b/internal/app/diagnostics.go
index 17286c1..189a08b 100644
--- a/internal/app/diagnostics.go
+++ b/internal/app/diagnostics.go
@@ -3,10 +3,23 @@ package app
 import (
 	"fmt"
 	"io"
+	"os"
 
+	"github.com/talkincode/sshx/internal/sshclient"
 	"github.com/talkincode/sshx/pkg/logger"
 )
 
+// noticeWriter is where human notices go for one invocation: stderr normally, and
+// nothing at all when --quiet asked for a notice-free stream. A notice explains or
+// narrates a result that has already been reported, so suppressing it never changes
+// stdout, the exit code, or the JSON document (issue #86).
+func noticeWriter(config *sshclient.Config) io.Writer {
+	if config != nil && config.Quiet {
+		return io.Discard
+	}
+	return os.Stderr
+}
+
 // writeDiagnosticNote writes a best-effort diagnostic note to w.
 //
 // Notes explain a result that has already been reported on stdout, so a failed
diff --git a/internal/app/dryrun.go b/internal/app/dryrun.go
index 5d2eb4f..6c39b6a 100644
--- a/internal/app/dryrun.go
+++ b/internal/app/dryrun.go
@@ -175,6 +175,49 @@ func emitDryRunPlan(config *sshclient.Config) error {
 	return nil
 }
 
+// sftpPathCheck reports the missing path of an SFTP action, naming the option
+// that supplies it. The compatibility surface splits a transfer across
+// --upload=<local> / --download=<remote> plus --to=<destination>, so a bare
+// "path is required" left the caller guessing which option to add.
+func sftpPathCheck(config *sshclient.Config) string {
+	remote, local := strings.TrimSpace(config.RemotePath), strings.TrimSpace(config.LocalPath)
+	switch config.SftpAction {
+	case "upload":
+		switch {
+		case local == "":
+			return "--upload=<local-file> needs a local path"
+		case remote == "":
+			return "--upload needs a destination: add --to=<remote-path>"
+		}
+	case "download":
+		switch {
+		case remote == "":
+			return "--download=<remote-file> needs a remote path"
+		case local == "":
+			return "--download needs a destination: add --to=<local-path>"
+		}
+	case "list", "mkdir", "remove":
+		if remote == "" {
+			return fmt.Sprintf("%s needs a remote path", sftpActionFlag(config.SftpAction))
+		}
+	}
+	return ""
+}
+
+// sftpActionFlag names the compatibility flag that carries an SFTP action path.
+func sftpActionFlag(action string) string {
+	switch action {
+	case "list":
+		return "--list=<path>"
+	case "mkdir":
+		return "--mkdir=<path>"
+	case "remove":
+		return "--rm=<path>"
+	default:
+		return "--" + action + "=<path>"
+	}
+}
+
 func buildDryRunPlan(config *sshclient.Config) dryRunPlan {
 	plan := dryRunPlan{
 		DryRun:               true,
@@ -346,7 +389,7 @@ func resolveDryRunSSHHost(config *sshclient.Config, plan *dryRunPlan) {
 	if !config.BindSet && hostConfig.Bind != "" {
 		config.Bind = hostConfig.Bind
 	}
-	if sudoKey := hostConfig.EffectiveSudoPasswordKey(); sudoKey != "" && config.SudoKey == sshclient.DefaultSudoKey {
+	if sudoKey := hostConfig.EffectiveSudoPasswordKey(); sudoKey != "" && !sudoKeyChosen(config) {
 		config.SudoKey = sudoKey
 	}
 	if config.SSHPasswordKey == "" {
@@ -450,7 +493,7 @@ func resolveDryRunHostTest(config *sshclient.Config, plan *dryRunPlan) {
 		config.SSHPasswordKey = sshKey
 		plan.hostTestReadsSecret = true
 	}
-	if sudoKey := hostConfig.EffectiveSudoPasswordKey(); sudoKey != "" {
+	if sudoKey := hostConfig.EffectiveSudoPasswordKey(); sudoKey != "" && !sudoKeyChosen(config) {
 		config.SudoKey = sudoKey
 	}
 	if !config.BindSet {
@@ -548,19 +591,12 @@ func fillDryRunValidation(config *sshclient.Config, plan *dryRunPlan) {
 		return
 	}
 	if config.Mode == "sftp" {
-		// Mirror the MCP adapter's pre-flight checks: an empty path cannot
-		// produce a plan, and rejecting it here keeps the diagnostic a config
-		// error instead of a misleading connection failure.
-		if strings.TrimSpace(config.RemotePath) == "" {
-			plan.ConfigCheck = dryRunStatus{Status: "error", ErrorKind: "config", Message: "remote path is required"}
+		// Match the MCP adapter's pre-flight check for the same condition (an
+		// empty path cannot produce a plan); the CLI wording names the flag that
+		// supplies the missing value, while MCP names its JSON fields.
+		if message := sftpPathCheck(config); message != "" {
+			plan.ConfigCheck = dryRunStatus{Status: "error", ErrorKind: "config", Message: message}
 			plan.Valid = false
-			return
-		}
-		if config.SftpAction == "upload" || config.SftpAction == "download" {
-			if strings.TrimSpace(config.LocalPath) == "" {
-				plan.ConfigCheck = dryRunStatus{Status: "error", ErrorKind: "config", Message: "local path is required"}
-				plan.Valid = false
-			}
 		}
 		return
 	}
diff --git a/internal/app/lifecycle.go b/internal/app/lifecycle.go
index 5cdc58b..6942cee 100644
--- a/internal/app/lifecycle.go
+++ b/internal/app/lifecycle.go
@@ -5,7 +5,6 @@ import (
 	"encoding/json"
 	"fmt"
 	"io"
-	"os"
 	"strings"
 	"time"
 
@@ -115,8 +114,9 @@ func emitLifecycleJSON(config *sshclient.Config, value any) error {
 		return err
 	}
 	// Write the human-readable mirror first so the JSON document stays the last
-	// line a caller that merges stderr into stdout would have to parse.
-	reportPolicyRejection(os.Stderr, document)
+	// line a caller that merges stderr into stdout would have to parse. --quiet
+	// suppresses the mirror without touching the document.
+	reportPolicyRejection(noticeWriter(config), document)
 	if err := encodeJSON(document); err != nil {
 		return fmt.Errorf("%w: deliver execution result: %w", execution.ErrLocalIO, err)
 	}
diff --git a/internal/app/lifecycle_policy_test.go b/internal/app/lifecycle_policy_test.go
index e2d855b..e1995d3 100644
--- a/internal/app/lifecycle_policy_test.go
+++ b/internal/app/lifecycle_policy_test.go
@@ -156,6 +156,33 @@ func TestBlockedJSONKeepsStdoutPureAndMirrorsStderr(t *testing.T) {
 	assert.NotContains(t, string(stdout), "blocked by safety policy", "the mirror must not leak into stdout")
 }
 
+// TestBlockedJSONMirrorIsSilencedByQuiet: --quiet keeps the same single JSON
+// document on stdout and drops the human mirror from stderr, so a caller that
+// merges the streams still reads exactly one parseable document (issue #86).
+func TestBlockedJSONMirrorIsSilencedByQuiet(t *testing.T) {
+	config := &sshclient.Config{
+		Mode:       "ssh",
+		Host:       "db1.example.net",
+		Port:       "22",
+		User:       "operator",
+		Command:    `docker exec teamsacs_pgdb18 psql -U teamsacs -d teamsacs -At -c 'select 1'`,
+		JSONOutput: true,
+		Quiet:      true,
+	}
+	blocked := &sshclient.CommandBlockedError{
+		Command: config.Command,
+		Reason:  `Direct PostgreSQL client execution ("psql") bypasses the guarded SQL pipeline.`,
+	}
+
+	var runErr error
+	stdout, stderr := captureStreams(t, func() {
+		runErr = reportSSHFailure(config, nil, sshclient.AuthMethodUnknown, "blocked", blocked)
+	})
+	require.ErrorIs(t, runErr, ErrReported)
+	assert.True(t, json.Valid(bytes.TrimSpace(stdout)), "stdout must stay a single JSON document: %q", stdout)
+	assert.Empty(t, stderr, "--quiet must suppress the policy mirror on stderr")
+}
+
 // TestNonBlockedJSONFailureHasNoMirror: a plain remote failure keeps today's
 // behavior and writes nothing extra to stderr.
 func TestNonBlockedJSONFailureHasNoMirror(t *testing.T) {
diff --git a/internal/app/mcp.go b/internal/app/mcp.go
index 3ab884f..ce42a48 100644
--- a/internal/app/mcp.go
+++ b/internal/app/mcp.go
@@ -210,9 +210,10 @@ func execMCPCommand(ctx context.Context, cmd *exec.Cmd, stdin string, globalTime
 		return nil, nil, err
 	}
 	defer process.close()
-	if stdin != "" {
-		cmd.Stdin = strings.NewReader(stdin)
-	}
+	// Always replace the child's stdin: a one-shot tool call must never be able
+	// to read the MCP client's protocol stream, and an empty payload must reach
+	// EOF instead of blocking. Tools that take no stdin payload get "".
+	cmd.Stdin = strings.NewReader(stdin)
 	// Command's copying goroutines drain both pipes independently. Output and
 	// progress are bounded, and neither writer waits for an MCP client.
 	progress, finishProgress := mcpProgressDispatcher(onEvent)
diff --git a/internal/app/plan.go b/internal/app/plan.go
index 60ccbe6..bed1ae5 100644
--- a/internal/app/plan.go
+++ b/internal/app/plan.go
@@ -422,7 +422,7 @@ func prepareRunPlan(config *sshclient.Config, req *execution.Request, snap *exec
 			}
 		}
 		copyConfig.SSHPasswordKey = firstNonEmpty(req.Policy.SSHPasswordKey, t.SSHPasswordKey)
-		copyConfig.SudoKey = firstNonEmpty(req.Policy.SudoPasswordKey, t.SudoPasswordKey)
+		copyConfig.SudoKey = execution.SudoKeyForTarget(req.Policy.SudoPasswordKey, t.SudoPasswordKey)
 		plan.Targets = append(plan.Targets, publicPlanTarget(&copyConfig, t.Alias, "target", plan))
 		t.KnownHostsData, t.ExpectedKeyFingerprint = copyConfig.KnownHostsData, copyConfig.ExpectedKeyFingerprint
 		t.Bind = copyConfig.Bind
diff --git a/internal/app/plan_admission_test.go b/internal/app/plan_admission_test.go
index 350726d..fd9ef72 100644
--- a/internal/app/plan_admission_test.go
+++ b/internal/app/plan_admission_test.go
@@ -198,13 +198,13 @@ func TestPlanAdmissionRejectsEmptySFTPPaths(t *testing.T) {
 		args    []string
 		message string
 	}{
-		{"upload without local path", []string{"--upload=", "--to=/remote/file"}, "local path is required"},
-		{"upload without remote path", []string{"--upload=/etc/hosts"}, "remote path is required"},
-		{"download without local path", []string{"--download=/remote/file"}, "local path is required"},
-		{"download without remote path", []string{"--download=", "--to=/local/file"}, "remote path is required"},
-		{"list without remote path", []string{"--list="}, "remote path is required"},
-		{"mkdir without remote path", []string{"--mkdir="}, "remote path is required"},
-		{"remove without remote path", []string{"--rm="}, "remote path is required"},
+		{"upload without local path", []string{"--upload=", "--to=/remote/file"}, "--upload=<local-file> needs a local path"},
+		{"upload without destination", []string{"--upload=/etc/hosts"}, "--upload needs a destination: add --to=<remote-path>"},
+		{"download without local path", []string{"--download=/remote/file"}, "--download needs a destination: add --to=<local-path>"},
+		{"download without remote path", []string{"--download=", "--to=/local/file"}, "--download=<remote-file> needs a remote path"},
+		{"list without remote path", []string{"--list="}, "--list=<path> needs a remote path"},
+		{"mkdir without remote path", []string{"--mkdir="}, "--mkdir=<path> needs a remote path"},
+		{"remove without remote path", []string{"--rm="}, "--rm=<path> needs a remote path"},
 	}
 	for _, tc := range cases {
 		t.Run(tc.name, func(t *testing.T) {
diff --git a/internal/app/plugin.go b/internal/app/plugin.go
index fe62869..f4751e7 100644
--- a/internal/app/plugin.go
+++ b/internal/app/plugin.go
@@ -16,7 +16,7 @@ func HandlePluginManagement(config *sshclient.Config) error {
 	}
 	action := config.PluginAction
 	if action == "" {
-		return reportPluginError(config, "config", fmt.Errorf("plugin action is required: create, list, show, validate, test, trust, or remove"))
+		return reportPluginError(config, "config", fmt.Errorf("plugin action is required: create, install, list, show, validate, test, trust, or remove"))
 	}
 
 	var result pluginpkg.ActionResult
@@ -55,10 +55,31 @@ func HandlePluginManagement(config *sshclient.Config) error {
 				},
 			}
 		}
+	case "install":
+		if config.PluginSource == "" {
+			err = fmt.Errorf("plugin source directory is required (sshx plugin install <dir>)")
+			break
+		}
+		var installed *pluginpkg.InstallResult
+		installed, err = pluginpkg.Install(pluginpkg.InstallOptions{
+			Source:  config.PluginSource,
+			Replace: config.PluginReplace,
+			Trust:   config.PluginTrust,
+		})
+		if err == nil {
+			resolved := installed.Resolved
+			result = pluginpkg.ActionResult{
+				Success: true, Action: action, PluginID: resolved.Manifest.ID,
+				Path: resolved.Path, PluginRoot: pluginRootOrEmpty(), Source: config.PluginSource,
+				BackupPath: installed.BackupPath, Digest: resolved.Digest,
+				Trusted: resolved.Trusted, Builtin: resolved.Builtin, Valid: true, Files: installed.Files,
+				NextActions: pluginNextActions(resolved.Manifest.ID, resolved.Trusted),
+			}
+		}
 	case "list":
 		var plugins []pluginpkg.Summary
 		plugins, err = pluginpkg.List()
-		result = pluginpkg.ActionResult{Success: err == nil, Action: action, Plugins: plugins}
+		result = pluginpkg.ActionResult{Success: err == nil, Action: action, Plugins: plugins, PluginRoot: pluginRootOrEmpty()}
 	case "show", "validate":
 		if config.PluginID == "" {
 			err = fmt.Errorf("plugin id is required")
@@ -68,7 +89,7 @@ func HandlePluginManagement(config *sshclient.Config) error {
 		resolved, err = pluginpkg.Resolve(config.PluginID)
 		if err == nil {
 			summary := pluginpkg.SummaryFromResolved(resolved)
-			result = pluginpkg.ActionResult{Success: true, Action: action, PluginID: config.PluginID, Path: resolved.Path, Digest: resolved.Digest, Trusted: resolved.Trusted, Valid: true, Plugin: &summary, Manifest: &resolved.Manifest}
+			result = pluginpkg.ActionResult{Success: true, Action: action, PluginID: config.PluginID, Path: resolved.Path, Digest: resolved.Digest, Trusted: resolved.Trusted, Builtin: resolved.Builtin, Valid: true, Plugin: &summary, Manifest: &resolved.Manifest}
 		}
 	case "test":
 		if config.PluginID == "" {
@@ -80,7 +101,7 @@ func HandlePluginManagement(config *sshclient.Config) error {
 		var testResult pluginpkg.Result
 		resolved, testResult, fixture, err = pluginpkg.Test(config.PluginID, config.PluginFixture)
 		if err == nil {
-			result = pluginpkg.ActionResult{Success: true, Action: action, PluginID: config.PluginID, Path: resolved.Path, Digest: resolved.Digest, Trusted: resolved.Trusted, Valid: true, Fixture: fixture, TestResult: &testResult}
+			result = pluginpkg.ActionResult{Success: true, Action: action, PluginID: config.PluginID, Path: resolved.Path, Digest: resolved.Digest, Trusted: resolved.Trusted, Builtin: resolved.Builtin, Valid: true, Fixture: fixture, TestResult: &testResult}
 		}
 	case "trust":
 		if config.PluginID == "" {
@@ -90,7 +111,7 @@ func HandlePluginManagement(config *sshclient.Config) error {
 		var resolved *pluginpkg.Resolved
 		resolved, err = pluginpkg.Trust(config.PluginID)
 		if err == nil {
-			result = pluginpkg.ActionResult{Success: true, Action: action, PluginID: config.PluginID, Path: resolved.Path, Digest: resolved.Digest, Trusted: true, Valid: true}
+			result = pluginpkg.ActionResult{Success: true, Action: action, PluginID: config.PluginID, Path: resolved.Path, Digest: resolved.Digest, Trusted: true, Builtin: resolved.Builtin, Valid: true}
 		}
 	case "remove":
 		if config.PluginID == "" {
@@ -175,9 +196,7 @@ func emitPluginResult(config *sshclient.Config, result pluginpkg.ActionResult) e
 		return nil
 	}
 	if result.Action == "list" {
-		for _, summary := range result.Plugins {
-			fmt.Printf("%s\t%s\ttrusted=%t\tbuiltin=%t\tvalid=%t\n", summary.ID, summary.Version, summary.Trusted, summary.Builtin, summary.Valid)
-		}
+		printPluginList(result)
 		return nil
 	}
 	fmt.Printf("plugin %s: %s", result.Action, result.PluginID)
@@ -188,5 +207,59 @@ func emitPluginResult(config *sshclient.Config, result pluginpkg.ActionResult) e
 		fmt.Printf("; backup=%s", result.BackupPath)
 	}
 	fmt.Println()
+	if result.Digest != "" {
+		fmt.Printf("  builtin=%t trusted=%t valid=%t digest=%s\n", result.Builtin, result.Trusted, result.Valid, result.Digest)
+	}
+	for _, next := range result.NextActions {
+		fmt.Printf("  next: %s\n", next)
+	}
 	return nil
 }
+
+// printPluginList groups the inventory by provenance and always names the local
+// plugin root, so "no local plugins installed" is visible as such instead of
+// having to be inferred from the absence of rows, and a local entry shows the
+// state and digest a caller needs before running it.
+func printPluginList(result pluginpkg.ActionResult) {
+	builtins, local := []pluginpkg.Summary{}, []pluginpkg.Summary{}
+	for _, summary := range result.Plugins {
+		if summary.Builtin {
+			builtins = append(builtins, summary)
+		} else {
+			local = append(local, summary)
+		}
+	}
+	fmt.Printf("built-in capabilities (%d):\n", len(builtins))
+	for _, summary := range builtins {
+		fmt.Printf("  %s\t%s\ttrusted=true\tvalid=%t\n", summary.ID, summary.Version, summary.Valid)
+	}
+	fmt.Printf("local plugins (%d) in %s:\n", len(local), result.PluginRoot)
+	if len(local) == 0 {
+		fmt.Printf("  (none; use \"sshx plugin install <dir>\" or \"sshx plugin create <id>\")\n")
+		return
+	}
+	for _, summary := range local {
+		if !summary.Valid {
+			fmt.Printf("  %s\tINVALID\t%s\t%s\n", summary.ID, summary.ErrorKind, summary.Error)
+			continue
+		}
+		fmt.Printf("  %s\t%s\ttrusted=%t\tvalid=true\tdigest=%s\n", summary.ID, summary.Version, summary.Trusted, summary.Digest)
+	}
+}
+
+// pluginRootOrEmpty names the local plugin root for discovery output.
+func pluginRootOrEmpty() string {
+	root, err := pluginpkg.Root()
+	if err != nil {
+		return ""
+	}
+	return root
+}
+
+// pluginNextActions points at the remaining step after a plugin lands.
+func pluginNextActions(id string, trusted bool) []string {
+	if trusted {
+		return []string{"sshx plugin test " + id + " --json", "sshx inspect -h=<host> " + id + " --json"}
+	}
+	return []string{"sshx plugin validate " + id + " --json", "sshx plugin trust " + id + " --json", "sshx inspect -h=<host> " + id + " --json"}
+}
diff --git a/internal/app/run.go b/internal/app/run.go
index 1683e5f..e8cbabd 100644
--- a/internal/app/run.go
+++ b/internal/app/run.go
@@ -121,14 +121,14 @@ func HandleRun(config *sshclient.Config, audit *auditRecorder) error {
 	if execErr != nil {
 		if outcome.RunID != "" {
 			recordRunAudit(audit, config, req, snap, outcome)
-			reportRunSudoPromptFailures(outcome, req.Action.Command)
+			reportRunSudoPromptFailures(config, outcome, req.Action.Command)
 			return execErr
 		}
 		return reportRunRequestFailure(config, audit, execErr)
 	}
 
 	recordRunAudit(audit, config, req, snap, outcome)
-	reportRunSudoPromptFailures(outcome, req.Action.Command)
+	reportRunSudoPromptFailures(config, outcome, req.Action.Command)
 
 	// Single-target --json emits one versioned result document.
 	if req.JSONOutput && !req.JSONLOutput && outcome.Single != nil {
@@ -153,20 +153,21 @@ func HandleRun(config *sshclient.Config, audit *auditRecorder) error {
 // mid-command sudo stops with "a password is required". It writes straight to
 // stderr because the caller explaining a failure may be running with
 // diagnostics quieted, and stdout must keep exactly one result document.
-func reportRunSudoPromptFailures(outcome execution.RunOutcome, command string) {
+func reportRunSudoPromptFailures(config *sshclient.Config, outcome execution.RunOutcome, command string) {
 	hint, needed := sshclient.NonLeadingSudoHint(command)
 	if !needed {
 		return
 	}
+	out := noticeWriter(config)
 	for _, res := range outcome.Results {
 		if !sshclient.SudoPasswordPromptFailure(res.Stderr + res.Stdout) {
 			continue
 		}
 		if label := res.Target.Alias; label != "" {
-			fmt.Fprintf(os.Stderr, "sshx: [%s] %s\n", label, hint)
+			writeDiagnosticNote(out, "sshx: [%s] %s\n", label, hint)
 			continue
 		}
-		fmt.Fprintf(os.Stderr, "sshx: %s\n", hint)
+		writeDiagnosticNote(out, "sshx: %s\n", hint)
 	}
 }
 
@@ -385,10 +386,13 @@ func buildRunRequest(config *sshclient.Config) (*execution.Request, *execution.P
 			UseKeyAuth:           config.UseKeyAuth,
 			KeyPath:              config.KeyPath,
 			SSHPasswordKey:       config.SSHPasswordKey,
-			SudoPasswordKey:      config.SudoKey,
-			SSHPassword:          config.Password,
-			Bind:                 config.Bind,
-			BindSet:              config.BindSet,
+			// Run resolves each target's sudo key from its host record, so the policy
+			// carries only an explicit caller choice: the built-in default must not
+			// shadow a host's sudo_password_key (issue #78).
+			SudoPasswordKey: sudoKeyChoice(config),
+			SSHPassword:     config.Password,
+			Bind:            config.Bind,
+			BindSet:         config.BindSet,
 		},
 		JSONOutput:   config.JSONOutput,
 		JSONLOutput:  config.JSONLOutput,
@@ -492,6 +496,12 @@ func recordRunAudit(audit *auditRecorder, config *sshclient.Config, req *executi
 	audit.event.Concurrency = req.Limits.Concurrency
 	audit.event.FailureMode = req.Policy.FailureMode
 	audit.event.TargetCount = snap.Count
+	// Run resolves the sudo key per target, so the summary records only a caller
+	// choice: the built-in default would misreport a fleet whose hosts each carry
+	// their own sudo_password_key (issue #78). Per-target events record the
+	// reference each host actually used.
+	audit.event.SudoKey = sudoKeyChoice(config)
+	audit.sudoKeyResolved = true
 	audit.completed = true
 	audit.event.Metadata = outcome.Metadata
 	if outcome.Counts.Succeeded == outcome.Counts.Selected && outcome.Counts.Failed == 0 {
@@ -515,10 +525,17 @@ func writeTargetAudit(config *sshclient.Config, runID string, req *execution.Req
 	if config == nil || !config.AuditEnabled || config.DryRun {
 		return nil
 	}
-	rec := newAuditRecorder(config)
+	// The audit event must name the credential this target used: run resolves the
+	// sudo and SSH password keys from the host record, while the caller-level
+	// config still carries the caller's choice or the built-in default.
+	targetConfig := *config
+	targetConfig.SudoKey = execution.SudoKeyForTarget(req.Policy.SudoPasswordKey, tr.Target.SudoPasswordKey)
+	targetConfig.SSHPasswordKey = firstNonEmptyStr(req.Policy.SSHPasswordKey, tr.Target.SSHPasswordKey)
+	rec := newAuditRecorder(&targetConfig)
 	if rec == nil {
 		return nil
 	}
+	rec.sudoKeyResolved = true
 	rec.event.Mode = "run"
 	rec.event.Action = req.Action.Kind
 	rec.event.RunID = runID
@@ -547,7 +564,7 @@ func writeTargetAudit(config *sshclient.Config, runID string, req *execution.Req
 	} else {
 		rec.event.Outcome = auditStatus{Status: "failed"}
 	}
-	return rec.finish(config, nil)
+	return rec.finish(&targetConfig, nil)
 }
 
 func max(a, b int) int {
diff --git a/internal/app/sql.go b/internal/app/sql.go
index 8bad27e..ccaf898 100644
--- a/internal/app/sql.go
+++ b/internal/app/sql.go
@@ -262,7 +262,7 @@ func validateSQLConfig(config *sshclient.Config) error {
 		return fmt.Errorf("host is required (use -h=<host>)")
 	}
 	if config.SQLStatement == "" {
-		return fmt.Errorf("SQL statement is required (positional argument or after --)")
+		return fmt.Errorf("SQL statement is required (positional argument, after --, --statement-file=PATH, or on stdin)")
 	}
 	if config.SQLEngine == sqlsafe.EngineSQLite {
 		return validateSQLiteConfig(config)
diff --git a/internal/app/text.go b/internal/app/text.go
index 663b134..0d41774 100644
--- a/internal/app/text.go
+++ b/internal/app/text.go
@@ -2,7 +2,6 @@ package app
 
 import (
 	"fmt"
-	"os"
 	"strings"
 	"time"
 
@@ -161,7 +160,7 @@ func (r *textRun) collect(req textsafe.Request) (textsafe.Result, error) {
 	// A streamed SFTP window is the only source that can idle for minutes, so it
 	// is the one that narrates progress. stdout stays untouched because the
 	// reporter writes to stderr.
-	r.reporter = newTextScanReporter(os.Stderr, req.Pattern != "")
+	r.reporter = newTextScanReporter(noticeWriter(r.config), req.Pattern != "")
 	r.scanStart = time.Now()
 	switch req.Kind {
 	case textsafe.SourceFile:
diff --git a/internal/app/text_progress_test.go b/internal/app/text_progress_test.go
index 22a6a01..d8b5f05 100644
--- a/internal/app/text_progress_test.go
+++ b/internal/app/text_progress_test.go
@@ -10,6 +10,7 @@ import (
 	"github.com/stretchr/testify/require"
 
 	"github.com/talkincode/sshx/internal/execution"
+	"github.com/talkincode/sshx/internal/sshclient"
 	"github.com/talkincode/sshx/internal/textsafe"
 )
 
@@ -224,7 +225,7 @@ func TestReportRunSudoPromptFailuresPerTarget(t *testing.T) {
 	}
 
 	_, stderr := captureStreams(t, func() {
-		reportRunSudoPromptFailures(outcome, command)
+		reportRunSudoPromptFailures(&sshclient.Config{}, outcome, command)
 	})
 
 	// Only the target that actually hit the prompt is named.
@@ -266,9 +267,17 @@ func TestReportRunSudoPromptFailuresStaysQuiet(t *testing.T) {
 	for _, tc := range tests {
 		t.Run(tc.name, func(t *testing.T) {
 			_, stderr := captureStreams(t, func() {
-				reportRunSudoPromptFailures(tc.outcome, tc.command)
+				reportRunSudoPromptFailures(&sshclient.Config{}, tc.outcome, tc.command)
 			})
 			assert.Empty(t, string(stderr))
 		})
 	}
+
+	// --quiet suppresses the hint even when it would otherwise be printed.
+	t.Run("quiet suppresses the hint", func(t *testing.T) {
+		_, stderr := captureStreams(t, func() {
+			reportRunSudoPromptFailures(&sshclient.Config{Quiet: true}, refusal, `cd /srv && sudo id`)
+		})
+		assert.Empty(t, string(stderr))
+	})
 }
diff --git a/internal/app/usage.go b/internal/app/usage.go
index be0fff1..e61ec97 100644
--- a/internal/app/usage.go
+++ b/internal/app/usage.go
@@ -1,753 +1,195 @@
 package app
 
-import "fmt"
+import (
+	"fmt"
+	"strings"
+
+	"github.com/talkincode/sshx/internal/execution"
+	"github.com/talkincode/sshx/internal/sshclient"
+)
 
 // Version is the sshx build version, set by the main package at startup
 // (injected via -ldflags). Defaults to "dev" for go test / go run builds.
 var Version = "dev"
 
-// PrintUsage prints the usage information for the sshx command.
-func PrintUsage() {
-	fmt.Printf("\nSSHX — Agent-native remote host execution over SSH\nVersion: %s\n", Version)
-	fmt.Println(`
-Usage:
-  sshx -h=<host> [options] <command>              # SSH mode (compatibility)
-  sshx run [selectors] [options] -- <command>     # Canonical execution contract
-  sshx run --script-file=PATH ...                 # Byte-preserving script payload
-  sshx -h=<host> [options] --upload=<file>        # SFTP upload
-  sshx -h=<host> [options] --download=<file>      # SFTP download
-  sshx --transfer=<host>:<path> --to=<host>:<path> # Server-to-server transfer
-  sshx --password-set=<key>[:<password>]          # Store a password (keyring or local vault)
-  sshx --password-get=<key>                       # Get password from OS keyring (denied for local vault)
-  sshx --password-delete=<key>                    # Delete a stored password
-  sshx --password-list                            # List stored or common password keys
-  sshx --host-add                                 # Add host configuration
-  sshx --host-update                              # Update host configuration
-  sshx --host-list                                # List configured hosts
-  sshx --host-test=<name>                         # Test host connection
-  sshx --host-test-all                            # Test all host connections
-  sshx --host-remove=<name>                       # Remove host configuration
-  sshx skill install [options]                    # Install/update the bundled Agent skill
-  sshx plugin create <id> [options]               # Scaffold a local inspection plugin
-  sshx plugin list [--json]                       # List built-in and local capabilities
-  sshx inspect -h=<host> <capability> [options]   # Run one structured host inspection
-  sshx sql -h=<host> --db=<name> [options] "SQL"  # Guarded SQL via remote psql/sqlite3
-  sshx ros -h=<host> [options] <cmd...>           # MikroTik RouterOS over SSH
-  sshx apply -h=<host> --path=<remote> --from=<local>  # Guarded remote file apply
-  sshx text -h=<host> --path=<remote> [options]   # Bounded remote text/log dissection
-  sshx login <name> [--sudo]                      # Human interactive login (TTY required)
-  sshx mcp                                        # Serve the execution contract over stdio (MCP)
-  sshx audit query [filters] [--json]             # Read-only audit trail query
-  sshx audit export --to=<file> [filters]         # Export matching audit events as JSONL
-
-SSH Options:
-  -h, --host=HOST          Remote host address (required in compatibility mode)
-  -p, --port=PORT          SSH port (default: 22)
-  -u, --user=USER          SSH username (default: master)
-  -i, --key=PATH           SSH private key path (default: ~/.ssh/id_rsa)
-  -pk, --password-key=KEY  Sudo password keyring key name (default: master)
-                           Used only when the remote command starts with sudo
-  --ssh-password-key=KEY   SSH login password keyring key (never used for sudo)
-  --bind=ADDR              Local source IP or interface (e.g. 192.0.2.10 or en0)
-  --via=NAME               Named sshx jump host (session-bound; no local tunnel)
-  --dry-run                Print the local execution plan without side effects
-  --expect-plan=HASH       Require the reviewed sha256:<64 lowercase hex> plan
-  --audit-output=DIR       Write audit JSONL files to DIR (default: ~/.sshx/audit)
-  --no-audit               Disable local audit event writing for this invocation
-  --timeout=DURATION       Command execution timeout (e.g. 30s, 2m, or 30 = seconds)
-  --host-timeout=DURATION  Optional total admitted-target budget (setup + verify)
-  --global-timeout=DURATION Optional operation budget, including queued targets
-  --json                   Emit a single structured JSON result on stdout
-  --pty                    Request a PTY (merges stderr into stdout; off by default)
-  --version                Show version information (alias: -v)
-  --help                   Show this help message
-
-Run Contract (preferred for Agents):
-  sshx run --target=prod-web --json -- "systemctl is-active nginx"
-  sshx run --group=prod-web --tag=env=prod --concurrency=4 --jsonl -- "uptime"
-  sshx run --target=prod-web --script-file=./check.sh --json
-  cat ./check.sh | sshx run --target=prod-web --script-stdin --json
-
-  Selectors (configured hosts only; multi-host never treats names as DNS):
-    --target=NAME            strict alias (repeatable via --targets=a,b)
-    --group=NAME             union with other names/groups (repeatable)
-    --tag=key=value          AND filter (repeatable)
-    --all-hosts              all configured hosts before tag filters
-    --address=HOST           explicit single literal address (not for fan-out)
-
-  Script payloads:
-    --script-file=PATH       byte-preserving script from a local file
-    --script-stdin           byte-preserving script from stdin
-    --shell=NAME             interpreter override: sh, bash, zsh, dash, ksh, ash
-                             (default: the script's #! line, else sh)
-
-  Limits / policy:
-    --concurrency=N          default 4, hard max 32
-    --failure-mode=continue|fail_fast   default continue
-    --fail-fast              Alias of --failure-mode=fail_fast
-    --max-failures=N          Stop new admission at this failure threshold
-    --intent=read|change|unknown
-    --force / --no-safety-check require --bypass-reason=TEXT
-    --jsonl                  stream run_started/target_*/run_finished events
-
-  Failure thresholds stop admission only; already admitted targets finish and
-  can add failures. Conflicting failure policies are configuration errors.
-  New time budgets are opt-in; --timeout keeps its existing meaning/defaults.
-  Cancellation closes local transport work, not guaranteed remote termination
-  or rollback. Treat unacknowledged changes as uncertain before retrying.
-
-  Multi-target exit codes:
-    0    all selected targets succeeded
-    1    run accepted but at least one target failed/skipped/uncertain
-    255  request-level failure (bad selectors, zero matches, invalid input)
-
-Agent / Scripting Mode:
-  By default command output streams live with stdout and stderr kept on
-  separate channels (no PTY), and the remote command's exit status is
-  propagated as sshx's own exit code.
-
-  Compatibility --json emits one JSON object on stdout:
-    {host, port, user, command, exit_code, success, stdout, stderr,
-     stdout_truncated, stderr_truncated, duration_ms, auth_method,
-     error_kind, error}
-  sshx run --json adds versioned fields (schema_version, run_id, status,
-  phase, completion, structured error).
-
-  Shared Execution Evidence:
-    plan_hash, risk, effects, execution_id, parent_execution_id,
-    execution_fingerprint, change_state, executed (nullable), verified,
-    verification, preconditions, postconditions.
-  change_state is changed|unchanged|unknown; null executed is not false.
-  Success, execution acknowledgement, change, and verification are distinct.
-  Unknown commands/scripts default to mutation risk with unknown effects;
-  --intent=read is not proof of read-only behavior. Risk is
-  read|mutation|privileged|destructive, not an authorization grant.
-  Raw stdout/stderr and secret values are not execution-fingerprinted.
-
-  Exit codes (single-host compatibility mode):
-    0          command succeeded
-    1..254     remote command's exit status (propagated verbatim)
-    255        sshx-level failure (connect/auth/host-key/timeout/blocked/...)
-    In --json mode an sshx-level failure has exit_code -1 and a non-empty
-    error_kind (timeout, auth, host_key, connect, blocked, exit_missing,
-    config, error), so it is always distinguishable from a remote exit 255.
-
-  A policy block also writes its reason to stderr
-  (exit_code=-1, error_kind=blocked, phase=admission, executed=false), so a
-  caller that only prints the streams sees why nothing ran. Use the guarded
-  alternative instead: sshx sql -h=<host> --db=<name> [--docker=<container>]
-  "<SQL>". stdout still carries exactly one JSON document.
-
-  Trust note: high-risk bypasses (force, no-safety-check, accept-unknown-host,
-  insecure-hostkey) require explicit CLI flags. Inherited env values and
-  working-directory .env files are ignored for those decisions.
-
-Sudo Auto-fill:
-  sshx auto-fills a sudo password only when the remote command starts with
-  sudo, for example:
-    sshx -h=host "sudo systemctl status nginx"
-
-  Non-leading sudo is not auto-filled and does not trigger keyring lookup:
-    sshx -h=host "sh -c 'sudo whoami'"
-    sshx -h=host "echo sudo"
-
-  sshx warns on stderr when it sees a non-leading sudo, because the remote then
-  stops with "sudo: a password is required". Wrap the privileged part instead:
-    sshx -h=host "sudo sh -c 'cd /data/app && docker compose up -d'"
-
-  This keeps keyring lookup, stdin password injection, and future audit fields
-  on one clear rule. Put sudo at the beginning of the remote command when you
-  want sshx to auto-fill it.
-
-Dry-run Plan Preview:
-  Add --dry-run to see how sshx would interpret an invocation before any
-  connection, command execution, keyring secret lookup, known_hosts mutation, or
-  settings write. Use --json with --dry-run for an agent-readable plan.
-
-  Examples:
-    sshx -h=prod-web --dry-run "sudo systemctl restart nginx"
-    sshx -h=prod-web --dry-run --json --upload=local.txt --to=/tmp/local.txt
-
-  Dry-run is a local plan preview only. It does not prove the remote command
-  would succeed.
-
-  Bound Plan Admission:
-  Remote command/run/apply/sql/SFTP/transfer/inspect previews add a nested
-  sshx.plan.v1 plan plus plan_hash and risk. Run keeps sshx.request.v1 outside.
-  Repeat reviewed inputs with --expect-plan=sha256:<64 lowercase hex>.
-  Local mismatch fails before secret lookup or network work; --force cannot
-  bypass it. Errors: config (format), plan_mismatch, plan_unresolved.
-  Check plan.bindable and plan.unresolved: DNS-only addresses, unavailable
-  public-key sidecars, missing/relaxed trust, and remotely discovered SQL
-  identity cannot bind offline. The entire sorted known_hosts record snapshot
-  is hashed, so unrelated trust changes can conservatively invalidate a plan.
-  Dry-run never connects, reads secrets, or writes state. A plan hash is not
-  a lock on remote files, rows, permissions, or recursive directory membership.
-
-Audit Trail:
-  sshx writes one structured JSONL audit event per non-dry-run invocation to
-  ~/.sshx/audit/sshx-YYYY-MM-DD.jsonl by default. Use --audit-output=<dir> to
-  save audit events next to a project or incident record.
-
-  Audit events record metadata and outcomes such as mode/action, host
-  resolution, sudo/keyring decisions, safety status, auth method, exit code, and
-  error kind. They do not record plaintext passwords, private key contents, or
-  stdout/stderr. Command text is best-effort redacted for password/token-style
-  arguments.
-
-  Read-only consumption:
-    sshx audit query --since=2026-09-01 --target=prod-web --json
-    sshx audit query --run-id=<id> --error-kind=blocked --bypass-only
-    sshx audit query --execution-id=<id> --json
-    sshx audit export --to=./incident.jsonl --since=2026-09-01
-  Empty query results exit 0. JSON mode emits {schema_version, success, count, events}.
-  Corrupt/partial records have visible diagnostics; valid records are retained.
-  Audit writes are best-effort, with persistence status separate from execution.
-  Do not repeat a successful mutation just because audit writing failed.
-
-Safety Options:
-  -f, --force           Force execution, bypass safety checks (use with caution!)
-  --no-safety-check     Disable safety checks completely (not recommended)
-  --bypass-reason=TEXT  Required with --force / --no-safety-check in command
-                        mode and sshx run (recorded in dry-run, result, audit)
-
-  Safety checks protect against:
-    - Destructive operations (rm -rf /, mkfs, dd)
-    - System shutdown/reboot commands
-    - Critical file modifications (/etc/passwd, /etc/shadow)
-    - Dangerous pipe operations (curl | sh)
-    - Fork bombs and other malicious patterns
-    - Direct database client execution (psql/pgcli/sqlite3/mysql/mariadb,
-      incl. docker exec, sudo -u, sh -c, kubectl exec wrappers) — use 'sshx sql' instead
-
-SFTP Options:
-  --upload=<local>      Upload file (use with --to=<remote>)
-  --download=<remote>   Download file (use with --to=<local>)
-  --to=<path>           Target path for upload/download
-  --list=<path>         List directory contents (alias: --ls)
-  --mkdir=<path>        Create remote directory
-  --rm=<path>           Remove remote file or directory
-
-  Add --json for structured operation/effect evidence. Size-only verification
-  does not prove content equality. Partial recursive progress is not rolled
-  back as one atomic directory operation.
-
-Server-to-Server Transfer:
-  --transfer=<src-host>:<src-path> --to=<dst-host>:<dst-path>
-
-  Streams files directly from one server to another through the local
-  machine (nothing is written to local disk). Supports single files and
-  recursive directory transfers, and preserves file permission bits.
-  Both hosts can be configured host names (from ~/.sshx/settings.json)
-  or IP addresses, each using its own SSH key/user/port from settings.
-
-Password Management (Cross-Platform):
-  --password-set=<key>[:<password>]   Store a password in the secret backend
-                                      If password omitted, will prompt
-  --password-get=<key>                OS keyring: emit the value only when piped.
-                                      Local vault: always refused (write-only).
-  --password-check=<key>              Check if password exists (alias: --password-exists).
-                                      Missing keys exit non-zero. --json emits
-                                      sshx.secrets.v1 with success/exists.
-  --password-delete=<key>             Delete password (alias: --password-del)
-  --password-list                     List stored keys (vault) or common keys (keyring).
-                                      --json emits keys[] (list_complete=false on keyring probes)
-
-  Default backend: OS keyring (macOS Keychain / Linux Secret Service /
-  Windows Credential Manager). Headless servers can opt into an encrypted
-  local vault with SSHX_SECRET_BACKEND=local-vault. There is no silent
-  fallback. The vault never displays secret values; sshx injects them over
-  stdin during execution. Unlock with SSHX_VAULT_PASSPHRASE or
-  SSHX_VAULT_KEY_FILE (0600). The vault file is $SSHX_HOME/vault.
-
-Host Management:
-  --host-add                          Add new host (interactive or with options).
-                                      Omitting -pk does not persist sudo_password_key=master.
-                                      --json emits sshx.hosts.v1 for add/update/remove/test.
-  --host-import                       Selectively import hosts from ~/.ssh/config (interactive)
-  --host-import=<name1,name2>         Import only the named ssh_config hosts (non-interactive)
-  --ssh-config=<path>                 ssh_config file to import from (default: ~/.ssh/config)
-  --host-update                       Update existing host configuration
-  --host-list                         List all configured hosts (alias: --host-ls)
-  --host-test=<name>                  Test connection to configured host
-  --host-test-all                     Test connections for all configured hosts
-  --host-remove=<name>                Remove host from configuration (alias: --host-rm)
-
-  Host Add/Update Options:
-    --host-name=<name>                Host name (unique identifier, required for update)
-    --host-desc=<description>         Host description
-    -h=<address>                      Host address (IP or hostname)
-    -p=<port>                         SSH port
-    -u=<user>                         SSH username
-    -i=<key>, --key=<key>            SSH private key path for this host (optional)
-    -pk=<key>                         Password key name
-    --host-type=<type>                System type (linux/windows/macos)
-    --bind=<ip|iface>                 Persist a source address for this host
-    --via=<name>                      Named jump host for this target
-
-  Configuration file: ~/.sshx/settings.json
-
-Inspection Capabilities:
-  sshx inspect -h=<host> <capability> [options]
-
-  Built in:
-    system.identity, system.resources, system.baseline
-    network.interfaces, network.routes, network.dns
-    network.listeners, network.firewall
-
-  --cache=off|remote-prefer  Reuse/write a remote observation (default: off)
-  --refresh                  Ignore a reusable observation and run the collector
-  --max-age=DURATION         Require observations no older than this duration
-  --allow-stale              Explicitly allow an expired observation
-  --sudo                     Use sudo for an optional-privilege plugin
-
-  Collectors execute once through SSH stdin and are never installed on the
-  target. With remote-prefer caching, only redacted JSON is stored below the
-  remote user's ~/.sshx/observations/v1 directory.
-
-Guarded SQL Execution:
-  sshx sql -h=<host> --db=<name> [options] "<single SQL statement>"
-  sshx sql -h=<host> --engine=sqlite --db-file=/abs/path.db [options] "SQL"
-  sshx sql -h=<host> --db=<name> [options] -- <SQL words...>
-
-  Statements run through the database client already present on the remote
-  host (psql, sqlite3, or mysql/mariadb). sshx embeds no database driver and opens no tunnel.
-  Exactly one statement per invocation. Unknown or dangerous statement heads
-  (DROP DATABASE/SCHEMA, ALTER SYSTEM, COPY, DO, ATTACH, sqlite3 dot-commands,
-  transaction control, multi-statement input), psql meta-commands,
-  EXPLAIN ANALYZE, data-modifying CTE bodies, SELECT INTO, CALL, dblink,
-  load_extension, writable PRAGMA, and other unanalyzable forms are blocked
-  fail-closed. PostgreSQL reads run in a read-only transaction; SQLite reads
-  open the file URI with mode=ro. Direct psql/pgcli/sqlite3 invocations in
-  run/command mode are blocked — use sshx sql. Every invocation is audited
-  with a literal-redacted statement, its exact SHA-256 digest, classification,
-  backup, and outcome.
-
-  --engine=postgres|sqlite|mysql  SQL engine (default: postgres)
-  --db=NAME                 PostgreSQL database name, or SQLite path if --db-file is omitted
-  --db-file=PATH            Absolute SQLite database file path (required for --engine=sqlite)
-  --db-user=USER            Database role (default: remote psql default; sqlite unused)
-  --db-host=HOST            Database host as seen from the remote (default: local socket)
-  --db-port=PORT            Database port
-  --db-password-key=KEY     Keyring key for the DB password; delivered via stdin,
-                            never via argv (implies --db-host=127.0.0.1 when unset)
-  --docker=CONTAINER        Run psql inside this container via docker exec -i
-                            (default connection becomes the container-local socket;
-                            backups still land on the host)
-  --db-cred-from=SOURCE     Resolve DB credentials on the remote host instead of the
-                            local keyring: docker:<container> (container env) or
-                            env-file:<path> (KEY=VALUE file). Recognizes PG*,
-                            POSTGRES_*, DB_* keys and DATABASE_URL. Mutually
-                            exclusive with --db-password-key; --db becomes optional
-                            when the source provides the database name.
-  --cred-cache=off|DURATION Temporary local cache for remotely resolved credentials
-                            (default: 15m). The secret lives only in the secret backend;
-                            ~/.sshx/sql-cred-cache.json records identity + expiry.
-                            Expired entries are deleted from the keyring.
-  --cred-refresh            Drop the cached entry and re-resolve from the source
-  --explain                 Run EXPLAIN only; never executes the statement
-  --row-threshold=N         EXPLAIN row estimate that upgrades a row backup to a
-                            full-table CSV snapshot (default: 1000)
-  --allow-full-table        Required for UPDATE/DELETE without a WHERE clause
-  --no-backup               Skip pre-change backup (requires --force)
-  --backup-dir=PATH         Remote backup directory (default: ~/.sshx/sql-backups)
-  --sudo                    Run sqlite3/psql via sudo -S (SSH user cannot open the file)
-  --force, -f               Confirms DDL; destructive DDL also requires --no-backup
-
-  Safety pipeline for data changes: classify locally (fail-closed), gate by
-  policy, then snapshot and execute. PostgreSQL runs EXPLAIN (FORMAT JSON)
-  and snapshots rows or the table under one transaction plus a SHARE ROW
-  EXCLUSIVE lock. SQLite skips row estimates and snapshots the table (CSV)
-  or the whole file under BEGIN IMMEDIATE. Whole-file .backup uses a second
-  read-only client while the mutation client holds the writer lock; mutation
-  is sent only after snapshot completion. SELECT and other reads skip EXPLAIN
-  and backups.
-  Catalog preflight blocks automatic execution when triggers, rewrite rules,
-  partitions, or cascading referential actions can affect related tables;
-  proceed only after an independent backup with --force --no-backup. Automatic
-  backups are not claimed for destructive DDL, which also requires
-  --force --no-backup. Backup directories/files are owner-only. --dry-run
-  previews the local plan without connecting; runtime catalog checks may block.
-  Row counts are engine-specific evidence, not universal proof of value changes.
-  Commit acknowledgement and verification are separate; uncertain commits need
-  inspection before retry. MySQL atomicity requires a supported, proven strategy:
-  separate-session backup/mutation and implicit-commit DDL are not atomic.
-  Bound SQL cannot depend on remote credential/container identity discovery.
-  SQL evidence.verification=protocol_verified acknowledges the client protocol,
-  not actual changed values; effect_verification remains separate.
-  Mutation state_change stays unknown, including zero affected rows.
-  Missing/malformed evidence reports protocol_error or verification_failed.
-  Guarded MySQL supports simple InnoDB single-table UPDATE/DELETE with a write
-  lock. Its SSHX_MYSQL_HEX_ROWS_V1 backup preserves NULL/binary values and is
-  not CSV, a schema dump, or automatic restore; no backup table/DDL is created.
-
-  sshx sql -h=db1 --db=app "SELECT count(*) FROM users"
-  sshx sql -h=db1 --db=app --db-user=app --db-password-key=app-db \
-      "UPDATE users SET active=false WHERE id=42"
-  sshx sql -h=db1 --db=app --explain "DELETE FROM sessions WHERE expires_at < now()"
-  sshx sql -h=db1 --db=app --force "TRUNCATE staging_events"
-  # Dockerized production DB: credentials live in the container env, psql runs
-  # inside the container, resolved credentials are cached in the keyring for 15m
-  sshx sql -h=prod --docker=pg-prod --db-cred-from=docker:pg-prod \
-      "UPDATE users SET active=false WHERE id=42"
-  sshx sql -h=prod --docker=pg-prod --db-cred-from=env-file:/opt/app/.env \
-      --cred-cache=1h "SELECT count(*) FROM orders"
-  sshx sql -h=app --engine=sqlite --db-file=/var/lib/app/app.db --json \
-      "UPDATE users SET active=0 WHERE id=42"
-  sshx sql -h=app --engine=sqlite --db-file=/var/lib/app/app.db --sudo --json \
-      "UPDATE users SET active=0 WHERE id=42"
-
-MikroTik RouterOS (ROS) over SSH:
-  sshx ros -h=<host> [options] <path...> <action> [key=value ...]
-  sshx ros -h=<host> interface print [--json]
-  sshx ros -h=<host> ip address add address=192.168.88.1/24 interface=ether1
-  sshx ros -h=<host> raw "/system/resource/print"
-  sshx ros -h=<host> file upload <local> <remote>
-  sshx ros -h=<host> file download <remote> <local>
-  sshx ros -h=<host> backup download <local.backup> [--name=<name>] [--cleanup]
-  sshx ros -h=<host> export download <local.rsc> [--compact] [--cleanup]
-  sshx ros -h=<host> import <local.rsc> [--cleanup]
-  sshx ros -h=<host> script put <name> --source=@<local.rsc>
-  sshx ros commands [--json]                      # List supported RouterOS commands
-  sshx ros help [command] [--json]                # Show command help and arguments
-  sshx ros schema [command] [--json]              # Emit JSON schema for command
-  sshx ros doctor [-h=<host>] [--include-remote]  # Health & environment check
-  sshx ros explain-error <code>                   # Explain error code and remediation
-
-  ROS Options:
-    --dry-run               Emit execution plan JSON without modifying router
-    --allow-write           Permit raw commands or mutations to alter state
-    --force, -f             Bypass safety guardrails for destructive commands
-    --raw                   Execute without CLI response parsing
-    --ros-version=VER       RouterOS major version hint (v6, v7, auto)
-    --source=@PATH          Local .rsc script file for script put
-    --cleanup               Delete temporary remote files after workflow
-    --compact               Use compact export for export download
-    --name=NAME             Custom backup file name
-
-Guarded File Apply:
-  sshx apply -h=<host> --path=/abs/remote.conf --from=./local.conf [options]
-  sshx apply --target=<name> --path=/abs/remote.conf --from=./local.conf --json
-
-  Replaces one remote regular file. sshx reads the current file, optionally
-  checks --expect-sha256, writes an owner-only backup, then atomically replaces
-  the target while preserving mode and owner. Reload/restart is not part of
-  this command — run a separate sshx run after apply succeeds.
-
-  --path=PATH             Absolute remote file path (required)
-  --from=PATH             Local source file (required)
-  --expect-sha256=HEX     Fail closed unless the current remote hash matches
-  --no-backup             Skip the pre-change copy (requires --force)
-  --backup-dir=PATH       Remote backup directory (default: ~/.sshx/file-backups)
-  --sudo                  Stage the payload over SFTP, then install with sudo
-  --force, -f             Skip the hash precondition; required with --no-backup
-  --bypass-reason=TEXT    Required with --force to overwrite /etc/passwd,
-                          /etc/shadow, or /etc/sudoers
-
-  JSON fields to branch on: success, change_state, executed, verified,
-  verification, completion, error_kind (legacy changed/created remain)
-  (precondition/blocked/remote_io/config/...), before_sha256, after_sha256,
-  backup.path, rollback_available. Identical content is success with
-  changed=false and does not write a backup.
-  Post-write verification_failed can mean the target already changed; inspect
-  hashes/backup before retry. SFTP hash rechecks are not arbitrary-writer CAS.
-
-  sshx apply -h=prod --path=/etc/nginx/nginx.conf --from=./nginx.conf \
-      --expect-sha256=<current> --sudo --json
-  sshx apply -h=prod --path=/etc/nginx/nginx.conf --from=./nginx.conf \
-      --dry-run --json
-
-Text Dissection:
-  sshx text --help
-  sshx text --help --json
-  sshx text -h=<host> --path=/abs/file.log [options]
-  sshx text -h=<host> --journal=UNIT [options]
-
-  Bounded remote text/log anatomy for Agents. Do not wrap grep/journalctl
-  in sshx run for incident triage — text returns structured hits.
-
-  Workflow:
-    1. sshx text --help  (or --help --json)
-    2. --preset=exception --json  (blocks and counts first)
-    3. --around-line=<hit.start_line> --context=5 --json
-    4. --download only for incident archives
-
-  --path=/abs/file          Stream a remote regular file over SFTP (default
-                            scan=end, last 8MiB). Symlinks/dirs refused.
-  --journal=UNIT            sshx-owned journalctl for one systemd unit
-  --preset=exception,error,panic,oom,http5xx
-  --pattern=RE2             Optional linear-time regexp after presets
-  --context=N               Neighbor lines (0..20)
-  --around-line=L           Slice around a previous hit
-  --offset=L --limit=N      Line window inside the scanned bytes
-  --tail=N                  Last N lines of the scanned window
-  --scan=start|end          File origin (default end)
-  --since= --until=         Journal time bounds (no shell metacharacters)
-  --max-hits=N --max-bytes=N --max-scan-bytes=N
-  --sudo                    Read with sudo -S
-  --no-redact               Keep secret-shaped spans (default redacts)
-
-  JSON schema sshx.text.v1: hits[], stats.total_hits vs returned,
-  truncated, truncated_reason, line_origin, redacted.
-  There is no --command; that is sshx run.
-
-  sshx text -h=prod-web --path=/var/log/nginx/error.log --preset=exception --json
-  sshx text -h=prod-web --journal=nginx.service --since=1h --preset=error --json
-
-Interactive Login:
-  sshx login <name> [--sudo]
-  sshx login -h=<host> [-u=<user>] [-i=<key>] [--sudo]
-  sshx login --address=<host> [--sudo]
-  sshx login <name> --dry-run --json
-
-  Human-only escape hatch onto a host already known to sshx. It opens one
-  interactive session and attaches the local TTY. This is not an Agent
-  contract: --json is only valid with --dry-run, multi-host selectors are
-  rejected, and login is not exposed over MCP.
-
-  <name> / -h=HOST          Named host or hostname (exactly one)
-  --target=NAME             Long alias of -h= / <name>
-  --address=HOST            Literal address; skip settings.json resolution
-  --sudo                    Land in a privileged login shell (sudo -i)
-                            using the host sudo keyring secret on stdin
-  --dry-run / --json        Local plan only; --json requires --dry-run
-
-  Requires a local TTY. POSIX only; Windows returns an explicit unsupported
-  error. There is no command timeout and no session transcript. Audit records
-  target, auth, sudo, duration, and exit code.
-
-  sshx login prod-web
-  sshx login prod-web --sudo
-  sshx login -h=prod-web --sudo
-  sshx login prod-web --dry-run --json
-
-Plugin Management:
-  sshx plugin create <id> [--runner=sh] [--platform=linux|darwin]
-                          [--privilege=never|optional|required]
-                          [--template=generic|docker|nginx] [--replace] [--json]
-  sshx plugin list [--json]
-  sshx plugin show <id> [--json]
-  sshx plugin validate <id> [--json]
-  sshx plugin test <id> [--fixture=<name>] [--json]
-  sshx plugin trust <id> [--json]
-  sshx plugin remove <id> [--json]
-
-  Local plugins belong to sshx, not to an Agent skill. They are stored under
-  ~/.sshx/plugins/<id> and remain untrusted until their current digest is
-  explicitly trusted. Editing a trusted manifest, schema, or collector changes
-  the digest and blocks remote execution until it is trusted again.
-
-Agent Skill Installation:
-  sshx skill install [--dir=<path>] [--force] [--json]
-
-  The canonical sshx Agent skill is embedded in the binary, so installation
-  does not need a network download or a release archive next to the executable.
-  The default target is ~/.agents/skills/sshx/SKILL.md. Pass --dir to select
-  another sshx skill directory.
-
-  A matching installed skill is left unchanged (or repaired to mode 0644).
-  A prior sshx-managed version is updated using its digest sidecar. Differing
-  unmanaged content is preserved unless --force is explicit. Symlinked targets
-  are rejected. JSON status is installed, current, repaired, or updated;
-  failures use conflict, unsafe_target, or install_error.
-
-Environment Variables (.env):
-  SSH_PASSWORD          SSH password (not recommended, use SSH keys or keyring)
-  SSH_KEY_PATH          SSH private key path
-  SSH_SUDO_KEY          Sudo password keyring key name (default: master)
-  SSH_NO_SAFETY_CHECK   Disable safety checks (true/false)
-  SSH_FORCE             Force execution mode (true/false)
-  SSH_TIMEOUT           Command execution timeout (e.g. 30s, 2m, or 30 = seconds)
-  SSHX_AUDIT_OUTPUT     Audit output directory (default: ~/.sshx/audit)
-  SSHX_NO_AUDIT         Disable audit writing (true/false)
-  SSHX_HOME             Override the local sshx runtime root (default: ~/.sshx)
-  SSHX_SECRET_BACKEND   Secret store: keyring (default) or local-vault
-  SSHX_VAULT_PASSPHRASE Unlock passphrase for local-vault (unattended)
-  SSHX_VAULT_KEY_FILE   0600 file containing the vault passphrase (wins over env)
-
-SSH Examples:
-  # Execute simple command (default user: master)
-  sshx -h=192.168.1.100 "uptime"
-
-  # Execute sudo command (auto password from keyring: master)
-  sshx -h=192.168.1.100 "sudo systemctl status docker"
-
-  # Use custom sudo password key for specific server
-  sshx -h=192.168.1.100 -pk=server-A "sudo systemctl restart nginx"
-  sshx -h=192.168.1.101 -pk=server-B "sudo systemctl restart nginx"
-
-  # Custom SSH port
-  sshx -h=192.168.1.100 -p=2222 "ps aux | grep nginx"
-
-  # Bind the local source address (IP or interface name)
-  sshx -h=prod-web --bind=en0 "uptime"
-
-  # Structured JSON output for scripts/agents (one object on stdout)
-  sshx -h=192.168.1.100 --json "systemctl is-active nginx"
-
-  # Preview the execution plan without connecting or reading secrets
-  sshx -h=prod-web --dry-run --json "sudo systemctl restart nginx"
-
-  # Save audit events for this project
-  sshx -h=prod-web --audit-output=./.sshx-audit "systemctl reload nginx"
-
-  # Bound the command wait (does not guarantee remote termination)
-  sshx -h=192.168.1.100 --timeout=30s "apt-get update"
-
-  # Dangerous command will be blocked
-  sshx -h=192.168.1.100 "sudo rm -rf /tmp/*"  # Safe
-  sshx -h=192.168.1.100 "sudo rm -rf /"       # ⚠️ BLOCKED!
-
-  # Force execute (bypass safety check - use with caution!)
-  sshx -h=192.168.1.100 --force "sudo reboot"
-  sshx -h=192.168.1.100 -f "sudo systemctl reboot"
-
-Inspection Examples:
-  # Inspect stable system/network state in one invocation
-  sshx inspect -h=prod-web system.baseline --json
-
-  # Create a locally editable Docker capability, validate it, then trust it
-  sshx plugin create docker.environment --template=docker --privilege=optional --json
-  sshx plugin validate docker.environment --json
-  sshx plugin test docker.environment --fixture=complete --json
-  sshx plugin trust docker.environment --json
-
-  # Inspect once and persist only the redacted observation on the target
-  sshx inspect -h=prod-web docker.environment --cache=remote-prefer --json
-
-Agent Skill Example:
-  # Install after Homebrew/go install, or refresh after upgrading sshx
-  sshx skill install
-
-  # Replace a locally modified copy after reviewing the difference
-  sshx skill install --force --json
-
-SFTP Examples:
-  # Upload file
-  sshx -h=192.168.1.100 --upload=local.txt --to=/tmp/remote.txt
-
-  # Download file
-  sshx -h=192.168.1.100 --download=/var/log/app.log --to=./app.log
-
-  # List directory
-  sshx -h=192.168.1.100 --list=/var/log
-
-  # Create directory
-  sshx -h=192.168.1.100 --mkdir=/tmp/newdir
-
-  # Remove file
-  sshx -h=192.168.1.100 --rm=/tmp/oldfile.txt
-
-  # Batch upload
-  for file in *.txt; do
-    sshx -h=192.168.1.100 --upload=$file --to=/backup/$file
-  done
-
-Server-to-Server Transfer Examples:
-  # Transfer a file directly between two servers (by IP)
-  sshx --transfer=192.168.1.100:/var/log/app.log --to=192.168.1.101:/backup/app.log
-
-  # Transfer between configured hosts (from settings.json)
-  sshx --transfer=prod-web:/etc/nginx/nginx.conf --to=staging-web:/etc/nginx/nginx.conf
-
-  # Transfer a whole directory recursively
-  sshx --transfer=prod-db:/var/backups --to=backup-server:/mnt/archive/db
-
-  # If the destination is an existing directory, the source is placed inside it
-  sshx --transfer=prod-web:/var/log/app.log --to=log-server:/var/logs/
-
-  # Preview the transfer plan without connecting
-  sshx --transfer=prod-web:/data --to=prod-db:/data --dry-run
-
-Password Management Examples:
-  # Set default sudo password (interactive prompt)
-  sshx --password-set=master
-
-  # Set sudo password (inline, not recommended for security)
-  sshx --password-set=master:mypassword
-
-  # Set passwords for different servers with same username
-  sshx --password-set=server-A
-  sshx --password-set=server-B
-  sshx --password-set=server-C
-
-  # Use different password keys for different servers
-  sshx -h=192.168.1.100 -pk=server-A "sudo systemctl status nginx"
-  sshx -h=192.168.1.101 -pk=server-B "sudo systemctl status nginx"
-  sshx -h=192.168.1.102 -pk=server-C "sudo systemctl status nginx"
-
-  # Set password for specific user
-  sshx --password-set=root
-  sshx --password-set=admin
-
-  # Get password from OS keyring (refused when using local-vault)
-  sshx --password-get=master
-
-  # Headless server: encrypted local vault (write-only; Agent never sees the value)
-  SSHX_SECRET_BACKEND=local-vault SSHX_VAULT_PASSPHRASE='…' \
-    sshx --password-set=prod-web
-  SSHX_SECRET_BACKEND=local-vault SSHX_VAULT_PASSPHRASE='…' \
-    sshx --password-check=prod-web
-
-
-  # Check if password exists
-  sshx --password-check=server-A
-
-  # List common password keys
-  sshx --password-list
-
-  # Delete password from keyring
-  sshx --password-delete=server-A
-
-Host Management Examples:
-  # Add host interactively
-  sshx --host-add
-
-  # Add host with command line options
-  sshx --host-add --host-name=prod-web -h=192.168.1.100 -u=root -pk=prod-web --host-desc="Production Web Server"
-
-  # Add host with its own SSH private key
-  sshx --host-add --host-name=prod-db -h=192.168.1.200 -u=admin -i=~/.ssh/prod-db.pem
+// helpSchemaVersion is the schema of the generic per-verb help document.
+const helpSchemaVersion = "sshx.help.v1"
+
+// usageSection is one titled block of the sshx help surface. `sshx --help`
+// prints every block in order; `sshx <verb> --help` prints that verb's blocks
+// plus the shared option blocks. The text is defined once, in
+// usage_sections.go, so the per-verb help cannot drift from the global help.
+type usageSection struct {
+	title   string
+	verb    string // empty for blocks that no single verb owns
+	summary string // one line, emitted by sshx.help.v1
+	text    string
+}
 
-  # Persist a source bind for a named host
-  sshx --host-add --host-name=edge --bind=en0 -h=100.117.253.247 -p=18922
+// helpVerbs are the subcommands that answer `sshx <verb> --help`.
+var helpVerbs = []string{"run", "apply", "sql", "text", "inspect", "plugin", "skill", "audit", "login", "mcp", "ros"}
+
+// verbSharedSections are the blocks every remote verb accepts, repeated in each
+// per-verb help so one call answers "what may I pass here?".
+var verbSharedSections = []string{
+	"SSH Options",
+	"Agent / Scripting Mode",
+	"Sudo Auto-fill",
+	"Dry-run Plan Preview",
+	"Audit Trail",
+	"Safety Options",
+}
 
-  # Update host IP address
-  sshx --host-update --host-name=prod-web -h=192.168.1.101
+// usageSections returns every help block in global-help order.
+func usageSections() []usageSection {
+	return []usageSection{
+		{title: "Usage", verb: "", summary: "", text: usageIntro},
+		{title: "SSH Options", verb: "", summary: "", text: usageSSHOptions},
+		{title: "Run Contract (preferred for Agents)", verb: "run", summary: "Execute one command or script across selected hosts with the versioned sshx.run contract.", text: usageRun},
+		{title: "Agent / Scripting Mode", verb: "", summary: "", text: usageAgentMode},
+		{title: "Sudo Auto-fill", verb: "", summary: "", text: usageSudoAutoFill},
+		{title: "Dry-run Plan Preview", verb: "", summary: "", text: usageDryRun},
+		{title: "Audit Trail", verb: "", summary: "", text: usageAuditTrail},
+		{title: "Audit Query and Export", verb: "audit", summary: "Query or export the local structured audit trail without connecting or writing.", text: usageAuditQuery},
+		{title: "Safety Options", verb: "", summary: "", text: usageSafety},
+		{title: "SFTP Options", verb: "", summary: "", text: usageSFTP},
+		{title: "Server-to-Server Transfer", verb: "", summary: "", text: usageTransfer},
+		{title: "Password Management (Cross-Platform)", verb: "", summary: "", text: usagePassword},
+		{title: "Host Management", verb: "", summary: "", text: usageHost},
+		{title: "Inspection Capabilities", verb: "inspect", summary: "Collect or reuse one structured host observation from a built-in or local capability.", text: usageInspect},
+		{title: "Guarded SQL Execution", verb: "sql", summary: "Run one guarded SQL statement through the database client already present on the remote host.", text: usageSQL},
+		{title: "MikroTik RouterOS (ROS) over SSH", verb: "ros", summary: "Manage MikroTik RouterOS devices over SSH and SFTP with structured commands.", text: usageROS},
+		{title: "Guarded File Apply", verb: "apply", summary: "Replace one remote regular file with a precondition, backup, and post-write verification pipeline.", text: usageApply},
+		{title: "Text Dissection", verb: "", summary: "", text: usageText},
+		{title: "Interactive Login", verb: "login", summary: "Open one human interactive TTY session on a host already known to sshx.", text: usageLogin},
+		{title: "Plugin Management", verb: "plugin", summary: "Install, create, list, validate, trust, and remove local inspection plugins.", text: usagePlugin},
+		{title: "Agent Skill Installation", verb: "skill", summary: "Install or update the sshx Agent skill embedded in the binary.", text: usageSkill},
+		{title: "MCP Server (stdio)", verb: "mcp", summary: "Serve the sshx execution contract over stdio to an MCP client.", text: usageMCP},
+		{title: "Environment Variables (.env)", verb: "", summary: "", text: usageEnv},
+		{title: "SSH Examples", verb: "", summary: "", text: usageSSHExamples},
+		{title: "Inspection Examples", verb: "inspect", summary: "", text: usageInspectExamples},
+		{title: "Agent Skill Example", verb: "skill", summary: "", text: usageSkillExample},
+		{title: "SFTP Examples", verb: "", summary: "", text: usageSFTPExamples},
+		{title: "Server-to-Server Transfer Examples", verb: "", summary: "", text: usageTransferExamples},
+		{title: "Password Management Examples", verb: "", summary: "", text: usagePasswordExamples},
+		{title: "Host Management Examples", verb: "", summary: "", text: usageHostExamples},
+		{title: "Note", verb: "", summary: "", text: usageNotes},
+	}
+}
 
-  # Update host SSH key
-  sshx --host-update --host-name=prod-web -i=~/.ssh/new-key.pem
+// PrintUsage prints the global sshx help surface.
+func PrintUsage() {
+	fmt.Printf("\nSSHX — Agent-native remote host execution over SSH\nVersion: %s\n", Version)
+	for _, section := range usageSections() {
+		fmt.Print(section.text)
+	}
+	fmt.Println()
+}
 
-  # Update host password key
-  sshx --host-update --host-name=prod-web -pk=new-password-key
+// PrintVerbUsage answers `sshx <verb> --help`: the verb's own blocks, the
+// shared option blocks, and a pointer to the global surface. With --json it
+// emits the sshx.help.v1 document instead of prose. `sshx text` keeps its
+// dedicated Agent-facing document and its own sshx.text.help.v1 schema.
+func PrintVerbUsage(config *sshclient.Config) error {
+	verb := config.HelpVerb
+	if verb == "text" {
+		return HandleTextHelp(config)
+	}
+	sections := verbUsageSections(verb)
+	if len(sections) == 0 {
+		return fmt.Errorf("%w: unknown help verb %q (known verbs: %s)", execution.ErrConfig, verb, strings.Join(helpVerbs, ", "))
+	}
+	if config.JSONOutput {
+		document := verbHelpDocument{
+			SchemaVersion: helpSchemaVersion, Verb: verb,
+			Summary: verbSummary(sections), Usage: helpDocumentSections(sections),
+		}
+		if err := encodeJSON(document); err != nil {
+			return fmt.Errorf("%w: deliver help: %w", execution.ErrLocalIO, err)
+		}
+		return nil
+	}
+	fmt.Print(renderVerbUsage(verb, sections))
+	return nil
+}
 
-  # Update multiple fields
-  sshx --host-update --host-name=prod-web -h=192.168.1.101 -u=admin -pk=new-key
+// verbHelpDocument is the machine-readable form of a per-verb help surface.
+type verbHelpDocument struct {
+	SchemaVersion string            `json:"schema_version"`
+	Verb          string            `json:"verb"`
+	Summary       string            `json:"summary"`
+	Usage         []verbHelpSection `json:"usage"`
+}
 
-  # List all configured hosts
-  sshx --host-list
+type verbHelpSection struct {
+	Title string `json:"title"`
+	Text  string `json:"text"`
+}
 
-  # Test connection to a configured host
-  sshx --host-test=prod-web
+// verbUsageSections returns the blocks printed by `sshx <verb> --help`: the
+// verb's own blocks first, then the shared option blocks. An unknown verb
+// returns nil so the caller can report it.
+func verbUsageSections(verb string) []usageSection {
+	if !containsString(helpVerbs, verb) {
+		return nil
+	}
+	var sections []usageSection
+	for _, section := range usageSections() {
+		if section.verb == verb {
+			sections = append(sections, section)
+		}
+	}
+	for _, section := range usageSections() {
+		if section.verb == "" && containsString(verbSharedSections, section.title) {
+			sections = append(sections, section)
+		}
+	}
+	return sections
+}
 
-  # Test all configured hosts and get a report with auth methods
-  sshx --host-test-all
+func verbSummary(sections []usageSection) string {
+	for _, section := range sections {
+		if section.summary != "" {
+			return section.summary
+		}
+	}
+	return ""
+}
 
-  # Remove a host from configuration
-  sshx --host-remove=prod-web
+func helpDocumentSections(sections []usageSection) []verbHelpSection {
+	document := make([]verbHelpSection, 0, len(sections))
+	for _, section := range sections {
+		document = append(document, verbHelpSection{Title: section.title, Text: strings.TrimRight(section.text, "\n")})
+	}
+	return document
+}
 
-  # Use configured host (looks up from settings if not an IP)
-  sshx -h=prod-web "uptime"
+func renderVerbUsage(verb string, sections []usageSection) string {
+	var out strings.Builder
+	fmt.Fprintf(&out, "sshx %s — %s\n\n", verb, verbSummary(sections))
+	for _, section := range sections {
+		if section.verb == verb {
+			out.WriteString(section.text)
+		}
+	}
+	out.WriteString("Shared options and semantics:\n")
+	for _, section := range sections {
+		if section.verb == "" {
+			out.WriteString(section.text)
+		}
+	}
+	fmt.Fprintf(&out, "See also:\n  %-28s full help surface\n  %-28s this document as %s\n",
+		"sshx --help", "sshx "+verb+" --help --json", helpSchemaVersion)
+	return out.String()
+}
 
-Note:
-  - SSH key authentication is tried first; password auth is used only when SSH_PASSWORD is provided
-  - Sudo password is auto-filled only when the remote command starts with sudo
-  - Dry-run never connects, executes, reads keyring secrets, or writes state
-  - Audit events are JSONL files under ~/.sshx/audit by default
-  - SFTP operations use the same SSH connection
-  - Password manager works across macOS/Linux/Windows
-  - Default user: master, Default sudo key: master
-  - Host configurations are stored in ~/.sshx/settings.json`)
+func containsString(values []string, want string) bool {
+	for _, value := range values {
+		if value == want {
+			return true
+		}
+	}
+	return false
 }
 
 // PrintTextUsage is the dedicated Agent-facing help for sshx text.
@@ -793,14 +235,6 @@ There is no --command. JSON schema is sshx.text.v1. Branch on success,
 hits[].kind, stats.total_hits vs returned, truncated, truncated_reason,
 and line_origin (file vs scanned_window).
 
-Monitoring:
-  A scan that runs longer than a few seconds narrates progress on stderr
-  (bytes, percentage, lines, elapsed, matches). Long or budget-limited scans
-  close with advice naming --offset/--tail/--max-scan-bytes. stderr carries
-  these lines only: stdout stays exactly one JSON document. stats gains
-  expected_scan_bytes (the window budget) alongside file_size/window_start_byte,
-  so a caller can size a scan before trusting total_hits_exact.
-
 Examples:
   sshx text -h=prod-web --path=/var/log/nginx/error.log --preset=exception --json
   sshx text -h=prod-web --journal=nginx.service --since=1h --preset=error --json
diff --git a/internal/app/usage_sections.go b/internal/app/usage_sections.go
new file mode 100644
index 0000000..aac5095
--- /dev/null
+++ b/internal/app/usage_sections.go
@@ -0,0 +1,884 @@
+package app
+
+// Help text for the sshx command surface.
+//
+// Each block is defined exactly once: `sshx --help` prints every block in
+// order, and `sshx <verb> --help` prints that verb's blocks plus the shared
+// option blocks. Add or change text here, never in a second place.
+
+const usageIntro = `
+Usage:
+  sshx -h=<host> [options] <command>              # SSH mode (compatibility)
+  sshx run [selectors] [options] -- <command>     # Canonical execution contract
+  sshx run --script-file=PATH ...                 # Byte-preserving script payload
+  sshx -h=<host> [options] --upload=<file>        # SFTP upload
+  sshx -h=<host> [options] --download=<file>      # SFTP download
+  sshx --transfer=<host>:<path> --to=<host>:<path> # Server-to-server transfer
+  sshx --password-set=<key>[:<password>]          # Store a password (keyring or local vault)
+  sshx --password-get=<key>                       # Get password from OS keyring (denied for local vault)
+  sshx --password-delete=<key>                    # Delete a stored password
+  sshx --password-list                            # List stored or common password keys
+  sshx --host-add                                 # Add host configuration
+  sshx --host-update                              # Update host configuration
+  sshx --host-list                                # List configured hosts
+  sshx --host-test=<name>                         # Test host connection
+  sshx --host-test-all                            # Test all host connections
+  sshx --host-remove=<name>                       # Remove host configuration
+  sshx skill install [options]                    # Install/update the bundled Agent skill
+  sshx plugin create <id> [options]               # Scaffold a local inspection plugin
+  sshx plugin list [--json]                       # List built-in and local capabilities
+  sshx inspect -h=<host> <capability> [options]   # Run one structured host inspection
+  sshx sql -h=<host> --db=<name> [options] "SQL"  # Guarded SQL via remote psql/sqlite3
+  sshx ros -h=<host> [options] <cmd...>           # MikroTik RouterOS over SSH
+  sshx apply -h=<host> --path=<remote> --from=<local>  # Guarded remote file apply
+  sshx text -h=<host> --path=<remote> [options]   # Bounded remote text/log dissection
+  sshx login <name> [--sudo]                      # Human interactive login (TTY required)
+  sshx mcp                                        # Serve the execution contract over stdio (MCP)
+  sshx audit query [filters] [--json]             # Read-only audit trail query
+  sshx audit export --to=<file> [filters]         # Export matching audit events as JSONL
+  sshx <verb> --help                              # Per-verb usage (add --json for sshx.help.v1)
+`
+
+const usageSSHOptions = `
+SSH Options:
+  -h, --host=HOST          Remote host address (required in compatibility mode)
+  -p, --port=PORT          SSH port (default: 22)
+  -u, --user=USER          SSH username (default: master)
+  -i, --key=PATH           SSH private key path (default: ~/.ssh/id_rsa)
+  -pk, --password-key=KEY  Sudo password keyring key name (default: master)
+                           Used only when the remote command starts with sudo
+  --ssh-password-key=KEY   SSH login password keyring key (never used for sudo)
+  --bind=ADDR              Local source IP or interface (e.g. 192.0.2.10 or en0)
+  --via=NAME               Named sshx jump host (session-bound; no local tunnel)
+  --dry-run                Print the local execution plan without side effects
+  --expect-plan=HASH       Require the reviewed sha256:<64 lowercase hex> plan
+  --audit-output=DIR       Write audit JSONL files to DIR (default: ~/.sshx/audit)
+  --no-audit               Disable local audit event writing for this invocation
+  --timeout=DURATION       Command execution timeout (e.g. 30s, 2m, or 30 = seconds)
+  --host-timeout=DURATION  Optional total admitted-target budget (setup + verify)
+  --global-timeout=DURATION Optional operation budget, including queued targets
+  --json                   Emit a single structured JSON result on stdout
+  --quiet, --no-notices    Suppress human notices on stderr (deprecation warnings,
+                           narration). stdout, the exit code, and the JSON
+                           document are unchanged
+  --pty                    Request a PTY (merges stderr into stdout; off by default)
+  --version                Show version information (alias: -v)
+  --help                   Show this help message
+`
+
+const usageRun = `
+Run Contract (preferred for Agents):
+  sshx run --target=prod-web --json -- "systemctl is-active nginx"
+  sshx run --group=prod-web --tag=env=prod --concurrency=4 --jsonl -- "uptime"
+  sshx run --target=prod-web --script-file=./check.sh --json
+  cat ./check.sh | sshx run --target=prod-web --script-stdin --json
+
+  Selectors (configured hosts only; multi-host never treats names as DNS):
+    --target=NAME            strict alias (repeatable via --targets=a,b)
+    --group=NAME             union with other names/groups (repeatable)
+    --tag=key=value          AND filter (repeatable)
+    --all-hosts              all configured hosts before tag filters
+    --address=HOST           explicit single literal address (not for fan-out)
+
+  Script payloads:
+    --script-file=PATH       byte-preserving script from a local file
+    --script-stdin           byte-preserving script from stdin
+    --shell=NAME             interpreter override: sh, bash, zsh, dash, ksh, ash
+                             (default: the script's #! line, else sh)
+
+  Limits / policy:
+    --concurrency=N          default 4, hard max 32
+    --failure-mode=continue|fail_fast   default continue
+    --fail-fast              Alias of --failure-mode=fail_fast
+    --max-failures=N          Stop new admission at this failure threshold
+    --intent=read|change|unknown
+    --force / --no-safety-check require --bypass-reason=TEXT
+    --jsonl                  stream run_started/target_*/run_finished events
+
+  Failure thresholds stop admission only; already admitted targets finish and
+  can add failures. Conflicting failure policies are configuration errors.
+  New time budgets are opt-in; --timeout keeps its existing meaning/defaults.
+  Cancellation closes local transport work, not guaranteed remote termination
+  or rollback. Treat unacknowledged changes as uncertain before retrying.
+
+  Multi-target exit codes:
+    0    all selected targets succeeded
+    1    run accepted but at least one target failed/skipped/uncertain
+    255  request-level failure (bad selectors, zero matches, invalid input)
+`
+
+const usageAgentMode = `
+Agent / Scripting Mode:
+  By default command output streams live with stdout and stderr kept on
+  separate channels (no PTY), and the remote command's exit status is
+  propagated as sshx's own exit code.
+
+  Compatibility --json emits one JSON object on stdout:
+    {host, port, user, command, exit_code, success, stdout, stderr,
+     stdout_truncated, stderr_truncated, duration_ms, auth_method,
+     error_kind, error}
+
+  Under --json, stdout carries the machine document and only the machine
+  document; sshx never writes human text there, including on failure. Human
+  notices (deprecation warnings, narration) go to stderr. A caller that merges
+  the streams (2>&1) should pass --quiet, which suppresses the notices so the
+  merged stream is still parseable; failures keep their JSON error_kind/error.
+  sshx run --json adds versioned fields (schema_version, run_id, status,
+  phase, completion, structured error).
+
+  Shared Execution Evidence:
+    plan_hash, risk, effects, execution_id, parent_execution_id,
+    execution_fingerprint, change_state, executed (nullable), verified,
+    verification, preconditions, postconditions.
+  change_state is changed|unchanged|unknown; null executed is not false.
+  Success, execution acknowledgement, change, and verification are distinct.
+  Unknown commands/scripts default to mutation risk with unknown effects;
+  --intent=read is not proof of read-only behavior. Risk is
+  read|mutation|privileged|destructive, not an authorization grant.
+  Raw stdout/stderr and secret values are not execution-fingerprinted.
+
+  Exit codes (single-host compatibility mode):
+    0          command succeeded
+    1..254     remote command's exit status (propagated verbatim)
+    255        sshx-level failure (connect/auth/host-key/timeout/blocked/...)
+    In --json mode an sshx-level failure has exit_code -1 and a non-empty
+    error_kind (timeout, auth, host_key, connect, blocked, exit_missing,
+    config, error), so it is always distinguishable from a remote exit 255.
+
+  A policy block also writes its reason to stderr
+  (exit_code=-1, error_kind=blocked, phase=admission, executed=false), so a
+  caller that only prints the streams sees why nothing ran. Use the guarded
+  alternative instead: sshx sql -h=<host> --db=<name> [--docker=<container>]
+  "<SQL>". stdout still carries exactly one JSON document.
+
+  Trust note: high-risk bypasses (force, no-safety-check, accept-unknown-host,
+  insecure-hostkey) require explicit CLI flags. Inherited env values and
+  working-directory .env files are ignored for those decisions.
+`
+
+const usageSudoAutoFill = `
+Sudo Auto-fill:
+  sshx auto-fills a sudo password only when the remote command starts with
+  sudo, for example:
+    sshx -h=host "sudo systemctl status nginx"
+
+  Non-leading sudo is not auto-filled and does not trigger keyring lookup:
+    sshx -h=host "sh -c 'sudo whoami'"
+    sshx -h=host "echo sudo"
+
+  sshx warns on stderr when it sees a non-leading sudo, because the remote then
+  stops with "sudo: a password is required". Wrap the privileged part instead:
+    sshx -h=host "sudo sh -c 'cd /data/app && docker compose up -d'"
+
+  This keeps keyring lookup, stdin password injection, and future audit fields
+  on one clear rule. Put sudo at the beginning of the remote command when you
+  want sshx to auto-fill it.
+`
+
+const usageDryRun = `
+Dry-run Plan Preview:
+  Add --dry-run to see how sshx would interpret an invocation before any
+  connection, command execution, keyring secret lookup, known_hosts mutation, or
+  settings write. Use --json with --dry-run for an agent-readable plan.
+
+  Examples:
+    sshx -h=prod-web --dry-run "sudo systemctl restart nginx"
+    sshx -h=prod-web --dry-run --json --upload=local.txt --to=/tmp/local.txt
+
+  Dry-run is a local plan preview only. It does not prove the remote command
+  would succeed.
+
+  Bound Plan Admission:
+  Remote command/run/apply/sql/SFTP/transfer/inspect previews add a nested
+  sshx.plan.v1 plan plus plan_hash and risk. Run keeps sshx.request.v1 outside.
+  Repeat reviewed inputs with --expect-plan=sha256:<64 lowercase hex>.
+  Local mismatch fails before secret lookup or network work; --force cannot
+  bypass it. Errors: config (format), plan_mismatch, plan_unresolved.
+  Check plan.bindable and plan.unresolved: DNS-only addresses, unavailable
+  public-key sidecars, missing/relaxed trust, and remotely discovered SQL
+  identity cannot bind offline. The entire sorted known_hosts record snapshot
+  is hashed, so unrelated trust changes can conservatively invalidate a plan.
+  Dry-run never connects, reads secrets, or writes state. A plan hash is not
+  a lock on remote files, rows, permissions, or recursive directory membership.
+`
+
+const usageAuditTrail = `
+Audit Trail:
+  sshx writes one structured JSONL audit event per non-dry-run invocation to
+  ~/.sshx/audit/sshx-YYYY-MM-DD.jsonl by default. Use --audit-output=<dir> to
+  save audit events next to a project or incident record.
+
+  Audit events record metadata and outcomes such as mode/action, host
+  resolution, sudo/keyring decisions, safety status, auth method, exit code, and
+  error kind. They do not record plaintext passwords, private key contents, or
+  stdout/stderr. Command text is best-effort redacted for password/token-style
+  arguments.
+
+  Read-only consumption:
+    sshx audit query --since=2026-09-01 --target=prod-web --json
+    sshx audit query --run-id=<id> --error-kind=blocked --bypass-only
+    sshx audit query --execution-id=<id> --json
+    sshx audit export --to=./incident.jsonl --since=2026-09-01
+  Empty query results exit 0. JSON mode emits {schema_version, success, count, events}.
+  Corrupt/partial records have visible diagnostics; valid records are retained.
+  Audit writes are best-effort, with persistence status separate from execution.
+  Do not repeat a successful mutation just because audit writing failed.
+`
+
+const usageSafety = `
+Safety Options:
+  -f, --force           Force execution, bypass safety checks (use with caution!)
+  --no-safety-check     Disable safety checks completely (not recommended)
+  --bypass-reason=TEXT  Required with --force / --no-safety-check in command
+                        mode and sshx run (recorded in dry-run, result, audit)
+
+  Safety checks protect against:
+    - Destructive operations (rm -rf /, mkfs, dd)
+    - System shutdown/reboot commands
+    - Critical file modifications (/etc/passwd, /etc/shadow)
+    - Dangerous pipe operations (curl | sh)
+    - Fork bombs and other malicious patterns
+    - Direct database client execution (psql/pgcli/sqlite3/mysql/mariadb,
+      incl. docker exec, sudo -u, sh -c, kubectl exec wrappers) — use 'sshx sql' instead
+`
+
+const usageSFTP = `
+SFTP Options:
+  --upload=<local>      Upload file (use with --to=<remote>)
+  --download=<remote>   Download file (use with --to=<local>)
+  --to=<path>           Target path for upload/download
+  --list=<path>         List directory contents (alias: --ls)
+  --mkdir=<path>        Create remote directory
+  --rm=<path>           Remove remote file or directory
+
+  Add --json for structured operation/effect evidence. Size-only verification
+  does not prove content equality. Partial recursive progress is not rolled
+  back as one atomic directory operation.
+`
+
+const usageTransfer = `
+Server-to-Server Transfer:
+  --transfer=<src-host>:<src-path> --to=<dst-host>:<dst-path>
+
+  Streams files directly from one server to another through the local
+  machine (nothing is written to local disk). Supports single files and
+  recursive directory transfers, and preserves file permission bits.
+  Both hosts can be configured host names (from ~/.sshx/settings.json)
+  or IP addresses, each using its own SSH key/user/port from settings.
+`
+
+const usagePassword = `
+Password Management (Cross-Platform):
+  --password-set=<key>[:<password>]   Store a password in the secret backend
+                                      If password omitted, will prompt
+  --password-get=<key>                OS keyring: emit the value only when piped.
+                                      Local vault: always refused (write-only).
+  --password-check=<key>              Check if password exists (alias: --password-exists).
+                                      Missing keys exit non-zero. --json emits
+                                      sshx.secrets.v1 with success/exists.
+  --password-delete=<key>             Delete password (alias: --password-del)
+  --password-list                     List stored keys (vault) or common keys (keyring).
+                                      --json emits keys[] (list_complete=false on keyring probes)
+
+  Default backend: OS keyring (macOS Keychain / Linux Secret Service /
+  Windows Credential Manager). Headless servers can opt into an encrypted
+  local vault with SSHX_SECRET_BACKEND=local-vault. There is no silent
+  fallback. The vault never displays secret values; sshx injects them over
+  stdin during execution. Unlock with SSHX_VAULT_PASSPHRASE or
+  SSHX_VAULT_KEY_FILE (0600). The vault file is $SSHX_HOME/vault.
+`
+
+const usageHost = `
+Host Management:
+  --host-add                          Add new host (interactive or with options).
+                                      Omitting -pk does not persist sudo_password_key=master.
+                                      --json emits sshx.hosts.v1 for add/update/remove/test.
+  --host-import                       Selectively import hosts from ~/.ssh/config (interactive)
+  --host-import=<name1,name2>         Import only the named ssh_config hosts (non-interactive)
+  --ssh-config=<path>                 ssh_config file to import from (default: ~/.ssh/config)
+  --host-update                       Update existing host configuration
+  --host-list                         List all configured hosts (alias: --host-ls)
+  --host-test=<name>                  Test connection to configured host
+  --host-test-all                     Test connections for all configured hosts
+  --host-remove=<name>                Remove host from configuration (alias: --host-rm)
+
+  Host Add/Update Options:
+    --host-name=<name>                Host name (unique identifier, required for update)
+    --host-desc=<description>         Host description
+    -h=<address>                      Host address (IP or hostname)
+    -p=<port>                         SSH port
+    -u=<user>                         SSH username
+    -i=<key>, --key=<key>            SSH private key path for this host (optional)
+    -pk=<key>                         Password key name
+    --host-type=<type>                System type (linux/windows/macos)
+    --bind=<ip|iface>                 Persist a source address for this host
+    --via=<name>                      Named jump host for this target
+
+  Configuration file: ~/.sshx/settings.json
+`
+
+const usageInspect = `
+Inspection Capabilities:
+  sshx inspect -h=<host> <capability> [options]
+
+  Built in:
+    system.identity, system.resources, system.baseline
+    network.interfaces, network.routes, network.dns
+    network.listeners, network.firewall
+
+  --cache=off|remote-prefer  Reuse/write a remote observation (default: off)
+  --refresh                  Ignore a reusable observation and run the collector
+  --max-age=DURATION         Require observations no older than this duration
+  --allow-stale              Explicitly allow an expired observation
+  --sudo                     Use sudo for an optional-privilege plugin
+
+  Collectors execute once through SSH stdin and are never installed on the
+  target. With remote-prefer caching, only redacted JSON is stored below the
+  remote user's ~/.sshx/observations/v1 directory.
+`
+
+const usageSQL = `
+Guarded SQL Execution:
+  sshx sql -h=<host> --db=<name> [options] "<single SQL statement>"
+  sshx sql -h=<host> --engine=sqlite --db-file=/abs/path.db [options] "SQL"
+  sshx sql -h=<host> --db=<name> [options] -- <SQL words...>
+  sshx sql -h=<host> --db=<name> [options] --statement-file=./query.sql
+  printf '%s' 'select 1' | sshx sql -h=<host> --db=<name> [options]
+
+  The statement may be a positional argument, everything after --, a local file
+  via --statement-file=PATH, or stdin when it is piped rather than a terminal.
+  Reading stdin waits for EOF, so close stdin when another process holds the pipe
+  open, or pass --statement-file=PATH.
+  A statement that opens with a comment ("-- header") cannot be an option
+  token, so it is taken as statement text; only option-shaped typos are
+  rejected, and those name the intended option.
+
+  Statements run through the database client already present on the remote
+  host (psql, sqlite3, or mysql/mariadb). sshx embeds no database driver and opens no tunnel.
+  Exactly one statement per invocation. Unknown or dangerous statement heads
+  (DROP DATABASE/SCHEMA, ALTER SYSTEM, COPY, DO, ATTACH, sqlite3 dot-commands,
+  transaction control, multi-statement input), psql meta-commands,
+  EXPLAIN ANALYZE, data-modifying CTE bodies, SELECT INTO, CALL, dblink,
+  load_extension, writable PRAGMA, and other unanalyzable forms are blocked
+  fail-closed. PostgreSQL reads run in a read-only transaction; SQLite reads
+  open the file URI with mode=ro. Direct psql/pgcli/sqlite3 invocations in
+  run/command mode are blocked — use sshx sql. Every invocation is audited
+  with a literal-redacted statement, its exact SHA-256 digest, classification,
+  backup, and outcome.
+
+  --statement-file=PATH     Read the statement from a local file (mutually
+                            exclusive with a positional statement)
+  --engine=postgres|sqlite|mysql  SQL engine (default: postgres)
+  --db=NAME                 PostgreSQL database name, or SQLite path if --db-file is omitted
+  --db-file=PATH            Absolute SQLite database file path (required for --engine=sqlite)
+  --db-user=USER            Database role (default: remote psql default; sqlite unused)
+  --db-host=HOST            Database host as seen from the remote (default: local socket)
+  --db-port=PORT            Database port
+  --db-password-key=KEY     Keyring key for the DB password; delivered via stdin,
+                            never via argv (implies --db-host=127.0.0.1 when unset)
+  --docker=CONTAINER        Run psql inside this container via docker exec -i
+                            (default connection becomes the container-local socket;
+                            backups still land on the host)
+  --db-cred-from=SOURCE     Resolve DB credentials on the remote host instead of the
+                            local keyring: docker:<container> (container env) or
+                            env-file:<path> (KEY=VALUE file). Recognizes PG*,
+                            POSTGRES_*, DB_* keys and DATABASE_URL. Mutually
+                            exclusive with --db-password-key; --db becomes optional
+                            when the source provides the database name.
+  --cred-cache=off|DURATION Temporary local cache for remotely resolved credentials
+                            (default: 15m). The secret lives only in the secret backend;
+                            ~/.sshx/sql-cred-cache.json records identity + expiry.
+                            Expired entries are deleted from the keyring.
+  --cred-refresh            Drop the cached entry and re-resolve from the source
+  --explain                 Run EXPLAIN only; never executes the statement
+  --row-threshold=N         EXPLAIN row estimate that upgrades a row backup to a
+                            full-table CSV snapshot (default: 1000)
+  --allow-full-table        Required for UPDATE/DELETE without a WHERE clause
+  --no-backup               Skip pre-change backup (requires --force)
+  --backup-dir=PATH         Remote backup directory (default: ~/.sshx/sql-backups)
+  --sudo                    Run sqlite3/psql via sudo -S (SSH user cannot open the file)
+  --force, -f               Confirms DDL; destructive DDL also requires --no-backup
+
+  Safety pipeline for data changes: classify locally (fail-closed), gate by
+  policy, then snapshot and execute. PostgreSQL runs EXPLAIN (FORMAT JSON)
+  and snapshots rows or the table under one transaction plus a SHARE ROW
+  EXCLUSIVE lock. SQLite skips row estimates and snapshots the table (CSV)
+  or the whole file under BEGIN IMMEDIATE. Whole-file .backup uses a second
+  read-only client while the mutation client holds the writer lock; mutation
+  is sent only after snapshot completion. SELECT and other reads skip EXPLAIN
+  and backups.
+  Catalog preflight blocks automatic execution when triggers, rewrite rules,
+  partitions, or cascading referential actions can affect related tables;
+  proceed only after an independent backup with --force --no-backup. Automatic
+  backups are not claimed for destructive DDL, which also requires
+  --force --no-backup. Backup directories/files are owner-only. --dry-run
+  previews the local plan without connecting; runtime catalog checks may block.
+  Row counts are engine-specific evidence, not universal proof of value changes.
+  Commit acknowledgement and verification are separate; uncertain commits need
+  inspection before retry. MySQL atomicity requires a supported, proven strategy:
+  separate-session backup/mutation and implicit-commit DDL are not atomic.
+  Bound SQL cannot depend on remote credential/container identity discovery.
+  SQL evidence.verification=protocol_verified acknowledges the client protocol,
+  not actual changed values; effect_verification remains separate.
+  Mutation state_change stays unknown, including zero affected rows.
+  Missing/malformed evidence reports protocol_error or verification_failed.
+  Guarded MySQL supports simple InnoDB single-table UPDATE/DELETE with a write
+  lock. Its SSHX_MYSQL_HEX_ROWS_V1 backup preserves NULL/binary values and is
+  not CSV, a schema dump, or automatic restore; no backup table/DDL is created.
+
+  sshx sql -h=db1 --db=app "SELECT count(*) FROM users"
+  sshx sql -h=db1 --db=app --db-user=app --db-password-key=app-db \
+      "UPDATE users SET active=false WHERE id=42"
+  sshx sql -h=db1 --db=app --explain "DELETE FROM sessions WHERE expires_at < now()"
+  sshx sql -h=db1 --db=app --force "TRUNCATE staging_events"
+  # Dockerized production DB: credentials live in the container env, psql runs
+  # inside the container, resolved credentials are cached in the keyring for 15m
+  sshx sql -h=prod --docker=pg-prod --db-cred-from=docker:pg-prod \
+      "UPDATE users SET active=false WHERE id=42"
+  sshx sql -h=prod --docker=pg-prod --db-cred-from=env-file:/opt/app/.env \
+      --cred-cache=1h "SELECT count(*) FROM orders"
+  sshx sql -h=app --engine=sqlite --db-file=/var/lib/app/app.db --json \
+      "UPDATE users SET active=0 WHERE id=42"
+  sshx sql -h=app --engine=sqlite --db-file=/var/lib/app/app.db --sudo --json \
+      "UPDATE users SET active=0 WHERE id=42"
+`
+
+const usageROS = `
+MikroTik RouterOS (ROS) over SSH:
+  sshx ros -h=<host> [options] <path...> <action> [key=value ...]
+  sshx ros -h=<host> interface print [--json]
+  sshx ros -h=<host> ip address add address=192.168.88.1/24 interface=ether1
+  sshx ros -h=<host> raw "/system/resource/print"
+  sshx ros -h=<host> file upload <local> <remote>
+  sshx ros -h=<host> file download <remote> <local>
+  sshx ros -h=<host> backup download <local.backup> [--name=<name>] [--cleanup]
+  sshx ros -h=<host> export download <local.rsc> [--compact] [--cleanup]
+  sshx ros -h=<host> import <local.rsc> [--cleanup]
+  sshx ros -h=<host> script put <name> --source=@<local.rsc>
+  sshx ros commands [--json]                      # List supported RouterOS commands
+  sshx ros help [command] [--json]                # Show command help and arguments
+  sshx ros schema [command] [--json]              # Emit JSON schema for command
+  sshx ros doctor [-h=<host>] [--include-remote]  # Health & environment check
+  sshx ros explain-error <code>                   # Explain error code and remediation
+
+  ROS Options:
+    --dry-run               Emit execution plan JSON without modifying router
+    --allow-write           Permit raw commands or mutations to alter state
+    --force, -f             Bypass safety guardrails for destructive commands
+    --raw                   Execute without CLI response parsing
+    --ros-version=VER       RouterOS major version hint (v6, v7, auto)
+    --source=@PATH          Local .rsc script file for script put
+    --cleanup               Delete temporary remote files after workflow
+    --compact               Use compact export for export download
+    --name=NAME             Custom backup file name
+`
+
+const usageApply = `
+Guarded File Apply:
+  sshx apply -h=<host> --path=/abs/remote.conf --from=./local.conf [options]
+  sshx apply --target=<name> --path=/abs/remote.conf --from=./local.conf --json
+
+  Replaces one remote regular file. sshx reads the current file, optionally
+  checks --expect-sha256, writes an owner-only backup, then atomically replaces
+  the target while preserving mode and owner. Reload/restart is not part of
+  this command — run a separate sshx run after apply succeeds.
+
+  --path=PATH             Absolute remote file path (required)
+  --from=PATH             Local source file (required)
+  --expect-sha256=HEX     Fail closed unless the current remote hash matches
+  --no-backup             Skip the pre-change copy (requires --force)
+  --backup-dir=PATH       Remote backup directory (default: ~/.sshx/file-backups)
+  --sudo                  Stage the payload over SFTP, then install with sudo
+  --force, -f             Skip the hash precondition; required with --no-backup
+  --bypass-reason=TEXT    Required with --force to overwrite /etc/passwd,
+                          /etc/shadow, or /etc/sudoers
+
+  JSON fields to branch on: success, change_state, executed, verified,
+  verification, completion, error_kind (legacy changed/created remain)
+  (precondition/blocked/remote_io/config/...), before_sha256, after_sha256,
+  backup.path, rollback_available. Identical content is success with
+  changed=false and does not write a backup.
+  Post-write verification_failed can mean the target already changed; inspect
+  hashes/backup before retry. SFTP hash rechecks are not arbitrary-writer CAS.
+
+  sshx apply -h=prod --path=/etc/nginx/nginx.conf --from=./nginx.conf \
+      --expect-sha256=<current> --sudo --json
+  sshx apply -h=prod --path=/etc/nginx/nginx.conf --from=./nginx.conf \
+      --dry-run --json
+`
+
+const usageText = `
+Text Dissection:
+  sshx text --help
+  sshx text --help --json
+  sshx text -h=<host> --path=/abs/file.log [options]
+  sshx text -h=<host> --journal=UNIT [options]
+
+  Bounded remote text/log anatomy for Agents. Do not wrap grep/journalctl
+  in sshx run for incident triage — text returns structured hits.
+
+  Workflow:
+    1. sshx text --help  (or --help --json)
+    2. --preset=exception --json  (blocks and counts first)
+    3. --around-line=<hit.start_line> --context=5 --json
+    4. --download only for incident archives
+
+  --path=/abs/file          Stream a remote regular file over SFTP (default
+                            scan=end, last 8MiB). Symlinks/dirs refused.
+  --journal=UNIT            sshx-owned journalctl for one systemd unit
+  --preset=exception,error,panic,oom,http5xx
+  --pattern=RE2             Optional linear-time regexp after presets
+  --context=N               Neighbor lines (0..20)
+  --around-line=L           Slice around a previous hit
+  --offset=L --limit=N      Line window inside the scanned bytes
+  --tail=N                  Last N lines of the scanned window
+  --scan=start|end          File origin (default end)
+  --since= --until=         Journal time bounds (no shell metacharacters)
+  --max-hits=N --max-bytes=N --max-scan-bytes=N
+  --sudo                    Read with sudo -S
+  --no-redact               Keep secret-shaped spans (default redacts)
+
+  JSON schema sshx.text.v1: hits[], stats.total_hits vs returned,
+  truncated, truncated_reason, line_origin, redacted.
+  There is no --command; that is sshx run.
+
+  Monitoring:
+    A scan that runs longer than a few seconds narrates progress on stderr
+    (bytes, percentage, lines, elapsed, matches). Long or budget-limited scans
+    close with advice naming --offset/--tail/--max-scan-bytes. stderr carries
+    these lines only: stdout stays exactly one JSON document. stats gains
+    expected_scan_bytes (the window budget) alongside file_size/window_start_byte,
+    so a caller can size a scan before trusting total_hits_exact.
+
+  sshx text -h=prod-web --path=/var/log/nginx/error.log --preset=exception --json
+  sshx text -h=prod-web --journal=nginx.service --since=1h --preset=error --json
+`
+
+const usageLogin = `
+Interactive Login:
+  sshx login <name> [--sudo]
+  sshx login -h=<host> [-u=<user>] [-i=<key>] [--sudo]
+  sshx login --address=<host> [--sudo]
+  sshx login <name> --dry-run --json
+
+  Human-only escape hatch onto a host already known to sshx. It opens one
+  interactive session and attaches the local TTY. This is not an Agent
+  contract: --json is only valid with --dry-run, multi-host selectors are
+  rejected, and login is not exposed over MCP.
+
+  <name> / -h=HOST          Named host or hostname (exactly one)
+  --target=NAME             Long alias of -h= / <name>
+  --address=HOST            Literal address; skip settings.json resolution
+  --sudo                    Land in a privileged login shell (sudo -i)
+                            using the host sudo keyring secret on stdin
+  --dry-run / --json        Local plan only; --json requires --dry-run
+
+  Requires a local TTY. POSIX only; Windows returns an explicit unsupported
+  error. There is no command timeout and no session transcript. Audit records
+  target, auth, sudo, duration, and exit code.
+
+  sshx login prod-web
+  sshx login prod-web --sudo
+  sshx login -h=prod-web --sudo
+  sshx login prod-web --dry-run --json
+`
+
+const usagePlugin = `
+Plugin Management:
+  sshx plugin install <dir> [--replace] [--trust] [--json]
+  sshx plugin create <id> [--runner=sh] [--platform=linux|darwin]
+                          [--privilege=never|optional|required]
+                          [--template=generic|docker|nginx] [--replace] [--json]
+  sshx plugin list [--json]
+  sshx plugin show <id> [--json]
+  sshx plugin validate <id> [--json]
+  sshx plugin test <id> [--fixture=<name>] [--json]
+  sshx plugin trust <id> [--json]
+  sshx plugin remove <id> [--json]
+
+  Local plugins belong to sshx, not to an Agent skill. They are stored under
+  ~/.sshx/plugins/<id> and remain untrusted until their current digest is
+  explicitly trusted. Editing a trusted manifest, schema, or collector changes
+  the digest and blocks remote execution until it is trusted again.
+
+  plugin install is the audited way to provision an existing plugin directory:
+  it stages the source with sshx's own modes, validates it through the same
+  loader the executor uses, publishes it only if it is valid, and with --trust
+  records the published digest in one step. Symlinks and non-regular entries are
+  refused, and the copy is bounded (8MiB, 128 files). --replace preserves the
+  previous plugin under ~/.sshx/plugin-backups.
+
+  plugin list groups built-in capabilities and local plugins and always names
+  the local root, so "no local plugins installed" is visible as such; a local
+  entry reports builtin/trusted/valid and its digest. A missing plugin names the
+  directory that was searched.
+`
+
+const usageSkill = `
+Agent Skill Installation:
+  sshx skill install [--dir=<path>] [--force] [--json]
+
+  The canonical sshx Agent skill is embedded in the binary, so installation
+  does not need a network download or a release archive next to the executable.
+  The default target is ~/.agents/skills/sshx/SKILL.md. Pass --dir to select
+  another sshx skill directory.
+
+  A matching installed skill is left unchanged (or repaired to mode 0644).
+  A prior sshx-managed version is updated using its digest sidecar. Differing
+  unmanaged content is preserved unless --force is explicit. Symlinked targets
+  are rejected. JSON status is installed, current, repaired, or updated;
+  failures use conflict, unsafe_target, or install_error.
+`
+
+const usageEnv = `
+Environment Variables (.env):
+  SSH_PASSWORD          SSH password (not recommended, use SSH keys or keyring)
+  SSH_KEY_PATH          SSH private key path
+  SSH_SUDO_KEY          Sudo password keyring key name (default: master)
+  SSH_NO_SAFETY_CHECK   Disable safety checks (true/false)
+  SSH_FORCE             Force execution mode (true/false)
+  SSH_TIMEOUT           Command execution timeout (e.g. 30s, 2m, or 30 = seconds)
+  SSHX_AUDIT_OUTPUT     Audit output directory (default: ~/.sshx/audit)
+  SSHX_NO_AUDIT         Disable audit writing (true/false)
+  SSHX_HOME             Override the local sshx runtime root (default: ~/.sshx)
+  SSHX_SECRET_BACKEND   Secret store: keyring (default) or local-vault
+  SSHX_VAULT_PASSPHRASE Unlock passphrase for local-vault (unattended)
+  SSHX_VAULT_KEY_FILE   0600 file containing the vault passphrase (wins over env)
+`
+
+const usageSSHExamples = `
+SSH Examples:
+  # Execute simple command (default user: master)
+  sshx -h=192.168.1.100 "uptime"
+
+  # Execute sudo command (auto password from keyring: master)
+  sshx -h=192.168.1.100 "sudo systemctl status docker"
+
+  # Use custom sudo password key for specific server
+  sshx -h=192.168.1.100 -pk=server-A "sudo systemctl restart nginx"
+  sshx -h=192.168.1.101 -pk=server-B "sudo systemctl restart nginx"
+
+  # Custom SSH port
+  sshx -h=192.168.1.100 -p=2222 "ps aux | grep nginx"
+
+  # Bind the local source address (IP or interface name)
+  sshx -h=prod-web --bind=en0 "uptime"
+
+  # Structured JSON output for scripts/agents (one object on stdout)
+  sshx -h=192.168.1.100 --json "systemctl is-active nginx"
+
+  # Preview the execution plan without connecting or reading secrets
+  sshx -h=prod-web --dry-run --json "sudo systemctl restart nginx"
+
+  # Save audit events for this project
+  sshx -h=prod-web --audit-output=./.sshx-audit "systemctl reload nginx"
+
+  # Bound the command wait (does not guarantee remote termination)
+  sshx -h=192.168.1.100 --timeout=30s "apt-get update"
+
+  # Dangerous command will be blocked
+  sshx -h=192.168.1.100 "sudo rm -rf /tmp/*"  # Safe
+  sshx -h=192.168.1.100 "sudo rm -rf /"       # ⚠️ BLOCKED!
+
+  # Force execute (bypass safety check - use with caution!)
+  sshx -h=192.168.1.100 --force "sudo reboot"
+  sshx -h=192.168.1.100 -f "sudo systemctl reboot"
+`
+
+const usageInspectExamples = `
+Inspection Examples:
+  # Inspect stable system/network state in one invocation
+  sshx inspect -h=prod-web system.baseline --json
+
+  # Create a locally editable Docker capability, validate it, then trust it
+  sshx plugin create docker.environment --template=docker --privilege=optional --json
+  sshx plugin validate docker.environment --json
+  sshx plugin test docker.environment --fixture=complete --json
+  sshx plugin trust docker.environment --json
+
+  # Inspect once and persist only the redacted observation on the target
+  sshx inspect -h=prod-web docker.environment --cache=remote-prefer --json
+`
+
+const usageSkillExample = `
+Agent Skill Example:
+  # Install after Homebrew/go install, or refresh after upgrading sshx
+  sshx skill install
+
+  # Replace a locally modified copy after reviewing the difference
+  sshx skill install --force --json
+`
+
+const usageSFTPExamples = `
+SFTP Examples:
+  # Upload file
+  sshx -h=192.168.1.100 --upload=local.txt --to=/tmp/remote.txt
+
+  # Download file
+  sshx -h=192.168.1.100 --download=/var/log/app.log --to=./app.log
+
+  # List directory
+  sshx -h=192.168.1.100 --list=/var/log
+
+  # Create directory
+  sshx -h=192.168.1.100 --mkdir=/tmp/newdir
+
+  # Remove file
+  sshx -h=192.168.1.100 --rm=/tmp/oldfile.txt
+
+  # Batch upload
+  for file in *.txt; do
+    sshx -h=192.168.1.100 --upload=$file --to=/backup/$file
+  done
+`
+
+const usageTransferExamples = `
+Server-to-Server Transfer Examples:
+  # Transfer a file directly between two servers (by IP)
+  sshx --transfer=192.168.1.100:/var/log/app.log --to=192.168.1.101:/backup/app.log
+
+  # Transfer between configured hosts (from settings.json)
+  sshx --transfer=prod-web:/etc/nginx/nginx.conf --to=staging-web:/etc/nginx/nginx.conf
+
+  # Transfer a whole directory recursively
+  sshx --transfer=prod-db:/var/backups --to=backup-server:/mnt/archive/db
+
+  # If the destination is an existing directory, the source is placed inside it
+  sshx --transfer=prod-web:/var/log/app.log --to=log-server:/var/logs/
+
+  # Preview the transfer plan without connecting
+  sshx --transfer=prod-web:/data --to=prod-db:/data --dry-run
+`
+
+const usagePasswordExamples = `
+Password Management Examples:
+  # Set default sudo password (interactive prompt)
+  sshx --password-set=master
+
+  # Set sudo password (inline, not recommended for security)
+  sshx --password-set=master:mypassword
+
+  # Set passwords for different servers with same username
+  sshx --password-set=server-A
+  sshx --password-set=server-B
+  sshx --password-set=server-C
+
+  # Use different password keys for different servers
+  sshx -h=192.168.1.100 -pk=server-A "sudo systemctl status nginx"
+  sshx -h=192.168.1.101 -pk=server-B "sudo systemctl status nginx"
+  sshx -h=192.168.1.102 -pk=server-C "sudo systemctl status nginx"
+
+  # Set password for specific user
+  sshx --password-set=root
+  sshx --password-set=admin
+
+  # Get password from OS keyring (refused when using local-vault)
+  sshx --password-get=master
+
+  # Headless server: encrypted local vault (write-only; Agent never sees the value)
+  SSHX_SECRET_BACKEND=local-vault SSHX_VAULT_PASSPHRASE='…' \
+    sshx --password-set=prod-web
+  SSHX_SECRET_BACKEND=local-vault SSHX_VAULT_PASSPHRASE='…' \
+    sshx --password-check=prod-web
+
+
+  # Check if password exists
+  sshx --password-check=server-A
+
+  # List common password keys
+  sshx --password-list
+
+  # Delete password from keyring
+  sshx --password-delete=server-A
+`
+
+const usageHostExamples = `
+Host Management Examples:
+  # Add host interactively
+  sshx --host-add
+
+  # Add host with command line options
+  sshx --host-add --host-name=prod-web -h=192.168.1.100 -u=root -pk=prod-web --host-desc="Production Web Server"
+
+  # Add host with its own SSH private key
+  sshx --host-add --host-name=prod-db -h=192.168.1.200 -u=admin -i=~/.ssh/prod-db.pem
+
+  # Persist a source bind for a named host
+  sshx --host-add --host-name=edge --bind=en0 -h=100.117.253.247 -p=18922
+
+  # Update host IP address
+  sshx --host-update --host-name=prod-web -h=192.168.1.101
+
+  # Update host SSH key
+  sshx --host-update --host-name=prod-web -i=~/.ssh/new-key.pem
+
+  # Update host password key
+  sshx --host-update --host-name=prod-web -pk=new-password-key
+
+  # Update multiple fields
+  sshx --host-update --host-name=prod-web -h=192.168.1.101 -u=admin -pk=new-key
+
+  # List all configured hosts
+  sshx --host-list
+
+  # Test connection to a configured host
+  sshx --host-test=prod-web
+
+  # Test all configured hosts and get a report with auth methods
+  sshx --host-test-all
+
+  # Remove a host from configuration
+  sshx --host-remove=prod-web
+
+  # Use configured host (looks up from settings if not an IP)
+  sshx -h=prod-web "uptime"
+`
+
+const usageNotes = `
+Note:
+  - SSH key authentication is tried first; password auth is used only when SSH_PASSWORD is provided
+  - Sudo password is auto-filled only when the remote command starts with sudo
+  - Dry-run never connects, executes, reads keyring secrets, or writes state
+  - Audit events are JSONL files under ~/.sshx/audit by default
+  - SFTP operations use the same SSH connection
+  - Password manager works across macOS/Linux/Windows
+  - Default user: master, Default sudo key: master
+  - Host configurations are stored in ~/.sshx/settings.json`
+
+const usageAuditQuery = `
+Audit Query and Export:
+  sshx audit query [filters] [--json]
+  sshx audit export --to=<file> [filters]
+
+  Read-only consumption of the local JSONL trail. Query never connects and never
+  writes; export writes only the requested file.
+
+  --since=YYYY-MM-DD        Inclusive lower bound (date or RFC3339)
+  --until=YYYY-MM-DD        Exclusive upper bound
+  --target=NAME             Filter by target host name
+  --action=ACTION           Filter by action (command, run, apply, sql, ...)
+  --run-id=ID               Filter by run id
+  --execution-id=ID         Filter by execution id
+  --error-kind=KIND         Filter by error kind
+  --bypass-only             Only events that used a trust/safety bypass
+  --to=FILE                 Export destination (audit export only)
+  --json                    Emit the sshx.audit.v1 query document on stdout
+
+  Empty results exit 0. Corrupt or partial records are reported as diagnostics
+  and the valid records are retained.
+
+  sshx audit query --since=2026-09-01 --target=prod-web --json
+  sshx audit query --execution-id=<id> --json
+  sshx audit export --to=./incident.jsonl --since=2026-09-01
+`
+
+const usageMCP = `
+MCP Server (stdio):
+  sshx mcp
+
+  Serves the execution contract to an MCP client over stdio. The server is
+  spawned and owned by the client, lives for exactly one client session, and
+  re-enters sshx as one-shot child processes per tool call: no listening socket,
+  no resident state, no connection pool. Tools map 1:1 to CLI verbs and return
+  the same versioned JSON, and password management is never exposed as a tool.
+`
diff --git a/internal/app/usage_test.go b/internal/app/usage_test.go
index d3412ac..5d878d6 100644
--- a/internal/app/usage_test.go
+++ b/internal/app/usage_test.go
@@ -1,8 +1,13 @@
 package app
 
 import (
+	"encoding/json"
 	"strings"
 	"testing"
+
+	"github.com/stretchr/testify/require"
+
+	"github.com/talkincode/sshx/internal/sshclient"
 )
 
 func TestPrintUsage(t *testing.T) {
@@ -162,3 +167,70 @@ func TestPrintUsage_Examples(t *testing.T) {
 		}
 	}
 }
+
+// Every subcommand renders its own usage document, and sshx.help.v1 carries the
+// same blocks in machine-readable form. The global help points at both.
+func TestPrintVerbUsage(t *testing.T) {
+	// sshx text keeps its own Agent-facing document rather than the generic
+	// section rendering, in both the human and the JSON variant.
+	t.Run("text", func(t *testing.T) {
+		output := string(captureStdout(t, func() {
+			require.NoError(t, PrintVerbUsage(&sshclient.Config{HelpVerb: "text"}))
+		}))
+		require.Contains(t, output, "bounded remote text and log dissection")
+		require.Contains(t, output, "sshx.text.v1")
+	})
+	for _, verb := range helpVerbs {
+		if verb == "text" {
+			continue
+		}
+		t.Run(verb, func(t *testing.T) {
+			var printErr error
+			output := string(captureStdout(t, func() {
+				printErr = PrintVerbUsage(&sshclient.Config{HelpVerb: verb})
+			}))
+			require.NoError(t, printErr)
+			require.Contains(t, output, "sshx "+verb+" — ")
+			require.Contains(t, output, "SSH Options:")
+			require.Contains(t, output, "sshx "+verb+" --help --json")
+			for _, section := range usageSections() {
+				if section.verb == verb {
+					require.Contains(t, output, section.title+":")
+				}
+			}
+		})
+	}
+
+	unknown := PrintVerbUsage(&sshclient.Config{HelpVerb: "no-such-verb"})
+	require.Error(t, unknown)
+}
+
+func TestPrintVerbUsageJSON(t *testing.T) {
+	for _, verb := range helpVerbs {
+		if verb == "text" {
+			continue // covered by TestTextHelpJSON in the compiled-binary E2E suite
+		}
+		t.Run(verb, func(t *testing.T) {
+			output := captureStdout(t, func() {
+				require.NoError(t, PrintVerbUsage(&sshclient.Config{HelpVerb: verb, JSONOutput: true}))
+			})
+			var document verbHelpDocument
+			require.NoError(t, json.Unmarshal(output, &document))
+			require.Equal(t, helpSchemaVersion, document.SchemaVersion)
+			require.Equal(t, verb, document.Verb)
+			require.NotEmpty(t, document.Summary)
+			require.NotEmpty(t, document.Usage)
+			for _, section := range document.Usage {
+				require.NotEmpty(t, section.Title)
+				require.NotEmpty(t, section.Text)
+			}
+		})
+	}
+}
+
+func TestPrintUsageAdvertisesHelpSurfaces(t *testing.T) {
+	output := string(captureStdout(t, PrintUsage))
+	require.Contains(t, output, "sshx <verb> --help")
+	require.Contains(t, output, "--quiet, --no-notices")
+	require.Contains(t, output, "should pass --quiet")
+}
diff --git a/internal/execution/executor.go b/internal/execution/executor.go
index b97c67e..f43cdca 100644
--- a/internal/execution/executor.go
+++ b/internal/execution/executor.go
@@ -678,6 +678,16 @@ func executeOneWithMetadata(ctx context.Context, opts RunOptions, target Resolve
 	return res
 }
 
+// SudoKeyForTarget resolves the sudo keyring reference for one run target: the
+// caller's explicit key wins, then the host's configured sudo_password_key, then
+// the built-in default. The caller's key is empty unless it was chosen
+// explicitly (Policy.SudoPasswordKey), so the default key can never shadow a
+// host's own sudo key (issue #78), and the plan, the SSH client, and the keyring
+// lookup all resolve the same reference.
+func SudoKeyForTarget(policyKey, targetKey string) string {
+	return firstNonEmpty(policyKey, targetKey, sshclient.DefaultSudoKey)
+}
+
 func applyExecResult(res *TargetResult, req *Request, execRes sshclient.ExecResult, execErr error) {
 	res.Stdout = execRes.Stdout
 	res.Stderr = execRes.Stderr
@@ -751,7 +761,7 @@ func buildSSHConfig(req *Request, target ResolvedTarget) *sshclient.Config {
 		AllowInsecureHostKey:   req.Policy.AllowInsecureHostKey,
 		KnownHostsPath:         req.Policy.KnownHostsPath,
 		JSONOutput:             true,
-		SudoKey:                firstNonEmpty(target.SudoPasswordKey, req.Policy.SudoPasswordKey),
+		SudoKey:                SudoKeyForTarget(req.Policy.SudoPasswordKey, target.SudoPasswordKey),
 		Command:                req.Action.Command,
 		Mode:                   "ssh",
 		Bind:                   target.Bind,
@@ -853,10 +863,7 @@ func applySecrets(cfg *sshclient.Config, req *Request, target ResolvedTarget, se
 	if err := ctx.Err(); err != nil {
 		return err
 	}
-	sudoKey := firstNonEmpty(req.Policy.SudoPasswordKey, target.SudoPasswordKey)
-	if sudoKey == "" {
-		sudoKey = sshclient.DefaultSudoKey
-	}
+	sudoKey := SudoKeyForTarget(req.Policy.SudoPasswordKey, target.SudoPasswordKey)
 	cfg.SudoKey = sudoKey
 	if secrets == nil {
 		return fmt.Errorf("%w: sudo password key %q requested without secret resolver", ErrConfig, sudoKey)
diff --git a/internal/execution/selector_test.go b/internal/execution/selector_test.go
index fcc5a61..7c2a187 100644
--- a/internal/execution/selector_test.go
+++ b/internal/execution/selector_test.go
@@ -3,6 +3,8 @@ package execution
 import (
 	"errors"
 	"testing"
+
+	"github.com/talkincode/sshx/internal/sshclient"
 )
 
 func sampleHosts() []HostRecord {
@@ -137,3 +139,28 @@ func TestResolveTargets_BindInheritOverrideAndClear(t *testing.T) {
 		t.Fatalf("literal target bind = %#v", snap.Targets[0])
 	}
 }
+
+// The sudo keyring reference is resolved once for the plan, the SSH client, and
+// the keyring lookup: an explicit caller key wins, a host's configured
+// sudo_password_key comes next, and the built-in default is the last resort
+// (issue #78).
+func TestSudoKeyForTargetPrecedence(t *testing.T) {
+	tests := []struct {
+		name      string
+		policyKey string
+		targetKey string
+		want      string
+	}{
+		{"explicit caller key wins", "explicit-sudo", "host-sudo", "explicit-sudo"},
+		{"host key beats the default", "", "host-sudo", "host-sudo"},
+		{"host key fills a target without one", "", "", sshclient.DefaultSudoKey},
+		{"explicit caller key fills a target without one", "explicit-sudo", "", "explicit-sudo"},
+	}
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			if got := SudoKeyForTarget(test.policyKey, test.targetKey); got != test.want {
+				t.Fatalf("SudoKeyForTarget(%q, %q) = %q, want %q", test.policyKey, test.targetKey, got, test.want)
+			}
+		})
+	}
+}
diff --git a/internal/plugin/install.go b/internal/plugin/install.go
new file mode 100644
index 0000000..c3daa80
--- /dev/null
+++ b/internal/plugin/install.go
@@ -0,0 +1,225 @@
+package plugin
+
+import (
+	"fmt"
+	"io/fs"
+	"os"
+	"path/filepath"
+	"sort"
+	"strings"
+)
+
+const (
+	// MaxInstallBytes bounds the total payload copied from an install source.
+	MaxInstallBytes = 8 << 20
+	// MaxInstallFiles bounds the number of entries copied from an install source.
+	MaxInstallFiles = 128
+)
+
+// InstallOptions configures `sshx plugin install`.
+type InstallOptions struct {
+	Source  string // local directory that holds the plugin
+	Replace bool   // preserve an existing plugin as a backup (--replace)
+	Trust   bool   // trust the installed digest in the same step (--trust)
+}
+
+// InstallResult reports the published plugin.
+type InstallResult struct {
+	Resolved   *Resolved
+	Files      []string
+	BackupPath string
+}
+
+// Install publishes a local plugin directory into the runtime plugin root
+// ($SSHX_HOME/plugins/<id>). The source is staged with sshx's own restrictive
+// modes, validated through the same loader the executor uses, and only then
+// published, so an invalid source can never replace an installed plugin. --trust
+// records the published digest in the local trust lock in the same step.
+//
+// This is the audited alternative to hand-placing files under the plugin root:
+// it is one CLI invocation, it refuses symlinks and non-regular files, and it is
+// bounded by MaxInstallBytes/MaxInstallFiles.
+func Install(options InstallOptions) (*InstallResult, error) {
+	source, sourceErr := filepath.Abs(strings.TrimSpace(options.Source))
+	if sourceErr != nil {
+		return nil, fmt.Errorf("resolve install source: %w", sourceErr)
+	}
+	// The source itself must be a real directory: a symlinked source would make
+	// "install this directory" mean "install whatever it points at".
+	if linkInfo, linkErr := os.Lstat(source); linkErr != nil {
+		if os.IsNotExist(linkErr) {
+			return nil, fmt.Errorf("install source %s does not exist", source)
+		}
+		return nil, fmt.Errorf("inspect install source: %w", linkErr)
+	} else if !linkInfo.IsDir() || linkInfo.Mode()&(os.ModeSymlink|os.ModeIrregular) != 0 {
+		return nil, fmt.Errorf("install source must be a real directory (not a symlink): %s", source)
+	}
+
+	// A rooted handle keeps every source read inside the source directory even if
+	// the tree changes while it is being copied.
+	sourceRoot, rootErr := os.OpenRoot(source)
+	if rootErr != nil {
+		if os.IsNotExist(rootErr) {
+			return nil, fmt.Errorf("install source %s does not exist", source)
+		}
+		return nil, fmt.Errorf("inspect install source: %w", rootErr)
+	}
+	defer func() { _ = sourceRoot.Close() }() //nolint:errcheck // read-only handle cleanup
+	if info, statErr := sourceRoot.Stat("."); statErr != nil {
+		return nil, fmt.Errorf("inspect install source: %w", statErr)
+	} else if !info.IsDir() {
+		return nil, fmt.Errorf("install source must be a real directory (not a symlink): %s", source)
+	}
+
+	// The source is caller-owned staging: its permissions are not a plugin
+	// contract, because the staged copy below is written with sshx's own modes
+	// and then validated. Only the manifest identity is read from the source.
+	manifestInfo, manifestStatErr := sourceRoot.Lstat(ManifestFile)
+	if manifestStatErr != nil {
+		return nil, fmt.Errorf("read manifest: %w", manifestStatErr)
+	}
+	if !manifestInfo.Mode().IsRegular() || manifestInfo.Size() > MaxManifest {
+		return nil, fmt.Errorf("read manifest: %s is not a regular file under %d bytes", ManifestFile, MaxManifest)
+	}
+	manifestBytes, readErr := sourceRoot.ReadFile(ManifestFile)
+	if readErr != nil {
+		return nil, fmt.Errorf("read manifest: %w", readErr)
+	}
+	var manifest Manifest
+	if decodeErr := decodeStrictJSON(manifestBytes, &manifest); decodeErr != nil {
+		return nil, fmt.Errorf("parse manifest: %w", decodeErr)
+	}
+	id := strings.TrimSpace(manifest.ID)
+	if idErr := ValidateID(id); idErr != nil {
+		return nil, idErr
+	}
+	if _, builtin := resolveBuiltin(id); builtin {
+		return nil, fmt.Errorf("plugin id %q is reserved by a built-in capability", id)
+	}
+
+	root, rootErr := Root()
+	if rootErr != nil {
+		return nil, rootErr
+	}
+	if rootErr := ensurePrivateRoot(root); rootErr != nil {
+		return nil, rootErr
+	}
+
+	tempDir, tempErr := os.MkdirTemp(root, ".install-"+id+"-*")
+	if tempErr != nil {
+		return nil, fmt.Errorf("stage plugin install: %w", tempErr)
+	}
+	cleanup := true
+	defer func() {
+		if cleanup {
+			_ = os.RemoveAll(tempDir) //nolint:errcheck // best-effort cleanup inside the constrained plugin root
+		}
+	}()
+	// os.MkdirTemp already created the staging directory owner-only (0700).
+
+	files, copyErr := copyPluginTree(sourceRoot, tempDir, manifest)
+	if copyErr != nil {
+		return nil, copyErr
+	}
+	if _, validateErr := loadFromPath(tempDir, id); validateErr != nil {
+		return nil, fmt.Errorf("validate source plugin: %w", validateErr)
+	}
+
+	target := filepath.Join(root, id)
+	var backupPath string
+	if _, lstatErr := os.Lstat(target); lstatErr == nil {
+		if !options.Replace {
+			return nil, fmt.Errorf("plugin %q already exists; use --replace to preserve it as a backup", id)
+		}
+		var backupErr error
+		backupPath, backupErr = backupExisting(target, id)
+		if backupErr != nil {
+			return nil, backupErr
+		}
+	} else if !os.IsNotExist(lstatErr) {
+		return nil, fmt.Errorf("inspect existing plugin: %w", lstatErr)
+	}
+	published, renameErr := publishStagedDir(tempDir, target, backupPath)
+	if renameErr != nil {
+		return nil, renameErr
+	}
+	backupPath = published
+	cleanup = false
+
+	resolved, resolveErr := Resolve(id)
+	if resolveErr != nil {
+		return nil, fmt.Errorf("validate installed plugin: %w", resolveErr)
+	}
+	if options.Trust {
+		resolved, resolveErr = trustResolved(resolved)
+		if resolveErr != nil {
+			return nil, resolveErr
+		}
+	}
+	return &InstallResult{Resolved: resolved, Files: files, BackupPath: backupPath}, nil
+}
+
+// copyPluginTree stages one source plugin under the plugin root with sshx's own
+// modes: directories 0700, files 0600, and the declared entrypoint 0700. Symlinks
+// and non-regular files are refused so a source cannot pull content from outside
+// the plugin directory, and both handles are rooted, so the copy stays inside the
+// source and the staging directory even if the trees change mid-walk.
+func copyPluginTree(sourceRoot *os.Root, tempDir string, manifest Manifest) ([]string, error) {
+	stageRoot, rootErr := os.OpenRoot(tempDir)
+	if rootErr != nil {
+		return nil, fmt.Errorf("stage plugin install: %w", rootErr)
+	}
+	defer func() { _ = stageRoot.Close() }() //nolint:errcheck // staging handle cleanup
+
+	entrypoint := filepath.ToSlash(filepath.Clean(manifest.Runner.Entrypoint))
+	files := make([]string, 0, 8)
+	var total int64
+	walkErr := fs.WalkDir(sourceRoot.FS(), ".", func(relative string, entry fs.DirEntry, err error) error {
+		if err != nil {
+			return err
+		}
+		if relative == "." {
+			return nil
+		}
+		switch {
+		case entry.Type()&fs.ModeSymlink != 0:
+			return fmt.Errorf("install source contains a symlink (%s); plugins hold plain files only", relative)
+		case entry.IsDir():
+			return stageRoot.Mkdir(relative, 0o700)
+		case !entry.Type().IsRegular():
+			return fmt.Errorf("install source contains a non-regular entry (%s)", relative)
+		}
+		if len(files) >= MaxInstallFiles {
+			return fmt.Errorf("install source holds more than %d files", MaxInstallFiles)
+		}
+		info, infoErr := entry.Info()
+		if infoErr != nil {
+			return fmt.Errorf("read %s: %w", relative, infoErr)
+		}
+		if info.Size() > MaxInstallBytes {
+			return fmt.Errorf("read %s: file exceeds %d-byte limit", relative, MaxInstallBytes)
+		}
+		data, readErr := sourceRoot.ReadFile(relative)
+		if readErr != nil {
+			return fmt.Errorf("read %s: %w", relative, readErr)
+		}
+		total += int64(len(data))
+		if total > MaxInstallBytes {
+			return fmt.Errorf("install source exceeds %d bytes", MaxInstallBytes)
+		}
+		mode := os.FileMode(0o600)
+		if relative == entrypoint {
+			mode = 0o700
+		}
+		if writeErr := stageRoot.WriteFile(relative, data, mode); writeErr != nil {
+			return fmt.Errorf("stage %s: %w", relative, writeErr)
+		}
+		files = append(files, relative)
+		return nil
+	})
+	if walkErr != nil {
+		return nil, walkErr
+	}
+	sort.Strings(files)
+	return files, nil
+}
diff --git a/internal/plugin/install_test.go b/internal/plugin/install_test.go
new file mode 100644
index 0000000..6173b2c
--- /dev/null
+++ b/internal/plugin/install_test.go
@@ -0,0 +1,310 @@
+package plugin
+
+import (
+	"io/fs"
+	"os"
+	"path/filepath"
+	"runtime"
+	"strings"
+	"testing"
+
+	"github.com/stretchr/testify/require"
+)
+
+// installSourcePath stages one scaffolded plugin as an external source directory
+// with caller-owned permissions: install sanitizes modes instead of inheriting
+// them, so the source deliberately keeps a permissive layout. The scaffold is
+// built in a scratch runtime root, then copied out, because a source is by
+// definition not part of the plugin root.
+func installSourcePath(t *testing.T, id string) string {
+	t.Helper()
+	runtimeRoot := os.Getenv("SSHX_HOME")
+	scratch := t.TempDir()
+	t.Setenv("SSHX_HOME", scratch)
+	created, err := Create(CreateOptions{ID: id, Template: "generic"})
+	if err != nil {
+		t.Fatalf("Create(%q) error = %v", id, err)
+	}
+	t.Setenv("SSHX_HOME", runtimeRoot)
+	source := filepath.Join(t.TempDir(), id)
+	if copyErr := copyDirForTest(created.Resolved.Path, source); copyErr != nil {
+		t.Fatalf("stage source: %v", copyErr)
+	}
+	return source
+}
+
+func copyDirForTest(from, to string) error {
+	if err := os.MkdirAll(to, 0o750); err != nil { // #nosec G301 -- fixture stages a caller-owned source layout.
+		return err
+	}
+	sourceRoot, err := os.OpenRoot(from)
+	if err != nil {
+		return err
+	}
+	defer func() { _ = sourceRoot.Close() }() //nolint:errcheck // fixture handle cleanup
+	stageRoot, err := os.OpenRoot(to)
+	if err != nil {
+		return err
+	}
+	defer func() { _ = stageRoot.Close() }() //nolint:errcheck // fixture handle cleanup
+	return fs.WalkDir(sourceRoot.FS(), ".", func(relative string, entry fs.DirEntry, err error) error {
+		if err != nil {
+			return err
+		}
+		if relative == "." {
+			return nil
+		}
+		if entry.IsDir() {
+			return stageRoot.Mkdir(relative, 0o750)
+		}
+		data, readErr := sourceRoot.ReadFile(relative)
+		if readErr != nil {
+			return readErr
+		}
+		return stageRoot.WriteFile(relative, data, 0o600) // #nosec G306 -- fixture copy of its own scaffold.
+	})
+}
+
+func TestInstallPublishesValidatedPluginWithRestrictiveModes(t *testing.T) {
+	t.Setenv("SSHX_HOME", t.TempDir())
+	source := installSourcePath(t, "installed.inspect")
+
+	installed, err := Install(InstallOptions{Source: source})
+	if err != nil {
+		t.Fatalf("Install() error = %v", err)
+	}
+	if installed.Resolved.Trusted {
+		t.Fatal("installed plugin must stay untrusted until it is explicitly trusted")
+	}
+	if installed.BackupPath != "" {
+		t.Fatalf("fresh install must not back anything up, got %q", installed.BackupPath)
+	}
+	if installed.Resolved.Manifest.ID != "installed.inspect" {
+		t.Fatalf("installed id = %q", installed.Resolved.Manifest.ID)
+	}
+	root, err := Root()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if want := filepath.Join(root, "installed.inspect"); installed.Resolved.Path != want {
+		t.Fatalf("installed path = %q, want %q", installed.Resolved.Path, want)
+	}
+	for _, relative := range installed.Files {
+		info, statErr := os.Stat(filepath.Join(installed.Resolved.Path, relative))
+		if statErr != nil {
+			t.Fatalf("stat %s: %v", relative, statErr)
+		}
+		wantMode := os.FileMode(0o600)
+		if relative == "collectors/linux.sh" {
+			wantMode = 0o700
+		}
+		if runtime.GOOS == "windows" {
+			continue // synthetic mode bits on Windows are not ACL evidence
+		}
+		if info.Mode().Perm() != wantMode {
+			t.Fatalf("%s mode = %04o, want %04o", relative, info.Mode().Perm(), wantMode)
+		}
+	}
+	// The published plugin is immediately usable through the normal loader.
+	if _, resolveErr := Resolve("installed.inspect"); resolveErr != nil {
+		t.Fatalf("Resolve(installed) error = %v", resolveErr)
+	}
+}
+
+func TestInstallReplacesWithBackupAndTrustsInOneStep(t *testing.T) {
+	t.Setenv("SSHX_HOME", t.TempDir())
+	source := installSourcePath(t, "installed.inspect")
+
+	if _, err := Install(InstallOptions{Source: source}); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := Install(InstallOptions{Source: source}); err == nil {
+		t.Fatal("second install succeeded without --replace")
+	}
+	replaced, err := Install(InstallOptions{Source: source, Replace: true, Trust: true})
+	if err != nil {
+		t.Fatalf("Install(replace, trust) error = %v", err)
+	}
+	if replaced.BackupPath == "" {
+		t.Fatal("replace must preserve the previous plugin as a backup")
+	}
+	if _, statErr := os.Stat(filepath.Join(replaced.BackupPath, ManifestFile)); statErr != nil {
+		t.Fatalf("backup missing manifest: %v", statErr)
+	}
+	if !replaced.Resolved.Trusted {
+		t.Fatal("--trust must record the published digest in the same step")
+	}
+	// The trust lock stores the published digest, not the source's bytes.
+	listed, err := List()
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, summary := range listed {
+		if summary.ID != "installed.inspect" {
+			continue
+		}
+		if !summary.Trusted || summary.Digest != replaced.Resolved.Digest {
+			t.Fatalf("listing = %#v", summary)
+		}
+	}
+}
+
+func TestInstallRefusesSymlinksNonDirectoriesAndReservedIDs(t *testing.T) {
+	t.Setenv("SSHX_HOME", t.TempDir())
+	source := installSourcePath(t, "installed.inspect")
+	if symlinkErr := os.Symlink(filepath.Join(source, ManifestFile), filepath.Join(source, "linked.json")); symlinkErr != nil {
+		t.Skipf("symlinks unsupported here: %v", symlinkErr)
+	}
+	if _, err := Install(InstallOptions{Source: source}); err == nil || !strings.Contains(err.Error(), "symlink") {
+		t.Fatalf("symlink source error = %v", err)
+	}
+	if _, err := Install(InstallOptions{Source: filepath.Join(source, ManifestFile)}); err == nil {
+		t.Fatal("installing a file instead of a directory must fail")
+	}
+	if _, err := Install(InstallOptions{Source: filepath.Join(t.TempDir(), "missing")}); err == nil {
+		t.Fatal("missing source must fail")
+	}
+	reserved := installSourcePath(t, "installed.inspect")
+	manifestPath := filepath.Join(reserved, ManifestFile)
+	data, readErr := os.ReadFile(manifestPath) // #nosec G304 -- fixture reads its own staged manifest.
+	if readErr != nil {
+		t.Fatal(readErr)
+	}
+	reservedManifest := strings.Replace(string(data), `"installed.inspect"`, `"network.dns"`, 1)
+	if writeErr := os.WriteFile(manifestPath, []byte(reservedManifest), 0o600); writeErr != nil { // #nosec G304,G703 -- fixture rewrites its own staged manifest.
+		t.Fatal(writeErr)
+	}
+	if _, err := Install(InstallOptions{Source: reserved}); err == nil || !strings.Contains(err.Error(), "built-in") {
+		t.Fatalf("built-in id error = %v", err)
+	}
+}
+
+// A source that cannot be validated must never reach the published plugin: the
+// validation happens on a staged copy before the installed directory is touched.
+func TestInstallKeepsPublishedPluginWhenSourceIsInvalid(t *testing.T) {
+	t.Setenv("SSHX_HOME", t.TempDir())
+	source := installSourcePath(t, "installed.inspect")
+	published, err := Install(InstallOptions{Source: source})
+	if err != nil {
+		t.Fatal(err)
+	}
+	broken := installSourcePath(t, "installed.inspect")
+	collector := filepath.Join(broken, "collectors", "linux.sh")
+	if removeErr := os.Remove(collector); removeErr != nil {
+		t.Fatal(removeErr)
+	}
+	if _, err := Install(InstallOptions{Source: broken, Replace: true}); err == nil || !strings.Contains(err.Error(), "validate source plugin") {
+		t.Fatalf("invalid source error = %v", err)
+	}
+	if _, statErr := os.Stat(filepath.Join(published.Resolved.Path, "collectors", "linux.sh")); statErr != nil {
+		t.Fatalf("published plugin was disturbed by a failed install: %v", statErr)
+	}
+	if _, resolveErr := Resolve("installed.inspect"); resolveErr != nil {
+		t.Fatalf("published plugin no longer resolves: %v", resolveErr)
+	}
+}
+
+// A missing plugin names the directory that was searched, so a caller does not
+// have to derive the plugin root from the source or the documentation.
+func TestResolveMissingPluginNamesTheSearchedDirectory(t *testing.T) {
+	root := t.TempDir()
+	t.Setenv("SSHX_HOME", root)
+	_, err := Resolve("missing.plugin")
+	if err == nil {
+		t.Fatal("missing plugin resolved")
+	}
+	if !strings.Contains(err.Error(), filepath.Join(root, "plugins")) {
+		t.Fatalf("error does not name the plugin root: %v", err)
+	}
+	if !strings.Contains(err.Error(), "not found") {
+		t.Fatalf("error does not report a miss: %v", err)
+	}
+}
+
+// A killed install can leave a staging directory behind. It is not a plugin, and
+// a dot-prefixed name can never be a valid plugin id, so the inventory must not
+// report it as an INVALID entry that hides the real local plugins (issue #88).
+func TestListSkipsInterruptedInstallStaging(t *testing.T) {
+	root := t.TempDir()
+	t.Setenv("SSHX_HOME", root)
+	source := installSourcePath(t, "installed.inspect")
+	published, err := Install(InstallOptions{Source: source})
+	if err != nil {
+		t.Fatal(err)
+	}
+	pluginsRoot, err := Root()
+	if err != nil {
+		t.Fatal(err)
+	}
+	leftover := filepath.Join(pluginsRoot, ".install-installed.inspect-123456")
+	if mkdirErr := os.MkdirAll(leftover, 0o700); mkdirErr != nil {
+		t.Fatal(mkdirErr)
+	}
+	listed, err := List()
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, summary := range listed {
+		if strings.HasPrefix(summary.ID, ".install-") {
+			t.Fatalf("staging directory reported as a plugin: %#v", summary)
+		}
+	}
+	found := false
+	for _, summary := range listed {
+		if summary.ID == "installed.inspect" {
+			found = true
+			if !summary.Valid || summary.Path != published.Resolved.Path {
+				t.Fatalf("published plugin listing = %#v", summary)
+			}
+		}
+	}
+	if !found {
+		t.Fatalf("published plugin missing from %#v", listed)
+	}
+}
+
+// A failed publication must not leave the plugin missing: the previous plugin is
+// restored when the staged move fails and the restore can run, and it is kept at
+// its backup path when the restore cannot (AGENT.md §9 recovery evidence).
+func TestPublishStagedDirRestoresOrKeepsThePreviousPlugin(t *testing.T) {
+	dir := t.TempDir()
+	target := filepath.Join(dir, "target")
+	backup := filepath.Join(dir, "backup")
+	writeBackup := func(t *testing.T) {
+		t.Helper()
+		require.NoError(t, os.MkdirAll(backup, 0o700))
+		require.NoError(t, os.WriteFile(filepath.Join(backup, ManifestFile), []byte("previous\n"), 0o600))
+	}
+
+	// The staged move fails (the staging directory was lost) while the previous
+	// plugin is still recoverable: it must come back instead of staying missing.
+	writeBackup(t)
+	kept, publishErr := publishStagedDir(filepath.Join(dir, "lost-stage"), target, backup)
+	require.Error(t, publishErr)
+	require.Contains(t, publishErr.Error(), "previous plugin restored")
+	require.Empty(t, kept, "a restored plugin no longer needs its backup path")
+	restored, readErr := os.ReadFile(filepath.Join(target, ManifestFile)) // #nosec G304 -- fixture path inside the owned test directory.
+	require.NoError(t, readErr, "the previous plugin must be back in place")
+	require.Equal(t, []byte("previous\n"), restored)
+	require.NoFileExists(t, backup, "the restore consumes the backup")
+
+	// The rename fails because the target cannot be replaced and the restore
+	// cannot run either: the failure must name where the previous plugin is kept,
+	// and that recovery copy must survive.
+	writeBackup(t)
+	stage := filepath.Join(dir, "stage")
+	require.NoError(t, os.MkdirAll(stage, 0o700))
+	require.NoError(t, os.MkdirAll(filepath.Join(target, "child"), 0o700))
+	kept, publishErr = publishStagedDir(stage, target, backup)
+	require.Error(t, publishErr)
+	require.Contains(t, publishErr.Error(), "previous plugin kept at "+backup)
+	require.Equal(t, backup, kept)
+	_, statErr := os.Stat(filepath.Join(backup, ManifestFile))
+	require.NoError(t, statErr, "the recovery copy must survive a failed publication")
+
+	// Without a backup there is nothing to restore, and the error stays plain.
+	kept, publishErr = publishStagedDir(stage, target, "")
+	require.Error(t, publishErr)
+	require.NotContains(t, publishErr.Error(), "kept at")
+	require.Empty(t, kept)
+}
diff --git a/internal/plugin/store.go b/internal/plugin/store.go
index 5d8c721..f00b977 100644
--- a/internal/plugin/store.go
+++ b/internal/plugin/store.go
@@ -46,6 +46,19 @@ func Path(id string) (string, error) {
 	return filepath.Join(root, id), nil
 }
 
+// ensurePrivateRoot creates the plugin root when it is missing and keeps it
+// owner-only: a group- or world-writable plugin root would let another local
+// account plant a plugin that later gets trusted.
+func ensurePrivateRoot(root string) error {
+	if err := os.MkdirAll(root, 0o700); err != nil {
+		return fmt.Errorf("create plugin root: %w", err)
+	}
+	if err := os.Chmod(root, 0o700); err != nil { // #nosec G302 -- private directory requires owner traversal.
+		return fmt.Errorf("secure plugin root: %w", err)
+	}
+	return nil
+}
+
 func Resolve(id string) (*Resolved, error) {
 	if builtin, ok := resolveBuiltin(id); ok {
 		return builtin, nil
@@ -62,7 +75,7 @@ func loadFromPath(pluginPath, expectedID string) (*Resolved, error) {
 	rootInfo, rootErr := os.Lstat(pluginRoot)
 	if rootErr != nil {
 		if os.IsNotExist(rootErr) {
-			return nil, fmt.Errorf("plugin %q not found", expectedID)
+			return nil, fmt.Errorf("plugin %q not found in %s", expectedID, pluginRoot)
 		}
 		return nil, fmt.Errorf("inspect plugin root: %w", rootErr)
 	}
@@ -72,7 +85,7 @@ func loadFromPath(pluginPath, expectedID string) (*Resolved, error) {
 	info, statErr := os.Lstat(pluginPath)
 	if statErr != nil {
 		if os.IsNotExist(statErr) {
-			return nil, fmt.Errorf("plugin %q not found", expectedID)
+			return nil, fmt.Errorf("plugin %q not found in %s", expectedID, pluginRoot)
 		}
 		return nil, fmt.Errorf("inspect plugin path: %w", statErr)
 	}
@@ -373,6 +386,13 @@ func List() ([]Summary, error) {
 		if !entry.IsDir() {
 			continue
 		}
+		// sshx's own staging and scaffold directories (".install-*", ".create-*")
+		// are not plugins, and a dot-prefixed name can never be a valid plugin id:
+		// reporting them as INVALID entries would hide the real inventory after an
+		// interrupted install (issue #88).
+		if strings.HasPrefix(entry.Name(), ".") {
+			continue
+		}
 		id := entry.Name()
 		resolved, resolveErr := Resolve(id)
 		if resolveErr != nil {
@@ -465,6 +485,14 @@ func Trust(id string) (*Resolved, error) {
 	if resolved.Builtin {
 		return resolved, nil
 	}
+	return trustResolved(resolved)
+}
+
+// trustResolved records one already-resolved plugin digest in the local trust
+// lock. An explicitly trusted digest is the only way a local plugin becomes
+// admissible for remote execution.
+func trustResolved(resolved *Resolved) (*Resolved, error) {
+	id := resolved.Manifest.ID
 	lock, err := loadLock()
 	if err != nil {
 		return nil, err
diff --git a/internal/plugin/templates.go b/internal/plugin/templates.go
index 6c2771e..a6a2e41 100644
--- a/internal/plugin/templates.go
+++ b/internal/plugin/templates.go
@@ -62,11 +62,8 @@ func Create(options CreateOptions) (*CreateResult, error) {
 	if rootErr != nil {
 		return nil, rootErr
 	}
-	if mkdirErr := os.MkdirAll(root, 0o700); mkdirErr != nil {
-		return nil, fmt.Errorf("create plugin root: %w", mkdirErr)
-	}
-	if chmodErr := os.Chmod(root, 0o700); chmodErr != nil { // #nosec G302 -- private directory requires owner traversal.
-		return nil, fmt.Errorf("secure plugin root: %w", chmodErr)
+	if rootErr := ensurePrivateRoot(root); rootErr != nil {
+		return nil, rootErr
 	}
 	target := filepath.Join(root, options.ID)
 	var backupPath string
@@ -93,9 +90,7 @@ func Create(options CreateOptions) (*CreateResult, error) {
 			_ = os.RemoveAll(tempDir) //nolint:errcheck // best-effort cleanup inside constrained plugin root
 		}
 	}()
-	if chmodErr := os.Chmod(tempDir, 0o700); chmodErr != nil { // #nosec G302 -- private directory requires owner traversal.
-		return nil, chmodErr
-	}
+	// os.MkdirTemp already created the scaffold directory owner-only (0700).
 
 	manifest := templateManifest(options)
 	manifestData, marshalErr := json.MarshalIndent(manifest, "", "  ")
@@ -127,9 +122,11 @@ func Create(options CreateOptions) (*CreateResult, error) {
 		}
 		written = append(written, relative)
 	}
-	if renameErr := os.Rename(tempDir, target); renameErr != nil {
-		return nil, fmt.Errorf("install plugin: %w", renameErr)
+	published, renameErr := publishStagedDir(tempDir, target, backupPath)
+	if renameErr != nil {
+		return nil, renameErr
 	}
+	backupPath = published
 	cleanup = false
 	sort.Strings(written)
 	resolved, resolveErr := Resolve(options.ID)
@@ -168,6 +165,23 @@ func Remove(id string) (string, error) {
 	return backup, nil
 }
 
+// publishStagedDir moves a staged plugin directory into place and restores the
+// previous plugin when the move fails, so a failed publication never leaves the
+// plugin missing while a recovery copy exists elsewhere. It returns the backup
+// path that still holds the previous plugin ("" when the restore consumed it).
+func publishStagedDir(tempDir, target, backupPath string) (string, error) {
+	if err := os.Rename(tempDir, target); err != nil {
+		if backupPath != "" {
+			if restoreErr := os.Rename(backupPath, target); restoreErr == nil {
+				return "", fmt.Errorf("publish plugin: %w (previous plugin restored)", err)
+			}
+			return backupPath, fmt.Errorf("publish plugin: %w (previous plugin kept at %s)", err, backupPath)
+		}
+		return "", fmt.Errorf("publish plugin: %w", err)
+	}
+	return backupPath, nil
+}
+
 func backupExisting(source, id string) (string, error) {
 	root, err := runtimeRoot()
 	if err != nil {
diff --git a/internal/plugin/types.go b/internal/plugin/types.go
index 74330c9..08ed7ed 100644
--- a/internal/plugin/types.go
+++ b/internal/plugin/types.go
@@ -145,6 +145,9 @@ type ActionResult struct {
 	Action      string    `json:"action"`
 	PluginID    string    `json:"plugin_id,omitempty"`
 	Path        string    `json:"path,omitempty"`
+	Builtin     bool      `json:"builtin,omitempty"`
+	PluginRoot  string    `json:"plugin_root,omitempty"`
+	Source      string    `json:"source,omitempty"`
 	BackupPath  string    `json:"backup_path,omitempty"`
 	Digest      string    `json:"digest,omitempty"`
 	Trusted     bool      `json:"trusted,omitempty"`
diff --git a/internal/sshclient/client.go b/internal/sshclient/client.go
index 3c10daf..5c85a2b 100644
--- a/internal/sshclient/client.go
+++ b/internal/sshclient/client.go
@@ -131,7 +131,12 @@ type Config struct {
 	PluginPrivilege string
 	PluginTemplate  string
 	PluginFixture   string
-	PluginReplace   bool
+	// PluginSource is the install positional: the local plugin directory that
+	// `sshx plugin install` publishes into the runtime plugin root.
+	PluginSource string
+	// PluginTrust trusts the installed digest in the same install step.
+	PluginTrust   bool
+	PluginReplace bool
 
 	// Agent skill lifecycle fields (Mode == "skill").
 	SkillAction string
@@ -175,6 +180,9 @@ type Config struct {
 
 	// Guarded SQL execution fields (Mode == "sql").
 	SQLStatement string
+	// SQLStatementFile is a local file holding the statement, used when no
+	// positional statement is given (--statement-file=PATH).
+	SQLStatementFile string
 	// SQLEngine names the database engine: "postgres" (default) or "sqlite".
 	SQLEngine   string
 	SQLDatabase string
@@ -252,7 +260,21 @@ type Config struct {
 	TextMaxScanBytes int64
 	TextUseSudo      bool
 	TextRedact       bool
-	TextHelp         bool
+
+	// HelpVerb is the subcommand whose usage document was requested with
+	// `sshx <verb> --help`. It short-circuits parsing and execution: the verb's
+	// own usage is printed instead of running anything.
+	HelpVerb string
+
+	// ShowUsage requests the global `sshx --help` surface. It is answered before
+	// any mode runs, so a usage request never resolves a host, connects, or
+	// writes trust state.
+	ShowUsage bool
+
+	// Quiet suppresses human notices on stderr (deprecation warnings, narration
+	// log lines). It never changes stdout, the exit code, or the machine result,
+	// so a caller that merges stderr under --json can still parse stdout.
+	Quiet bool
 
 	// Interactive login fields (Mode == "login").
 	LoginUseSudo     bool
diff --git a/skills/sshx/SKILL.md b/skills/sshx/SKILL.md
index d67bfa9..9385f8e 100644
--- a/skills/sshx/SKILL.md
+++ b/skills/sshx/SKILL.md
@@ -40,6 +40,16 @@ sshx plugin list --json
 sshx inspect -h=prod-web system.baseline --json
 ```
 
+`sshx plugin list` always names the local plugin root and its provenance, and a
+missing plugin names the directory that was searched. When a plugin already
+exists as a local directory, provision it through the CLI instead of placing
+files by hand:
+
+```bash
+sshx plugin install ./my-plugin --trust --json   # validate + publish + trust
+sshx plugin install ./my-plugin --replace --json # keep the old one as a backup
+```
+
 Application-specific scripts are sshx runtime assets under
 `~/.sshx/plugins/<id>` (or `$SSHX_HOME/plugins/<id>`). **Do not embed or maintain
 collector scripts in this skill.** If no suitable plugin exists, ask sshx to
@@ -112,6 +122,16 @@ Branch on `success` / `status` first; on failure read `error.kind` or
 `error_kind` (do not parse free-form text). For change actions, inspect
 `completion` before any retry (`not_started|partial|completed|completed_unconfirmed|unknown`).
 
+Every subcommand documents itself: `sshx <verb> --help` prints that verb's
+usage, and `sshx <verb> --help --json` returns the same blocks as
+`sshx.help.v1` (`sshx text --help --json` keeps its structured
+`sshx.text.help.v1` document). Read the verb's help before guessing flag names.
+
+Under `--json`, stdout carries the machine document and nothing else; human
+notices (deprecation warnings, narration) go to stderr. Pass `--quiet` when you
+merge the streams (`2>&1`): it suppresses the notices, so the merged stream still
+parses while failures keep their JSON `error_kind`/`error`.
+
 Selectors resolve only configured host aliases. Literal addresses require
 `--address=` and cannot enter group/tag fan-out. Zero matches is exit `255`
 with no network access.
@@ -322,6 +342,11 @@ automatic backup → execute → structured result + audit event.
 # Reads run directly; no EXPLAIN, no backup.
 sshx sql -h=db1 --db=app --json "SELECT count(*) FROM users"
 
+# A statement that opens with a comment is statement text, not an option; a
+# .sql file can be handed over directly, or piped on stdin.
+sshx sql -h=db1 --db=app --json --statement-file=./query.sql
+printf '%s' 'select 1' | sshx sql -h=db1 --db=app --json
+
 # DML with WHERE: rows are snapshotted to CSV on the remote host first.
 sshx sql -h=db1 --db=app --db-user=app --db-password-key=app-db --json \
     "UPDATE users SET active=false WHERE id=42"
diff --git a/tests/e2e/host_audit_e2e_test.go b/tests/e2e/host_audit_e2e_test.go
index 82b8e7f..4de173b 100644
--- a/tests/e2e/host_audit_e2e_test.go
+++ b/tests/e2e/host_audit_e2e_test.go
@@ -84,6 +84,91 @@ func TestCLIAuditQueryByRunID(t *testing.T) {
 	assert.Equal(t, 0, emptyDoc.Count)
 }
 
+// `sshx run --target=` resolves the sudo key per host, and the audit trail must
+// name the reference each host actually used: the per-target event carries the
+// resolved key, while the run summary reports only a caller-level choice instead
+// of misreporting the built-in default (issue #78).
+func TestCLIRunAuditRecordsResolvedPerTargetSudoKey(t *testing.T) {
+	server := startSSHServer(t, serverOptions{})
+	home := t.TempDir()
+	auditDir := filepath.Join(home, "audit")
+	env := map[string]string{
+		"SSHX_E2E_KEYRING_FILE": filepath.Join(home, "keyring.json"),
+		"SSH_PASSWORD":          operatorPassword,
+		"SSHX_NO_AUDIT":         "false",
+	}
+	// The host's sudo key holds the operator password; "master" is never seeded,
+	// so a run that fell back to the default could not authenticate sudo.
+	set := runSSHXWithTestKeyring(t, home, []string{"--password-set=hostkey:" + operatorPassword, "--no-audit"}, env)
+	require.Equal(t, 0, set.exitCode, set.stderr)
+	writeSettings(t, home, map[string]any{
+		"hosts": []map[string]any{{
+			"name": "prod-web", "host": server.host, "port": server.port, "user": "operator",
+			"sudo_password_key": "hostkey",
+		}},
+	})
+
+	auditEventsFor := func(t *testing.T, runID string) []map[string]any {
+		t.Helper()
+		queried := runSSHXWithTestKeyring(t, home, []string{
+			"audit", "query", "--run-id=" + runID, "--json", "--audit-output=" + auditDir, "--no-audit",
+		}, env)
+		require.Equal(t, 0, queried.exitCode, queried.stderr)
+		var queryDoc struct {
+			Events []map[string]any `json:"events"`
+		}
+		require.NoError(t, json.Unmarshal([]byte(queried.stdout), &queryDoc))
+		require.NotEmpty(t, queryDoc.Events, queried.stdout)
+		return queryDoc.Events
+	}
+	splitEvents := func(t *testing.T, events []map[string]any) (summary, target map[string]any) {
+		t.Helper()
+		for _, event := range events {
+			if _, ok := event["target_index"]; ok {
+				target = event
+				continue
+			}
+			summary = event
+		}
+		require.NotNil(t, summary, "run must write a summary audit event")
+		require.NotNil(t, target, "run must write a per-target audit event")
+		return summary, target
+	}
+
+	ran := runSSHXWithTestKeyring(t, home, []string{
+		"run", "--target=prod-web", "--no-key", "--accept-unknown-host",
+		"--json", "--audit-output=" + auditDir, "--", "sudo whoami",
+	}, env)
+	require.Equal(t, 0, ran.exitCode, "stderr=%s stdout=%s", ran.stderr, ran.stdout)
+	var runDoc struct {
+		RunID string `json:"run_id"`
+	}
+	require.NoError(t, json.Unmarshal([]byte(ran.stdout), &runDoc))
+	require.NotEmpty(t, runDoc.RunID)
+
+	summary, target := splitEvents(t, auditEventsFor(t, runDoc.RunID))
+	assert.Equal(t, "hostkey", target["sudo_key"],
+		"the per-target event must name the sudo key the host resolved to")
+	assert.NotContains(t, summary, "sudo_key",
+		"a caller that chose no key must not be recorded as using the built-in default")
+
+	// An explicit caller key overrides the host's key and is recorded as such.
+	explicitSet := runSSHXWithTestKeyring(t, home, []string{"--password-set=explicit:" + operatorPassword, "--no-audit"}, env)
+	require.Equal(t, 0, explicitSet.exitCode, explicitSet.stderr)
+	override := runSSHXWithTestKeyring(t, home, []string{
+		"run", "--target=prod-web", "-pk=explicit", "--no-key", "--accept-unknown-host",
+		"--json", "--audit-output=" + auditDir, "--", "sudo whoami",
+	}, env)
+	require.Equal(t, 0, override.exitCode, "stderr=%s stdout=%s", override.stderr, override.stdout)
+	var overrideDoc struct {
+		RunID string `json:"run_id"`
+	}
+	require.NoError(t, json.Unmarshal([]byte(override.stdout), &overrideDoc))
+	overrideSummary, overrideTarget := splitEvents(t, auditEventsFor(t, overrideDoc.RunID))
+	assert.Equal(t, "explicit", overrideTarget["sudo_key"])
+	assert.Equal(t, "explicit", overrideSummary["sudo_key"])
+}
+
 func TestCLIHostImportIsUsableAndFailedSelectionIsAllOrNothing(t *testing.T) {
 	server := startSSHServer(t, serverOptions{})
 	home := t.TempDir()
diff --git a/tests/e2e/inspect_plugin_e2e_test.go b/tests/e2e/inspect_plugin_e2e_test.go
index b8b9a50..ef712ad 100644
--- a/tests/e2e/inspect_plugin_e2e_test.go
+++ b/tests/e2e/inspect_plugin_e2e_test.go
@@ -2,6 +2,7 @@ package e2e
 
 import (
 	"encoding/json"
+	"io/fs"
 	"os"
 	"path/filepath"
 	"strings"
@@ -115,6 +116,164 @@ func TestCLIPluginLifecycleCreatesValidRecoverableRuntimeAssets(t *testing.T) {
 	assert.NoDirExists(t, createResult.Path)
 }
 
+// `sshx plugin install <dir>` is the audited provisioning path: it publishes a
+// local plugin directory into the runtime plugin root with sshx's own modes,
+// validates it before publishing, and can trust the digest in the same step.
+func TestCLIPluginInstallProvisionsFromALocalDirectory(t *testing.T) {
+	home := t.TempDir()
+	runtimeRoot := filepath.Join(t.TempDir(), "agent-runtime")
+	runtimeEnv := map[string]string{"SSHX_HOME": runtimeRoot}
+
+	// Stage the source outside the runtime root, the way an operator would.
+	scaffold := runSSHX(t, home, []string{"plugin", "create", "private.environment", "--privilege=optional", "--json"},
+		map[string]string{"SSHX_HOME": filepath.Join(t.TempDir(), "scaffold-runtime")})
+	require.Equal(t, 0, scaffold.exitCode, scaffold.stderr)
+	var scaffoldResult pluginpkg.ActionResult
+	require.NoError(t, json.Unmarshal([]byte(scaffold.stdout), &scaffoldResult))
+	source := filepath.Join(t.TempDir(), "staging", "private.environment")
+	copyPluginTreeForTest(t, scaffoldResult.Path, source)
+	// A checked-out plugin carries caller-owned modes; install must not inherit them.
+	manifestSource := filepath.Join(source, pluginpkg.ManifestFile)
+	collectorSourcePath := filepath.Join(source, "collectors", "linux.sh")
+	require.NoError(t, os.Chmod(manifestSource, 0o644))      // #nosec G302 -- fixture stages caller-owned source modes on purpose.
+	require.NoError(t, os.Chmod(collectorSourcePath, 0o755)) // #nosec G302 -- fixture stages caller-owned source modes on purpose.
+
+	// A missing plugin names the directory that was searched.
+	missing := runSSHX(t, home, []string{"plugin", "show", "private.environment", "--json"}, runtimeEnv)
+	assert.Equal(t, 255, missing.exitCode)
+	assert.Contains(t, missing.stdout, filepath.Join(runtimeRoot, "plugins"))
+
+	installed := runSSHX(t, home, []string{"plugin", "install", source, "--json"}, runtimeEnv)
+	require.Equal(t, 0, installed.exitCode, installed.stderr)
+	var installResult pluginpkg.ActionResult
+	require.NoError(t, json.Unmarshal([]byte(installed.stdout), &installResult))
+	assert.True(t, installResult.Success)
+	assert.Equal(t, "private.environment", installResult.PluginID)
+	assert.Equal(t, filepath.Join(runtimeRoot, "plugins", "private.environment"), installResult.Path)
+	assert.Equal(t, filepath.Join(runtimeRoot, "plugins"), installResult.PluginRoot)
+	assert.False(t, installResult.Trusted)
+	assert.Len(t, installResult.Files, 6)
+	for _, relative := range installResult.Files {
+		info, err := os.Stat(filepath.Join(installResult.Path, relative))
+		require.NoError(t, err)
+		want := os.FileMode(0o600)
+		if strings.HasPrefix(relative, "collectors/") {
+			want = 0o700
+		}
+		assert.Equal(t, want, info.Mode().Perm(), relative)
+	}
+
+	// The installed plugin is immediately usable, but still untrusted.
+	tested := runSSHX(t, home, []string{"plugin", "test", "private.environment", "--fixture=complete", "--json"}, runtimeEnv)
+	require.Equal(t, 0, tested.exitCode, tested.stderr)
+	untrusted := runSSHX(t, home, []string{"plugin", "show", "private.environment", "--json"}, runtimeEnv)
+	require.Equal(t, 0, untrusted.exitCode, untrusted.stderr)
+	var untrustedResult pluginpkg.ActionResult
+	require.NoError(t, json.Unmarshal([]byte(untrusted.stdout), &untrustedResult))
+	assert.False(t, untrustedResult.Trusted)
+	assert.False(t, untrustedResult.Builtin)
+	assert.Equal(t, installResult.Digest, untrustedResult.Digest)
+
+	// Re-installing needs --replace; the previous plugin stays recoverable and the
+	// digest follows the content, so the replacement must be re-trusted.
+	duplicate := runSSHX(t, home, []string{"plugin", "install", source, "--json"}, runtimeEnv)
+	assert.Equal(t, 255, duplicate.exitCode)
+	var duplicateResult pluginpkg.ActionResult
+	require.NoError(t, json.Unmarshal([]byte(duplicate.stdout), &duplicateResult))
+	assert.Equal(t, "already_exists", duplicateResult.ErrorKind)
+
+	// The digest covers identity-bearing content: changing the collector changes
+	// the digest, so the replaced plugin is untrusted until it is trusted again.
+	trustedFirst := runSSHX(t, home, []string{"plugin", "trust", "private.environment", "--json"}, runtimeEnv)
+	require.Equal(t, 0, trustedFirst.exitCode, trustedFirst.stderr)
+	collectorSource := collectorSourcePath
+	collectorBytes, readErr := os.ReadFile(collectorSource) // #nosec G304 -- fixture reads its own staged source.
+	require.NoError(t, readErr)
+	require.NoError(t, os.WriteFile(collectorSource, append(collectorBytes, []byte("# edited\n")...), 0o755)) // #nosec G306,G703 -- fixture stages a permissive source collector.
+
+	replaced := runSSHX(t, home, []string{"plugin", "install", source, "--replace", "--json"}, runtimeEnv)
+	require.Equal(t, 0, replaced.exitCode, replaced.stderr)
+	var replaceResult pluginpkg.ActionResult
+	require.NoError(t, json.Unmarshal([]byte(replaced.stdout), &replaceResult))
+	assert.NotEmpty(t, replaceResult.BackupPath)
+	_, err := os.Stat(filepath.Join(replaceResult.BackupPath, pluginpkg.ManifestFile))
+	require.NoError(t, err)
+	assert.False(t, replaceResult.Trusted, "replaced content must be trusted again explicitly")
+	assert.NotEqual(t, installResult.Digest, replaceResult.Digest)
+
+	retrusted := runSSHX(t, home, []string{"plugin", "install", source, "--replace", "--trust", "--json"}, runtimeEnv)
+	require.Equal(t, 0, retrusted.exitCode, retrusted.stderr)
+	var retrustResult pluginpkg.ActionResult
+	require.NoError(t, json.Unmarshal([]byte(retrusted.stdout), &retrustResult))
+	assert.True(t, retrustResult.Trusted)
+	assert.Equal(t, replaceResult.Digest, retrustResult.Digest)
+
+	// A source that cannot be validated never replaces the published plugin.
+	broken := filepath.Join(t.TempDir(), "broken", "private.environment")
+	copyPluginTreeForTest(t, source, broken)
+	require.NoError(t, os.Remove(filepath.Join(broken, "collectors", "linux.sh")))
+	refused := runSSHX(t, home, []string{"plugin", "install", broken, "--replace", "--json"}, runtimeEnv)
+	assert.Equal(t, 255, refused.exitCode)
+	var refusedResult pluginpkg.ActionResult
+	require.NoError(t, json.Unmarshal([]byte(refused.stdout), &refusedResult))
+	assert.Contains(t, refusedResult.Error, "validate source plugin")
+	stillThere := runSSHX(t, home, []string{"plugin", "validate", "private.environment", "--json"}, runtimeEnv)
+	require.Equal(t, 0, stillThere.exitCode, stillThere.stderr)
+
+	// A symlink in the source is refused: a plugin holds plain files only.
+	symlinked := filepath.Join(t.TempDir(), "symlinked", "private.environment")
+	copyPluginTreeForTest(t, source, symlinked)
+	if symlinkErr := os.Symlink(filepath.Join(symlinked, pluginpkg.ManifestFile), filepath.Join(symlinked, "alias.json")); symlinkErr != nil {
+		t.Logf("skipping symlink assertion: %v", symlinkErr)
+	} else {
+		refusedLink := runSSHX(t, home, []string{"plugin", "install", symlinked, "--json"}, runtimeEnv)
+		assert.Equal(t, 255, refusedLink.exitCode)
+		assert.Contains(t, refusedLink.stdout, "symlink")
+	}
+
+	// The inventory groups provenance, names the local root, and makes an empty
+	// local set visible instead of inferring it from missing rows.
+	listed := runSSHX(t, home, []string{"plugin", "list"}, runtimeEnv)
+	require.Equal(t, 0, listed.exitCode, listed.stderr)
+	assert.Contains(t, listed.stdout, "built-in capabilities (8):")
+	assert.Contains(t, listed.stdout, "local plugins (1) in "+filepath.Join(runtimeRoot, "plugins"))
+	assert.Contains(t, listed.stdout, "trusted=true")
+	empty := runSSHX(t, home, []string{"plugin", "list"}, map[string]string{"SSHX_HOME": filepath.Join(t.TempDir(), "empty-runtime")})
+	require.Equal(t, 0, empty.exitCode, empty.stderr)
+	assert.Contains(t, empty.stdout, "local plugins (0)")
+	assert.Contains(t, empty.stdout, "(none;")
+}
+
+// copyPluginTreeForTest stages a plugin directory outside the runtime root with
+// rooted handles, so the fixture cannot escape either tree while copying.
+func copyPluginTreeForTest(t *testing.T, from, to string) {
+	t.Helper()
+	require.NoError(t, os.MkdirAll(to, 0o750)) // #nosec G301 -- fixture stages a caller-owned source layout.
+	sourceRoot, err := os.OpenRoot(from)
+	require.NoError(t, err)
+	defer func() { _ = sourceRoot.Close() }() //nolint:errcheck // fixture handle cleanup
+	stageRoot, err := os.OpenRoot(to)
+	require.NoError(t, err)
+	defer func() { _ = stageRoot.Close() }() //nolint:errcheck // fixture handle cleanup
+	walkErr := fs.WalkDir(sourceRoot.FS(), ".", func(relative string, entry fs.DirEntry, err error) error {
+		if err != nil {
+			return err
+		}
+		if relative == "." {
+			return nil
+		}
+		if entry.IsDir() {
+			return stageRoot.Mkdir(relative, 0o750)
+		}
+		data, readErr := sourceRoot.ReadFile(relative)
+		if readErr != nil {
+			return readErr
+		}
+		return stageRoot.WriteFile(relative, data, 0o600) // #nosec G306 -- fixture copy of its own scaffold.
+	})
+	require.NoError(t, walkErr)
+}
+
 func TestCLIInspectionTrustExecutionRedactionAndRemoteCache(t *testing.T) {
 	server := startSSHServer(t, serverOptions{})
 	home := t.TempDir()