Document and enforce that just recipe arguments are positional

Justfile

@@ -20,6 +20,10 @@ default:
     @echo "  just security-check # Check dependency/security policy"
     @echo "  just doctor         # Diagnose environment problems"
     @echo ""
+    @echo "Recipe arguments are positional. Entries like 'build profile=\"debug\"' below are"
+    @echo "signatures (parameter name + default), so run 'just build release', not"
+    @echo "'just build profile=release' -- the latter passes the literal text 'profile=release'."
+    @echo ""
     @echo "All commands:"
     @just --list --list-heading ''
 
@@ -285,7 +289,7 @@ pytest *args:
 
 # Run the substantive PR Python lane after building the test-only native bindings it needs.
 [group('test')]
-python-ci-core profile="debug": (python-ci-build-test profile)
+python-ci-core profile="debug": (validate-profile "python-ci-core" profile) (python-ci-build-test profile)
     just pytest-ci-core
 
 # Fast Python validation for PR CI. Selene plugin coverage stays in its own workflow.
@@ -297,7 +301,7 @@ pytest-ci-core:
 
 # Build and import the core Python packages on a target platform/interpreter.
 [group('test')]
-python-ci-smoke profile="debug": (python-ci-build profile)
+python-ci-smoke profile="debug": (validate-profile "python-ci-smoke" profile) (python-ci-build profile)
     uv run --frozen python -c "from importlib.metadata import version; import pecos, pecos_rslib, pecos_rslib_llvm; print({'pecos': pecos.__version__, 'pecos_rslib': pecos_rslib.__version__, 'pecos_rslib_llvm': version('pecos-rslib-llvm')})"
 
 # Run Rust tests (CUDA-aware; mode: dev/debug, release, native)
@@ -446,11 +450,20 @@ bench profile="release" features="" pattern="": _msvc-bootstrap (validate-bench-
     PROFILE="{{profile}}"
     FEATURES="{{features}}"
     PATTERN="{{pattern}}"
+    # A named-looking argument can land in any slot, so each slot rejects every
+    # parameter name -- otherwise 'just bench release pattern=foo' would reach
+    # cargo as '--features pattern=foo'.
     case "$FEATURES" in
         features=*)
             VALUE="${FEATURES#features=}"
             echo "Invalid features argument: $FEATURES"
-            echo "Just recipe parameters are positional. Use: just bench $PROFILE $VALUE"
+            echo "Just recipe parameters are positional. Use: just bench $PROFILE '$VALUE'"
+            exit 2
+            ;;
+        pattern=*)
+            VALUE="${FEATURES#pattern=}"
+            echo "Invalid features argument: $FEATURES"
+            echo "Just recipe parameters are positional. Use: just bench $PROFILE '' '$VALUE'"
             exit 2
             ;;
     esac
@@ -461,6 +474,12 @@ bench profile="release" features="" pattern="": _msvc-bootstrap (validate-bench-
             echo "Just recipe parameters are positional. Use: just bench $PROFILE '$FEATURES' '$VALUE'"
             exit 2
             ;;
+        features=*)
+            VALUE="${PATTERN#features=}"
+            echo "Invalid pattern argument: $PATTERN"
+            echo "Just recipe parameters are positional. Use: just bench $PROFILE '$VALUE'"
+            exit 2
+            ;;
     esac
     ARGS=(bench -p benchmarks --bench benchmarks)
     if [ "$PROFILE" = "native" ]; then

docs/development/dev-tools.md

@@ -62,6 +62,21 @@ Most development tasks are managed through the Justfile. Make sure you have `jus
 cargo install just
 ```
 
+### Passing arguments to a recipe
+
+`just --list` (and `just` with no arguments) prints each recipe as a signature, such as
+`build profile="debug"`. That names the parameter and its default; it is not the syntax for
+calling the recipe. Recipe arguments are positional:
+
+```bash
+just build release             # correct
+just build profile=release     # wrong: passes the literal text "profile=release"
+```
+
+The `name=value` form is reserved for overriding top-level variables, and only works before the
+recipe name (`just pecos="..." build`). After a recipe name, `name=value` is consumed as an ordinary
+positional argument.
+
 ### Quick Reference
 
 ```bash