fix(deployment): harden offline bundle import for move-to-another-computer

Audit of the Deployment tab's move-to-another-computer workflow surfaced gaps
on the import side that only bite at first launch on the field machine. Harden
import_bundle (warn-only where import-first-point-later is valid; hard-fail only
on a genuinely broken bundle):

- Empty/placeholder Kraken2 DB: flag kraken_db_unset + warn instead of silently
  leaving the ${KRAKEN_DB} placeholder (matched as a substring since ConfigLoader
  normalises it to <cwd>/${KRAKEN_DB}).
- Missing main.nf in a bundled pipeline: hard-fail the import (was a warning).
- Empty Nextflow plugins dir: warn (would otherwise fall back to the online
  registry and break offline).
- Re-verify checksums AFTER the copy to home (excluding the templated/mutated
  genome_metadata.json and config.yaml) to catch a truncated copy.
- Record a Nextflow version floor (26.04.0) in the manifest and warn on import
  when the field machine is older.
- Path-aware genome_metadata templating on export: report any path outside the
  data home instead of silently leaking it.

UI: the import callback surfaces kraken_db_unset / plugins_empty as a prominent
"Action required" row so the operator does not read "Offline mode activated" as
"ready to run".

Docs: add a step-by-step "Move Nanometa Live to another computer" section to
OPERATOR_GUIDE.md and document nxf_conda_cachedir / nxf_plugins_dir / the
import-sets-offline_mode behaviour in configuration.md.

Tests: new test_bundle_roundtrip.py (real export -> import into a fresh home,
asserting config rebasing / offline_mode / restored data / re-templated
metadata) plus per-finding classes in test_bundle_manager.py. Full suite 2618
passed; a live same-machine round-trip verified end to end.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: druvus

docs/OPERATOR_GUIDE.md

@@ -124,6 +124,74 @@ The most operationally relevant tabs:
   watchlists or load a custom one.
 - **Preparation** -- before running validation on a new organism, or when
   setting up an offline-deployment bundle.
+- **Deployment** -- to package this installation for another computer, or to
+  install a package received from another computer (see the next section).
+
+---
+
+## Move Nanometa Live to another computer (offline deployment)
+
+Use this to run on an air-gapped or field computer that has no internet
+access. You prepare a bundle on a build machine that does have internet,
+transfer it, and import it on the field machine.
+
+### What transfers
+
+The bundle (a single `.tar.gz`) contains the reference genomes, BLAST
+databases, taxid mappings, taxonomy cache, watchlists, the pipeline source,
+and the Nextflow plugins -- optionally also pre-warmed conda environments or
+container images. The **Kraken2 database is not included** because of its size;
+copy it separately (for example on the same drive).
+
+### 1. On the build machine -- export
+
+1. Open the **Deployment** tab and use **Export Bundle**.
+2. Choose the container engine:
+   - **conda** -- smallest bundle, but the field machine must have the **same
+     operating system and CPU architecture** as the build machine (for example
+     both Linux x86_64, or both macOS arm64). Conda environments are not
+     portable across platforms.
+   - **docker** or **singularity/apptainer** -- portable across operating
+     systems; the bundle carries the container images.
+3. Optionally tick **pre-warm conda envs** (conda only). This bakes the
+   per-process environments so the field machine does not build them on first
+   run; it adds roughly 30 minutes and several GB, and keeps the same-OS/arch
+   restriction above.
+4. The bundle is written to the chosen folder.
+
+### 2. Transfer
+
+Copy the bundle `.tar.gz` and the Kraken2 database directory to the field
+machine (USB drive, etc.). The field machine needs roughly three times the
+bundle size in free space for extraction.
+
+### 3. On the field machine -- import
+
+1. Open the **Deployment** tab and use **Import Bundle**.
+2. Provide the path to the bundle **and** the path to the Kraken2 database on
+   this machine.
+3. If the bundle was pre-warmed, run `source activate_offline_envs.sh` from the
+   install directory in the shell that launches Nanometa Live.
+
+Messages you may see on import, and what to do:
+
+- *"Kraken2 database path was not provided"* -- you imported without giving the
+  database path. Set `kraken_db` on the Watchlist & Preparation tab (or in
+  `config.yaml`) before starting analysis.
+- *Platform mismatch* -- the bundle was built on a different OS/architecture.
+  With pre-warmed conda envs the import is refused; rebuild the bundle on a
+  matching machine, or use docker/singularity mode.
+- *"missing main.nf"* -- the bundled pipeline is incomplete or was truncated in
+  transfer; re-export and re-transfer.
+- *"empty plugins directory"* -- re-export from a machine with the Nextflow
+  plugins cached, or the offline run will fail when Nextflow probes the online
+  plugin registry.
+
+### 4. After import
+
+Offline mode is enabled automatically. Open the **Watchlist & Preparation**
+tab, run the **Readiness** checklist until everything is green, then click
+**Start Analysis**.
 
 ---
 

docs/configuration.md

@@ -31,7 +31,7 @@ nanopore_output_directory: "/path/to/input"
 | `processing_mode` | string | "batch" | `batch` or `realtime` |
 | `sample_handling` | string | "by_barcode" | `by_barcode`, `single_sample`, or `per_file` |
 | `sample_name` | string | "sample" | Name when using single_sample mode |
-| `offline_mode` | bool | false | Skip network calls and use cached data only |
+| `offline_mode` | bool | false | Skip network calls and use cached data only. Set automatically to `true` by a Deployment-tab bundle import; if the Kraken2 database path was not supplied at import, set `kraken_db` before starting analysis. |
 
 ### Kraken2 Classification
 
@@ -48,6 +48,8 @@ nanopore_output_directory: "/path/to/input"
 |-----------|------|---------|-------------|
 | `pipeline_profile` | string | "conda"  | `conda` is the canonical and supported profile for nanometanf. `docker` and `singularity` exist but are not used by Nanometa Live. |
 | `pipeline_source` | string | "remote:master" | Pipeline location (see below) |
+| `nxf_conda_cachedir` | path | null | Field-machine path to a bundle's pre-warmed Nextflow conda cache. Set automatically by bundle import; exported as `NXF_CONDA_CACHEDIR`. |
+| `nxf_plugins_dir` | path | null | Field-machine path to a bundle's Nextflow plugin cache. Set automatically by bundle import; suppresses the online plugin-registry probe in offline mode. |
 | `pipeline_cores` | int | 1 | CPU cores for pipeline |
 | `kraken_cores` | int | 1 | CPU cores for Kraken2 classification |
 | `validation_cores` | int | 1 | CPU cores for validation tasks |

nanometa_live/app/tabs/preparation_tab.py

@@ -763,6 +763,30 @@ def import_bundle(n_clicks, bundle_path, kraken_db_path):
                     html.I(className="bi bi-check-circle me-2"),
                     html.Strong("Bundle imported. Offline mode activated."),
                 ]
+                # Setup that is not yet complete (action required) -- surface
+                # these prominently so the operator does not read "activated"
+                # as "ready to run".
+                action_needed = []
+                if result.get("kraken_db_unset"):
+                    action_needed.append(
+                        "Set the Kraken2 database path before starting analysis "
+                        "(it is transferred separately from the bundle)."
+                    )
+                if result.get("plugins_empty"):
+                    action_needed.append(
+                        "Bundled Nextflow plugins are missing; re-export from a "
+                        "machine with the plugins cached, or the offline run will "
+                        "fail when Nextflow probes the online plugin registry."
+                    )
+                if action_needed:
+                    children.append(
+                        dbc.Alert(
+                            [html.Strong("Action required: ")]
+                            + [html.Div(a, className="small") for a in action_needed],
+                            color="warning",
+                            className="mt-2 mb-2",
+                        )
+                    )
                 if result["warnings"]:
                     children.append(html.Br())
                     children.append(html.Strong("Warnings: "))