diff --git a/cli/cmd/analyzer_inputs.go b/cli/cmd/analyzer_inputs.go
index 3290a995f..3ed3a4571 100644
--- a/cli/cmd/analyzer_inputs.go
+++ b/cli/cmd/analyzer_inputs.go
@@ -6,7 +6,7 @@ import (
 
 func addDataflowApproximations(b *AnalyzerBuilder, paths []string, analyzerJarPath, projectModelDir string) {
 	for _, approxPath := range paths {
-		absApproxPath := log.AbsPathOrExit(approxPath, "dataflow-approximations")
+		absApproxPath := log.AbsPathOrExit(approxPath, "java-models")
 		compiledPath, err := compileApproximationsIfNeeded(absApproxPath, analyzerJarPath, projectModelDir)
 		if err != nil {
 			out.Fatalf("Approximation compilation failed: %s", err)
@@ -17,6 +17,6 @@ func addDataflowApproximations(b *AnalyzerBuilder, paths []string, analyzerJarPa
 
 func addPassthroughApproximations(b *AnalyzerBuilder, paths []string) {
 	for _, passthrough := range paths {
-		b.AddPassthroughApproximations(log.AbsPathOrExit(passthrough, "passthrough-approximations"))
+		b.AddPassthroughApproximations(log.AbsPathOrExit(passthrough, "passthrough-models"))
 	}
 }
diff --git a/cli/cmd/compile.go b/cli/cmd/compile.go
index 3d33c8d33..8da1600dc 100644
--- a/cli/cmd/compile.go
+++ b/cli/cmd/compile.go
@@ -32,21 +32,33 @@ func currentCompileBuilder(projectPath string) *utils.OpentaintCommandBuilder {
 // dockerCompileSuggestion builds the "try Docker-based compilation" fallback hint.
 func dockerCompileSuggestion() output.Suggestion {
 	return output.Suggestion{
-		Description: dockerFallbackHintPrefix + "compilation:",
+		Description: "If the required Java is missing, set JAVA_HOME or compile in a container instead:",
 		Command:     utils.BuildCompileCommandWithDocker(currentCompileBuilder(""), ProjectPath, OutputProjectModelPath),
 	}
 }
 
 // compileCmd represents the compile command
 var compileCmd = &cobra.Command{
-	Use:   "compile project",
-	Short: "Compile your Java or Kotlin project",
+	Use:   "compile <project>",
+	Short: "Compile a project into a reusable project model",
 	Args:  cobra.ExactArgs(1), // require exactly one argument
-	Long: `This command takes a required path to the project, automatically detects Java/Kotlin build system, modules and dependencies and compiles project model.
+	Long: `Compile a project into a project model that you can scan many times. OpenTaint finds the build system, collects the modules and dependencies, and builds the project.
 
-Arguments:
-  project  - Path to a project to compile (required)
-`,
+The project argument is the path to the project root. It is required. Use --output to set the project model directory. This directory must not exist before the command runs.
+
+Later scans can use the model without a new build. This makes repeated scans fast.
+
+Before your first compile, run "opentaint pull" one time. To scan the model, use "opentaint scan --project-model".`,
+	Example: `  # Compile the current directory into a project model
+  opentaint compile . -o ./model
+
+  # Make sure the inputs are correct, without a build
+  opentaint compile . -o ./model --dry-run
+
+  # Recipe: compile one time, then scan with different settings
+  opentaint compile ./my-app -o ./model
+  opentaint scan --project-model ./model --ruleset ./team-rules -o team.sarif
+  opentaint scan --project-model ./model --severity error -o errors.sarif`,
 	Annotations: map[string]string{"PrintConfig": "true"},
 	Run: func(cmd *cobra.Command, args []string) {
 		ProjectPath = args[0]
@@ -72,25 +84,25 @@ Arguments:
 			sb.Line()
 		}
 		sb.FieldNode("Project", absProjectRoot).
-			FieldNode("Output project model", absOutputProjectModelPath).
+			FieldNode("Project model", absOutputProjectModelPath).
 			FieldNode("Autobuilder", utils.ArtifactVersionWithPath(globals.ArtifactByKind("autobuilder"))).
 			Render()
 
 		if DryRunCompile {
 			out.Blank()
 			failOnInvalidInputs(func() error { return validation.ValidateCompileInputs(absProjectRoot, absOutputProjectModelPath) })
-			runDryRun("Compilation")
+			runDryRun("compilation")
 			return
 		}
 
 		autobuilderJarPath, err := ensureAutobuilderAvailable()
 		if err != nil {
-			out.Fatalf("Native compile preparation failed: %s", err)
+			failf("Native compile preparation failed: %s", err)
 		}
 
 		compileJavaRunner := newAutobuilderJavaRunner()
 		if _, err := compileJavaRunner.EnsureJava(); err != nil {
-			out.Fatalf("Failed to resolve Java for compilation: %s", err)
+			failf("Failed to resolve Java for compilation: %s", err)
 		}
 
 		if err := out.RunWithSpinner("Compiling project model", func() error {
@@ -98,7 +110,8 @@ Arguments:
 		}); err == nil {
 			out.Blank()
 			printCompileSummary(absOutputProjectModelPath)
-			suggest("To scan project run", utils.BuildScanCommandFromCompile(projectRoot, absOutputProjectModelPath))
+			out.Successf("Compilation completed.")
+			suggest("To scan the compiled project model, run:", utils.BuildScanCommandFromCompile(projectRoot, absOutputProjectModelPath))
 		} else {
 			out.InteractiveBlank()
 			failWith(1, fmt.Sprintf("Native compile has failed: %s", err), dockerCompileSuggestion())
@@ -109,7 +122,7 @@ Arguments:
 func init() {
 	rootCmd.AddCommand(compileCmd)
 
-	compileCmd.Flags().StringVarP(&OutputProjectModelPath, "output", "o", "", `Path to the result project model`)
+	compileCmd.Flags().StringVarP(&OutputProjectModelPath, "output", "o", "", `Path to the project model directory to create (required, must not exist)`)
 	_ = compileCmd.MarkFlagRequired("output")
 	compileCmd.Flags().BoolVar(&DryRunCompile, "dry-run", false, "Validate inputs and show what would run without compiling")
 	compileCmd.Flags().StringVar(&CompileLogFile, "log-file", "", "Path to the log file (default: <cache-dir>/logs/<timestamp>.log)")
diff --git a/cli/cmd/compile_approximations.go b/cli/cmd/compile_approximations.go
index ed61db7b1..651d5e3c1 100644
--- a/cli/cmd/compile_approximations.go
+++ b/cli/cmd/compile_approximations.go
@@ -18,7 +18,7 @@ import (
 // bundles approximation support sources (OpentaintNdUtil, ArgumentTypeContext).
 const approxClassesJarPrefix = "opentaint-dataflow-approximations/"
 
-// compileApproximationsIfNeeded checks whether a --dataflow-approximations directory
+// compileApproximationsIfNeeded checks whether a --java-models directory
 // contains .java source files. If so, it compiles them using javac (with the
 // analyzer JAR + project dependencies on the classpath) and returns the path to
 // the compiled .class output directory. If the directory already contains only
diff --git a/cli/cmd/dry_run.go b/cli/cmd/dry_run.go
index e0c2f7276..914db0609 100644
--- a/cli/cmd/dry_run.go
+++ b/cli/cmd/dry_run.go
@@ -1,6 +1,9 @@
 package cmd
 
-import "fmt"
+import (
+	"os"
+	"strings"
+)
 
 func failOnInvalidInputs(validate func() error) {
 	if err := validate(); err != nil {
@@ -8,6 +11,46 @@ func failOnInvalidInputs(validate func() error) {
 	}
 }
 
+// runDryRun prints the standard dry-run tail: a status line naming the skipped
+// action, then a suggestion to repeat the same invocation without --dry-run.
 func runDryRun(skippedAction string) {
-	out.Print(fmt.Sprintf("Dry run mode. Inputs validated. %s skipped.", skippedAction))
+	out.Printf("Dry run complete. Inputs validated, %s skipped.", skippedAction)
+	suggest("To run for real, run:", rerunWithoutDryRun())
+}
+
+// rerunWithoutDryRun reconstructs the current invocation with the --dry-run
+// flag removed, so the dry-run tail can suggest the real run verbatim. It works
+// from os.Args, which keeps it correct for every command that shares this tail
+// (scan, compile, project, test rule reachability).
+func rerunWithoutDryRun() string {
+	args := []string{"opentaint"}
+	for _, arg := range os.Args[1:] {
+		if arg == "--dry-run" || strings.HasPrefix(arg, "--dry-run=") {
+			continue
+		}
+		args = append(args, shellQuote(arg))
+	}
+	return strings.Join(args, " ")
+}
+
+// shellQuote single-quotes an argument that would break when copy-pasted into
+// a shell. Only arguments made of known-inert characters pass through
+// unchanged, so globs, variables, and separators survive the round trip.
+func shellQuote(arg string) string {
+	if arg != "" && !strings.ContainsFunc(arg, shellUnsafe) {
+		return arg
+	}
+	return "'" + strings.ReplaceAll(arg, "'", `'\''`) + "'"
+}
+
+// shellUnsafe reports whether a character can change the meaning of an
+// unquoted shell word. The safe set mirrors Python's shlex.quote.
+func shellUnsafe(r rune) bool {
+	switch {
+	case r >= 'a' && r <= 'z', r >= 'A' && r <= 'Z', r >= '0' && r <= '9':
+		return false
+	case strings.ContainsRune("_@%+=:,./-", r):
+		return false
+	}
+	return true
 }
diff --git a/cli/cmd/exit_codes.go b/cli/cmd/exit_codes.go
new file mode 100644
index 000000000..5de9a0912
--- /dev/null
+++ b/cli/cmd/exit_codes.go
@@ -0,0 +1,36 @@
+package cmd
+
+import (
+	"fmt"
+
+	"github.com/seqra/opentaint/internal/analyzer"
+)
+
+// analyzerExitCodeRows renders the forwarded analyzer exit codes (252-255) as
+// help rows. The row text is generated from analyzer.ExitMessage so the
+// documented codes can never drift from the runtime failure messages.
+func analyzerExitCodeRows() string {
+	rows := ""
+	for _, code := range []int{analyzer.ExitException, analyzer.ExitOOM, analyzer.ExitTimeout, analyzer.ExitConfigError} {
+		rows += fmt.Sprintf("\n  %-3d  %s", code, analyzer.ExitMessage(code))
+	}
+	return rows
+}
+
+// scanExitCodesHelp renders the exit-codes block for commands that forward
+// analyzer exit codes but have no test-failure code (scan, test rule
+// reachability).
+func scanExitCodesHelp(completedLine string) string {
+	return `Exit codes:
+  0    ` + completedLine + `
+  1    General failure (configuration or infrastructure error)` + analyzerExitCodeRows()
+}
+
+// testExitCodesHelp renders the exit-codes block for the test-run commands,
+// which add exit code 2 for sample failures.
+func testExitCodesHelp(passedLine string) string {
+	return `Exit codes:
+  0    ` + passedLine + `
+  1    General failure (configuration or infrastructure error)
+  2    One or more tests failed (false negatives, false positives, or skipped samples)` + analyzerExitCodeRows()
+}
diff --git a/cli/cmd/flag_alias.go b/cli/cmd/flag_alias.go
new file mode 100644
index 000000000..30d86fe23
--- /dev/null
+++ b/cli/cmd/flag_alias.go
@@ -0,0 +1,42 @@
+package cmd
+
+import (
+	"strings"
+
+	"github.com/spf13/pflag"
+)
+
+// renamedStringArray backs a renamed flag and its deprecated alias. pflag's
+// stringArrayValue replaces the bound slice on each flag's own first value, so
+// two stock flags bound to one slice silently drop whatever the other spelling
+// already collected. Appending unconditionally keeps the values of both
+// spellings, in command-line order.
+type renamedStringArray struct {
+	target *[]string
+}
+
+func (v renamedStringArray) String() string {
+	if len(*v.target) == 0 {
+		return ""
+	}
+	return "[" + strings.Join(*v.target, ",") + "]"
+}
+
+func (v renamedStringArray) Set(s string) error {
+	*v.target = append(*v.target, s)
+	return nil
+}
+
+func (v renamedStringArray) Type() string {
+	return "stringArray"
+}
+
+// addRenamedStringArrayFlag registers a flag under its new name and its
+// deprecated old spelling, both accumulating into the same slice.
+func addRenamedStringArrayFlag(fs *pflag.FlagSet, target *[]string, name, deprecated, usage string) {
+	fs.Var(renamedStringArray{target}, name, usage)
+	fs.Var(renamedStringArray{target}, deprecated, usage)
+	if err := fs.MarkDeprecated(deprecated, "use --"+name); err != nil {
+		panic(err)
+	}
+}
diff --git a/cli/cmd/flag_alias_test.go b/cli/cmd/flag_alias_test.go
new file mode 100644
index 000000000..f0220ad99
--- /dev/null
+++ b/cli/cmd/flag_alias_test.go
@@ -0,0 +1,56 @@
+package cmd
+
+import (
+	"reflect"
+	"testing"
+
+	"github.com/spf13/pflag"
+)
+
+func parseRenamed(t *testing.T, args []string) []string {
+	t.Helper()
+	var target []string
+	fs := pflag.NewFlagSet("test", pflag.ContinueOnError)
+	addRenamedStringArrayFlag(fs, &target, "passthrough-models", "passthrough-approximations", "usage")
+	if err := fs.Parse(args); err != nil {
+		t.Fatalf("parse %v: %v", args, err)
+	}
+	return target
+}
+
+func TestRenamedFlagAccumulatesAcrossBothSpellings(t *testing.T) {
+	cases := [][]string{
+		{"--passthrough-models", "a.yaml", "--passthrough-approximations", "b.yaml"},
+		{"--passthrough-approximations", "a.yaml", "--passthrough-models", "b.yaml"},
+	}
+	for _, args := range cases {
+		got := parseRenamed(t, args)
+		if len(got) != 2 {
+			t.Errorf("args %v: got %v, want both values kept", args, got)
+		}
+	}
+}
+
+func TestRenamedFlagKeepsRepeatsInOrder(t *testing.T) {
+	got := parseRenamed(t, []string{
+		"--passthrough-models", "a.yaml",
+		"--passthrough-models", "b.yaml",
+		"--passthrough-approximations", "c.yaml",
+	})
+	if want := []string{"a.yaml", "b.yaml", "c.yaml"}; !reflect.DeepEqual(got, want) {
+		t.Errorf("got %v, want %v", got, want)
+	}
+}
+
+func TestRenamedFlagAliasIsDeprecatedAndHidden(t *testing.T) {
+	var target []string
+	fs := pflag.NewFlagSet("test", pflag.ContinueOnError)
+	addRenamedStringArrayFlag(fs, &target, "passthrough-models", "passthrough-approximations", "usage")
+	alias := fs.Lookup("passthrough-approximations")
+	if alias == nil || alias.Deprecated == "" {
+		t.Fatal("alias must be registered and marked deprecated")
+	}
+	if fs.Lookup("passthrough-models").Deprecated != "" {
+		t.Error("the new spelling must not be deprecated")
+	}
+}
diff --git a/cli/cmd/health.go b/cli/cmd/health.go
index 0954bbbf4..4878de84d 100644
--- a/cli/cmd/health.go
+++ b/cli/cmd/health.go
@@ -27,15 +27,26 @@ type healthComponent struct {
 
 var healthCmd = &cobra.Command{
 	Use:   "health",
-	Short: "Show resolved dependency paths",
-	Long: `Show the on-disk paths OpenTaint uses for the autobuilder, analyzer,
-built-in rules, and Java runtime.
+	Short: "Show dependency paths and report missing components",
+	Long: `Show the paths of the components on this computer. The components are the autobuilder, the analyzer, the built-in rules, and the Java runtime. The command shows if each component is present.
 
-Use --autobuilder, --analyzer, --rules, or --runtime to select components. When
-exactly one component is selected, only its path is printed. The command does
-not download artifacts except built-in rules, which are fetched on demand.
+To select components, use --autobuilder, --analyzer, --rules, or --runtime. With no flag, the command shows all four components. If you select exactly one component, only its path is printed. This output is good for scripts.
 
-The exit code is non-zero when any selected component is missing.`,
+Only the built-in rules are downloaded when they are missing. No other component is downloaded.
+
+If a selected component is missing, the command exits with a code that is not zero. To download the missing components, run "opentaint pull".`,
+	Example: `  # Show all components and their paths
+  opentaint health
+
+  # Print only the analyzer JAR path, for a script
+  opentaint health --analyzer
+
+  # Make sure the Java runtime is present
+  opentaint health --runtime
+
+  # Recipe: use the built-in rules path in a script
+  RULES=$(opentaint health --rules)
+  opentaint scan . --ruleset "$RULES" --ruleset ./extra-rules -o report.sarif`,
 	Args: cobra.NoArgs,
 	RunE: func(cmd *cobra.Command, args []string) error {
 		return runHealth()
@@ -105,6 +116,7 @@ func runHealth() error {
 	}
 	sb.Render()
 	if len(missing) > 0 {
+		out.Suggest("To download the missing components, run:", "opentaint pull")
 		return fmt.Errorf("missing components: %s", strings.Join(missing, ", "))
 	}
 	return nil
diff --git a/cli/cmd/project.go b/cli/cmd/project.go
index 60e31d5d2..ed7236c3f 100644
--- a/cli/cmd/project.go
+++ b/cli/cmd/project.go
@@ -181,7 +181,8 @@ func (c *JavaAutobuilderConfig) printProjectSummary(config *project.Config) erro
 	projectYamlPath := filepath.Join(c.outputDir, "project.yaml")
 
 	c.logProjectSummary(projectYamlPath, config)
-	suggest("To scan project run", utils.BuildScanCommandFromCompile(c.outputDir, c.outputDir))
+	out.Successf("Project model generated.")
+	suggest("To scan the generated model, run:", utils.BuildScanCommandFromCompile(c.outputDir, c.outputDir))
 	return nil
 }
 
@@ -218,16 +219,28 @@ var (
 
 var projectCmd = &cobra.Command{
 	Use:   "project",
-	Short: "Create a project model directory containing a project.yaml configuration from precompiled JARs or classes",
-	Long: `Create a project model directory containing a project.yaml configuration from precompiled JARs or classes.
+	Short: "Create a project model from precompiled JARs or classes",
+	Long: `Create a project model from JARs or classes that are already compiled. No build occurs. OpenTaint examines the classpath, finds the modules and dependencies, and writes a project.yaml file.
 
-This command generates a project model, automatically detecting dependencies and project structure.
-Additional packages have to be specified to enhance the generated configuration.
+Use this command when you have compiled artifacts but no build. To build a model from sources, use "opentaint compile".
 
-Examples:
-  # Classpath analysis
-  opentaint project --output ./project-model --source-root /path/to/source \
-    --classpath /path/to/app.jar --package com.example`,
+All inputs are flags. Give the source path with --source-root. Give the compiled classes or JARs with --classpath. Give the packages to include with --package. Add more JAR files with --dependency.
+
+Use --output to set the project model directory. This directory must not exist before the command runs.
+
+Before the first run, run "opentaint pull" one time. To scan the model, use "opentaint scan --project-model".`,
+	Example: `  # Create a project model from a compiled JAR
+  opentaint project --source-root ./src --classpath ./app.jar --package com.example -o ./model
+
+  # Add more dependency JARs to the classpath
+  opentaint project --source-root ./src --classpath ./app.jar --dependency ./lib.jar --package com.example -o ./model
+
+  # Make sure the inputs are correct, without a model
+  opentaint project --source-root ./src --classpath ./app.jar --package com.example -o ./model --dry-run
+
+  # Recipe: scan a vendor JAR that you cannot build
+  opentaint project --source-root ./src --classpath ./vendor-app.jar --package com.vendor -o ./model
+  opentaint scan --project-model ./model -o report.sarif`,
 	Run: func(cmd *cobra.Command, args []string) {
 		config := NewJavaAutobuilder().
 			WithOutputDir(OutputDir).
@@ -269,12 +282,12 @@ Examples:
 
 		if DryRunProject {
 			failOnInvalidInputs(config.validate)
-			runDryRun("Project generation")
+			runDryRun("project-model generation")
 			return
 		}
 
 		if err := config.Execute(); err != nil {
-			out.Fatalf("Failed to generate project configuration: %s", err)
+			failf("Failed to generate project configuration: %s", err)
 		}
 	},
 }
@@ -282,15 +295,15 @@ Examples:
 func init() {
 	rootCmd.AddCommand(projectCmd)
 
-	projectCmd.Flags().StringVarP(&OutputDir, "output", "o", "", "Output directory for project.yaml")
+	projectCmd.Flags().StringVarP(&OutputDir, "output", "o", "", "Directory to write the generated project model (required, must not exist)")
 	_ = projectCmd.MarkFlagRequired("output")
-	projectCmd.Flags().StringVar(&SourceRoot, "source-root", "", "Source root directory")
+	projectCmd.Flags().StringVar(&SourceRoot, "source-root", "", "Path to the project source root")
 	_ = projectCmd.MarkFlagRequired("source-root")
-	projectCmd.Flags().StringArrayVar(&Dependencies, "dependency", []string{}, "Project dependencies (JAR files)")
-	projectCmd.Flags().StringArrayVar(&Packages, "package", []string{}, "Project packages")
+	projectCmd.Flags().StringArrayVar(&Dependencies, "dependency", []string{}, "Additional dependency JAR file on the compile classpath (repeatable)")
+	projectCmd.Flags().StringArrayVar(&Packages, "package", []string{}, "Package to include in the generated model (repeatable)")
 	_ = projectCmd.MarkFlagRequired("package")
-	projectCmd.Flags().StringArrayVar(&Classpaths, "classpath", []string{}, "Classpath entries (classes or JAR files)")
+	projectCmd.Flags().StringArrayVar(&Classpaths, "classpath", []string{}, "Classpath entry: a compiled classes directory or a JAR file (repeatable)")
 	_ = projectCmd.MarkFlagRequired("classpath")
-	projectCmd.Flags().BoolVar(&DryRunProject, "dry-run", false, "Validate inputs and show what would run without generating project model")
+	projectCmd.Flags().BoolVar(&DryRunProject, "dry-run", false, "Validate inputs and show what would run without generating the project model")
 	projectCmd.Flags().StringVar(&ProjectLogFile, "log-file", "", "Path to the log file (default: <cache-dir>/logs/<timestamp>.log)")
 }
diff --git a/cli/cmd/prune.go b/cli/cmd/prune.go
index a4da4e6b8..aab398e19 100644
--- a/cli/cmd/prune.go
+++ b/cli/cmd/prune.go
@@ -57,24 +57,27 @@ func resolveCategories() (utils.PruneCategory, error) {
 
 var pruneCmd = &cobra.Command{
 	Use:   "prune",
-	Short: "Remove stale downloaded artifacts from ~/.opentaint",
-	Long: `Remove stale downloaded artifacts from the local cache (~/.opentaint).
-
-Identifies artifacts that are no longer needed:
-- Old versions of analyzer JARs, autobuilder JARs, and rules
-- Downloaded JDK/JRE versions that don't match the current version
-- Cached project models
-
-Use category flags to prune selectively:
-  --artifacts   Stale analyzer and autobuilder JARs
-  --rules       Stale rules directories
-  --jdk         Old JDK/JRE versions
-  --models      Cached project models
-  --logs        Project log files
-  --install     Install-tier lib and JRE artifacts (requires re-download)
-
-Without category flags, prunes: artifacts + rules + jdk + models.
-With --all: prunes everything including logs and install-tier.`,
+	Short: "Remove old downloaded artifacts from the cache",
+	Long: `Remove old downloaded artifacts from the local cache (~/.opentaint). The command removes analyzer and autobuilder JARs that a newer version replaced, old rules, JDK and JRE versions that do not match the configuration, and cached project models.
+
+To select categories, use --artifacts, --rules, --jdk, --models, --logs, or --install. With no category flag, the command removes artifacts, rules, jdk, and models. The --all flag removes everything, with logs and install-tier artifacts included. Do not give --all together with a category flag.
+
+To see the deletions without a removal, use --dry-run. To skip the confirmation prompt, use --yes. To download the toolchain again, run "opentaint pull".`,
+	Example: `  # Remove the default categories, with a confirmation prompt
+  opentaint prune
+
+  # Remove only the old JDK and JRE versions
+  opentaint prune --jdk
+
+  # Remove everything, with logs and install-tier artifacts included
+  opentaint prune --all
+
+  # See what the command would delete, without a deletion
+  opentaint prune --dry-run
+
+  # Recipe: get disk space back, keep the current toolchain
+  opentaint prune --dry-run
+  opentaint prune --yes`,
 	Run: func(cmd *cobra.Command, args []string) {
 		categories, err := resolveCategories()
 		if err != nil {
@@ -84,23 +87,23 @@ With --all: prunes everything including logs and install-tier.`,
 		// Acquire global prune lock
 		pruneLockPath, err := utils.PruneLockPath()
 		if err != nil {
-			out.Fatalf("Failed to resolve prune lock path: %s", err)
+			failf("Failed to resolve prune lock path: %s", err)
 		}
 		pruneLock, err := utils.TryLockExclusive(pruneLockPath, utils.LockMeta{
 			PID:     os.Getpid(),
 			Command: "prune",
 		})
 		if err == utils.ErrLocked {
-			out.Fatal("Another prune is already running")
+			failWith(1, "Another prune is already running")
 		}
 		if err != nil {
-			out.Fatalf("Failed to acquire prune lock: %s", err)
+			failf("Failed to acquire prune lock: %s", err)
 		}
 		defer pruneLock.Unlock()
 
 		result, err := utils.ScanForStaleArtifacts(categories)
 		if err != nil {
-			out.Fatalf("Failed to scan for stale artifacts: %s", err)
+			failf("Failed to scan for stale artifacts: %s", err)
 		}
 
 		// Display skipped projects
@@ -130,22 +133,27 @@ With --all: prunes everything including logs and install-tier.`,
 			Render()
 
 		if pruneDryRun {
-			out.Print("Dry run mode. No files were deleted.")
+			out.Print("Dry run complete. No files were deleted.")
+			suggest("To delete these artifacts, run:", withFlag(rerunWithoutDryRun(), "--yes"))
 			return
 		}
 
 		if !pruneYes {
 			if !out.Confirm("Delete these artifacts?", false) {
 				out.Print("Prune cancelled.")
+				suggest("To prune without confirming, run:", withFlag(rerunWithoutDryRun(), "--yes"))
 				return
 			}
 		}
 
 		if err := utils.DeleteArtifacts(result.Stale); err != nil {
-			out.Fatalf("Failed to delete artifacts: %s", err)
+			failf("Failed to delete artifacts: %s", err)
 		}
 
 		out.Successf("Pruned %d items, freed %s", result.TotalCount, output.FormatSize(result.TotalSize))
+		if pruneInstall || pruneAll {
+			suggest("To restore the removed components, run:", "opentaint pull")
+		}
 	},
 }
 
diff --git a/cli/cmd/pull.go b/cli/cmd/pull.go
index ff95db860..503ab2442 100644
--- a/cli/cmd/pull.go
+++ b/cli/cmd/pull.go
@@ -17,15 +17,21 @@ import (
 
 var pullCmd = &cobra.Command{
 	Use:   "pull",
-	Short: "Download autobuilder, analyzer binaries, rules and Java runtime",
-	Long: `Download all necessary binaries and assets:
-- OpenTaint autobuilder JAR
-- OpenTaint analyzer JAR
-- OpenTaint rules archive
-- Java runtime (Temurin JRE)
-
-This prepares the environment with all required dependencies for offline analysis.
-When bundled artifacts are present (from a release archive), they will be used directly.`,
+	Short: "Download the analysis toolchain and Java runtime",
+	Long: `Download the toolchain into the local cache. The toolchain contains the analyzer, the autobuilder, the built-in rules, and a Java runtime. After the download, OpenTaint can build and scan projects without network access.
+
+If a release archive supplied bundled artifacts, OpenTaint uses them. They are not downloaded again.
+
+Run "opentaint pull" one time before your first scan. To remove old downloads, use "opentaint prune".`,
+	Example: `  # Download the toolchain before the first scan
+  opentaint pull
+
+  # Download a different Java runtime version
+  opentaint pull --java-version 17
+
+  # Recipe: prepare a machine that will have no network access
+  opentaint pull
+  opentaint health`,
 	Run: func(cmd *cobra.Command, args []string) {
 		out.Section("OpenTaint Pull").
 			Field("Autobuilder", globals.Config.Autobuilder.Version).
@@ -40,7 +46,7 @@ When bundled artifacts are present (from a release archive), they will be used d
 		installCurrent := utils.IsInstallCurrent()
 		if !installCurrent {
 			if err := utils.CleanInstallDir(); err != nil {
-				out.Fatalf("Failed to clean install directory: %s", err)
+				failf("Failed to clean install directory: %s", err)
 			}
 		}
 
@@ -50,26 +56,29 @@ When bundled artifacts are present (from a release archive), they will be used d
 		for _, spec := range artifacts {
 			node, err := downloadArtifact(spec, installNextToBinary, installCurrent)
 			if err != nil {
-				out.Fatalf("Failed to download %s: %s", spec.Kind(), err)
+				failf("Failed to download %s: %s", spec.Kind(), err)
 			}
 			summaryNodes = append(summaryNodes, node)
 		}
 
 		javaNode, err := downloadJava(installNextToBinary, installCurrent)
 		if err != nil {
-			out.Fatalf("Failed to download Java: %s", err)
+			failf("Failed to download Java: %s", err)
 		}
 		summaryNodes = append(summaryNodes, javaNode)
 
 		// Write version marker after all downloads succeed
 		if err := utils.WriteInstallVersionMarker(); err != nil {
-			out.Fatalf("Failed to write install version marker: %s", err)
+			failf("Failed to write install version marker: %s", err)
 		}
 
 		out.Blank()
 		out.Section("Pull Summary").
 			Child(summaryNodes...).
 			Render()
+
+		out.Successf("Pull completed.")
+		suggest("To scan your project, run:", "opentaint scan .")
 	},
 }
 
diff --git a/cli/cmd/rerun_test.go b/cli/cmd/rerun_test.go
new file mode 100644
index 000000000..2d2291f24
--- /dev/null
+++ b/cli/cmd/rerun_test.go
@@ -0,0 +1,143 @@
+package cmd
+
+import (
+	"os"
+	"testing"
+
+	"github.com/seqra/opentaint/internal/analyzer"
+)
+
+func withOSArgs(t *testing.T, args []string) {
+	t.Helper()
+	saved := os.Args
+	os.Args = args
+	t.Cleanup(func() { os.Args = saved })
+}
+
+func TestRerunWithoutDryRunStripsFlag(t *testing.T) {
+	withOSArgs(t, []string{"/usr/bin/opentaint", "scan", "./proj", "--dry-run", "--color", "never"})
+	got := rerunWithoutDryRun()
+	want := "opentaint scan ./proj --color never"
+	if got != want {
+		t.Fatalf("rerunWithoutDryRun() = %q, want %q", got, want)
+	}
+}
+
+func TestRerunWithoutDryRunStripsEqualsForm(t *testing.T) {
+	withOSArgs(t, []string{"opentaint", "compile", ".", "--dry-run=true", "-o", "./model"})
+	got := rerunWithoutDryRun()
+	want := "opentaint compile . -o ./model"
+	if got != want {
+		t.Fatalf("rerunWithoutDryRun() = %q, want %q", got, want)
+	}
+}
+
+func TestRerunWithoutDryRunQuotesSpaces(t *testing.T) {
+	withOSArgs(t, []string{"opentaint", "scan", "my project", "--dry-run"})
+	got := rerunWithoutDryRun()
+	want := "opentaint scan 'my project'"
+	if got != want {
+		t.Fatalf("rerunWithoutDryRun() = %q, want %q", got, want)
+	}
+}
+
+func TestWithFlag(t *testing.T) {
+	if got := withFlag("opentaint prune", "--yes"); got != "opentaint prune --yes" {
+		t.Fatalf("withFlag append = %q", got)
+	}
+	if got := withFlag("opentaint prune --yes", "--yes"); got != "opentaint prune --yes" {
+		t.Fatalf("withFlag no-op = %q", got)
+	}
+}
+
+func TestRerunReplacingFlagValueForm(t *testing.T) {
+	withOSArgs(t, []string{"opentaint", "scan", ".", "--max-memory", "8G"})
+	got := rerunReplacingFlag("16G", "--max-memory")
+	want := "opentaint scan . --max-memory 16G"
+	if got != want {
+		t.Fatalf("rerunReplacingFlag() = %q, want %q", got, want)
+	}
+}
+
+func TestRerunReplacingFlagAliasAndEqualsForm(t *testing.T) {
+	withOSArgs(t, []string{"opentaint", "scan", ".", "-t", "15m", "--timeout=10m"})
+	got := rerunReplacingFlag("30m0s", "--timeout", "-t")
+	want := "opentaint scan . --timeout 30m0s"
+	if got != want {
+		t.Fatalf("rerunReplacingFlag() = %q, want %q", got, want)
+	}
+}
+
+func TestRerunReplacingFlagAppendsWhenAbsent(t *testing.T) {
+	withOSArgs(t, []string{"opentaint", "test", "rule", "run", "./model"})
+	got := rerunReplacingFlag("16G", "--max-memory")
+	want := "opentaint test rule run ./model --max-memory 16G"
+	if got != want {
+		t.Fatalf("rerunReplacingFlag() = %q, want %q", got, want)
+	}
+}
+
+func TestDoubleMemory(t *testing.T) {
+	cases := map[string]string{
+		"8G":       "16G",
+		"1024m":    "2048m",
+		"83886080": "167772160",
+		"weird":    "16G",
+		"":         "16G",
+	}
+	for in, want := range cases {
+		if got := doubleMemory(in); got != want {
+			t.Fatalf("doubleMemory(%q) = %q, want %q", in, got, want)
+		}
+	}
+}
+
+func TestRetrySuggestion(t *testing.T) {
+	withOSArgs(t, []string{"opentaint", "scan", ".", "--max-memory", "8G"})
+
+	oom, ok := retrySuggestion(analyzer.ExitOOM, 900e9, "8G")
+	if !ok || oom.Description != "To retry with more memory, run:" || oom.Command != "opentaint scan . --max-memory 16G" {
+		t.Fatalf("OOM retry = %+v ok=%t", oom, ok)
+	}
+
+	timeoutRetry, ok := retrySuggestion(analyzer.ExitTimeout, 900e9, "8G")
+	if !ok || timeoutRetry.Description != "To retry with a longer timeout, run:" {
+		t.Fatalf("timeout retry = %+v ok=%t", timeoutRetry, ok)
+	}
+	want := "opentaint scan . --max-memory 8G --timeout 30m0s"
+	if timeoutRetry.Command != want {
+		t.Fatalf("timeout retry command = %q, want %q", timeoutRetry.Command, want)
+	}
+
+	if _, ok := retrySuggestion(analyzer.ExitException, 900e9, "8G"); ok {
+		t.Fatal("exception exit code must not produce a retry suggestion")
+	}
+}
+
+func TestShellQuoteLeavesInertArgumentsAlone(t *testing.T) {
+	for _, arg := range []string{"opentaint", "report.sarif", "--max-memory=8G", "path/to/file.yaml", "a-b_c.d,e:f@g%h+i"} {
+		if got := shellQuote(arg); got != arg {
+			t.Errorf("shellQuote(%q) = %q, want unchanged", arg, got)
+		}
+	}
+}
+
+func TestShellQuoteQuotesShellMetacharacters(t *testing.T) {
+	cases := map[string]string{
+		"demo-rule-*":      "'demo-rule-*'",
+		"java/security/**": "'java/security/**'",
+		"$HOME":            "'$HOME'",
+		"a;b":              "'a;b'",
+		"a|b":              "'a|b'",
+		"a b":              "'a b'",
+		"it's":             `'it'\''s'`,
+		"":                 "''",
+		"a>b":              "'a>b'",
+		"`cmd`":            "'`cmd`'",
+	}
+	for in, want := range cases {
+		if got := shellQuote(in); got != want {
+			t.Errorf("shellQuote(%q) = %q, want %q", in, got, want)
+		}
+	}
+}
diff --git a/cli/cmd/root.go b/cli/cmd/root.go
index 214028ec8..e457002da 100644
--- a/cli/cmd/root.go
+++ b/cli/cmd/root.go
@@ -33,9 +33,14 @@ var updateHintCh = make(chan string, 1)
 
 // rootCmd represents the base command when called without any subcommands
 var rootCmd = &cobra.Command{
-	Use:           "opentaint",
-	Short:         "OpenTaint Analyzer",
-	Long:          `OpenTaint is a CLI tool that analyzes Java and Kotlin projects to find vulnerabilities`,
+	Use:   "opentaint",
+	Short: "Find vulnerabilities in source code with taint analysis",
+	Long: `OpenTaint finds vulnerabilities in your code. It follows tainted data from untrusted sources to dangerous sinks. Java and Kotlin projects are supported.
+
+Quick start:
+  1. Run "opentaint pull" one time. This downloads the toolchain.
+  2. Run "opentaint scan ." to scan a project.
+  3. Run "opentaint summary <report> --show-findings" to read the findings.`,
 	SilenceErrors: true,
 	SilenceUsage:  true,
 
diff --git a/cli/cmd/scan.go b/cli/cmd/scan.go
index 9750dcdeb..7b7af94af 100644
--- a/cli/cmd/scan.go
+++ b/cli/cmd/scan.go
@@ -4,6 +4,7 @@ import (
 	"fmt"
 	"os"
 	"path/filepath"
+	"strings"
 	"time"
 
 	"github.com/seqra/opentaint/internal/analyzer"
@@ -72,15 +73,40 @@ func (p scanPlan) title() string {
 // scanCmd represents the scan command
 var scanCmd = &cobra.Command{
 	Use:   "scan [source-path]",
-	Short: "Scan your Java or Kotlin project",
+	Short: "Scan a project for vulnerabilities",
 	Args:  cobra.MaximumNArgs(1),
-	Long: `This command automatically detects Java/Kotlin build systems, builds the project, and analyzes it
+	Long: `Scan a project and find vulnerabilities. OpenTaint finds the build system, builds the project, and does a taint analysis.
 
-Arguments:
-  source-path  - Path to the project sources (default: current directory)
+The source-path argument is the project root. It is optional. The default is the current directory. To scan a project model that is already compiled, use --project-model. Do not give source-path and --project-model together.
 
-Use --project-model to scan a pre-compiled project model instead of compiling from sources.
-`,
+OpenTaint writes the findings to a SARIF report. Use --output to set the report path. If --output is not set, the report goes into the project model directory. A summary is shown when the scan completes.
+
+Before your first scan, run "opentaint pull" one time. To read a report again later, use "opentaint summary".
+
+` + scanExitCodesHelp("Scan completed"),
+	Example: `  # Scan the current directory with the built-in rules
+  opentaint scan .
+
+  # Scan a project and write the report to a known path
+  opentaint scan ./my-app -o report.sarif
+
+  # Scan a project model that is already compiled
+  opentaint scan --project-model ./model -o report.sarif
+
+  # Use your own rules and show only errors
+  opentaint scan . --ruleset ./rules --severity error -o report.sarif
+
+  # Give a large project more time and memory
+  opentaint scan . --timeout 30m --max-memory 16G -o report.sarif
+
+  # Recipe: first scan on a new machine
+  opentaint pull
+  opentaint scan . -o report.sarif
+  opentaint summary report.sarif --show-findings
+
+  # Recipe: build one time, then scan many times
+  opentaint compile ./my-app -o ./model
+  opentaint scan --project-model ./model -o report.sarif`,
 	Annotations: map[string]string{"PrintConfig": "true"},
 	Run: func(cmd *cobra.Command, args []string) {
 		if scanFlags.DebugRunAnalysisOnSelectedEntryPoints != "" {
@@ -93,7 +119,7 @@ Use --project-model to scan a pre-compiled project model instead of compiling fr
 func prepareScanConfig(cfg ScanConfig, args []string) ScanConfig {
 	if len(args) > 0 && cfg.ProjectModelPath != "" {
 		out.Error("Cannot use both a source path argument and --project-model flag")
-		suggest("Use either a source path or --project-model",
+		suggest("Use either a source path or --project-model:",
 			utils.NewScanCommand("<source-path>").Build()+"\n  "+utils.NewScanCommand("").WithProjectModel("<model-path>").Build())
 		os.Exit(1)
 	}
@@ -122,28 +148,28 @@ func addEntryPointsFlag(cmd *cobra.Command) {
 }
 
 func addRuleIDFlag(cmd *cobra.Command) {
-	cmd.Flags().StringArrayVar(&scanFlags.RuleID, "rule-id", nil, "Filter active rules by ID (repeatable)")
+	cmd.Flags().StringArrayVar(&scanFlags.RuleID, "rule-id", nil, "Run only rules with this ID (repeatable)")
 }
 
 func addScanFlags(cmd *cobra.Command) {
-	cmd.Flags().DurationVarP(&globals.Config.Scan.Timeout, "timeout", "t", 900*time.Second, "Timeout for analysis")
+	cmd.Flags().DurationVarP(&globals.Config.Scan.Timeout, "timeout", "t", 900*time.Second, "Maximum wall-clock time for analysis (e.g. 30m, 1h)")
 
-	cmd.Flags().StringArrayVar(&scanFlags.Ruleset, "ruleset", []string{"builtin"}, "YAML rules file, directory of YAML rules files ending in .yml or .yaml, or `builtin` to scan with built-in rules")
+	cmd.Flags().StringArrayVar(&scanFlags.Ruleset, "ruleset", []string{"builtin"}, "Rules to run: a YAML file, a directory of .yml or .yaml files, or builtin for the built-in rules (repeatable)")
 
-	cmd.Flags().BoolVar(&scanFlags.SemgrepCompatibilitySarif, "semgrep-compatibility-sarif", true, "Use Semgrep compatible ruleId")
-	cmd.Flags().StringVarP(&scanFlags.SarifReportPath, "output", "o", "", "Path to the SARIF-report output file")
+	cmd.Flags().BoolVar(&scanFlags.SemgrepCompatibilitySarif, "semgrep-compatibility-sarif", true, "Use Semgrep-compatible rule IDs in the SARIF report")
+	cmd.Flags().StringVarP(&scanFlags.SarifReportPath, "output", "o", "", "Path to write the SARIF report")
 
-	cmd.Flags().StringArrayVar(&scanFlags.Severity, "severity", []string{"warning", "error"}, "Report findings only from rules matching the supplied severity level. By default only warning and error rules are run (note, warning, error)")
-	cmd.Flags().StringVar(&globals.Config.Scan.MaxMemory, "max-memory", "8G", "Maximum memory for the analyzer (e.g., 1024m, 8G, 81920k, 83886080)")
+	cmd.Flags().StringArrayVar(&scanFlags.Severity, "severity", []string{"warning", "error"}, "Run only rules at these severity levels: note, warning, error (repeatable)")
+	cmd.Flags().StringVar(&globals.Config.Scan.MaxMemory, "max-memory", "8G", "Maximum analyzer heap size (e.g. 8G, 1024m)")
 	cmd.Flags().Int64Var(&globals.Config.Scan.CodeFlowLimit, "code-flow-limit", 0, "Maximum number of code flows to include in the report (0 = unlimited)")
 	cmd.Flags().BoolVar(&scanFlags.DryRun, "dry-run", false, "Validate inputs and show what would run without compiling or scanning")
 	cmd.Flags().BoolVar(&scanFlags.Recompile, "recompile", false, "Force recompilation even if a cached project model exists")
 	cmd.Flags().StringVar(&scanFlags.ProjectModelPath, "project-model", "", "Path to a pre-compiled project model (skips compilation)")
 	cmd.Flags().StringVar(&scanFlags.LogFile, "log-file", "", "Path to the log file (default: <cache-dir>/logs/<timestamp>.log)")
 
-	cmd.Flags().StringArrayVar(&scanFlags.PassthroughApproximations, "passthrough-approximations", nil, "Pass-through approximation YAML file or directory (repeatable)")
+	addRenamedStringArrayFlag(cmd.Flags(), &scanFlags.PassthroughApproximations, "passthrough-models", "passthrough-approximations", "Pass-through models: a YAML file or a directory of them (repeatable)")
 
-	cmd.Flags().StringArrayVar(&scanFlags.DataflowApproximations, "dataflow-approximations", nil, "Dataflow approximation class directory or Java source directory (repeatable)")
+	addRenamedStringArrayFlag(cmd.Flags(), &scanFlags.DataflowApproximations, "java-models", "dataflow-approximations", "Java dataflow models: a compiled class directory or a Java source directory (repeatable)")
 
 	cmd.Flags().BoolVar(&scanFlags.TrackExternalMethods, "track-external-methods", false, "Write external-method coverage files next to the SARIF report")
 }
@@ -172,7 +198,7 @@ func isDefaultSeverity(sev []string) bool {
 // dockerScanSuggestion builds the "try Docker-based scan" fallback hint.
 func dockerScanSuggestion(cfg ScanConfig, projectRoot, sarifReportPath string) output.Suggestion {
 	return output.Suggestion{
-		Description: dockerFallbackHintPrefix + "scan:",
+		Description: "If the required Java is missing, set JAVA_HOME or scan in a container instead:",
 		Command:     utils.BuildScanCommandWithDocker(currentScanBuilder(cfg, ""), projectRoot, sarifReportPath, cfg.Ruleset),
 	}
 }
@@ -190,7 +216,7 @@ func runScan(cmd *cobra.Command, cfg ScanConfig) {
 		if err := validation.ValidateSourceProject(absUserProjectRoot); err != nil {
 			if validation.IsProjectModel(absUserProjectRoot) {
 				out.ErrorErr(err)
-				suggest("Use --project-model to scan a pre-compiled model", currentScanBuilder(cfg, "").WithProjectModel(absUserProjectRoot).Build())
+				suggest("Use --project-model to scan a pre-compiled model:", currentScanBuilder(cfg, "").WithProjectModel(absUserProjectRoot).Build())
 				os.Exit(1)
 			}
 			out.FatalErr(err)
@@ -283,7 +309,7 @@ func runScan(cmd *cobra.Command, cfg ScanConfig) {
 	}
 
 	if cfg.DryRun {
-		runDryRun("Compilation and analysis")
+		runDryRun("the build and scan")
 		return
 	}
 
@@ -296,25 +322,25 @@ func runScan(cmd *cobra.Command, cfg ScanConfig) {
 	}
 	if hasBuiltin {
 		if _, err := utils.EnsureRulesPath(out); err != nil {
-			out.Fatalf("Failed to prepare built-in rules: %s", err)
+			failf("Failed to prepare built-in rules: %s", err)
 		}
 	}
 
 	if plan.needsCompilation {
 		autobuilderJarPath, err := ensureAutobuilderAvailable()
 		if err != nil {
-			out.Fatalf("Native compile preparation failed: %s", err)
+			failf("Native compile preparation failed: %s", err)
 		}
 
 		compileJavaRunner := newAutobuilderJavaRunner()
 		if _, err := compileJavaRunner.EnsureJava(); err != nil {
-			out.Fatalf("Failed to resolve Java for compilation: %s", err)
+			failf("Failed to resolve Java for compilation: %s", err)
 		}
 
 		// Wipe any residue from a prior crashed compile before writing new output.
 		if plan.projectCachePath != "" {
 			if err := os.RemoveAll(plan.absProjectModel); err != nil {
-				out.Fatalf("Failed to prepare cache directory: %s", err)
+				failf("Failed to prepare cache directory: %s", err)
 			}
 		}
 
@@ -333,7 +359,7 @@ func runScan(cmd *cobra.Command, cfg ScanConfig) {
 		if plan.projectCachePath != "" {
 			if err := utils.MarkCompileComplete(plan.projectCachePath); err != nil {
 				_ = os.RemoveAll(plan.absProjectModel)
-				out.Fatalf("Failed to mark model complete: %s", err)
+				failf("Failed to mark model complete: %s", err)
 			}
 			if err := plan.cacheLock.Downgrade(); err != nil {
 				output.LogInfof("Cache lock downgrade failed, continuing under exclusive: %v", err)
@@ -344,7 +370,7 @@ func runScan(cmd *cobra.Command, cfg ScanConfig) {
 	}
 
 	if err := utils.EnsureParentDir(absSarifReportPath); err != nil {
-		out.Fatalf("Failed to create output directory: %s", err)
+		failf("Failed to create output directory: %s", err)
 	}
 
 	// Update builder with native paths for native execution
@@ -397,16 +423,16 @@ func runScan(cmd *cobra.Command, cfg ScanConfig) {
 
 	analyzerJarPath, err := ensureAnalyzerAvailable()
 	if err != nil {
-		out.Fatalf("Native scan preparation failed: %s", err)
+		failf("Native scan preparation failed: %s", err)
 	}
 	nativeBuilder.SetJarPath(analyzerJarPath)
 
-	// Process --dataflow-approximations: auto-compile .java sources if needed
+	// Process --java-models: auto-compile .java sources if needed
 	addDataflowApproximations(nativeBuilder, cfg.DataflowApproximations, analyzerJarPath, absProjectModelPath)
 
 	analyzerJavaRunner := newAnalyzerJavaRunner()
 	if _, err := analyzerJavaRunner.EnsureJava(); err != nil {
-		out.Fatalf("Failed to resolve Java for analyzer: %s", err)
+		failf("Failed to resolve Java for analyzer: %s", err)
 	}
 
 	var analyzerFail *analyzer.Error
@@ -461,15 +487,43 @@ func runScan(cmd *cobra.Command, cfg ScanConfig) {
 	var suggestions []output.Suggestion
 	if analyzerFail != nil {
 		suggestions = appendLogSuggestion(suggestions)
+		if retry, ok := retrySuggestion(analyzerFail.ExitCode, globals.Config.Scan.Timeout, globals.Config.Scan.MaxMemory); ok {
+			suggestions = append(suggestions, retry)
+		}
 	}
 	if report != nil {
 		// Scan does not expose summary's filter/group flags, so pass zero values:
 		// no filtering, default group dimension, first-flow code-flow selection.
 		printSarifSummary(report, absSarifReportPath, sarif.Filters{}, sarif.ListingOptions{MaxNestingLevel: -1})
-		suggestions = append(suggestions, output.Suggestion{
-			Description: "To view findings run",
-			Command:     utils.NewSummaryCommand(absSarifReportPath).WithShowFindings().Build(),
-		})
+		switch {
+		case cfg.DebugFactReachabilitySarif:
+			if analyzerFail == nil {
+				out.Successf("Reachability analysis completed.")
+			}
+			// The reachability report is the command's deliverable. Point at it,
+			// never at the main SARIF.
+			reachabilityReportPath := filepath.Join(filepath.Dir(absSarifReportPath), "debug-ifds-fact-reachability.sarif")
+			suggestions = append(suggestions, output.Suggestion{
+				Description: "To view the reachability report, run:",
+				Command:     utils.NewSummaryCommand(reachabilityReportPath).WithShowFindings().Build(),
+			})
+		case sarif.GenerateSummary(report).TotalFindings > 0:
+			if analyzerFail == nil {
+				out.Successf("Scan completed.")
+			}
+			suggestions = append(suggestions, output.Suggestion{
+				Description: "To view the findings, run:",
+				Command:     utils.NewSummaryCommand(absSarifReportPath).WithShowFindings().Build(),
+			})
+		case analyzerFail == nil:
+			out.Successf("Scan completed. No vulnerabilities found at %s severity.", strings.Join(cfg.Severity, " or "))
+			if isDefaultSeverity(cfg.Severity) {
+				suggestions = append(suggestions, output.Suggestion{
+					Description: "To also check note-level rules, run:",
+					Command:     noteSeverityScanCommand(cfg),
+				})
+			}
+		}
 	}
 	out.Suggestions(suggestions...)
 
@@ -478,6 +532,20 @@ func runScan(cmd *cobra.Command, cfg ScanConfig) {
 	}
 }
 
+// noteSeverityScanCommand builds the follow-up command for a clean scan: the
+// same invocation narrowed to the note-level rules the default run skips.
+func noteSeverityScanCommand(cfg ScanConfig) string {
+	sourcePath := cfg.UserProjectPath
+	if cfg.ProjectModelPath != "" {
+		sourcePath = ""
+	}
+	b := currentScanBuilder(cfg, sourcePath).WithSeverity([]string{"note"})
+	if cfg.ProjectModelPath != "" {
+		b.WithProjectModel(cfg.ProjectModelPath)
+	}
+	return b.Build()
+}
+
 func resolveScanPlan(cfg ScanConfig, absUserProjectRoot string) scanPlan {
 	if cfg.ProjectModelPath != "" {
 		return scanPlan{
@@ -537,7 +605,7 @@ func resolveScanPlan(cfg ScanConfig, absUserProjectRoot string) scanPlan {
 		} else {
 			out.Error("Another scan is currently analyzing this project")
 		}
-		suggest("To scan an existing model instead", utils.NewScanCommand("").WithProjectModel("<model-path>").Build())
+		suggest("To scan an existing model instead, run:", utils.NewScanCommand("").WithProjectModel("<model-path>").Build())
 		os.Exit(1)
 	}
 	if lockErr != nil {
diff --git a/cli/cmd/suggest.go b/cli/cmd/suggest.go
index 9508a86cb..416c76e69 100644
--- a/cli/cmd/suggest.go
+++ b/cli/cmd/suggest.go
@@ -3,20 +3,97 @@ package cmd
 import (
 	"fmt"
 	"os"
+	"strconv"
+	"strings"
+	"time"
 
+	"github.com/seqra/opentaint/internal/analyzer"
 	"github.com/seqra/opentaint/internal/globals"
 	"github.com/seqra/opentaint/internal/output"
 )
 
-// dockerFallbackHintPrefix is the shared lead-in for the Docker-based fallback
-// hints emitted when native compilation can't find a suitable Java. compile and
-// scan complete it with their respective "compilation:" / "scan:" suffix.
-const dockerFallbackHintPrefix = "If native compilation fails due to missing required Java, set JAVA_HOME according to the project's requirements or try Docker-based "
-
 func suggest(description, command string) {
 	out.Suggest(description, command)
 }
 
+// withFlag appends flag to the command string when it is not already present,
+// for suggestions that re-run the current invocation with one extra flag.
+func withFlag(command, flag string) string {
+	if strings.Contains(command, flag) {
+		return command
+	}
+	return command + " " + flag
+}
+
+// retrySuggestion builds the "re-run with more resources" hint for a resource
+// analyzer failure. The second result is false for exit codes where a plain
+// retry would not help (unhandled exception, configuration error).
+func retrySuggestion(exitCode int, timeout time.Duration, maxMemory string) (output.Suggestion, bool) {
+	switch exitCode {
+	case analyzer.ExitOOM:
+		return output.Suggestion{
+			Description: "To retry with more memory, run:",
+			Command:     rerunReplacingFlag(doubleMemory(maxMemory), "--max-memory"),
+		}, true
+	case analyzer.ExitTimeout:
+		return output.Suggestion{
+			Description: "To retry with a longer timeout, run:",
+			Command:     rerunReplacingFlag((timeout * 2).String(), "--timeout", "-t"),
+		}, true
+	}
+	return output.Suggestion{}, false
+}
+
+// rerunReplacingFlag reconstructs the current invocation with the named flag
+// (any alias, in both "--flag value" and "--flag=value" forms) replaced by the
+// given value, appended as names[0].
+func rerunReplacingFlag(value string, names ...string) string {
+	args := []string{"opentaint"}
+	skipNext := false
+	for _, arg := range os.Args[1:] {
+		if skipNext {
+			skipNext = false
+			continue
+		}
+		matched := false
+		for _, name := range names {
+			if arg == name {
+				matched = true
+				skipNext = true
+				break
+			}
+			if strings.HasPrefix(arg, name+"=") {
+				matched = true
+				break
+			}
+		}
+		if matched {
+			continue
+		}
+		args = append(args, shellQuote(arg))
+	}
+	args = append(args, names[0], shellQuote(value))
+	return strings.Join(args, " ")
+}
+
+// doubleMemory doubles a memory value like 8G or 1024m, falling back to the
+// runtime failure message's own 16G example when the value does not parse.
+func doubleMemory(value string) string {
+	digits := 0
+	for digits < len(value) && value[digits] >= '0' && value[digits] <= '9' {
+		digits++
+	}
+	suffix := value[digits:]
+	if digits == 0 || len(suffix) > 1 {
+		return "16G"
+	}
+	n, err := strconv.ParseInt(value[:digits], 10, 64)
+	if err != nil {
+		return "16G"
+	}
+	return fmt.Sprintf("%d%s", n*2, suffix)
+}
+
 // logSuggestion returns a Suggestion pointing at the active log file. The
 // second result is false when no log file is active (e.g. failures that occur
 // before logging is activated), in which case callers omit it.
diff --git a/cli/cmd/summary.go b/cli/cmd/summary.go
index 0959b5257..9b6da780c 100644
--- a/cli/cmd/summary.go
+++ b/cli/cmd/summary.go
@@ -9,14 +9,34 @@ import (
 
 // summaryCmd represents the summary command
 var summaryCmd = &cobra.Command{
-	Use:   "summary sarif",
-	Short: "Print summary of your sarif",
+	Use:   "summary <sarif-report>",
+	Short: "Show a summary of a SARIF report",
 	Args:  cobra.ExactArgs(1), // require exactly one argument
-	Long: `Print summary of your sarif file
+	Long: `Show a summary of a SARIF report in the terminal. The summary counts the findings by severity. It also shows which rules ran and which rules found problems.
 
-Arguments:
-  sarif  - Path to a sarif file
-`,
+The sarif-report argument is the path to a SARIF report. It is required. Use a report from "opentaint scan" or "opentaint test".
+
+To see each finding, use --show-findings. To make the list smaller, use --severity, --rule-id, or --path. To see the full data flow, use --verbose-flow and --show-code-snippets.
+
+This command only reads the report. It does not write files.`,
+	Example: `  # Show a summary of a report
+  opentaint summary report.sarif
+
+  # Show each finding with its location
+  opentaint summary report.sarif --show-findings
+
+  # Show only the error-level findings
+  opentaint summary report.sarif --show-findings --severity error
+
+  # Group the findings by rule
+  opentaint summary report.sarif --show-findings --group-by rule-id
+
+  # Recipe: examine one rule in full detail
+  opentaint summary report.sarif --show-findings --group-by rule-id
+  opentaint summary report.sarif --show-findings --rule-id <rule-id> --verbose-flow --show-code-snippets
+
+  # Recipe: read the findings for one part of the code
+  opentaint summary report.sarif --show-findings --path "src/main/**" --severity error`,
 
 	Run: func(cmd *cobra.Command, args []string) {
 		for _, s := range summarySeverities {
@@ -39,6 +59,13 @@ Arguments:
 			out.Fatalf("Failed to load SARIF report: %s", err)
 		}
 		printSarifSummary(report, absSarifPath, summaryFilters(), summaryListingOptions(dim, codeFlowSel))
+
+		if !showFindings && sarif.GenerateSummary(report.Filter(summaryFilters())).TotalFindings > 0 {
+			out.Suggest(
+				"To list the findings, run:",
+				currentSummaryBuilder(absSarifPath).WithShowFindings().Build(),
+			)
+		}
 	},
 }
 
@@ -58,16 +85,16 @@ var summaryCodeFlow string
 func init() {
 	rootCmd.AddCommand(summaryCmd)
 
-	summaryCmd.Flags().BoolVar(&showFindings, "show-findings", false, "Show all issues from Sarif file")
+	summaryCmd.Flags().BoolVar(&showFindings, "show-findings", false, "Show every finding in the SARIF report")
 	summaryCmd.Flags().BoolVar(&showCodeSnippets, "show-code-snippets", false, "Show finding related code snippets")
 	summaryCmd.Flags().BoolVar(&verboseFlow, "verbose-flow", false, "Show full code flow steps for findings")
 	summaryCmd.Flags().StringArrayVar(&summaryPaths, "path", nil, "Show only findings whose file path matches this glob (** supported, repeatable)")
-	summaryCmd.Flags().StringArrayVar(&summarySeverities, "severity", nil, "Show only findings of this SARIF level: error, warning, note, none (repeatable)")
-	summaryCmd.Flags().StringArrayVar(&summaryRuleIDs, "rule-id", nil, "Show only findings for this rule: full id, leaf name, or glob (repeatable)")
+	summaryCmd.Flags().StringArrayVar(&summarySeverities, "severity", nil, "Show only findings at these SARIF levels: note, warning, error, none (repeatable)")
+	summaryCmd.Flags().StringArrayVar(&summaryRuleIDs, "rule-id", nil, "Show only findings from this rule: full id, leaf name, or glob (repeatable)")
 	summaryCmd.Flags().StringArrayVar(&summaryFingerprints, "partial-fingerprint", nil, "Show only findings whose partial fingerprint starts with this value (git-hash style, repeatable)")
-	summaryCmd.Flags().StringVar(&summaryFingerprintKey, "partial-fingerprint-key", "", "partialFingerprints key matched by --partial-fingerprint (default vulnerabilityWithTraceHash/v1)")
+	summaryCmd.Flags().StringVar(&summaryFingerprintKey, "partial-fingerprint-key", "", "partialFingerprints key matched by --partial-fingerprint (defaults to vulnerabilityWithTraceHash/v1)")
 	summaryCmd.Flags().IntVar(&summaryMaxNestingLevel, "max-nesting-level", -1, "Collapse code-flow steps deeper than this call-nesting level (-1 = no cap)")
-	summaryCmd.Flags().StringVar(&summaryGroupBy, "group-by", "", "Group the --show-findings listing by: severity, rule-id, file-path (default file-path)")
+	summaryCmd.Flags().StringVar(&summaryGroupBy, "group-by", "", "Group the --show-findings listing by: severity, rule-id, file-path (defaults to file-path)")
 	summaryCmd.Flags().StringVar(&summaryCodeFlow, "code-flow", "", "Render code flows: \"all\", a 1-based index, or unset (first only)")
 }
 
@@ -137,7 +164,7 @@ func printSarifSummary(report *sarif.Report, absSarifPath string, filters sarif.
 
 	if showFindings && hasOmittedFlow && !verboseFlow {
 		out.Suggest(
-			"To see full code flow and code snippets, use:",
+			"To see the full code flow and code snippets, run:",
 			currentSummaryBuilder(absSarifPath).WithVerboseFlow().WithShowCodeSnippets().Build(),
 		)
 	}
diff --git a/cli/cmd/test.go b/cli/cmd/test.go
index 409240606..6b3b25a55 100644
--- a/cli/cmd/test.go
+++ b/cli/cmd/test.go
@@ -9,17 +9,38 @@ import (
 var testCmd = &cobra.Command{
 	Use:   "test",
 	Short: "Create and run rule and approximation tests",
-	Long:  `Tools for creating test projects, running annotated rule and approximation tests, and debugging rule reachability.`,
+	Long: `Create and run tests for detection rules and for dataflow approximations. Rule tests make sure that a rule finds the positive samples and ignores the negative samples. Approximation tests make sure that a dataflow approximation moves taint from source to sink.
+
+Workflow:
+  1. Create a test project with init.
+  2. Compile the project with "opentaint compile".
+  3. Run the samples with "test rule run" or "test approximation run".
+
+To see why one rule does or does not fire, use "test rule reachability".`,
 }
 
 var testRuleCmd = &cobra.Command{
 	Use:   "rule",
 	Short: "Create, run, and debug detection-rule tests",
+	Long: `Create, run, and debug tests for taint detection rules. A rule test makes sure that a rule finds the positive samples and ignores the negative samples.
+
+Workflow:
+  1. Create a test project with "test rule init".
+  2. Compile the project with "opentaint compile".
+  3. Run the samples with "test rule run".
+
+To see why one rule does or does not fire, use "test rule reachability".`,
 }
 
 var testApproximationCmd = &cobra.Command{
 	Use:   "approximation",
 	Short: "Create and run dataflow-approximation tests",
+	Long: `Create and run tests for dataflow approximations. An approximation test makes sure that an approximation moves taint from source to sink in your samples.
+
+Workflow:
+  1. Create a test project with "test approximation init".
+  2. Compile the project with "opentaint compile".
+  3. Run the samples with "test approximation run --java-models <approximation>".`,
 }
 
 func init() {
@@ -28,20 +49,9 @@ func init() {
 	testCmd.AddCommand(testApproximationCmd)
 }
 
-func testExitCodesHelp(passedLine string) string {
-	return `Exit codes:
-  0    ` + passedLine + `
-  1    General failure (configuration or infrastructure error)
-  2    One or more tests failed (false negatives/positives or skipped samples)
-  252  Unhandled analyzer exception
-  253  Out of memory (try increasing --max-memory)
-  254  Analysis timed out (try increasing --timeout)
-  255  Project configuration error`
-}
-
 func addTestRunFlags(cmd *cobra.Command, outputDir *string, timeout *time.Duration, maxMemory *string, dataflow *[]string) {
 	cmd.Flags().StringVarP(outputDir, "output", "o", "", "Directory for test-result.json and test-results.sarif")
-	cmd.Flags().DurationVar(timeout, "timeout", 600*time.Second, "Analysis timeout")
-	cmd.Flags().StringVar(maxMemory, "max-memory", "8G", "Maximum analyzer heap size (e.g., 8G)")
-	cmd.Flags().StringArrayVar(dataflow, "dataflow-approximations", nil, "Dataflow approximation class directory or Java source directory (repeatable)")
+	cmd.Flags().DurationVar(timeout, "timeout", 600*time.Second, "Maximum wall-clock time for analysis (e.g. 30m, 1h)")
+	cmd.Flags().StringVar(maxMemory, "max-memory", "8G", "Maximum analyzer heap size (e.g. 8G, 1024m)")
+	addRenamedStringArrayFlag(cmd.Flags(), dataflow, "java-models", "dataflow-approximations", "Java dataflow models: a compiled class directory or a Java source directory (repeatable)")
 }
diff --git a/cli/cmd/test_approximation_run.go b/cli/cmd/test_approximation_run.go
index 018e16c03..9f688c1f4 100644
--- a/cli/cmd/test_approximation_run.go
+++ b/cli/cmd/test_approximation_run.go
@@ -17,13 +17,25 @@ var (
 
 var testApproximationRunCmd = &cobra.Command{
 	Use:   "run <project-model>",
-	Short: "Run dataflow approximation tests on a compiled project model",
-	Long: `Run the samples specified in rule-test.yaml with the supplied dataflow approximations applied.
+	Short: "Run dataflow-approximation tests on a compiled project model",
+	Long: `Run the samples that rule-test.yaml declares, with your dataflow approximations applied. The command reports which samples passed. A fixed source-to-sink harness rule is applied automatically. Positive samples point to it with the id approximation-rule.
 
-A built-in source-to-sink harness rule is applied automatically; positive samples reference the
-approximation-rule.yaml rule with id "approximation-rule".
+The project-model argument is a compiled project model directory from "opentaint compile". Give the approximation under test with --java-models.
+
+The command writes test-result.json and a test-results.sarif report to --output. If --output is not set, it writes to a temporary directory.
+
+Compile the test project before you run the tests. To read the results, use "opentaint summary".
 
 ` + testExitCodesHelp("All approximation tests passed"),
+	Example: `  # Run an approximation test on a compiled model
+  opentaint test approximation run ./approx-test/model --java-models ./approx
+
+  # Write the results to a directory
+  opentaint test approximation run ./approx-test/model --java-models ./approx -o ./results
+
+  # Recipe: change an approximation, then make sure the tests stay green
+  opentaint test approximation run ./approx-test/model --java-models ./approx -o ./results
+  opentaint summary ./results/test-results.sarif --show-findings`,
 	Args: cobra.ExactArgs(1),
 	Run: func(cmd *cobra.Command, args []string) {
 		ruleDir, err := os.MkdirTemp("", "opentaint-approx-rule-*")
@@ -36,6 +48,7 @@ approximation-rule.yaml rule with id "approximation-rule".
 
 		runTestProject(args[0], testProjectOptions{
 			label:          "Approximation tests",
+			passedLine:     "All approximation tests passed.",
 			tempDir:        "opentaint-test-approximations-*",
 			rulesets:       []string{ruleDir},
 			outputDir:      testApproxOutputDir,
diff --git a/cli/cmd/test_init.go b/cli/cmd/test_init.go
index 2c4966f82..0686204fb 100644
--- a/cli/cmd/test_init.go
+++ b/cli/cmd/test_init.go
@@ -4,6 +4,7 @@ import (
 	"fmt"
 	"path/filepath"
 
+	"github.com/seqra/opentaint/internal/output"
 	"github.com/seqra/opentaint/internal/testapprox"
 	"github.com/seqra/opentaint/internal/testproject"
 	"github.com/seqra/opentaint/internal/testrule"
@@ -18,19 +19,26 @@ var initRuleSourcesOnly bool
 var testRuleInitCmd = &cobra.Command{
 	Use:   "init <output-dir>",
 	Short: "Create rule test projects with source and sink harnesses",
-	Long: `Create one or two Gradle test projects under <output-dir>. The sinks
-project tests sink rules against a generic Taint source; the sources project
-tests source rules against a generic Taint sink. Use --sinks-only or
---sources-only when only one project is needed.
+	Long: `Create one or two Gradle test projects for detection-rule tests. The sinks project tests sink rules with a generic taint source. The sources project tests source rules with a generic taint sink.
 
-Each project includes:
-  - build.gradle.kts with compile-only dependencies, settings.gradle.kts
-  - src/main/java/test/ with Taint.java (the generic source()/sink()) for test sample sources
-  - test-rules/java/lib/test/generic-{source,sink}.yaml marker rules for test-only joins
+The output-dir argument is the parent directory for the new projects. The default creates the two projects, in output-dir/sinks and output-dir/sources. To create one project only, use --sinks-only or --sources-only. To add compile-only Maven dependencies for the samples, use --dependency.
 
-Positive and negative samples are specified via rule-test.yaml.
+Each project contains a rule-test.yaml file and a Taint.java harness. Declare your positive and negative samples in rule-test.yaml.
 
-Use --dependency to add compile-only Maven dependencies for the samples.`,
+Then compile the project with "opentaint compile" and run the samples with "opentaint test rule run".`,
+	Example: `  # Create the sinks and the sources test projects
+  opentaint test rule init ./rule-tests
+
+  # Create only the sinks project
+  opentaint test rule init ./rule-tests --sinks-only
+
+  # Add a compile-only dependency for the samples
+  opentaint test rule init ./rule-tests --dependency <group:artifact:version>
+
+  # Recipe: from an empty directory to a first test run
+  opentaint test rule init ./rule-tests
+  opentaint compile ./rule-tests/sinks -o ./rule-tests/sinks/model
+  opentaint test rule run ./rule-tests/sinks/model --ruleset ./my-rules`,
 	Args: cobra.ExactArgs(1),
 	Run: func(cmd *cobra.Command, args []string) {
 		if initRuleSinksOnly && initRuleSourcesOnly {
@@ -50,28 +58,38 @@ Use --dependency to add compile-only Maven dependencies for the samples.`,
 			if err := testrule.Scaffold(dir); err != nil {
 				out.Fatalf("Failed to scaffold rule test project: %s", err)
 			}
-			fmt.Printf("Rule test project (%s) initialized at %s\n", kind, dir)
+			out.Printf("Rule test project (%s) initialized at %s", kind, dir)
 		}
+		dir := filepath.Join(args[0], kinds[0])
+		modelDir := filepath.Join(dir, "model")
+		out.Suggestions(
+			output.Suggestion{Description: "To add your test samples, edit:", Command: filepath.Join(dir, "rule-test.yaml")},
+			output.Suggestion{Description: "To compile the test project, run:", Command: fmt.Sprintf("opentaint compile %s -o %s", dir, modelDir)},
+			output.Suggestion{Description: "To run the tests, run:", Command: fmt.Sprintf("opentaint test rule run %s", modelDir)},
+		)
 	},
 }
 
 var testApproximationInitCmd = &cobra.Command{
 	Use:   "init <output-dir>",
-	Short: "Create a dataflow approximation test project",
-	Long: `Create a minimal Gradle project for testing OpenTaint dataflow approximations.
+	Short: "Create a dataflow-approximation test project",
+	Long: `Create a Gradle test project for dataflow-approximation tests. The project contains a fixed source-to-sink rule. The samples are checked against this rule.
+
+The output-dir argument is the directory for the new project. To add compile-only Maven dependencies for the samples, use --dependency. The approximation under test is not part of the project. Give it at run time with --java-models.
 
-The project includes:
-  - build.gradle.kts with compile-only dependencies
-  - settings.gradle.kts
-  - approximation-rule.yaml, the fixed source-to-sink rule the samples are checked against
-  - src/main/java/test/ with Taint.java (the fixed source() and sink()) for test sample sources
+The project contains a rule-test.yaml file, a Taint.java source and sink, and the fixed approximation-rule.yaml. Declare your positive and negative samples in rule-test.yaml.
 
-Positive and negative samples are specified via rule-test.yaml.
+Then compile the project with "opentaint compile" and run the samples with "opentaint test approximation run".`,
+	Example: `  # Create an approximation test project
+  opentaint test approximation init ./approx-test
 
-The approximation under test is supplied separately at test time with
---dataflow-approximations.
+  # Add a compile-only dependency for the samples
+  opentaint test approximation init ./approx-test --dependency <group:artifact:version>
 
-Use --dependency to add compile-only Maven dependencies for the samples.`,
+  # Recipe: from an empty directory to a first test run
+  opentaint test approximation init ./approx-test
+  opentaint compile ./approx-test -o ./approx-test/model
+  opentaint test approximation run ./approx-test/model --java-models ./my-approximation`,
 	Args: cobra.ExactArgs(1),
 	Run: func(cmd *cobra.Command, args []string) {
 		if err := testproject.Bootstrap(args[0], "approximation-test-project", initApproxProjectDeps); err != nil {
@@ -80,7 +98,14 @@ Use --dependency to add compile-only Maven dependencies for the samples.`,
 		if err := testapprox.Scaffold(args[0]); err != nil {
 			out.Fatalf("Failed to scaffold approximation project: %s", err)
 		}
-		fmt.Printf("Approximation test project initialized at %s\n", args[0])
+		out.Printf("Approximation test project initialized at %s", args[0])
+		dir := args[0]
+		modelDir := filepath.Join(dir, "model")
+		out.Suggestions(
+			output.Suggestion{Description: "To add your test samples, edit:", Command: filepath.Join(dir, "rule-test.yaml")},
+			output.Suggestion{Description: "To compile the test project, run:", Command: fmt.Sprintf("opentaint compile %s -o %s", dir, modelDir)},
+			output.Suggestion{Description: "To run the tests, run:", Command: fmt.Sprintf("opentaint test approximation run %s --java-models <approximation>", modelDir)},
+		)
 	},
 }
 
diff --git a/cli/cmd/test_rule_reachability.go b/cli/cmd/test_rule_reachability.go
index ecb0bf323..20714bdf8 100644
--- a/cli/cmd/test_rule_reachability.go
+++ b/cli/cmd/test_rule_reachability.go
@@ -8,12 +8,31 @@ var reachabilityEntryPoint string
 
 var testRuleReachabilityCmd = &cobra.Command{
 	Use:   "reachability <rule-id> [source-path]",
-	Short: "Trace why a rule can or cannot reach its facts",
-	Long: `Scan a project with one rule and write a sibling fact-reachability SARIF
-report (debug-ifds-fact-reachability.sarif) next to the main one. Use this to
-debug why a rule does or does not fire.
+	Short: "Show why a rule does or does not fire",
+	Long: `Scan a project with one rule and write a fact-reachability SARIF report. The report shows why the rule does or does not fire. Library source and sink rules that the rule points to are included automatically.
 
-Referenced library source and sink rules are collected and analyzed automatically.`,
+The rule-id argument selects the rule. The source-path argument is the project root. It is optional. The default is the current directory. To use a compiled model, use --project-model. Do not give source-path and --project-model together. To start the analysis from one method, use --entry-points.
+
+The report name is debug-ifds-fact-reachability.sarif. It is written adjacent to the main SARIF report.
+
+Before the first run, run "opentaint pull" one time. To read the report, use "opentaint summary".
+
+` + scanExitCodesHelp("Reachability analysis completed"),
+	Example: `  # Show why a rule does or does not fire on the current directory
+  opentaint test rule reachability <rule-id> .
+
+  # Examine a rule on a compiled project model
+  opentaint test rule reachability <rule-id> --project-model ./model
+
+  # Start the analysis from one entry-point method
+  opentaint test rule reachability <rule-id> . --entry-points com.example.App#main
+
+  # Make sure the inputs are correct, without a scan
+  opentaint test rule reachability <rule-id> . --dry-run
+
+  # Recipe: find why a new rule stays silent
+  opentaint test rule reachability <rule-id> . -o report.sarif
+  opentaint summary debug-ifds-fact-reachability.sarif --show-findings --verbose-flow`,
 	Annotations: map[string]string{"PrintConfig": "true"},
 	Args:        cobra.RangeArgs(1, 2),
 	Run: func(cmd *cobra.Command, args []string) {
diff --git a/cli/cmd/test_rule_run.go b/cli/cmd/test_rule_run.go
index 4b380c617..15a1e3c4b 100644
--- a/cli/cmd/test_rule_run.go
+++ b/cli/cmd/test_rule_run.go
@@ -7,6 +7,7 @@ import (
 	"time"
 
 	"github.com/seqra/opentaint/internal/analyzer"
+	"github.com/seqra/opentaint/internal/output"
 	"github.com/seqra/opentaint/internal/utils"
 	"github.com/seqra/opentaint/internal/utils/log"
 	"github.com/spf13/cobra"
@@ -25,14 +26,32 @@ var (
 var testRuleRunCmd = &cobra.Command{
 	Use:   "run <project-model>",
 	Short: "Run detection-rule tests on a compiled project model",
-	Long: `Run detection rules against the samples specified in rule-test.yaml in the
-compiled project model.
+	Long: `Run detection rules on the samples that rule-test.yaml declares. The command reports which samples passed. The built-in rules are always included.
+
+The project-model argument is a compiled project model directory from "opentaint compile". To add your own rules, use --ruleset. To run only specified rules, use --rule-id. To apply models, use --java-models or --passthrough-models.
+
+The command writes test-result.json and a test-results.sarif report to --output. If --output is not set, it writes to a temporary directory.
+
+Compile the test project before you run the tests. To read the results, use "opentaint summary".
 
 ` + testExitCodesHelp("All rule tests passed"),
+	Example: `  # Run the built-in rules on a compiled model
+  opentaint test rule run ./rule-tests/sinks/model
+
+  # Test your own rules and write the results to a directory
+  opentaint test rule run ./rule-tests/sinks/model --ruleset ./rules -o ./results
+
+  # Run only one rule
+  opentaint test rule run ./rule-tests/sinks/model --rule-id <rule-id>
+
+  # Recipe: change a rule, then make sure the tests stay green
+  opentaint test rule run ./rule-tests/sinks/model --ruleset ./rules -o ./results
+  opentaint summary ./results/test-results.sarif --show-findings`,
 	Args: cobra.ExactArgs(1),
 	Run: func(cmd *cobra.Command, args []string) {
 		runTestProject(args[0], testProjectOptions{
 			label:               "Rule tests",
+			passedLine:          "All rule tests passed.",
 			tempDir:             "opentaint-test-rules-*",
 			rulesets:            testRulesRuleset,
 			outputDir:           testRulesOutputDir,
@@ -48,6 +67,7 @@ compiled project model.
 
 type testProjectOptions struct {
 	label               string
+	passedLine          string // success status line, matching the documented exit-code 0 row
 	tempDir             string
 	rulesets            []string
 	outputDir           string
@@ -104,7 +124,7 @@ func runTestProject(projectModelArg string, opts testProjectOptions) {
 	if opts.includeBuiltinRules {
 		rulesPath, err := utils.EnsureRulesPath(out)
 		if err != nil {
-			out.Fatalf("Failed to prepare built-in rules: %s", err)
+			failf("Failed to prepare built-in rules: %s", err)
 		}
 		builder.AddRuleSet(rulesPath)
 	}
@@ -124,7 +144,7 @@ func runTestProject(projectModelArg string, opts testProjectOptions) {
 
 	analyzerJarPath, err := ensureAnalyzerAvailable()
 	if err != nil {
-		out.Fatalf("Failed to resolve analyzer: %s", err)
+		failf("Failed to resolve analyzer: %s", err)
 	}
 	builder.SetJarPath(analyzerJarPath)
 
@@ -133,45 +153,62 @@ func runTestProject(projectModelArg string, opts testProjectOptions) {
 
 	javaRunner := newAnalyzerJavaRunner()
 	if _, err := javaRunner.EnsureJava(); err != nil {
-		out.Fatalf("Failed to resolve Java for analyzer: %s", err)
+		failf("Failed to resolve Java for analyzer: %s", err)
 	}
 
 	cmdErr, err := scanProject(builder, javaRunner)
 	if err != nil {
-		out.Fatalf("%s failed: %s", opts.label, err)
+		failf("%s failed: %s", opts.label, err)
 	}
 	analyzerFail := analyzer.Classify(cmdErr)
-	if analyzerFail != nil {
-		out.Error(analyzerFail.Message)
-	}
 
 	resultPath := filepath.Join(outputDir, "test-result.json")
-	fmt.Printf("Results directory: %s\n", outputDir)
-	fmt.Printf("Test results:     %s\n", resultPath)
+	out.Printf("Results directory: %s", outputDir)
+	out.Printf("Test results:     %s", resultPath)
 
 	if analyzerFail != nil {
+		out.Error(analyzerFail.Message)
+		// Test runs do not activate file logging, so the log pointer is usually
+		// absent. For resource failures suggest the retry with more resources.
+		// Otherwise the --debug re-run is the actionable way to see what failed.
+		hint := output.Suggestion{
+			Description: "To stream the analyzer output, re-run with --debug:",
+			Command:     withFlag(rerunWithoutDryRun(), "--debug"),
+		}
+		if retry, ok := retrySuggestion(analyzerFail.ExitCode, opts.timeout, opts.maxMemory); ok {
+			hint = retry
+		}
+		out.Suggestions(append(appendLogSuggestion(nil), hint)...)
 		os.Exit(analyzerFail.ExitCode)
 	}
 
 	tr, err := analyzer.LoadTestResult(resultPath)
 	if err != nil {
-		out.Fatalf("%s produced no readable test-result.json: %s", opts.label, err)
+		failf("%s produced no readable test-result.json: %s", opts.label, err)
 	}
-	fmt.Printf("Passed: %d, failed: %d (false negatives: %d, false positives: %d, skipped: %d), disabled: %d\n",
+	out.Printf("Passed: %d, failed: %d (false negatives: %d, false positives: %d, skipped: %d), disabled: %d",
 		len(tr.Success), tr.Failed(), len(tr.FalseNegative), len(tr.FalsePositive), len(tr.Skipped), len(tr.Disabled))
+
+	viewResultsCommand := utils.NewSummaryCommand(filepath.Join(outputDir, "test-results.sarif")).WithShowFindings().Build()
+
 	if tr.Failed() > 0 {
 		out.Error(fmt.Sprintf("%s failed", opts.label))
+		out.Suggestions(append(appendLogSuggestion(nil), output.Suggestion{
+			Description: "To inspect the failing samples, run:",
+			Command:     viewResultsCommand,
+		})...)
 		os.Exit(2)
 	}
 
-	fmt.Printf("%s completed successfully\n", opts.label)
+	out.Successf("%s", opts.passedLine)
+	suggest("To view the test results, run:", viewResultsCommand)
 }
 
 func init() {
 	testRuleCmd.AddCommand(testRuleRunCmd)
 
-	testRuleRunCmd.Flags().StringArrayVar(&testRulesRuleset, "ruleset", nil, "Ruleset file or directory to test (repeatable)")
+	testRuleRunCmd.Flags().StringArrayVar(&testRulesRuleset, "ruleset", nil, "Ruleset to test: a YAML file or a directory of .yml or .yaml files (repeatable)")
 	addTestRunFlags(testRuleRunCmd, &testRulesOutputDir, &testRulesTimeout, &testRulesMaxMemory, &testRulesDataflow)
 	testRuleRunCmd.Flags().StringArrayVar(&testRulesRuleID, "rule-id", nil, "Run only rules with this ID (repeatable)")
-	testRuleRunCmd.Flags().StringArrayVar(&testRulesPassthrough, "passthrough-approximations", nil, "Pass-through approximation YAML file or directory (repeatable)")
+	addRenamedStringArrayFlag(testRuleRunCmd.Flags(), &testRulesPassthrough, "passthrough-models", "passthrough-approximations", "Pass-through models: a YAML file or a directory of them (repeatable)")
 }
diff --git a/cli/cmd/update.go b/cli/cmd/update.go
index 1d3a5c1bd..6ef0484d9 100644
--- a/cli/cmd/update.go
+++ b/cli/cmd/update.go
@@ -20,13 +20,25 @@ var (
 var updateCmd = &cobra.Command{
 	Use:   "update [version]",
 	Short: "Update opentaint to the latest version",
-	Long: `Update opentaint to the latest version (or a specific version).
+	Long: `Update the opentaint binary to the latest release. To get a specified version, give the version argument. Only upgrades are possible. The command refuses a version that is older than the current one.
 
-This command detects how opentaint was installed and provides appropriate
-instructions for package manager installations. For binary installations,
-it performs an in-place update.
+If opentaint was installed with Homebrew or npm, the command does not change the binary. It shows the correct package-manager command.
 
-Only upgrades are supported — downgrading to an older version is refused.`,
+To see the latest version without a download, use --check. To skip the confirmation prompt, use --yes.
+
+After a successful update, remove the old artifacts with "opentaint prune".`,
+	Example: `  # Update to the latest release
+  opentaint update
+
+  # See if a newer version is available, without a download
+  opentaint update --check
+
+  # Update to a specified version without a prompt
+  opentaint update 1.2.3 --yes
+
+  # Recipe: update, then remove the artifacts of the old version
+  opentaint update --yes
+  opentaint prune --yes`,
 	Args: cobra.MaximumNArgs(1),
 	Run: func(cmd *cobra.Command, args []string) {
 		// Check installation method first
@@ -35,11 +47,11 @@ Only upgrades are supported — downgrading to an older version is refused.`,
 		switch method {
 		case utils.InstallMethodHomebrew:
 			out.Print("opentaint was installed via Homebrew.")
-			out.Print("Run: brew upgrade --cask opentaint")
+			suggest("To update, run:", "brew upgrade --cask opentaint")
 			return
 		case utils.InstallMethodNpm:
 			out.Print("opentaint was installed via npm.")
-			out.Print("Run: npm install -g @seqra/opentaint@latest")
+			suggest("To update, run:", "npm install -g @seqra/opentaint@latest")
 			return
 		}
 
@@ -75,7 +87,7 @@ Only upgrades are supported — downgrading to an older version is refused.`,
 			out.Warnf("Could not compare versions: %s", err)
 			out.Printf("Current: %s, Latest: %s", currentVersion, targetVersion)
 			if !updateYes {
-				out.Print("Use --yes to proceed anyway.")
+				suggest("To proceed anyway, run:", withFlag(rerunWithoutDryRun(), "--yes"))
 				return
 			}
 		}
@@ -94,9 +106,8 @@ Only upgrades are supported — downgrading to an older version is refused.`,
 			out.Section("Update Available").
 				Field("Current version", fmt.Sprintf("v%s", currentVersion)).
 				Field("Latest version", fmt.Sprintf("v%s", targetVersion)).
-				Line().
-				Text("Run 'opentaint update' to update.").
 				Render()
+			suggest("To update, run:", "opentaint update")
 			return
 		}
 
@@ -107,6 +118,7 @@ Only upgrades are supported — downgrading to an older version is refused.`,
 		if !updateYes {
 			if !out.Confirm("Proceed with update?", false) {
 				out.Print("Update cancelled.")
+				suggest("To update without confirming, run:", "opentaint update --yes")
 				return
 			}
 		}
@@ -132,7 +144,7 @@ Only upgrades are supported — downgrading to an older version is refused.`,
 		}
 
 		out.Successf("Successfully updated to v%s", targetVersion)
-		suggest("To clean up old artifacts run", "opentaint prune")
+		suggest("To clean up old artifacts, run:", "opentaint prune")
 	},
 }
 
diff --git a/cli/internal/analyzer/exit.go b/cli/internal/analyzer/exit.go
index 6d38e7599..9e97afbda 100644
--- a/cli/internal/analyzer/exit.go
+++ b/cli/internal/analyzer/exit.go
@@ -37,9 +37,9 @@ func ExitMessage(code int) string {
 	case ExitConfigError:
 		return "project configuration error"
 	case ExitTimeout:
-		return "analysis timed out — try increasing --timeout or --max-memory"
+		return "analysis timed out: try increasing --timeout or --max-memory"
 	case ExitOOM:
-		return "out of memory — try increasing --max-memory (e.g. --max-memory 16G)"
+		return "out of memory: try increasing --max-memory (e.g. --max-memory 16G)"
 	case ExitException:
 		return "unhandled analyzer exception"
 	default:
diff --git a/cli/internal/utils/opentaint_command_builder.go b/cli/internal/utils/opentaint_command_builder.go
index 1356a557b..369f62cd5 100644
--- a/cli/internal/utils/opentaint_command_builder.go
+++ b/cli/internal/utils/opentaint_command_builder.go
@@ -184,7 +184,7 @@ func (cb *OpentaintCommandBuilder) WithRuleID(ruleIDs []string) *OpentaintComman
 func (cb *OpentaintCommandBuilder) WithPassthroughApproximations(paths []string) *OpentaintCommandBuilder {
 	for _, p := range paths {
 		if p != "" {
-			cb.arrayFlags["passthrough-approximations"] = append(cb.arrayFlags["passthrough-approximations"], p)
+			cb.arrayFlags["passthrough-models"] = append(cb.arrayFlags["passthrough-models"], p)
 		}
 	}
 	return cb
@@ -193,7 +193,7 @@ func (cb *OpentaintCommandBuilder) WithPassthroughApproximations(paths []string)
 func (cb *OpentaintCommandBuilder) WithDataflowApproximations(paths []string) *OpentaintCommandBuilder {
 	for _, p := range paths {
 		if p != "" {
-			cb.arrayFlags["dataflow-approximations"] = append(cb.arrayFlags["dataflow-approximations"], p)
+			cb.arrayFlags["java-models"] = append(cb.arrayFlags["java-models"], p)
 		}
 	}
 	return cb
diff --git a/docs/README.md b/docs/README.md
index 760695b75..cb3fe42fd 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -128,11 +128,11 @@ opentaint summary --show-findings --verbose-flow --show-code-snippets results.sa
 
 | Command | Description |
 |---------|-------------|
-| `opentaint scan` | Analyze projects (auto-detects Maven/Gradle) |
+| `opentaint scan` | Analyze projects (auto-detects the build system) |
 | `opentaint compile` | Build project model separately |
 | `opentaint project` | Create model from precompiled JARs |
 | `opentaint summary` | View SARIF results |
-| `opentaint health` | Show resolved analyzer, autobuilder, rules, and runtime paths |
+| `opentaint health` | Show dependency paths and report missing components |
 | `opentaint test rule` | Scaffold, test, and debug detection rules |
 | `opentaint test approximation` | Scaffold and test dataflow approximations |
 | `opentaint pull` | Download dependencies |
diff --git a/docs/installation.md b/docs/installation.md
index c1e400cc8..8d76abffe 100644
--- a/docs/installation.md
+++ b/docs/installation.md
@@ -1,6 +1,6 @@
 # Installation
 
-**Prerequisites:** Same build requirements as your Java/Kotlin project (Maven or Gradle, project dependencies). Java runtime is bundled with release archives.
+**Prerequisites:** Same build requirements as your project (Maven or Gradle for Java/Kotlin). Java runtime is bundled with release archives.
 
 ## Homebrew (Linux/macOS)
 
@@ -150,7 +150,7 @@ For package manager installations, `opentaint update` will show the appropriate
 
 ## Cleaning Up
 
-Remove stale downloaded artifacts:
+Remove old downloaded artifacts:
 
 ```bash
 opentaint prune              # Interactive confirmation
diff --git a/docs/usage.md b/docs/usage.md
index 84f9359ed..7a60d4812 100644
--- a/docs/usage.md
+++ b/docs/usage.md
@@ -78,20 +78,20 @@ Use [CodeChecker](https://github.com/Ericsson/codechecker) for advanced result m
 
 | Command | Description |
 |---------|-------------|
-| `opentaint scan` | Analyze projects (auto-detects Maven/Gradle, builds, and scans) |
+| `opentaint scan` | Analyze projects (auto-detects the build system, builds, and scans) |
 | `opentaint compile` | Build project model separately from scanning |
 | `opentaint project` | Create project model from precompiled JARs/classes |
 | `opentaint summary` | View SARIF analysis results |
-| `opentaint health` | Show resolved paths for the analyzer, autobuilder, rules, and Java runtime |
+| `opentaint health` | Show dependency paths and report missing components |
 | `opentaint test rule` | Create, run, and debug detection-rule tests |
 | `opentaint test approximation` | Create and run dataflow-approximation tests |
-| `opentaint pull` | Download analyzer dependencies |
+| `opentaint pull` | Download the analysis toolchain and Java runtime |
 | `opentaint update` | Update to latest version |
-| `opentaint prune` | Remove stale downloaded artifacts and cached models |
+| `opentaint prune` | Remove old downloaded artifacts and cached models |
 
 ### opentaint scan
 
-Automatically detects Maven/Gradle projects, builds them, and performs security analysis. The source path defaults to the current directory when omitted.
+Automatically detects the project's build system (Maven or Gradle), builds the project, and runs taint analysis over the result. The source path defaults to the current directory when omitted.
 
 On the first run, the compiled project model is cached in `~/.opentaint/cache/`. Subsequent scans of the same project reuse the cached model, skipping compilation entirely.
 
@@ -100,10 +100,10 @@ On the first run, the compiled project model is cached in `~/.opentaint/cache/`.
 | `--output`, `-o` | Path to the SARIF report (default: `<model-dir>/sources/opentaint.sarif`) |
 | `--recompile` | Force recompilation even if a cached project model exists |
 | `--project-model` | Path to a pre-compiled project model (skips compilation) |
-| `--timeout`, `-t` | Timeout for analysis (default: `15m`) |
-| `--max-memory` | Maximum memory for the analyzer (default: `8G`) |
-| `--severity` | Severity levels to report (default: `warning`, `error`) |
-| `--ruleset` | YAML rules file or directory (default: `builtin`) |
+| `--timeout`, `-t` | Maximum wall-clock time for analysis (default: `15m`) |
+| `--max-memory` | Maximum analyzer heap size (default: `8G`) |
+| `--severity` | Run only rules at these severity levels: `note`, `warning`, `error` (default: `warning`, `error`) |
+| `--ruleset` | Rules to run: a YAML file, a directory of rules files, or `builtin` (default: `builtin`) |
 | `--dry-run` | Validate inputs and show what would run without compiling or scanning |
 | `--log-file` | Path to the log file (default: `<cache-dir>/logs/<timestamp>.log`) |
 
@@ -114,10 +114,10 @@ These flags are to work with custom approximations:
 | Flag | Description |
 |------|-------------|
 | `--track-external-methods` | Write external-method coverage files next to the SARIF report |
-| `--passthrough-approximations` | Apply pass-through approximation YAML files or directories (repeatable) |
-| `--dataflow-approximations` | Apply dataflow approximation classes or Java source directories (repeatable) |
+| `--passthrough-models` | Apply pass-through model YAML files or directories (repeatable) |
+| `--java-models` | Apply Java dataflow model classes or source directories (repeatable) |
 
-Use external-method tracking when a scan may miss flows through library methods. The dropped-methods file shows where taint was killed because no model was available; the approximated-methods file shows methods already covered by built-in or custom models.
+Use external-method tracking when a scan may miss flows through library methods. The dropped-methods file shows where taint was killed because no model was available. The approximated-methods file shows methods already covered by built-in or custom models.
 
 ### opentaint health
 
@@ -129,7 +129,7 @@ opentaint health --rules
 opentaint health --analyzer
 ```
 
-With no flags, `health` shows the autobuilder, analyzer, built-in rules, and Java runtime. With a single component flag, it prints only the bare path, which is useful for scripts.
+With no flags, `health` shows the autobuilder, analyzer, built-in rules, and Java runtime, and reports whether each is present. With a single component flag, it prints only the bare path, which is useful for scripts. The command exits non-zero when a selected component is missing. Fetch missing components with `opentaint pull`.
 
 | Flag | Description |
 |------|-------------|
@@ -155,7 +155,7 @@ opentaint test rule reachability java/security/my-rule.yaml:my-rule --project-mo
 |---------|-------------|
 | `opentaint test rule init <output-dir>` | Create source and sink test projects with annotated sample support |
 | `opentaint test rule run <project-model>` | Run detection-rule tests on a compiled project model |
-| `opentaint test rule reachability <rule-id> [source-path]` | Trace why a rule can or cannot reach its facts |
+| `opentaint test rule reachability <rule-id> [source-path]` | Show why a rule does or does not fire |
 
 #### Approximation tests
 
@@ -163,13 +163,13 @@ opentaint test rule reachability java/security/my-rule.yaml:my-rule --project-mo
 opentaint test approximation init .opentaint/test-projects/my-approximation
 opentaint compile .opentaint/test-projects/my-approximation -o .opentaint/test-compiled/my-approximation
 opentaint test approximation run .opentaint/test-compiled/my-approximation \
-  --dataflow-approximations .opentaint/dataflow/my-approximation
+  --java-models .opentaint/dataflow/my-approximation
 ```
 
 | Command | Description |
 |---------|-------------|
 | `opentaint test approximation init <output-dir>` | Create a test project with a fixed `Taint.source()` to `Taint.sink(...)` harness |
-| `opentaint test approximation run <project-model>` | Run dataflow approximation tests on a compiled project model |
+| `opentaint test approximation run <project-model>` | Run dataflow-approximation tests on a compiled project model |
 
 Rule and approximation test runs write `test-result.json` and `test-results.sarif` to the selected output directory.
 
@@ -184,20 +184,20 @@ opentaint scan --project-model ./my-project-model
 
 | Flag | Description |
 |------|-------------|
-| `--output`, `-o` | Path to the result project model (required) |
+| `--output`, `-o` | Path to the project model directory to create (required, must not exist) |
 | `--dry-run` | Validate inputs and show what would run without compiling |
 | `--log-file` | Path to the log file (default: `<cache-dir>/logs/<timestamp>.log`) |
 
 ### opentaint summary
 
-View findings from a SARIF report. By default it prints the Scan Summary; add
+View findings from a SARIF report. By default it prints the Scan Summary. Add
 `--show-findings` for the detailed listing. The filter flags below narrow the
-whole summary (both the counts and the listing); `Rules executed` always
+whole summary (both the counts and the listing). `Rules executed` always
 reflects the full set the tool ran.
 
 | Flag | Description |
 |------|-------------|
-| `--show-findings` | Show all findings |
+| `--show-findings` | Show every finding in the SARIF report |
 | `--show-code-snippets` | Show code snippets for each finding |
 | `--verbose-flow` | Show full code flow steps for each finding |
 | `--path` | Show only findings whose file path matches this glob (`**` supported, repeatable) |
@@ -224,12 +224,12 @@ opentaint scan --project-model ./project-model
 
 | Flag | Description |
 |------|-------------|
-| `--output`, `-o` | Output directory for project.yaml (required) |
-| `--source-root` | Source root directory (required) |
-| `--classpath` | Classpath entries — classes or JAR files (required) |
-| `--package` | Project packages (required) |
-| `--dependency` | Project dependencies — JAR files |
-| `--dry-run` | Validate inputs and show what would run without generating project model |
+| `--output`, `-o` | Directory to write the generated project model (required, must not exist) |
+| `--source-root` | Path to the project source root (required) |
+| `--classpath` | Classpath entries: compiled classes directories or JAR files (required, repeatable) |
+| `--package` | Packages to include in the generated model (required, repeatable) |
+| `--dependency` | Additional dependency JAR files on the compile classpath (repeatable) |
+| `--dry-run` | Validate inputs and show what would run without generating the project model |
 | `--log-file` | Path to the log file (default: `<cache-dir>/logs/<timestamp>.log`) |
 
 ## Model Caching
@@ -267,6 +267,6 @@ These options apply to all commands:
 - `--java-version int` — Java version for analyzer (default: 21)
 - `--quiet` / `-q` — Suppress interactive output (spinners, progress bars, JAR streaming)
 - `--debug` / `-d` — Enable debug output (stream JAR subprocess output, show debug fields)
-- `--color string` — Color mode (`auto`, `always`, `never`); defaults to `auto` (detects terminal)
+- `--color string` — Color mode (`auto`, `always`, `never`), defaults to `auto` (detects terminal)
 
 For persistent configuration using files or environment variables, see the [Configuration](configuration.md) documentation.
diff --git a/skills-templates/create-dataflow-approximation/references/java.md.j2 b/skills-templates/create-dataflow-approximation/references/java.md.j2
index 523eb6e5b..943916079 100644
--- a/skills-templates/create-dataflow-approximation/references/java.md.j2
+++ b/skills-templates/create-dataflow-approximation/references/java.md.j2
@@ -65,7 +65,7 @@ Run `test approximation run` over the compiled test project applying this batch'
 ```bash
 opentaint test approximation run .opentaint/test-compiled/<batch> \
   -o .opentaint/test-results/<batch> \
-  --dataflow-approximations .opentaint/dataflow/<batch>
+  --java-models .opentaint/dataflow/<batch>
 ```
 
 `test approximation run` applies its own bundled fixed source→sink rule automatically — you don't author or pass one. The CLI auto-compiles the `.java` sources against the analyzer JAR (for `@Approximate`, `OpentaintNdUtil`, `ArgumentTypeContext`) and the project's dependencies; if compilation fails it reports the errors and aborts before the tests. A positive sample is a `falseNegative` until the model propagates taint. Read the result with the bundled script — it prints the pass/fail counts and names each failing sample, so you don't parse the JSON by hand:
diff --git a/skills-templates/create-rule/references/debugging.md.j2 b/skills-templates/create-rule/references/debugging.md.j2
index dd8fce4a0..bd2774264 100644
--- a/skills-templates/create-rule/references/debugging.md.j2
+++ b/skills-templates/create-rule/references/debugging.md.j2
@@ -8,7 +8,7 @@ When a positive won't pass and the suspicion is a library method on its flow dro
 opentaint scan --project-model .opentaint/test-compiled/<unit>/<side> \
   -o .opentaint/test-results/<unit>/<side>/diag.sarif \
   --ruleset builtin --ruleset .opentaint/rules --ruleset .opentaint/test-projects/<unit>/<side>/test-rules \
-  --passthrough-approximations .opentaint/pass-through \
+  --passthrough-models .opentaint/pass-through \
   --track-external-methods
 ```
 
diff --git a/skills-templates/create-rule/sections/workflow.md b/skills-templates/create-rule/sections/workflow.md
index 61858ed2e..8269c9db1 100644
--- a/skills-templates/create-rule/sections/workflow.md
+++ b/skills-templates/create-rule/sections/workflow.md
@@ -24,7 +24,7 @@ Run the rule tests directly as a foreground, blocking command and wait for exit
 opentaint test rule run .opentaint/test-compiled/<unit>/<side> \
   -o .opentaint/test-results/<unit>/<side> \
   --ruleset .opentaint/rules --ruleset .opentaint/test-projects/<unit>/<side>/test-rules \
-  --passthrough-approximations .opentaint/pass-through
+  --passthrough-models .opentaint/pass-through
 ```
 
 `test rule run` auto-loads the built-in rules, so pass only your custom rulesets. Apply the passthrough approximations as-is, an empty one is harmless. Read the result with the bundled script — it prints the pass/fail counts and names the failing samples, so you never parse the JSON by hand:
diff --git a/skills-templates/debug-rule/sections/workflow.md b/skills-templates/debug-rule/sections/workflow.md
index 3a490974f..888b296d2 100644
--- a/skills-templates/debug-rule/sections/workflow.md
+++ b/skills-templates/debug-rule/sections/workflow.md
@@ -7,8 +7,8 @@ opentaint test rule reachability <rule> \
   --project-model <model> \
   -o <results-dir>/report.sarif \
   --ruleset builtin --ruleset .opentaint/rules \
-  --passthrough-approximations .opentaint/pass-through \
-  --dataflow-approximations .opentaint/dataflow
+  --passthrough-models .opentaint/pass-through \
+  --java-models .opentaint/dataflow
 ```
 
 `<results-dir>` is `.opentaint/test-results/<name>` for a test model, `.opentaint/results` for the main scan. The per-instruction facts are in the sibling `<results-dir>/debug-ifds-fact-reachability.sarif`, not the `-o` file — the `-o` SARIF only shows whether the rule fired. Read that sibling to find the kill:
diff --git a/skills-templates/run-scan/sections/workflow.md b/skills-templates/run-scan/sections/workflow.md
index aeab157e3..6ddb900c2 100644
--- a/skills-templates/run-scan/sections/workflow.md
+++ b/skills-templates/run-scan/sections/workflow.md
@@ -10,8 +10,8 @@ opentaint scan --project-model .opentaint/project \
 ```
 
 - `--rule-id <full-id>` — restrict to specific rules (repeatable, one per input rule ID); every unnamed rule is dropped, including library `refs`, so list every id the restricted rules depend on. Omit to run all loaded rules
-- `--passthrough-approximations .opentaint/pass-through` — add when that directory exists: passThrough configs override built-ins at the rule level, a provided rule overriding a built-in only when it matches one
-- `--dataflow-approximations .opentaint/dataflow` — add when that directory exists: code-based approximations (sources auto-compiled; pre-compiled `.class` dirs passed through as-is)
+- `--passthrough-models .opentaint/pass-through` — add when that directory exists: passThrough configs override built-ins at the rule level, a provided rule overriding a built-in only when it matches one
+- `--java-models .opentaint/dataflow` — add when that directory exists: code-based approximations (sources auto-compiled; pre-compiled `.class` dirs passed through as-is)
 
 Both approximation-dir flags walk their trees recursively; pass each parent directory once, not every package or batch separately.
 
diff --git a/skills-templates/shared/debugging.md b/skills-templates/shared/debugging.md
index 8b7ce3171..8d80bd6ce 100644
--- a/skills-templates/shared/debugging.md
+++ b/skills-templates/shared/debugging.md
@@ -15,7 +15,7 @@ opentaint test rule reachability <full-id> \
 
 - `<full-id>` — the one rule whose sample routes taint through the code under test (`<ruleSetRelativePath>.yaml:<shortId>`). One rule per run — across many rules the trace is unusably huge. Its library `refs` are collected automatically
 - read the sibling `<results-dir>/debug-ifds-fact-reachability.sarif`, not the `-o` file. The `-o` SARIF only shows default scan output. The sibling holds the per-instruction facts that show where taint dies
-- apply the approximations the failing run used so the trace matches it: `--passthrough-approximations <pass-through-dir>` and/or `--dataflow-approximations <dataflow-dir>`. Taint dying at an approximated call then means that approximation isn't propagating
+- apply the approximations the failing run used so the trace matches it: `--passthrough-models <pass-through-dir>` and/or `--java-models <dataflow-dir>`. Taint dying at an approximated call then means that approximation isn't propagating
 - debug the exact run that showed the problem — same model, rulesets, approximation dirs — or you're debugging something else
 
 ## Reading the trace
diff --git a/skills/create-dataflow-approximation/references/debugging.md b/skills/create-dataflow-approximation/references/debugging.md
index 8b7ce3171..8d80bd6ce 100644
--- a/skills/create-dataflow-approximation/references/debugging.md
+++ b/skills/create-dataflow-approximation/references/debugging.md
@@ -15,7 +15,7 @@ opentaint test rule reachability <full-id> \
 
 - `<full-id>` — the one rule whose sample routes taint through the code under test (`<ruleSetRelativePath>.yaml:<shortId>`). One rule per run — across many rules the trace is unusably huge. Its library `refs` are collected automatically
 - read the sibling `<results-dir>/debug-ifds-fact-reachability.sarif`, not the `-o` file. The `-o` SARIF only shows default scan output. The sibling holds the per-instruction facts that show where taint dies
-- apply the approximations the failing run used so the trace matches it: `--passthrough-approximations <pass-through-dir>` and/or `--dataflow-approximations <dataflow-dir>`. Taint dying at an approximated call then means that approximation isn't propagating
+- apply the approximations the failing run used so the trace matches it: `--passthrough-models <pass-through-dir>` and/or `--java-models <dataflow-dir>`. Taint dying at an approximated call then means that approximation isn't propagating
 - debug the exact run that showed the problem — same model, rulesets, approximation dirs — or you're debugging something else
 
 ## Reading the trace
diff --git a/skills/create-dataflow-approximation/references/java.md b/skills/create-dataflow-approximation/references/java.md
index 523eb6e5b..943916079 100644
--- a/skills/create-dataflow-approximation/references/java.md
+++ b/skills/create-dataflow-approximation/references/java.md
@@ -65,7 +65,7 @@ Run `test approximation run` over the compiled test project applying this batch'
 ```bash
 opentaint test approximation run .opentaint/test-compiled/<batch> \
   -o .opentaint/test-results/<batch> \
-  --dataflow-approximations .opentaint/dataflow/<batch>
+  --java-models .opentaint/dataflow/<batch>
 ```
 
 `test approximation run` applies its own bundled fixed source→sink rule automatically — you don't author or pass one. The CLI auto-compiles the `.java` sources against the analyzer JAR (for `@Approximate`, `OpentaintNdUtil`, `ArgumentTypeContext`) and the project's dependencies; if compilation fails it reports the errors and aborts before the tests. A positive sample is a `falseNegative` until the model propagates taint. Read the result with the bundled script — it prints the pass/fail counts and names each failing sample, so you don't parse the JSON by hand:
diff --git a/skills/create-rule/SKILL.md b/skills/create-rule/SKILL.md
index 323c89356..d3dfe112d 100644
--- a/skills/create-rule/SKILL.md
+++ b/skills/create-rule/SKILL.md
@@ -49,7 +49,7 @@ Run the rule tests directly as a foreground, blocking command and wait for exit
 opentaint test rule run .opentaint/test-compiled/<unit>/<side> \
   -o .opentaint/test-results/<unit>/<side> \
   --ruleset .opentaint/rules --ruleset .opentaint/test-projects/<unit>/<side>/test-rules \
-  --passthrough-approximations .opentaint/pass-through
+  --passthrough-models .opentaint/pass-through
 ```
 
 `test rule run` auto-loads the built-in rules, so pass only your custom rulesets. Apply the passthrough approximations as-is, an empty one is harmless. Read the result with the bundled script — it prints the pass/fail counts and names the failing samples, so you never parse the JSON by hand:
diff --git a/skills/create-rule/references/debugging.md b/skills/create-rule/references/debugging.md
index e6d8f8ad1..b280d46ea 100644
--- a/skills/create-rule/references/debugging.md
+++ b/skills/create-rule/references/debugging.md
@@ -15,7 +15,7 @@ opentaint test rule reachability <full-id> \
 
 - `<full-id>` — the one rule whose sample routes taint through the code under test (`<ruleSetRelativePath>.yaml:<shortId>`). One rule per run — across many rules the trace is unusably huge. Its library `refs` are collected automatically
 - read the sibling `<results-dir>/debug-ifds-fact-reachability.sarif`, not the `-o` file. The `-o` SARIF only shows default scan output. The sibling holds the per-instruction facts that show where taint dies
-- apply the approximations the failing run used so the trace matches it: `--passthrough-approximations <pass-through-dir>` and/or `--dataflow-approximations <dataflow-dir>`. Taint dying at an approximated call then means that approximation isn't propagating
+- apply the approximations the failing run used so the trace matches it: `--passthrough-models <pass-through-dir>` and/or `--java-models <dataflow-dir>`. Taint dying at an approximated call then means that approximation isn't propagating
 - debug the exact run that showed the problem — same model, rulesets, approximation dirs — or you're debugging something else
 
 ## Reading the trace
@@ -35,7 +35,7 @@ When a positive won't pass and the suspicion is a library method on its flow dro
 opentaint scan --project-model .opentaint/test-compiled/<unit>/<side> \
   -o .opentaint/test-results/<unit>/<side>/diag.sarif \
   --ruleset builtin --ruleset .opentaint/rules --ruleset .opentaint/test-projects/<unit>/<side>/test-rules \
-  --passthrough-approximations .opentaint/pass-through \
+  --passthrough-models .opentaint/pass-through \
   --track-external-methods
 ```
 
diff --git a/skills/debug-rule/SKILL.md b/skills/debug-rule/SKILL.md
index 0907d496d..d5a1d464b 100644
--- a/skills/debug-rule/SKILL.md
+++ b/skills/debug-rule/SKILL.md
@@ -30,8 +30,8 @@ opentaint test rule reachability <rule> \
   --project-model <model> \
   -o <results-dir>/report.sarif \
   --ruleset builtin --ruleset .opentaint/rules \
-  --passthrough-approximations .opentaint/pass-through \
-  --dataflow-approximations .opentaint/dataflow
+  --passthrough-models .opentaint/pass-through \
+  --java-models .opentaint/dataflow
 ```
 
 `<results-dir>` is `.opentaint/test-results/<name>` for a test model, `.opentaint/results` for the main scan. The per-instruction facts are in the sibling `<results-dir>/debug-ifds-fact-reachability.sarif`, not the `-o` file — the `-o` SARIF only shows whether the rule fired. Read that sibling to find the kill:
diff --git a/skills/run-scan/SKILL.md b/skills/run-scan/SKILL.md
index 8c363c092..c81bad9ad 100644
--- a/skills/run-scan/SKILL.md
+++ b/skills/run-scan/SKILL.md
@@ -33,8 +33,8 @@ opentaint scan --project-model .opentaint/project \
 ```
 
 - `--rule-id <full-id>` — restrict to specific rules (repeatable, one per input rule ID); every unnamed rule is dropped, including library `refs`, so list every id the restricted rules depend on. Omit to run all loaded rules
-- `--passthrough-approximations .opentaint/pass-through` — add when that directory exists: passThrough configs override built-ins at the rule level, a provided rule overriding a built-in only when it matches one
-- `--dataflow-approximations .opentaint/dataflow` — add when that directory exists: code-based approximations (sources auto-compiled; pre-compiled `.class` dirs passed through as-is)
+- `--passthrough-models .opentaint/pass-through` — add when that directory exists: passThrough configs override built-ins at the rule level, a provided rule overriding a built-in only when it matches one
+- `--java-models .opentaint/dataflow` — add when that directory exists: code-based approximations (sources auto-compiled; pre-compiled `.class` dirs passed through as-is)
 
 Both approximation-dir flags walk their trees recursively; pass each parent directory once, not every package or batch separately.