From 334dd617f74f479683189ca666c39d7bc80e85b9 Mon Sep 17 00:00:00 2001
From: Alexander Medvednikov <alexander@medvednikov.com>
Date: Tue, 14 Apr 2026 12:45:26 +0300
Subject: [PATCH] all: Help text and possibly wrong behaviour of 'run' command
 (fixes #15520)

---
 vlib/v/help/common/crun.txt |  8 ++++----
 vlib/v/help/common/run.txt  |  2 ++
 vlib/v/help/default.txt     |  6 +++---
 vlib/v/help/help_test.v     | 15 +++++++++++++++
 4 files changed, 24 insertions(+), 7 deletions(-)

diff --git a/vlib/v/help/common/crun.txt b/vlib/v/help/common/crun.txt
index ce32f70cb..5b6324008 100644
--- a/vlib/v/help/common/crun.txt
+++ b/vlib/v/help/common/crun.txt
@@ -1,6 +1,6 @@
-Equivalent to running `v run`, which builds and runs compiled executable.
-The differences is, that `v crun` will store executable and will recompile
-only when project files are changed.
+Equivalent to running `v run`, which builds and runs a compiled executable.
+The difference is that `v crun` keeps the executable and recompiles only
+when project files are changed.
 
 Usage:
-  v [build flags] crun <file.v|directory|-> [arguments...]
\ No newline at end of file
+  v [build flags] crun <file.v|directory|-> [arguments...]
diff --git a/vlib/v/help/common/run.txt b/vlib/v/help/common/run.txt
index a3b8b825b..076af8e61 100644
--- a/vlib/v/help/common/run.txt
+++ b/vlib/v/help/common/run.txt
@@ -6,6 +6,8 @@ Usage:
 This command is equivalent to running `v build` and running the compiled
 executable.
 The executable is passed the arguments as provided in [arguments...].
+If `v run` created the executable for this run, it is deleted afterwards.
+If the executable already existed before the command, it is kept.
 
 If the target is '-', it means that the V source code to build comes from stdin.
 If the '-o' option is not specified, and the target is '-', a temporary base
diff --git a/vlib/v/help/default.txt b/vlib/v/help/default.txt
index d4ce082c3..c173778f5 100644
--- a/vlib/v/help/default.txt
+++ b/vlib/v/help/default.txt
@@ -38,9 +38,9 @@ V supports the following commands:
 
 * Commonly Used Utilities:
   run                          Compile and run a V program. Delete the
-                               executable after the run.
-  crun                         Compile and run a V program without deleting the
-                               executable.
+                               executable if V created it for this run.
+  crun                         Compile and run a V program, keeping the
+                               executable for reuse.
                                If you run the same program a second time,
                                without changing the source files,
                                V will just run the executable, without
diff --git a/vlib/v/help/help_test.v b/vlib/v/help/help_test.v
index 88d553607..3720117af 100644
--- a/vlib/v/help/help_test.v
+++ b/vlib/v/help/help_test.v
@@ -20,6 +20,21 @@ fn test_help_as_long_option() {
 	assert res.output.starts_with('V is a tool for managing V source code.')
 }
 
+fn test_run_help_text() {
+	res := os.execute(vexe + ' help')
+	assert res.exit_code == 0, res.output
+	assert res.output.contains('executable if V created it for this run.')
+	assert res.output.contains('Compile and run a V program, keeping the')
+	assert res.output.contains('executable for reuse.')
+}
+
+fn test_run_topic_mentions_conditional_cleanup() {
+	res := os.execute(vexe + ' help run')
+	assert res.exit_code == 0, res.output
+	assert res.output.contains('If `v run` created the executable for this run')
+	assert res.output.contains('If the executable already existed before the command')
+}
+
 fn test_all_topics() {
 	help_dir := os.join_path(@VEXEROOT, 'vlib', 'v', 'help')
 	topic_paths := os.walk_ext(help_dir, '.txt')
-- 
2.39.5