diff --git a/Dockerfile b/Dockerfile
index 20a3d675..45ca0ae0 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -27,7 +27,6 @@
 #     --ensemble-sizes "1 4" \
 #     --gradient-weights "0.1 0.2" \
 #     --output-dir /data/results \
-#     --use-tweedie \
 #     --gradient-normalization \
 #     --augmentation \
 #     --align-to-input
@@ -41,8 +40,7 @@
 #     --methods "X-RAY DIFFRACTION" \
 #     --ensemble-sizes "1 4" \
 #     --gradient-weights "0.1 0.2" \
-#     --output-dir /data/results \
-#     --use-tweedie
+#     --output-dir /data/results
 #
 #   # Interactive shell
 #   docker run --gpus all -it sampleworks bash
@@ -64,6 +62,9 @@
 # ============================================================================
 FROM nvidia/cuda:12.4.1-devel-ubuntu22.04 AS base
 
+ARG SAMPLEWORKS_GIT_SHA=unknown
+ARG SAMPLEWORKS_IMAGE_TAG=unknown
+
 ENV DEBIAN_FRONTEND=noninteractive \
     # Pixi configuration
     PIXI_HOME=/root/.pixi \
@@ -74,7 +75,12 @@ ENV DEBIAN_FRONTEND=noninteractive \
     # Disable user site packages (isolation)
     PYTHONNOUSERSITE=1 \
     # Optimize CUDA compilation for H100
-    TORCH_CUDA_ARCH_LIST="9.0"
+    TORCH_CUDA_ARCH_LIST="9.0" \
+    SAMPLEWORKS_GIT_SHA=${SAMPLEWORKS_GIT_SHA} \
+    SAMPLEWORKS_IMAGE_TAG=${SAMPLEWORKS_IMAGE_TAG}
+
+LABEL org.opencontainers.image.revision=${SAMPLEWORKS_GIT_SHA} \
+      org.opencontainers.image.version=${SAMPLEWORKS_IMAGE_TAG}
 
 # Install system dependencies required for building scientific packages
 RUN apt-get update && apt-get install -y --no-install-recommends \
diff --git a/GRID_SEARCH.md b/GRID_SEARCH.md
index 154d00c5..e50bfb16 100644
--- a/GRID_SEARCH.md
+++ b/GRID_SEARCH.md
@@ -26,8 +26,8 @@ protein structure, density map, and resolution columns, described below.
 ```bash
 pixi run -e boltz python run_grid_search.py \
     --proteins proteins.csv \
-    --models boltz2 \                # options: boltz1, boltz2, protenix, rf3 (make sure env aligns!)
-    --methods "X-RAY DIFFRACTION" \  # only useful for Boltz-2, ignored otherwise
+    --model boltz2 \                 # options: boltz1, boltz2, protenix, rf3 (make sure env aligns!)
+    --method "X-RAY DIFFRACTION" \   # only useful for Boltz-2, ignored otherwise
     --scalers pure_guidance \        # options: pure_guidance, fk_steering, or both as space-separated list
     --ensemble-sizes "1 4" \
     --gradient-weights "0.1 0.2" \
@@ -51,11 +51,11 @@ name,structure,density,resolution
 | Argument             | Description                                                | Default                     |
 |----------------------|------------------------------------------------------------|-----------------------------|
 | `--proteins`         | CSV with structure/density/resolution columns              | required                    |
-| `--models`           | Model to run. One of `boltz1`, `boltz2`, `protenix`, `rf3` | required                    |
+| `--model`            | Model to run. One of `boltz1`, `boltz2`, `protenix`, `rf3` | required                    |
 | `--scalers`          | Guidance method(s) to sweep                                | `pure_guidance fk_steering` |
 | `--ensemble-sizes`   | Space-separated values, e.g. `"1 4"`                       | `"1 2 4 8"`                 |
 | `--gradient-weights` | Space-separated values, e.g. `"0.1 0.2"`                   | `"0.01 0.1 0.2"`            |
-| `--methods`          | Boltz-2 sampling method (required for boltz2)              | `X-RAY DIFFRACTION`         |
+| `--method`           | Boltz-2 sampling method (required for boltz2)              | `X-RAY DIFFRACTION`         |
 | `--max-parallel`     | Parallel workers (default: number of GPUs)                 | `auto`                      |
 | `--dry-run`          | Print jobs without running them                            | off                         |
 | `--force-all`        | Re-run including already-successful jobs                   | off                         |
@@ -65,7 +65,7 @@ name,structure,density,resolution
 | `--track-chiral-features` | Track RF3 chiral gradient magnitude                   | off                         |
 
 > **Note**: Jobs are skipped if a `refined.cif` file already exists in the output directory.
-> Some flags (e.g., `--use-tweedie`, `--gradient-normalization`) are not reflected in the
+> Some flags (e.g., `--gradient-normalization`) are not reflected in the
 > directory structure, so changing them alone won't trigger a re-run. Use `--force-all` to
 > re-run all jobs regardless. This is under active development and will likely change soon.
 
diff --git a/README.md b/README.md
index 7087c139..84d63cdf 100644
--- a/README.md
+++ b/README.md
@@ -88,8 +88,8 @@ Output files appear in `output/boltz2_pure_guidance/`: `refined.cif` (final ense
 ```bash
 pixi run -e boltz python run_grid_search.py \
     --proteins proteins.csv \
-    --models boltz2 \                # options: boltz1, boltz2, protenix, rf3 (make sure env aligns!)
-    --methods "X-RAY DIFFRACTION" \  # only useful for Boltz-2, ignored otherwise
+    --model boltz2 \                 # options: boltz1, boltz2, protenix, rf3 (make sure env aligns!)
+    --method "X-RAY DIFFRACTION" \   # only useful for Boltz-2, ignored otherwise
     --scalers pure_guidance \        # options: pure_guidance, fk_steering, or both as space-separated list
     --ensemble-sizes "1 4" \
     --gradient-weights "0.1 0.2" \
@@ -113,11 +113,11 @@ name,structure,density,resolution
 | Argument | Description | Default |
 |---|---|---|
 | `--proteins` | CSV with structure/density/resolution columns | required |
-| `--models` | Model to run. One of `boltz1`, `boltz2`, `protenix`, `rf3` | required |
+| `--model` | Model to run. One of `boltz1`, `boltz2`, `protenix`, `rf3` | required |
 | `--scalers` | Guidance method(s) to sweep | `pure_guidance fk_steering` |
 | `--ensemble-sizes` | Space-separated values, e.g. `"1 4"` | `"1 2 4 8"` |
 | `--gradient-weights` | Space-separated values, e.g. `"0.1 0.2"` | `"0.01 0.1 0.2"` |
-| `--methods` | Boltz-2 sampling method (required for boltz2) | `X-RAY DIFFRACTION` |
+| `--method` | Boltz-2 sampling method (required for boltz2) | `X-RAY DIFFRACTION` |
 | `--max-parallel` | Parallel workers (default: number of GPUs) | `auto` |
 | `--dry-run` | Print jobs without running them | off |
 | `--force-all` | Re-run including already-successful jobs | off |
@@ -126,7 +126,7 @@ name,structure,density,resolution
 
 Output layout: `grid_search_results/<protein>/<model>[_<method>]/<scaler>/ens<N>_gw<W>/`
 
-> **Note**: Jobs are skipped if a `refined.cif` file already exists in the output directory. Some flags (e.g., `--use-tweedie`, `--gradient-normalization`) are not reflected in the directory structure, so changing them alone won't trigger a re-run. Use `--force-all` to re-run all jobs regardless. This is under active development and will likely change soon.
+> **Note**: Jobs are skipped if a `refined.cif` file already exists in the output directory. Some flags (e.g., `--gradient-normalization`) are not reflected in the directory structure, so changing them alone won't trigger a re-run. Use `--force-all` to re-run all jobs regardless. This is under active development and will likely change soon.
 
 Instructions for running evaluation and metrics scripts are coming soon.
 
diff --git a/diffuse.yaml b/diffuse.yaml
new file mode 100644
index 00000000..bdec6330
--- /dev/null
+++ b/diffuse.yaml
@@ -0,0 +1,60 @@
+# diffuse.yaml -- the contract between Sampleworks and Diffuse.
+#
+# Apply with: diffuse apply
+# Run with:   diffuse run sampleworks --params params.json --output-dir /data/results/run-001
+#
+# Idempotent -- safe to apply repeatedly.
+
+version: 1
+
+type: sampleworks
+name: Sampleworks
+description: >
+  Generic Sampleworks experiment runner. Diffuse accepts a flexible params.json
+  blob, stores it for traceability, materializes it inside the pod, and lets
+  Sampleworks own validation and model-specific execution.
+
+profiles:
+  - slug: sampleworks
+    name: Sampleworks
+    container:
+      image: diffuseproject/sampleworks
+      tag: latest
+      gpus:
+        min: 2
+    entrypoint: null
+    input_schema:
+      inputs:
+        - key: params_json
+          type: json
+          required: true
+          description: Arbitrary Sampleworks-owned params.json object.
+        - key: output_dir
+          type: text
+          required: true
+          default: /data/results
+          description: Container output directory, usually under /data/results.
+    run_config_defaults:
+      shared_memory_size: "16Gi"
+      image_pull_policy: IfNotPresent
+      poll_max_retries: 720
+      params_file:
+        param_key: params_json
+        path: /diffuse/input/params.json
+      volumes:
+        - name: data-input
+          hostPath: /data/sampleworks-exp/input
+          mountPath: /data/input
+          readOnly: true
+        - name: data-results
+          hostPath: /data/sampleworks-exp/grid_search_results
+          mountPath: /data/results
+        - name: msa-cache
+          hostPath: /data/sampleworks-exp/msa_cache
+          mountPath: /root/.sampleworks/msa
+      args_template:
+        base_command: [--params, /diffuse/input/params.json]
+        flag_args:
+          output_dir: --output-dir
+        boolean_args: {}
+        static_args: []
diff --git a/docker-entrypoint.sh b/docker-entrypoint.sh
index d89abc5d..45ca3bb2 100755
--- a/docker-entrypoint.sh
+++ b/docker-entrypoint.sh
@@ -4,6 +4,7 @@
 # Usage:
 #   docker run sampleworks -e <pixi_env> <script> [args...]
 #   docker run sampleworks -e boltz run_grid_search.py --proteins /data/proteins.csv ...
+#   docker run sampleworks --params /data/input/params.json --output-dir /data/results
 #   docker run sampleworks bash  # interactive shell
 #
 # Available pixi environments: boltz, protenix, rf3
@@ -18,7 +19,6 @@
 #     --ensemble-sizes "1 4" \
 #     --gradient-weights "0.1 0.2" \
 #     --output-dir /data/results \
-#     --use-tweedie \
 #     --rf3-checkpoint /data/checkpoints/rf3.ckpt
 
 set -e
@@ -29,6 +29,7 @@ Sampleworks - Protein structure prediction with diffusion model guidance
 
 USAGE:
     docker run --gpus all --shm-size=16g sampleworks -e <environment> <script> [arguments...]
+    docker run --gpus all --shm-size=16g sampleworks --params <params.json> --output-dir <dir>
     docker run sampleworks bash
     docker run sampleworks --help
 
@@ -37,6 +38,7 @@ IMPORTANT:
 
 OPTIONS:
     -e, --env <env>     Pixi environment to use (boltz, protenix, rf3)
+    --params FILE       Run grid search from a flexible params.json file
     -h, --help          Show this help message
     bash                Start an interactive shell
 
@@ -46,6 +48,11 @@ ENVIRONMENTS:
     rf3         For RF3 model
 
 EXAMPLES:
+    # Run generic Diffuse/Sampleworks params mode. The JSON chooses the model/env.
+    docker run --gpus all --shm-size=16g -v /data:/data sampleworks \
+      --params /data/input/params.json \
+      --output-dir /data/results/run-001
+
     # Run grid search with RF3 model
     docker run --gpus all --shm-size=16g -v /data:/data sampleworks \
       -e rf3 run_grid_search.py \
@@ -55,7 +62,6 @@ EXAMPLES:
       --ensemble-sizes "1 4" \
       --gradient-weights "0.1 0.2" \
       --output-dir /data/results \
-      --use-tweedie \
       --gradient-normalization \
       --augmentation \
       --align-to-input \
@@ -70,7 +76,6 @@ EXAMPLES:
       --ensemble-sizes "1 4" \
       --gradient-weights "0.1 0.2" \
       --output-dir /data/results \
-      --use-tweedie \
       --boltz1-checkpoint /data/checkpoints/boltz1_conf.ckpt
 
     # Run grid search with Boltz2 model
@@ -83,7 +88,6 @@ EXAMPLES:
       --ensemble-sizes "1 4" \
       --gradient-weights "0.1 0.2" \
       --output-dir /data/results \
-      --use-tweedie \
       --boltz2-checkpoint /data/checkpoints/boltz2_conf.ckpt
 
     # Run grid search with Protenix model
@@ -95,7 +99,6 @@ EXAMPLES:
       --ensemble-sizes "1 4" \
       --gradient-weights "0.1 0.2" \
       --output-dir /data/results \
-      --use-tweedie \
       --protenix-checkpoint /data/checkpoints/protenix_base_default_v0.5.0.pt
 
     # Interactive shell
@@ -120,7 +123,6 @@ GRID SEARCH ARGUMENTS (run_grid_search.py):
       --scalers SCALER            Guidance method (pure_guidance, fk_steering)
       --ensemble-sizes "N M..."   Space-separated ensemble sizes (e.g., "1 4")
       --gradient-weights "X Y..." Space-separated gradient weights (e.g., "0.1 0.2")
-      --use-tweedie               Use Tweedie's formula for gradient computation
       --gradient-normalization    Enable gradient normalization
       --augmentation              Enable data augmentation
       --align-to-input            Enable alignment to input structure
@@ -177,6 +179,62 @@ For full argument details, run:
 EOF
 }
 
+infer_env_from_params() {
+    local value="$1"
+    pixi run -e boltz python - "$value" << 'PY'
+import json
+import sys
+
+value = sys.argv[1]
+with open(value) as handle:
+    params = json.load(handle)
+
+if isinstance(params, dict) and isinstance(params.get("params_json"), dict):
+    params = params["params_json"]
+
+def model_value(value):
+    if value is None:
+        return None
+    if isinstance(value, dict):
+        return model_value(value.get("name") or value.get("type") or value.get("model"))
+    if isinstance(value, list):
+        if len(value) != 1:
+            raise SystemExit("Sampleworks params mode supports exactly one model")
+        return str(value[0])
+    return str(value)
+
+model = model_value(params.get("model"))
+models = params.get("models")
+if models is not None:
+    if isinstance(models, str):
+        models = models.split()
+    if not isinstance(models, list) or len(models) != 1:
+        raise SystemExit("Sampleworks params mode supports exactly one model")
+    if model is not None and str(models[0]) != model:
+        raise SystemExit("Sampleworks params JSON defines conflicting model and models values")
+    model = str(models[0])
+
+model_section = params.get("model_config") or params.get("model_settings")
+if isinstance(model_section, dict):
+    nested_model = model_value(
+        model_section.get("name") or model_section.get("type") or model_section.get("model")
+    )
+    if nested_model is not None:
+        if model is not None and nested_model != model:
+            raise SystemExit("Sampleworks params JSON defines conflicting nested model value")
+        model = nested_model
+
+if model in ("boltz1", "boltz2"):
+    print("boltz")
+elif model == "protenix":
+    print("protenix")
+elif model == "rf3":
+    print("rf3")
+else:
+    raise SystemExit("params JSON must include model: boltz1, boltz2, protenix, or rf3")
+PY
+}
+
 # Handle special cases first
 if [ $# -eq 0 ] || [ "$1" = "-h" ] || [ "$1" = "--help" ]; then
     show_help
@@ -188,6 +246,17 @@ if [ "$1" = "bash" ] || [ "$1" = "sh" ]; then
     exec "$@"
 fi
 
+# Generic params mode. Diffuse uses this path: it materializes params.json in
+# the pod, then passes --params plus --output-dir to this entrypoint.
+if [ "$1" = "--params" ]; then
+    if [ -z "$2" ] || [[ "$2" == -* ]]; then
+        echo "Error: $1 requires a value"
+        exit 1
+    fi
+    ENV="$(infer_env_from_params "$2")"
+    exec pixi run -e "$ENV" python /app/run_grid_search.py "$@"
+fi
+
 # Parse -e/--env argument
 ENV=""
 while [[ $# -gt 0 ]]; do
@@ -202,9 +271,10 @@ while [[ $# -gt 0 ]]; do
             break
             ;;
         *)
-            echo "Error: First argument must be -e <environment>, bash, or --help"
+            echo "Error: First argument must be -e <environment>, --params, bash, or --help"
             echo ""
             echo "Usage: docker run sampleworks -e <env> <script> [args...]"
+            echo "       docker run sampleworks --params <params.json> --output-dir <dir>"
             echo "       docker run sampleworks bash"
             echo "       docker run sampleworks --help"
             exit 1
diff --git a/run_grid_search.py b/run_grid_search.py
index 67a737ad..a78dace7 100755
--- a/run_grid_search.py
+++ b/run_grid_search.py
@@ -13,14 +13,21 @@
 import time
 from concurrent.futures import ProcessPoolExecutor
 from dataclasses import asdict, dataclass
+from datetime import UTC, datetime
 from pathlib import Path
 from threading import Lock
 from typing import Any
 
 from loguru import logger as log
-from sampleworks.utils.guidance_constants import GuidanceType, StructurePredictor
+from sampleworks.utils.guidance_constants import Boltz2Method, GuidanceType, StructurePredictor
 from sampleworks.utils.guidance_script_arguments import GuidanceConfig, JobConfig, JobResult
 from sampleworks.utils.protein_input import ProteinInput
+from sampleworks.utils.run_params import (
+    apply_run_params,
+    has_params_mode,
+    write_params_artifacts,
+    write_run_summary,
+)
 
 
 @dataclass
@@ -113,6 +120,8 @@ def build_args_for_process_pool(
         gradient_normalization=args.gradient_normalization,
         augmentation=args.augmentation,
         align_to_input=args.align_to_input,
+        em=getattr(args, "em", False),
+        guidance_start=getattr(args, "guidance_start", -1),
     )
     # given model_type and guidance_type, the GuidanceConfig class will set itself up
     # with defaults for remaining required args, but we want to set them further here.
@@ -237,36 +246,72 @@ def main(args: argparse.Namespace):
     Args:
         args: Command-line arguments.
     """
-    gpus = detect_gpus()
-    log.info(f"Detected {len(gpus)} GPUs: {gpus}")
-    if args.max_parallel != "auto":
-        gpus = gpus[: int(args.max_parallel)]
-
-    log_args(args, gpus)
-
-    filtered_jobs, job_statuses = generate_and_filter_jobs(args)
-
-    if len(filtered_jobs) == 0:
-        log.info("No jobs to run!")
-        return
-
-    config = GridSearchConfig(
-        model=args.model,
-        scalers=args.scalers.split(),
-        ensemble_sizes=[int(x) for x in args.ensemble_sizes.split()],
-        gradient_weights=[float(x) for x in args.gradient_weights.split()],
-        gd_steps=[int(x) for x in args.num_gd_steps.split()],
-        method=args.method,
-        proteins_file=args.proteins,
-        output_dir=args.output_dir,
-    )
-
-    start_time = time.time()
+    started_at = datetime.now(UTC)
+    os.makedirs(args.output_dir, exist_ok=True)
+    write_params_artifacts(args, args.output_dir)
 
-    results = run_grid_search(filtered_jobs, gpus, args, job_statuses=job_statuses)
+    try:
+        gpus = detect_gpus()
+        log.info(f"Detected {len(gpus)} GPUs: {gpus}")
+        if args.max_parallel != "auto":
+            gpus = gpus[: int(args.max_parallel)]
+
+        log_args(args, gpus)
+
+        filtered_jobs, job_statuses = generate_and_filter_jobs(args)
+
+        if len(filtered_jobs) == 0:
+            log.info("No jobs to run!")
+            write_run_summary(
+                args=args,
+                output_dir=args.output_dir,
+                status="skipped",
+                started_at=started_at,
+                total_jobs=0,
+            )
+            return
+
+        config = GridSearchConfig(
+            model=args.model,
+            scalers=args.scalers.split(),
+            ensemble_sizes=[int(x) for x in args.ensemble_sizes.split()],
+            gradient_weights=[float(x) for x in args.gradient_weights.split()],
+            gd_steps=[int(x) for x in args.num_gd_steps.split()],
+            method=args.method,
+            proteins_file=args.proteins,
+            output_dir=args.output_dir,
+        )
 
-    if not args.dry_run and results:
-        save_results(results, config, args.output_dir, time.time() - start_time)
+        start_time = time.time()
+
+        results = run_grid_search(filtered_jobs, gpus, args, job_statuses=job_statuses)
+
+        if not args.dry_run and results:
+            save_results(results, config, args.output_dir, time.time() - start_time)
+
+        successful = sum(1 for result in results if result.status == "success")
+        failed = sum(1 for result in results if result.status == "failed")
+        status = "dry_run" if args.dry_run else "success"
+        if failed:
+            status = "failed"
+        write_run_summary(
+            args=args,
+            output_dir=args.output_dir,
+            status=status,
+            started_at=started_at,
+            total_jobs=len(filtered_jobs),
+            successful_jobs=successful,
+            failed_jobs=failed,
+        )
+    except Exception as exc:
+        write_run_summary(
+            args=args,
+            output_dir=args.output_dir,
+            status="failed",
+            started_at=started_at,
+            error=str(exc),
+        )
+        raise
 
     log.info("=" * 50)
     log.info("Grid search complete")
@@ -423,15 +468,24 @@ def parse_args() -> argparse.Namespace:
     )
     # Experiment level arguments
     parser.add_argument(
-        "--proteins", required=True, help="CSV file with columns: structure,density,resolution,name"
+        "--params",
+        default=None,
+        help="JSON params file. In params mode, Sampleworks owns validation and schema.",
+    )
+    parser.add_argument(
+        "--proteins",
+        required=False,
+        help="CSV file with columns: structure,density,resolution,name",
     )
 
     # Model arguments
     parser.add_argument(
         "--model",
+        "--models",
+        dest="model",
         default="boltz2",
         choices=["boltz1", "boltz2", "protenix", "rf3"],
-        help="The protein structure predictor model to use",
+        help="The protein structure predictor model to use. --models is a legacy alias.",
     )
     parser.add_argument(
         "--model-checkpoint",
@@ -440,10 +494,16 @@ def parse_args() -> argparse.Namespace:
     )
     parser.add_argument(
         "--method",
+        "--methods",
+        dest="method",
         default="X-RAY DIFFRACTION",
-        choices=["X-RAY DIFFRACTION", "MD"],
-        help="Method for Boltz2 ('X-RAY DIFFRACTION', 'MD')",
+        choices=[method.value for method in Boltz2Method],
+        help="Method for Boltz2. --methods is a legacy alias.",
     )
+    parser.add_argument("--boltz1-checkpoint", default=None, help=argparse.SUPPRESS)
+    parser.add_argument("--boltz2-checkpoint", default=None, help=argparse.SUPPRESS)
+    parser.add_argument("--protenix-checkpoint", default=None, help=argparse.SUPPRESS)
+    parser.add_argument("--rf3-checkpoint", default=None, help=argparse.SUPPRESS)
 
     # Trajectory scaling arguments
     parser.add_argument(
@@ -504,9 +564,16 @@ def parse_args() -> argparse.Namespace:
 
     # Reward/Loss function arguments
     parser.add_argument("--loss-order", type=int, default=2, help="L1 (1) or L2 (2) loss")
+    parser.add_argument("--em", action="store_true", help="Use EM scattering factors")
+    parser.add_argument(
+        "--guidance-start",
+        type=int,
+        default=-1,
+        help="Step to start guidance (default: -1, starts immediately)",
+    )
 
     # Output arguments
-    parser.add_argument("--output-dir", default="./grid_search_results", help="Output directory")
+    parser.add_argument("--output-dir", default=None, help="Output directory")
 
     # Arguments for choosing what to run and what hardware to use.
     parser.add_argument(
@@ -535,7 +602,20 @@ def parse_args() -> argparse.Namespace:
         help="Run only un-run jobs, skip failed and successful jobs",
     )
 
-    return parser.parse_args()
+    args = parser.parse_args()
+    checkpoint = getattr(args, f"{args.model}_checkpoint", None)
+    if checkpoint:
+        args.model_checkpoint = checkpoint
+    if has_params_mode(args):
+        try:
+            return apply_run_params(args)
+        except Exception as exc:
+            parser.error(str(exc))
+    if not args.proteins:
+        parser.error("--proteins is required unless --params is used")
+    if args.output_dir is None:
+        args.output_dir = "./grid_search_results"
+    return args
 
 
 def log_args(args: argparse.Namespace, gpus: list[str]):
@@ -552,6 +632,8 @@ def log_args(args: argparse.Namespace, gpus: list[str]):
     log.info(f"Gradient weights: {args.gradient_weights}")
     log.info(f"GD steps: {args.num_gd_steps}")
     log.info(f"Output directory: {args.output_dir}")
+    if getattr(args, "_sampleworks_params_source", None):
+        log.info(f"Params source: {args._sampleworks_params_source}")
     log.info(f"GPUs: {gpus}")
     log.info(f"Dry run: {args.dry_run}")
     log.info("=" * 50)
diff --git a/src/sampleworks/utils/guidance_script_utils.py b/src/sampleworks/utils/guidance_script_utils.py
index 40b633f5..76d4fee5 100644
--- a/src/sampleworks/utils/guidance_script_utils.py
+++ b/src/sampleworks/utils/guidance_script_utils.py
@@ -41,6 +41,7 @@
     validate_model_checkpoint,
 )
 from sampleworks.utils.msa import MSAManager
+from sampleworks.utils.run_params import diffuse_runtime_metadata, sampleworks_runtime_metadata
 
 
 # The following imports aren't compatible with each other and are supported in separate
@@ -618,7 +619,10 @@ def run_guidance_job_queue(job_queue_path: str) -> list[JobResult]:
         # write out the job parameters to a JSON file in the same directory as the refined.cif file
         with open(Path(job_result.output_dir) / "job_metadata.json", "w") as fp:
             # use the GuidanceConfig's as_dict() method to avoid serializing PosixPath objects
-            json.dump(job.as_dict(), fp)
+            metadata_payload = job.as_dict()
+            metadata_payload["sampleworks"] = sampleworks_runtime_metadata()
+            metadata_payload["diffuse"] = diffuse_runtime_metadata()
+            json.dump(metadata_payload, fp, indent=2, sort_keys=True)
 
         job_results.append(job_result)
         torch.cuda.empty_cache()  # just in case
diff --git a/src/sampleworks/utils/run_params.py b/src/sampleworks/utils/run_params.py
new file mode 100644
index 00000000..f964762f
--- /dev/null
+++ b/src/sampleworks/utils/run_params.py
@@ -0,0 +1,698 @@
+from __future__ import annotations
+
+import argparse
+import csv
+import json
+import os
+from datetime import UTC, datetime
+from importlib import metadata
+from pathlib import Path
+from typing import Any
+
+from sampleworks.utils.guidance_constants import Boltz2Method, GuidanceType, StructurePredictor
+
+
+def has_params_mode(args: argparse.Namespace) -> bool:
+    """Return whether the namespace requests params-file mode.
+
+    Parameters
+    ----------
+    args
+        Parsed command-line arguments.
+
+    Returns
+    -------
+    bool
+        ``True`` when ``--params`` was supplied.
+    """
+    return bool(getattr(args, "params", None))
+
+
+def load_run_params(params_path: str) -> tuple[dict[str, Any], str]:
+    """Load a Sampleworks run parameter object from a JSON file.
+
+    Parameters
+    ----------
+    params_path
+        Path to a JSON file.
+
+    Returns
+    -------
+    tuple[dict[str, Any], str]
+        Loaded parameter object and a human-readable source string.
+
+    Raises
+    ------
+    ValueError
+        If the path is empty, JSON is invalid, or the parsed value is not an
+        object.
+    """
+    if not str(params_path).strip():
+        raise ValueError("--params requires a JSON file path")
+
+    path = Path(params_path).expanduser()
+    raw = path.read_text()
+    source = f"file:{path}"
+
+    try:
+        parsed = json.loads(raw)
+    except json.JSONDecodeError as exc:
+        raise ValueError(f"Invalid params JSON from {source}: {exc}") from exc
+
+    if not isinstance(parsed, dict):
+        raise ValueError("Sampleworks params JSON must be an object")
+
+    # Diffuse's full run params shape is {params_json: {...}, output_dir: ...}.
+    # Accept that file shape while keeping Sampleworks' contract file-only.
+    if isinstance(parsed.get("params_json"), dict):
+        inner = dict(parsed["params_json"])
+        if "output_dir" in parsed and "output_dir" not in inner:
+            inner["output_dir"] = parsed["output_dir"]
+        return inner, source
+
+    return parsed, source
+
+
+def infer_model(params: dict[str, Any]) -> str:
+    """Infer the requested Sampleworks model from a params object.
+
+    Parameters
+    ----------
+    params
+        Scientist-owned parameter object.
+
+    Returns
+    -------
+    str
+        One of ``boltz1``, ``boltz2``, ``protenix``, or ``rf3``.
+    """
+    model = _model_value(params.get("model"))
+    models = params.get("models")
+    if model is not None and models is not None:
+        inferred_models = _models_value(models)
+        if inferred_models != [model]:
+            raise ValueError("Sampleworks params JSON defines conflicting model and models values")
+    elif models is not None:
+        inferred_models = _models_value(models)
+        model = inferred_models[0]
+
+    model_section = params.get("model_config") or params.get("model_settings")
+    if isinstance(model_section, dict):
+        nested_model = _model_value(
+            model_section.get("name")
+            or model_section.get("type")
+            or model_section.get("model")
+        )
+        if nested_model is not None:
+            if model is not None and nested_model != model:
+                raise ValueError("Sampleworks params JSON defines conflicting nested model value")
+            model = nested_model
+
+    if not model:
+        raise ValueError("Sampleworks params JSON must include a 'model' field")
+    model = str(model)
+    valid = {m.value for m in StructurePredictor}
+    if model not in valid:
+        raise ValueError(f"Unknown Sampleworks model: {model}. Valid options: {sorted(valid)}")
+    return model
+
+
+def _model_value(value: Any) -> str | None:
+    """Extract one model name from a scalar or model section.
+
+    Parameters
+    ----------
+    value
+        Model field value.
+
+    Returns
+    -------
+    str | None
+        Extracted model name, if present.
+    """
+    if value is None:
+        return None
+    if isinstance(value, dict):
+        return _model_value(value.get("name") or value.get("type") or value.get("model"))
+    if isinstance(value, list):
+        if len(value) != 1:
+            raise ValueError("Sampleworks params mode supports exactly one model per run")
+        value = value[0]
+    return str(value)
+
+
+def _models_value(value: Any) -> list[str]:
+    """Extract the models list and reject multi-model params.
+
+    Parameters
+    ----------
+    value
+        Models field value.
+
+    Returns
+    -------
+    list[str]
+        Single-item model list.
+    """
+    if isinstance(value, str):
+        models = value.split()
+    elif isinstance(value, (list, tuple)):
+        models = [str(item) for item in value]
+    else:
+        raise ValueError("models must be a string or list containing exactly one model")
+    if len(models) != 1:
+        raise ValueError("Sampleworks params mode supports exactly one model per run")
+    return models
+
+
+def infer_pixi_env(model: str) -> str:
+    """Return the Pixi environment for a Sampleworks model name.
+
+    Parameters
+    ----------
+    model
+        Sampleworks model identifier.
+
+    Returns
+    -------
+    str
+        Pixi environment name.
+    """
+    if model in (StructurePredictor.BOLTZ_1, StructurePredictor.BOLTZ_2, "boltz1", "boltz2"):
+        return "boltz"
+    if model in (StructurePredictor.PROTENIX, "protenix"):
+        return "protenix"
+    if model in (StructurePredictor.RF3, "rf3"):
+        return "rf3"
+    raise ValueError(f"Unknown Sampleworks model: {model}")
+
+
+def normalize_space_list(value: Any, *, item_type: type = str, param_name: str) -> str:
+    """Normalize scalar/list JSON values to Sampleworks' space-separated CLI strings.
+
+    Parameters
+    ----------
+    value
+        JSON value from params.
+    item_type
+        Type used to normalize list elements.
+    param_name
+        Human-readable parameter name for validation errors.
+
+    Returns
+    -------
+    str
+        Existing string values unchanged, list values joined by spaces.
+    """
+    if isinstance(value, str):
+        if not value.strip():
+            raise ValueError(f"{param_name} must not be empty")
+        return value
+    if isinstance(value, (list, tuple)):
+        if len(value) == 0:
+            raise ValueError(f"{param_name} must not be empty")
+        try:
+            return " ".join(str(item_type(item)) for item in value)
+        except (TypeError, ValueError) as exc:
+            raise ValueError(f"{param_name} values must be {item_type.__name__}") from exc
+    if item_type is not str and isinstance(value, (int, float)):
+        try:
+            return str(item_type(value))
+        except (TypeError, ValueError) as exc:
+            raise ValueError(f"{param_name} must be {item_type.__name__}, string, or list") from exc
+    raise ValueError(f"{param_name} must be a string or list")
+
+
+def normalize_optional_single(value: Any, *, param_name: str) -> str:
+    """Normalize a scalar or single-item list to a string.
+
+    Parameters
+    ----------
+    value
+        Parameter value.
+    param_name
+        Human-readable parameter name for validation errors.
+
+    Returns
+    -------
+    str
+        Normalized value.
+    """
+    if isinstance(value, str):
+        return value
+    if isinstance(value, (list, tuple)):
+        if len(value) != 1:
+            raise ValueError(f"{param_name} must contain exactly one value")
+        return str(value[0])
+    return str(value)
+
+
+def normalize_bool(value: Any, *, param_name: str) -> bool:
+    """Normalize a JSON boolean or boolean-like string.
+
+    Parameters
+    ----------
+    value
+        Parameter value.
+    param_name
+        Human-readable parameter name for validation errors.
+
+    Returns
+    -------
+    bool
+        Normalized boolean.
+    """
+    if isinstance(value, bool):
+        return value
+    if isinstance(value, str):
+        normalized = value.strip().lower()
+        if normalized in {"true", "1", "yes", "on"}:
+            return True
+        if normalized in {"false", "0", "no", "off"}:
+            return False
+    raise ValueError(f"{param_name} must be a boolean")
+
+
+def normalize_scalar(value: Any, *, item_type: type, param_name: str) -> Any:
+    """Normalize a scalar JSON value.
+
+    Parameters
+    ----------
+    value
+        Parameter value.
+    item_type
+        Target scalar type.
+    param_name
+        Human-readable parameter name for validation errors.
+
+    Returns
+    -------
+    Any
+        Converted scalar value.
+    """
+    if isinstance(value, (list, tuple, dict)):
+        raise ValueError(f"{param_name} must be a {item_type.__name__} value")
+    try:
+        return item_type(value)
+    except (TypeError, ValueError) as exc:
+        raise ValueError(f"{param_name} must be a {item_type.__name__} value") from exc
+
+
+def resolve_output_dir(params: dict[str, Any], cli_output_dir: str | None) -> Path:
+    """Resolve output directory with CLI value taking precedence.
+
+    Parameters
+    ----------
+    params
+        Scientist-owned parameter object.
+    cli_output_dir
+        Value supplied via ``--output-dir``.
+
+    Returns
+    -------
+    pathlib.Path
+        Output directory path.
+    """
+    paths = params.get("paths") if isinstance(params.get("paths"), dict) else {}
+    value = cli_output_dir or params.get("output_dir") or paths.get("output_dir")
+    return Path(str(value or "./grid_search_results")).expanduser()
+
+
+def _lookup(params: dict[str, Any], *keys: str, section: str | None = None) -> Any:
+    """Look up a value from top-level params or a nested section.
+
+    Parameters
+    ----------
+    params
+        Parameter object.
+    keys
+        Candidate keys in priority order.
+    section
+        Optional nested section to consult before top-level keys.
+
+    Returns
+    -------
+    Any
+        First present value, or ``None``.
+    """
+    if section and isinstance(params.get(section), dict):
+        nested = params[section]
+        for key in keys:
+            if key in nested:
+                return nested[key]
+    for key in keys:
+        if key in params:
+            return params[key]
+    return None
+
+
+def write_inline_proteins_csv(proteins: list[dict[str, Any]], output_dir: Path) -> Path:
+    """Materialize inline protein input records to a proteins CSV file.
+
+    Parameters
+    ----------
+    proteins
+        List of objects containing ``name``, ``structure``, ``density``, and
+        ``resolution``.
+    output_dir
+        Run output directory.
+
+    Returns
+    -------
+    pathlib.Path
+        Path to the generated CSV file.
+    """
+    inputs_dir = output_dir / "inputs"
+    inputs_dir.mkdir(parents=True, exist_ok=True)
+    path = inputs_dir / "proteins.csv"
+    required = ("name", "structure", "density", "resolution")
+    with path.open("w", newline="") as handle:
+        writer = csv.DictWriter(handle, fieldnames=list(required))
+        writer.writeheader()
+        for index, protein in enumerate(proteins):
+            if not isinstance(protein, dict):
+                raise ValueError(f"Inline protein #{index + 1} must be an object")
+            missing = [key for key in required if key not in protein]
+            if missing:
+                raise ValueError(
+                    f"Inline protein #{index + 1} is missing required keys: {missing}"
+                )
+            writer.writerow({key: protein[key] for key in required})
+    return path
+
+
+def apply_run_params(args: argparse.Namespace) -> argparse.Namespace:
+    """Apply greedy JSON params to an existing argparse namespace.
+
+    Parameters
+    ----------
+    args
+        Parsed arguments from ``run_grid_search.py``.
+
+    Returns
+    -------
+    argparse.Namespace
+        The same namespace, mutated with resolved Sampleworks options.
+    """
+    params, source = load_run_params(getattr(args, "params", None))
+    output_dir = resolve_output_dir(params, getattr(args, "output_dir", None))
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    model = infer_model(params)
+    args.model = model
+    args.output_dir = str(output_dir)
+
+    inputs_value = params.get("inputs")
+    if inputs_value is not None and not isinstance(inputs_value, dict):
+        raise ValueError("inputs must be an object")
+    inputs = inputs_value or {}
+    proteins = (
+        params.get("proteins")
+        or params.get("proteins_path")
+        or inputs.get("proteins")
+        or inputs.get("proteins_path")
+    )
+    if isinstance(proteins, list):
+        args.proteins = str(write_inline_proteins_csv(proteins, output_dir))
+    elif isinstance(proteins, dict):
+        raise ValueError("inputs.proteins must be a file path or a list of protein objects")
+    elif proteins:
+        args.proteins = str(proteins)
+    else:
+        raise ValueError("Sampleworks params JSON must define inputs.proteins or proteins_path")
+
+    guidance_mappings: tuple[tuple[str, tuple[str, ...], type], ...] = (
+        ("scalers", ("scalers", "scaler"), str),
+        ("ensemble_sizes", ("ensemble_sizes", "ensemble_size"), int),
+        ("gradient_weights", ("gradient_weights", "gradient_weight"), float),
+        ("num_gd_steps", ("num_gd_steps", "num_gd_step"), int),
+    )
+    for attr, keys, item_type in guidance_mappings:
+        value = _lookup(params, *keys, section="guidance")
+        if value is not None:
+            setattr(
+                args,
+                attr,
+                normalize_space_list(value, item_type=item_type, param_name=keys[0]),
+            )
+
+    method = _lookup(params, "method", "methods", section="model")
+    if method is None:
+        method = _lookup(params, "method", "methods", section="model_config")
+    if method is None:
+        method = _lookup(params, "method", "methods", section="model_settings")
+    if method is not None:
+        if model != StructurePredictor.BOLTZ_2:
+            raise ValueError("method is only valid for model boltz2")
+        method = normalize_optional_single(method, param_name="method")
+        valid_methods = {item.value for item in Boltz2Method}
+        if method not in valid_methods:
+            raise ValueError(f"Unknown Boltz2 method: {method}. Valid options: {sorted(valid_methods)}")
+        args.method = method
+    elif model != StructurePredictor.BOLTZ_2:
+        args.method = None
+
+    scalar_mappings: tuple[tuple[str, tuple[str, ...], str | None, type], ...] = (
+        ("partial_diffusion_step", ("partial_diffusion_step",), "guidance", int),
+        ("guidance_start", ("guidance_start",), "guidance", int),
+        ("loss_order", ("loss_order",), "guidance", int),
+        ("num_particles", ("num_particles",), "guidance", int),
+        ("fk_lambda", ("fk_lambda",), "guidance", float),
+        ("fk_resampling_interval", ("fk_resampling_interval",), "guidance", int),
+    )
+    for attr, keys, section, item_type in scalar_mappings:
+        value = _lookup(params, *keys, section=section)
+        if value is not None:
+            setattr(args, attr, normalize_scalar(value, item_type=item_type, param_name=keys[0]))
+
+    step_scaler_type = _lookup(params, "step_scaler_type", section="guidance")
+    if step_scaler_type is not None:
+        step_scaler_type = str(step_scaler_type)
+        valid_step_scalers = {"dataspace", "noisespace", "none"}
+        if step_scaler_type not in valid_step_scalers:
+            raise ValueError(
+                f"Unknown step_scaler_type: {step_scaler_type}. "
+                f"Valid options: {sorted(valid_step_scalers)}"
+            )
+        args.step_scaler_type = step_scaler_type
+
+    max_parallel = _lookup(params, "max_parallel", section="execution")
+    if max_parallel is not None:
+        if max_parallel != "auto":
+            normalize_scalar(max_parallel, item_type=int, param_name="max_parallel")
+        args.max_parallel = str(max_parallel)
+
+    fk = params.get("fk")
+    guidance = params.get("guidance") if isinstance(params.get("guidance"), dict) else {}
+    if not isinstance(fk, dict):
+        fk = guidance.get("fk") if isinstance(guidance.get("fk"), dict) else {}
+    for attr, key, item_type in (
+        ("num_gd_steps", "num_gd_steps", int),
+        ("num_particles", "num_particles", int),
+        ("fk_lambda", "fk_lambda", float),
+        ("fk_resampling_interval", "fk_resampling_interval", int),
+    ):
+        if key in fk:
+            value = fk[key]
+            if attr == "num_gd_steps":
+                value = normalize_space_list(value, item_type=item_type, param_name=key)
+            else:
+                value = normalize_scalar(value, item_type=item_type, param_name=key)
+            setattr(args, attr, value)
+
+    paths = params.get("paths") if isinstance(params.get("paths"), dict) else {}
+    model_section = params.get("model") if isinstance(params.get("model"), dict) else {}
+    model_config = params.get("model_config") if isinstance(params.get("model_config"), dict) else {}
+    model_settings = (
+        params.get("model_settings") if isinstance(params.get("model_settings"), dict) else {}
+    )
+    checkpoint = (
+        params.get("model_checkpoint")
+        or model_section.get("checkpoint")
+        or model_section.get("model_checkpoint")
+        or model_config.get("checkpoint")
+        or model_config.get("model_checkpoint")
+        or model_settings.get("checkpoint")
+        or model_settings.get("model_checkpoint")
+        or paths.get("model_checkpoint")
+    )
+    if checkpoint is not None:
+        args.model_checkpoint = str(checkpoint)
+
+    for attr in (
+        "gradient_normalization",
+        "augmentation",
+        "align_to_input",
+        "em",
+        "dry_run",
+        "force_all",
+        "only_failed",
+        "only_missing",
+        "disable_chiral_features",
+        "track_chiral_features",
+    ):
+        value = _lookup(params, attr, section="guidance")
+        if value is None:
+            value = _lookup(params, attr, section="execution")
+        if value is not None:
+            setattr(args, attr, normalize_bool(value, param_name=attr))
+
+    scalers = args.scalers.split()
+    valid_scalers = {item.value for item in GuidanceType}
+    invalid_scalers = [scaler for scaler in scalers if scaler not in valid_scalers]
+    if invalid_scalers:
+        raise ValueError(f"Unknown scalers: {invalid_scalers}. Valid options: {sorted(valid_scalers)}")
+
+    args._sampleworks_params = params
+    args._sampleworks_params_source = source
+    return args
+
+
+def _jsonable(value: Any) -> Any:
+    """Convert common runtime values to JSON-serializable values.
+
+    Parameters
+    ----------
+    value
+        Arbitrary value.
+
+    Returns
+    -------
+    Any
+        JSON-compatible value.
+    """
+    if isinstance(value, Path):
+        return str(value)
+    if isinstance(value, dict):
+        return {str(k): _jsonable(v) for k, v in value.items() if not str(k).startswith("_")}
+    if isinstance(value, (list, tuple)):
+        return [_jsonable(v) for v in value]
+    return value
+
+
+def write_params_artifacts(args: argparse.Namespace, output_dir: str | Path) -> None:
+    """Write original and resolved params artifacts for a params-mode run.
+
+    Parameters
+    ----------
+    args
+        Resolved run namespace.
+    output_dir
+        Run output directory.
+    """
+    params = getattr(args, "_sampleworks_params", None)
+    if params is None:
+        return
+    out = Path(output_dir)
+    out.mkdir(parents=True, exist_ok=True)
+    (out / "params.original.json").write_text(json.dumps(params, indent=2, sort_keys=True))
+    resolved = {
+        key: _jsonable(value)
+        for key, value in vars(args).items()
+        if not key.startswith("_")
+    }
+    resolved["params_source"] = getattr(args, "_sampleworks_params_source", None)
+    (out / "params.resolved.json").write_text(json.dumps(resolved, indent=2, sort_keys=True))
+
+
+def sampleworks_runtime_metadata() -> dict[str, Any]:
+    """Collect runtime provenance from package metadata and environment.
+
+    Returns
+    -------
+    dict[str, Any]
+        Runtime metadata suitable for run summaries.
+    """
+    try:
+        version = metadata.version("sampleworks")
+    except metadata.PackageNotFoundError:
+        version = "unknown"
+    return {
+        "version": version,
+        "git_sha": os.environ.get("SAMPLEWORKS_GIT_SHA", "unknown"),
+        "image_tag": os.environ.get("SAMPLEWORKS_IMAGE_TAG", "unknown"),
+    }
+
+
+def diffuse_runtime_metadata() -> dict[str, Any]:
+    """Collect Diffuse runtime metadata from injected environment variables.
+
+    Returns
+    -------
+    dict[str, Any]
+        Diffuse run context.
+    """
+    return {
+        "run_id": os.environ.get("DIFFUSE_RUN_ID"),
+        "profile_slug": os.environ.get("DIFFUSE_PROFILE_SLUG"),
+        "experiment_id": os.environ.get("DIFFUSE_EXPERIMENT_ID"),
+        "api_url": os.environ.get("DIFFUSE_API_URL"),
+        "params_path": os.environ.get("DIFFUSE_PARAMS_PATH"),
+    }
+
+
+def write_run_summary(
+    *,
+    args: argparse.Namespace,
+    output_dir: str | Path,
+    status: str,
+    started_at: datetime,
+    finished_at: datetime | None = None,
+    total_jobs: int = 0,
+    successful_jobs: int = 0,
+    failed_jobs: int = 0,
+    error: str | None = None,
+) -> None:
+    """Write the top-level Sampleworks run summary consumed by humans/Diffuse.
+
+    Parameters
+    ----------
+    args
+        Resolved run namespace.
+    output_dir
+        Run output directory.
+    status
+        Run status string.
+    started_at
+        UTC start timestamp.
+    finished_at
+        UTC finish timestamp. Defaults to ``now``.
+    total_jobs
+        Number of jobs selected for this run.
+    successful_jobs
+        Number of successful jobs.
+    failed_jobs
+        Number of failed jobs.
+    error
+        Optional error message.
+    """
+    finished = finished_at or datetime.now(UTC)
+    out = Path(output_dir)
+    out.mkdir(parents=True, exist_ok=True)
+    results_json = out / "results.json"
+    summary = {
+        "schema_version": 1,
+        "status": status,
+        "started_at": started_at.isoformat(),
+        "finished_at": finished.isoformat(),
+        "runtime_seconds": round((finished - started_at).total_seconds(), 3),
+        "sampleworks": sampleworks_runtime_metadata(),
+        "diffuse": diffuse_runtime_metadata(),
+        "params": {
+            "source": getattr(args, "_sampleworks_params_source", None),
+            "original_path": str(out / "params.original.json"),
+            "resolved_path": str(out / "params.resolved.json"),
+        },
+        "outputs": {
+            "output_dir": str(out),
+            "results_json": str(results_json) if results_json.exists() else None,
+        },
+        "summary": {
+            "total": total_jobs,
+            "successful": successful_jobs,
+            "failed": failed_jobs,
+        },
+    }
+    if error:
+        summary["error"] = error
+    (out / "run_summary.json").write_text(json.dumps(summary, indent=2, sort_keys=True))
diff --git a/tests/utils/test_run_params.py b/tests/utils/test_run_params.py
new file mode 100644
index 00000000..548c7b01
--- /dev/null
+++ b/tests/utils/test_run_params.py
@@ -0,0 +1,338 @@
+"""Tests for flexible Sampleworks params.json handling."""
+
+from __future__ import annotations
+
+import json
+from argparse import Namespace
+
+import pytest
+
+from sampleworks.utils.run_params import (
+    apply_run_params,
+    infer_model,
+    infer_pixi_env,
+    load_run_params,
+    normalize_space_list,
+    write_params_artifacts,
+)
+
+
+def _namespace(**overrides) -> Namespace:
+    defaults = dict(
+        params=None,
+        proteins=None,
+        model="boltz2",
+        method="X-RAY DIFFRACTION",
+        scalers="pure_guidance fk_steering",
+        ensemble_sizes="1 2 4 8",
+        gradient_weights="0.01 0.1 0.2",
+        partial_diffusion_step=0,
+        num_gd_steps="20",
+        num_particles=3,
+        fk_lambda=0.5,
+        fk_resampling_interval=1,
+        step_scaler_type="noisespace",
+        gradient_normalization=False,
+        augmentation=False,
+        align_to_input=False,
+        disable_chiral_features=False,
+        track_chiral_features=False,
+        loss_order=2,
+        em=False,
+        guidance_start=-1,
+        output_dir="./grid_search_results",
+        max_parallel="auto",
+        dry_run=False,
+        force_all=False,
+        only_failed=False,
+        only_missing=False,
+        model_checkpoint="",
+    )
+    defaults.update(overrides)
+    return Namespace(**defaults)
+
+
+def test_load_run_params_from_file(tmp_path):
+    params_path = tmp_path / "params.json"
+    params_path.write_text(json.dumps({"model": "boltz2"}))
+
+    params, source = load_run_params(str(params_path))
+
+    assert params == {"model": "boltz2"}
+    assert source == f"file:{params_path}"
+
+
+def test_load_run_params_unwraps_diffuse_params_file(tmp_path):
+    params_path = tmp_path / "params.json"
+    params_path.write_text(
+        json.dumps(
+            {
+                "params_json": {"model": "rf3", "scalers": ["pure_guidance"]},
+                "output_dir": "/data/results/run-001",
+            }
+        )
+    )
+
+    params, source = load_run_params(str(params_path))
+
+    assert source == f"file:{params_path}"
+    assert params == {
+        "model": "rf3",
+        "scalers": ["pure_guidance"],
+        "output_dir": "/data/results/run-001",
+    }
+
+
+def test_infer_model_and_pixi_env():
+    assert infer_model({"model": "boltz2"}) == "boltz2"
+    assert infer_pixi_env("boltz2") == "boltz"
+    assert infer_pixi_env("protenix") == "protenix"
+    assert infer_pixi_env("rf3") == "rf3"
+
+
+def test_infer_model_rejects_unknown():
+    with pytest.raises(ValueError, match="Unknown Sampleworks model"):
+        infer_model({"model": "madeup"})
+
+
+def test_normalize_space_list():
+    assert normalize_space_list([8], item_type=int, param_name="ensemble_sizes") == "8"
+    assert (
+        normalize_space_list([0.1, 0.2], item_type=float, param_name="gradient_weights")
+        == "0.1 0.2"
+    )
+    assert (
+        normalize_space_list("0.1 0.2", item_type=float, param_name="gradient_weights")
+        == "0.1 0.2"
+    )
+
+
+def test_normalize_space_list_rejects_object():
+    with pytest.raises(ValueError, match="gradient_weights must be a string or list"):
+        normalize_space_list({"bad": True}, item_type=float, param_name="gradient_weights")
+
+
+def test_apply_run_params_maps_nested_guidance_and_output_dir(tmp_path):
+    params_path = tmp_path / "params.json"
+    output_dir = tmp_path / "out"
+    params_path.write_text(
+        json.dumps(
+            {
+                "model": "boltz2",
+                "inputs": {"proteins": "/data/input/proteins.csv"},
+                "guidance": {
+                    "scalers": ["pure_guidance"],
+                    "ensemble_sizes": [8],
+                    "gradient_weights": [0.1, 0.2],
+                    "partial_diffusion_step": 120,
+                    "gradient_normalization": True,
+                    "augmentation": True,
+                    "align_to_input": True,
+                },
+                "paths": {"output_dir": str(output_dir)},
+            }
+        )
+    )
+
+    args = apply_run_params(_namespace(params=str(params_path), output_dir=None))
+
+    assert args.model == "boltz2"
+    assert args.proteins == "/data/input/proteins.csv"
+    assert args.output_dir == str(output_dir)
+    assert args.scalers == "pure_guidance"
+    assert args.ensemble_sizes == "8"
+    assert args.gradient_weights == "0.1 0.2"
+    assert args.partial_diffusion_step == 120
+    assert args.gradient_normalization is True
+    assert args.augmentation is True
+    assert args.align_to_input is True
+
+
+def test_apply_run_params_maps_nested_model_method(tmp_path):
+    params_path = tmp_path / "params.json"
+    params_path.write_text(
+        json.dumps(
+            {
+                "model": {"name": "boltz2", "method": "ELECTRON MICROSCOPY"},
+                "inputs": {"proteins": "/data/input/proteins.csv"},
+            }
+        )
+    )
+
+    args = apply_run_params(_namespace(params=str(params_path)))
+
+    assert args.model == "boltz2"
+    assert args.method == "ELECTRON MICROSCOPY"
+
+
+def test_apply_run_params_maps_model_config_method_and_checkpoint(tmp_path):
+    params_path = tmp_path / "params.json"
+    params_path.write_text(
+        json.dumps(
+            {
+                "model_config": {
+                    "name": "boltz2",
+                    "method": "NEUTRON DIFFRACTION",
+                    "checkpoint": "/data/checkpoints/boltz2.ckpt",
+                },
+                "inputs": {"proteins": "/data/input/proteins.csv"},
+            }
+        )
+    )
+
+    args = apply_run_params(_namespace(params=str(params_path)))
+
+    assert args.model == "boltz2"
+    assert args.method == "NEUTRON DIFFRACTION"
+    assert args.model_checkpoint == "/data/checkpoints/boltz2.ckpt"
+
+
+def test_apply_run_params_clears_method_for_non_boltz2(tmp_path):
+    params_path = tmp_path / "params.json"
+    params_path.write_text(
+        json.dumps(
+            {
+                "model": "protenix",
+                "inputs": {"proteins": "/data/input/proteins.csv"},
+            }
+        )
+    )
+
+    args = apply_run_params(_namespace(params=str(params_path)))
+
+    assert args.method is None
+
+
+def test_apply_run_params_rejects_method_for_non_boltz2(tmp_path):
+    params_path = tmp_path / "params.json"
+    params_path.write_text(
+        json.dumps(
+            {
+                "model": "rf3",
+                "method": "MD",
+                "inputs": {"proteins": "/data/input/proteins.csv"},
+            }
+        )
+    )
+
+    with pytest.raises(ValueError, match="method is only valid"):
+        apply_run_params(_namespace(params=str(params_path)))
+
+
+def test_apply_run_params_rejects_multiple_models(tmp_path):
+    params_path = tmp_path / "params.json"
+    params_path.write_text(json.dumps({"models": ["boltz2", "rf3"]}))
+
+    with pytest.raises(ValueError, match="exactly one model"):
+        apply_run_params(_namespace(params=str(params_path)))
+
+
+def test_apply_run_params_rejects_conflicting_model_fields(tmp_path):
+    params_path = tmp_path / "params.json"
+    params_path.write_text(json.dumps({"model": "boltz2", "models": ["rf3"]}))
+
+    with pytest.raises(ValueError, match="conflicting model"):
+        apply_run_params(_namespace(params=str(params_path)))
+
+
+def test_apply_run_params_rejects_missing_inputs(tmp_path):
+    params_path = tmp_path / "params.json"
+    params_path.write_text(json.dumps({"model": "boltz2"}))
+
+    with pytest.raises(ValueError, match="inputs.proteins or proteins_path"):
+        apply_run_params(_namespace(params=str(params_path), proteins=None))
+
+
+def test_apply_run_params_rejects_bad_list_type(tmp_path):
+    params_path = tmp_path / "params.json"
+    params_path.write_text(
+        json.dumps(
+            {
+                "model": "boltz2",
+                "inputs": {"proteins": "/data/input/proteins.csv"},
+                "guidance": {"gradient_weights": {"bad": True}},
+            }
+        )
+    )
+
+    with pytest.raises(ValueError, match="gradient_weights must be a string or list"):
+        apply_run_params(_namespace(params=str(params_path)))
+
+
+def test_apply_run_params_preserves_unknown_params(tmp_path):
+    params_path = tmp_path / "params.json"
+    output_dir = tmp_path / "out"
+    params_path.write_text(
+        json.dumps(
+            {
+                "model": "boltz2",
+                "inputs": {"proteins": "/data/input/proteins.csv"},
+                "scientist_note": {"arbitrary": ["kept"]},
+            }
+        )
+    )
+
+    args = apply_run_params(_namespace(params=str(params_path), output_dir=str(output_dir)))
+    write_params_artifacts(args, output_dir)
+
+    original = json.loads((output_dir / "params.original.json").read_text())
+    assert original["scientist_note"] == {"arbitrary": ["kept"]}
+
+
+def test_apply_run_params_cli_output_dir_wins(tmp_path):
+    params_path = tmp_path / "params.json"
+    params_path.write_text(
+        json.dumps(
+            {
+                "model": "rf3",
+                "inputs": {"proteins": "/data/input/proteins.csv"},
+                "paths": {"output_dir": "/ignored"},
+            }
+        )
+    )
+
+    args = apply_run_params(
+        _namespace(params=str(params_path), output_dir="/data/results/from-cli")
+    )
+
+    assert args.output_dir == "/data/results/from-cli"
+
+
+def test_apply_run_params_materializes_inline_proteins(tmp_path):
+    params_path = tmp_path / "params.json"
+    output_dir = tmp_path / "out"
+    params_path.write_text(
+        json.dumps(
+            {
+                "model": "protenix",
+                "inputs": {
+                    "proteins": [
+                        {
+                            "name": "1abc",
+                            "structure": "/data/1abc.cif",
+                            "density": "/data/1abc.ccp4",
+                            "resolution": 1.8,
+                        }
+                    ]
+                },
+            }
+        )
+    )
+
+    args = apply_run_params(_namespace(params=str(params_path), output_dir=str(output_dir)))
+
+    assert args.proteins == str(output_dir / "inputs" / "proteins.csv")
+    csv_text = (output_dir / "inputs" / "proteins.csv").read_text()
+    assert "1abc,/data/1abc.cif,/data/1abc.ccp4,1.8" in csv_text
+
+
+def test_write_params_artifacts(tmp_path):
+    params_path = tmp_path / "params.json"
+    params_path.write_text(json.dumps({"model": "boltz2", "inputs": {"proteins": "p.csv"}}))
+    output_dir = tmp_path / "out"
+    args = apply_run_params(_namespace(params=str(params_path), output_dir=str(output_dir)))
+
+    write_params_artifacts(args, output_dir)
+
+    assert (output_dir / "params.original.json").exists()
+    assert (output_dir / "params.resolved.json").exists()