HF demo: block chat submissions and guide local edge install; add optional virgin-system runtime config

README.md

@@ -85,6 +85,25 @@ chmod +x scripts/install_fresh_copy.sh
 ./scripts/install_fresh_copy.sh --skip-clone
 ```
 
+Optional: predownload MedGemma model files during install:
+
+```bash
+./scripts/install_fresh_copy.sh --skip-clone --download-models --hf-token <YOUR_HF_TOKEN>
+```
+
+Optional: explicitly configure runtime defaults for this machine during install:
+
+```bash
+./scripts/install_fresh_copy.sh --skip-clone --configure-system
+```
+
+This writes `sailingmed.local.env`, which `run_med_advisor.sh` loads automatically at startup.
+
+Notes:
+- Model downloads are large (multi-GB; 27B is significantly larger).
+- Your Hugging Face token must have access to the MedGemma repositories.
+- You can also download later from `Settings -> Offline Readiness Check`.
+
 For full instructions and troubleshooting, see `docs/FRESH_INSTALL.md`.
 
 You can re-run the deterministic installation verification at any time:
@@ -100,6 +119,18 @@ chmod +x scripts/bootstrap_ubuntu24_sailingmedadvisor.sh
 ./scripts/bootstrap_ubuntu24_sailingmedadvisor.sh
 ```
 
+With optional model predownload:
+
+```bash
+./scripts/bootstrap_ubuntu24_sailingmedadvisor.sh --download-models --hf-token <YOUR_HF_TOKEN>
+```
+
+With explicit machine configuration during bootstrap:
+
+```bash
+./scripts/bootstrap_ubuntu24_sailingmedadvisor.sh --configure-system
+```
+
 ## Demo Reproduction (27B scenario)
 
 For the Kaggle demo scenario, use the 27B model path in the UI:

app.py

@@ -181,6 +181,17 @@ def _env_bool(name: str, default: bool = False) -> bool:
 DISABLE_LOCAL_INFERENCE = _env_bool("DISABLE_LOCAL_INFERENCE", False)
 # Optional override: force remote inference only when on HF runtime.
 FORCE_REMOTE_INFERENCE_ON_HF = _env_bool("FORCE_REMOTE_INFERENCE_ON_HF", False)
+# Public demo mode: disable live MedGemma chat submissions in hosted demo UI.
+PUBLIC_DEMO_DISABLE_CHAT = _env_bool("PUBLIC_DEMO_DISABLE_CHAT", IS_HF_SPACE)
+PUBLIC_DEMO_REPO_URL = (
+    os.environ.get("PUBLIC_DEMO_REPO_URL")
+    or "https://github.com/rickeae/SailingMedAdvisor"
+).strip()
+HF_DEMO_CHAT_DISABLED_MESSAGE = (
+    "This Hugging Face-hosted build is a workflow demo for an edge deployment. "
+    "MedGemma triage/inquiry execution is not available in this hosted version. "
+    "Install SailingMedAdvisor locally to run full consultations."
+)
 
 # Gemma3 masking patch for torch<2.6 (required when token_type_ids are present).
 def _torch_version_ge(major: int, minor: int) -> bool:
@@ -266,6 +277,7 @@ _dbg(
             f"IS_HF_SPACE={IS_HF_SPACE}",
             f"DISABLE_LOCAL_INFERENCE={DISABLE_LOCAL_INFERENCE}",
             f"FORCE_REMOTE_INFERENCE_ON_HF={FORCE_REMOTE_INFERENCE_ON_HF}",
+            f"PUBLIC_DEMO_DISABLE_CHAT={PUBLIC_DEMO_DISABLE_CHAT}",
             f"AUTO_DOWNLOAD_MODELS={AUTO_DOWNLOAD_MODELS}",
             f"VERIFY_MODELS_ON_START={VERIFY_MODELS_ON_START}",
             f"AUTO_VERIFY_ONLINE={AUTO_VERIFY_ONLINE}",
@@ -468,6 +480,14 @@ def _use_remote_inference(request: Optional[Request] = None) -> bool:
     return False
 
 
+def _chat_disabled_in_hosted_demo(request: Optional[Request] = None) -> bool:
+    """
+    Disable chat execution for hosted demo contexts.
+    This keeps HF demos focused on workflow while preserving full local edge behavior.
+    """
+    return bool(PUBLIC_DEMO_DISABLE_CHAT or _request_is_hf_runtime(request))
+
+
 def _is_valid_sqlite(path: Path) -> bool:
     """
      Is Valid Sqlite helper.
@@ -635,6 +655,7 @@ async def _log_db_path():
             db_path=DB_PATH.resolve(),
             runtime_log_path=RUNTIME_LOG_PATH.resolve(),
             is_hf_space=IS_HF_SPACE,
+            public_demo_disable_chat=PUBLIC_DEMO_DISABLE_CHAT,
             disable_local_inference=DISABLE_LOCAL_INFERENCE,
             force_remote_inference_on_hf=FORCE_REMOTE_INFERENCE_ON_HF,
             remote_timeout_s=HF_REMOTE_TIMEOUT_SECONDS,
@@ -2539,6 +2560,10 @@ async def index(request: Request):
             "store": store,
             "vessel_prefill": vessel_prefill,
             "use_splash_purple_tabbar": USE_SPLASH_PURPLE_TABBAR,
+            "is_hf_space": IS_HF_SPACE,
+            "disable_local_inference": DISABLE_LOCAL_INFERENCE,
+            "public_demo_disable_chat": PUBLIC_DEMO_DISABLE_CHAT,
+            "public_demo_repo_url": PUBLIC_DEMO_REPO_URL,
         },
     )
 
@@ -3899,6 +3924,24 @@ async def chat(request: Request, _=Depends(require_auth)):
         if not msg:
             _runtime_log("chat.request.invalid", level=logging.WARNING, trace_id=trace_id, reason="empty_message")
             return JSONResponse({"error": "Message is required."}, status_code=status.HTTP_400_BAD_REQUEST)
+        if _chat_disabled_in_hosted_demo(request):
+            _runtime_log(
+                "chat.request.rejected",
+                level=logging.INFO,
+                trace_id=trace_id,
+                reason="hosted_demo_chat_disabled",
+                is_hf_runtime=_request_is_hf_runtime(request),
+                public_demo_disable_chat=PUBLIC_DEMO_DISABLE_CHAT,
+            )
+            return JSONResponse(
+                {
+                    "error": HF_DEMO_CHAT_DISABLED_MESSAGE,
+                    "public_demo_disabled": True,
+                    "is_hf_runtime": _request_is_hf_runtime(request),
+                    "repo_url": PUBLIC_DEMO_REPO_URL,
+                },
+                status_code=status.HTTP_403_FORBIDDEN,
+            )
         user_msg_raw = msg
         p_name = form.get("patient") or ""
         mode = (form.get("mode") or "triage").strip()

run_med_advisor.sh

@@ -24,6 +24,18 @@ fi
 # Activate virtual environment
 source .venv/bin/activate
 
+# Optional local runtime overrides generated during fresh install.
+# This lets us configure a new machine once and keep startup consistent.
+LOCAL_ENV_FILE="${SAILINGMED_LOCAL_ENV:-./sailingmed.local.env}"
+if [ -f "$LOCAL_ENV_FILE" ]; then
+    echo "🔧 Loading local runtime config from $LOCAL_ENV_FILE"
+    # Export sourced vars so child processes (uvicorn/app) receive them.
+    set -a
+    # shellcheck disable=SC1090
+    source "$LOCAL_ENV_FILE"
+    set +a
+fi
+
 # Check if required packages are installed
 python3 -c "import fastapi, uvicorn" 2>/dev/null || {
     echo "❌ Error: FastAPI or Uvicorn not installed. Install with: pip install fastapi uvicorn[standard]"

scripts/bootstrap_ubuntu24_sailingmedadvisor.sh

@@ -28,6 +28,10 @@
 #   --start                Start app after verification
 #   --prefer-gpu-start     Prefer GPU settings when starting app (default is CPU-safe start)
 #   --force-cuda <0|1>     Set FORCE_CUDA explicitly when starting app
+#   --download-models      Download MedGemma model files during install (requires HF token)
+#   --hf-token <token>     Hugging Face token used for optional model download
+#   --configure-system     Configure local runtime defaults during install
+#   --skip-configure       Skip local runtime configuration during install
 #   --help                 Show usage
 
 set -euo pipefail
@@ -39,6 +43,9 @@ SKIP_SYSTEM_PACKAGES="0"
 START_APP="0"
 PREFER_GPU_START="0"
 FORCE_CUDA_OVERRIDE=""
+DOWNLOAD_MODELS="0"
+HF_TOKEN_INPUT=""
+CONFIGURE_VIRGIN_SYSTEM="ask"
 
 usage() {
   cat <<'EOF'
@@ -52,6 +59,10 @@ Flags:
   --start                 Start app after successful verification
   --prefer-gpu-start      Prefer GPU startup flags (default start is CPU-safe)
   --force-cuda <0|1>      Force FORCE_CUDA value when starting app
+  --download-models       Download MedGemma model files during install (requires HF token)
+  --hf-token <token>      Hugging Face token used for optional model download
+  --configure-system      Configure local runtime defaults during install
+  --skip-configure        Skip local runtime configuration during install
   --help                  Show this help text
 EOF
 }
@@ -72,6 +83,14 @@ while [[ $# -gt 0 ]]; do
       PREFER_GPU_START="1"; shift ;;
     --force-cuda)
       FORCE_CUDA_OVERRIDE="$2"; shift 2 ;;
+    --download-models)
+      DOWNLOAD_MODELS="1"; shift ;;
+    --hf-token)
+      HF_TOKEN_INPUT="$2"; shift 2 ;;
+    --configure-system)
+      CONFIGURE_VIRGIN_SYSTEM="1"; shift ;;
+    --skip-configure)
+      CONFIGURE_VIRGIN_SYSTEM="0"; shift ;;
     --help|-h)
       usage; exit 0 ;;
     *)
@@ -128,7 +147,19 @@ install_project() {
   echo "[step] Running project installer"
   cd "$TARGET_DIR"
   chmod +x scripts/install_fresh_copy.sh
-  ./scripts/install_fresh_copy.sh --skip-clone
+  local install_args=(--skip-clone)
+  if [[ "$DOWNLOAD_MODELS" == "1" ]]; then
+    install_args+=(--download-models)
+  fi
+  if [[ -n "$HF_TOKEN_INPUT" ]]; then
+    install_args+=(--hf-token "$HF_TOKEN_INPUT")
+  fi
+  if [[ "$CONFIGURE_VIRGIN_SYSTEM" == "1" ]]; then
+    install_args+=(--configure-system)
+  elif [[ "$CONFIGURE_VIRGIN_SYSTEM" == "0" ]]; then
+    install_args+=(--skip-configure)
+  fi
+  ./scripts/install_fresh_copy.sh "${install_args[@]}"
 }
 
 verify_project() {

scripts/install_fresh_copy.sh

@@ -28,6 +28,9 @@ TARGET_DIR=""
 SKIP_CLONE="0"
 SKIP_VERIFY="0"
 PYTHON_BIN="python3"
+DOWNLOAD_MODELS="ask"
+HF_TOKEN_INPUT=""
+CONFIGURE_VIRGIN_SYSTEM="ask"
 
 usage() {
   cat <<'EOF'
@@ -40,6 +43,10 @@ Options:
   --python <bin>        Python executable (default: python3)
   --skip-clone          Use existing repository in target/current directory
   --skip-verify         Skip post-install verification script
+  --download-models     Download MedGemma model files after install (requires HF token)
+  --hf-token <token>    Hugging Face token used for model download
+  --configure-system    Configure local runtime defaults for this machine
+  --skip-configure      Skip local runtime configuration file generation
   -h, --help            Show this help
 EOF
 }
@@ -58,6 +65,14 @@ while [[ $# -gt 0 ]]; do
       SKIP_CLONE="1"; shift ;;
     --skip-verify)
       SKIP_VERIFY="1"; shift ;;
+    --download-models)
+      DOWNLOAD_MODELS="1"; shift ;;
+    --hf-token)
+      HF_TOKEN_INPUT="$2"; shift 2 ;;
+    --configure-system)
+      CONFIGURE_VIRGIN_SYSTEM="1"; shift ;;
+    --skip-configure)
+      CONFIGURE_VIRGIN_SYSTEM="0"; shift ;;
     -h|--help)
       usage; exit 0 ;;
     *)
@@ -123,6 +138,195 @@ else
   echo "[warn] Verification skipped (--skip-verify)"
 fi
 
+maybe_download_models() {
+  local want_download="$DOWNLOAD_MODELS"
+  if [[ "$want_download" == "ask" ]]; then
+    if [[ -t 0 ]]; then
+      cat <<'EOF'
+
+[optional] MedGemma model predownload
+- This can download many gigabytes (4B is large; 27B is much larger).
+- You need a Hugging Face token with access to MedGemma model repositories.
+- You can skip now and download later in Settings -> Offline Readiness Check.
+EOF
+      read -r -p "Download MedGemma model files now? [y/N]: " reply
+      case "${reply,,}" in
+        y|yes) want_download="1" ;;
+        *) want_download="0" ;;
+      esac
+    else
+      want_download="0"
+    fi
+  fi
+
+  if [[ "$want_download" != "1" ]]; then
+    echo "[info] Skipping model download."
+    return
+  fi
+
+  local token="${HF_TOKEN_INPUT:-${HUGGINGFACE_TOKEN:-${HF_TOKEN:-}}}"
+  if [[ -z "$token" && -t 0 ]]; then
+    read -r -p "Enter Hugging Face token (hf_...) or leave blank to skip: " token
+  fi
+  if [[ -z "$token" ]]; then
+    echo "[warn] No Hugging Face token provided. Skipping model download."
+    echo "       Use Settings -> Offline Readiness Check later when token is available."
+    return
+  fi
+
+  echo "[info] Starting optional MedGemma model download."
+  echo "[info] This may take significant time and disk space."
+  export HUGGINGFACE_TOKEN="$token"
+  export HF_TOKEN="$token"
+  export HF_HOME="$WORKDIR/models_cache"
+  export HUGGINGFACE_HUB_CACHE="$WORKDIR/models_cache/hub"
+  mkdir -p "$HUGGINGFACE_HUB_CACHE"
+
+  set +e
+  ./.venv/bin/python - <<'PY'
+import os
+from huggingface_hub import snapshot_download
+
+models = [
+    "google/medgemma-1.5-4b-it",
+    "google/medgemma-27b-text-it",
+]
+allow_patterns = [
+    "config.json",
+    "generation_config.json",
+    "tokenizer_config.json",
+    "tokenizer.json",
+    "tokenizer.model",
+    "vocab.json",
+    "merges.txt",
+    "preprocessor_config.json",
+    "processor_config.json",
+    "special_tokens_map.json",
+    "model.safetensors",
+    "model.safetensors.index.json",
+    "model-*.safetensors",
+    "chat_template*",
+    "README*",
+]
+
+cache_dir = os.environ.get("HUGGINGFACE_HUB_CACHE")
+token = os.environ.get("HUGGINGFACE_TOKEN") or os.environ.get("HF_TOKEN")
+if not token:
+    raise SystemExit("Missing Hugging Face token.")
+
+for model_name in models:
+    print(f"[model-download] Downloading {model_name} ...", flush=True)
+    snapshot_download(
+        repo_id=model_name,
+        cache_dir=cache_dir,
+        local_dir=None,
+        local_dir_use_symlinks=False,
+        resume_download=True,
+        allow_patterns=allow_patterns,
+        token=token,
+    )
+    print(f"[model-download] Completed {model_name}", flush=True)
+
+print("[model-download] All requested downloads complete.", flush=True)
+PY
+  local rc=$?
+  set -e
+  if [[ $rc -ne 0 ]]; then
+    echo "[warn] Model download did not complete successfully (exit code: $rc)."
+    echo "       You can retry from Settings -> Offline Readiness Check."
+  fi
+}
+
+configure_virgin_system() {
+  local want_config="$CONFIGURE_VIRGIN_SYSTEM"
+  if [[ "$want_config" == "ask" ]]; then
+    if [[ -t 0 ]]; then
+      read -r -p "Create local runtime config for this machine now? [Y/n]: " reply
+      case "${reply,,}" in
+        n|no) want_config="0" ;;
+        *) want_config="1" ;;
+      esac
+    else
+      # Non-interactive install: generate a sane default config automatically.
+      want_config="1"
+    fi
+  fi
+
+  if [[ "$want_config" != "1" ]]; then
+    echo "[info] Skipping local runtime configuration."
+    return
+  fi
+
+  local force_cuda_default="0"
+  if command -v nvidia-smi >/dev/null 2>&1; then
+    force_cuda_default="1"
+  fi
+  local force_cuda="$force_cuda_default"
+  local allow_cpu_fallback="0"
+  local verify_models_on_start="0"
+  local auto_verify_online="0"
+  local model_device_map_27b="manual"
+  local model_gpu_layers_27b="14"
+
+  if [[ -t 0 ]]; then
+    local reply=""
+    if [[ "$force_cuda_default" == "1" ]]; then
+      read -r -p "Prefer GPU startup by default (FORCE_CUDA=1)? [Y/n]: " reply
+      case "${reply,,}" in
+        n|no) force_cuda="0" ;;
+        *) force_cuda="1" ;;
+      esac
+    else
+      read -r -p "No NVIDIA tooling detected. Keep CPU-safe startup (FORCE_CUDA=0)? [Y/n]: " reply
+      case "${reply,,}" in
+        n|no) force_cuda="1" ;;
+        *) force_cuda="0" ;;
+      esac
+    fi
+
+    read -r -p "Allow CPU fallback when CUDA runtime errors occur? [y/N]: " reply
+    case "${reply,,}" in
+      y|yes) allow_cpu_fallback="1" ;;
+      *) allow_cpu_fallback="0" ;;
+    esac
+
+    read -r -p "Verify model cache at startup (slower startup)? [y/N]: " reply
+    case "${reply,,}" in
+      y|yes) verify_models_on_start="1" ;;
+      *) verify_models_on_start="0" ;;
+    esac
+  fi
+
+  local config_file="$WORKDIR/sailingmed.local.env"
+  cat >"$config_file" <<EOF
+# =============================================================================
+# SailingMedAdvisor local runtime configuration
+# Generated by scripts/install_fresh_copy.sh
+# =============================================================================
+FORCE_CUDA=${force_cuda}
+ALLOW_CPU_FALLBACK_ON_CUDA_ERROR=${allow_cpu_fallback}
+DISABLE_LOCAL_INFERENCE=0
+PUBLIC_DEMO_DISABLE_CHAT=0
+VERIFY_MODELS_ON_START=${verify_models_on_start}
+AUTO_VERIFY_ONLINE=${auto_verify_online}
+MODEL_DEVICE_MAP_27B=${model_device_map_27b}
+MODEL_GPU_LAYERS_27B=${model_gpu_layers_27b}
+EOF
+
+  if [[ -d "$WORKDIR/models_cache/hub" ]]; then
+    {
+      echo "HF_HOME=${WORKDIR}/models_cache"
+      echo "HUGGINGFACE_HUB_CACHE=${WORKDIR}/models_cache/hub"
+    } >>"$config_file"
+  fi
+
+  chmod 600 "$config_file" || true
+  echo "[info] Wrote local runtime config: $config_file"
+}
+
+maybe_download_models
+configure_virgin_system
+
 cat <<'EOF'
 
 Installation complete.
@@ -136,4 +340,6 @@ Next steps:
    - Check cache status
    - Download missing models (while online)
    - Enable offline mode before offshore use
+4) Optional local runtime config:
+   - Edit ./sailingmed.local.env to tune startup defaults for this machine
 EOF

static/js/chat.js

@@ -122,6 +122,7 @@ const CHAT_STATE_KEY = 'sailingmed:chatState';
 const SKIP_LAST_CHAT_KEY = 'sailingmed:skipLastChat';
 const EMPTY_RESPONSE_PLACEHOLDER_TEXT = 'No consultation response yet. Expand "Start New Triage Consultation" above and submit to generate guidance.';
 const NO_LOCAL_MODELS_MESSAGE = 'No local MedGemma models are installed. Open Settings -> Offline Readiness Check to download at least one model.';
+const HF_DEMO_UNAVAILABLE_MESSAGE = 'This Hugging Face-hosted build is a demo of an edge system. MedGemma triage/inquiry execution is not available here. Install SailingMedAdvisor locally to run full consultations.';
 const MODEL_CHOICES = [
     { value: 'google/medgemma-1.5-4b-it', label: 'medgemma-1.5-4b-it (local)' },
     { value: 'google/medgemma-27b-text-it', label: 'medgemma-27b-text-it (local)' },
@@ -139,6 +140,37 @@ let modelAvailabilityState = {
     message: '',
 };
 let modelSelectSignature = '';
+const PUBLIC_DEMO_DISABLE_CHAT = !!(window.SMA_RUNTIME && window.SMA_RUNTIME.publicDemoDisableChat);
+const PUBLIC_DEMO_REPO_URL = String(
+    (window.SMA_RUNTIME && window.SMA_RUNTIME.publicDemoRepoUrl)
+    || 'https://github.com/rickeae/SailingMedAdvisor'
+);
+
+function isPublicDemoChatDisabled() {
+    const runtimeFlag = !!(window.SMA_RUNTIME && window.SMA_RUNTIME.isHfSpace);
+    return PUBLIC_DEMO_DISABLE_CHAT || runtimeFlag || isHfHostedRuntime();
+}
+
+function closePublicDemoChatDisabledModal() {
+    const modal = document.getElementById('public-demo-chat-disabled-modal');
+    if (modal) modal.style.display = 'none';
+}
+
+function showPublicDemoChatDisabledModal() {
+    const modal = document.getElementById('public-demo-chat-disabled-modal');
+    if (!modal) {
+        alert(HF_DEMO_UNAVAILABLE_MESSAGE);
+        return;
+    }
+    const repoLink = document.getElementById('public-demo-repo-link');
+    if (repoLink) {
+        repoLink.href = PUBLIC_DEMO_REPO_URL;
+        repoLink.textContent = PUBLIC_DEMO_REPO_URL;
+    }
+    modal.style.display = 'flex';
+}
+
+window.closePublicDemoChatDisabledModal = closePublicDemoChatDisabledModal;
 
 function isHfHostedRuntime() {
     try {
@@ -1074,9 +1106,10 @@ function updateUI() {
     const chatModelWarning = document.getElementById('chat-model-availability-warning');
     const promptRefreshInline = document.getElementById('prompt-refresh-inline');
     const promptHeader = document.getElementById('prompt-preview-header');
+    const demoChatBlocked = isPublicDemoChatDisabled();
     const localModelsAvailable = hasRunnableLocalModel();
     const noModels = !localModelsAvailable;
-    const noModelsMsg = noLocalModelsMessage();
+    const noModelsMsg = demoChatBlocked ? HF_DEMO_UNAVAILABLE_MESSAGE : noLocalModelsMessage();
     
     // Remove both classes first
     banner.classList.remove('inquiry-mode', 'private-mode', 'no-privacy');
@@ -1166,10 +1199,11 @@ function updateUI() {
         }
     }
     if (runBtn) {
-        runBtn.disabled = isSessionActive() || noModels;
+        // Keep submit clickable in hosted demo mode so we can show the explanatory popup.
+        runBtn.disabled = isSessionActive() || (noModels && !demoChatBlocked);
     }
     if (sendBtn) {
-        sendBtn.disabled = !isSessionActive() || noModels;
+        sendBtn.disabled = !isSessionActive() || (noModels && !demoChatBlocked);
         sendBtn.title = noModels ? noModelsMsg : '';
     }
     if (startModelWarning) {
@@ -1475,6 +1509,10 @@ function buildSessionMetaPayload({ initialQuery, patientId, patientName, mode })
 }
 
 async function submitChatMessage({ message, isStart, force28b = false, queueWait = false }) {
+    if (isPublicDemoChatDisabled()) {
+        showPublicDemoChatDisabledModal();
+        return;
+    }
     const txt = (message || '').trim();
     if (!txt || isProcessing) return;
     if (!hasRunnableLocalModel()) {
@@ -1718,6 +1756,10 @@ async function submitChatMessage({ message, isStart, force28b = false, queueWait
 }
 
 async function runChat(promptText = null, force28b = false) {
+    if (isPublicDemoChatDisabled()) {
+        showPublicDemoChatDisabledModal();
+        return;
+    }
     if (!hasRunnableLocalModel()) {
         alert(noLocalModelsMessage());
         updateUI();
@@ -1746,6 +1788,10 @@ async function runChat(promptText = null, force28b = false) {
 }
 
 async function sendChatMessage() {
+    if (isPublicDemoChatDisabled()) {
+        showPublicDemoChatDisabledModal();
+        return;
+    }
     if (!hasRunnableLocalModel()) {
         alert(noLocalModelsMessage());
         updateUI();

templates/index.html

@@ -181,9 +181,32 @@
         .btn-row { display: flex; gap: 8px; margin-top: 10px; }
         .btn-sm { padding: 6px 12px; font-size: 13px; }
         .crew-header { display: flex; justify-content: space-between; align-items: center; margin-bottom: 15px; }
+        /* Settings page section ordering */
+        #Settings .panel-wrapper {
+            display: flex;
+            flex-direction: column;
+        }
+        #Settings .settings-section-medgemma { order: 1; }
+        #Settings .settings-section-user-mode { order: 2; }
+        #Settings .settings-section-offline { order: 3; }
+        #Settings .settings-section-runtime-log { order: 4; }
+        #Settings .settings-section-last-prompt { order: 5; }
+        #Settings .settings-section-crew-creds { order: 6; }
+        #Settings .settings-section-vax-types { order: 7; }
+        #Settings .settings-section-pharmacy-labels { order: 8; }
+        #Settings .settings-section-default-export { order: 9; }
         
         .btn { padding: 10px 20px; color: white; border: none; border-radius: 4px; cursor: pointer; font-weight: bold; transition: opacity 0.3s; }
         .btn:disabled { opacity: 0.5; cursor: not-allowed; }
+        .triage-action-btn {
+            background: #1f4f8f !important;
+            color: #fff !important;
+            padding: 6px 12px !important;
+            min-width: 116px;
+            text-align: center;
+            border-radius: 6px;
+            font-weight: 800;
+        }
         .export-cta-btn {
             display: inline-flex;
             align-items: center;
@@ -1125,7 +1148,7 @@
             <div class="page-body sidebar-open">
             <div class="page-main">
                 <div class="panel-wrapper">
-                    <div class="collapsible" style="margin-bottom:12px;">
+                    <div class="collapsible settings-section settings-section-crew-creds" style="margin-bottom:12px;">
                         <div class="col-header crew-med-header" onclick="toggleSection(this)" style="background:#fff; justify-content:flex-start;">
                             <span class="dev-tag">dev:settings-crew-creds</span><span class="detail-icon history-arrow" style="font-size:18px; margin-right:8px;">▸</span><span style="font-weight:700;">Crew Login Credentials</span>
                             <span id="crew-creds-meta" style="margin-left:auto; font-size:12px; color:#4a5568;"></span>
@@ -1134,7 +1157,7 @@
                             <div id="crew-credentials"></div>
                         </div>
                     </div>
-                    <div class="collapsible" style="margin-bottom:12px;">
+                    <div class="collapsible settings-section settings-section-vax-types" style="margin-bottom:12px;">
                         <div class="col-header crew-med-header" onclick="toggleSection(this)" style="background:#fff; justify-content:flex-start;">
                             <span class="dev-tag">dev:settings-vax-types</span><span class="detail-icon history-arrow" style="font-size:18px; margin-right:8px;">▸</span><span style="font-weight:700;">Vaccine Type Dropdown</span>
                             <span id="vax-meta" style="margin-left:auto; font-size:12px; color:#4a5568;"></span>
@@ -1150,7 +1173,7 @@
                             <div id="vaccine-types-status" style="margin-top:8px; font-size:12px; color:#555;">Saved with app settings.</div>
                         </div>
                     </div>
-                    <div class="collapsible" style="margin-bottom:12px;">
+                    <div class="collapsible settings-section settings-section-pharmacy-labels" style="margin-bottom:12px;">
                         <div class="col-header crew-med-header" onclick="toggleSection(this)" style="background:#fff; justify-content:flex-start;">
                             <span class="dev-tag">dev:settings-pharmacy-labels</span><span class="detail-icon history-arrow" style="font-size:18px; margin-right:8px;">▸</span><span style="font-weight:700;">Pharmaceutical User Labels</span>
                             <span id="pharm-meta" style="margin-left:auto; font-size:12px; color:#4a5568;"></span>
@@ -1166,7 +1189,7 @@
                             <div id="pharmacy-labels-status" style="margin-top:8px; font-size:12px; color:#555;">Saved with app settings.</div>
                         </div>
                     </div>
-                    <div class="collapsible" style="margin-bottom:12px;">
+                    <div class="collapsible settings-section settings-section-user-mode" style="margin-bottom:12px;">
                         <div class="col-header crew-med-header" onclick="toggleSection(this)" style="background:#fff; justify-content:flex-start;">
                             <span class="dev-tag">dev:settings-usermode</span><span class="detail-icon history-arrow" style="font-size:18px; margin-right:8px;">▸</span><span style="font-weight:700;">User Mode</span>
                             <span id="user-mode-meta" style="margin-left:auto; font-size:12px; color:#4a5568;"></span>
@@ -1193,7 +1216,7 @@
                             </div>
                         </div>
                     </div>
-                    <div class="collapsible" style="margin-bottom:12px;">
+                    <div class="collapsible settings-section settings-section-offline" style="margin-bottom:12px;">
                         <div class="col-header crew-med-header" onclick="toggleSection(this)" style="background:#fff; justify-content:flex-start;">
                             <span class="dev-tag">dev:settings-offline</span><span class="detail-icon history-arrow" style="font-size:18px; margin-right:8px;">▸</span><span style="font-weight:700;">Offline Readiness Check</span>
                             <span id="offline-meta" style="margin-left:auto; font-size:12px; color:#4a5568;"></span>
@@ -1217,7 +1240,7 @@
                             <div style="font-size:12px; color:#555;">Recommended sequence: Run readiness check → Download missing models → Create backup snapshot → Enable offline mode.</div>
                         </div>
                     </div>
-                    <div class="collapsible" style="margin-bottom:12px;">
+                    <div class="collapsible settings-section settings-section-runtime-log" style="margin-bottom:12px;">
                         <div class="col-header crew-med-header" onclick="toggleSection(this)" style="background:#fff; justify-content:flex-start;">
                             <span class="dev-tag">dev:settings-runtime-log</span><span class="detail-icon history-arrow" style="font-size:18px; margin-right:8px;">▸</span><span style="font-weight:700;">Runtime Debug Log (HF)</span>
                             <span id="runtime-log-meta" style="margin-left:auto; font-size:12px; color:#4a5568;"></span>
@@ -1237,7 +1260,7 @@
                             <textarea id="runtime-log-text" data-settings-no-autosave="1" readonly style="width:100%; min-height:240px; font-family:Menlo, Consolas, monospace; font-size:12px; line-height:1.35; background:#fff;"></textarea>
                         </div>
                     </div>
-                    <div class="collapsible" style="margin-bottom:12px;">
+                    <div class="collapsible settings-section settings-section-last-prompt" style="margin-bottom:12px;">
                         <div class="col-header crew-med-header" onclick="toggleSection(this)" style="background:#fff; justify-content:flex-start;">
                             <span class="dev-tag">dev:settings-last-prompt</span><span class="detail-icon history-arrow" style="font-size:18px; margin-right:8px;">▸</span><span style="font-weight:700;">Last Prompt Verbatim</span>
                         </div>
@@ -1246,7 +1269,7 @@
                             <textarea id="last_prompt_verbatim" readonly style="width:100%; min-height:160px;"></textarea>
                         </div>
                     </div>
-                    <div class="collapsible developer-only" style="margin-bottom:12px; display:none;">
+                    <div class="collapsible developer-only settings-section settings-section-default-export" style="margin-bottom:12px; display:none;">
                         <div class="col-header crew-med-header" onclick="toggleSection(this)" style="background:#fff; justify-content:flex-start;">
                             <span class="dev-tag">dev:settings-default-export</span><span class="detail-icon history-arrow" style="font-size:18px; margin-right:8px;">▸</span><span style="font-weight:700;">Export Default Dataset (Dev)</span>
                         </div>
@@ -1256,7 +1279,7 @@
                             <div id="default-export-status" style="margin-top:8px; font-size:12px; color:#555;"></div>
                         </div>
                     </div>
-                    <div class="collapsible" style="margin-top:12px;">
+                    <div class="collapsible settings-section settings-section-medgemma" style="margin-bottom:12px;">
                         <div class="col-header crew-med-header" onclick="toggleSection(this)" style="background:#fff; justify-content:flex-start;">
                             <span class="dev-tag">dev:settings-models</span><span class="detail-icon history-arrow" style="font-size:18px; margin-right:8px;">▸</span><span style="font-weight:700;">MedGemma Model Parameters</span>
                             <span id="model-meta" style="margin-left:auto; font-size:12px; color:#4a5568;"></span>
@@ -1281,8 +1304,18 @@
                                 </div>
                                 <div class="col-body" style="padding:12px; background:#f8f9fa; display:none;">
                                     <div style="padding:10px; border:1px solid #dde3ec; border-radius:8px; background:#fff; margin-bottom:12px;">
-                                        <div style="font-size:12px; color:#4a5568; margin-bottom:10px; font-weight:700;">
-                                            Generation Parameters (Inquiry Only)
+                                        <div style="display:flex; align-items:center; justify-content:space-between; gap:10px; margin-bottom:10px; flex-wrap:wrap;">
+                                            <div style="font-size:12px; color:#4a5568; font-weight:700;">
+                                                Generation Parameters (Inquiry Only)
+                                            </div>
+                                            <button
+                                                type="button"
+                                                class="btn btn-sm"
+                                                style="background:#1f4f8f; color:#fff; padding:5px 10px;"
+                                                onclick="showGenerationParametersHelp('inquiry')"
+                                            >
+                                                What do these mean?
+                                            </button>
                                         </div>
                                         <div style="display:flex; gap:20px; align-items:center; flex-wrap:wrap;">
                                             <div style="display:flex; align-items:center; gap:6px;">
@@ -1326,12 +1359,22 @@
 
                             <div class="collapsible" style="margin-bottom:12px;">
                                 <div class="col-header crew-med-header" data-pref-key="settings-triage-open" onclick="toggleSection(this)" style="background:#fff; justify-content:flex-start;">
-                                    <span class="dev-tag">dev:settings-triage</span><span class="detail-icon history-arrow" style="font-size:18px; margin-right:8px;">▸</span><span style="font-weight:700;">Triage</span>
+                                    <span class="dev-tag">dev:settings-triage</span><span class="detail-icon history-arrow" style="font-size:18px; margin-right:8px;">▸</span><span style="font-weight:700;">Triage Consultation Prompt (General and Clinical Triage Pathway Builder)</span>
                                 </div>
                                 <div class="col-body" style="padding:12px; background:#f8f9fa; display:none;">
                                     <div style="padding:10px; border:1px solid #dde3ec; border-radius:8px; background:#fff; margin-bottom:12px;">
-                                        <div style="font-size:12px; color:#4a5568; margin-bottom:10px; font-weight:700;">
-                                            Generation Parameters (Triage Only)
+                                        <div style="display:flex; align-items:center; justify-content:space-between; gap:10px; margin-bottom:10px; flex-wrap:wrap;">
+                                            <div style="font-size:12px; color:#4a5568; font-weight:700;">
+                                                Generation Parameters (Triage Only)
+                                            </div>
+                                            <button
+                                                type="button"
+                                                class="btn btn-sm"
+                                                style="background:#1f4f8f; color:#fff; padding:5px 10px;"
+                                                onclick="showGenerationParametersHelp('triage')"
+                                            >
+                                                What do these mean?
+                                            </button>
                                         </div>
                                         <div style="display:flex; gap:20px; align-items:center; flex-wrap:wrap;">
                                             <div style="display:flex; align-items:center; gap:6px;">
@@ -1351,7 +1394,7 @@
                                                 <input type="number" id="tr_k" style="width:70px;">
                                             </div>
                                             <div style="margin-left:auto;">
-                                                <button class="btn btn-sm" style="background:var(--inquiry);" onclick="resetSection('triage')">Reset to Default</button>
+                                                <button class="btn btn-sm triage-action-btn" onclick="resetSection('triage')">Reset to Default</button>
                                             </div>
                                         </div>
                                     </div>
@@ -1383,9 +1426,9 @@
                                         <div class="col-header crew-med-header" data-pref-key="settings-triage-pathway-open" onclick="toggleSection(this)" style="background:#fff; justify-content:flex-start;">
                                             <span class="dev-tag">dev:settings-triage-tree</span><span class="detail-icon history-arrow" style="font-size:16px; margin-right:8px;">▸</span><span style="font-weight:700;">Clinical Triage Pathway Prompt Builder</span>
                                             <span style="margin-left:auto; display:flex; gap:6px;" onclick="event.stopPropagation();">
-                                                <button class="btn btn-sm" style="background:#0b8457;" onclick="event.stopPropagation(); exportTriagePromptTreeJson();">Export</button>
-                                                <button class="btn btn-sm" style="background:#0f766e;" onclick="event.stopPropagation(); triggerTriagePromptTreeImportPicker();">Import</button>
-                                                <button class="btn btn-sm" style="background:#4a5568;" onclick="event.stopPropagation(); resetTriagePromptTreeToDefault();">Reset to Default</button>
+                                                <button class="btn btn-sm triage-action-btn" onclick="event.stopPropagation(); exportTriagePromptTreeJson();">Export</button>
+                                                <button class="btn btn-sm triage-action-btn" onclick="event.stopPropagation(); triggerTriagePromptTreeImportPicker();">Import</button>
+                                                <button class="btn btn-sm triage-action-btn" onclick="event.stopPropagation(); resetTriagePromptTreeToDefault();">Reset to Default</button>
                                             </span>
                                         </div>
                                         <div class="col-body" style="padding:12px; background:#f8f9fa; display:none;">
@@ -1520,9 +1563,70 @@
         </div>
     </div>
 
+    <div
+        id="gen-params-help-modal"
+        style="display:none; position:fixed; inset:0; z-index:2100; background:rgba(6,28,48,0.55); align-items:center; justify-content:center; padding:20px;"
+        onclick="if (event.target === this) closeGenerationParametersHelp()"
+    >
+        <div style="background:#fff; border-radius:14px; box-shadow:0 18px 48px rgba(0,0,0,0.25); max-width:700px; width:100%; max-height:min(84vh, 780px); overflow:auto; padding:20px; border:1px solid #d8e2f5;">
+            <div id="gen-params-help-title" style="font-size:20px; font-weight:800; color:#122b4d; margin-bottom:10px;">Generation Parameters</div>
+            <div id="gen-params-help-body" style="font-size:14px; color:#2c3e50; line-height:1.5;"></div>
+            <div style="margin-top:14px; display:flex; justify-content:flex-end;">
+                <button class="btn btn-sm" style="background:#2c3e50;" onclick="closeGenerationParametersHelp()">Close</button>
+            </div>
+        </div>
+    </div>
+
+    <div
+        id="public-demo-chat-disabled-modal"
+        style="display:none; position:fixed; inset:0; z-index:2150; background:rgba(6,28,48,0.58); align-items:center; justify-content:center; padding:20px;"
+        onclick="if (event.target === this) closePublicDemoChatDisabledModal()"
+    >
+        <div style="background:#fff; border-radius:14px; box-shadow:0 18px 48px rgba(0,0,0,0.25); max-width:760px; width:100%; max-height:min(88vh, 900px); overflow:auto; padding:20px; border:1px solid #d8e2f5;">
+            <div style="font-size:20px; font-weight:800; color:#122b4d; margin-bottom:10px;">
+                MedGemma Is Not Available In This Hugging Face Demo
+            </div>
+            <div style="font-size:14px; color:#2c3e50; line-height:1.5;">
+                <p style="margin:0 0 10px 0;">
+                    This is a demo of a system that runs on the edge. MedGemma triage/inquiry execution is not available in this Hugging Face-hosted version.
+                </p>
+                <p style="margin:0 0 10px 0;">
+                    To run full MedGemma functionality, install locally from:
+                    <a id="public-demo-repo-link" href="#" target="_blank" rel="noopener">SailingMedAdvisor GitHub repository</a>.
+                </p>
+                <div style="background:#f8fbff; border:1px solid #d5e6fb; border-radius:8px; padding:10px; margin:0 0 10px 0;">
+                    <div style="font-weight:800; margin-bottom:6px;">Quick local setup</div>
+                    <ol style="margin:0 0 0 18px; padding:0;">
+                        <li><code>git clone https://github.com/rickeae/SailingMedAdvisor.git</code></li>
+                        <li><code>cd SailingMedAdvisor</code></li>
+                        <li><code>chmod +x scripts/bootstrap_ubuntu24_sailingmedadvisor.sh</code></li>
+                        <li><code>./scripts/bootstrap_ubuntu24_sailingmedadvisor.sh --start --configure-system</code></li>
+                    </ol>
+                </div>
+                <div style="background:#fff7ed; border:1px solid #f4c89a; border-radius:8px; padding:10px;">
+                    <div style="font-weight:800; margin-bottom:6px;">Before downloading models</div>
+                    <ul style="margin:0 0 0 18px; padding:0;">
+                        <li>Model downloads are large (multi-GB; 27B is significantly larger).</li>
+                        <li>You need a Hugging Face token with access to the MedGemma model repositories.</li>
+                        <li>Use Settings → Offline Readiness Check to download and verify model cache while online.</li>
+                    </ul>
+                </div>
+            </div>
+            <div style="margin-top:14px; display:flex; justify-content:flex-end;">
+                <button class="btn btn-sm" style="background:#2c3e50;" onclick="closePublicDemoChatDisabledModal()">Close</button>
+            </div>
+        </div>
+    </div>
+
     <script>
         // Preload vessel data from server-rendered context to avoid empty fields if API fetch is delayed or fails
         window.VESSEL_PREFILL = {{ vessel_prefill|tojson|safe }};
+        window.SMA_RUNTIME = {
+            isHfSpace: {{ is_hf_space|tojson|safe }},
+            disableLocalInference: {{ disable_local_inference|tojson|safe }},
+            publicDemoDisableChat: {{ public_demo_disable_chat|tojson|safe }},
+            publicDemoRepoUrl: {{ public_demo_repo_url|tojson|safe }},
+        };
     </script>
     <script src="/static/js/utils.js?v=20260226"></script>
     <script src="/static/js/chat.js?v=20260325"></script>
@@ -1596,6 +1700,39 @@
         }
     }
 
+    function showGenerationParametersHelp(mode) {
+        const modal = document.getElementById('gen-params-help-modal');
+        const title = document.getElementById('gen-params-help-title');
+        const body = document.getElementById('gen-params-help-body');
+        if (!modal || !title || !body) return;
+        const normalized = mode === 'triage' ? 'triage' : 'inquiry';
+        const modeLabel = normalized === 'triage' ? 'Triage Consultation' : 'Inquiry Consultation';
+        const usageHint = normalized === 'triage'
+            ? '<p style="margin:0 0 10px 0;"><strong>For triage:</strong> lower creativity is usually safer. Start with lower Temperature and keep Top-P/Top-K conservative.</p>'
+            : '<p style="margin:0 0 10px 0;"><strong>For inquiry:</strong> you can allow a little more flexibility if you want broader explanations.</p>';
+        title.textContent = `${modeLabel}: What these 4 settings mean`;
+        body.innerHTML = `
+            ${usageHint}
+            <div style="display:grid; gap:8px;">
+                <div><strong>Temperature</strong>: Controls how strict vs. creative the wording is. Lower = more consistent and predictable. Higher = more varied.</div>
+                <div><strong>Top-P</strong>: Controls how wide the model's word choices are. Lower = safer and narrower choices. Higher = broader choices.</div>
+                <div><strong>Top-K</strong>: Limits choices to the top K likely words each step. Smaller K = tighter and more focused. Larger K = more variety.</div>
+                <div><strong>Tokens</strong>: Maximum response length. Higher values allow longer answers. Lower values produce shorter answers and faster return.</div>
+            </div>
+            <p style="margin:10px 0 0 0;"><strong>Simple rule:</strong> If output feels too random, lower Temperature/Top-P/Top-K. If output is too short, increase Tokens.</p>
+        `;
+        modal.style.display = 'flex';
+    }
+
+    function closeGenerationParametersHelp() {
+        const modal = document.getElementById('gen-params-help-modal');
+        if (modal) modal.style.display = 'none';
+    }
+
+    document.addEventListener('keydown', function(evt) {
+        if (evt.key === 'Escape') closeGenerationParametersHelp();
+    });
+
     document.addEventListener('DOMContentLoaded', checkDbStatus);
 </script>
 </body>