Document and test -- separator behavior with installables

Clarifies that the first positional argument is always treated as the
installable, even after --. Adds tests to prevent accidental change.

Addresses #13994

Author: roberth

src/nix/run.md

@@ -33,6 +33,16 @@ R""(
   # nix run nixpkgs#vim -- --help
   ```
 
+* Run the default app from the current directory with arguments:
+
+  ```console
+  # nix run . -- arg1 arg2
+  ```
+
+  Note: The first positional argument is always treated as the *installable*,
+  even after `--`. To pass arguments to the default installable, specify it
+  explicitly: `nix run . -- arg1 arg2` or `nix run -- . arg1 arg2`.
+
 # Description
 
 `nix run` builds and runs [*installable*](./nix.md#installables), which must evaluate to an

tests/functional/flakes/run.sh

@@ -55,5 +55,41 @@ echo "_=..." >> "$TEST_ROOT"/actual-env
 sort "$TEST_ROOT"/actual-env | uniq > "$TEST_ROOT"/actual-env.sorted
 diff "$TEST_ROOT"/expected-env.sorted "$TEST_ROOT"/actual-env.sorted
 
+# Test for issue #13994: verify behavior of -- separator with installable
+# Create a flake with an app that prints its arguments
 clearStore
+rm -rf "$TEST_HOME"/.cache "$TEST_HOME"/.config "$TEST_HOME"/.local
+cd "$TEST_HOME"
+
+cat <<'EOF' > print-args.sh
+#!/bin/sh
+printf "ARGS:"
+for arg in "$@"; do
+    printf " %s" "$arg"
+done
+printf "\n"
+EOF
+chmod +x print-args.sh
+
+cat <<EOF > flake.nix
+{
+  outputs = {self}: {
+    apps.$system.default = {
+      type = "app";
+      program = "\${self}/print-args.sh";
+    };
+  };
+}
+EOF
+
+# Test correct usage: installable before --
+output=$(nix run --no-write-lock-file . -- myarg1 myarg2 2>&1)
+[[ "$output" == "ARGS: myarg1 myarg2" ]] || fail "Expected 'ARGS: myarg1 myarg2', got '$output'"
+
+# Test that first positional argument is still treated as installable after -- (issue #13994)
+output=$(nix run --no-write-lock-file -- . myarg1 myarg2 2>&1)
+[[ "$output" == "ARGS: myarg1 myarg2" ]] || fail "Expected 'ARGS: myarg1 myarg2', got '$output'"
+
+# And verify that a non-installable first argument causes an error
+expectStderr 1 nix run --no-write-lock-file -- myarg1 myarg2 | grepQuiet "error.*myarg1"