HF deploy snapshot (no app.db)

.gitattributes

@@ -0,0 +1 @@
+seed/app.db filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,56 @@
+# --- Existing entries ---
+.env.*
+data/
+datasets/
+outputs/
+runs/
+wandb/
+mlruns/
+checkpoints/
+*.pt
+*.pth
+*.ckpt
+*.safetensors
+*.bin
+
+# --- New FastAPI/Python Additions ---
+venv/
+.env
+__pycache__/
+*.pyc
+.pytest_cache/
+.vscode/
+.codium/
+
+# --- Data logic (Keep as is if you want JSONs in Gitea) ---
+data/*
+!data/.gitkeep
+!data/*.json
+!data/default/
+!data/default/*.json
+!data/default/uploads/
+!data/default/uploads/medicines/
+# Local secrets (keep out of version control)
+templates/sidebars/SailingMedAdvisorDeloy\ token\ Huggingface
+
+# Local virtualenvs
+.venv/
+venv/
+# Editor/temp artifacts
+*.swp
+
+# Local DB/runtime artifacts
+# Keep primary app.db tracked for deployment/demo portability.
+app.db.*
+seed/*.db
+not_needed/
+
+# Local scratch/export artifacts
+server.log
+Untitled Folder/
+*_export_text.txt
+consumables
+consumables to import.txt
+non-consumables to import.txt
+who list for import.txt
+copy_pharm_lorraine_to_rick.sh

Dockerfile

@@ -0,0 +1,36 @@
+# =============================================================================
+# Author: Rick Escher
+# Project: SailingMedAdvisor
+# Context: Google HAI-DEF Framework
+# Models: Google MedGemmas
+# Program: Kaggle Impact Challenge
+# =============================================================================
+
+FROM python:3.10-slim
+
+# 1. Install system tools as ROOT
+RUN apt-get update && apt-get install -y build-essential curl && rm -rf /var/lib/apt/lists/*
+
+# 2. Setup the user but STAY as root for a moment
+RUN useradd -m -u 1000 user
+WORKDIR /home/user/app
+
+# 3. Create the folder while still ROOT
+RUN mkdir -p /home/user/app/data \
+             /home/user/app/uploads/medicines \
+             /home/user/app/offload \
+             /home/user/app/models_cache \
+             /home/user/app/backups && \
+    chown -R user:user /home/user/app
+
+# 4. NOW switch to the user
+USER user
+ENV HOME=/home/user \
+    PATH=/home/user/.local/bin:$PATH
+
+# 5. Copy files and install (using --chown for safety)
+COPY --chown=user requirements.txt .
+RUN pip install --no-cache-dir --upgrade -r requirements.txt
+COPY --chown=user . .
+
+CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "7860"]

LICENSE

@@ -0,0 +1,396 @@
+Attribution 4.0 International
+
+=======================================================================
+
+Creative Commons Corporation ("Creative Commons") is not a law firm and
+does not provide legal services or legal advice. Distribution of
+Creative Commons public licenses does not create a lawyer-client or
+other relationship. Creative Commons makes its licenses and related
+information available on an "as-is" basis. Creative Commons gives no
+warranties regarding its licenses, any material licensed under their
+terms and conditions, or any related information. Creative Commons
+disclaims all liability for damages resulting from their use to the
+fullest extent possible.
+
+Using Creative Commons Public Licenses
+
+Creative Commons public licenses provide a standard set of terms and
+conditions that creators and other rights holders may use to share
+original works of authorship and other material subject to copyright
+and certain other rights specified in the public license below. The
+following considerations are for informational purposes only, are not
+exhaustive, and do not form part of our licenses.
+
+     Considerations for licensors: Our public licenses are
+     intended for use by those authorized to give the public
+     permission to use material in ways otherwise restricted by
+     copyright and certain other rights. Our licenses are
+     irrevocable. Licensors should read and understand the terms
+     and conditions of the license they choose before applying it.
+     Licensors should also secure all rights necessary before
+     applying our licenses so that the public can reuse the
+     material as expected. Licensors should clearly mark any
+     material not subject to the license. This includes other CC-
+     licensed material, or material used under an exception or
+     limitation to copyright. More considerations for licensors:
+    wiki.creativecommons.org/Considerations_for_licensors
+
+     Considerations for the public: By using one of our public
+     licenses, a licensor grants the public permission to use the
+     licensed material under specified terms and conditions. If
+     the licensor's permission is not necessary for any reason--for
+     example, because of any applicable exception or limitation to
+     copyright--then that use is not regulated by the license. Our
+     licenses grant only permissions under copyright and certain
+     other rights that a licensor has authority to grant. Use of
+     the licensed material may still be restricted for other
+     reasons, including because others have copyright or other
+     rights in the material. A licensor may make special requests,
+     such as asking that all changes be marked or described.
+     Although not required by our licenses, you are encouraged to
+     respect those requests where reasonable. More considerations
+     for the public:
+    wiki.creativecommons.org/Considerations_for_licensees
+
+=======================================================================
+
+Creative Commons Attribution 4.0 International Public License
+
+By exercising the Licensed Rights (defined below), You accept and agree
+to be bound by the terms and conditions of this Creative Commons
+Attribution 4.0 International Public License ("Public License"). To the
+extent this Public License may be interpreted as a contract, You are
+granted the Licensed Rights in consideration of Your acceptance of
+these terms and conditions, and the Licensor grants You such rights in
+consideration of benefits the Licensor receives from making the
+Licensed Material available under these terms and conditions.
+
+
+Section 1 -- Definitions.
+
+  a. Adapted Material means material subject to Copyright and Similar
+     Rights that is derived from or based upon the Licensed Material
+     and in which the Licensed Material is translated, altered,
+     arranged, transformed, or otherwise modified in a manner requiring
+     permission under the Copyright and Similar Rights held by the
+     Licensor. For purposes of this Public License, where the Licensed
+     Material is a musical work, performance, or sound recording,
+     Adapted Material is always produced where the Licensed Material is
+     synched in timed relation with a moving image.
+
+  b. Adapter's License means the license You apply to Your Copyright
+     and Similar Rights in Your contributions to Adapted Material in
+     accordance with the terms and conditions of this Public License.
+
+  c. Copyright and Similar Rights means copyright and/or similar rights
+     closely related to copyright including, without limitation,
+     performance, broadcast, sound recording, and Sui Generis Database
+     Rights, without regard to how the rights are labeled or
+     categorized. For purposes of this Public License, the rights
+     specified in Section 2(b)(1)-(2) are not Copyright and Similar
+     Rights.
+
+  d. Effective Technological Measures means those measures that, in the
+     absence of proper authority, may not be circumvented under laws
+     fulfilling obligations under Article 11 of the WIPO Copyright
+     Treaty adopted on December 20, 1996, and/or similar international
+     agreements.
+
+  e. Exceptions and Limitations means fair use, fair dealing, and/or
+     any other exception or limitation to Copyright and Similar Rights
+     that applies to Your use of the Licensed Material.
+
+  f. Licensed Material means the artistic or literary work, database,
+     or other material to which the Licensor applied this Public
+     License.
+
+  g. Licensed Rights means the rights granted to You subject to the
+     terms and conditions of this Public License, which are limited to
+     all Copyright and Similar Rights that apply to Your use of the
+     Licensed Material and that the Licensor has authority to license.
+
+  h. Licensor means the individual(s) or entity(ies) granting rights
+     under this Public License.
+
+  i. Share means to provide material to the public by any means or
+     process that requires permission under the Licensed Rights, such
+     as reproduction, public display, public performance, distribution,
+     dissemination, communication, or importation, and to make material
+     available to the public including in ways that members of the
+     public may access the material from a place and at a time
+     individually chosen by them.
+
+  j. Sui Generis Database Rights means rights other than copyright
+     resulting from Directive 96/9/EC of the European Parliament and of
+     the Council of 11 March 1996 on the legal protection of databases,
+     as amended and/or succeeded, as well as other essentially
+     equivalent rights anywhere in the world.
+
+  k. You means the individual or entity exercising the Licensed Rights
+     under this Public License. Your has a corresponding meaning.
+
+
+Section 2 -- Scope.
+
+  a. License grant.
+
+       1. Subject to the terms and conditions of this Public License,
+          the Licensor hereby grants You a worldwide, royalty-free,
+          non-sublicensable, non-exclusive, irrevocable license to
+          exercise the Licensed Rights in the Licensed Material to:
+
+            a. reproduce and Share the Licensed Material, in whole or
+               in part; and
+
+            b. produce, reproduce, and Share Adapted Material.
+
+       2. Exceptions and Limitations. For the avoidance of doubt, where
+          Exceptions and Limitations apply to Your use, this Public
+          License does not apply, and You do not need to comply with
+          its terms and conditions.
+
+       3. Term. The term of this Public License is specified in Section
+          6(a).
+
+       4. Media and formats; technical modifications allowed. The
+          Licensor authorizes You to exercise the Licensed Rights in
+          all media and formats whether now known or hereafter created,
+          and to make technical modifications necessary to do so. The
+          Licensor waives and/or agrees not to assert any right or
+          authority to forbid You from making technical modifications
+          necessary to exercise the Licensed Rights, including
+          technical modifications necessary to circumvent Effective
+          Technological Measures. For purposes of this Public License,
+          simply making modifications authorized by this Section 2(a)
+          (4) never produces Adapted Material.
+
+       5. Downstream recipients.
+
+            a. Offer from the Licensor -- Licensed Material. Every
+               recipient of the Licensed Material automatically
+               receives an offer from the Licensor to exercise the
+               Licensed Rights under the terms and conditions of this
+               Public License.
+
+            b. No downstream restrictions. You may not offer or impose
+               any additional or different terms or conditions on, or
+               apply any Effective Technological Measures to, the
+               Licensed Material if doing so restricts exercise of the
+               Licensed Rights by any recipient of the Licensed
+               Material.
+
+       6. No endorsement. Nothing in this Public License constitutes or
+          may be construed as permission to assert or imply that You
+          are, or that Your use of the Licensed Material is, connected
+          with, or sponsored, endorsed, or granted official status by,
+          the Licensor or others designated to receive attribution as
+          provided in Section 3(a)(1)(A)(i).
+
+  b. Other rights.
+
+       1. Moral rights, such as the right of integrity, are not
+          licensed under this Public License, nor are publicity,
+          privacy, and/or other similar personality rights; however, to
+          the extent possible, the Licensor waives and/or agrees not to
+          assert any such rights held by the Licensor to the limited
+          extent necessary to allow You to exercise the Licensed
+          Rights, but not otherwise.
+
+       2. Patent and trademark rights are not licensed under this
+          Public License.
+
+       3. To the extent possible, the Licensor waives any right to
+          collect royalties from You for the exercise of the Licensed
+          Rights, whether directly or through a collecting society
+          under any voluntary or waivable statutory or compulsory
+          licensing scheme. In all other cases the Licensor expressly
+          reserves any right to collect such royalties.
+
+
+Section 3 -- License Conditions.
+
+Your exercise of the Licensed Rights is expressly made subject to the
+following conditions.
+
+  a. Attribution.
+
+       1. If You Share the Licensed Material (including in modified
+          form), You must:
+
+            a. retain the following if it is supplied by the Licensor
+               with the Licensed Material:
+
+                 i. identification of the creator(s) of the Licensed
+                    Material and any others designated to receive
+                    attribution, in any reasonable manner requested by
+                    the Licensor (including by pseudonym if
+                    designated);
+
+                ii. a copyright notice;
+
+               iii. a notice that refers to this Public License;
+
+                iv. a notice that refers to the disclaimer of
+                    warranties;
+
+                 v. a URI or hyperlink to the Licensed Material to the
+                    extent reasonably practicable;
+
+            b. indicate if You modified the Licensed Material and
+               retain an indication of any previous modifications; and
+
+            c. indicate the Licensed Material is licensed under this
+               Public License, and include the text of, or the URI or
+               hyperlink to, this Public License.
+
+       2. You may satisfy the conditions in Section 3(a)(1) in any
+          reasonable manner based on the medium, means, and context in
+          which You Share the Licensed Material. For example, it may be
+          reasonable to satisfy the conditions by providing a URI or
+          hyperlink to a resource that includes the required
+          information.
+
+       3. If requested by the Licensor, You must remove any of the
+          information required by Section 3(a)(1)(A) to the extent
+          reasonably practicable.
+
+       4. If You Share Adapted Material You produce, the Adapter's
+          License You apply must not prevent recipients of the Adapted
+          Material from complying with this Public License.
+
+
+Section 4 -- Sui Generis Database Rights.
+
+Where the Licensed Rights include Sui Generis Database Rights that
+apply to Your use of the Licensed Material:
+
+  a. for the avoidance of doubt, Section 2(a)(1) grants You the right
+     to extract, reuse, reproduce, and Share all or a substantial
+     portion of the contents of the database;
+
+  b. if You include all or a substantial portion of the database
+     contents in a database in which You have Sui Generis Database
+     Rights, then the database in which You have Sui Generis Database
+     Rights (but not its individual contents) is Adapted Material; and
+
+  c. You must comply with the conditions in Section 3(a) if You Share
+     all or a substantial portion of the contents of the database.
+
+For the avoidance of doubt, this Section 4 supplements and does not
+replace Your obligations under this Public License where the Licensed
+Rights include other Copyright and Similar Rights.
+
+
+Section 5 -- Disclaimer of Warranties and Limitation of Liability.
+
+  a. UNLESS OTHERWISE SEPARATELY UNDERTAKEN BY THE LICENSOR, TO THE
+     EXTENT POSSIBLE, THE LICENSOR OFFERS THE LICENSED MATERIAL AS-IS
+     AND AS-AVAILABLE, AND MAKES NO REPRESENTATIONS OR WARRANTIES OF
+     ANY KIND CONCERNING THE LICENSED MATERIAL, WHETHER EXPRESS,
+     IMPLIED, STATUTORY, OR OTHER. THIS INCLUDES, WITHOUT LIMITATION,
+     WARRANTIES OF TITLE, MERCHANTABILITY, FITNESS FOR A PARTICULAR
+     PURPOSE, NON-INFRINGEMENT, ABSENCE OF LATENT OR OTHER DEFECTS,
+     ACCURACY, OR THE PRESENCE OR ABSENCE OF ERRORS, WHETHER OR NOT
+     KNOWN OR DISCOVERABLE. WHERE DISCLAIMERS OF WARRANTIES ARE NOT
+     ALLOWED IN FULL OR IN PART, THIS DISCLAIMER MAY NOT APPLY TO YOU.
+
+  b. TO THE EXTENT POSSIBLE, IN NO EVENT WILL THE LICENSOR BE LIABLE
+     TO YOU ON ANY LEGAL THEORY (INCLUDING, WITHOUT LIMITATION,
+     NEGLIGENCE) OR OTHERWISE FOR ANY DIRECT, SPECIAL, INDIRECT,
+     INCIDENTAL, CONSEQUENTIAL, PUNITIVE, EXEMPLARY, OR OTHER LOSSES,
+     COSTS, EXPENSES, OR DAMAGES ARISING OUT OF THIS PUBLIC LICENSE OR
+     USE OF THE LICENSED MATERIAL, EVEN IF THE LICENSOR HAS BEEN
+     ADVISED OF THE POSSIBILITY OF SUCH LOSSES, COSTS, EXPENSES, OR
+     DAMAGES. WHERE A LIMITATION OF LIABILITY IS NOT ALLOWED IN FULL OR
+     IN PART, THIS LIMITATION MAY NOT APPLY TO YOU.
+
+  c. The disclaimer of warranties and limitation of liability provided
+     above shall be interpreted in a manner that, to the extent
+     possible, most closely approximates an absolute disclaimer and
+     waiver of all liability.
+
+
+Section 6 -- Term and Termination.
+
+  a. This Public License applies for the term of the Copyright and
+     Similar Rights licensed here. However, if You fail to comply with
+     this Public License, then Your rights under this Public License
+     terminate automatically.
+
+  b. Where Your right to use the Licensed Material has terminated under
+     Section 6(a), it reinstates:
+
+       1. automatically as of the date the violation is cured, provided
+          it is cured within 30 days of Your discovery of the
+          violation; or
+
+       2. upon express reinstatement by the Licensor.
+
+     For the avoidance of doubt, this Section 6(b) does not affect any
+     right the Licensor may have to seek remedies for Your violations
+     of this Public License.
+
+  c. For the avoidance of doubt, the Licensor may also offer the
+     Licensed Material under separate terms or conditions or stop
+     distributing the Licensed Material at any time; however, doing so
+     will not terminate this Public License.
+
+  d. Sections 1, 5, 6, 7, and 8 survive termination of this Public
+     License.
+
+
+Section 7 -- Other Terms and Conditions.
+
+  a. The Licensor shall not be bound by any additional or different
+     terms or conditions communicated by You unless expressly agreed.
+
+  b. Any arrangements, understandings, or agreements regarding the
+     Licensed Material not stated herein are separate from and
+     independent of the terms and conditions of this Public License.
+
+
+Section 8 -- Interpretation.
+
+  a. For the avoidance of doubt, this Public License does not, and
+     shall not be interpreted to, reduce, limit, restrict, or impose
+     conditions on any use of the Licensed Material that could lawfully
+     be made without permission under this Public License.
+
+  b. To the extent possible, if any provision of this Public License is
+     deemed unenforceable, it shall be automatically reformed to the
+     minimum extent necessary to make it enforceable. If the provision
+     cannot be reformed, it shall be severed from this Public License
+     without affecting the enforceability of the remaining terms and
+     conditions.
+
+  c. No term or condition of this Public License will be waived and no
+     failure to comply consented to unless expressly agreed to by the
+     Licensor.
+
+  d. Nothing in this Public License constitutes or may be interpreted
+     as a limitation upon, or waiver of, any privileges and immunities
+     that apply to the Licensor or You, including from the legal
+     processes of any jurisdiction or authority.
+
+
+=======================================================================
+
+Creative Commons is not a party to its public
+licenses. Notwithstanding, Creative Commons may elect to apply one of
+its public licenses to material it publishes and in those instances
+will be considered the “Licensor.” The text of the Creative Commons
+public licenses is dedicated to the public domain under the CC0 Public
+Domain Dedication. Except for the limited purpose of indicating that
+material is shared under a Creative Commons public license or as
+otherwise permitted by the Creative Commons policies published at
+creativecommons.org/policies, Creative Commons does not authorize the
+use of the trademark "Creative Commons" or any other trademark or logo
+of Creative Commons without its prior written consent including,
+without limitation, in connection with any unauthorized modifications
+to any of its public licenses or any other arrangements,
+understandings, or agreements concerning use of licensed material. For
+the avoidance of doubt, this paragraph does not form part of the
+public licenses.
+
+Creative Commons may be contacted at creativecommons.org.
+

README.md

@@ -0,0 +1,153 @@
+---
+title: SailingMedAdvisor
+emoji: ⛵
+colorFrom: blue
+colorTo: indigo
+sdk: docker
+pinned: false
+---
+
+# SailingMedAdvisor
+
+Offline-first emergency decision support for offshore crews, using Google MedGemma models with a structured triage workflow.
+
+## What This Repository Contains
+
+This repository contains the active application code and core runtime assets for:
+
+- FastAPI backend (`app.py`)
+- SQLite persistence layer (`app.db`, `db_store.py`)
+- MedGemma inference adapters (`medgemma4.py`, `medgemma27b.py`, `medgemma_common.py`)
+- Frontend UI (`templates/`, `static/`)
+- Default seed data (`data/default/`)
+- Startup script (`run_med_advisor.sh`)
+
+Non-project scratch/export artifacts have been removed from version control.
+
+## Core Capabilities
+
+- Triage and inquiry consultation modes
+- Clinical triage pathway dropdowns (Domain, Problem, Anatomy, Mechanism/Cause, Severity/Complication)
+- Patient condition capture (Consciousness, Breathing, Circulation, Overall Stability)
+- Prompt assembly with pathway fallback to general triage instructions when path coverage is incomplete
+- Consultation logging with restore/demo-restore workflows
+- Crew, vessel, inventory, and settings management from UI
+- Model parameters in Settings (temperature, top-p, top-k, token limits, etc.)
+
+## Models
+
+- `google/medgemma-1.5-4b-it`
+- `google/medgemma-27b-text-it` (runtime adapter file: `medgemma27b.py`)
+
+Both model paths are wired to use settings-defined sampling/token parameters.
+
+## Quick Start
+
+1. Create and activate a virtual environment:
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+```
+
+2. Install dependencies:
+
+```bash
+pip install -r requirements.txt
+```
+
+3. Start the app:
+
+```bash
+chmod +x run_med_advisor.sh
+./run_med_advisor.sh
+```
+
+4. Open:
+
+- Local: `http://127.0.0.1:5000`
+- LAN: `http://<your-machine-ip>:5000`
+
+Portable startup (works on machines without a working GPU):
+
+```bash
+FORCE_CUDA=0 ALLOW_CPU_FALLBACK_ON_CUDA_ERROR=1 ./run_med_advisor.sh
+```
+
+## Fresh Install On A New Computer (Contest Repro Path)
+
+Use the installer script to set up and verify a new machine:
+
+```bash
+git clone https://github.com/rickeae/SailingMedAdvisor.git
+cd SailingMedAdvisor
+chmod +x scripts/install_fresh_copy.sh
+./scripts/install_fresh_copy.sh --skip-clone
+```
+
+For full instructions and troubleshooting, see `docs/FRESH_INSTALL.md`.
+
+You can re-run the deterministic installation verification at any time:
+
+```bash
+./.venv/bin/python scripts/verify_fresh_install.py
+```
+
+For a clean Ubuntu 24.04 environment, you can run the all-in-one bootstrap script:
+
+```bash
+chmod +x scripts/bootstrap_ubuntu24_sailingmedadvisor.sh
+./scripts/bootstrap_ubuntu24_sailingmedadvisor.sh
+```
+
+## Demo Reproduction (27B scenario)
+
+For the Kaggle demo scenario, use the 27B model path in the UI:
+
+1. Open `http://127.0.0.1:5000`.
+2. In MedGemma Consultation, choose `Triage Consultation`.
+3. Set model to `google/medgemma-27b-text-it`.
+4. Enter the fish-hook cheek scenario used in the demo.
+5. Select the matching clinical triage pathway values.
+6. Submit and compare output structure against the demo video.
+
+## Authentication Behavior
+
+- If crew credentials are configured, login is required.
+- If no credentials are configured yet, login is auto-admitted.
+
+Credentials are managed from the app UI (Vessel & Crew / Settings flows).
+
+## Data Storage
+
+- Primary runtime data is stored in `app.db`.
+- Default dataset JSONs live in `data/default/` and are used for baseline content and seeding support.
+
+## Repository Layout (Primary)
+
+```text
+SailingMedAdvisor/
+├── app.py
+├── app.db
+├── db_store.py
+├── medgemma4.py
+├── medgemma27b.py
+├── medgemma_common.py
+├── run_med_advisor.sh
+├── requirements.txt
+├── templates/
+├── static/
+├── scripts/
+└── data/default/
+```
+
+## Operational Notes
+
+- The startup script performs CUDA preflight when `FORCE_CUDA=1` (default).
+- CPU fallback on CUDA runtime errors is disabled by default (`ALLOW_CPU_FALLBACK_ON_CUDA_ERROR=0`).
+- If GPU is already occupied, the app surfaces a GPU-busy style failure message instead of silently switching devices.
+
+## Medical Safety Note
+
+This software is a decision-support aid for constrained/offshore scenarios.  
+It is not a replacement for licensed medical professionals or emergency services.

REFACTORING.md

@@ -0,0 +1,161 @@
+# Code Refactoring Documentation
+
+## Overview
+The codebase has been refactored to improve maintainability and enable easier team collaboration by splitting monolithic files into smaller, focused modules.
+
+## Structure Changes
+
+### Frontend JavaScript (Before → After)
+
+**Before:**
+- `templates/index.html` - ~900 lines (HTML + CSS + JavaScript all in one file)
+
+**After:**
+```
+static/js/
+├── main.js       - Core utilities, navigation, data loading (~110 lines)
+├── chat.js       - Triage/Inquiry chat functionality (~110 lines)
+├── crew.js       - Crew management, CRUD operations (~490 lines)
+├── pharmacy.js   - Medicine inventory management (~190 lines)
+├── settings.js   - Configuration management (~10 lines)
+└── vessel.js     - Vessel information (~25 lines)
+```
+
+### Benefits
+
+1. **Parallel Development**: Multiple developers can work on different features without merge conflicts
+   - Developer A: Works on `crew.js` (crew page features)
+   - Developer B: Works on `pharmacy.js` (inventory features)
+
+2. **Code Organization**: Each file has a single responsibility
+   - Easier to locate and fix bugs
+   - Clearer code structure
+   - Better separation of concerns
+
+3. **Maintainability**: Smaller files are easier to understand and modify
+   - Average file size: ~150 lines (vs 900+ lines before)
+   - Focused functionality per module
+
+4. **Reusability**: Shared utilities in `main.js` can be used across modules
+
+## Module Descriptions
+
+### main.js
+- Toggle functions for collapsible sections
+- Tab navigation (`showTab`)
+- Central data loading (`loadData`)
+- Tools and history display functions
+- Window initialization
+
+### chat.js
+- Chat state management (isPrivate, lastPrompt, isProcessing)
+- UI update functions (`updateUI`, `togglePriv`)
+- Chat execution (`runChat`, `repeatLast`)
+- Enter key handler for message submission
+
+### crew.js
+- Crew display and sorting logic
+- CRUD operations (add, auto-save, delete)
+- Emergency contact management
+- Document upload/delete (passport photos)
+- Import/export functionality
+- Crew list CSV generation
+
+### pharmacy.js
+- Medicine inventory display
+- Add/save/delete medicine operations
+- CSV import/export functionality
+- Category and controlled substance handling
+
+### settings.js
+- Configuration save functionality
+- Settings synchronization with backend
+
+### vessel.js
+- Vessel information save/load operations
+
+## File Loading Order
+
+The modules are loaded in this specific order in `index.html`:
+```html
+<script src="/static/js/chat.js"></script>
+<script src="/static/js/crew.js"></script>
+<script src="/static/js/pharmacy.js"></script>
+<script src="/static/js/settings.js"></script>
+<script src="/static/js/vessel.js"></script>
+<script src="/static/js/main.js"></script>  <!-- Last - initializes the app -->
+```
+
+**Important**: `main.js` must load last because it contains `window.onload` which calls functions from other modules.
+
+## Development Workflow
+
+### Working on Crew Features
+1. Edit `static/js/crew.js`
+2. Refresh browser to test
+3. No need to touch other files
+
+### Working on Pharmacy Features
+1. Edit `static/js/pharmacy.js`
+2. Refresh browser to test
+3. Independent of crew.js changes
+
+### Adding New Features
+1. Create new module in `static/js/` (e.g., `reports.js`)
+2. Add script tag to `index.html` before `main.js`
+3. Implement functionality
+4. Call from `loadData()` in main.js if needed
+
+## Testing
+
+After refactoring, test these key workflows:
+- [ ] Chat/Triage functionality
+- [ ] Add/edit/delete crew members
+- [ ] Auto-save in crew details
+- [ ] Document upload (passport photos)
+- [ ] Add/edit/delete medicines
+- [ ] CSV import/export (crew and pharmacy)
+- [ ] Settings save
+- [ ] Vessel information save
+- [ ] Tab navigation
+- [ ] History display
+
+## Backward Compatibility
+
+The refactoring maintains 100% backward compatibility:
+- Same API endpoints
+- Same data structures
+- Same UI/UX
+- Same functionality
+
+Only the code organization changed, not the behavior.
+
+## Future Improvements
+
+Potential next steps for further refactoring:
+
+### Phase 2 (Optional):
+- Extract CSS from inline styles to `static/css/style.css`
+- Split HTML into template partials
+
+### Phase 3 (Optional - Backend):
+```
+app.py → 
+├── config.py      - Configuration & defaults
+├── database.py    - Data operations
+├── auth.py        - Authentication
+├── models.py      - AI model loading
+└── routes.py      - API endpoints
+```
+
+## Rollback Plan
+
+If issues arise, restore from backup:
+```bash
+# The original file had all JavaScript inline
+# Can be reconstructed by concatenating modules
+```
+
+## Questions?
+
+Contact the development team or refer to individual module files for implementation details.

SPEC_Add_Crew_Functionality.md

@@ -0,0 +1,327 @@
+# Specification: Add Crew Member Functionality
+## Vessel & Crew Info Page
+
+**Document Version:** 1.0  
+**Date:** January 22, 2026  
+**System:** SailingMedAdvisor v5.7
+
+---
+
+## 1. Overview
+
+The Add Crew Member functionality allows users to register new crew members, passengers, or captain into the SailingMedAdvisor system. This feature is located on the **Vessel & Crew Info** tab within a collapsible "Add New Crew Member" section under "Crew Information".
+
+---
+
+## 2. User Interface Location
+
+- **Primary Tab:** Vessel & Crew (4th tab in main navigation)
+- **Parent Section:** Crew Information (collapsible)
+- **Component:** Add New Crew Member (nested collapsible form)
+- **UI State:** Initially collapsed (must be expanded to access)
+
+---
+
+## 3. Form Fields
+
+### 3.1 Personal Information
+
+| Field Name | Input Type | Required | Validation | Notes |
+|------------|------------|----------|------------|-------|
+| First Name | Text | Yes* | Non-empty after trim | Left column of 3-column grid |
+| Middle Name(s) | Text | No | None | Center column of 3-column grid |
+| Last Name | Text | Yes* | Non-empty after trim | Right column of 3-column grid |
+| Sex | Dropdown | Yes* | Must select value | Options: Male, Female, Non-binary, Other, Prefer not to say |
+| Birthdate | Date | Yes* | Must have value | Standard HTML date picker |
+| Position | Dropdown | Yes* | Must select value | Options: Captain, Crew, Passenger |
+
+### 3.2 Travel Documents
+
+| Field Name | Input Type | Required | Validation | Notes |
+|------------|------------|----------|------------|-------|
+| Citizenship | Text + Datalist | Yes* | Non-empty after trim | Autocomplete suggestions from predefined country list |
+| Passport Number | Text | Yes* | Non-empty after trim | Unique identifier |
+| Issue Date | Date | No | None | Passport issue date |
+| Expiry Date | Date | No | None | Passport expiration date |
+
+**Country Datalist:** USA, Canada, UK, Australia, New Zealand, France, Germany, Spain, Italy, Netherlands, Singapore, Malaysia, Thailand, Philippines, Japan, China, India
+
+### 3.3 Contact Information
+
+| Field Name | Input Type | Required | Validation | Notes |
+|------------|------------|----------|------------|-------|
+| Cell/WhatsApp | Text | No | None | Placeholder format: +1234567890 |
+| Passport Photo/PDF | File | No | Image/* or PDF, <5MB | Uploaded separately after crew creation |
+| Passport Page Photo/PDF | File | No | Image/* or PDF, <5MB | Uploaded separately after crew creation |
+
+### 3.4 Emergency Contact Information
+
+| Field Name | Input Type | Required | Validation | Notes |
+|------------|------------|----------|------------|-------|
+| Name | Text | No | None | Emergency contact's full name |
+| Relationship | Text | No | None | Relationship to crew member |
+| Phone | Text | No | None | Emergency contact phone number |
+| Email | Email | No | None | Emergency contact email address |
+| Emergency Contact Notes | Text | No | None | Additional emergency contact information |
+
+\* = Required field validation enforced
+
+---
+
+## 4. Functional Behavior
+
+### 4.1 Add Operation Workflow
+
+1. **User Input Phase:**
+   - User expands "Crew Information" section (if collapsed)
+   - User expands "Add New Crew Member" section (if collapsed)
+   - User fills out form fields
+   - User clicks "+ Add Crew Member" button
+
+2. **Validation Phase:**
+   ```javascript
+   Required Field Checks (in order):
+   1. First Name - Alert: "Please enter first name and last name"
+   2. Last Name - Alert: "Please enter first name and last name"
+   3. Sex - Alert: "Please select sex"
+   4. Birthdate - Alert: "Please enter birthdate"
+   5. Position - Alert: "Please select position"
+   6. Citizenship - Alert: "Please enter citizenship"
+   7. Passport Number - Alert: "Please enter passport number"
+   ```
+   - If any validation fails, display alert and stop processing
+   - User must correct the issue and re-submit
+
+3. **Data Creation Phase:**
+   - Fetch existing crew data from `/api/data/patients`
+   - Create new crew member object:
+     ```javascript
+     {
+       id: Date.now().toString(),  // Timestamp-based unique ID
+       firstName: string,
+       middleName: string,
+       lastName: string,
+       sex: string,
+       birthdate: string (YYYY-MM-DD),
+       position: string,
+       citizenship: string,
+       passportNumber: string,
+       passportIssue: string (YYYY-MM-DD),
+       passportExpiry: string (YYYY-MM-DD),
+       emergencyContactName: string,
+       emergencyContactRelation: string,
+       emergencyContactPhone: string,
+       emergencyContactEmail: string,
+       emergencyContactNotes: string,
+       phoneNumber: string,
+       passportPhoto: '',  // Empty initially
+       passportPage: '',   // Empty initially
+       history: ''         // Empty initially
+     }
+     ```
+
+4. **Data Persistence Phase:**
+   - Append new crew member to existing array
+   - POST updated array to `/api/data/patients` endpoint
+   - Server persists data to JSON file
+
+5. **UI Update Phase:**
+   - Clear all form fields (reset to empty/default state)
+   - Call `loadData()` function to refresh UI
+   - New crew member appears in:
+     - Crew Information list (on current tab)
+     - Crew Health & Log dropdown
+     - Chat page crew member selector
+
+---
+
+## 5. Data Model
+
+### 5.1 Storage Location
+- **Endpoint:** `/api/data/patients`
+- **Method:** GET (retrieve), POST (update)
+- **Format:** JSON array
+- **File:** `data/patients.json`
+
+### 5.2 ID Generation
+- **Algorithm:** `Date.now().toString()`
+- **Format:** Unix timestamp as string (e.g., "1737522671234")
+- **Uniqueness:** Guaranteed by millisecond precision
+- **Note:** IDs are not sequential, time-based for traceability
+
+---
+
+## 6. Integration Points
+
+### 6.1 Affected Components
+1. **Crew Member Dropdown (Chat Page):**
+   - New crew member added to `p-select` dropdown
+   - Available for triage queries immediately
+
+2. **Crew Medical List:**
+   - New entry created with empty medical history
+   - Accessible on "Crew Health & Log" tab
+
+3. **Crew Information List:**
+   - New collapsible section created
+   - Shows crew member details with edit capability
+
+### 6.2 Related Functions
+- `loadCrewData()` - Refreshes all crew-dependent UI elements
+- `getCrewDisplayName()` - Formats name as "Last, First"
+- `getCrewFullName()` - Formats name as "First Last"
+- `calculateAge()` - Calculates age from birthdate
+
+---
+
+## 7. User Experience Features
+
+### 7.1 Form Behavior
+- **Auto-trim:** All text fields automatically trimmed before save
+- **Reset on Success:** Form clears completely after successful add
+- **Datalist Support:** Citizenship field provides autocomplete suggestions
+- **File Upload:** Document uploads handled separately after crew creation
+
+### 7.2 Validation Feedback
+- **Real-time:** No real-time validation (submit-time only)
+- **Error Messages:** Alert-based, blocking further action until resolved
+- **Field Focus:** No automatic focus on error field (manual user correction required)
+
+---
+
+## 8. Button Specification
+
+### 8.1 Add Crew Member Button
+- **Label:** "+ Add Crew Member"
+- **Style:** 
+  - Background: `var(--dark)` (#2c3e50)
+  - Text: White
+  - Width: 100% of container
+  - Class: `btn btn-sm`
+- **Action:** `onclick="addCrew()"`
+- **Location:** Bottom of Add New Crew Member form
+
+---
+
+## 9. Edge Cases and Error Handling
+
+### 9.1 Duplicate Detection
+- **Current Behavior:** No duplicate detection
+- **Allowed:** Multiple crew members with identical names
+- **Recommendation:** Consider adding duplicate warning for same passport number
+
+### 9.2 Network Failures
+- **No Error Handling:** Function assumes successful API calls
+- **Risk:** Silent failure if network or server issues occur
+- **Recommendation:** Add try-catch blocks and user feedback
+
+### 9.3 Concurrent Modifications
+- **Race Condition:** Possible if multiple users add crew simultaneously
+- **Mitigation:** Last-write-wins (later POST overwrites earlier)
+- **Recommendation:** Implement server-side locking or conflict detection
+
+---
+
+## 10. Security Considerations
+
+### 10.1 Input Sanitization
+- **Client-side:** Basic HTML escaping via `escapeHtml()` on display
+- **Server-side:** Assumed (not verified in frontend code)
+- **File Uploads:** Size limit enforced (5MB), type validation (image/PDF)
+
+### 10.2 Authentication
+- **Current:** Uses `credentials: 'same-origin'` for API calls
+- **Session-based:** Assumes server-side session validation
+- **Login:** Crew-specific login credentials managed separately in Settings
+
+---
+
+## 11. Accessibility Notes
+
+### 11.1 Current State
+- **Labels:** Present for all form fields
+- **Required Indicators:** Asterisk (*) in label text
+- **Keyboard Navigation:** Standard HTML form tab order
+- **Screen Reader:** Field labels associated with inputs
+
+### 11.2 Improvements Needed
+- **ARIA attributes:** Not currently implemented
+- **Error announcements:** Alert dialogs are announced but could be improved
+- **Focus management:** No automatic focus on validation errors
+
+---
+
+## 12. Performance Characteristics
+
+### 12.1 Scalability
+- **Data Structure:** Array-based, linear search for operations
+- **Current Capacity:** Suitable for small crews (< 100 members)
+- **Load Time:** O(n) where n = number of crew members
+- **Recommendation:** Consider indexing for larger datasets
+
+### 12.2 Network Efficiency
+- **Data Transfer:** Full array sent on each POST (not incremental)
+- **Bandwidth:** Minimal for typical crew sizes
+- **Optimization:** Could implement PATCH for single crew updates
+
+---
+
+## 13. Testing Scenarios
+
+### 13.1 Happy Path
+1. Fill all required fields with valid data
+2. Click "+ Add Crew Member"
+3. Verify form clears
+4. Verify crew appears in all relevant lists
+5. Verify crew is selectable in chat dropdown
+
+### 13.2 Validation Testing
+1. Submit with each required field missing (one at a time)
+2. Verify correct error message displayed
+3. Verify form data retained after validation failure
+
+### 13.3 Data Integrity
+1. Add crew member
+2. Refresh page
+3. Verify crew member persists
+4. Verify all fields saved correctly
+
+### 13.4 Special Characters
+1. Enter names with special characters (e.g., O'Brien, José)
+2. Verify correct storage and display
+3. Check CSV export format
+
+---
+
+## 14. Related Documentation
+
+- **Main Application:** `app.py` - Backend API endpoints
+- **Frontend Logic:** `static/js/crew.js` - Crew management functions
+- **UI Template:** `templates/index.html` - Form structure
+- **Data Schema:** `data/patients.json` - Sample data structure
+
+---
+
+## 15. Version History
+
+| Version | Date | Changes | Author |
+|---------|------|---------|--------|
+| 1.0 | 2026-01-22 | Initial specification based on code analysis | System |
+
+---
+
+## 16. Future Enhancements
+
+### 16.1 Potential Improvements
+1. **Photo capture:** Direct camera integration for passport photos
+2. **Barcode scanning:** Auto-fill from passport MRZ scan
+3. **Duplicate detection:** Warning for similar names/passport numbers
+4. **Batch import:** CSV import for multiple crew members
+5. **Validation enhancement:** Real-time field validation
+6. **Data export:** Individual crew member PDF dossier generation
+7. **History tracking:** Audit log of crew member additions/changes
+
+### 16.2 Integration Opportunities
+1. **External APIs:** Passport validation services
+2. **Compliance:** International maritime crew list standards (IMO FAL forms)
+3. **Sync:** Cloud backup and multi-device synchronization

SPEC_Vessel_Crew_Add_Functionality.md

@@ -0,0 +1,429 @@
+# Specification: Add Crew Member Functionality
+## Vessel & Crew Info Page - SailingMedAdvisor
+
+**Document Version:** 1.0  
+**Last Updated:** January 22, 2026  
+**Component:** Vessel & Crew Information Management
+
+---
+
+## Overview
+
+The Add Crew Member functionality allows authorized users to register new crew members, passengers, or captain information into the SailingMedAdvisor system. This feature is located within the "Vessel & Crew Info" tab and provides a comprehensive data entry form for capturing essential crew information, documentation, and emergency contacts.
+
+---
+
+## Location & Access
+
+**Navigation Path:**  
+Main Navigation Bar → **VESSEL & CREW** tab → Crew Information section → **Add New Crew Member** (expandable section)
+
+**Access Control:**  
+- Requires user authentication (session-based)
+- Available to all authenticated users
+- No role-based restrictions currently implemented
+
+---
+
+## User Interface Components
+
+###  1. Collapsible Section Header
+
+**Element:** `div.col-header.crew-med-header`  
+**Default State:** Collapsed (▸ icon)  
+**Interactive Element:** Clickable header with toggle icon  
+**Visual Indicator:** Arrow icon (▸ when collapsed, ▾ when expanded)
+
+**Header Text:** "Add New Crew Member"
+
+**Behavior:**
+- Single-click toggles expansion/collapse
+- Icon rotates to indicate current state
+- State persists using localStorage with key based on `data-sidebar-id="crew-add"`
+
+---
+
+### 2. Input Form Fields
+
+The add crew form is organized into logical grouped sections with a responsive grid layout.
+
+#### **2.1 Name Fields**
+**Layout:** 3-column grid (`grid-template-columns: 1fr 1fr 1fr`)
+
+| Field Label | Element ID | Type | Required | Placeholder | Notes |
+|------------|-----------|------|----------|-------------|--------|
+| First Name | `cn-first` | text | Yes (*) | - | Primary identifier |
+| Middle Name(s) | `cn-middle` | text | No | - | Optional middle names |
+| Last Name | `cn-last` | text | Yes (*) | - | Family name |
+
+#### **2.2 Personal Information**
+**Layout:** 3-column grid
+
+| Field Label | Element ID | Type | Required | Options/Format | Notes |
+|------------|-----------|------|----------|----------------|--------|
+| Sex | `cn-sex` | select | Yes (*) | Male, Female, Non-binary, Other, Prefer not to say | Gender identity |
+| Birthdate | `cn-birthdate` | date | Yes (*) | YYYY-MM-DD | Age calculation base |
+| Position | `cn-position` | select | Yes (*) | Captain, Crew, Passenger | Role aboard vessel |
+
+#### **2.3 Documentation Fields**
+**Layout:** 4-column grid
+
+| Field Label | Element ID | Type | Required | Format/List | Notes |
+|------------|-----------|------|----------|-------------|--------|
+| Citizenship | `cn-citizenship` | text + datalist | Yes (*) | Country names | Autocomplete enabled |
+| Passport Number | `cn-passport` | text | Yes (*) | Alphanumeric | Official passport ID |
+| Issue Date | `cn-pass-issue` | date | No | YYYY-MM-DD | Passport issue |
+| Expiry Date | `cn-pass-expiry` | date | No | YYYY-MM-DD | Passport expiration |
+
+**Datalist Options** (id="countries"):  
+USA, Canada, UK, Australia, New Zealand, France, Germany, Spain, Italy, Netherlands, Singapore, Malaysia, Thailand, Philippines, Japan, China, India
+
+#### **2.4 Contact & File Upload**
+**Layout:** 3-column grid (contact) + single row (files)
+
+| Field Label | Element ID | Type | Required | Format | Notes |
+|------------|-----------|------|----------|--------|--------|
+| Cell/WhatsApp | `cn-phone` | text | No | +[country][number] | International format |
+| Passport Photo/PDF | `cn-passport-photo` | file | No | image/*,.pdf | Photo upload |
+| Passport Page Photo/PDF | `cn-passport-page` | file | No | image/*,.pdf | Document scan |
+
+#### **2.5 Emergency Contact Section**
+**Sub-header:** "Emergency Contact"  
+**Layout:** 4-column grid + notes field
+
+| Field Label | Element ID | Type | Required | Format | Notes |
+|------------|-----------|------|----------|--------|--------|
+| Name | `cn-emerg-name` | text | No | Full name | Contact person |
+| Relationship | `cn-emerg-rel` | text | No | e.g., Spouse, Parent | Relation to crew |
+| Phone | `cn-emerg-phone` | text | No | Phone number | Contact number |
+| Email | `cn-emerg-email` | email | No | email@domain.com | Email address |
+| Emergency Contact Notes | `cn-emerg-notes` | text | No | Additional info | Full-width field |
+
+---
+
+### 3. Action Button
+
+**Element:** `<button onclick="addCrew()">`  
+**Class:** `btn btn-sm`  
+**Style:** `background:var(--dark); width:100%;`  
+**Text:** "+ Add Crew Member"
+
+**Visual Properties:**
+- Dark background color (CSS variable: `--dark` = `#2c3e50`)
+- Full width of container
+- Small button sizing (`btn-sm` = `padding: 6px 12px; font-size: 13px`)
+- White text color
+- Pointer cursor on hover
+- Transition effects on interaction
+
+---
+
+## Functional Behavior
+
+### 1. Form Submission Process
+
+**Trigger:** Click on "+ Add Crew Member" button  
+**Handler Function:** `addCrew()` (defined in `/static/js/crew.js`)
+
+**Execution Flow:**
+
+1. **Data Collection**
+   - Reads all input field values by element ID
+   - Reads file uploads (if any)
+   - Constructs crew member object
+
+2. **Validation**
+   - Checks required fields (marked with *)
+   - First Name, Last Name, Sex, Birthdate, Position, Citizenship, and Passport Number are mandatory
+   - Displays browser alert if required fields are missing
+   - Validation message format: "Please fill in: First Name, Last Name, Sex, Birthdate, Position, Citizenship, Passport Number."
+
+3. **File Handling**
+   - Processes uploaded passport photo/PDF files
+   - Stores file references or base64 encoded data
+   - Associates files with crew member record
+
+4. **API Request**
+   ```javascript
+   POST /api/data/patients
+   Headers: { credentials: 'same-origin' }
+   Content-Type: application/json
+   Body: [updated patients array including new crew member]
+   ```
+
+5. **Response Handling**
+   - **Success (200 OK):**
+     - Displays success alert
+     - Clears all form fields
+     - Reloads crew list display (`loadData()`)
+     - Collapses the Add New Crew Member section
+   
+   - **Failure (non-200):**
+     - Displays error alert with message
+     - Retains form data for correction
+     - Does not clear form fields
+
+6. **UI Updates**
+   - Updates crew member dropdown in chat interface (`#p-select`)
+   - Updates crew list display in Crew Information section
+   - Updates crew list in Crew Health & Log tab
+   - Refreshes crew credentials (if username/password set)
+
+---
+
+### 2. Data Structure
+
+**Stored Object Format:**
+```javascript
+{
+  "firstName": string,
+  "middleName": string | "",
+  "lastName": string,
+  "name": string,  // Computed: "firstName middleName lastName"
+  "sex": string,   // "Male" | "Female" | "Non-binary" | "Other" | "Prefer not to say"
+  "birthdate": string,  // "YYYY-MM-DD"
+  "position": string,   // "Captain" | "Crew" | "Passenger"
+  "citizenship": string,
+  "passportNumber": string,
+  "passportIssueDate": string | "",    // "YYYY-MM-DD"
+  "passportExpiryDate": string | "",   // "YYYY-MM-DD"
+  "phone": string | "",
+  "passportPhoto": string | null,      // File reference or base64
+  "passportPage": string | null,       // File reference or base64
+  "emergencyContact": {
+    "name": string | "",
+    "relationship": string | "",
+    "phone": string | "",
+    "email": string | "",
+    "notes": string | ""
+  },
+  "history": string | "",              // Medical history notes
+  "username": string | "",             // Optional login credential
+  "password": string | ""              // Optional login credential
+}
+```
+
+**Storage Location:**  
+`/data/patients.json` (server-side file storage)
+
+**Data Persistence:**  
+- Written to disk immediately upon successful API call
+- Loaded on page initialization and tab navigation
+- Cached in browser session until page reload
+
+---
+
+### 3. Form Field Clearing
+
+After successful submission, all form fields are reset:
+
+```javascript
+document.getElementById('cn-first').value = '';
+document.getElementById('cn-middle').value = '';
+document.getElementById('cn-last').value = '';
+// ... (all fields cleared to empty string)
+document.getElementById('cn-passport-photo').value = '';
+document.getElementById('cn-passport-page').value = '';
+```
+
+---
+
+### 4. Integration Points
+
+#### **4.1 Patient Selection Dropdown**
+- Location: MEDGEMMA CHAT tab → "Crew Member Receiving Care"
+- Element ID: `#p-select`
+- Auto-populates with format: "LastName, FirstName"
+- Includes default option: "Unnamed Crew"
+- Updates immediately after adding new crew member
+
+#### **4.2 Crew Information List**
+- Location: VESSEL & CREW tab → Crew Information section
+- Container ID: `#crew-info-list`
+- Displays all registered crew members as expandable cards
+- Each card shows:
+  - Name and position
+  - Basic details (birthdate, citizenship, passport)
+  - Emergency contact information
+  - Edit and Delete action buttons
+
+#### **4.3 Crew Health & Log**
+- Location: CREW HEALTH & LOG tab
+- Container ID: `#crew-medical-list`
+- Shows crew members with medical history entries
+- Allows adding medical notes per crew member
+
+#### **4.4 Login Credentials**
+- Location: SETTINGS tab → Crew Login Credentials
+- Displays crew members who have username/password set
+- Enables authentication for restricted access
+
+---
+
+## CSS Styling
+
+### Form Container Styles
+
+```css
+.col-body {
+    padding: 15px;
+    background: #f8f9fa;
+    display: none;  /* Initially collapsed */
+}
+```
+
+### Grid Layout
+
+```css
+display: grid;
+grid-template-columns: 1fr 1fr 1fr;  /* 3-column for names */
+grid-template-columns: 1fr 1fr 1fr 1fr;  /* 4-column for docs/contact */
+gap: 8px;
+margin-bottom: 8px;
+font-size: 15px;
+```
+
+### Input Field Styles
+
+```css
+input, select, textarea {
+    padding: 6px;
+    width: 100%;
+    font-size: 15px;
+}
+
+label {
+    font-size: 13px;
+    margin-bottom: 2px;
+    display: block;
+}
+```
+
+### Button Styles
+
+```css
+.btn-sm {
+    padding: 6px 12px;
+    font-size: 13px;
+    background: var(--dark);  /* #2c3e50 */
+    color: white;
+    border: none;
+    border-radius: 4px;
+    cursor: pointer;
+    font-weight: bold;
+}
+```
+
+---
+
+## Error Handling
+
+### Client-Side Validation Errors
+
+**Missing Required Fields:**
+```
+Alert Message: "Please fill in: [list of missing fields]"
+Behavior: Form remains open, data retained, focus on first missing field
+```
+
+**File Upload Errors:**
+```
+Alert Message: "Error uploading files: [error description]"
+Behavior: Form remains open, previously entered data retained
+```
+
+### Server-Side Errors
+
+**API Request Failure:**
+```
+Alert Message: "Failed to add crew member: [HTTP status or error message]"
+Behavior: Form remains open, all data retained for retry
+```
+
+**Network Error:**
+```
+Alert Message: "Network error. Please check your connection and try again."
+Behavior: Form remains open, all data retained
+```
+
+---
+
+## Accessibility Features
+
+- **Keyboard Navigation:** Full tab-through support for all form fields
+- **Screen Reader Support:** Proper label associations via `<label>` elements
+- **Required Field Indicators:** Asterisk (*) in field labels
+- **Focus Management:** First field receives focus when section expands
+- **Error Messaging:** Clear, descriptive error messages for validation failures
+
+---
+
+## Security Considerations
+
+1. **Authentication:** Requires active session (cookie-based)
+2. **Data Validation:** Server-side validation of all inputs
+3. **File Upload Security:**  
+   - Restricted to image/* and .pdf MIME types
+   - File size limits enforced server-side
+   - Sanitized file names
+
+4. **XSS Prevention:** All user inputs are escaped before rendering
+5. **CSRF Protection:** SessionMiddleware with same-site=lax policy
+
+---
+
+## Performance Considerations
+
+- **Form Load Time:** < 100ms (minimal DOM manipulation)
+- **API Response Time:** Typically < 500ms for add operation
+- **File Upload:** Dependent on file size and connection speed
+- **Data Reload:** Full crew list refresh after successful addition
+
+---
+
+## Browser Compatibility
+
+- **Tested Browsers:** Chrome, Firefox, Edge, Safari
+- **Required Features:**
+  - ES6+ JavaScript support
+  - Fetch API
+  - LocalStorage
+  - HTML5 form inputs (date, email, file)
+  - CSS Grid Layout
+
+---
+
+## Related Documentation
+
+- Backend API: `/api/data/patients` endpoint specification
+- Crew Management Module: `/static/js/crew.js`
+- Data Storage: `/data/patients.json` format specification
+- Authentication: Session management and login flow
+
+---
+
+## Known Issues & Limitations
+
+1. **File Storage:** Currently stores base64 encoded files in JSON (may cause performance issues with large files)
+2. **Validation:** Phone number format validation is not enforced
+3. **Duplicate Prevention:** No check for duplicate passport numbers or names
+4. **Photo Preview:** Uploaded photos are not previewed before submission
+5. **Internationalization:** Form labels and messages are English-only
+
+---
+
+## Future Enhancements
+
+- Photo preview before submission
+- Duplicate detection (passport number, name)
+- International phone number validation
+- Multi-language support
+- Batch import from CSV/Excel
+- Photo compression before upload
+- Separate file storage system (not embedded in JSON)
+- Auto-save draft functionality
+- Field-level inline validation
+
+---
+
+**End of Specification**

check_gpu.py

@@ -0,0 +1,77 @@
+#!/usr/bin/env python3
+# =============================================================================
+# Author: Rick Escher
+# Project: SailingMedAdvisor
+# Context: Google HAI-DEF Framework
+# Models: Google MedGemmas
+# Program: Kaggle Impact Challenge
+# =============================================================================
+"""
+GPU Detection Diagnostic Script
+Run this to check if PyTorch can see our NVIDIA GPU
+"""
+
+import sys
+
+print("=" * 60)
+print("GPU Detection Diagnostic")
+print("=" * 60)
+
+# Check if torch is installed
+try:
+    import torch
+    print(f"✓ PyTorch installed: {torch.__version__}")
+except ImportError as e:
+    print(f"✗ PyTorch not found: {e}")
+    print("  Install with: pip install torch")
+    sys.exit(1)
+
+print()
+
+# Check CUDA availability
+print(f"CUDA available: {torch.cuda.is_available()}")
+print(f"CUDA version (compiled): {torch.version.cuda}")
+
+if torch.cuda.is_available():
+    print(f"✓ GPU DETECTED!")
+    print(f"  Number of GPUs: {torch.cuda.device_count()}")
+    
+    for i in range(torch.cuda.device_count()):
+        print(f"\n  GPU {i}:")
+        print(f"    Name: {torch.cuda.get_device_name(i)}")
+        props = torch.cuda.get_device_properties(i)
+        print(f"    Total memory: {props.total_memory / 1024**3:.2f} GB")
+        print(f"    Compute capability: {props.major}.{props.minor}")
+    
+    # Test tensor creation
+    try:
+        test_tensor = torch.zeros(10, 10).cuda()
+        print(f"\n✓ Successfully created tensor on GPU: {test_tensor.device}")
+        del test_tensor
+    except Exception as e:
+        print(f"\n✗ Failed to create tensor on GPU: {e}")
+else:
+    print("✗ NO GPU DETECTED")
+    print("\nPossible reasons:")
+    print("  1. No NVIDIA GPU installed")
+    print("  2. NVIDIA drivers not installed")
+    print("  3. PyTorch installed without CUDA support")
+    print("  4. CUDA toolkit version mismatch")
+    
+    print("\nTo install PyTorch with CUDA support:")
+    print("  pip3 install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118")
+    
+    # Check for NVIDIA driver
+    try:
+        import subprocess
+        result = subprocess.run(['nvidia-smi'], capture_output=True, text=True)
+        if result.returncode == 0:
+            print("\n✓ nvidia-smi found - NVIDIA driver is installed")
+            print("\nNVIDIA Driver Info:")
+            print(result.stdout)
+        else:
+            print("\n✗ nvidia-smi not found - NVIDIA driver may not be installed")
+    except FileNotFoundError:
+        print("\n✗ nvidia-smi not found - NVIDIA driver may not be installed")
+
+print("\n" + "=" * 60)

data/default/chats.json

@@ -0,0 +1 @@
+[]

data/default/context.json

@@ -0,0 +1 @@
+{}

data/default/history.json

@@ -0,0 +1 @@
+[]

data/default/inventory.json

@@ -0,0 +1 @@
+[]

data/default/med_photo_jobs.json

@@ -0,0 +1 @@
+[]

data/default/med_photo_queue.json

@@ -0,0 +1 @@
+[]

data/default/patients.json

@@ -0,0 +1 @@
+[]

data/default/settings.json

@@ -0,0 +1 @@
+{}

data/default/tools.json

@@ -0,0 +1 @@
+[]

data/default/vessel.json

@@ -0,0 +1 @@
+{}

debug_inference.py

@@ -0,0 +1,47 @@
+#!/usr/bin/env python3
+# =============================================================================
+# Author: Rick Escher
+# Project: SailingMedAdvisor
+# Context: Google HAI-DEF Framework
+# Models: Google MedGemmas
+# Program: Kaggle Impact Challenge
+# =============================================================================
+"""
+Quick runtime diagnostic for local inference behavior.
+
+This script calls the running app's offline-status endpoint and prints
+the exact environment flags/model cache state the backend sees.
+"""
+import requests
+
+# Check what the API reports
+print("1. Checking API status:")
+resp = requests.get("http://127.0.0.1:5000/api/offline/check")
+data = resp.json()
+
+print(f"   Offline mode: {data.get('offline_mode')}")
+print(f"   Cache dir: {data.get('cache_dir')}")
+print(f"   Models cached:")
+for m in data.get('models', []):
+    status = "✓" if m['cached'] else "✗"
+    print(f"      {status} {m['model']}")
+
+# Check environment from the app's perspective
+print("\n2. Checking app environment flags:")
+env_flags = data.get('env', {})
+for k, v in sorted(env_flags.items()):
+    print(f"   {k}: {v}")
+
+print("\n3. Attempting to decode why GPU not used...")
+print("   Possible causes:")
+print("   - DISABLE_LOCAL_INFERENCE might be True")
+print("   - HF_REMOTE_TOKEN might be set (using remote API)")
+print("   - Models loading to CPU instead of GPU")
+print("   - device_map not working correctly")
+
+# Try to trigger a simple test query and see response time
+print("\n4. Check if you can see logs during query:")
+print("   In terminal running server, watch for:")
+print("   - 'Loading model...' or similar")
+print("   - Any torch/transformers messages")
+print("   - Error messages")

docs/FRESH_INSTALL.md

@@ -0,0 +1,111 @@
+# SailingMedAdvisor Fresh Install Guide
+
+This guide is the reproducible install path for setting up a working copy of SailingMedAdvisor on a new computer.
+
+## 1. Prerequisites
+
+- OS: Linux (tested on Ubuntu-class environments)
+- Python: `3.10+`
+- Git: installed
+- GPU runtime (recommended for MedGemma inference):
+  - NVIDIA driver + CUDA-compatible PyTorch environment
+- Network access for first-time dependency/model downloads
+
+## 2. One-Command Install (Recommended)
+
+From any directory:
+
+```bash
+git clone https://github.com/rickeae/SailingMedAdvisor.git
+cd SailingMedAdvisor
+chmod +x scripts/install_fresh_copy.sh
+./scripts/install_fresh_copy.sh --skip-clone
+```
+
+What this does:
+
+1. Creates `.venv`
+2. Installs dependencies from `requirements.txt`
+3. Runs deterministic verification (`scripts/verify_fresh_install.py`)
+
+## 2b. Full Ubuntu 24.04 Bootstrap (System + Clone + Install + Verify)
+
+If the machine is truly fresh and you want one script to do the full flow:
+
+```bash
+git clone https://github.com/rickeae/SailingMedAdvisor.git
+cd SailingMedAdvisor
+chmod +x scripts/bootstrap_ubuntu24_sailingmedadvisor.sh
+./scripts/bootstrap_ubuntu24_sailingmedadvisor.sh
+```
+
+Optional: also launch the app automatically after verification:
+
+```bash
+./scripts/bootstrap_ubuntu24_sailingmedadvisor.sh --start
+```
+
+## 3. Verification Command (Standalone)
+
+You can re-run install verification any time:
+
+```bash
+./.venv/bin/python scripts/verify_fresh_install.py
+```
+
+Verification covers:
+
+- Python version
+- Required files present
+- Required package imports
+- Database initialization/schema checks
+- Default triage tree JSON integrity
+- API startup smoke test via `GET /api/db/status`
+
+## 4. Start the Application
+
+```bash
+FORCE_CUDA=0 ALLOW_CPU_FALLBACK_ON_CUDA_ERROR=1 ./run_med_advisor.sh
+```
+
+Open:
+
+- Local: `http://127.0.0.1:5000`
+- LAN: `http://<machine-ip>:5000`
+
+GPU-known-good optional start:
+
+```bash
+FORCE_CUDA=1 ALLOW_CPU_FALLBACK_ON_CUDA_ERROR=1 ./run_med_advisor.sh
+```
+
+## 5. Prepare for Offline Use (Before Departure)
+
+In the app UI:
+
+1. Go to `Settings -> Offline Readiness Check`
+2. Click `Check cache status`
+3. Click `Download missing models` while internet is available
+4. Enable offline flags before operating without internet
+
+Expected required models:
+
+- `google/medgemma-1.5-4b-it`
+- `google/medgemma-27b-text-it`
+
+## 6. Demo Reproduction Note
+
+To reproduce the challenge demo scenario, select the 27B model in the consultation UI:
+
+- `google/medgemma-27b-text-it`
+
+## 7. Troubleshooting
+
+- CUDA preflight fails:
+  - Check `FORCE_CUDA` and NVIDIA driver health.
+  - Use kernel logs (`journalctl -k | grep -i -E 'NVRM|Xid'`) to diagnose driver errors.
+- API smoke test fails:
+  - Re-run `./.venv/bin/python scripts/verify_fresh_install.py --timeout 90`
+  - Check for port conflicts and Python import errors.
+- Missing model cache in offline mode:
+  - Disable offline flags temporarily, reconnect internet, then use `Download missing models`.

medgemma15_test.py

@@ -0,0 +1,369 @@
+# =============================================================================
+# Author: Rick Escher
+# Project: SailingMedAdvisor
+# Context: Google HAI-DEF Framework
+# Models: Google MedGemmas
+# Program: Kaggle Impact Challenge
+# =============================================================================
+import os
+import argparse
+import json
+from pathlib import Path
+
+# Force offline mode + make sure only GPU 0 is visible before torch import.
+os.environ.setdefault("HF_HUB_OFFLINE", "1")
+os.environ.setdefault("TRANSFORMERS_OFFLINE", "1")
+os.environ.setdefault("CUDA_VISIBLE_DEVICES", "0")
+
+import torch
+
+# --- GEMMA3 MASK PATCH (torch<2.6) ---
+def _torch_version_ge(major: int, minor: int) -> bool:
+    """
+     Torch Version Ge helper.
+    Detailed inline notes are included to support safe maintenance and future edits.
+    """
+    try:
+        base = torch.__version__.split("+", 1)[0]
+        parts = base.split(".")
+        return (int(parts[0]), int(parts[1])) >= (major, minor)
+    except Exception:
+        return False
+
+if not _torch_version_ge(2, 6):
+    try:
+        import transformers.models.gemma3.modeling_gemma3 as gemma_model
+        _orig_create_causal_mask_mapping = gemma_model.create_causal_mask_mapping
+
+        def _create_causal_mask_mapping_no_or(*args, **kwargs):
+            # torch<2.6 can't use or_mask_function; ignore token_type_ids for text-only.
+            """
+             Create Causal Mask Mapping No Or helper.
+            Detailed inline notes are included to support safe maintenance and future edits.
+            """
+            if len(args) >= 7:
+                args = list(args)
+                args[6] = None
+            if "token_type_ids" in kwargs:
+                kwargs = dict(kwargs)
+                kwargs["token_type_ids"] = None
+            return _orig_create_causal_mask_mapping(*args, **kwargs)
+
+        gemma_model.create_causal_mask_mapping = _create_causal_mask_mapping_no_or
+    except Exception:
+        # If the import fails, let the main error surface later.
+        pass
+# -------------------------------------------------
+
+from transformers import AutoTokenizer, AutoModelForCausalLM, AutoProcessor
+
+def _safe_pad_token_id(tok):
+    """
+     Safe Pad Token Id helper.
+    Detailed inline notes are included to support safe maintenance and future edits.
+    """
+    pad = getattr(tok, "pad_token_id", None)
+    if pad is not None:
+        return pad
+    eos = getattr(tok, "eos_token_id", None)
+    if isinstance(eos, (list, tuple)):
+        return eos[0] if eos else None
+    return eos
+
+def _iter_cache_roots() -> list[Path]:
+    """
+     Iter Cache Roots helper.
+    Detailed inline notes are included to support safe maintenance and future edits.
+    """
+    roots: list[Path] = []
+    env_cache = os.environ.get("HUGGINGFACE_HUB_CACHE")
+    if env_cache:
+        roots.append(Path(env_cache))
+    env_home = os.environ.get("HF_HOME")
+    if env_home:
+        roots.append(Path(env_home) / "hub")
+    roots.append(Path("/mnt/modelcache/models_cache/hub"))
+    roots.append(Path("/mnt/modelcache/hf_home/hub"))
+    # De-dup while keeping order.
+    seen = set()
+    final: list[Path] = []
+    for root in roots:
+        if root in seen:
+            continue
+        seen.add(root)
+        if root.is_dir():
+            final.append(root)
+    return final
+
+def _snapshot_complete(snapshot: Path) -> bool:
+    """
+     Snapshot Complete helper.
+    Detailed inline notes are included to support safe maintenance and future edits.
+    """
+    index = snapshot / "model.safetensors.index.json"
+    if index.exists():
+        try:
+            data = json.loads(index.read_text())
+        except Exception:
+            return False
+        weight_map = data.get("weight_map") or {}
+        files = set(weight_map.values())
+        if not files:
+            return False
+        for name in files:
+            f = snapshot / name
+            if not f.exists():
+                return False
+            target = f.resolve()
+            if str(target).endswith(".incomplete"):
+                return False
+        return True
+    single = snapshot / "model.safetensors"
+    if single.exists():
+        target = single.resolve()
+        return not str(target).endswith(".incomplete")
+    return False
+
+def _pick_latest_complete(snapshot_dir: Path, model_id: str) -> str:
+    """
+     Pick Latest Complete helper.
+    Detailed inline notes are included to support safe maintenance and future edits.
+    """
+    if not snapshot_dir.is_dir():
+        raise FileNotFoundError(f"Snapshot dir not found for {model_id}: {snapshot_dir}")
+    snapshots = [d for d in snapshot_dir.iterdir() if d.is_dir()]
+    if not snapshots:
+        raise FileNotFoundError(f"No snapshots found for {model_id} in: {snapshot_dir}")
+    snapshots.sort(key=lambda p: p.stat().st_mtime, reverse=True)
+    for snap in snapshots:
+        if _snapshot_complete(snap):
+            return str(snap)
+    raise FileNotFoundError(
+        f"Snapshots found for {model_id}, but weights are incomplete (.incomplete). "
+        f"Checked: {snapshot_dir}"
+    )
+
+def _resolve_snapshot(model_id: str, snapshot_override: str | None) -> str:
+    """
+     Resolve Snapshot helper.
+    Detailed inline notes are included to support safe maintenance and future edits.
+    """
+    if snapshot_override:
+        override = Path(snapshot_override)
+        # Accept either a snapshot path or the repo root containing "snapshots/".
+        if (override / "snapshots").is_dir():
+            return _pick_latest_complete(override / "snapshots", model_id)
+        if override.is_dir() and _snapshot_complete(override):
+            return str(override)
+        return snapshot_override
+    safe = model_id.replace("/", "--")
+    snapshots: list[Path] = []
+    for root in _iter_cache_roots():
+        base = root / f"models--{safe}" / "snapshots"
+        if not base.is_dir():
+            continue
+        snapshots.extend([d for d in base.iterdir() if d.is_dir()])
+    if not snapshots:
+        raise FileNotFoundError(
+            f"No snapshots found for {model_id}. Checked: {', '.join(map(str, _iter_cache_roots()))}"
+        )
+    snapshots.sort(key=lambda p: p.stat().st_mtime, reverse=True)
+    for snap in snapshots:
+        if _snapshot_complete(snap):
+            return str(snap)
+    raise FileNotFoundError(
+        f"Snapshots found for {model_id}, but weights are incomplete (.incomplete). "
+        f"Checked: {', '.join(map(str, _iter_cache_roots()))}"
+    )
+
+if not torch.cuda.is_available():
+    raise RuntimeError("CUDA not available. This script requires the RTX 5000 GPU.")
+
+gpu_name = torch.cuda.get_device_name(0)
+if "RTX 5000" not in gpu_name.upper():
+    raise RuntimeError(f"Unexpected GPU detected: '{gpu_name}'. Expected RTX 5000.")
+if not torch.cuda.is_bf16_supported():
+    raise RuntimeError("bfloat16 not supported on this GPU/driver. This model is unstable in float16.")
+
+def _pick_input_device(model) -> str:
+    """
+     Pick Input Device helper.
+    Detailed inline notes are included to support safe maintenance and future edits.
+    """
+    if hasattr(model, "hf_device_map"):
+        device_map = getattr(model, "hf_device_map") or {}
+        preferred = None
+        for name, dev in device_map.items():
+            if isinstance(dev, str) and dev.startswith("cuda"):
+                if "embed" in name:
+                    return dev
+                preferred = dev
+        if preferred:
+            return preferred
+    return "cuda:0" if torch.cuda.is_available() else "cpu"
+
+def _normalize_device_map(device_map: str | dict) -> str | dict:
+    """
+     Normalize Device Map helper.
+    Detailed inline notes are included to support safe maintenance and future edits.
+    """
+    if isinstance(device_map, str):
+        value = device_map.strip()
+        if value in {"auto", "balanced", "balanced_low_0", "sequential"}:
+            return value
+        if value.startswith("cuda") or value.startswith("cpu"):
+            return {"": value}
+    return device_map
+
+def _device_map_all_cuda(device_map: str | dict) -> bool:
+    """
+     Device Map All Cuda helper.
+    Detailed inline notes are included to support safe maintenance and future edits.
+    """
+    if isinstance(device_map, str):
+        return device_map.strip().startswith("cuda")
+    if isinstance(device_map, dict):
+        return all(str(v).startswith("cuda") for v in device_map.values())
+    return False
+
+def _load_model(
+    snapshot: str,
+    quant4: bool,
+    device_map: str | dict,
+    max_memory: dict | None,
+    cpu_offload: bool,
+):
+    """
+     Load Model helper.
+    Detailed inline notes are included to support safe maintenance and future edits.
+    """
+    model_kwargs = {
+        "device_map": _normalize_device_map(device_map),
+        "dtype": torch.bfloat16,
+        "attn_implementation": "eager",
+        "local_files_only": True,
+        "low_cpu_mem_usage": True,
+    }
+    if max_memory:
+        model_kwargs["max_memory"] = max_memory
+    if quant4:
+        try:
+            from transformers import BitsAndBytesConfig
+        except Exception as exc:
+            raise RuntimeError(f"bitsandbytes not available for 4-bit load: {exc}")
+        bnb_kwargs = dict(
+            load_in_4bit=True,
+            bnb_4bit_compute_dtype=torch.bfloat16,
+            bnb_4bit_use_double_quant=True,
+            bnb_4bit_quant_type="nf4",
+        )
+        if cpu_offload or not _device_map_all_cuda(device_map):
+            bnb_kwargs["llm_int8_enable_fp32_cpu_offload"] = True
+        model_kwargs["quantization_config"] = BitsAndBytesConfig(**bnb_kwargs)
+    model = AutoModelForCausalLM.from_pretrained(snapshot, **model_kwargs)
+    tokenizer = AutoTokenizer.from_pretrained(snapshot, local_files_only=True)
+    try:
+        processor = AutoProcessor.from_pretrained(snapshot, local_files_only=True)
+    except Exception:
+        processor = None
+    model.eval()
+    return model, tokenizer, processor
+
+def _ensure_gpu_used(model) -> None:
+    """
+     Ensure Gpu Used helper.
+    Detailed inline notes are included to support safe maintenance and future edits.
+    """
+    device_map = getattr(model, "hf_device_map", None) or {}
+    if any(isinstance(v, str) and v.startswith("cuda") for v in device_map.values()):
+        return
+    for param in model.parameters():
+        if param.device.type == "cuda":
+            return
+    raise RuntimeError("Model did not place any weights on CUDA. RTX 5000 usage is required.")
+
+def ask(model, tokenizer, processor, text: str, max_new_tokens: int, raw_prompt: bool):
+    """
+    Ask helper.
+    Detailed inline notes are included to support safe maintenance and future edits.
+    """
+    if raw_prompt:
+        prompt = text
+    else:
+        # Use the model's chat template (<start_of_turn> ... <end_of_turn>)
+        messages = [{"role": "user", "content": text}]
+        prompt = tokenizer.apply_chat_template(
+            messages,
+            add_generation_prompt=True,
+            tokenize=False,
+        )
+    if processor is not None:
+        inputs = processor(text=prompt, return_tensors="pt")
+        input_ids = inputs.get("input_ids")
+    else:
+        inputs = tokenizer(prompt, return_tensors="pt")
+        input_ids = inputs.get("input_ids")
+    input_device = _pick_input_device(model)
+    inputs = {k: v.to(input_device) for k, v in inputs.items()}
+
+    with torch.inference_mode():
+        out = model.generate(
+            **inputs,
+            max_new_tokens=max_new_tokens,
+            do_sample=False,
+            pad_token_id=_safe_pad_token_id(tokenizer),
+        )
+
+    response = tokenizer.decode(out[0][input_ids.shape[-1]:], skip_special_tokens=True)
+    return response.strip()
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description="MedGemma local test runner")
+    parser.add_argument("--model", choices=["4b", "27b"], default="4b", help="Select model size.")
+    parser.add_argument("--model-id", default="", help="Override Hugging Face model id.")
+    parser.add_argument("--snapshot", default="", help="Override snapshot path directly.")
+    parser.add_argument("--max-new-tokens", type=int, default=600, help="Generation length.")
+    parser.add_argument("--prompt", default="Explain first aid for a deep fishhook embedded in the cheek while at sea.")
+    parser.add_argument("--quant4", action="store_true", help="Load model in 4-bit (recommended for 27B).")
+    parser.add_argument("--device-map", default="", help="Override device_map (e.g. 'auto' or 'cuda:0').")
+    parser.add_argument("--raw-prompt", action="store_true", help="Use raw prompt (no chat template).")
+    parser.add_argument("--max-memory-gpu", default="15GiB", help="Max GPU memory for auto device_map.")
+    parser.add_argument("--max-memory-cpu", default="64GiB", help="Max CPU memory for auto device_map.")
+    parser.add_argument("--cpu-offload", action="store_true", help="Enable CPU offload for 4-bit quant.")
+    args = parser.parse_args()
+
+    model_id = args.model_id.strip() or (
+        "google/medgemma-27b-text-it" if args.model == "27b" else "google/medgemma-1.5-4b-it"
+    )
+    snapshot = _resolve_snapshot(model_id, args.snapshot.strip() or None)
+    if not os.path.isdir(snapshot):
+        raise FileNotFoundError(f"Model snapshot not found at: {snapshot}")
+
+    device_map = args.device_map.strip() or ("auto" if args.model == "27b" and not args.quant4 else "cuda:0")
+    print(f"Loading {model_id} from snapshot: {snapshot}")
+    print(f"device_map: {device_map}")
+    if args.model == "27b" and not args.quant4 and device_map != "auto":
+        print("Warning: 27B model typically needs --device-map auto or --quant4 on RTX 5000.")
+
+    max_memory = None
+    if torch.cuda.is_available() and not _device_map_all_cuda(device_map):
+        max_memory = {0: args.max_memory_gpu, "cpu": args.max_memory_cpu}
+    model, tokenizer, processor = _load_model(
+        snapshot,
+        args.quant4,
+        device_map,
+        max_memory,
+        args.cpu_offload,
+    )
+    _ensure_gpu_used(model)
+    query = args.prompt
+    print(f"\nQUERY: {query}")
+
+    try:
+        response = ask(model, tokenizer, processor, query, args.max_new_tokens, args.raw_prompt)
+        if not response:
+            print("\nRESPONSE: [Still blank. Attempting fallback...]")
+        else:
+            print(f"\nRESPONSE:\n{'-'*30}\n{response}\n{'-'*30}")
+    except Exception as e:
+        print(f"\nERROR: {e}")

medgemma27b.py

@@ -0,0 +1,261 @@
+# =============================================================================
+# Author: Rick Escher
+# Project: SailingMedAdvisor
+# Context: Google HAI-DEF Framework
+# Models: Google MedGemmas
+# Program: Kaggle Impact Challenge
+# =============================================================================
+"""
+MedGemma 27B inference runner.
+
+Design intent:
+- Use 4-bit quantization to fit 27B inference on constrained edge hardware.
+- Support automatic and manual layer placement across GPU/CPU.
+- Reuse loaded model when snapshot/load signature is unchanged to reduce
+  repeated load latency and VRAM fragmentation.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict
+
+import os
+import gc
+
+import torch
+from transformers import AutoConfig, AutoModelForCausalLM, AutoTokenizer
+
+from medgemma_common import (
+    cap_new_tokens,
+    normalize_device_map,
+    pick_input_device,
+    resolve_model_max_length,
+    resolve_snapshot,
+    safe_pad_token_id,
+)
+
+MODEL_ID = "google/medgemma-27b-text-it"
+
+_MODEL = None
+_TOKENIZER = None
+_ACTIVE_SNAPSHOT = None
+_ACTIVE_LOAD_SIGNATURE = None
+
+
+def _default_dtype() -> torch.dtype:
+    """Select default compute dtype with BF16 preference when available."""
+    if os.environ.get("FORCE_FP16", "").strip() == "1":
+        return torch.float16
+    if torch.cuda.is_available() and torch.cuda.is_bf16_supported():
+        return torch.bfloat16
+    if torch.cuda.is_available():
+        return torch.float16
+    return torch.float32
+
+
+def _load_quant_config() -> Any:
+    """Build BitsAndBytes 4-bit configuration for 27B local inference."""
+    try:
+        from transformers import BitsAndBytesConfig
+    except Exception as exc:
+        raise RuntimeError(f"bitsandbytes not available for 4-bit load: {exc}")
+    bnb_compute_dtype = torch.bfloat16 if torch.cuda.is_bf16_supported() else torch.float16
+    return BitsAndBytesConfig(
+        load_in_4bit=True,
+        bnb_4bit_compute_dtype=bnb_compute_dtype,
+        bnb_4bit_use_double_quant=True,
+        bnb_4bit_quant_type="nf4",
+        llm_int8_enable_fp32_cpu_offload=True,
+    )
+
+
+def _resolve_num_layers(config_obj: Any) -> int:
+    """Extract layer count from model config with safe fallback."""
+    if config_obj is None:
+        return 62
+    val = getattr(config_obj, "num_hidden_layers", None)
+    if isinstance(val, int) and val > 0:
+        return val
+    text_cfg = getattr(config_obj, "text_config", None)
+    val = getattr(text_cfg, "num_hidden_layers", None)
+    if isinstance(val, int) and val > 0:
+        return val
+    return 62
+
+
+def _manual_device_map(num_layers: int, gpu_layers: int) -> Dict[str, str]:
+    """
+    Create deterministic layer placement for mixed GPU/CPU execution.
+
+    The first `gpu_layers` transformer blocks stay on GPU; remaining layers
+    plus final norm/head are offloaded to CPU.
+    """
+    gpu_layers = max(0, min(int(gpu_layers), int(num_layers)))
+    dm: Dict[str, str] = {
+        "model.embed_tokens": "cuda:0",
+        "model.rotary_emb": "cuda:0",
+        "model.norm": "cpu",
+        "lm_head": "cpu",
+    }
+    for i in range(int(num_layers)):
+        dm[f"model.layers.{i}"] = "cuda:0" if i < gpu_layers else "cpu"
+    return dm
+
+
+def _resolve_device_map_for_27b(
+    device_map: str | dict,
+    *,
+    resolved_snapshot: str,
+    local_files_only: bool,
+) -> str | Dict[str, str]:
+    """Normalize configured device map into a concrete mapping."""
+    if isinstance(device_map, dict):
+        return normalize_device_map(device_map)
+    if not isinstance(device_map, str):
+        return normalize_device_map(device_map)
+    value = device_map.strip()
+    mode = value.lower()
+    if mode.startswith("manual"):
+        config_obj = AutoConfig.from_pretrained(resolved_snapshot, local_files_only=local_files_only)
+        num_layers = _resolve_num_layers(config_obj)
+        gpu_layers = int(os.environ.get("MODEL_GPU_LAYERS_27B", "14"))
+        if ":" in mode:
+            try:
+                gpu_layers = int(mode.split(":", 1)[1].strip())
+            except Exception:
+                pass
+        return _manual_device_map(num_layers, gpu_layers)
+    return normalize_device_map(value)
+
+
+def load_model(
+    *,
+    snapshot: str | None = None,
+    device_map: str | dict = "auto",
+    dtype: torch.dtype | None = None,
+    max_memory: Dict[str, str] | None = None,
+    local_files_only: bool = True,
+) -> tuple[Any, Any]:
+    """
+    Load/reuse 27B model and tokenizer.
+
+    Reload triggers:
+    - Snapshot changed
+    - Device map changed
+    - Dtype changed
+    - Max-memory map changed
+    """
+    global _MODEL, _TOKENIZER, _ACTIVE_SNAPSHOT, _ACTIVE_LOAD_SIGNATURE
+    if dtype is None:
+        dtype = _default_dtype()
+    resolved = resolve_snapshot(MODEL_ID, snapshot)
+    normalized_device_map = _resolve_device_map_for_27b(
+        device_map,
+        resolved_snapshot=resolved,
+        local_files_only=local_files_only,
+    )
+    memory_sig = tuple(sorted((max_memory or {}).items(), key=lambda kv: str(kv[0])))
+    load_sig = (str(dtype), str(normalized_device_map), memory_sig)
+    if (
+        _MODEL is not None
+        and _TOKENIZER is not None
+        and _ACTIVE_SNAPSHOT == resolved
+        and _ACTIVE_LOAD_SIGNATURE == load_sig
+    ):
+        return _MODEL, _TOKENIZER
+    if _MODEL is not None or _TOKENIZER is not None:
+        unload_model()
+
+    quant_config = _load_quant_config()
+    attn_impl = (os.environ.get("MODEL_ATTN_IMPL_27B", "eager") or "").strip() or "eager"
+    model_kwargs: Dict[str, Any] = {
+        "torch_dtype": dtype,
+        "device_map": normalized_device_map,
+        "local_files_only": local_files_only,
+        "low_cpu_mem_usage": True,
+        "quantization_config": quant_config,
+        "offload_folder": os.environ.get("MODEL_OFFLOAD_DIR", "offload"),
+        # Avoid flash/SDPA kernel selection issues on older GPUs/offload mixes.
+        "attn_implementation": attn_impl,
+    }
+    if max_memory:
+        model_kwargs["max_memory"] = max_memory
+
+    _TOKENIZER = AutoTokenizer.from_pretrained(resolved, use_fast=True, local_files_only=local_files_only)
+    _MODEL = AutoModelForCausalLM.from_pretrained(resolved, **model_kwargs)
+    _MODEL.eval()
+    _ACTIVE_SNAPSHOT = resolved
+    _ACTIVE_LOAD_SIGNATURE = load_sig
+    return _MODEL, _TOKENIZER
+
+
+def unload_model() -> None:
+    """Release 27B references and request CUDA cache cleanup."""
+    global _MODEL, _TOKENIZER, _ACTIVE_SNAPSHOT, _ACTIVE_LOAD_SIGNATURE
+    _MODEL = None
+    _TOKENIZER = None
+    _ACTIVE_SNAPSHOT = None
+    _ACTIVE_LOAD_SIGNATURE = None
+    gc.collect()
+    if torch.cuda.is_available():
+        torch.cuda.empty_cache()
+
+
+def generate(
+    prompt: str,
+    cfg: Dict[str, Any],
+    *,
+    snapshot: str | None = None,
+    device_map: str | dict = "auto",
+    max_memory: Dict[str, str] | None = None,
+) -> str:
+    """
+    Generate one assistant response with context-length and token safeguards.
+
+    This path caps input tokens for VRAM stability, then caps output tokens
+    against remaining model context budget.
+    """
+    model, tokenizer = load_model(snapshot=snapshot, device_map=device_map, max_memory=max_memory)
+
+    # Keep prompt construction aligned with instruction chat fine-tuning.
+    messages = [{"role": "user", "content": prompt}]
+    prompt_text = tokenizer.apply_chat_template(messages, add_generation_prompt=True, tokenize=False)
+    inputs = tokenizer(prompt_text, return_tensors="pt")
+    # Keep context bounded for 27B to control KV-cache VRAM on 16GB GPUs.
+    try:
+        max_input_tokens = int(os.environ.get("MODEL_MAX_INPUT_TOKENS_27B", "2048"))
+    except Exception:
+        max_input_tokens = 2048
+    input_ids = inputs.get("input_ids")
+    if (
+        max_input_tokens > 0
+        and input_ids is not None
+        and input_ids.shape[-1] > max_input_tokens
+    ):
+        start = input_ids.shape[-1] - max_input_tokens
+        for key in ("input_ids", "attention_mask"):
+            if key in inputs and inputs[key] is not None and inputs[key].shape[-1] > max_input_tokens:
+                inputs[key] = inputs[key][:, start:]
+        input_ids = inputs.get("input_ids")
+    input_device = pick_input_device(model)
+    inputs = {k: v.to(input_device) for k, v in inputs.items()}
+
+    # Preserve prompt token count so decode excludes the original prompt.
+    input_len = input_ids.shape[-1] if input_ids is not None else inputs["input_ids"].shape[-1]
+    model_max_len = resolve_model_max_length(model, tokenizer)
+    max_new_tokens = cap_new_tokens(cfg.get("tk"), input_len, model_max_len)
+
+    with torch.inference_mode():
+        out = model.generate(
+            **inputs,
+            max_new_tokens=max_new_tokens,
+            temperature=cfg.get("t"),
+            top_p=cfg.get("p"),
+            top_k=cfg.get("k"),
+            repetition_penalty=cfg.get("rep_penalty", 1.1),
+            do_sample=(cfg.get("t", 0) > 0),
+            pad_token_id=safe_pad_token_id(tokenizer),
+        )
+
+    response = tokenizer.decode(out[0][input_len:], skip_special_tokens=True)
+    return response.strip()

medgemma4.py

@@ -0,0 +1,144 @@
+# =============================================================================
+# Author: Rick Escher
+# Project: SailingMedAdvisor
+# Context: Google HAI-DEF Framework
+# Models: Google MedGemmas
+# Program: Kaggle Impact Challenge
+# =============================================================================
+"""
+MedGemma 4B inference runner.
+
+Design intent:
+- Keep 4B loading fast and deterministic for triage-first workflows.
+- Reuse one model/tokenizer instance per active snapshot to avoid repeated
+  GPU allocation churn between requests.
+- Apply safety caps from runtime config before generation so user-provided
+  token settings cannot exceed model context limits.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict
+
+import os
+import gc
+
+import torch
+from transformers import AutoModelForCausalLM, AutoTokenizer
+
+from medgemma_common import (
+    cap_new_tokens,
+    pick_input_device,
+    resolve_model_max_length,
+    resolve_snapshot,
+    safe_pad_token_id,
+)
+
+MODEL_ID = "google/medgemma-1.5-4b-it"
+
+_MODEL = None
+_TOKENIZER = None
+_ACTIVE_SNAPSHOT = None
+
+
+def _default_dtype() -> torch.dtype:
+    """Select a stable default dtype based on runtime hardware and flags."""
+    if os.environ.get("FORCE_FP16", "").strip() == "1":
+        return torch.float16
+    if torch.cuda.is_available() and torch.cuda.is_bf16_supported():
+        return torch.bfloat16
+    if torch.cuda.is_available():
+        return torch.float16
+    return torch.float32
+
+
+def load_model(
+    *,
+    snapshot: str | None = None,
+    device_map: str | dict = "cuda:0",
+    dtype: torch.dtype | None = None,
+    attn_implementation: str | None = "eager",
+    local_files_only: bool = True,
+) -> tuple[Any, Any]:
+    """
+    Load or reuse the 4B model.
+
+    Reuse strategy:
+    - If snapshot path matches `_ACTIVE_SNAPSHOT`, return cached objects.
+    - Otherwise load tokenizer/model once and pin as active snapshot.
+    """
+    global _MODEL, _TOKENIZER, _ACTIVE_SNAPSHOT
+    if dtype is None:
+        dtype = _default_dtype()
+    resolved = resolve_snapshot(MODEL_ID, snapshot)
+    if _MODEL is not None and _TOKENIZER is not None and _ACTIVE_SNAPSHOT == resolved:
+        return _MODEL, _TOKENIZER
+
+    model_kwargs: Dict[str, Any] = {
+        "torch_dtype": dtype,
+        "device_map": device_map,
+        "local_files_only": local_files_only,
+        "low_cpu_mem_usage": True,
+    }
+    if attn_implementation:
+        model_kwargs["attn_implementation"] = attn_implementation
+
+    _TOKENIZER = AutoTokenizer.from_pretrained(resolved, use_fast=True, local_files_only=local_files_only)
+    _MODEL = AutoModelForCausalLM.from_pretrained(resolved, **model_kwargs)
+    _MODEL.eval()
+    _ACTIVE_SNAPSHOT = resolved
+    return _MODEL, _TOKENIZER
+
+
+def unload_model() -> None:
+    """Release model/tokenizer references and clear CUDA cache when present."""
+    global _MODEL, _TOKENIZER, _ACTIVE_SNAPSHOT
+    _MODEL = None
+    _TOKENIZER = None
+    _ACTIVE_SNAPSHOT = None
+    gc.collect()
+    if torch.cuda.is_available():
+        torch.cuda.empty_cache()
+
+
+def generate(prompt: str, cfg: Dict[str, Any], *, snapshot: str | None = None, device_map: str | dict = "cuda:0") -> str:
+    """
+    Generate one assistant response using chat-template formatting.
+
+    `cfg` keys consumed:
+    - `tk`: max new tokens target
+    - `t`: temperature
+    - `p`: top-p
+    - `k`: top-k
+    - `rep_penalty`: repetition penalty
+    """
+    model, tokenizer = load_model(snapshot=snapshot, device_map=device_map)
+
+    # Use the tokenizer's chat template to keep prompt framing aligned with
+    # the instruction-tuned MedGemma 4B format.
+    messages = [{"role": "user", "content": prompt}]
+    prompt_text = tokenizer.apply_chat_template(messages, add_generation_prompt=True, tokenize=False)
+    inputs = tokenizer(prompt_text, return_tensors="pt")
+    input_ids = inputs.get("input_ids")
+    input_device = pick_input_device(model)
+    inputs = {k: v.to(input_device) for k, v in inputs.items()}
+
+    # Preserve prompt token length so we only decode newly generated tokens.
+    input_len = input_ids.shape[-1] if input_ids is not None else inputs["input_ids"].shape[-1]
+    model_max_len = resolve_model_max_length(model, tokenizer)
+    max_new_tokens = cap_new_tokens(cfg.get("tk"), input_len, model_max_len)
+
+    with torch.inference_mode():
+        out = model.generate(
+            **inputs,
+            max_new_tokens=max_new_tokens,
+            temperature=cfg.get("t"),
+            top_p=cfg.get("p"),
+            top_k=cfg.get("k"),
+            repetition_penalty=cfg.get("rep_penalty", 1.1),
+            do_sample=(cfg.get("t", 0) > 0),
+            pad_token_id=safe_pad_token_id(tokenizer),
+        )
+
+    response = tokenizer.decode(out[0][input_len:], skip_special_tokens=True)
+    return response.strip()

medgemma_common.py

@@ -0,0 +1,210 @@
+# =============================================================================
+# Author: Rick Escher
+# Project: SailingMedAdvisor
+# Context: Google HAI-DEF Framework
+# Models: Google MedGemmas
+# Program: Kaggle Impact Challenge
+# =============================================================================
+"""
+Shared helpers for MedGemma inference runners.
+
+This module centralizes shared safeguards used by both 4B and 27B runners:
+- Resolving a complete local snapshot from HF cache roots
+- Guarding token lengths against model context limits
+- Selecting stable padding and input device behavior across device maps
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Dict, List
+
+import torch
+
+
+def safe_pad_token_id(tok):
+    """Return a usable pad token ID fallback for generation APIs."""
+    pad = getattr(tok, "pad_token_id", None)
+    if pad is not None:
+        return pad
+    eos = getattr(tok, "eos_token_id", None)
+    if isinstance(eos, (list, tuple)):
+        return eos[0] if eos else None
+    return eos
+
+
+def iter_cache_roots() -> List[Path]:
+    """Yield known HuggingFace cache roots, deduplicated and existing only."""
+    roots: List[Path] = []
+    env_cache = os.environ.get("HUGGINGFACE_HUB_CACHE")
+    if env_cache:
+        roots.append(Path(env_cache))
+    env_home = os.environ.get("HF_HOME")
+    if env_home:
+        roots.append(Path(env_home) / "hub")
+    roots.append(Path("/mnt/modelcache/models_cache/hub"))
+    roots.append(Path("/mnt/modelcache/hf_home/hub"))
+    seen = set()
+    final: List[Path] = []
+    for root in roots:
+        if root in seen:
+            continue
+        seen.add(root)
+        if root.is_dir():
+            final.append(root)
+    return final
+
+
+def _snapshot_complete(snapshot: Path) -> bool:
+    """Validate that a snapshot directory has complete safetensor files."""
+    index = snapshot / "model.safetensors.index.json"
+    if index.exists():
+        try:
+            data = json.loads(index.read_text())
+        except Exception:
+            return False
+        weight_map = data.get("weight_map") or {}
+        files = set(weight_map.values())
+        if not files:
+            return False
+        for name in files:
+            f = snapshot / name
+            if not f.exists():
+                return False
+            target = f.resolve()
+            if str(target).endswith(".incomplete"):
+                return False
+        return True
+    single = snapshot / "model.safetensors"
+    if single.exists():
+        target = single.resolve()
+        return not str(target).endswith(".incomplete")
+    return False
+
+
+def _pick_latest_complete(snapshot_dir: Path, model_id: str) -> str:
+    """Pick newest snapshot that passes completeness checks."""
+    if not snapshot_dir.is_dir():
+        raise FileNotFoundError(f"Snapshot dir not found for {model_id}: {snapshot_dir}")
+    snapshots = [d for d in snapshot_dir.iterdir() if d.is_dir()]
+    if not snapshots:
+        raise FileNotFoundError(f"No snapshots found for {model_id} in: {snapshot_dir}")
+    snapshots.sort(key=lambda p: p.stat().st_mtime, reverse=True)
+    for snap in snapshots:
+        if _snapshot_complete(snap):
+            return str(snap)
+    raise FileNotFoundError(
+        f"Snapshots found for {model_id}, but weights are incomplete (.incomplete). "
+        f"Checked: {snapshot_dir}"
+    )
+
+
+def resolve_snapshot(model_id: str, snapshot_override: str | None = None) -> str:
+    """
+    Resolve a concrete snapshot path for local model loading.
+
+    Preference order:
+    1) Caller override path (direct snapshot or `.../snapshots`)
+    2) Latest complete snapshot from known cache roots
+    """
+    if snapshot_override:
+        override = Path(snapshot_override)
+        if (override / "snapshots").is_dir():
+            return _pick_latest_complete(override / "snapshots", model_id)
+        if override.is_dir() and _snapshot_complete(override):
+            return str(override)
+        return snapshot_override
+    safe = model_id.replace("/", "--")
+    snapshots: List[Path] = []
+    for root in iter_cache_roots():
+        base = root / f"models--{safe}" / "snapshots"
+        if not base.is_dir():
+            continue
+        snapshots.extend([d for d in base.iterdir() if d.is_dir()])
+    if not snapshots:
+        raise FileNotFoundError(
+            f"No snapshots found for {model_id}. Checked: {', '.join(map(str, iter_cache_roots()))}"
+        )
+    snapshots.sort(key=lambda p: p.stat().st_mtime, reverse=True)
+    for snap in snapshots:
+        if _snapshot_complete(snap):
+            return str(snap)
+    raise FileNotFoundError(
+        f"Snapshots found for {model_id}, but weights are incomplete (.incomplete). "
+        f"Checked: {', '.join(map(str, iter_cache_roots()))}"
+    )
+
+
+def resolve_model_max_length(model, tok=None):
+    """Infer effective model context length from config/tokenizer metadata."""
+    cfg = getattr(model, "config", None)
+    candidates: List[int] = []
+    if cfg is not None:
+        for attr in ("max_position_embeddings", "max_seq_len", "max_sequence_length", "n_positions"):
+            val = getattr(cfg, attr, None)
+            if isinstance(val, int) and val > 0:
+                candidates.append(val)
+        text_cfg = getattr(cfg, "text_config", None)
+        if text_cfg is not None:
+            for attr in ("max_position_embeddings", "max_seq_len", "max_sequence_length", "n_positions"):
+                val = getattr(text_cfg, attr, None)
+                if isinstance(val, int) and val > 0:
+                    candidates.append(val)
+    if tok is not None:
+        tok_max = getattr(tok, "model_max_length", None)
+        if isinstance(tok_max, int) and 0 < tok_max < 1_000_000_000:
+            candidates.append(tok_max)
+    return min(candidates) if candidates else None
+
+
+def cap_new_tokens(max_new_tokens, input_len: int, model_max_len: int | None):
+    """Clamp requested output tokens so prompt+response stay within context."""
+    if not isinstance(max_new_tokens, int):
+        return max_new_tokens
+    if model_max_len is None:
+        return max_new_tokens
+    if input_len >= model_max_len:
+        return 1
+    max_allowed = max(model_max_len - input_len - 1, 1)
+    return min(max_new_tokens, max_allowed)
+
+
+def pick_input_device(model) -> str:
+    """
+    Choose where prompt tensors should be placed before generation.
+
+    For partitioned/offloaded models, this prefers embedding-layer device.
+    """
+    if hasattr(model, "hf_device_map"):
+        device_map = getattr(model, "hf_device_map") or {}
+        preferred = None
+        for name, dev in device_map.items():
+            if isinstance(dev, str) and dev.startswith("cuda"):
+                if "embed" in name:
+                    return dev
+                preferred = dev
+        if preferred:
+            return preferred
+    return "cuda:0" if torch.cuda.is_available() else "cpu"
+
+
+def normalize_device_map(device_map: str | Dict[str, str]):
+    """Normalize common string forms into transformers-compatible device maps."""
+    if isinstance(device_map, str):
+        value = device_map.strip()
+        if value in {"auto", "balanced", "balanced_low_0", "sequential"}:
+            return value
+        if value.startswith("cuda") or value.startswith("cpu"):
+            return {"": value}
+    return device_map
+
+
+def device_map_all_cuda(device_map: str | Dict[str, str]) -> bool:
+    """Return True when all mapped targets point to CUDA devices."""
+    if isinstance(device_map, str):
+        return device_map.strip().startswith("cuda")
+    if isinstance(device_map, dict):
+        return all(str(v).startswith("cuda") for v in device_map.values())
+    return False

medgemma_writeup.md

@@ -0,0 +1,347 @@
+# SailingMedAdvisor  
+## Offline Emergency Decision Support for Offshore Crews Using MedGemma
+
+**One-Sentence Summary:**  
+SailingMedAdvisor is a clinical decision-support system for offshore sailing vessels, powered by Google’s MedGemma models from the Health AI Developer Foundations (HAI-DEF), operating on edge hardware without reliable internet access.
+
+### Project name
+
+SailingMedAdvisor
+
+### Your team: Rick Escher (solo project lead)
+Captain of **s/v Aphrodite** since 2015, with direct operational responsibility for offshore safety, medical decision-making, and emergency logistics. Background in physics and space science (**M.S. in Space Science**). Former founder of **Recognia Inc.** (now TradingCentral.com).
+
+**Role in this project:** problem definition, system architecture, product design, implementation, prompt pathway design, offline deployment/testing, and clinical workflow validation against real offshore scenarios.
+
+---
+
+### Problem statement
+
+Offshore sailing vessels routinely operate hundreds or thousands of miles from the nearest hospital. During ocean passages there is no reliable internet connectivity, no rapid evacuation capability, and often no professional medical assistance available. The crew must manage traumatic injuries, infections, allergic reactions, burns, embedded objects, and other acute medical conditions using only the limited supplies stored onboard. Under the principles of SOLAS and longstanding maritime law, the captain bears ultimate responsibility for the health and safety of all persons aboard, including the provision of reasonable medical care within the vessel’s operational constraints.
+
+Most AI healthcare tools assume constant internet access or centralized cloud infrastructure. That assumption fails in maritime, polar, wilderness, and disaster-response environments. In these settings, privacy and autonomy are equally critical: crew medical history should not leave the vessel, and treatment guidance must function entirely offline.
+
+The core problem addressed by this project is:
+
+> **Can a clinically capable large language model support structured emergency reasoning fully offline, on edge hardware, while respecting supply constraints, privacy, and distance from definitive care?**
+
+SailingMedAdvisor demonstrates that MedGemma can operate in constrained, real-world, non-cloud environments and provide structured, context-aware decision support during medical events at sea.
+
+---
+
+### Impact potential
+
+In a local pilot snapshot (as of 2026-02-23), the system shows measurable operational impact for offshore decision support:
+
+- **Sustained use, not one-off demo:** **114 completed consultations** were recorded locally (`109` on 4B, `5` on 27B).
+- **Fast first-pass guidance option:** 4B averaged **102.2 seconds** per run, enabling near-real-time initial triage support.
+- **Structured emergency framing:** retained consultation responses included an evacuation-state marker (`STAY`, `URGENT`, or `IMMEDIATE`) in **9/9** reviewed cases.
+
+**Method:** metrics were computed from local SQLite tables (`chat_metrics`, `history_entries`) using run counts, duration fields, and response-text pattern checks. No external telemetry was used.
+
+---
+
+### Overall solution
+
+SailingMedAdvisor integrates Google’s MedGemma models into a structured triage workflow that:
+
+1. Runs entirely offline on a local machine (for this project a Lenovo P53 with an NVIDIA Quadro RTX 5000 GPU).
+2. Uses a hierarchical clinical triage pathway to constrain reasoning.
+3. Incorporates onboard medical inventory into the prompt.
+4. Stores all patient and vessel data locally in SQLite.
+5. Avoids network calls during inference.
+
+The system supports two reasoning modes:
+
+- **General Triage Mode:** Used when limited structured inputs are provided.
+- **Pathway-Specific Mode:** Activated when structured triage inputs are provided.
+
+When structured inputs are supplied, the system dynamically assembles a pathway-specific prompt composed of modular clinical instruction blocks. This increases reasoning specificity and reduces generic or irrelevant recommendations.
+
+Inference is performed locally using:
+
+- `google/medgemma-1.5-4b-it`
+- `google/medgemma-27b-text-it`
+
+No cloud APIs are used during runtime.
+
+---
+
+### Technical details
+
+## Inputs and Data Handling
+
+There is no external dataset. The system operates on structured and contextual inputs including:
+
+- Triage dropdown selections  
+- Patient condition indicators (Consciousness, Breathing, Circulation, Stability)  
+- Crew medical history  
+- Vessel-specific operational constraints (crew size, sea state, power, environment, evacuation feasibility)  
+- Onboard medical inventory (medications, procedural supplies, monitoring tools)  
+- Distance from definitive care  
+
+All data is stored locally in `app.db` (SQLite).
+
+---
+
+## Prompt Construction Strategy
+
+Act as a Trauma Surgeon. You are in Trauma Mode. Rule out physiological failure before addressing anatomical appearance. Do not provide wound care instructions until you have confirmed Airway, Breathing, and Circulation (ABC) stability.
+The system now uses a hierarchical prompt assembly approach:
+
+1. User selects structured triage categories:
+   - Domain (Trauma, Medical Illness, Environmental, Dental, Psychological)
+   - Problem Type
+   - Anatomy
+   - Mechanism/Cause
+   - Severity/Complication
+
+2. The system maps selections to predefined clinical prompt modules.
+
+3. Modules are combined with:
+   - Structured inventory constraints (pharmaceuticals, equipment, consumables)
+   - Distance-from-care context
+   - Structured emergency safety framework (airway, breathing, bleeding checks, and evacuation thresholds)
+   - Clarifying question templates
+
+4. If the pathway is incomplete, the system falls back to a general triage framework.
+
+This structured assembly improves:
+
+- Clinical specificity  
+- Operational alignment  
+- Supply awareness  
+- Reduction of generic responses  
+
+---
+### Inventory Constraints
+
+Onboard medical inventory is structured into three operational categories:
+
+1. **Pharmaceuticals** – antibiotics, analgesics, antiemetics, epinephrine, antiparasitics, and controlled medications.  
+2. **Equipment** – suturing kits, irrigation devices, splints, monitoring tools, dental repair materials, and procedural instruments.  
+3. **Consumables** – gauze, sterile saline, gloves, dressings, syringes, and other expendable supplies.  
+
+Recommendations are constrained to what is physically available onboard. This prevents unrealistic or non-executable guidance and ensures that suggested interventions are operationally feasible in a remote maritime environment.
+
+Because vessels routinely enter new jurisdictions, controlled medications must be tracked, declared, and reconciled for customs and immigration authorities. The system includes structured controlled-substance logging not only for clinical accountability but also to support regulatory compliance during international clearance procedures.
+
+#### Operational Continuity and System Reliability
+
+Additional vessel and crew management features were integrated intentionally. The system includes:
+
+- Vessel documentation records  
+- Crew list management including passport information, vaccine history and photographs  
+- Controlled medicine logs  
+- Export tools for immigration and customs documentation  
+
+These capabilities serve dual purposes.
+
+First, they support real operational requirements during international clearance.
+
+Second, they ensure the software is used regularly between medical events. In remote environments, infrequently used computer systems risk becoming outdated or misconfigured. By embedding high-frequency operational tasks into the platform, SailingMedAdvisor remains active, validated, and familiar to users. This reduces startup friction and increases reliability during times of actual emergency.
+
+Together, structured pathway logic, inventory constraint modeling, stabilization scaffolding, and operational integration allow MedGemma to function as a context-aware clinical reasoning engine within the practical realities of offshore sailing.
+
+---
+## Model Integration
+
+MedGemma is loaded using Hugging Face Transformers with runtime-selectable parameters:
+
+- Temperature  
+- Top-p  
+- Top-k  
+- Max new tokens  
+
+The inference adapters (`medgemma4.py`, `medgemma27b.py`), with shared helpers in `medgemma_common.py`, standardize prompt formatting, device handling, and token budgeting for consistent behavior. When sampling is enabled, outputs are not strictly deterministic.
+
+Startup logic performs:
+
+- CUDA preflight validation  
+- Configurable GPU memory caps and placement constraints  
+- Optional CPU fallback control (disabled by default)  
+- Explicit failure if GPU is unavailable when `FORCE_CUDA=1`  
+
+Inference runs locally in edge deployment mode. A separate remote-inference path exists only when local inference is explicitly disabled (for example, hosted mode).
+
+---
+
+### Reproducibility (initial results)
+
+- Public repository: https://github.com/rickeae/SailingMedAdvisor
+- Pinned code snapshot for this submission: `de93f406d161b832482494b9c90b4f2578e3a85a`
+- Models used: `google/medgemma-1.5-4b-it`, `google/medgemma-27b-text-it`
+
+#### Setup and run
+
+```bash
+git clone https://github.com/rickeae/SailingMedAdvisor.git
+cd SailingMedAdvisor
+git checkout de93f406d161b832482494b9c90b4f2578e3a85a
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+chmod +x run_med_advisor.sh
+./run_med_advisor.sh
+```
+
+Open: `http://127.0.0.1:5000`
+
+#### Reproduce the demo scenario
+
+1. Select **Triage Consultation** mode.
+2. Select model: **google/medgemma-27b-text-it**.
+3. Enter the fish-hook cheek scenario shown in the demo.
+4. Select the matching clinical pathway values shown in the demo.
+5. Submit and compare the returned guidance structure to the video.
+
+---
+
+# Architecture & Components
+
+## High-Level Workflow
+
+1. Captain/crew enters scenario details and optional triage pathway selections.  
+2. System assembles a mode-specific prompt (general triage or pathway-specific triage).  
+3. Prompt is augmented with onboard inventory and relevant vessel/crew context.  
+4. MedGemma runs locally and returns structured guidance.  
+5. Result is displayed and optionally stored in the consultation log for replay/review.  
+
+---
+
+## Core Components
+
+**Backend**
+- Python
+- FastAPI
+- SQLite
+
+**Models**
+- MedGemma 1.5 4B
+- MedGemma 27B
+
+**Frontend**
+- HTML templates
+- JavaScript
+- Structured triage dropdowns
+
+**Inference Pipeline**
+- Hugging Face Transformers
+- CUDA acceleration
+- Parameterized sampling
+
+**Edge Constraints**
+- No external API calls in edge deployment mode
+- No telemetry
+- No remote logging
+- Fully local state persistence
+
+---
+
+# Demo and Results
+
+The demonstration presents a real offshore scenario: a barbed fish hook embedded in a child’s cheek in a remote harbor in the Solomon Islands. Patient identifiers are fictionalized, but the medical scenario reflects an actual offshore event.
+
+Observed system behaviors:
+
+- Network disabled during inference.
+- GPU utilization rises to 100%, confirming local execution.
+- MedGemma returns:
+  - Structured triage summary
+  - Initial assessment
+  - Stabilization plan
+  - Procedural considerations
+  - Clarifying questions
+
+When the structured pathway is selected:
+
+The generated guidance becomes more anatomy-specific, mechanism-aware, and inventory-constrained than in generic triage mode, reducing irrelevant recommendations.
+
+The resulting guidance is anatomy-specific, operationally constrained, and supply-aware.
+
+Evaluation is qualitative and scenario-based, focusing on:
+
+- Structured output consistency  
+- Offline reliability  
+- Clinical coherence  
+- Operational realism  
+
+### Measured feasibility results (pilot)
+
+| Metric | 4B (`google/medgemma-1.5-4b-it`) | 27B (`google/medgemma-27b-text-it`) | Measurement source |
+| --- | ---: | ---: | --- |
+| Logged completed runs | 109 | 5 | `chat_metrics.count` |
+| Mean response time | 102.2 s | 2,904.9 s (48.4 min) | `chat_metrics.avg_ms` |
+| Retained-log median response time | 53.4 s (n=7) | 3,476.6 s (n=1) | `history_entries.duration_ms` |
+| Retained-log P95 response time | 109.4 s (n=7) | 3,476.6 s (n=1) | `history_entries.duration_ms` |
+| Non-empty response rate (retained log) | 7/7 (100%) | 2/2 (100%) | `history_entries.response` |
+
+**Method note:** `history_entries` currently contains a pruned subset (9 records). The `chat_metrics` table captures aggregate throughput across a larger run set.
+
+The system demonstrates that MedGemma can perform context-constrained clinical reasoning entirely at the edge.
+
+---
+
+# Final Model Description
+
+The final configuration uses:
+
+- MedGemma 1.5 4B for lightweight deployment
+- MedGemma 27B for higher-fidelity reasoning
+- No fine-tuning
+- Hierarchical prompt assembly
+- Controlled generation parameters
+
+Validation strategy:
+
+- Structured vs unstructured prompt comparison
+- Pathway-specific vs general reasoning evaluation
+- Multiple real-world offshore case simulations
+- GPU-only execution validation
+
+There is no leaderboard dataset; evaluation focuses on feasibility, reproducibility, and real-world applicability.
+
+---
+
+# Sources / References
+
+- Google Health AI Developer Foundations (HAI-DEF)
+- MedGemma model collection (Hugging Face)
+- Hugging Face Transformers
+- FastAPI documentation
+- SQLite documentation
+- CUDA runtime documentation
+- Public code repository: https://github.com/rickeae/SailingMedAdvisor
+
+All models are used in accordance with HAI-DEF Terms of Use.
+
+---
+
+# Future Work
+
+Planned enhancements include:
+
+- Structured risk scoring overlay  
+- Dosage calculation module  
+- Formal evacuation threshold classifier  
+- Offline PDF export of consultations  
+- Multilingual support  
+- Model distillation for lower-power hardware  
+- Structured evaluation against maritime medical manuals  
+
+Long-term applications extend beyond sailing vessels to:
+
+- Remote research stations  
+- Disaster response environments  
+- Wilderness expeditions  
+- Rural mobile clinics  
+
+---
+
+# Conclusion
+
+SailingMedAdvisor demonstrates that MedGemma can operate as a structured clinical decision-support engine entirely at the edge.
+
+The system runs fully offline, keeps all patient data local, integrates operational constraints, and delivers structured medical reasoning tailored to offshore emergencies.
+
+This project shows that high-fidelity medical AI does not require cloud infrastructure to be effective. In constrained environments where internet access is unavailable and evacuation may be delayed, MedGemma can function as a privacy-preserving, operationally grounded clinical reasoning system.

requirements.txt

@@ -0,0 +1,13 @@
+fastapi
+uvicorn
+jinja2
+python-multipart
+aiofiles
+pillow
+torch
+transformers
+bitsandbytes
+accelerate
+safetensors
+huggingface-hub
+itsdangerous

run_med_advisor.sh

@@ -0,0 +1,118 @@
+#!/bin/bash
+# =============================================================================
+# Author: Rick Escher
+# Project: SailingMedAdvisor
+# Context: Google HAI-DEF Framework
+# Models: Google MedGemmas
+# Program: Kaggle Impact Challenge
+# =============================================================================
+# run_med_advisor.sh - Secure startup script for MedGemma Advisor
+
+echo "=================================================="
+echo "SailingMeAdvisor - Offline emergency medical guidance for offshore sailors,"
+echo "powered by MedGemma (HAI-DEF)"
+echo ""
+echo "=================================================="
+
+# Check if virtual environment exists
+if [ ! -d ".venv" ]; then
+    echo "❌ Error: Virtual environment not found!"
+    echo "Please create it first: python3 -m venv .venv"
+    exit 1
+fi
+
+# Activate virtual environment
+source .venv/bin/activate
+
+# 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]"
+    exit 1
+}
+
+# Set environment variables (can be customized)
+# export ADMIN_PASSWORD='your_secure_password'
+# export SECRET_KEY='your_secret_key'
+# Prefer BF16 for stability; set FORCE_FP16=1 (and ALLOW_FP16=1) to override.
+# Respect user override; default to 0 to prefer BF16 on supported GPUs.
+export FORCE_FP16="${FORCE_FP16:-0}"
+# Keep SDP kernels conservative on RTX 5000/Turing; opt in to fast kernels manually.
+export USE_FAST_SDP="${USE_FAST_SDP:-0}"
+# Tab bar theme toggle:
+# 1 = splash purple (#7452B9), 0 = default gray.
+export USE_SPLASH_PURPLE_TABBAR="${USE_SPLASH_PURPLE_TABBAR:-0}"
+# Legacy env retained for compatibility with any existing checks.
+export USE_FLASH_ATTENTION="${USE_FLASH_ATTENTION:-$USE_FAST_SDP}"
+export TORCH_USE_CUDA_DSA=0
+# Choose a safe default for mixed hardware:
+# - If user explicitly sets FORCE_CUDA, honor it.
+# - If unset, prefer GPU only when NVIDIA tooling is present.
+if [ -z "${FORCE_CUDA+x}" ]; then
+    if command -v nvidia-smi >/dev/null 2>&1; then
+        export FORCE_CUDA="1"
+    else
+        export FORCE_CUDA="0"
+    fi
+else
+    export FORCE_CUDA
+fi
+# Keep GPU-only behavior by default; set to 1 only if we explicitly want CPU fallback on CUDA runtime faults.
+export ALLOW_CPU_FALLBACK_ON_CUDA_ERROR="${ALLOW_CPU_FALLBACK_ON_CUDA_ERROR:-0}"
+# Keep global cap high for 4B but reserve headroom for 27B KV cache.
+export MODEL_MAX_GPU_MEM="${MODEL_MAX_GPU_MEM:-15GiB}"
+export MODEL_MAX_GPU_MEM_27B="${MODEL_MAX_GPU_MEM_27B:-8GiB}"
+export MODEL_MAX_CPU_MEM=64GiB
+# 0 disables hard cap so token count comes from Settings (tr_tok/in_tok).
+export MODEL_MAX_NEW_TOKENS_27B="${MODEL_MAX_NEW_TOKENS_27B:-0}"
+export MODEL_MAX_INPUT_TOKENS_27B="${MODEL_MAX_INPUT_TOKENS_27B:-2048}"
+export MODEL_DEVICE_MAP_27B="${MODEL_DEVICE_MAP_27B:-manual}"
+export MODEL_GPU_LAYERS_27B="${MODEL_GPU_LAYERS_27B:-14}"
+export MODEL_ATTN_IMPL_27B="${MODEL_ATTN_IMPL_27B:-eager}"
+# Reduce allocator fragmentation on long sessions.
+export PYTORCH_CUDA_ALLOC_CONF="${PYTORCH_CUDA_ALLOC_CONF:-expandable_segments:True}"
+
+# CUDA preflight: fail early when FORCE_CUDA=1 so we don't silently run on CPU.
+if [ "$FORCE_CUDA" = "1" ]; then
+    echo "🔎 CUDA preflight (FORCE_CUDA=1)"
+    python3 - <<'PY'
+import sys
+import torch
+
+if not torch.cuda.is_available():
+    print("❌ CUDA preflight failed: torch.cuda.is_available() is False")
+    try:
+        torch.cuda.current_device()
+    except Exception as exc:
+        print(f"   CUDA error: {exc}")
+    sys.exit(1)
+
+try:
+    _ = torch.zeros(1, device="cuda")
+except Exception as exc:
+    print(f"❌ CUDA preflight failed during tensor allocation: {exc}")
+    sys.exit(1)
+
+print(f"✅ CUDA preflight passed on GPU: {torch.cuda.get_device_name(0)}")
+PY
+    if [ $? -ne 0 ]; then
+        echo "Hint: check kernel GPU errors with: journalctl -k | grep -i -E 'NVRM|Xid'"
+        echo "If errors persist, reboot or reload NVIDIA driver modules before restarting SailingMedAdvisor."
+        exit 1
+    fi
+fi
+
+# Detect a LAN IP to share in the startup banner (best effort)
+LAN_IP=$(hostname -I 2>/dev/null | awk 'NF{print $1; exit}')
+if [ -z "$LAN_IP" ] && command -v ip >/dev/null 2>&1; then
+    LAN_IP=$(ip route get 8.8.8.8 2>/dev/null | awk 'NR==1 {print $7}')
+fi
+
+# Run the application
+echo "🚀 Starting server on http://127.0.0.1:5000"
+if [ -n "$LAN_IP" ]; then
+    echo "🌐 LAN access: http://${LAN_IP}:5000"
+else
+    echo "🌐 LAN access: http://<this-machine-ip>:5000"
+fi
+echo "=================================================="
+python3 -m uvicorn app:app --host 0.0.0.0 --port 5000

scripts/bootstrap_ubuntu24_sailingmedadvisor.sh

@@ -0,0 +1,199 @@
+#!/usr/bin/env bash
+# =============================================================================
+# Author: Rick Escher
+# Project: SailingMedAdvisor
+# Context: Google HAI-DEF Framework
+# Models: Google MedGemmas
+# Program: Kaggle Impact Challenge
+# =============================================================================
+# scripts/bootstrap_ubuntu24_sailingmedadvisor.sh
+#
+# Purpose:
+#   End-to-end bootstrap for a clean Ubuntu 24.04 machine:
+#   1) install required system packages
+#   2) clone SailingMedAdvisor anonymously from GitHub
+#   3) run project install script
+#   4) run fresh-install verification
+#   5) optionally start the app
+#
+# Usage:
+#   chmod +x scripts/bootstrap_ubuntu24_sailingmedadvisor.sh
+#   ./scripts/bootstrap_ubuntu24_sailingmedadvisor.sh
+#
+# Optional flags:
+#   --target <dir>         Install directory (default: $HOME/SailingMedAdvisor)
+#   --branch <name>        Git branch (default: main)
+#   --repo-url <url>       Repo URL (default: public GitHub URL)
+#   --skip-system-packages Skip apt install step
+#   --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
+#   --help                 Show usage
+
+set -euo pipefail
+
+REPO_URL="https://github.com/rickeae/SailingMedAdvisor.git"
+BRANCH="main"
+TARGET_DIR="${HOME}/SailingMedAdvisor"
+SKIP_SYSTEM_PACKAGES="0"
+START_APP="0"
+PREFER_GPU_START="0"
+FORCE_CUDA_OVERRIDE=""
+
+usage() {
+  cat <<'EOF'
+bootstrap_ubuntu24_sailingmedadvisor.sh
+
+Flags:
+  --target <dir>          Install directory (default: $HOME/SailingMedAdvisor)
+  --branch <name>         Git branch (default: main)
+  --repo-url <url>        Repo URL (default: https://github.com/rickeae/SailingMedAdvisor.git)
+  --skip-system-packages  Skip apt package installation
+  --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
+  --help                  Show this help text
+EOF
+}
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --target)
+      TARGET_DIR="$2"; shift 2 ;;
+    --branch)
+      BRANCH="$2"; shift 2 ;;
+    --repo-url)
+      REPO_URL="$2"; shift 2 ;;
+    --skip-system-packages)
+      SKIP_SYSTEM_PACKAGES="1"; shift ;;
+    --start)
+      START_APP="1"; shift ;;
+    --prefer-gpu-start)
+      PREFER_GPU_START="1"; shift ;;
+    --force-cuda)
+      FORCE_CUDA_OVERRIDE="$2"; shift 2 ;;
+    --help|-h)
+      usage; exit 0 ;;
+    *)
+      echo "Unknown argument: $1"
+      usage
+      exit 1 ;;
+  esac
+done
+
+run_as_root() {
+  if [[ "${EUID:-$(id -u)}" -eq 0 ]]; then
+    "$@"
+    return
+  fi
+  if command -v sudo >/dev/null 2>&1; then
+    sudo "$@"
+    return
+  fi
+  echo "ERROR: Need root or sudo to run: $*"
+  exit 1
+}
+
+install_system_packages() {
+  if [[ "$SKIP_SYSTEM_PACKAGES" == "1" ]]; then
+    echo "[info] Skipping apt package installation (--skip-system-packages)"
+    return
+  fi
+  if ! command -v apt-get >/dev/null 2>&1; then
+    echo "[warn] apt-get not found; skipping package install step."
+    return
+  fi
+  echo "[step] Installing system packages (git, python3, venv, pip, certs)"
+  run_as_root apt-get update
+  run_as_root apt-get install -y git python3 python3-venv python3-pip ca-certificates
+}
+
+clone_or_update_repo() {
+  echo "[step] Cloning/updating repository"
+  if [[ -d "$TARGET_DIR/.git" ]]; then
+    echo "[info] Existing repo found at $TARGET_DIR"
+    git -C "$TARGET_DIR" fetch --all --tags
+    git -C "$TARGET_DIR" checkout "$BRANCH"
+    git -C "$TARGET_DIR" pull --ff-only
+    return
+  fi
+  if [[ -e "$TARGET_DIR" && ! -d "$TARGET_DIR/.git" ]]; then
+    echo "ERROR: Target exists but is not a git repo: $TARGET_DIR"
+    exit 1
+  fi
+  git clone --branch "$BRANCH" "$REPO_URL" "$TARGET_DIR"
+}
+
+install_project() {
+  echo "[step] Running project installer"
+  cd "$TARGET_DIR"
+  chmod +x scripts/install_fresh_copy.sh
+  ./scripts/install_fresh_copy.sh --skip-clone
+}
+
+verify_project() {
+  echo "[step] Running verification"
+  cd "$TARGET_DIR"
+  ./.venv/bin/python scripts/verify_fresh_install.py
+}
+
+resolve_force_cuda() {
+  if [[ -n "$FORCE_CUDA_OVERRIDE" ]]; then
+    echo "$FORCE_CUDA_OVERRIDE"
+    return
+  fi
+  # Default to CPU-safe startup for reproducibility across unknown machines.
+  # This avoids failing on hosts with partial/broken GPU drivers.
+  if [[ "$PREFER_GPU_START" != "1" ]]; then
+    echo "0"
+    return
+  fi
+  if command -v nvidia-smi >/dev/null 2>&1; then
+    echo "1"
+  else
+    echo "0"
+  fi
+}
+
+start_project_if_requested() {
+  if [[ "$START_APP" != "1" ]]; then
+    return
+  fi
+  cd "$TARGET_DIR"
+  chmod +x run_med_advisor.sh
+  FORCE_CUDA_VALUE="$(resolve_force_cuda)"
+  if [[ "$FORCE_CUDA_VALUE" == "1" ]]; then
+    echo "[step] Starting SailingMedAdvisor in GPU-preferred mode (FORCE_CUDA=1)"
+    FORCE_CUDA=1 ALLOW_CPU_FALLBACK_ON_CUDA_ERROR=1 ./run_med_advisor.sh
+  else
+    echo "[step] Starting SailingMedAdvisor in CPU-safe mode (FORCE_CUDA=0)"
+    FORCE_CUDA=0 ALLOW_CPU_FALLBACK_ON_CUDA_ERROR=1 ./run_med_advisor.sh
+  fi
+}
+
+main() {
+  echo "=================================================="
+  echo "SailingMedAdvisor Ubuntu 24.04 Bootstrap"
+  echo "Target: $TARGET_DIR"
+  echo "Repo:   $REPO_URL ($BRANCH)"
+  echo "=================================================="
+
+  install_system_packages
+  clone_or_update_repo
+  install_project
+  verify_project
+
+  cat <<EOF
+
+[done] Fresh install test completed successfully.
+Installed at: $TARGET_DIR
+
+To run manually:
+  cd "$TARGET_DIR"
+  FORCE_CUDA=0 ALLOW_CPU_FALLBACK_ON_CUDA_ERROR=1 ./run_med_advisor.sh
+
+EOF
+  start_project_if_requested
+}
+
+main "$@"

scripts/copy_pharma_lorraine_to_rick.sh

@@ -0,0 +1,65 @@
+#!/usr/bin/env bash
+# =============================================================================
+# Author: Rick Escher
+# Project: SailingMedAdvisor
+# Context: Google HAI-DEF Framework
+# Models: Google MedGemmas
+# Program: Kaggle Impact Challenge
+# =============================================================================
+set -euo pipefail
+
+# Copy only pharmaceuticals (type == "medication") from one workspace to another.
+# Equipment and consumables in the destination are preserved.
+
+SRC_WORKSPACE="${SRC_WORKSPACE:-Lorraine}"
+DEST_WORKSPACE="${DEST_WORKSPACE:-Rick}"
+APP_HOME="${APP_HOME:-/home/user/app}"
+
+slug() {
+  echo "${1:-}" | tr '[:upper:]' '[:lower:]' | sed -E 's/[^a-z0-9]+/-/g; s/^-+|-+$//g'
+}
+
+SRC_SLUG=$(slug "$SRC_WORKSPACE")
+DEST_SLUG=$(slug "$DEST_WORKSPACE")
+
+DATA_BASE="$APP_HOME/data"
+UPLOAD_BASE="$APP_HOME/uploads"
+
+SRC_INV="$DATA_BASE/$SRC_SLUG/inventory.json"
+DEST_INV="$DATA_BASE/$DEST_SLUG/inventory.json"
+
+if [[ ! -f "$SRC_INV" ]]; then
+  echo "Source inventory not found: $SRC_INV" >&2
+  exit 1
+fi
+if [[ ! -f "$DEST_INV" ]]; then
+  echo "Destination inventory not found: $DEST_INV" >&2
+  exit 1
+fi
+
+backup="$DEST_INV.bak.$(date +%s)"
+if ! cp "$DEST_INV" "$backup" 2>/dev/null; then
+  echo "Unable to create backup at $backup. Check permissions (maybe the data dir is read-only)." >&2
+  exit 1
+fi
+
+jq -s '
+  def norm: ( .type // "" ) | ascii_downcase;
+  (.[0] // []) as $dest
+  | (.[1] // []) as $src
+  | ($dest | map(select(norm != "medication"))) as $dest_keep
+  | ($src  | map(select(norm == "medication"))) as $src_meds
+  | $dest_keep + $src_meds
+' "$DEST_INV" "$SRC_INV" > "${DEST_INV}.tmp"
+mv "${DEST_INV}.tmp" "$DEST_INV"
+
+SRC_PHOTOS="$UPLOAD_BASE/$SRC_SLUG/medicines"
+DEST_PHOTOS="$UPLOAD_BASE/$DEST_SLUG/medicines"
+if [[ -d "$SRC_PHOTOS" ]]; then
+  mkdir -p "$DEST_PHOTOS"
+  rsync -av "$SRC_PHOTOS/" "$DEST_PHOTOS/"
+else
+  echo "No medicine photos found at $SRC_PHOTOS (skipping photos copy)"
+fi
+
+echo "Done. Backed up: $backup"

scripts/copy_pharma_lorraine_to_rick_pure.sh

@@ -0,0 +1,73 @@
+#!/usr/bin/env bash
+# =============================================================================
+# Author: Rick Escher
+# Project: SailingMedAdvisor
+# Context: Google HAI-DEF Framework
+# Models: Google MedGemmas
+# Program: Kaggle Impact Challenge
+# =============================================================================
+set -euo pipefail
+
+# Copy only pharmaceuticals from Lorraine to Rick without jq.
+# Heuristic: anything not explicitly consumable/equipment/durable is treated as medication.
+# Requires python3 (available) for JSON manipulation; avoids sudo.
+
+SRC_WORKSPACE="${SRC_WORKSPACE:-Lorraine}"
+DEST_WORKSPACE="${DEST_WORKSPACE:-Rick}"
+APP_HOME="${APP_HOME:-/home/user/app}"
+
+slug() {
+  echo "${1:-}" | tr '[:upper:]' '[:lower:]' | sed -E 's/[^a-z0-9]+/-/g; s/^-+|-+$//g'
+}
+
+SRC_SLUG=$(slug "$SRC_WORKSPACE")
+DEST_SLUG=$(slug "$DEST_WORKSPACE")
+
+SRC_INV="$APP_HOME/data/$SRC_SLUG/inventory.json"
+DEST_INV="$APP_HOME/data/$DEST_SLUG/inventory.json"
+
+if [[ ! -f "$SRC_INV" ]]; then
+  echo "Source inventory not found: $SRC_INV" >&2
+  exit 1
+fi
+if [[ ! -f "$DEST_INV" ]]; then
+  echo "Destination inventory not found: $DEST_INV" >&2
+  exit 1
+fi
+
+backup="$DEST_INV.bak.$(date +%s)"
+cp "$DEST_INV" "$backup"
+
+python3 - <<PY
+import json
+from pathlib import Path
+
+src = Path("$SRC_INV").read_text()
+dest = Path("$DEST_INV").read_text()
+try:
+    src_data = json.loads(src)
+    dest_data = json.loads(dest)
+except Exception as e:
+    raise SystemExit(f"JSON parse error: {e}")
+
+def norm_type(item):
+    return (item.get("type") or "").strip().lower()
+
+keep_types = {"consumable", "equipment", "durable"}
+dest_keep = [x for x in dest_data if norm_type(x) in keep_types]
+src_meds = [x for x in src_data if norm_type(x) not in keep_types]
+
+merged = dest_keep + src_meds
+Path("$DEST_INV").write_text(json.dumps(merged, indent=2))
+PY
+
+SRC_PH="$APP_HOME/uploads/$SRC_SLUG/medicines"
+DEST_PH="$APP_HOME/uploads/$DEST_SLUG/medicines"
+if [[ -d "$SRC_PH" ]]; then
+  mkdir -p "$DEST_PH"
+  cp -a "$SRC_PH/." "$DEST_PH/"
+else
+  echo "No medicine photos found at $SRC_PH (skipping photos copy)"
+fi
+
+echo "Done. Backup created at $backup"

scripts/import_clean_triage_tree.py

@@ -0,0 +1,345 @@
+#!/usr/bin/env python3
+# =============================================================================
+# Author: Rick Escher
+# Project: SailingMedAdvisor
+# Context: Google HAI-DEF Framework
+# Models: Google MedGemmas
+# Program: Kaggle Impact Challenge
+# =============================================================================
+"""
+Import the clean hierarchical triage tree into SailingMedAdvisor's runtime schema.
+
+Input schema (clean, editable):
+{
+  "tree_version": "1.0",
+  "domain": {
+    "Trauma": {
+      "presentation": {
+        "Laceration": {
+          "region_or_system": {
+            "Head": {
+              "condition_state": [...],
+              "risk_modifier": [...]
+            }
+          }
+        }
+      }
+    }
+  }
+}
+
+Runtime schema (current app expects):
+{
+  "base_doctrine": "...",
+  "tree": {
+        "Trauma": {
+          "mindset": "...",
+          "problems": {
+            "Laceration": {
+              "procedure": "...",
+              "anatomy_guardrails": {"Head": "..."},
+              "severity_modifiers": {"Stable": "..."},
+              "mechanism_modifiers": {"Fall mechanism": "..."}
+            }
+          }
+    }
+  }
+}
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+PROJECT_ROOT = Path(__file__).resolve().parents[1]
+if str(PROJECT_ROOT) not in sys.path:
+    sys.path.insert(0, str(PROJECT_ROOT))
+
+import db_store
+
+
+DEFAULT_BASE_DOCTRINE = (
+    "You are SailingMedAdvisor. Role: Damage-control for Vessel Captain. "
+    "Priority: MARCH-PAWS. Rules: Numbered imperative steps, timed reassessment intervals, "
+    "no speculation, only Medical Chest items. For Ethan: weight-based dosing. "
+    "Output: STAY, URGENT, or IMMEDIATE."
+)
+
+DOMAIN_MINDSETS = {
+    "Trauma": "Physiology over appearance. Stabilize first. Order: Hemostasis -> Airway -> Breathing -> Circulation.",
+    "Medical Illness": "Vitals trends and treatment response only. Avoid rare/complex diagnoses.",
+    "Environmental": "Neutralize the pathogen (environment) first.",
+    "Dental": "Preservation only. No extractions unless airway is threatened.",
+    "Behavioral": "Vessel safety first. Secure the environment; avoid chemical restraint.",
+}
+
+DOMAIN_ALIASES = {
+    "medical illness": "Medical Illness",
+    "behavioral / psychological": "Behavioral",
+}
+
+
+def norm(value: Any) -> str:
+    """
+    Norm helper.
+    Detailed inline notes are included to support safe maintenance and future edits.
+    """
+    return re.sub(r"[^a-z0-9]+", "", str(value or "").strip().lower())
+
+
+def first_existing_key(options: Dict[str, Any], wanted: str) -> Optional[str]:
+    """
+    First Existing Key helper.
+    Detailed inline notes are included to support safe maintenance and future edits.
+    """
+    if not isinstance(options, dict) or not wanted:
+        return None
+    if wanted in options:
+        return wanted
+    w = norm(wanted)
+    for key in options.keys():
+        if norm(key) == w:
+            return key
+    return None
+
+
+def as_list(values: Any) -> List[str]:
+    """
+    As List helper.
+    Detailed inline notes are included to support safe maintenance and future edits.
+    """
+    if not isinstance(values, list):
+        return []
+    seen = set()
+    out: List[str] = []
+    for v in values:
+        s = str(v or "").strip()
+        if not s:
+            continue
+        n = norm(s)
+        if n in seen:
+            continue
+        seen.add(n)
+        out.append(s)
+    return out
+
+
+def choose_text(
+    existing_map: Dict[str, Any],
+    key: str,
+    fallback: str,
+) -> str:
+    """
+    Choose Text helper.
+    Detailed inline notes are included to support safe maintenance and future edits.
+    """
+    if isinstance(existing_map, dict):
+        hit = first_existing_key(existing_map, key)
+        if hit and isinstance(existing_map.get(hit), str) and existing_map.get(hit).strip():
+            return existing_map.get(hit).strip()
+    return fallback
+
+
+def convert_clean_to_runtime(
+    clean: Dict[str, Any],
+    existing_runtime: Dict[str, Any],
+) -> Dict[str, Any]:
+    """
+    Convert Clean To Runtime helper.
+    Detailed inline notes are included to support safe maintenance and future edits.
+    """
+    clean_domains = clean.get("domain")
+    if not isinstance(clean_domains, dict) or not clean_domains:
+        raise ValueError("Input clean JSON must contain a non-empty 'domain' object.")
+
+    existing_tree = existing_runtime.get("tree") if isinstance(existing_runtime, dict) else {}
+    if not isinstance(existing_tree, dict):
+        existing_tree = {}
+
+    base_doctrine = (clean.get("base_doctrine") or "").strip()
+    if not base_doctrine:
+        base_doctrine = (existing_runtime.get("base_doctrine") or "").strip() if isinstance(existing_runtime, dict) else ""
+    if not base_doctrine:
+        base_doctrine = DEFAULT_BASE_DOCTRINE
+
+    runtime_tree: Dict[str, Any] = {}
+    for raw_domain_name, domain_payload in clean_domains.items():
+        if not isinstance(domain_payload, dict):
+            continue
+        domain_name = str(raw_domain_name or "").strip()
+        if not domain_name:
+            continue
+
+        canonical_domain = DOMAIN_ALIASES.get(domain_name.lower(), domain_name)
+        existing_domain_key = first_existing_key(existing_tree, canonical_domain) or first_existing_key(existing_tree, domain_name)
+        existing_domain = existing_tree.get(existing_domain_key, {}) if existing_domain_key else {}
+        existing_problems = existing_domain.get("problems") if isinstance(existing_domain, dict) else {}
+        if not isinstance(existing_problems, dict):
+            existing_problems = {}
+
+        mindset = (domain_payload.get("mindset") or "").strip()
+        if not mindset:
+            if isinstance(existing_domain, dict):
+                mindset = (existing_domain.get("mindset") or "").strip()
+        if not mindset:
+            mindset = DOMAIN_MINDSETS.get(canonical_domain, "")
+
+        clean_presentations = domain_payload.get("presentation")
+        if not isinstance(clean_presentations, dict):
+            clean_presentations = {}
+
+        problems_out: Dict[str, Any] = {}
+        for raw_presentation_name, presentation_payload in clean_presentations.items():
+            if not isinstance(presentation_payload, dict):
+                continue
+            presentation_name = str(raw_presentation_name or "").strip()
+            if not presentation_name:
+                continue
+
+            existing_problem_key = first_existing_key(existing_problems, presentation_name)
+            existing_problem = existing_problems.get(existing_problem_key, {}) if existing_problem_key else {}
+            if not isinstance(existing_problem, dict):
+                existing_problem = {}
+
+            procedure = (presentation_payload.get("procedure") or "").strip()
+            if not procedure:
+                procedure = (existing_problem.get("procedure") or "").strip()
+            if not procedure:
+                procedure = (
+                    f"Manage {presentation_name} under {canonical_domain} pathway. "
+                    "Use selected region/system, condition state, and risk modifier to drive step priorities."
+                )
+
+            existing_anatomy = existing_problem.get("anatomy_guardrails") if isinstance(existing_problem, dict) else {}
+            existing_severity = existing_problem.get("severity_modifiers") if isinstance(existing_problem, dict) else {}
+            existing_mechanism = existing_problem.get("mechanism_modifiers") if isinstance(existing_problem, dict) else {}
+            if not isinstance(existing_anatomy, dict):
+                existing_anatomy = {}
+            if not isinstance(existing_severity, dict):
+                existing_severity = {}
+            if not isinstance(existing_mechanism, dict):
+                existing_mechanism = {}
+
+            anatomy_guardrails: Dict[str, str] = {}
+            severity_modifiers: Dict[str, str] = {}
+            mechanism_modifiers: Dict[str, str] = {}
+
+            region_map = presentation_payload.get("region_or_system")
+            if not isinstance(region_map, dict):
+                region_map = {}
+
+            for raw_region_name, region_payload in region_map.items():
+                region_name = str(raw_region_name or "").strip()
+                if not region_name:
+                    continue
+                region_obj = region_payload if isinstance(region_payload, dict) else {}
+
+                anatomy_guardrails[region_name] = choose_text(
+                    existing_anatomy,
+                    region_name,
+                    (
+                        f"Focus region/system: {region_name}. Prioritize site-specific risks, trend changes, "
+                        "and reassessment intervals aligned with selected condition and risk modifiers."
+                    ),
+                )
+
+                for state_name in as_list(region_obj.get("condition_state")):
+                    if state_name in severity_modifiers:
+                        continue
+                    severity_modifiers[state_name] = choose_text(
+                        existing_severity,
+                        state_name,
+                        (
+                            f"Condition state: {state_name}. Escalate urgency based on trend and response; "
+                            "repeat focused reassessment at short intervals."
+                        ),
+                    )
+
+                for risk_name in as_list(region_obj.get("risk_modifier")):
+                    if risk_name in mechanism_modifiers:
+                        continue
+                    mechanism_modifiers[risk_name] = choose_text(
+                        existing_mechanism,
+                        risk_name,
+                        (
+                            f"Risk modifier: {risk_name}. Adjust monitoring window, hidden-injury suspicion, "
+                            "and evacuation threshold accordingly."
+                        ),
+                    )
+
+            problems_out[presentation_name] = {
+                "procedure": procedure,
+                "anatomy_guardrails": anatomy_guardrails,
+                "severity_modifiers": severity_modifiers,
+                "mechanism_modifiers": mechanism_modifiers,
+            }
+
+        if problems_out:
+            runtime_tree[canonical_domain] = {
+                "mindset": mindset,
+                "problems": problems_out,
+            }
+
+    if not runtime_tree:
+        raise ValueError("Converted runtime tree is empty; check input JSON content.")
+
+    return {
+        "base_doctrine": base_doctrine,
+        "tree": runtime_tree,
+    }
+
+
+def main() -> int:
+    """
+    Main helper.
+    Detailed inline notes are included to support safe maintenance and future edits.
+    """
+    parser = argparse.ArgumentParser(description="Import clean hierarchical triage tree JSON into app runtime DB schema.")
+    parser.add_argument("--input", required=True, help="Path to clean triage JSON (tree_version/schema/domain format).")
+    parser.add_argument("--db", default="app.db", help="Path to SQLite database (default: app.db).")
+    parser.add_argument("--preview-out", default="", help="Optional path to write converted runtime JSON preview.")
+    parser.add_argument("--dry-run", action="store_true", help="Convert and validate, but do not write to DB.")
+    args = parser.parse_args()
+
+    input_path = Path(args.input)
+    if not input_path.exists():
+        raise SystemExit(f"Input file not found: {input_path}")
+
+    try:
+        clean_payload = json.loads(input_path.read_text(encoding="utf-8"))
+    except Exception as exc:
+        raise SystemExit(f"Invalid JSON in {input_path}: {exc}") from exc
+
+    db_store.configure_db(Path(args.db))
+    existing = db_store.get_triage_prompt_tree() or {}
+    converted = convert_clean_to_runtime(clean_payload, existing)
+
+    if args.preview_out:
+        preview_path = Path(args.preview_out)
+        preview_path.write_text(json.dumps(converted, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+        print(f"Preview written: {preview_path}")
+
+    tree = converted.get("tree", {})
+    print(f"Converted domains: {len(tree)}")
+    for domain_name, domain_node in tree.items():
+        problems = domain_node.get("problems", {}) if isinstance(domain_node, dict) else {}
+        print(f"- {domain_name}: problems={len(problems)}")
+
+    if args.dry_run:
+        print("Dry run only; DB not modified.")
+        return 0
+
+    saved = db_store.set_triage_prompt_tree(converted)
+    saved_tree = saved.get("tree", {}) if isinstance(saved, dict) else {}
+    print(f"Saved to DB: {args.db}")
+    print(f"Saved domains: {len(saved_tree)}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

scripts/install_fresh_copy.sh

@@ -0,0 +1,139 @@
+#!/usr/bin/env bash
+# =============================================================================
+# Author: Rick Escher
+# Project: SailingMedAdvisor
+# Context: Google HAI-DEF Framework
+# Models: Google MedGemmas
+# Program: Kaggle Impact Challenge
+# =============================================================================
+# scripts/install_fresh_copy.sh
+#
+# Purpose:
+#   Streamline first-time setup on a new machine:
+#   1) clone repository (optional)
+#   2) create virtual environment
+#   3) install Python dependencies
+#   4) run deterministic install verification
+#
+# Usage examples:
+#   ./scripts/install_fresh_copy.sh
+#   ./scripts/install_fresh_copy.sh --target ~/SailingMedAdvisor --repo-url https://github.com/rickeae/SailingMedAdvisor.git
+#   ./scripts/install_fresh_copy.sh --skip-clone --skip-verify
+
+set -euo pipefail
+
+REPO_URL="https://github.com/rickeae/SailingMedAdvisor.git"
+BRANCH="main"
+TARGET_DIR=""
+SKIP_CLONE="0"
+SKIP_VERIFY="0"
+PYTHON_BIN="python3"
+
+usage() {
+  cat <<'EOF'
+install_fresh_copy.sh
+
+Options:
+  --repo-url <url>      Git repository URL (default: official GitHub repo)
+  --branch <name>       Branch to checkout (default: main)
+  --target <path>       Target directory (default: current directory if --skip-clone, else ./SailingMedAdvisor)
+  --python <bin>        Python executable (default: python3)
+  --skip-clone          Use existing repository in target/current directory
+  --skip-verify         Skip post-install verification script
+  -h, --help            Show this help
+EOF
+}
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --repo-url)
+      REPO_URL="$2"; shift 2 ;;
+    --branch)
+      BRANCH="$2"; shift 2 ;;
+    --target)
+      TARGET_DIR="$2"; shift 2 ;;
+    --python)
+      PYTHON_BIN="$2"; shift 2 ;;
+    --skip-clone)
+      SKIP_CLONE="1"; shift ;;
+    --skip-verify)
+      SKIP_VERIFY="1"; shift ;;
+    -h|--help)
+      usage; exit 0 ;;
+    *)
+      echo "Unknown option: $1"
+      usage
+      exit 1 ;;
+  esac
+done
+
+if ! command -v "$PYTHON_BIN" >/dev/null 2>&1; then
+  echo "ERROR: Python executable not found: $PYTHON_BIN"
+  exit 1
+fi
+
+if [[ "$SKIP_CLONE" == "1" ]]; then
+  if [[ -n "$TARGET_DIR" ]]; then
+    WORKDIR="$TARGET_DIR"
+  else
+    WORKDIR="$(pwd)"
+  fi
+else
+  if [[ -z "$TARGET_DIR" ]]; then
+    TARGET_DIR="$(pwd)/SailingMedAdvisor"
+  fi
+  WORKDIR="$TARGET_DIR"
+  if [[ -d "$WORKDIR/.git" ]]; then
+    echo "[info] Existing git repo detected at $WORKDIR; fetching latest branch $BRANCH"
+    git -C "$WORKDIR" fetch --all --tags
+    git -C "$WORKDIR" checkout "$BRANCH"
+    git -C "$WORKDIR" pull --ff-only
+  else
+    echo "[info] Cloning $REPO_URL into $WORKDIR"
+    git clone --branch "$BRANCH" "$REPO_URL" "$WORKDIR"
+  fi
+fi
+
+if [[ ! -f "$WORKDIR/app.py" || ! -f "$WORKDIR/requirements.txt" ]]; then
+  echo "ERROR: $WORKDIR does not look like SailingMedAdvisor repository root."
+  exit 1
+fi
+
+echo "[info] Working directory: $WORKDIR"
+cd "$WORKDIR"
+
+if [[ ! -d ".venv" ]]; then
+  echo "[info] Creating virtual environment"
+  "$PYTHON_BIN" -m venv .venv
+fi
+
+echo "[info] Upgrading pip/setuptools/wheel"
+./.venv/bin/python -m pip install --upgrade pip setuptools wheel
+
+echo "[info] Installing dependencies"
+./.venv/bin/pip install -r requirements.txt
+
+chmod +x run_med_advisor.sh
+chmod +x scripts/verify_fresh_install.py || true
+
+if [[ "$SKIP_VERIFY" == "0" ]]; then
+  echo "[info] Running installation verification"
+  ./.venv/bin/python scripts/verify_fresh_install.py
+else
+  echo "[warn] Verification skipped (--skip-verify)"
+fi
+
+cat <<'EOF'
+
+Installation complete.
+
+Next steps:
+1) Start app:
+   FORCE_CUDA=0 ALLOW_CPU_FALLBACK_ON_CUDA_ERROR=1 ./run_med_advisor.sh
+2) Open:
+   http://127.0.0.1:5000
+3) In Settings > Offline Readiness Check:
+   - Check cache status
+   - Download missing models (while online)
+   - Enable offline mode before offshore use
+EOF

scripts/verify_fresh_install.py

@@ -0,0 +1,310 @@
+#!/usr/bin/env python3
+# =============================================================================
+# Author: Rick Escher
+# Project: SailingMedAdvisor
+# Context: Google HAI-DEF Framework
+# Models: Google MedGemmas
+# Program: Kaggle Impact Challenge
+# =============================================================================
+"""
+scripts/verify_fresh_install.py
+
+Purpose:
+Run a deterministic "fresh machine" verification for SailingMedAdvisor.
+This checks runtime prerequisites, required files, database schema, default
+triage tree content, and a lightweight API startup smoke test.
+"""
+
+from __future__ import annotations
+
+import argparse
+import importlib
+import json
+import os
+import sqlite3
+import subprocess
+import sys
+import time
+import urllib.error
+import urllib.request
+from pathlib import Path
+from typing import List, Tuple
+
+
+REQUIRED_IMPORTS = [
+    "fastapi",
+    "uvicorn",
+    "jinja2",
+    "multipart",  # python-multipart import name
+    "aiofiles",
+    "PIL",
+    "torch",
+    "transformers",
+    "bitsandbytes",
+    "accelerate",
+    "safetensors",
+    "huggingface_hub",
+    "itsdangerous",
+]
+
+REQUIRED_FILES = [
+    "app.py",
+    "db_store.py",
+    "requirements.txt",
+    "run_med_advisor.sh",
+    "seed/triage_prompt_tree.default.json",
+    "templates/index.html",
+    "static/js/chat.js",
+]
+
+REQUIRED_TABLES = [
+    "settings_meta",
+    "crew",
+    "triage_options",
+    "triage_prompt_modules",
+    "triage_prompt_tree",
+]
+
+
+class CheckResults:
+    def __init__(self) -> None:
+        self.ok: List[str] = []
+        self.fail: List[str] = []
+        self.warn: List[str] = []
+
+    def pass_(self, msg: str) -> None:
+        self.ok.append(msg)
+        print(f"[PASS] {msg}")
+
+    def fail_(self, msg: str) -> None:
+        self.fail.append(msg)
+        print(f"[FAIL] {msg}")
+
+    def warn_(self, msg: str) -> None:
+        self.warn.append(msg)
+        print(f"[WARN] {msg}")
+
+    def summary(self) -> int:
+        print("\n=== Verification Summary ===")
+        print(f"Passed: {len(self.ok)}")
+        print(f"Warnings: {len(self.warn)}")
+        print(f"Failed: {len(self.fail)}")
+        return 1 if self.fail else 0
+
+
+def _repo_root() -> Path:
+    return Path(__file__).resolve().parents[1]
+
+
+def check_python_version(results: CheckResults) -> None:
+    if sys.version_info >= (3, 10):
+        results.pass_(f"Python version is supported: {sys.version.split()[0]}")
+    else:
+        results.fail_(f"Python >= 3.10 required, found {sys.version.split()[0]}")
+
+
+def check_required_files(results: CheckResults, repo: Path) -> None:
+    missing = [rel for rel in REQUIRED_FILES if not (repo / rel).exists()]
+    if missing:
+        results.fail_(f"Missing required files: {', '.join(missing)}")
+        return
+    results.pass_("Required project files are present")
+
+
+def check_imports(results: CheckResults) -> None:
+    missing = []
+    for mod in REQUIRED_IMPORTS:
+        try:
+            importlib.import_module(mod)
+        except Exception:
+            missing.append(mod)
+    if missing:
+        results.fail_(f"Missing Python imports: {', '.join(missing)}")
+    else:
+        results.pass_("All required Python packages import successfully")
+
+
+def _is_valid_sqlite(path: Path) -> bool:
+    try:
+        with path.open("rb") as f:
+            return f.read(16).startswith(b"SQLite format 3")
+    except Exception:
+        return False
+
+
+def _ensure_runtime_db(repo: Path, results: CheckResults) -> Path:
+    db_path = repo / "app.db"
+    if db_path.exists() and _is_valid_sqlite(db_path):
+        results.pass_(f"Runtime DB present: {db_path}")
+        return db_path
+
+    # If DB is absent/invalid on fresh machine, initialize schema via db_store.
+    try:
+        import db_store
+
+        db_store.configure_db(db_path)
+        if db_path.exists() and _is_valid_sqlite(db_path):
+            results.pass_(f"Runtime DB initialized: {db_path}")
+            return db_path
+        results.fail_("Failed to initialize runtime DB")
+    except Exception as exc:
+        results.fail_(f"DB initialization error: {exc}")
+    return db_path
+
+
+def check_db_schema(results: CheckResults, db_path: Path) -> None:
+    if not db_path.exists() or not _is_valid_sqlite(db_path):
+        results.fail_("DB schema check skipped: app.db missing or invalid")
+        return
+
+    try:
+        with sqlite3.connect(db_path) as conn:
+            names = {r[0] for r in conn.execute("SELECT name FROM sqlite_master WHERE type='table'")}
+            missing = [t for t in REQUIRED_TABLES if t not in names]
+            if missing:
+                results.fail_(f"DB missing required tables: {', '.join(missing)}")
+            else:
+                results.pass_("DB schema includes required tables")
+
+            row = conn.execute("SELECT payload FROM triage_prompt_tree WHERE id=1").fetchone()
+            if not row:
+                results.fail_("triage_prompt_tree id=1 is missing")
+                return
+            payload = json.loads(row[0] or "{}")
+            if not isinstance(payload.get("tree"), dict) or not payload["tree"]:
+                results.fail_("triage_prompt_tree payload has no valid tree")
+            else:
+                results.pass_("triage_prompt_tree payload exists and is valid JSON")
+    except Exception as exc:
+        results.fail_(f"DB schema read failed: {exc}")
+
+
+def check_default_tree_json(results: CheckResults, repo: Path) -> None:
+    path = repo / "seed/triage_prompt_tree.default.json"
+    try:
+        payload = json.loads(path.read_text(encoding="utf-8"))
+    except Exception as exc:
+        results.fail_(f"Default tree JSON unreadable: {exc}")
+        return
+
+    if not isinstance(payload.get("base_doctrine"), str) or not payload["base_doctrine"].strip():
+        results.fail_("Default tree is missing base_doctrine text")
+        return
+
+    tree = payload.get("tree")
+    if not isinstance(tree, dict) or not tree:
+        results.fail_("Default tree JSON missing top-level tree map")
+        return
+
+    required_domains = {
+        "Trauma",
+        "Illness",
+        "Toxins/Bites/Stings & Environmental Hazards",
+        "Dental",
+        "Psychological/Behavioral",
+    }
+    missing_domains = sorted(required_domains - set(tree.keys()))
+    if missing_domains:
+        results.warn_(f"Default tree missing expected domains: {', '.join(missing_domains)}")
+    else:
+        results.pass_("Default tree includes expected core domains")
+
+
+def _poll_db_status(base_url: str, timeout_s: int) -> Tuple[bool, str]:
+    start = time.time()
+    url = f"{base_url}/api/db/status"
+    while time.time() - start < timeout_s:
+        try:
+            with urllib.request.urlopen(url, timeout=2.0) as resp:
+                if resp.status != 200:
+                    time.sleep(0.5)
+                    continue
+                data = json.loads(resp.read().decode("utf-8"))
+                if isinstance(data, dict) and "exists" in data:
+                    return True, f"/api/db/status ok: exists={data.get('exists')} size={data.get('size')}"
+        except urllib.error.URLError:
+            time.sleep(0.5)
+        except Exception:
+            time.sleep(0.5)
+    return False, "Timed out waiting for /api/db/status"
+
+
+def smoke_test_api_startup(results: CheckResults, repo: Path, port: int, timeout_s: int) -> None:
+    env = os.environ.copy()
+    # Keep startup deterministic and fast for verification.
+    env["VERIFY_MODELS_ON_START"] = "0"
+    env["AUTO_VERIFY_ONLINE"] = "0"
+    env["AUTO_DOWNLOAD_MODELS"] = env.get("AUTO_DOWNLOAD_MODELS", "0")
+
+    cmd = [
+        sys.executable,
+        "-m",
+        "uvicorn",
+        "app:app",
+        "--host",
+        "127.0.0.1",
+        "--port",
+        str(port),
+    ]
+    proc = subprocess.Popen(
+        cmd,
+        cwd=str(repo),
+        stdout=subprocess.PIPE,
+        stderr=subprocess.STDOUT,
+        text=True,
+    )
+
+    try:
+        ok, detail = _poll_db_status(f"http://127.0.0.1:{port}", timeout_s=timeout_s)
+        if ok:
+            results.pass_(f"API startup smoke test passed ({detail})")
+        else:
+            # Pull a short tail to help debug startup failures.
+            tail = ""
+            try:
+                if proc.stdout:
+                    out = proc.stdout.read() or ""
+                    tail = out[-1200:]
+            except Exception:
+                pass
+            if tail.strip():
+                results.fail_(f"API smoke test failed: {detail}\n--- uvicorn tail ---\n{tail}")
+            else:
+                results.fail_(f"API smoke test failed: {detail}")
+    finally:
+        try:
+            proc.terminate()
+            proc.wait(timeout=8)
+        except Exception:
+            try:
+                proc.kill()
+            except Exception:
+                pass
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Verify fresh SailingMedAdvisor install")
+    parser.add_argument("--repo", default=str(_repo_root()), help="Repository root path")
+    parser.add_argument("--skip-smoke", action="store_true", help="Skip uvicorn startup smoke test")
+    parser.add_argument("--port", type=int, default=5077, help="Port for smoke test server")
+    parser.add_argument("--timeout", type=int, default=40, help="Smoke test timeout in seconds")
+    args = parser.parse_args()
+
+    repo = Path(args.repo).resolve()
+    results = CheckResults()
+    print(f"[info] Verifying repository: {repo}")
+
+    check_python_version(results)
+    check_required_files(results, repo)
+    check_imports(results)
+    db_path = _ensure_runtime_db(repo, results)
+    check_db_schema(results, db_path)
+    check_default_tree_json(results, repo)
+    if not args.skip_smoke:
+        smoke_test_api_startup(results, repo, port=args.port, timeout_s=args.timeout)
+
+    return results.summary()
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

static/data/triage_samples.json

@@ -0,0 +1,602 @@
+[
+  {
+    "id": 1,
+    "situation": "Open Femur Fracture",
+    "chat_text": "One of the crew fell from the mast and their thigh is completely deformed with a bone sticking out. They are barely awake and breathing very fast. There is a lot of blood and they look incredibly pale.",
+    "responsive": "Drowsy",
+    "breathing": "Rapid/Shallow",
+    "pain": "10/10",
+    "main_problem": "Heavy bleeding/deformed thigh",
+    "temp": "36.2°C",
+    "circulation": "Pale, weak pulse, BP 90/60",
+    "cause": "Fall from mast during squall"
+  },
+  {
+    "id": 2,
+    "situation": "Tension Pneumothorax",
+    "chat_text": "He got hit hard in the chest by the boom and now he can't catch his breath. He’s struggling to breathe, his neck veins are bulging out, and his lips are turning blue.",
+    "responsive": "Alert/Anxious",
+    "breathing": "Struggling",
+    "pain": "8/10",
+    "main_problem": "One side of chest not moving",
+    "temp": "37.0°C",
+    "circulation": "Distended neck veins, low BP",
+    "cause": "Blown into shroud by boom"
+  },
+  {
+    "id": 3,
+    "situation": "Severe Scalp Laceration",
+    "chat_text": "A heavy block hit her in the head and blood is literally pulsing out in a spray. She’s awake but there’s a massive amount of bright red blood everywhere.",
+    "responsive": "Alert",
+    "breathing": "Normal",
+    "pain": "7/10",
+    "main_problem": "Arterial spurting from head",
+    "temp": "36.8°C",
+    "circulation": "Rapid pulse, BP normal",
+    "cause": "Hit by mainsheet block"
+  },
+  {
+    "id": 4,
+    "situation": "Traumatic Amputation",
+    "chat_text": "Her hand got sucked into the electric winch. Three fingers are gone and the stumps are bleeding uncontrollably. She’s passed out and her skin is cold and white.",
+    "responsive": "Unconscious",
+    "breathing": "Labored",
+    "pain": "N/A",
+    "main_problem": "Missing fingers (R hand)",
+    "temp": "35.5°C",
+    "circulation": "Massive hemorrhage, shock",
+    "cause": "Hand caught in electric winch"
+  },
+  {
+    "id": 5,
+    "situation": "Internal Hemorrhage",
+    "chat_text": "He was thrown against the cockpit table during a roll. His stomach is becoming very hard and bloated, he’s breathing fast, and he looks like he’s going into shock.",
+    "responsive": "Drowsy",
+    "breathing": "Fast",
+    "pain": "6/10",
+    "main_problem": "Distended/rigid abdomen",
+    "temp": "36.0°C",
+    "circulation": "Cold/clammy, BP dropping",
+    "cause": "Thrown against cockpit table"
+  },
+  {
+    "id": 6,
+    "situation": "Crush Injury (Foot)",
+    "chat_text": "An anchor fell on his foot. The pain is a 9 out of 10, his foot is turning blue and cold, and I can't find a pulse anywhere on his ankle.",
+    "responsive": "Normal",
+    "breathing": "Normal",
+    "pain": "9/10",
+    "main_problem": "Swollen, blue, no pulse in foot",
+    "temp": "37.2°C",
+    "circulation": "Good BP, peripheral blockage",
+    "cause": "Heavy anchor dropped on foot"
+  },
+  {
+    "id": 7,
+    "situation": "Flail Chest",
+    "chat_text": "He slammed his chest into a winch. Part of his ribcage is moving inward when he breathes in and outward when he breathes out. He’s in a lot of pain and struggling for air.",
+    "responsive": "Alert",
+    "breathing": "Very painful",
+    "pain": "9/10",
+    "main_problem": "Paradoxical chest movement",
+    "temp": "37.1°C",
+    "circulation": "Fast pulse",
+    "cause": "Chest slammed into winch"
+  },
+  {
+    "id": 8,
+    "situation": "Concussion/TBI",
+    "chat_text": "She hit her head on the deck. She’s very confused, keep throwing up, and one of her pupils is much larger than the other.",
+    "responsive": "Confused",
+    "breathing": "Normal",
+    "pain": "5/10",
+    "main_problem": "Repeated vomiting, pupil dilation",
+    "temp": "36.9°C",
+    "circulation": "BP 140/90 (Rising)",
+    "cause": "Slip on wet deck, head hit GRP"
+  },
+  {
+    "id": 9,
+    "situation": "Dislocated Shoulder",
+    "chat_text": "He reached for the rail during a big wave and his shoulder popped out. It looks completely misshapen and he can't move his arm at all.",
+    "responsive": "Alert",
+    "breathing": "Normal",
+    "pain": "8/10",
+    "main_problem": "Visual deformity, arm locked",
+    "temp": "37.0°C",
+    "circulation": "Normal",
+    "cause": "Reaching for rail during roll"
+  },
+  {
+    "id": 10,
+    "situation": "Impaled Object",
+    "chat_text": "The spinnaker pole shattered and a long, sharp piece of carbon fiber is stuck deep in his thigh. It’s not bleeding much but the object is still in there.",
+    "responsive": "Alert",
+    "breathing": "Normal",
+    "pain": "7/10",
+    "main_problem": "Shard of carbon fiber in thigh",
+    "temp": "36.8°C",
+    "circulation": "Steady, bleeding controlled",
+    "cause": "Shattered spinnaker pole"
+  },
+  {
+    "id": 11,
+    "situation": "Severe Hypothermia",
+    "chat_text": "We pulled him out of the water after 30 minutes. He’s stopped shivering, he’s mumbles when he speaks, and his body feels ice cold and stiff.",
+    "responsive": "Mumbling",
+    "breathing": "Very slow",
+    "pain": "None",
+    "main_problem": "Shivering stopped, rigid",
+    "temp": "31.0°C",
+    "circulation": "Barely palpable pulse",
+    "cause": "30 mins in 15°C water (MOB)"
+  },
+  {
+    "id": 12,
+    "situation": "Heat Stroke",
+    "chat_text": "He’s been working in the engine room and now he’s unconscious. His skin is red and bone dry, he’s having a seizure, and he feels like he's burning up.",
+    "responsive": "Unconscious",
+    "breathing": "Snoring",
+    "pain": "N/A",
+    "main_problem": "Hot, dry skin; seizures",
+    "temp": "41.1°C",
+    "circulation": "Tachycardia (140 bpm)",
+    "cause": "Engine room repair in tropics"
+  },
+  {
+    "id": 13,
+    "situation": "Saltwater Aspiration",
+    "chat_text": "She swallowed a lot of water when she fell overboard. She’s coughing constantly, gasping for air, and her lips look blue.",
+    "responsive": "Alert",
+    "breathing": "Gasping",
+    "pain": "6/10",
+    "main_problem": "Persistent coughing, blue lips",
+    "temp": "37.5°C",
+    "circulation": "Rapid pulse",
+    "cause": "Swallowed water during MOB"
+  },
+  {
+    "id": 14,
+    "situation": "Severe Dehydration",
+    "chat_text": "He’s been seasick for days and hasn't peed in 24 hours. His eyes are sunken in, he’s very weak, and he has a slight fever.",
+    "responsive": "Lethargic",
+    "breathing": "Normal",
+    "pain": "4/10",
+    "main_problem": "No urine for 24h, sunken eyes",
+    "temp": "38.2°C",
+    "circulation": "Weak pulse, very low BP",
+    "cause": "Chronic seasickness/vomiting"
+  },
+  {
+    "id": 15,
+    "situation": "2nd Degree Sunburn",
+    "chat_text": "He fell asleep on deck and has a massive sunburn. Almost half his body is covered in large blisters and he’s shaking even though he has a fever.",
+    "responsive": "Alert",
+    "breathing": "Normal",
+    "pain": "8/10",
+    "main_problem": "Blistering over 40% of body",
+    "temp": "38.5°C",
+    "circulation": "Shivers, mild hypotension",
+    "cause": "Fallen asleep on deck in doldrums"
+  },
+  {
+    "id": 16,
+    "situation": "Immersion Foot",
+    "chat_text": "His boots have been wet for four days straight. His feet are completely white, numb, and the skin is starting to peel off in chunks.",
+    "responsive": "Alert",
+    "breathing": "Normal",
+    "pain": "6/10",
+    "main_problem": "Feet white, numb, peeling",
+    "temp": "36.5°C",
+    "circulation": "Poor capillary refill",
+    "cause": "4 days in wet boots on watch"
+  },
+  {
+    "id": 17,
+    "situation": "Severe Hyponatremia",
+    "chat_text": "He’s been drinking gallons of water but eating no salt. Now he’s staggering around like he’s drunk and his speech is totally slurred.",
+    "responsive": "Confused",
+    "breathing": "Normal",
+    "pain": "2/10",
+    "main_problem": "Slurred speech, staggering",
+    "temp": "37.0°C",
+    "circulation": "Normal BP",
+    "cause": "Over-drinking water, no salt"
+  },
+  {
+    "id": 18,
+    "situation": "Deep Frostbite",
+    "chat_text": "We’ve been handling ice-cold lines and his fingers have turned hard and gray-black. He can't feel them at all.",
+    "responsive": "Alert",
+    "breathing": "Normal",
+    "pain": "3/10",
+    "main_problem": "Fingers hard, black/gray",
+    "temp": "35.8°C",
+    "circulation": "Poor circulation to hand",
+    "cause": "Hand handling icy lines"
+  },
+  {
+    "id": 19,
+    "situation": "Nitrogen Narcosis",
+    "chat_text": "He came up too fast after checking the hull. He’s acting very strangely, giggling, and seems totally confused about where he is.",
+    "responsive": "Giggling",
+    "breathing": "Fast",
+    "pain": "None",
+    "main_problem": "Irrational behavior/confusion",
+    "temp": "36.7°C",
+    "circulation": "Normal",
+    "cause": "Rapid ascent from hull check"
+  },
+  {
+    "id": 20,
+    "situation": "Lightning Strike",
+    "chat_text": "The boat was hit by lightning. He’s unconscious and not breathing. I can't find a pulse and there are weird burn marks on his skin.",
+    "responsive": "Unconscious",
+    "breathing": "Arrested",
+    "pain": "N/A",
+    "main_problem": "Cardiac arrest, \"feather\" burns",
+    "temp": "36.4°C",
+    "circulation": "No pulse (requires CPR)",
+    "cause": "Direct hit on mast during storm"
+  },
+  {
+    "id": 21,
+    "situation": "Acute Appendicitis",
+    "chat_text": "She has a 9 out of 10 pain in her lower right stomach. If I press down and let go, the pain is even worse. She also has a fever.",
+    "responsive": "Alert",
+    "breathing": "Guarded",
+    "pain": "9/10",
+    "main_problem": "Rebound tenderness lower R",
+    "temp": "38.9°C",
+    "circulation": "High BP from pain",
+    "cause": "Random/Bacterial"
+  },
+  {
+    "id": 22,
+    "situation": "Sepsis (Infected Wound)",
+    "chat_text": "An old coral cut on his leg has red streaks coming out of it. He’s shaking with chills, has a high fever, and his blood pressure seems very low.",
+    "responsive": "Drowsy",
+    "breathing": "Rapid",
+    "pain": "5/10",
+    "main_problem": "Red streaks, shaking chills",
+    "temp": "39.5°C",
+    "circulation": "BP 80/50 (Septic shock)",
+    "cause": "Uncleaned coral cut"
+  },
+  {
+    "id": 23,
+    "situation": "Anaphylaxis",
+    "chat_text": "He got bit by an insect and now his throat is swelling up. He’s wheezing, covered in hives, and looks like he’s about to pass out.",
+    "responsive": "Drowsy",
+    "breathing": "Wheezing",
+    "pain": "4/10",
+    "main_problem": "Swollen throat, hives",
+    "temp": "37.2°C",
+    "circulation": "BP dropping rapidly",
+    "cause": "Unknown insect bite/food"
+  },
+  {
+    "id": 24,
+    "situation": "Myocardial Infarction",
+    "chat_text": "He says it feels like an elephant is sitting on his chest. The pain is going down his left arm, he’s sweating, and his pulse feels irregular.",
+    "responsive": "Alert",
+    "breathing": "Shortness",
+    "pain": "9/10",
+    "main_problem": "Crushing chest pain/Left arm",
+    "temp": "37.0°C",
+    "circulation": "Irregular pulse, sweating",
+    "cause": "Clogged artery (Heart Attack)"
+  },
+  {
+    "id": 25,
+    "situation": "Diabetic Ketoacidosis",
+    "chat_text": "He’s very confused and his breath smells sweet, almost like fruit. He’s breathing very deeply and fast and says he’s incredibly thirsty.",
+    "responsive": "Confused",
+    "breathing": "Deep/Fast",
+    "pain": "3/10",
+    "main_problem": "Fruity breath, extreme thirst",
+    "temp": "37.4°C",
+    "circulation": "Weak pulse",
+    "cause": "Insulin pump failure"
+  },
+  {
+    "id": 26,
+    "situation": "Perforated Ulcer",
+    "chat_text": "He has a sudden, agonizing pain in his stomach. His belly feels as hard as a board and he’s pale and sweating.",
+    "responsive": "Alert",
+    "breathing": "Shallow",
+    "pain": "10/10",
+    "main_problem": "Sudden, board-like abdomen",
+    "temp": "37.8°C",
+    "circulation": "Shock signs",
+    "cause": "Long-term NSAID use (Advil)"
+  },
+  {
+    "id": 27,
+    "situation": "Kidney Stones",
+    "chat_text": "He’s in 10 out of 10 pain in his side and back. He’s pacing around because he can't get comfortable and there is blood in his urine.",
+    "responsive": "Alert",
+    "breathing": "Fast",
+    "pain": "10/10",
+    "main_problem": "Agonizing flank pain/blood",
+    "temp": "37.3°C",
+    "circulation": "Pacing around, high BP",
+    "cause": "Dehydration"
+  },
+  {
+    "id": 28,
+    "situation": "Acute Asthma Attack",
+    "chat_text": "She’s having a massive asthma attack. Her inhaler isn't working and I can't hear any air moving in her chest at all. Her lips are turning blue.",
+    "responsive": "Alert",
+    "breathing": "Silent",
+    "pain": "7/10",
+    "main_problem": "No air movement (Silent chest)",
+    "temp": "37.0°C",
+    "circulation": "Tachycardia",
+    "cause": "Mold in cabin/ventilation"
+  },
+  {
+    "id": 29,
+    "situation": "Ischemic Stroke",
+    "chat_text": "One side of his face is drooping and he can't move his right arm or leg. He’s awake but his blood pressure is extremely high.",
+    "responsive": "Alert",
+    "breathing": "Normal",
+    "pain": "2/10",
+    "main_problem": "Facial droop, R-side paralysis",
+    "temp": "36.8°C",
+    "circulation": "BP 180/110",
+    "cause": "Blood clot"
+  },
+  {
+    "id": 30,
+    "situation": "Status Epilepticus",
+    "chat_text": "He’s been having a violent seizure for over five minutes straight and it won't stop. His breathing is irregular and he’s turning red.",
+    "responsive": "Seizing",
+    "breathing": "Irregular",
+    "pain": "N/A",
+    "main_problem": "Continuous convulsions >5min",
+    "temp": "38.0°C",
+    "circulation": "Rapid pulse",
+    "cause": "Missed meds/High stress"
+  },
+  {
+    "id": 31,
+    "situation": "Carbon Monoxide",
+    "chat_text": "Everyone in the cabin is lethargic with a headache. One person has bright red skin and is breathing very slowly. We suspect an exhaust leak.",
+    "responsive": "Lethargic",
+    "breathing": "Slow",
+    "pain": "5/10",
+    "main_problem": "Cherry-red skin, headache",
+    "temp": "36.6°C",
+    "circulation": "Normal",
+    "cause": "Leaking heater/engine exhaust"
+  },
+  {
+    "id": 32,
+    "situation": "Ciguatera Poisoning",
+    "chat_text": "We ate a barracuda and now he’s acting weird. He says cold water feels hot to him, and his heart rate has dropped to 40 beats per minute.",
+    "responsive": "Alert",
+    "breathing": "Normal",
+    "pain": "6/10",
+    "main_problem": "Hot feels cold, cold feels hot",
+    "temp": "37.2°C",
+    "circulation": "Bradycardia (Slow pulse)",
+    "cause": "Eating reef fish (Barracuda)"
+  },
+  {
+    "id": 33,
+    "situation": "Box Jellyfish Sting",
+    "chat_text": "He was stung by a jellyfish and went into cardiac arrest almost immediately. There are massive red welts all over his chest and legs.",
+    "responsive": "Unconscious",
+    "breathing": "Arrested",
+    "pain": "10/10",
+    "main_problem": "Massive welts, heart failure",
+    "temp": "37.4°C",
+    "circulation": "Cardiac arrest signs",
+    "cause": "Swimming in doldrums"
+  },
+  {
+    "id": 34,
+    "situation": "Cellulitis",
+    "chat_text": "A small cut on her leg has turned into a massive, hot, red swelling that is spreading quickly. She has a high fever.",
+    "responsive": "Alert",
+    "breathing": "Normal",
+    "pain": "7/10",
+    "main_problem": "Leg hot, red, and swollen",
+    "temp": "39.0°C",
+    "circulation": "Fast pulse",
+    "cause": "Infected shaving cut"
+  },
+  {
+    "id": 35,
+    "situation": "Chemical Burn (Eyes)",
+    "chat_text": "Battery acid splashed directly into his eyes. He can't open them, he’s in 10 out of 10 pain, and his eyes look hazy and white.",
+    "responsive": "Alert",
+    "breathing": "Normal",
+    "pain": "10/10",
+    "main_problem": "Cannot open eyes, white haze",
+    "temp": "36.8°C",
+    "circulation": "Normal",
+    "cause": "Battery acid splash"
+  },
+  {
+    "id": 36,
+    "situation": "Aspiration Pneumonia",
+    "chat_text": "He’s been sick since he inhaled some vomit. He’s coughing up green gunk, has a high fever, and is struggling to breathe.",
+    "responsive": "Alert",
+    "breathing": "Labored",
+    "pain": "5/10",
+    "main_problem": "Productive cough (green)",
+    "temp": "39.2°C",
+    "circulation": "Low oxygen saturation",
+    "cause": "Vomit inhaled during storm"
+  },
+  {
+    "id": 37,
+    "situation": "Acute Urinary Retention",
+    "chat_text": "He’s in extreme pain because he hasn't been able to pee for hours. His lower stomach is hard and bulging.",
+    "responsive": "Alert",
+    "breathing": "Normal",
+    "pain": "9/10",
+    "main_problem": "Bladder distended, cannot pee",
+    "temp": "37.1°C",
+    "circulation": "High BP",
+    "cause": "Enlarged prostate"
+  },
+  {
+    "id": 38,
+    "situation": "Dental Abscess",
+    "chat_text": "His tooth is broken and now his entire face is swollen. His eye is starting to swell shut and he has a high fever.",
+    "responsive": "Alert",
+    "breathing": "Normal",
+    "pain": "8/10",
+    "main_problem": "Face swollen, eye closing",
+    "temp": "38.6°C",
+    "circulation": "Normal",
+    "cause": "Cracked tooth"
+  },
+  {
+    "id": 39,
+    "situation": "Pulmonary Embolism",
+    "chat_text": "He suddenly got a sharp pain in his chest and can't breathe. His lips are blue and he’s coughing up a little bit of blood.",
+    "responsive": "Alert",
+    "breathing": "Sharp pain",
+    "pain": "9/10",
+    "main_problem": "Sudden SOB, coughing blood",
+    "temp": "37.4°C",
+    "circulation": "Cyanosis (Blue lips)",
+    "cause": "DVT from long sitting/watch"
+  },
+  {
+    "id": 40,
+    "situation": "Bowel Obstruction",
+    "chat_text": "He hasn't been able to go to the bathroom or pass gas. Now he is actually vomiting stuff that smells like a bowel movement.",
+    "responsive": "Alert",
+    "breathing": "Normal",
+    "pain": "7/10",
+    "main_problem": "Fecal vomiting, no gas",
+    "temp": "37.6°C",
+    "circulation": "Low BP, dehydrated",
+    "cause": "Previous surgery/Adhesions"
+  },
+  {
+    "id": 41,
+    "situation": "Dengue Hemorrhagic",
+    "chat_text": "He has a high fever and his gums are bleeding. He’s covered in dark, blackish bruises and looks very weak.",
+    "responsive": "Drowsy",
+    "breathing": "Normal",
+    "pain": "7/10",
+    "main_problem": "Bleeding gums, black bruises",
+    "temp": "39.8°C",
+    "circulation": "Low BP (Shock)",
+    "cause": "Mosquito bite in Sumatra"
+  },
+  {
+    "id": 42,
+    "situation": "Malaria (Falciparum)",
+    "chat_text": "He’s totally confused and has a 40.5°C fever. His eyes look yellow and he’s breathing very fast.",
+    "responsive": "Confused",
+    "breathing": "Rapid",
+    "pain": "6/10",
+    "main_problem": "Cycling high fever, yellow eyes",
+    "temp": "40.5°C",
+    "circulation": "Tachycardia",
+    "cause": "Mosquito bite"
+  },
+  {
+    "id": 43,
+    "situation": "Giardia (Severe)",
+    "chat_text": "He has constant, explosive diarrhea that smells like sulfur. He’s becoming very dehydrated and lightheaded.",
+    "responsive": "Alert",
+    "breathing": "Normal",
+    "pain": "5/10",
+    "main_problem": "Explosive sulfurous diarrhea",
+    "temp": "37.5°C",
+    "circulation": "Orthostatic hypotension",
+    "cause": "Bad water tank hygiene"
+  },
+  {
+    "id": 44,
+    "situation": "Corneal Ulcer",
+    "chat_text": "His eye is bright red and filled with pus. He says it feels like there is sand in it and he can't look at any light.",
+    "responsive": "Alert",
+    "breathing": "Normal",
+    "pain": "9/10",
+    "main_problem": "Constant sand sensation, pus",
+    "temp": "36.8°C",
+    "circulation": "Normal",
+    "cause": "Contact lens left in too long"
+  },
+  {
+    "id": 45,
+    "situation": "Orchitis",
+    "chat_text": "He has sudden, 9 out of 10 pain in his groin. One side is swollen to the size of a grapefruit and he has a fever.",
+    "responsive": "Alert",
+    "breathing": "Normal",
+    "pain": "9/10",
+    "main_problem": "Scrotal swelling (grapefruit)",
+    "temp": "38.8°C",
+    "circulation": "Pain-induced high BP",
+    "cause": "Bacterial/STI"
+  },
+  {
+    "id": 46,
+    "situation": "Meningitis",
+    "chat_text": "He has a very high fever and a splitting headache. His neck is so stiff he can't touch his chin to his chest and light hurts his eyes.",
+    "responsive": "Lethargic",
+    "breathing": "Normal",
+    "pain": "9/10",
+    "main_problem": "Stiff neck, light sensitivity",
+    "temp": "40.1°C",
+    "circulation": "BP 100/60",
+    "cause": "Viral/Bacterial"
+  },
+  {
+    "id": 47,
+    "situation": "Staph (MRSA)",
+    "chat_text": "He has a huge, painful, pus-filled lump that looks like a spider bite. It’s hot to the touch and he has a fever.",
+    "responsive": "Alert",
+    "breathing": "Normal",
+    "pain": "6/10",
+    "main_problem": "\"Spider bite\" look, pus-filled",
+    "temp": "38.2°C",
+    "circulation": "Normal",
+    "cause": "Shared towels/gym gear"
+  },
+  {
+    "id": 48,
+    "situation": "Leptospirosis",
+    "chat_text": "His eyes are bright red, his skin looks yellow, and his calves are in a lot of pain. He has a high fever and low blood pressure.",
+    "responsive": "Alert",
+    "breathing": "Normal",
+    "pain": "8/10",
+    "main_problem": "Calf pain, jaundice, red eyes",
+    "temp": "39.4°C",
+    "circulation": "Low BP",
+    "cause": "Rat urine in bilge water"
+  },
+  {
+    "id": 49,
+    "situation": "Sea Urchin Granuloma",
+    "chat_text": "He stepped on a sea urchin and has over 20 spines stuck in his foot. His joints are starting to feel stiff and lock up.",
+    "responsive": "Alert",
+    "breathing": "Normal",
+    "pain": "4/10",
+    "main_problem": "20+ spines, joints locking",
+    "temp": "37.2°C",
+    "circulation": "Normal",
+    "cause": "Stepped on urchin in surf"
+  },
+  {
+    "id": 50,
+    "situation": "Ectopic Pregnancy",
+    "chat_text": "She has a sudden, ripping pain in her lower stomach and just fainted. She is very pale, cold, and her blood pressure is very low.",
+    "responsive": "Alert",
+    "breathing": "Fast",
+    "pain": "10/10",
+    "main_problem": "Ripping pelvic pain, fainting",
+    "temp": "36.5°C",
+    "circulation": "BP 85/40 (Internal bleed)",
+    "cause": "Ruptured fallopian tube"
+  }
+]

static/js/equipment.js

@@ -0,0 +1,1315 @@
+/* =============================================================================
+ * Author: Rick Escher
+ * Project: SailingMedAdvisor
+ * Context: Google HAI-DEF Framework
+ * Models: Google MedGemmas
+ * Program: Kaggle Impact Challenge
+ * ========================================================================== */
+/*
+File: static/js/equipment.js
+Author notes: Equipment and medical supplies management.
+
+Key Responsibilities:
+- Medical equipment inventory (durable goods: AED, blood pressure cuff, etc.)
+- Consumables tracking (bandages, gauze, gloves, syringes, etc.)
+- Import/export functionality for equipment lists (TSV format)
+- Resource availability trackiang (in-stock vs unavailable)
+- Equipment classification and categorization
+
+Equipment Classification:
+- 'durable': Medical equipment (reusable, tracked equipment)
+- 'consumable': Single-use supplies (tracked by quantity)
+- 'medication': Medicines (redirects to pharmacy module)
+
+Data Flow:
+- Equipment: /api/data/tools (tools.json)
+- Medications: /api/data/inventory (inventory.json)
+- Import/Export: TSV files for bulk updates
+
+Integration Points:
+- pharmacy.js: Medication management
+- main.js: Tab navigation, initial data load
+*/
+
+// Utility function imports from utils.js (with fallbacks)
+const workspaceHeaders = (window.Utils && window.Utils.workspaceHeaders) ? window.Utils.workspaceHeaders : (extra = {}) => extra;
+const fetchJson = (window.Utils && window.Utils.fetchJson) ? window.Utils.fetchJson : async (url, options = {}) => {
+    const res = await fetch(url, { credentials: 'same-origin', ...options });
+    const data = await res.json().catch(() => ({}));
+    if (!res.ok || data.error) throw new Error(data.error || `Status ${res.status}`);
+    return data;
+};
+const eqEscapeHtml = (window.Utils && window.Utils.escapeHtml) ? window.Utils.escapeHtml : (str) => str;
+
+// ============================================================================
+// STATE MANAGEMENT
+// ============================================================================
+
+let equipmentCache = [];              // Cached equipment/consumables from server
+const equipmentSaveTimers = {};       // Debounce timers for auto-save
+
+const eqWorkspaceHeaders = workspaceHeaders;
+
+const DEFAULT_EQUIPMENT_CATEGORIES = [
+    'Diagnostics & monitoring',
+    'Instruments & tools',
+    'Airway & breathing',
+    'Splints & supports',
+    'Eye care',
+    'Dental',
+    'PPE',
+    'Survival & utility',
+    'Other'
+];
+const DEFAULT_CONSUMABLE_CATEGORIES = [
+    'Wound care & dressings',
+    'Burn care',
+    'Antiseptics & hygiene',
+    'Irrigation & syringes',
+    'Splints & supports',
+    'PPE',
+    'Survival & utility',
+    'Other'
+];
+
+const EQ_TIER_OPTIONS = [
+    { value: '', label: 'Select...' },
+    { value: 'Tier 1', label: 'Tier 1 — Emergency & Surgical' },
+    { value: 'Tier 2', label: 'Tier 2 — Stabilization & Acute' },
+    { value: 'Tier 3', label: 'Tier 3 — Supportive & Maintenance' },
+];
+
+const EQ_TIER_SUBCATEGORIES = {
+    'Tier 1': [
+        'Local Anesthesia',
+        'Respiratory/Anaphylaxis',
+        'Critical Antibiotics (Systemic)',
+        'Critical Antibiotics (Ophthalmic)',
+        'Emergency Steroids',
+    ],
+    'Tier 2': [
+        'Analgesics (Moderate/Severe Pain)',
+        'NSAIDs (Mild/Moderate Pain)',
+        'Topical Antiseptics/Antibiotics',
+        'Standard Antibiotics/Antivirals',
+        'Antihistamines/Steroid Creams',
+    ],
+    'Tier 3': [
+        'Gastrointestinal (Nausea/Diarrhea/Reflux)',
+        'Hydration/Electrolytes',
+        'Dermatological (Fungal/Parasitic)',
+        'Diagnostic/Maintenance',
+        'Chronic/Behavioral',
+    ],
+};
+
+/**
+ * eqBuildTierOptions: function-level behavior note for maintainers.
+ * Keep this block synchronized with implementation changes.
+ */
+function eqBuildTierOptions(selected = '') {
+    return EQ_TIER_OPTIONS.map((opt) => `<option value="${eqEscapeHtml(opt.value)}" ${opt.value === selected ? 'selected' : ''}>${eqEscapeHtml(opt.label)}</option>`).join('');
+}
+
+/**
+ * eqBuildTierSubcategoryOptions: function-level behavior note for maintainers.
+ * Keep this block synchronized with implementation changes.
+ */
+function eqBuildTierSubcategoryOptions(tier = '', selected = '') {
+    const options = [{ value: '', label: 'Select...' }];
+    const list = EQ_TIER_SUBCATEGORIES[tier] || [];
+    list.forEach((entry) => options.push({ value: entry, label: entry }));
+    return options.map((opt) => `<option value="${eqEscapeHtml(opt.value)}" ${opt.value === selected ? 'selected' : ''}>${eqEscapeHtml(opt.label)}</option>`).join('');
+}
+
+/**
+ * handleEquipmentTierChange: function-level behavior note for maintainers.
+ * Keep this block synchronized with implementation changes.
+ */
+function handleEquipmentTierChange(itemId) {
+    const tierEl = document.getElementById(`eq-tier-${itemId}`);
+    const catEl = document.getElementById(`eq-tiercat-${itemId}`);
+    if (!tierEl || !catEl) return;
+    const tierVal = tierEl.value || '';
+    const current = catEl.value || '';
+    catEl.innerHTML = eqBuildTierSubcategoryOptions(tierVal, current);
+    if (current && !(EQ_TIER_SUBCATEGORIES[tierVal] || []).includes(current)) {
+        catEl.value = '';
+    }
+    scheduleSaveEquipment(itemId);
+}
+
+/**
+ * initTierFormControls: function-level behavior note for maintainers.
+ * Keep this block synchronized with implementation changes.
+ */
+function initTierFormControls() {
+    const pairs = [
+        { tier: 'eq-new-tier', cat: 'eq-new-tiercat' },
+        { tier: 'cons-new-tier', cat: 'cons-new-tiercat' },
+        { tier: 'med-new-tier', cat: 'med-new-tiercat' },
+    ];
+    pairs.forEach(({ tier, cat }) => {
+        const tierEl = document.getElementById(tier);
+        const catEl = document.getElementById(cat);
+        if (!tierEl || !catEl) return;
+        tierEl.innerHTML = eqBuildTierOptions(tierEl.value || '');
+        catEl.innerHTML = eqBuildTierSubcategoryOptions(tierEl.value || '', catEl.value || '');
+        if (!tierEl.dataset.bound) {
+            tierEl.dataset.bound = 'true';
+            tierEl.addEventListener('change', () => {
+                catEl.innerHTML = eqBuildTierSubcategoryOptions(tierEl.value || '', '');
+            });
+        }
+    });
+}
+
+window.refreshEquipmentCategoriesFromSettings = function () {
+    if (equipmentCache.length) {
+        renderEquipment(equipmentCache);
+    }
+};
+
+/**
+ * Update section header count badges.
+ * 
+ * Displays item counts in section headers (e.g., "Medical Equipment (12)").
+ * 
+ * @param {string} id - Element ID of the count badge
+ * @param {number} count - Number of items to display
+ */
+function updateSectionCount(id, count) {
+    const el = document.getElementById(id);
+    if (el) {
+        el.textContent = `(${count})`;
+    }
+}
+
+/**
+ * Normalize equipment item with default values.
+ * 
+ * Ensures all expected fields exist with appropriate defaults.
+ * Similar to pharmacy's ensurePharmacyDefaults but for equipment/consumables.
+ * 
+ * Equipment Structure:
+ * ```javascript
+ * {
+ *   id: string,                    // Unique ID (eq-timestamp-random)
+ *   name: string,                  // Equipment/consumable name
+ *   category: string,              // Category for grouping
+ *   type: string,                  // 'durable' | 'consumable' | 'medication'
+ *   storageLocation: string,       // Where it's stored
+ *   subLocation: string,           // Specific location details
+ *   status: string,                // 'In Stock' | 'Out of Stock' | 'Maintenance'
+ *   expiryDate: string,            // ISO date for consumables
+ *   lastInspection: string,        // ISO date of last inspection
+ *   batteryType: string,           // For powered equipment
+ *   batteryStatus: string,         // Battery condition
+ *   calibrationDue: string,        // ISO date for next calibration
+ *   totalQty: string,              // Current quantity
+ *   minPar: string,                // Minimum stock level
+ *   supplier: string,              // Supplier name
+ *   parentId: string,              // For nested equipment (e.g., kit contents)
+ *   requiresPower: boolean,        // Needs batteries/power
+ *   notes: string,                 // Additional information
+ *   excludeFromResources: boolean  // Hide from public resource lists
+ * }
+ * ```
+ * 
+ * @param {Object} item - Raw equipment data
+ * @returns {Object} Normalized equipment object with all fields
+ */
+function ensureEquipmentDefaults(item) {
+    return {
+        id: item.id || `eq-${Date.now()}-${Math.floor(Math.random() * 1000)}`,
+        name: item.name || '',
+        category: item.category || '',
+        type: item.type || 'durable', // durable | consumable
+        storageLocation: item.storageLocation || '',
+        subLocation: item.subLocation || '',
+        status: item.status || 'In Stock',
+        expiryDate: item.expiryDate || '',
+        lastInspection: item.lastInspection || '',
+        batteryType: item.batteryType || '',
+        batteryStatus: item.batteryStatus || '',
+        calibrationDue: item.calibrationDue || '',
+        totalQty: item.totalQty || '',
+        minPar: item.minPar || '',
+        supplier: item.supplier || '',
+        parentId: item.parentId || '',
+        requiresPower: item.requiresPower || false,
+        priorityTier: item.priorityTier || '',
+        tierCategory: item.tierCategory || '',
+        notes: item.notes || '',
+        excludeFromResources: Boolean(item.excludeFromResources),
+    };
+}
+
+/**
+ * Load and render all equipment from server.
+ * 
+ * Loading Process:
+ * 1. Fetches from /api/data/tools
+ * 2. Normalizes all items
+ * 3. Classifies into equipment/consumables/medications
+ * 4. Renders to appropriate lists
+ * 5. Updates section count badges
+ * 
+ * @param {string} expandId - Optional ID of item to auto-expand after render
+ */
+async function loadEquipment(expandId = null) {
+    const list = document.getElementById('equipment-list');
+    if (!list) return;
+    list.innerHTML = '';
+    try {
+        if (typeof refreshEquipmentCategoryOptions === 'function') {
+            refreshEquipmentCategoryOptions();
+        }
+        initTierFormControls();
+        const data = await fetchJson('/api/data/tools');
+        equipmentCache = (Array.isArray(data) ? data : []).map(ensureEquipmentDefaults);
+        renderEquipment(equipmentCache, expandId);
+    } catch (err) {
+        updateSectionCount('equipment-count', 0);
+        updateSectionCount('consumables-count', 0);
+        const errHtml = `<div style="color:red; padding:12px;">Error loading equipment: ${err.message}</div>`;
+        const equipmentList = document.getElementById('equipment-list');
+        const consumablesList = document.getElementById('consumables-list');
+        if (equipmentList) equipmentList.innerHTML = errHtml;
+        if (consumablesList) consumablesList.innerHTML = errHtml;
+        list.innerHTML = errHtml;
+    }
+}
+
+/**
+ * Classify equipment into category buckets.
+ * 
+ * Classification Rules:
+ * 1. type='medication' → 'medication'
+ * 2. type='consumable' → 'consumable'
+ * 3. Otherwise → 'equipment' (durable goods)
+ * 
+ * Used to route items to correct display lists and apply appropriate styling.
+ * 
+ * @param {Object} item - Equipment item to classify
+ * @returns {string} 'medication' | 'consumable' | 'equipment'
+ */
+function classifyEquipment(item) {
+    const type = (item.type || '').toLowerCase();
+    if (type === 'medication') return 'medication';
+    if (type === 'consumable') return 'consumable';
+    return 'equipment';
+}
+
+/**
+ * showImportStatus: function-level behavior note for maintainers.
+ * Keep this block synchronized with implementation changes.
+ */
+function showImportStatus(id, message, isError = false) {
+    const el = document.getElementById(id);
+    if (!el) return;
+    el.textContent = message;
+    el.style.color = isError ? 'var(--red)' : '#1f2d3d';
+}
+
+async function ensureEquipmentCacheLoaded() {
+    if (equipmentCache.length) return equipmentCache;
+    const data = await fetchJson('/api/data/tools');
+    equipmentCache = (Array.isArray(data) ? data : []).map(ensureEquipmentDefaults);
+    return equipmentCache;
+}
+
+/**
+ * Sanitize value for tab-delimited (TSV) export.
+ * 
+ * TSV Requirements:
+ * - No tab characters (field delimiter)
+ * - No newlines (row delimiter)
+ * - Consistent whitespace
+ * 
+ * Transformations:
+ * - Tabs → spaces
+ * - Newlines → spaces  
+ * - Trim leading/trailing whitespace
+ * - Null/undefined → empty string
+ * 
+ * @param {any} value - Value to sanitize
+ * @returns {string} TSV-safe string
+ */
+function sanitizeTSVField(value) {
+    const text = value == null ? '' : value.toString();
+    return text.replace(/\t/g, ' ').replace(/\r?\n/g, ' ').trim();
+}
+
+/**
+ * Build tab-delimited (TSV) content from equipment items.
+ * 
+ * TSV Format (3 columns):
+ * Name    Quantity    Comment
+ * 
+ * Features:
+ * - Alphabetically sorted by name
+ * - Sanitized fields (no tabs/newlines)
+ * - Customizable comment column via commentFn
+ * - Filters empty rows
+ * 
+ * Compatible with Excel, Google Sheets, Numbers, and text editors.
+ * 
+ * @param {Array<Object>} items - Equipment items to export
+ * @param {Function} commentFn - Function to extract comment from item
+ * @returns {string} TSV-formatted text
+ */
+function buildTabDelimitedContent(items, commentFn) {
+    const rows = [...items]
+        .sort((a, b) => (a.name || '').localeCompare(b.name || '', undefined, { sensitivity: 'base' }))
+        .map((item) => {
+            const name = sanitizeTSVField(item.name);
+            const quantity = sanitizeTSVField(item.totalQty);
+            const comment = sanitizeTSVField(typeof commentFn === 'function' ? commentFn(item) : item.notes);
+            return [name, quantity, comment].join('\t');
+        })
+        .filter((line) => line.trim());
+    return rows.join('\n');
+}
+
+/**
+ * Trigger browser download of TSV file.
+ * 
+ * Process:
+ * 1. Creates Blob with TSV MIME type
+ * 2. Generates object URL
+ * 3. Creates temporary <a> element
+ * 4. Triggers click to start download
+ * 5. Cleans up object URL after 1.5s
+ * 
+ * MIME Type: text/tab-separated-values
+ * 
+ * @param {string} filename - Suggested filename for download
+ * @param {string} content - TSV-formatted content
+ */
+function downloadTabDelimitedFile(filename, content) {
+    const blob = new Blob([content], { type: 'text/tab-separated-values' });
+    const url = URL.createObjectURL(blob);
+    const link = document.createElement('a');
+    link.href = url;
+    link.download = filename;
+    document.body.appendChild(link);
+    link.click();
+    document.body.removeChild(link);
+    setTimeout(() => URL.revokeObjectURL(url), 1500);
+}
+
+async function exportConsumables() {
+    try {
+        const items = await ensureEquipmentCacheLoaded();
+        const consumables = items.filter((item) => classifyEquipment(item) === 'consumable');
+        if (!consumables.length) {
+            showImportStatus('consumables-import-status', 'No consumables available to export.', true);
+            return;
+        }
+        const content = buildTabDelimitedContent(consumables, (item) => item.notes);
+        const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+        downloadTabDelimitedFile(`consumables-${timestamp}.tsv`, content);
+        showImportStatus('consumables-import-status', `Prepared ${consumables.length} consumable(s) for download.`);
+    } catch (err) {
+        showImportStatus('consumables-import-status', err.message, true);
+    }
+}
+
+/**
+ * parseTabDelimitedRows: function-level behavior note for maintainers.
+ * Keep this block synchronized with implementation changes.
+ */
+function parseTabDelimitedRows(text) {
+    if (typeof text !== 'string') return [];
+    return text
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter(Boolean)
+        .map((line) => {
+            const cols = line.split('\t');
+            return {
+                name: (cols[0] || '').trim(),
+                quantity: (cols[1] || '').trim(),
+                comment: cols.length > 2 ? cols.slice(2).join('\t').trim() : '',
+            };
+        })
+        .filter((row) => row.name);
+}
+
+/**
+ * parseConsumableFileText: function-level behavior note for maintainers.
+ * Keep this block synchronized with implementation changes.
+ */
+function parseConsumableFileText(text) {
+    return parseTabDelimitedRows(text).map((row) => ({
+        name: row.name,
+        totalQty: row.quantity,
+        notes: row.comment,
+        type: 'consumable',
+    }));
+}
+
+/**
+ * parseEquipmentFileText: function-level behavior note for maintainers.
+ * Keep this block synchronized with implementation changes.
+ */
+function parseEquipmentFileText(text) {
+    return parseTabDelimitedRows(text).map((row) => ({
+        name: row.name,
+        totalQty: row.quantity,
+        notes: row.comment,
+        type: 'durable',
+    }));
+}
+
+/**
+ * entryNameKey: function-level behavior note for maintainers.
+ * Keep this block synchronized with implementation changes.
+ */
+function entryNameKey(name) {
+    return (name || '').trim().toLowerCase();
+}
+
+/**
+ * buildEntryMap: function-level behavior note for maintainers.
+ * Keep this block synchronized with implementation changes.
+ */
+function buildEntryMap(entries) {
+    const map = new Map();
+    entries.forEach((entry) => {
+        const key = entryNameKey(entry.name);
+        if (!key) return;
+        map.set(key, entry);
+    });
+    return map;
+}
+
+/**
+ * mergeEntriesByName: function-level behavior note for maintainers.
+ * Keep this block synchronized with implementation changes.
+ */
+function mergeEntriesByName(existing, entryMap, targetClassifier) {
+    const result = [];
+    const usedKeys = new Set();
+    (existing || []).forEach((item) => {
+        const category = classifyEquipment(item);
+        if (category === targetClassifier) {
+            const key = entryNameKey(item.name);
+            if (entryMap.has(key)) {
+                result.push(entryMap.get(key));
+                usedKeys.add(key);
+                return;
+            }
+        }
+        result.push(item);
+    });
+    entryMap.forEach((entry, key) => {
+        if (!usedKeys.has(key)) {
+            result.push(entry);
+        }
+    });
+    return result;
+}
+
+async function mergeConsumableImports(entries, statusId) {
+    if (!entries.length) {
+        showImportStatus(statusId, 'No consumables found in file.', true);
+        return;
+    }
+    const normalized = entries.map((entry) => ensureEquipmentDefaults({ ...entry, type: 'consumable' }));
+    const data = await fetchJson('/api/data/tools');
+    const existing = Array.isArray(data) ? data.map(ensureEquipmentDefaults) : [];
+    const entryMap = buildEntryMap(normalized);
+    const merged = mergeEntriesByName(existing, entryMap, 'consumable');
+
+    const saveRes = await fetch('/api/data/tools', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(merged),
+        credentials: 'same-origin',
+    });
+    if (!saveRes.ok) {
+        let detail = '';
+        try {
+            const err = await saveRes.json();
+            detail = err?.error ? `: ${err.error}` : '';
+        } catch (_) {}
+        throw new Error(`Save failed (${saveRes.status})${detail}`);
+    }
+
+    equipmentCache = merged;
+    renderEquipment(equipmentCache);
+    showImportStatus(statusId, `Imported ${entryMap.size} consumable(s) from file.`);
+}
+
+async function mergeEquipmentImports(entries, statusId) {
+    if (!entries.length) {
+        showImportStatus(statusId, 'No equipment entries found in file.', true);
+        return;
+    }
+    const normalized = entries.map((entry) => ensureEquipmentDefaults({ ...entry, type: 'durable' }));
+    const data = await fetchJson('/api/data/tools');
+    const existing = Array.isArray(data) ? data.map(ensureEquipmentDefaults) : [];
+    const entryMap = buildEntryMap(normalized);
+    const merged = mergeEntriesByName(existing, entryMap, 'equipment');
+
+    const saveRes = await fetch('/api/data/tools', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(merged),
+        credentials: 'same-origin',
+    });
+    if (!saveRes.ok) {
+        let detail = '';
+        try {
+            const err = await saveRes.json();
+            detail = err?.error ? `: ${err.error}` : '';
+        } catch (_) {}
+        throw new Error(`Save failed (${saveRes.status})${detail}`);
+    }
+
+    equipmentCache = merged;
+    renderEquipment(equipmentCache);
+    showImportStatus(statusId, `Imported ${entryMap.size} equipment item(s) from file.`);
+}
+
+/**
+ * openConsumablesFilePicker: function-level behavior note for maintainers.
+ * Keep this block synchronized with implementation changes.
+ */
+function openConsumablesFilePicker() {
+    const input = document.getElementById('consumables-import-file');
+    if (!input) return;
+    input.value = '';
+    input.click();
+}
+
+async function handleConsumablesFileImport(event) {
+    const file = event?.target?.files?.[0];
+    if (!file) return;
+    try {
+        const content = await file.text();
+        const entries = parseConsumableFileText(content);
+        await mergeConsumableImports(entries, 'consumables-import-status');
+    } catch (err) {
+        showImportStatus('consumables-import-status', err.message, true);
+    } finally {
+        if (event?.target) event.target.value = '';
+    }
+}
+
+/**
+ * openEquipmentFilePicker: function-level behavior note for maintainers.
+ * Keep this block synchronized with implementation changes.
+ */
+function openEquipmentFilePicker() {
+    const input = document.getElementById('equipment-import-file');
+    if (!input) return;
+    input.value = '';
+    input.click();
+}
+
+async function handleEquipmentFileImport(event) {
+    const file = event?.target?.files?.[0];
+    if (!file) return;
+    try {
+        const content = await file.text();
+        const entries = parseEquipmentFileText(content);
+        await mergeEquipmentImports(entries, 'equipment-import-status');
+    } catch (err) {
+        showImportStatus('equipment-import-status', err.message, true);
+    } finally {
+        if (event?.target) event.target.value = '';
+    }
+}
+
+async function exportEquipmentItems() {
+    try {
+        const items = await ensureEquipmentCacheLoaded();
+        const equipment = items.filter((item) => classifyEquipment(item) === 'equipment');
+        if (!equipment.length) {
+            showImportStatus('equipment-import-status', 'No equipment available to export.', true);
+            return;
+        }
+        const content = buildTabDelimitedContent(equipment, (item) => item.notes || item.storageLocation);
+        const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+        downloadTabDelimitedFile(`equipment-${timestamp}.tsv`, content);
+        showImportStatus('equipment-import-status', `Prepared ${equipment.length} equipment item(s) for download.`);
+    } catch (err) {
+        showImportStatus('equipment-import-status', err.message, true);
+    }
+}
+
+/**
+ * Render all equipment items to appropriate lists.
+ * 
+ * Classification and Routing:
+ * 1. Classifies each item (equipment/consumable/medication)
+ * 2. Routes to correct list container:
+ *    - equipment → #equipment-list
+ *    - consumable → #consumables-list  
+ *    - medication → #medication-list
+ * 3. Sorts alphabetically within each category
+ * 4. Updates section count badges
+ * 
+ * Expansion Feature:
+ * If expandId provided, auto-expands that specific item's card
+ * (useful after adding new item to show it immediately).
+ * 
+ * @param {Array<Object>} items - All equipment/consumables to render
+ * @param {string} expandId - Optional ID of item to auto-expand
+ */
+function renderEquipment(items, expandId = null) {
+    const storeList = document.getElementById('equipment-list');
+    const medicationList = document.getElementById('medication-list');
+    const consumablesList = document.getElementById('consumables-list');
+
+    const stores = [];
+    const meds = [];
+    const cons = [];
+    (items || []).forEach((item) => {
+        const bucket = classifyEquipment(item);
+        if (bucket === 'medication') meds.push(item);
+        else if (bucket === 'consumable') cons.push(item);
+        else stores.push(item);
+    });
+
+    const sortByName = (a, b) => (a.name || '').localeCompare(b.name || '', undefined, { sensitivity: 'base' });
+    stores.sort(sortByName);
+    cons.sort(sortByName);
+
+    if (storeList) {
+        storeList.innerHTML = stores.length
+            ? stores.map((item) => renderEquipmentCard(item, expandId)).join('')
+            : '<div style="color:#666; padding:12px;">No medical equipment entries available.</div>';
+    }
+    if (medicationList) {
+        medicationList.innerHTML = meds.length ? meds.map((item) => renderEquipmentCard(item, expandId)).join('') : '';
+    }
+    if (consumablesList) {
+        consumablesList.innerHTML = cons.length
+            ? cons.map((item) => renderEquipmentCard(item, expandId)).join('')
+            : '<div style="color:#666; padding:12px;">No consumable entries available.</div>';
+    }
+    updateSectionCount('equipment-count', stores.length);
+    updateSectionCount('consumables-count', cons.length);
+}
+
+/**
+ * renderEquipmentCard: function-level behavior note for maintainers.
+ * Keep this block synchronized with implementation changes.
+ */
+function renderEquipmentCard(item, expandId = null) {
+    const itemType = (item.type || '').toLowerCase() || 'durable';
+    const isConsumable = itemType === 'consumable';
+    const isEquipment = itemType === 'durable';
+    const lowStock = item.minPar && Number(item.totalQty) <= Number(item.minPar);
+    const expirySoon = item.expiryDate && daysUntil(item.expiryDate) <= 60;
+    const headerNote = [lowStock ? 'Low Stock' : null, expirySoon ? 'Expiring Soon' : null, item.status && item.status !== 'In Stock' ? item.status : null]
+        .filter(Boolean)
+        .join(' · ');
+    const title = isConsumable
+        ? `${item.name || 'Consumable'}${item.totalQty ? ` — ${item.totalQty}` : ''}`
+        : `${item.name || 'Medical Equipment'}${item.totalQty ? ` — ${item.totalQty}` : ''}`;
+    const isOpen = expandId && item.id === expandId;
+    const bodyDisplay = isOpen ? 'display:block;' : '';
+    const arrow = isOpen ? '▾' : '▸';
+    // Palette: equipment stays green; consumables match pink shell (#f7eefc / #fcf7ff).
+    const headerBg = isConsumable
+        ? (item.excludeFromResources ? '#ffecef' : '#f7eefc')
+        : (item.excludeFromResources ? '#ffecef' : '#e8fdef');
+    const headerBorderColor = isConsumable
+        ? (item.excludeFromResources ? '#ffcbd3' : '#dec9f7')
+        : (item.excludeFromResources ? '#ffbfbf' : '#bde8c8');
+    const bodyBg = isConsumable
+        ? (item.excludeFromResources ? '#fff7f8' : '#fcf7ff')
+        : (item.excludeFromResources ? '#fff6f6' : '#f7fff7');
+    const bodyBorderColor = isConsumable
+        ? (item.excludeFromResources ? '#ffdbe2' : '#e6d7fb')
+        : (item.excludeFromResources ? '#ffcfd0' : '#cfe9d5');
+    const badgeColor = item.excludeFromResources ? '#d32f2f' : '#2e7d32';
+    const badgeText = item.excludeFromResources ? 'Resource Currently Unavailable' : 'Resource Available';
+    const availabilityBadge = `<span style="margin-left:auto; padding:2px 10px; border-radius:999px; background:${badgeColor}; color:#fff; font-size:11px; white-space:nowrap;">${badgeText}</span>`;
+    const consumableDetail = `
+            <div style="padding:10px; background:#fff; border:1px solid #dbe6f8; border-radius:6px;">
+                <div style="display:flex; align-items:center; gap:8px; margin-bottom:10px;">
+                    <span class="dev-tag">dev:consumable-detail-header</span>
+                    <span style="font-weight:700;">Consumable Detail</span>
+                    <button onclick="event.stopPropagation(); deleteEquipment('${item.id}')" class="btn btn-sm" style="background:var(--red); margin-left:auto;">🗑 Delete Consumble</button>
+                </div>
+                <div style="display:grid; grid-template-columns: 2fr 1fr; gap:10px; margin-bottom:10px; align-items:end;">
+                    <div>
+                        <div class="dev-tag">dev:consumable-detail-name</div>
+                        <label style="font-weight:700; font-size:12px;">Consumable Name</label>
+                        <input id="eq-name-${item.id}" type="text" value="${item.name}" style="width:100%; padding:8px;" oninput="scheduleSaveEquipment('${item.id}')">
+                    </div>
+                    <div>
+                        <div class="dev-tag">dev:consumable-detail-qty</div>
+                        <label style="font-weight:700; font-size:12px;">Quantity</label>
+                        <input id="eq-qty-${item.id}" type="text" value="${item.totalQty}" style="width:100%; padding:8px;" oninput="scheduleSaveEquipment('${item.id}')">
+                    </div>
+                    <div style="grid-column: span 2; display:grid; grid-template-columns: repeat(2, minmax(200px, 1fr)); gap:10px;">
+                        <div>
+                            <label style="font-weight:700; font-size:12px;">Priority Tier</label>
+                            <select id="eq-tier-${item.id}" style="width:100%; padding:8px;" onchange="handleEquipmentTierChange('${item.id}')">
+                                ${eqBuildTierOptions(item.priorityTier)}
+                            </select>
+                        </div>
+                        <div>
+                            <label style="font-weight:700; font-size:12px;">Functional Subcategory</label>
+                            <select id="eq-tiercat-${item.id}" style="width:100%; padding:8px;" onchange="scheduleSaveEquipment('${item.id}')">
+                                ${eqBuildTierSubcategoryOptions(item.priorityTier, item.tierCategory)}
+                            </select>
+                        </div>
+                    </div>
+                    <div style="grid-column: span 2;">
+                        <div class="dev-tag">dev:consumable-detail-notes</div>
+                        <label style="font-weight:700; font-size:12px;">Notes</label>
+                        <textarea id="eq-notes-${item.id}" style="width:100%; padding:8px; min-height:60px;" oninput="scheduleSaveEquipment('${item.id}')">${item.notes || ''}</textarea>
+                    </div>
+                </div>
+                <div style="display:flex; align-items:center; gap:8px; margin-top:6px;">
+                    <input id="eq-exclude-${item.id}" type="checkbox" ${item.excludeFromResources ? 'checked' : ''} onchange="scheduleSaveEquipment('${item.id}')">
+                    <label style="font-size:12px; line-height:1.2; margin:0;">Resource Currently Unavailable</label>
+                </div>
+            </div>`;
+
+    const equipmentDetail = `
+        <div class="collapsible history-item">
+            <div class="col-header crew-med-header" onclick="toggleCrewSection(this)" style="justify-content:flex-start; align-items:center; background:${headerBg}; border:1px solid ${headerBorderColor}; padding:8px 12px;">
+                <span class="toggle-label history-arrow" style="font-size:18px; margin-right:8px;">${arrow}</span>
+                <span style="flex:1; white-space:nowrap; overflow:hidden; text-overflow:ellipsis;">${title}</span>
+            ${headerNote ? `<span class="sidebar-pill" style="margin-right:8px; background:${lowStock ? '#ffebee' : '#fff7e0'}; color:${lowStock ? '#c62828' : '#b26a00'};">${headerNote}</span>` : ''}
+            ${availabilityBadge}
+        </div>
+        <div class="col-body" style="padding:12px; background:${bodyBg}; border:1px solid ${bodyBorderColor}; border-radius:6px; ${bodyDisplay}">
+            <div style="display:flex; align-items:center; gap:8px; margin-bottom:10px;">
+                <span style="font-weight:700;">${isEquipment ? 'Medical Equipment Detail' : 'Equipment Detail'}</span>
+                <button onclick="event.stopPropagation(); deleteEquipment('${item.id}')" class="btn btn-sm" style="background:var(--red); margin-left:auto;">🗑 Delete Medical Equipment Item</button>
+            </div>
+            <div style="display:grid; grid-template-columns: 2fr 1fr; gap:10px; margin-bottom:10px; align-items:end;">
+                <div>
+                    <label style="font-weight:700; font-size:12px;">Medical Equipment Name</label>
+                    <input id="eq-name-${item.id}" type="text" value="${item.name}" style="width:100%; padding:8px;" oninput="scheduleSaveEquipment('${item.id}')">
+                </div>
+                <div>
+                    <label style="font-weight:700; font-size:12px;">Quantity</label>
+                    <input id="eq-qty-${item.id}" type="text" value="${item.totalQty}" style="width:100%; padding:8px;" oninput="scheduleSaveEquipment('${item.id}')">
+                </div>
+                <div style="grid-column: span 2; display:grid; grid-template-columns: repeat(2, minmax(200px, 1fr)); gap:10px;">
+                    <div>
+                        <label style="font-weight:700; font-size:12px;">Priority Tier</label>
+                        <select id="eq-tier-${item.id}" style="width:100%; padding:8px;" onchange="handleEquipmentTierChange('${item.id}')">
+                            ${eqBuildTierOptions(item.priorityTier)}
+                        </select>
+                    </div>
+                    <div>
+                        <label style="font-weight:700; font-size:12px;">Functional Subcategory</label>
+                        <select id="eq-tiercat-${item.id}" style="width:100%; padding:8px;" onchange="scheduleSaveEquipment('${item.id}')">
+                            ${eqBuildTierSubcategoryOptions(item.priorityTier, item.tierCategory)}
+                        </select>
+                    </div>
+                </div>
+                <div style="grid-column: span 2;">
+                    <label style="font-weight:700; font-size:12px;">Storage Location</label>
+                    <input id="eq-loc-${item.id}" type="text" value="${item.storageLocation}" placeholder="Medical Bag 1, Locker B" style="width:100%; padding:8px;" oninput="scheduleSaveEquipment('${item.id}')">
+                </div>
+                <div style="grid-column: span 2;">
+                    <label style="font-weight:700; font-size:12px;">Notes</label>
+                    <textarea id="eq-notes-${item.id}" style="width:100%; padding:8px; min-height:60px;" oninput="scheduleSaveEquipment('${item.id}')">${item.notes || ''}</textarea>
+                </div>
+            </div>
+            <div style="display:flex; align-items:center; gap:8px; margin-top:6px;">
+                <input id="eq-exclude-${item.id}" type="checkbox" ${item.excludeFromResources ? 'checked' : ''} onchange="scheduleSaveEquipment('${item.id}')">
+                <label style="font-size:12px; line-height:1.2; margin:0;">Resource Currently Unavailable</label>
+            </div>
+        </div>
+    </div>`;
+
+    if (isConsumable) {
+        return `
+        <div class="collapsible history-item">
+        <div class="col-header crew-med-header" onclick="toggleCrewSection(this)" style="justify-content:flex-start; align-items:center; background:${headerBg}; border:1px solid ${headerBorderColor}; padding:8px 12px;">
+                <span class="toggle-label history-arrow" style="font-size:18px; margin-right:8px;">${arrow}</span>
+                <span style="flex:1; white-space:nowrap; overflow:hidden; text-overflow:ellipsis;">${title}</span>
+                ${headerNote ? `<span class="sidebar-pill" style="margin-right:8px; background:${lowStock ? '#ffebee' : '#fff7e0'}; color:${lowStock ? '#c62828' : '#b26a00'};">${headerNote}</span>` : ''}
+                ${availabilityBadge}
+            </div>
+            <div class="col-body" style="padding:12px; background:${bodyBg}; border:1px solid ${bodyBorderColor}; border-radius:6px; ${bodyDisplay}">
+                ${consumableDetail}
+            </div>
+        </div>`;
+    }
+
+    return equipmentDetail;
+}
+
+/**
+ * Schedule debounced auto-save for equipment item.
+ * 
+ * Debounce Period: 600ms
+ * 
+ * Allows rapid typing/editing without flooding the backend with saves.
+ * Each equipment item has independent timer.
+ * 
+ * Triggered by: Input/change events on equipment form fields
+ * 
+ * @param {string} id - Equipment item ID to save
+ */
+function scheduleSaveEquipment(id) {
+    if (equipmentSaveTimers[id]) clearTimeout(equipmentSaveTimers[id]);
+    equipmentSaveTimers[id] = setTimeout(() => saveEquipment(id), 600);
+}
+
+/**
+ * Save equipment item changes to server.
+ * 
+ * Save Process:
+ * 1. Loads full equipment list
+ * 2. Finds item by ID
+ * 3. Updates fields from form inputs
+ * 4. Writes entire list back to server
+ * 5. Updates cache and re-renders with item expanded
+ * 
+ * Fields Saved:
+ * - name, category, type, storage location
+ * - status, dates (expiry, inspection, calibration)
+ * - quantities (total, min PAR)
+ * - battery info, supplier, notes
+ * - excludeFromResources flag
+ * 
+ * Re-render Strategy:
+ * After save, re-renders with saved item expanded so user can verify
+ * changes persisted correctly.
+ * 
+ * @param {string} id - Equipment item ID to save
+ */
+async function saveEquipment(id) {
+    const getVal = (elementId, fallback = '') => {
+        const el = document.getElementById(elementId);
+        return el ? el.value : fallback;
+    };
+    const data = await fetchJson('/api/data/tools');
+    const items = Array.isArray(data) ? data.map(ensureEquipmentDefaults) : [];
+    const eq = items.find((i) => i.id === id);
+    if (!eq) return;
+    eq.name = getVal(`eq-name-${id}`, eq.name);
+    eq.type = getVal(`eq-type-${id}`, eq.type || 'durable');
+    eq.storageLocation = getVal(`eq-loc-${id}`, eq.storageLocation);
+    eq.subLocation = getVal(`eq-subloc-${id}`, eq.subLocation);
+    eq.parentId = getVal(`eq-parent-${id}`, eq.parentId);
+    eq.status = getVal(`eq-status-${id}`, eq.status || 'In Stock');
+    eq.expiryDate = getVal(`eq-exp-${id}`, eq.expiryDate);
+    eq.lastInspection = getVal(`eq-inspect-${id}`, eq.lastInspection);
+    eq.batteryType = getVal(`eq-batt-${id}`, eq.batteryType);
+    eq.calibrationDue = getVal(`eq-cal-${id}`, eq.calibrationDue);
+    eq.totalQty = getVal(`eq-qty-${id}`, eq.totalQty);
+    eq.minPar = getVal(`eq-par-${id}`, eq.minPar);
+    eq.supplier = getVal(`eq-sup-${id}`, eq.supplier);
+    eq.priorityTier = getVal(`eq-tier-${id}`, eq.priorityTier);
+    eq.tierCategory = getVal(`eq-tiercat-${id}`, eq.tierCategory);
+    eq.notes = getVal(`eq-notes-${id}`, eq.notes);
+    const excludeEl = document.getElementById(`eq-exclude-${id}`);
+    eq.excludeFromResources = !!(excludeEl && excludeEl.checked);
+
+    await fetch('/api/data/tools', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(items),
+        credentials: 'same-origin',
+    });
+    equipmentCache = items;
+    renderEquipment(equipmentCache, id);
+}
+
+/**
+ * openEquipmentAddForm: function-level behavior note for maintainers.
+ * Keep this block synchronized with implementation changes.
+ */
+function openEquipmentAddForm() {
+    // Ensure both outer and inner collapsibles are open so the add button is visible.
+    const outerHeader = document.querySelector('#equipment-section-header');
+    if (outerHeader) {
+        const outerBody = outerHeader.nextElementSibling;
+        if (outerBody && outerBody.style.display !== 'block') {
+            toggleSection(outerHeader);
+        }
+    }
+    const header = document.getElementById('equipment-add-header');
+    if (header) {
+        const body = header.nextElementSibling;
+        if (body && body.style.display !== 'block') {
+            toggleSection(header);
+        }
+    }
+    setTimeout(() => {
+        const nameField = document.getElementById('eq-new-name');
+        if (nameField) nameField.focus();
+    }, 30);
+}
+
+/**
+ * getNewEquipmentVal: function-level behavior note for maintainers.
+ * Keep this block synchronized with implementation changes.
+ */
+function getNewEquipmentVal(id) {
+    const el = document.getElementById(id);
+    return el ? el.value.trim() : '';
+}
+
+/**
+ * Add new medical equipment item from form.
+ * 
+ * Validation:
+ * - Name is required (focuses field if missing)
+ * - All other fields optional
+ * 
+ * Process:
+ * 1. Collects form values
+ * 2. Creates new item with generated ID
+ * 3. Adds to equipment list
+ * 4. Saves to server
+ * 5. Clears form for next entry
+ * 6. Reloads with new item expanded
+ * 
+ * Item Type: 'durable' (reusable equipment)
+ * Category: 'Medical Equipment'
+ * 
+ * Use Cases:
+ * - AED, blood pressure cuff, thermometer
+ * - Stethoscope, pulse oximeter, glucometer
+ * - Trauma shears, splints, suction devices
+ */
+async function addMedicalStore() {
+    const name = getNewEquipmentVal('eq-new-name');
+    if (!name) {
+        alert('Please enter a Medical Equipment name');
+        const nameField = document.getElementById('eq-new-name');
+        if (nameField) nameField.focus();
+        return;
+    }
+    const quantity = getNewEquipmentVal('eq-new-qty');
+    const location = getNewEquipmentVal('eq-new-loc');
+    const notes = document.getElementById('eq-new-notes')?.value || '';
+    const exclude = document.getElementById('eq-new-exclude')?.checked || false;
+    const priorityTier = getNewEquipmentVal('eq-new-tier');
+    const tierCategory = getNewEquipmentVal('eq-new-tiercat');
+    const newId = `eq-${Date.now()}`;
+    const newItem = ensureEquipmentDefaults({
+        id: newId,
+        name,
+        type: 'durable',
+        storageLocation: location,
+        totalQty: quantity,
+        priorityTier,
+        tierCategory,
+        notes,
+        status: 'In Stock',
+        excludeFromResources: exclude,
+    });
+
+    const data = await fetchJson('/api/data/tools');
+    const items = Array.isArray(data) ? data.map(ensureEquipmentDefaults) : [];
+    items.push(newItem);
+    await fetch('/api/data/tools', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(items),
+        credentials: 'same-origin',
+    });
+
+    // Clear the add form for the next entry
+    ['eq-new-name','eq-new-loc','eq-new-qty','eq-new-notes','eq-new-tier','eq-new-tiercat']
+        .forEach((id) => { const el = document.getElementById(id); if (el) el.value = ''; });
+    const newExclude = document.getElementById('eq-new-exclude');
+    if (newExclude) newExclude.checked = false;
+
+    loadEquipment(newId);
+}
+
+/**
+ * canonicalMedKey: function-level behavior note for maintainers.
+ * Keep this block synchronized with implementation changes.
+ */
+function canonicalMedKey(generic, brand, strength, formStrength = '') {
+    const clean = (val) => (val || '').toLowerCase().replace(/[^a-z0-9]+/g, '');
+    const strengthVal = clean(strength || formStrength).replace(/unspecified/g, '');
+    return `${clean(generic)}|${clean(brand)}|${strengthVal}`;
+}
+
+async function addMedicationItem() {
+    const name = getNewEquipmentVal('med-new-name');
+    if (!name) {
+        alert('Please enter a Medication name');
+        const nameField = document.getElementById('med-new-name');
+        if (nameField) nameField.focus();
+        return;
+    }
+    const sortSel = document.getElementById('med-new-sort');
+    const sortCustom = document.getElementById('med-new-sort-custom');
+    const sortCategoryRaw = sortSel ? (sortSel.value === '__custom' ? (sortCustom?.value || '') : (sortSel.value || '')) : '';
+    const sortCategory = (sortCategoryRaw || '').trim();
+    const verified = !!document.getElementById('med-new-verified')?.checked;
+    const exclude = document.getElementById('med-new-exclude')?.checked || false;
+    const controlled = document.getElementById('med-new-ctrl')?.value === 'true';
+    const dosage = document.getElementById('med-new-dose')?.value || '';
+    const expiryDate = document.getElementById('med-new-exp')?.value || '';
+    const expiryQty = getNewEquipmentVal('med-new-exp-qty') || '';
+    const expiryBatch = getNewEquipmentVal('med-new-exp-batch') || '';
+    const notes = document.getElementById('med-new-notes')?.value || '';
+    const priorityTier = getNewEquipmentVal('med-new-tier');
+    const tierCategory = getNewEquipmentVal('med-new-tiercat');
+    const newId = `med-${Date.now()}`;
+    const purchaseHistory = [];
+    if (expiryDate) {
+        purchaseHistory.push({
+            id: `ph-${Date.now()}`,
+            date: expiryDate,
+            quantity: expiryQty || getNewEquipmentVal('med-new-qty') || '',
+            notes: '',
+            manufacturer: getNewEquipmentVal('med-new-sup') || '',
+            batchLot: expiryBatch || '',
+        });
+    }
+    const newMed = {
+        id: newId,
+        genericName: name,
+        brandName: getNewEquipmentVal('med-new-brand'),
+        form: getNewEquipmentVal('med-new-form'),
+        strength: getNewEquipmentVal('med-new-strength'),
+        formStrength: [getNewEquipmentVal('med-new-form'), getNewEquipmentVal('med-new-strength')].join(' ').trim(),
+        currentQuantity: getNewEquipmentVal('med-new-qty') || '',
+        minThreshold: getNewEquipmentVal('med-new-par') || '',
+        unit: getNewEquipmentVal('med-new-unit') || '',
+        storageLocation: getNewEquipmentVal('med-new-loc') || '',
+        expiryDate: document.getElementById('med-new-exp')?.value || '',
+        batchLot: '',
+        controlled,
+        manufacturer: getNewEquipmentVal('med-new-sup') || '',
+        primaryIndication: getNewEquipmentVal('med-new-indication') || '',
+        allergyWarnings: getNewEquipmentVal('med-new-allergy') || '',
+        standardDosage: dosage,
+        sortCategory,
+        priorityTier,
+        tierCategory,
+        verified,
+        notes,
+        purchaseHistory,
+        source: 'manual_entry',
+        excludeFromResources: exclude,
+    };
+
+    const data = await fetchJson('/api/data/inventory');
+    const items = Array.isArray(data) ? data : [];
+    const g = (newMed.genericName || '').trim().toLowerCase();
+    const b = (newMed.brandName || '').trim().toLowerCase();
+    const targetKey = canonicalMedKey(g, b, newMed.strength, newMed.formStrength);
+    const dup = items.find((m) => {
+        const mg = (m.genericName || '').trim().toLowerCase();
+        const mb = (m.brandName || '').trim().toLowerCase();
+        return canonicalMedKey(mg, mb, m.strength, m.formStrength) === targetKey;
+    });
+    if (dup) {
+        alert('A medication with the same Generic + Brand + Strength already exists. Please adjust to keep entries unique.');
+        return;
+    }
+    items.push(newMed);
+    await fetch('/api/data/inventory', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(items),
+        credentials: 'same-origin',
+    });
+
+    ['med-new-name','med-new-brand','med-new-form','med-new-strength','med-new-loc','med-new-exp','med-new-exp-qty','med-new-exp-batch','med-new-qty','med-new-par','med-new-unit','med-new-sup','med-new-indication','med-new-allergy','med-new-dose','med-new-notes','med-new-tier','med-new-tiercat']
+        .forEach((id) => { const el = document.getElementById(id); if (el) el.value = ''; });
+    const sortSelect = document.getElementById('med-new-sort');
+    const sortCustomInput = document.getElementById('med-new-sort-custom');
+    if (sortSelect) sortSelect.value = '';
+    if (sortCustomInput) { sortCustomInput.value = ''; sortCustomInput.style.display = 'none'; }
+    const medVerified = document.getElementById('med-new-verified');
+    if (medVerified) medVerified.checked = false;
+    const medExclude = document.getElementById('med-new-exclude');
+    if (medExclude) medExclude.checked = false;
+    const ctrlSel = document.getElementById('med-new-ctrl');
+    if (ctrlSel) ctrlSel.value = 'false';
+
+    if (typeof loadPharmacy === 'function') {
+        loadPharmacy();
+    }
+}
+
+/**
+ * Add new consumable item from form.
+ * 
+ * Validation:
+ * - Name is required (focuses field if missing)
+ * - Quantity and notes optional
+ * 
+ * Process:
+ * 1. Collects form values  
+ * 2. Creates new item with generated ID
+ * 3. Adds to equipment list
+ * 4. Saves to server
+ * 5. Clears form for next entry
+ * 6. Reloads with new item expanded
+ * 
+ * Item Type: 'consumable' (single-use supplies)
+ * Category: 'Consumable'
+ * 
+ * Use Cases:
+ * - Bandages, gauze pads, tape
+ * - Gloves, masks, syringes
+ * - Alcohol wipes, antiseptic
+ * - Sutures, IV supplies
+ */
+async function addConsumableItem() {
+    const name = getNewEquipmentVal('cons-new-name');
+    if (!name) {
+        alert('Please enter a Consumable name');
+        const nameField = document.getElementById('cons-new-name');
+        if (nameField) nameField.focus();
+        return;
+    }
+    const quantity = getNewEquipmentVal('cons-new-qty');
+    const notes = document.getElementById('cons-new-notes')?.value || '';
+    const exclude = document.getElementById('cons-new-exclude')?.checked || false;
+    const priorityTier = getNewEquipmentVal('cons-new-tier');
+    const tierCategory = getNewEquipmentVal('cons-new-tiercat');
+    const newId = `eq-${Date.now()}`;
+    const newItem = ensureEquipmentDefaults({
+        id: newId,
+        name,
+        type: 'consumable',
+        totalQty: quantity,
+        priorityTier,
+        tierCategory,
+        notes,
+        status: 'In Stock',
+        excludeFromResources: exclude,
+    });
+
+    const res = await fetch('/api/data/tools', { credentials: 'same-origin' });
+    const data = await res.json();
+    const items = Array.isArray(data) ? data.map(ensureEquipmentDefaults) : [];
+    items.push(newItem);
+    await fetch('/api/data/tools', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(items),
+        credentials: 'same-origin',
+    });
+
+    ['cons-new-name','cons-new-qty','cons-new-notes','cons-new-tier','cons-new-tiercat']
+        .forEach((id) => { const el = document.getElementById(id); if (el) el.value = ''; });
+    const consumableExclude = document.getElementById('cons-new-exclude');
+    if (consumableExclude) consumableExclude.checked = false;
+
+    loadEquipment(newId);
+}
+
+/**
+ * Delete equipment item with double confirmation.
+ * 
+ * Two-Step Safety:
+ * 1. Confirm dialog
+ * 2. Type "DELETE" prompt (exact match required)
+ * 
+ * Process:
+ * 1. Loads full equipment list
+ * 2. Filters out deleted item
+ * 3. Writes remaining items to server
+ * 4. Reloads equipment display
+ * 
+ * Permanent Action:
+ * No undo available. Data is permanently removed from tools.json.
+ * 
+ * @param {string} id - Equipment item ID to delete
+ */
+async function deleteEquipment(id) {
+    if (!confirm('Delete this equipment item?')) return;
+    const confirmText = prompt('Type DELETE to confirm:');
+    if (confirmText !== 'DELETE') {
+        alert('Deletion cancelled.');
+        return;
+    }
+    const res = await fetch('/api/data/tools', { credentials: 'same-origin' });
+    const data = await res.json();
+    const items = Array.isArray(data) ? data : [];
+    const filtered = items.filter((i) => i.id !== id);
+    await fetch('/api/data/tools', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(filtered),
+        credentials: 'same-origin',
+    });
+    loadEquipment();
+}
+
+/**
+ * Calculate days until a future date.
+ * 
+ * Used for:
+ * - Expiry warnings (items expiring soon)
+ * - Calibration due dates
+ * - Maintenance schedules
+ * 
+ * Returns:
+ * - Positive number: Days in future
+ * - Negative number: Days in past (expired)
+ * - 9999: Invalid date (parsing failed)
+ * 
+ * Thresholds:
+ * - ≤ 60 days: Show "Expiring Soon" warning
+ * - < 0 days: Show "Expired" warning
+ * 
+ * @param {string} dateStr - ISO date string (YYYY-MM-DD)
+ * @returns {number} Days until date (or 9999 if invalid)
+ */
+function daysUntil(dateStr) {
+    const now = new Date();
+    const target = new Date(dateStr);
+    if (isNaN(target.getTime())) return 9999;
+    return Math.ceil((target.getTime() - now.getTime()) / (1000 * 60 * 60 * 24));
+}
+
+// Expose handlers
+window.loadEquipment = loadEquipment;
+window.addEquipment = openEquipmentAddForm;
+window.openEquipmentAddForm = openEquipmentAddForm;
+window.addMedicalStore = addMedicalStore;
+window.addMedicationItem = addMedicationItem;
+window.addConsumableItem = addConsumableItem;
+window.deleteEquipment = deleteEquipment;
+window.scheduleSaveEquipment = scheduleSaveEquipment;
+window.handleEquipmentTierChange = handleEquipmentTierChange;
+window.exportConsumables = exportConsumables;
+window.openConsumablesFilePicker = openConsumablesFilePicker;
+window.handleConsumablesFileImport = handleConsumablesFileImport;
+window.exportEquipmentItems = exportEquipmentItems;
+window.openEquipmentFilePicker = openEquipmentFilePicker;
+window.handleEquipmentFileImport = handleEquipmentFileImport;
+window.forceClearCache = function forceClearCache() {
+    if (typeof window.resetConsultationUiForDemo === 'function') {
+        window.resetConsultationUiForDemo();
+    }
+    try {
+        [
+            'sailingmed:lastPrompt',
+            'sailingmed:lastPatient',
+            'sailingmed:lastChatMode',
+            'sailingmed:promptPreviewOpen',
+            'sailingmed:promptPreviewContent',
+            'sailingmed:chatState',
+            'triage-pathway-open',
+            'sailingmed:skipLastChat',
+            'sailingmed:loggingOff',
+            'sailingmed:sidebarCollapsed',
+        ].forEach((k) => localStorage.removeItem(k));
+        localStorage.setItem('sailingmed:sidebarCollapsed', '0');
+        sessionStorage.clear();
+    } catch (err) { /* ignore */ }
+    // Route through logout to ensure splash/login is shown regardless of auth state.
+    window.location.assign(`/logout?fresh=${Date.now()}`);
+};

static/js/main.js

@@ -0,0 +1,1243 @@
+/* =============================================================================
+ * Author: Rick Escher
+ * Project: SailingMedAdvisor
+ * Context: Google HAI-DEF Framework
+ * Models: Google MedGemmas
+ * Program: Kaggle Impact Challenge
+ * ========================================================================== */
+/*
+File: static/js/main.js
+Author notes: Application orchestration and global UI utilities.
+
+Key Responsibilities:
+- Tab navigation and content switching
+- Collapsible section management (queries, headers, details)
+- Sidebar state persistence and synchronization
+- Application initialization and data preloading
+- Medical chest global search across all inventories
+- LocalStorage state restoration
+
+Architecture Overview:
+---------------------
+main.js acts as the conductor for the single-page application, coordinating:
+
+1. **Tab System**: 5 main tabs with lazy loading
+   - Chat: AI consultation interface
+   - Medical Chest: Pharmacy inventory (preloaded for performance)
+   - Crew Health & Log: Medical records and history
+   - Vessel & Crew Info: Demographics and documents
+   - Onboard Equipment: Medical equipment and consumables
+   - Settings: Configuration and offline mode
+
+2. **Collapsible Sections**: 3 different toggle patterns
+   - toggleSection(): Standard sections (most common)
+   - toggleDetailSection(): Detail panels with special handling
+   - toggleCrewSection(): Crew cards with accordion behavior
+
+3. **Sidebar Management**: Context-sensitive help/reference
+   - Collapsed/expanded state persists across sessions
+   - Auto-syncs with collapsible section states
+   - Shows/hides relevant content per active tab
+
+4. **Initialization Strategy**: Staggered loading for performance
+   - Immediate: Chat tab (default landing)
+   - Preload: Medical Chest (frequent access)
+   - On-demand: Other tabs load when opened
+   - Concurrent: Crew data, settings, history loaded together
+
+5. **Global Search**: Unified search across all inventories
+   - Searches pharmaceuticals, equipment, consumables
+   - Scope filtering (all/pharma/equipment/consumables)
+   - Grouped results by category
+   - Expandable result sections
+
+Data Loading Flow:
+-----------------
+```
+Page Load → ensureCrewData() → Promise.all([
+  /api/data/patients,
+  /api/data/history,
+  /api/data/settings
+]) → loadCrewData() → Render UI
+
+Tab Switch → showTab() → 
+  if Chat: updateUI(), restoreCollapsibleState()
+  if CrewMedical: ensureCrewData()
+  if OnboardEquipment: loadEquipment()
+  if Settings: loadSettingsUI(), loadCrewCredentials()
+```
+
+LocalStorage Keys:
+- sailingmed:sidebarCollapsed: Sidebar state (1=collapsed, 0=expanded)
+- sailingmed:lastOpenCrew: Last opened crew card ID
+- sailingmed:skipLastChat: Flag to skip restoring last chat
+- [headerId]: Per-section collapsed state
+
+Integration Points:
+- crew.js: loadCrewData() renders crew lists
+- pharmacy.js: preloadPharmacy(), loadPharmacy()
+- equipment.js: loadEquipment()
+- settings.js: loadSettingsUI(), loadCrewCredentials()
+- chat.js: updateUI(), refreshPromptPreview()
+*/
+
+// ============================================================================
+// STATE MANAGEMENT
+// ============================================================================
+
+const SIDEBAR_STATE_KEY = 'sailingmed:sidebarCollapsed';
+const renderAssistantMarkdownMain = (window.Utils && window.Utils.renderAssistantMarkdown)
+    ? window.Utils.renderAssistantMarkdown
+    : (txt) => (window.marked && typeof window.marked.parse === 'function')
+        ? window.marked.parse(txt || '', { gfm: true, breaks: true })
+        : (window.escapeHtml ? window.escapeHtml(txt || '') : String(txt || '')).replace(/\n/g, '<br>');
+let globalSidebarCollapsed = false;  // Sidebar collapse state (synced across all tabs)
+let crewDataLoaded = false;          // Prevent duplicate crew data loads
+let crewDataPromise = null;          // Promise for concurrent load protection
+let loadDataInFlight = null;         // Shared promise so concurrent refreshes collapse into one request
+let cachedPatientsRoster = null;     // Last successful /api/data/patients payload for lightweight refreshes
+const LAST_PATIENT_KEY_MAIN = 'sailingmed:lastPatient';
+const CREW_OPTIONS_CACHE_KEY = 'sailingmed:crewOptionsCache';
+const COLLAPSIBLE_PREF_SCHEMA_KEY = 'sailingmed:collapsiblePrefSchema';
+const COLLAPSIBLE_PREF_SCHEMA_VERSION = '2';
+let startupCriticalInitDone = false;   // Prevent duplicate critical bootstrap runs
+let startupDeferredInitDone = false;   // Prevent duplicate deferred bootstrap runs
+let startupCrewReadyPromise = null;    // Shared crew-ready promise across startup phases
+
+/**
+ * migrateCollapsiblePrefs: function-level behavior note for maintainers.
+ * Keep this block synchronized with implementation changes.
+ */
+function migrateCollapsiblePrefs() {
+    try {
+        const current = localStorage.getItem(COLLAPSIBLE_PREF_SCHEMA_KEY);
+        if (current === COLLAPSIBLE_PREF_SCHEMA_VERSION) return;
+        // Legacy values were stored inverted; normalize once.
+        ['query-form-open', 'triage-pathway-open'].forEach((key) => {
+            const raw = localStorage.getItem(key);
+            if (raw === 'true') localStorage.setItem(key, 'false');
+            else if (raw === 'false') localStorage.setItem(key, 'true');
+        });
+        localStorage.setItem(COLLAPSIBLE_PREF_SCHEMA_KEY, COLLAPSIBLE_PREF_SCHEMA_VERSION);
+    } catch (err) { /* ignore */ }
+}
+
+/**
+ * getCrewFullNameFast: function-level behavior note for maintainers.
+ * Keep this block synchronized with implementation changes.
+ */
+function getCrewFullNameFast(crew) {
+    const first = crew && typeof crew.firstName === 'string' ? crew.firstName.trim() : '';
+    const last = crew && typeof crew.lastName === 'string' ? crew.lastName.trim() : '';
+    const full = `${first} ${last}`.trim();
+    if (full) return full;
+    if (crew && typeof crew.name === 'string' && crew.name.trim()) return crew.name.trim();
+    return 'Unnamed Crew';
+}
+
+/**
+ * Fast-path dropdown population so the Chat crew selector is usable
+ * immediately after splash/login transition.
+ *
+ * This intentionally avoids rendering full crew/history UI and only updates
+ * `#p-select` while the rest of loadData() continues in the background.
+ */
+function populateCrewSelectFast(patients) {
+    if (!Array.isArray(patients)) return;
+    const select = document.getElementById('p-select');
+    if (!select) return;
+
+    let storedValue = '';
+    try {
+        storedValue = localStorage.getItem(LAST_PATIENT_KEY_MAIN) || '';
+    } catch (err) { /* ignore */ }
+    const currentValue = select.value || '';
+    const preferredValue = currentValue || storedValue;
+
+    const frag = document.createDocumentFragment();
+    const defaultOpt = document.createElement('option');
+    defaultOpt.value = '';
+    defaultOpt.textContent = 'Unnamed Crew Member';
+    frag.appendChild(defaultOpt);
+    patients.forEach((crew) => {
+        const opt = document.createElement('option');
+        opt.value = String((crew && crew.id) || '');
+        opt.textContent = getCrewFullNameFast(crew);
+        frag.appendChild(opt);
+    });
+    select.replaceChildren(frag);
+
+    if (preferredValue && Array.from(select.options).some((opt) => opt.value === preferredValue)) {
+        select.value = preferredValue;
+        return;
+    }
+    if (preferredValue) {
+        const byName = Array.from(select.options).find((opt) => opt.textContent === preferredValue);
+        select.value = byName ? (byName.value || '') : '';
+        return;
+    }
+    select.value = '';
+}
+
+/**
+ * cacheCrewOptionsFast: persist lightweight crew selector options for instant hydration.
+ */
+function cacheCrewOptionsFast(patients) {
+    if (!Array.isArray(patients)) return;
+    const compact = patients
+        .map((crew) => {
+            const id = String((crew && crew.id) || '').trim();
+            if (!id) return null;
+            const label = getCrewFullNameFast(crew);
+            return { id, label };
+        })
+        .filter(Boolean);
+    if (!compact.length) return;
+    try {
+        localStorage.setItem(CREW_OPTIONS_CACHE_KEY, JSON.stringify(compact));
+    } catch (err) { /* ignore */ }
+}
+
+/**
+ * hydrateCrewSelectFromCache: render cached crew options before network completes.
+ */
+function hydrateCrewSelectFromCache() {
+    try {
+        const raw = localStorage.getItem(CREW_OPTIONS_CACHE_KEY);
+        if (!raw) return false;
+        const parsed = JSON.parse(raw);
+        if (!Array.isArray(parsed) || !parsed.length) return false;
+        populateCrewSelectFast(parsed.map((entry) => ({
+            id: entry && entry.id,
+            name: entry && entry.label,
+        })));
+        return true;
+    } catch (err) {
+        return false;
+    }
+}
+
+/**
+ * getMedicalChestRenderCount: function-level behavior note for maintainers.
+ * Keep this block synchronized with implementation changes.
+ */
+function getMedicalChestRenderCount() {
+    const pharmaCount = document.querySelectorAll('#pharmacy-list .history-item').length;
+    const equipmentCount = document.querySelectorAll('#equipment-list .history-item').length;
+    const consumableCount = document.querySelectorAll('#consumables-list .history-item').length;
+    return pharmaCount + equipmentCount + consumableCount;
+}
+
+async function runMedicalChestLoadCycle() {
+    const loaders = [];
+    if (typeof loadEquipment === 'function') {
+        loaders.push(Promise.resolve(loadEquipment()));
+    }
+    if (typeof loadPharmacy === 'function') {
+        loaders.push(Promise.resolve(loadPharmacy()));
+    }
+    if (!loaders.length) return;
+    await Promise.allSettled(loaders);
+}
+
+async function ensureMedicalChestLoaded() {
+    await runMedicalChestLoadCycle();
+    if (getMedicalChestRenderCount() > 0) return;
+    try {
+        const [invRes, toolsRes] = await Promise.all([
+            fetch('/api/data/inventory', { credentials: 'same-origin' }),
+            fetch('/api/data/tools', { credentials: 'same-origin' }),
+        ]);
+        const [invData, toolsData] = await Promise.all([
+            invRes.ok ? invRes.json() : Promise.resolve([]),
+            toolsRes.ok ? toolsRes.json() : Promise.resolve([]),
+        ]);
+        const hasBackendData = (Array.isArray(invData) && invData.length > 0)
+            || (Array.isArray(toolsData) && toolsData.length > 0);
+        if (hasBackendData) {
+            console.warn('Medical Chest rendered empty; retrying load once.');
+            await new Promise((resolve) => setTimeout(resolve, 300));
+            await runMedicalChestLoadCycle();
+        }
+    } catch (err) {
+        console.warn('Medical Chest retry probe failed:', err);
+    }
+}
+
+/**
+ * Set sidebar collapsed state across all sidebars.
+ * 
+ * Sidebar States:
+ * - Expanded: Shows context help, reference content
+ * - Collapsed: Hides sidebar, maximizes main content area
+ * 
+ * UI Changes:
+ * 1. Adds/removes 'collapsed' class to all .page-sidebar elements
+ * 2. Updates toggle button text ("Context ←" / "Context →")
+ * 3. Adjusts page body layout classes
+ * 4. Persists state to localStorage
+ * 
+ * Applied Globally:
+ * All sidebars on the page sync to same state for consistency.
+ * 
+ * @param {boolean} collapsed - True to collapse, false to expand
+ */
+function setSidebarState(collapsed) {
+    globalSidebarCollapsed = !!collapsed;
+    try { localStorage.setItem(SIDEBAR_STATE_KEY, globalSidebarCollapsed ? '1' : '0'); } catch (err) { /* ignore */ }
+    document.querySelectorAll('.page-sidebar').forEach((sidebar) => {
+        sidebar.classList.toggle('collapsed', globalSidebarCollapsed);
+        const button = sidebar.querySelector('.sidebar-toggle');
+        if (button) button.textContent = globalSidebarCollapsed ? 'Context ←' : 'Context →';
+        const body = sidebar.closest('.page-body');
+        if (body) {
+            body.classList.toggle('sidebar-open', !globalSidebarCollapsed);
+            body.classList.toggle('sidebar-collapsed', globalSidebarCollapsed);
+        }
+    });
+}
+
+/**
+ * Toggle standard collapsible section visibility.
+ * 
+ * Standard Pattern:
+ * Header with .detail-icon (▸/▾) and body that expands/collapses.
+ * 
+ * Special Behaviors:
+ * 1. Crew Sort Control: Shows only when crew list expanded
+ * 2. Triage Sample Selector: Shows only when expanded AND in advanced/developer mode
+ * 3. Sidebar Sync: Updates related sidebar sections if data-sidebar-id present
+ * 4. State Persistence: Saves to localStorage if data-pref-key present
+ * 
+ * Used For:
+ * - Query form sections
+ * - Settings sections
+ * - Crew list headers
+ * - Equipment sections
+ * 
+ * @param {HTMLElement} el - Header element to toggle
+ */
+function toggleSection(el) {
+    const body = el.nextElementSibling;
+    const icon = el.querySelector('.detail-icon');
+    const isExpanded = body.style.display === "block";
+    const nextExpanded = !isExpanded;
+    body.style.display = nextExpanded ? "block" : "none";
+    if (icon) icon.textContent = nextExpanded ? "▾" : "▸";
+    // Show/hide crew sort control only when crew list expanded
+    const sortWrap = el.querySelector('#crew-sort-wrap');
+    if (sortWrap) {
+        sortWrap.style.display = nextExpanded ? "flex" : "none";
+    }
+    if (el.dataset && el.dataset.sidebarId) {
+        syncSidebarSections(el.dataset.sidebarId, nextExpanded);
+    }
+    if (el.dataset && el.dataset.prefKey) {
+        try { localStorage.setItem(el.dataset.prefKey, nextExpanded.toString()); } catch (err) { /* ignore */ }
+    }
+    if (el.id === 'query-form-header') {
+        if (typeof window.handleStartPanelToggle === 'function') {
+            window.handleStartPanelToggle(nextExpanded);
+        } else if (typeof window.updateStartPanelTitle === 'function') {
+            window.updateStartPanelTitle();
+        }
+    }
+}
+
+/**
+ * Toggle detail section with prompt preview special handling.
+ * 
+ * Similar to toggleSection but with additional logic for:
+ * - Prompt refresh inline button visibility (advanced/developer mode only)
+ * - ARIA attributes for accessibility (aria-expanded)
+ * 
+ * Used For:
+ * - Prompt preview/editor panel (chat.js)
+ * - Other detail panels requiring ARIA support
+ * 
+ * @param {HTMLElement} el - Header element to toggle
+ */
+function toggleDetailSection(el) {
+    const body = el.nextElementSibling;
+    const icon = el.querySelector('.detail-icon');
+    const isExpanded = body.style.display === "block";
+    const nextExpanded = !isExpanded;
+    body.style.display = nextExpanded ? "block" : "none";
+    icon.textContent = nextExpanded ? "▾" : "▸";
+    // Handle prompt refresh inline visibility
+    const refreshInline = document.getElementById('prompt-refresh-inline');
+    if (refreshInline && el.id === 'prompt-preview-header') {
+        const isAdvanced = document.body.classList.contains('mode-advanced') || document.body.classList.contains('mode-developer');
+        refreshInline.style.display = nextExpanded && isAdvanced ? 'flex' : 'none';
+        el.setAttribute('aria-expanded', nextExpanded ? 'true' : 'false');
+    }
+}
+
+/**
+ * Toggle crew card with accordion behavior.
+ * 
+ * Crew Card Features:
+ * 1. Icon: Changes ▸ (collapsed) ↔ ▾ (expanded)
+ * 2. Action Buttons: Shows/hides based on state
+ * 3. Accordion Groups: Collapses siblings in same group when opening
+ * 4. Sidebar Sync: Updates related sidebar content
+ * 5. Last Opened: Remembers last opened crew for reload restoration
+ * 
+ * Accordion Behavior (Pharmacy):
+ * When opening a medication card in pharmacy, other cards in the same
+ * collapse-group automatically close to keep UI clean and focused.
+ * 
+ * Used For:
+ * - Crew medical cards (crew.js)
+ * - Pharmacy medication cards (pharmacy.js)
+ * - Equipment cards (equipment.js)
+ * 
+ * @param {HTMLElement} el - Crew card header element
+ */
+function toggleCrewSection(el) {
+    const body = el.nextElementSibling;
+    const icon = el.querySelector('.toggle-label');
+    const actionBtns = el.querySelectorAll('.history-action-btn');
+    const isExpanded = body.style.display === "block";
+    
+    body.style.display = isExpanded ? "none" : "block";
+    icon.textContent = isExpanded ? "▸" : "▾";
+    actionBtns.forEach(btn => { btn.style.visibility = isExpanded ? "hidden" : "visible"; });
+    if (el.dataset && el.dataset.sidebarId) {
+        syncSidebarSections(el.dataset.sidebarId, !isExpanded);
+    }
+    // If this header participates in a collapse group, close siblings in the same group when opening
+    const group = el.querySelector('.toggle-label')?.dataset?.collapseGroup || el.dataset.collapseGroup;
+    if (!isExpanded && group) {
+        const container = el.closest('#pharmacy-list') || el.parentElement;
+        if (container) {
+            container.querySelectorAll(`.toggle-label[data-collapse-group="${group}"]`).forEach(lbl => {
+                const header = lbl.closest('.col-header');
+                if (!header || header === el) return;
+                const b = header.nextElementSibling;
+                if (b && b.style.display !== "none") {
+                    b.style.display = "none";
+                    lbl.textContent = ">";
+                    const btns = header.querySelectorAll('.history-action-btn');
+                    btns.forEach(btn => { btn.style.visibility = "hidden"; });
+                }
+            });
+        }
+    }
+    // Remember last opened crew card so we can restore after reloads (e.g., after uploads)
+    if (!isExpanded) {
+        try {
+            const parent = el.closest('.collapsible[data-crew-id]');
+            if (parent) {
+                const crewId = parent.getAttribute('data-crew-id');
+                localStorage.setItem('sailingmed:lastOpenCrew', crewId || '');
+            }
+        } catch (err) { /* ignore */ }
+    }
+}
+
+/**
+ * Toggle sidebar collapsed state.
+ * 
+ * Triggered by sidebar toggle button. Applies state globally to all
+ * sidebars on the page via setSidebarState().
+ * 
+ * @param {HTMLElement} btn - Toggle button element
+ */
+function toggleSidebar(btn) {
+    const sidebar = btn.closest ? btn.closest('.page-sidebar') : btn;
+    if (!sidebar) return;
+    // Toggle global state and apply to all sidebars
+    const nextCollapsed = !globalSidebarCollapsed;
+    setSidebarState(nextCollapsed);
+}
+
+/**
+ * Sync sidebar section visibility with main content sections.
+ * 
+ * When main content section opens/closes, matching sidebar sections
+ * (identified by data-sidebar-section attribute) show/hide accordingly.
+ * 
+ * Example:
+ * ```html
+ * <div data-sidebar-id="crew-medical">Crew Medical</div>
+ * <!-- Opens... -->
+ * <div data-sidebar-section="crew-medical">Related help content</div>
+ * <!-- ^ This shows in sidebar -->
+ * ```
+ * 
+ * @param {string} sectionId - Section identifier to sync
+ * @param {boolean} isOpen - True if section is open
+ */
+function syncSidebarSections(sectionId, isOpen) {
+    if (!sectionId) return;
+    document.querySelectorAll(`[data-sidebar-section="${sectionId}"]`).forEach(sec => {
+        if (isOpen) {
+            sec.classList.remove('hidden');
+        } else {
+            sec.classList.add('hidden');
+        }
+    });
+}
+
+/**
+ * Initialize sidebar state on page load.
+ * 
+ * Initialization Process:
+ * 1. Restores collapsed state from localStorage
+ * 2. Applies state to all sidebars
+ * 3. Syncs sidebar sections with main content collapsible states
+ * 
+ * Called once during startup initialization.
+ */
+function initSidebarSync() {
+    try {
+        const saved = localStorage.getItem(SIDEBAR_STATE_KEY);
+        globalSidebarCollapsed = saved === '1';
+    } catch (err) { /* ignore */ }
+    setSidebarState(globalSidebarCollapsed);
+    document.querySelectorAll('[data-sidebar-id]').forEach(header => {
+        const body = header.nextElementSibling;
+        const isOpen = body && body.style.display === 'block';
+        syncSidebarSections(header.dataset.sidebarId, isOpen);
+    });
+}
+
+/**
+ * Ensure crew data is loaded with concurrency protection.
+ * 
+ * Loading Strategy:
+ * - First call: Initiates loadData(), sets promise
+ * - Concurrent calls: Return existing promise (no duplicate loads)
+ * - Subsequent calls after load: Return immediately (cached flag)
+ * 
+ * Protects against race conditions when multiple tabs/functions
+ * request crew data simultaneously.
+ * 
+ * @returns {Promise<void>} Resolves when crew data loaded
+ */
+async function ensureCrewData() {
+    if (crewDataLoaded) return;
+    if (crewDataPromise) return crewDataPromise;
+    crewDataPromise = loadData()
+        .then(() => { crewDataLoaded = true; crewDataPromise = null; })
+        .catch((err) => { crewDataPromise = null; throw err; });
+    return crewDataPromise;
+}
+
+/**
+ * Navigate to a tab and initialize its content.
+ * 
+ * Tab Switching Process:
+ * 1. Hides all content sections
+ * 2. Removes 'active' class from all tabs
+ * 3. Shows target content section
+ * 4. Adds 'active' class to clicked tab
+ * 5. Updates banner controls visibility
+ * 6. Loads tab-specific data/UI
+ * 
+ * Tab-Specific Initialization:
+ * 
+ * **Chat Tab:**
+ * - Updates UI (mode, privacy state)
+ * - Ensures crew data loaded (for patient selector)
+ * - Loads context sidebar
+ * - Restores collapsible state
+ * - Prefetches prompt preview
+ * 
+ * **Settings Tab:**
+ * - Loads settings UI
+ * - Loads crew credentials
+ * - Loads workspace switcher
+ * - Loads context sidebar
+ * 
+ * **CrewMedical / VesselCrewInfo Tabs:**
+ * - Ensures crew data loaded
+ * - Loads vessel data (VesselCrewInfo only)
+ * - Loads context sidebar
+ * 
+ * **OnboardEquipment Tab:**
+ * - Loads equipment list
+ * - Preloads pharmacy data
+ * - Loads context sidebar
+ * 
+ * @param {Event} e - Click event
+ * @param {string} n - Tab name/ID to show
+ */
+async function showTab(trigger, n) {
+    document.querySelectorAll('.content').forEach(c=>c.style.display='none');
+    document.querySelectorAll('.tab').forEach(t=>t.classList.remove('active'));
+    document.getElementById(n).style.display='flex'; 
+    const clickedTab = trigger?.currentTarget
+        || (trigger && trigger.nodeType === 1 ? trigger : null)
+        || document.querySelector(`.tab[onclick*="'${n}'"]`);
+    if (clickedTab) {
+        clickedTab.classList.add('active');
+    }
+    toggleBannerControls(n);
+    if (n === 'Chat') updateUI();
+    
+    if(n === 'Settings') {
+        if (typeof loadSettingsUI === 'function') {
+            await loadSettingsUI();
+        }
+        if (typeof loadCrewCredentials === 'function') {
+            loadCrewCredentials();
+        }
+        if (typeof loadWorkspaceSwitcher === 'function') {
+            loadWorkspaceSwitcher();
+        }
+        loadContext('Settings');
+    } else if(n === 'CrewMedical' || n === 'VesselCrewInfo') { 
+        try {
+            await ensureCrewData();
+            if (n === 'VesselCrewInfo' && typeof ensureVesselLoaded === 'function') {
+                await ensureVesselLoaded();
+            }
+        } catch (err) {
+            console.warn('Tab load data failed:', err);
+        }
+        loadContext(n);
+    } else if (n === 'OnboardEquipment') {
+        await ensureMedicalChestLoaded();
+        loadContext(n);
+    }
+    if (n === 'Chat') {
+        try {
+            await ensureCrewData();
+        } catch (err) {
+            console.warn('Chat crew load failed:', err);
+        }
+        loadContext('Chat');
+        if (typeof window.syncStartPanelWithConsultationState === 'function') {
+            window.syncStartPanelWithConsultationState();
+        } else {
+            restoreCollapsibleState('query-form-header', true);
+        }
+        restoreCollapsibleState('triage-pathway-header', false);
+        // Prefetch prompt preview so it is ready when expanded
+        if (typeof refreshPromptPreview === 'function') {
+            refreshPromptPreview();
+        }
+    }
+}
+
+// Ensure inline onclick handlers can always resolve this function.
+window.showTab = showTab;
+
+/**
+ * Load crew, history, and settings data from server.
+ * 
+ * Loading Strategy:
+ * - Concurrent fetch of history/settings on every call
+ * - Optional patient roster reuse for lightweight refresh paths
+ * - Patients: Hard requirement, fails if unavailable
+ * - History: Soft requirement, continues if fails (empty array)
+ * - Settings: Optional, uses defaults if unavailable
+ *
+ * Concurrency Strategy:
+ * - If a refresh is already in flight, concurrent callers share that promise
+ *   unless `options.force === true`
+ *
+ * Lightweight Refresh Mode:
+ * - `options.skipPatients === true` reuses cached roster when available
+ * - This keeps post-chat refreshes fast while still updating history/settings
+ * 
+ * Error Handling:
+ * - History parse failure: Warns and continues with []
+ * - Settings parse failure: Warns and continues with {}
+ * - Patients failure: Throws error and shows graceful UI fallback
+ * 
+ * Race Condition Protection:
+ * If loadCrewData not yet available (script still loading), retries
+ * after 150ms to allow crew.js to finish initializing.
+ * 
+ * Side Effects:
+ * - Sets window.CACHED_SETTINGS for global access
+ * - Calls loadCrewData() to render crew UI
+ * - Sets crewDataLoaded flag
+ * - Updates patient selector dropdown
+ * 
+ * Fallback UI on Error:
+ * - Shows "Unable to load crew data" message
+ * - Provides "Unnamed Crew" option in selectors
+ * - Prevents cascading errors
+ * 
+ * @throws {Error} If patients data unavailable or malformed
+ */
+async function loadData(options = {}) {
+    const opts = {
+        skipPatients: false,
+        force: false,
+        forcePatients: false,
+        ...(options && typeof options === 'object' ? options : {}),
+    };
+    if (!opts.force && loadDataInFlight) {
+        return loadDataInFlight;
+    }
+    loadDataInFlight = (async () => {
+        try {
+            const historyResPromise = fetch('/api/data/history', { credentials: 'same-origin' })
+                .catch((err) => {
+                    console.warn('History request failed before response; continuing without history.', err);
+                    return null;
+                });
+            const settingsResPromise = fetch('/api/data/settings', { credentials: 'same-origin' })
+                .catch((err) => {
+                    console.warn('Settings request failed before response; using defaults.', err);
+                    return null;
+                });
+
+            const shouldFetchPatients = !opts.skipPatients
+                || opts.forcePatients
+                || !Array.isArray(cachedPatientsRoster)
+                || !cachedPatientsRoster.length;
+
+            let data = Array.isArray(cachedPatientsRoster) ? cachedPatientsRoster : [];
+            if (shouldFetchPatients) {
+                // Prioritize patient roster fetch so #p-select is usable as early as possible.
+                const patientsResPromise = fetch('/api/data/patients', { credentials: 'same-origin' });
+                const patientOptionsPromise = fetch('/api/patients/options', { credentials: 'same-origin' })
+                    .then(async (res) => {
+                        if (!res.ok) return null;
+                        const optionsData = await res.json();
+                        return Array.isArray(optionsData) ? optionsData : null;
+                    })
+                    .then((optionsData) => {
+                        if (Array.isArray(optionsData) && optionsData.length) {
+                            populateCrewSelectFast(optionsData);
+                            cacheCrewOptionsFast(optionsData);
+                        }
+                        return optionsData;
+                    })
+                    .catch((err) => {
+                        console.warn('Patient options request failed before response; falling back to full patients payload.', err);
+                        return null;
+                    });
+
+                const res = await patientsResPromise;
+                if (!res.ok) {
+                    if (!Array.isArray(cachedPatientsRoster) || !cachedPatientsRoster.length) {
+                        throw new Error(`Patients request failed: ${res.status}`);
+                    }
+                    console.warn('Patients request failed; reusing cached roster. Status:', res.status);
+                    data = cachedPatientsRoster;
+                } else {
+                    data = await res.json();
+                    if (!Array.isArray(data)) throw new Error('Unexpected patients data format');
+                    cachedPatientsRoster = data;
+                    populateCrewSelectFast(data);
+                    cacheCrewOptionsFast(data);
+                }
+
+                // Ensure fast options request has settled; failures are already handled.
+                await patientOptionsPromise;
+            } else {
+                // Reuse cached roster for lightweight refreshes (e.g., after chat completion).
+                populateCrewSelectFast(data);
+            }
+
+            const [historyRes, settingsRes] = await Promise.all([historyResPromise, settingsResPromise]);
+            if (!settingsRes || !settingsRes.ok) console.warn('Settings request failed:', settingsRes ? settingsRes.status : 'network');
+
+            // Parse history, but never block crew rendering if it fails
+            let history = [];
+            if (historyRes && historyRes.ok) {
+                try {
+                    const parsedHistory = await historyRes.json();
+                    history = Array.isArray(parsedHistory) ? parsedHistory : [];
+                } catch (err) {
+                    console.warn('History parse failed; continuing without history.', err);
+                    history = [];
+                }
+            } else {
+                console.warn('History request failed; continuing without history. Status:', historyRes ? historyRes.status : 'network');
+            }
+
+            // Parse settings (optional)
+            let settings = {};
+            try {
+                settings = (settingsRes && settingsRes.ok) ? await settingsRes.json() : {};
+            } catch (err) {
+                console.warn('Settings parse failed, using defaults.', err);
+            }
+            window.CACHED_SETTINGS = settings || {};
+
+            // Ensure crew renderer is ready; retry briefly if the script is still loading
+            if (typeof loadCrewData !== 'function') {
+                console.warn('loadCrewData missing; retrying shortly…');
+                setTimeout(() => {
+                    if (typeof loadCrewData === 'function') {
+                        loadCrewData(data, history, settings || {});
+                    } else {
+                        console.error('loadCrewData still missing after retry.');
+                    }
+                }, 150);
+                return;
+            }
+            loadCrewData(data, history, settings || {});
+            crewDataLoaded = true;
+
+        } catch (err) {
+            console.error('Failed to load crew data', err);
+            window.CACHED_SETTINGS = window.CACHED_SETTINGS || {};
+            // Gracefully clear UI to avoid JS errors
+            const pSelect = document.getElementById('p-select');
+            if (pSelect) pSelect.innerHTML = '<option value=\"\">Unnamed Crew Member</option>';
+            const medicalContainer = document.getElementById('crew-medical-list');
+            if (medicalContainer) medicalContainer.innerHTML = `<div style="color:#666;">Unable to load crew data. ${err.message}</div>`;
+            const infoContainer = document.getElementById('crew-info-list');
+            if (infoContainer) infoContainer.innerHTML = `<div style="color:#666;">Unable to load crew data. ${err.message}</div>`;
+        } finally {
+            loadDataInFlight = null;
+        }
+    })();
+    return loadDataInFlight;
+}
+
+/**
+ * Show/hide tab-specific banner controls.
+ * 
+ * Banner Control Groups:
+ * 
+ * **Chat Tab:**
+ * - Mode selector (triage/inquiry)
+ * - Privacy toggle (logging on/off)
+ * - Patient selector
+ * 
+ * **Crew Health & Log Tab:**
+ * - Export all medical records button
+ * 
+ * **Vessel & Crew Info Tab:**
+ * - Export crew CSV button (for border crossings)
+ * - Export immigration zip button (crew + vessel package)
+ * 
+ * Other tabs: All banner controls hidden
+ * 
+ * @param {string} activeTab - Current active tab name
+ */
+function toggleBannerControls(activeTab) {
+    const triageControls = document.getElementById('banner-controls-triage');
+    const crewControls = document.getElementById('banner-controls-crew');
+    const medExportAll = document.getElementById('crew-med-export-all-btn');
+    const crewCsvBtn = document.getElementById('crew-csv-btn');
+    const immigrationZipBtn = document.getElementById('crew-immigration-zip-btn');
+    if (triageControls) triageControls.style.display = activeTab === 'Chat' ? 'flex' : 'none';
+    if (crewControls) crewControls.style.display = (activeTab === 'CrewMedical' || activeTab === 'VesselCrewInfo') ? 'flex' : 'none';
+    if (medExportAll) medExportAll.style.display = activeTab === 'CrewMedical' ? 'inline-flex' : 'none';
+    if (crewCsvBtn) crewCsvBtn.style.display = activeTab === 'VesselCrewInfo' ? 'inline-flex' : 'none';
+    if (immigrationZipBtn) immigrationZipBtn.style.display = activeTab === 'VesselCrewInfo' ? 'inline-flex' : 'none';
+}
+
+window.toggleBannerControls = toggleBannerControls;
+
+/**
+ * Application initialization on page load.
+ * 
+ * Initialization Sequence:
+ * 1. **Crew Data**: Load immediately (used by multiple tabs)
+ * 2. **Medical Chest**: Preload for fast access
+ *    - preloadPharmacy(): Loads inventory
+ *    - loadWhoMedsFromServer(): Loads WHO reference list
+ *    - ensurePharmacyLabels(): Loads user labels
+ *    - loadPharmacy(): Pre-renders pharmacy UI
+ * 3. **Chat UI**: Initialize with updateUI()
+ * 4. **Banner Controls**: Show Chat tab controls
+ * 5. **Sidebar**: Initialize and restore state
+ * 6. **Query Form**: Restore collapsed state
+ * 7. **Last Chat**: Restore previous session view
+ * 
+ * Preloading Strategy:
+ * Medical Chest is preloaded because:
+ * - Frequently accessed (medications needed for consultations)
+ * - Large dataset (better to load early than wait on tab switch)
+ * - Improves perceived performance
+ * 
+ * Error Handling:
+ * All preload operations use .catch() to prevent blocking page load
+ * if individual components fail.
+ * 
+ * Called By: Browser on page load completion
+ */
+function runCriticalStartup() {
+    if (startupCriticalInitDone) return;
+    startupCriticalInitDone = true;
+    migrateCollapsiblePrefs();
+    // Use cached lightweight crew options immediately to avoid a blank selector
+    // while network requests are still in flight.
+    hydrateCrewSelectFromCache();
+    startupCrewReadyPromise = ensureCrewData().catch((err) => {
+        console.warn('ensureCrewData failed during critical boot:', err);
+    });
+    updateUI();
+    toggleBannerControls('Chat');
+    initSidebarSync();
+    if (typeof window.syncStartPanelWithConsultationState === 'function') {
+        window.syncStartPanelWithConsultationState();
+    } else {
+        restoreCollapsibleState('query-form-header', true);
+    }
+    restoreCollapsibleState('triage-pathway-header', false);
+}
+
+function runDeferredStartup() {
+    if (startupDeferredInitDone) return;
+    startupDeferredInitDone = true;
+    const preloadMedicalChest = () => {
+        // Preload Medical Chest after crew dropdown hydration to prioritize chat readiness.
+        if (typeof preloadPharmacy === 'function') {
+            preloadPharmacy().catch((err) => console.warn('preloadPharmacy failed:', err));
+        }
+        if (typeof loadWhoMedsFromServer === 'function') {
+            loadWhoMedsFromServer().catch((err) => console.warn('preload WHO meds failed:', err));
+        }
+        if (typeof ensurePharmacyLabels === 'function') {
+            ensurePharmacyLabels().catch((err) => console.warn('preload pharmacy labels failed:', err));
+        }
+        if (typeof loadPharmacy === 'function') {
+            loadPharmacy(); // pre-warm Medical Chest so list is ready when tab opens
+        }
+    };
+    const crewReady = startupCrewReadyPromise || ensureCrewData().catch((err) => {
+        console.warn('ensureCrewData failed during deferred boot:', err);
+    });
+    crewReady.finally(() => {
+        if (typeof window.requestIdleCallback === 'function') {
+            window.requestIdleCallback(preloadMedicalChest, { timeout: 800 });
+        } else {
+            setTimeout(preloadMedicalChest, 0);
+        }
+    });
+    restoreLastChatView();
+}
+
+document.addEventListener('DOMContentLoaded', runCriticalStartup);
+window.addEventListener('load', runDeferredStartup);
+
+// If scripts are injected late, run startup paths immediately as needed.
+if (document.readyState === 'interactive' || document.readyState === 'complete') {
+    runCriticalStartup();
+}
+if (document.readyState === 'complete') {
+    runDeferredStartup();
+}
+
+// Ensure loadCrewData exists before any calls (safety for race conditions)
+if (typeof window.loadCrewData !== 'function') {
+    console.error('window.loadCrewData is not defined at main.js load time.');
+}
+
+/**
+ * Restore collapsible section state from localStorage.
+ * 
+ * Restoration Process:
+ * 1. Looks for stored state in localStorage (by header ID or data-pref-key)
+ * 2. Applies stored state or uses default if not found
+ * 3. Updates icon (▸/▾)
+ * 4. Special handling for prompt preview (ARIA + refresh button)
+ * 
+ * Special Cases:
+ * 
+ * **Prompt Preview Header:**
+ * - Updates aria-expanded attribute
+ * - Shows/hides prompt refresh inline button
+ * 
+ * Use Cases:
+ * - Query form: Restore expanded/collapsed state
+ * - Prompt preview: Restore editor visibility
+ * - Settings sections: Restore user preferences
+ * 
+ * @param {string} headerId - ID of header element
+ * @param {boolean} defaultOpen - Default state if no stored preference
+ */
+function restoreCollapsibleState(headerId, defaultOpen = true) {
+    const header = document.getElementById(headerId);
+    if (!header) return;
+    const body = header.nextElementSibling;
+    if (!body) return;
+    let isOpen = defaultOpen;
+    const key = header.dataset?.prefKey || headerId;
+    try {
+        const stored = localStorage.getItem(key);
+        if (stored !== null) {
+            isOpen = stored === 'true';
+        }
+    } catch (err) { /* ignore */ }
+    body.style.display = isOpen ? 'block' : 'none';
+    const icon = header.querySelector('.detail-icon');
+    if (icon) icon.textContent = isOpen ? '▾' : '▸';
+    if (headerId === 'prompt-preview-header') {
+        const refreshInline = document.getElementById('prompt-refresh-inline');
+        if (refreshInline) refreshInline.style.display = isOpen ? 'flex' : 'none';
+        header.setAttribute('aria-expanded', isOpen ? 'true' : 'false');
+    }
+}
+
+/**
+ * Load context sidebar content for tab.
+ * 
+ * Legacy Function:
+ * Previously loaded remote context content. Now sidebars are static HTML,
+ * so this is a no-op but kept for compatibility.
+ * 
+ * @param {string} tabName - Tab name (no longer used)
+ * @deprecated Sidebars are now static HTML
+ */
+async function loadContext(tabName) {
+    // Sidebars are now fully static HTML; no remote context to fetch.
+    return;
+}
+
+/**
+ * Restore the most recent chat session on page load.
+ * 
+ * Restoration Process:
+ * 1. Checks display element is empty (fresh load)
+ * 2. Checks skipLastChat flag (user may have cleared it)
+ * 3. Fetches history from server
+ * 4. Gets most recent entry
+ * 5. Attempts active session restore via chat.js helper
+ * 6. Falls back to read-only rendering if active restore is unavailable
+ * 
+ * Display Format:
+ * - Title: "Last Session — [Patient] ([Date])"
+ * - Query section
+ * - Response section
+ * 
+ * Use Cases:
+ * - User returns to page: See previous consultation
+ * - Page refresh: Maintain context
+ * - Quick reference: Check recent advice
+ * 
+ * Skip Conditions:
+ * - User cleared display (skipLastChat=1)
+ * - Display already has content (manual chat run)
+ * - No history available
+ * - History fetch fails
+ * 
+ * Integration:
+ * Respects skipLastChat flag set when starting a new consultation clears prior
+ * on-screen results.
+ */
+async function restoreLastChatView() {
+    try {
+        const display = document.getElementById('display');
+        if (!display || display.children.length > 0) return;
+        try {
+            const skip = localStorage.getItem('sailingmed:skipLastChat');
+            if (skip === '1') return;
+        } catch (err) { /* ignore */ }
+        const res = await fetch('/api/data/history', { credentials: 'same-origin' });
+        if (!res.ok) return;
+        const history = await res.json();
+        if (!Array.isArray(history) || history.length === 0) return;
+        const toTimestamp = (entry) => {
+            if (!entry || typeof entry !== 'object') return Number.NEGATIVE_INFINITY;
+            const raw = entry.updated_at || entry.date || '';
+            if (!raw) return Number.NEGATIVE_INFINITY;
+            const normalized = raw.includes('T') ? raw : raw.replace(' ', 'T');
+            const ts = Date.parse(normalized);
+            return Number.isNaN(ts) ? Number.NEGATIVE_INFINITY : ts;
+        };
+        const sortedHistory = history.slice().sort((a, b) => toTimestamp(b) - toTimestamp(a));
+        const last = sortedHistory[0];
+        if (!last) return;
+        if (typeof window.restoreHistoryEntrySession === 'function') {
+            try {
+                const restored = window.restoreHistoryEntrySession(last, {
+                    focusInput: false,
+                    forceLoggingOn: true,
+                    notifyRestored: false,
+                    allowTakeover: false,
+                });
+                if (restored) return;
+            } catch (err) {
+                console.warn('Failed to restore active last chat session', err);
+            }
+        }
+        const parseTranscript = (entry) => {
+            if (!entry) return { messages: [] };
+            if (entry.response && typeof entry.response === 'object' && Array.isArray(entry.response.messages)) {
+                return { messages: entry.response.messages, meta: entry.response.meta || {} };
+            }
+            if (typeof entry.response === 'string' && entry.response.trim().startsWith('{')) {
+                try {
+                    const parsed = JSON.parse(entry.response);
+                    if (parsed && Array.isArray(parsed.messages)) {
+                        return { messages: parsed.messages, meta: parsed.meta || {} };
+                    }
+                } catch (err) { /* ignore */ }
+            }
+            return { messages: [] };
+        };
+        const transcript = parseTranscript(last);
+        if (transcript.messages.length && typeof window.renderTranscript === 'function') {
+            display.innerHTML = `
+                <div class="response-block" style="border-left-color:var(--inquiry);">
+                    <div style="font-weight:800; margin-bottom:6px;">Last Consultation (read-only) — ${last.patient || 'Unknown'} (${last.date || ''})</div>
+                    <div style="font-size:12px; color:#555;">Use the Consultation Log to restore and continue this session.</div>
+                </div>
+            `;
+            window.renderTranscript(transcript.messages, { append: true });
+            return;
+        }
+        const parse = (txt) => renderAssistantMarkdownMain(txt || '');
+        const responseHtml = parse(last.response || '');
+        const queryHtml = parse(last.query || '');
+        display.innerHTML = `
+            <div class="response-block">
+                <div style="font-weight:800; margin-bottom:6px;">Last Session — ${last.patient || 'Unknown'} (${last.date || ''})</div>
+                <div style="margin-bottom:8px;"><strong>Query:</strong><br>${queryHtml}</div>
+                <div><strong>Response:</strong><br>${responseHtml}</div>
+            </div>
+        `;
+    } catch (err) {
+        console.warn('Failed to restore last chat view', err);
+    } finally {
+        if (typeof window.syncStartPanelWithConsultationState === 'function') {
+            window.syncStartPanelWithConsultationState();
+        }
+    }
+}
+
+/**
+ * Search across all medical inventories.
+ * 
+ * Search Scope:
+ * - **all**: Pharmaceuticals + Equipment + Consumables
+ * - **pharma**: Medications only
+ * - **equipment**: Durable medical equipment only
+ * - **consumables**: Single-use supplies only
+ * 
+ * Search Fields:
+ * 
+ * **Pharmaceuticals:**
+ * - Generic name, brand name
+ * - Indication, dosage
+ * - Storage location, notes
+ * 
+ * **Equipment/Consumables:**
+ * - Item name
+ * - Storage location
+ * - Notes, quantity
+ * 
+ * Results Display:
+ * - Grouped by category (Pharmaceuticals, Equipment, Consumables)
+ * - Collapsible result sections
+ * - Shows count per category
+ * - Item details (title, detail, storage location)
+ * 
+ * Use Cases:
+ * - "Where is the amoxicillin?"
+ * - "Do we have any splints?"
+ * - "What's in Medical Bag 3?"
+ * - "Find all antibiotics"
+ * 
+ * Performance:
+ * Concurrent fetch of inventory and tools data for fast results.
+ * Case-insensitive search for better UX.
+ */
+async function searchMedicalChest() {
+    const input = document.getElementById('medchest-search-input');
+    const scopeSel = document.getElementById('medchest-search-scope');
+    const resultsBox = document.getElementById('medchest-search-results');
+    if (!input || !scopeSel || !resultsBox) return;
+    const q = (input.value || '').trim().toLowerCase();
+    const scope = scopeSel.value || 'all';
+    if (!q) {
+        resultsBox.innerHTML = '<div style="color:#b71c1c;">Enter a search term.</div>';
+        return;
+    }
+    resultsBox.innerHTML = '<div style="color:#555;">Searching…</div>';
+    try {
+        const wantPharma = scope === 'all' || scope === 'pharma';
+        const wantEquip = scope === 'all' || scope === 'equipment' || scope === 'consumables';
+        const [invData, toolsData] = await Promise.all([
+            wantPharma ? fetch('/api/data/inventory', { credentials: 'same-origin' }).then(r => r.json()) : Promise.resolve([]),
+            wantEquip ? fetch('/api/data/tools', { credentials: 'same-origin' }).then(r => r.json()) : Promise.resolve([]),
+        ]);
+        const results = [];
+        if (wantPharma && Array.isArray(invData)) {
+            invData.forEach(m => {
+                const hay = [m.genericName, m.brandName, m.primaryIndication, m.standardDosage, m.storageLocation, m.notes].join(' ').toLowerCase();
+                if (hay.includes(q)) {
+                    results.push({ section: 'Pharmaceuticals', title: m.genericName || m.brandName || 'Medication', detail: m.strength || '', extra: m.storageLocation || '' });
+                }
+            });
+        }
+        if (wantEquip && Array.isArray(toolsData)) {
+            toolsData.forEach(t => {
+                const hay = [t.name, t.storageLocation, t.notes, t.quantity].join(' ').toLowerCase();
+                const isConsumable = (t.type || '').toLowerCase() === 'consumable';
+                const sec = isConsumable ? 'Consumables' : 'Equipment';
+                if ((scope === 'consumables' && !isConsumable) || (scope === 'equipment' && isConsumable)) return;
+                if (hay.includes(q)) {
+                    results.push({ section: sec, title: t.name || 'Item', detail: t.quantity || '', extra: t.storageLocation || '' });
+                }
+            });
+        }
+        if (!results.length) {
+            resultsBox.innerHTML = '<div style="color:#2c3e50;">No matches found.</div>';
+            return;
+        }
+        const grouped = results.reduce((acc, r) => {
+            acc[r.section] = acc[r.section] || [];
+            acc[r.section].push(r);
+            return acc;
+        }, {});
+        let html = '';
+        Object.keys(grouped).forEach(sec => {
+            const list = grouped[sec];
+            html += `
+                <div style="margin-bottom:10px; border:1px solid #d8e2f5; border-radius:8px;">
+                    <div style="padding:8px 10px; background:#eef3ff; cursor:pointer; font-weight:700;" onclick="toggleSearchResults(this)">
+                        ${sec} — ${list.length} match(es)
+                        <span style="float:right;">▾</span>
+                    </div>
+                    <div class="medchest-search-results-body" style="padding:8px 10px; display:none; background:#fff;">
+                        ${list.map(item => `
+                            <div style="padding:6px 0; border-bottom:1px solid #eee;">
+                                <div style="font-weight:700;">${item.title}</div>
+                                <div style="font-size:12px; color:#444;">${item.detail || ''}</div>
+                                <div style="font-size:12px; color:#666;">${item.extra || ''}</div>
+                            </div>
+                        `).join('')}
+                    </div>
+                </div>
+            `;
+        });
+        resultsBox.innerHTML = html;
+    } catch (err) {
+        resultsBox.innerHTML = `<div style="color:#b71c1c;">Search failed: ${err.message}</div>`;
+    }
+}
+
+/**
+ * Toggle search result section visibility.
+ * 
+ * Each category (Pharmaceuticals, Equipment, Consumables) is a
+ * collapsible section. This toggles individual sections.
+ * 
+ * @param {HTMLElement} headerEl - Result category header element
+ */
+function toggleSearchResults(headerEl) {
+    const body = headerEl.nextElementSibling;
+    if (!body) return;
+    const isShown = body.style.display === 'block';
+    body.style.display = isShown ? 'none' : 'block';
+    const arrow = headerEl.querySelector('span');
+    if (arrow) arrow.textContent = isShown ? '▸' : '▾';
+}
+
+// expose for inline handlers
+window.searchMedicalChest = searchMedicalChest;
+window.toggleSearchResults = toggleSearchResults;
+
+
+//
+
+// MAINTENANCE NOTE
+// Historical auto-generated note blocks were removed because they were repetitive and
+// obscured real logic changes during review. Keep focused comments close to behavior-
+// critical code paths (UI state hydration, async fetch lifecycle, and mode-gated
+// controls) so maintenance remains actionable.

static/js/pharmacy.js

@@ -0,0 +1,1723 @@
+/* =============================================================================
+ * Author: Rick Escher
+ * Project: SailingMedAdvisor
+ * Context: Google HAI-DEF Framework
+ * Models: Google MedGemmas
+ * Program: Kaggle Impact Challenge
+ * ========================================================================== */
+/*
+File: static/js/pharmacy.js
+Author notes: Client-side controller for the Medical Chest (pharmaceuticals).
+I handle rendering, edits, autosave, WHO imports, expiry tracking, and
+single-card expansion behavior.
+*/
+
+let pharmacyCache = [];
+let pharmacyFetchPromise = null;
+const pharmacySaveTimers = {};
+const DEFAULT_USER_LABELS = ['Antibiotic', 'Analgesic', 'Cardiac', 'Respiratory', 'Gastrointestinal', 'Endocrine', 'Emergency'];
+let pharmacyLabelsCache = null;
+let WHO_RECOMMENDED_MEDS = [];
+let whoMedLoaded = false;
+
+const TIER_OPTIONS = [
+    { value: '', label: 'Select...' },
+    { value: 'Tier 1', label: 'Tier 1 — Emergency & Surgical' },
+    { value: 'Tier 2', label: 'Tier 2 — Stabilization & Acute' },
+    { value: 'Tier 3', label: 'Tier 3 — Supportive & Maintenance' },
+];
+
+const TIER_SUBCATEGORIES = {
+    'Tier 1': [
+        'Local Anesthesia',
+        'Respiratory/Anaphylaxis',
+        'Critical Antibiotics (Systemic)',
+        'Critical Antibiotics (Ophthalmic)',
+        'Emergency Steroids',
+    ],
+    'Tier 2': [
+        'Analgesics (Moderate/Severe Pain)',
+        'NSAIDs (Mild/Moderate Pain)',
+        'Topical Antiseptics/Antibiotics',
+        'Standard Antibiotics/Antivirals',
+        'Antihistamines/Steroid Creams',
+    ],
+    'Tier 3': [
+        'Gastrointestinal (Nausea/Diarrhea/Reflux)',
+        'Hydration/Electrolytes',
+        'Dermatological (Fungal/Parasitic)',
+        'Diagnostic/Maintenance',
+        'Chronic/Behavioral',
+    ],
+};
+
+/**
+ * buildTierOptions: function-level behavior note for maintainers.
+ * Keep this block synchronized with implementation changes.
+ */
+function buildTierOptions(selected = '') {
+    return TIER_OPTIONS.map((opt) => `<option value="${escapeHtml(opt.value)}" ${opt.value === selected ? 'selected' : ''}>${escapeHtml(opt.label)}</option>`).join('');
+}
+
+/**
+ * buildTierSubcategoryOptions: function-level behavior note for maintainers.
+ * Keep this block synchronized with implementation changes.
+ */
+function buildTierSubcategoryOptions(tier = '', selected = '') {
+    const options = [{ value: '', label: 'Select...' }];
+    const list = TIER_SUBCATEGORIES[tier] || [];
+    list.forEach((entry) => options.push({ value: entry, label: entry }));
+    return options.map((opt) => `<option value="${escapeHtml(opt.value)}" ${opt.value === selected ? 'selected' : ''}>${escapeHtml(opt.label)}</option>`).join('');
+}
+
+/**
+ * handleMedTierChange: function-level behavior note for maintainers.
+ * Keep this block synchronized with implementation changes.
+ */
+function handleMedTierChange(medId) {
+    const tierEl = document.getElementById(`tier-${medId}`);
+    const catEl = document.getElementById(`tiercat-${medId}`);
+    if (!tierEl || !catEl) return;
+    const tierVal = tierEl.value || '';
+    const current = catEl.value || '';
+    catEl.innerHTML = buildTierSubcategoryOptions(tierVal, current);
+    if (current && !(TIER_SUBCATEGORIES[tierVal] || []).includes(current)) {
+        catEl.value = '';
+    }
+    scheduleSaveMedication(medId);
+}
+
+/**
+ * initNewMedTierControls: function-level behavior note for maintainers.
+ * Keep this block synchronized with implementation changes.
+ */
+function initNewMedTierControls() {
+    const tierEl = document.getElementById('med-new-tier');
+    const catEl = document.getElementById('med-new-tiercat');
+    if (!tierEl || !catEl) return;
+    tierEl.innerHTML = buildTierOptions(tierEl.value || '');
+    catEl.innerHTML = buildTierSubcategoryOptions(tierEl.value || '', catEl.value || '');
+    if (!tierEl.dataset.bound) {
+        tierEl.dataset.bound = 'true';
+        tierEl.addEventListener('change', () => {
+            catEl.innerHTML = buildTierSubcategoryOptions(tierEl.value || '', '');
+        });
+    }
+}
+
+// --- Shared utilities -------------------------------------------------------
+
+// Small, collision-resistant id generator for client-created meds/expiries.
+function uid(prefix = 'id') {
+    // Prefer crypto for true randomness; fallback to timestamp + random.
+    if (window.crypto && crypto.randomUUID) return `${prefix}-${crypto.randomUUID()}`;
+    return `${prefix}-${Date.now()}-${Math.floor(Math.random() * 1e6)}`;
+}
+
+// Lightweight toast helper to surface success/error without blocking alerts.
+function showToast(message, isError = false) {
+    let el = document.getElementById('pharmacy-toast');
+    if (!el) {
+        el = document.createElement('div');
+        el.id = 'pharmacy-toast';
+        el.style.cssText =
+            'position:fixed; bottom:20px; right:20px; padding:12px 16px; border-radius:8px; box-shadow:0 6px 18px rgba(0,0,0,0.2); font-weight:800; z-index:9999; display:none; min-width:220px;';
+        document.body.appendChild(el);
+    }
+    el.textContent = message;
+    el.style.display = 'block';
+    el.style.background = isError ? '#ffebee' : '#e8f5e9';
+    el.style.color = isError ? '#c62828' : '#2e7d32';
+    el.style.border = `1px solid ${isError ? '#ef5350' : '#81c784'}`;
+    clearTimeout(el._timer);
+    el._timer = setTimeout(() => {
+        el.style.display = 'none';
+    }, 4000);
+}
+
+// Wrapper around /api/data/inventory with consistent error handling.
+async function fetchInventory(options = {}) {
+    const headers = { ...(options.headers || {}) };
+    const res = await fetch('/api/data/inventory', { credentials: 'same-origin', ...options, headers });
+    const data = await res.json().catch(() => ({}));
+    if (!res.ok || data.error) {
+        throw new Error(data.error || `Status ${res.status}`);
+    }
+    return data;
+}
+
+/**
+ * updatePharmacyCount: function-level behavior note for maintainers.
+ * Keep this block synchronized with implementation changes.
+ */
+function updatePharmacyCount(count) {
+    const el = document.getElementById('pharmacy-count');
+    if (el) {
+        el.textContent = `(${count})`;
+    }
+}
+
+/**
+ * syncPharmacyCountFromDOM: function-level behavior note for maintainers.
+ * Keep this block synchronized with implementation changes.
+ */
+function syncPharmacyCountFromDOM() {
+    const list = document.getElementById('pharmacy-list');
+    if (!list) {
+        updatePharmacyCount(0);
+        return;
+    }
+    const domCount = list.querySelectorAll('.history-item').length;
+    updatePharmacyCount(domCount);
+}
+
+/**
+ * observePharmacyList: function-level behavior note for maintainers.
+ * Keep this block synchronized with implementation changes.
+ */
+function observePharmacyList() {
+    const list = document.getElementById('pharmacy-list');
+    if (!list || list.dataset.countObserver === 'true') return;
+    const observer = new MutationObserver(() => syncPharmacyCountFromDOM());
+    observer.observe(list, { childList: true, subtree: true });
+    list.dataset.countObserver = 'true';
+    // Initial sync
+    syncPharmacyCountFromDOM();
+}
+
+/**
+ * getTextareaHeights: function-level behavior note for maintainers.
+ * Keep this block synchronized with implementation changes.
+ */
+function getTextareaHeights() {
+    const map = {};
+    document.querySelectorAll('#pharmacy-list textarea').forEach((el) => {
+        if (el.id && el.style && el.style.height) {
+            map[el.id] = el.style.height;
+        }
+    });
+    return map;
+}
+
+/**
+ * normalizeUserLabels: function-level behavior note for maintainers.
+ * Keep this block synchronized with implementation changes.
+ */
+function normalizeUserLabels(list) {
+    if (!Array.isArray(list)) return [...DEFAULT_USER_LABELS];
+    const seen = new Set();
+    return list
+        .map((v) => (typeof v === 'string' ? v.trim() : ''))
+        .filter(Boolean)
+        .filter((v) => {
+            const key = v.toLowerCase();
+            if (seen.has(key)) return false;
+            seen.add(key);
+            return true;
+        });
+}
+
+async function ensurePharmacyLabels() {
+    if (window.CACHED_SETTINGS && Array.isArray(window.CACHED_SETTINGS.pharmacy_labels)) {
+        const normalized = normalizeUserLabels(window.CACHED_SETTINGS.pharmacy_labels);
+        if (!pharmacyLabelsCache || normalized.join('|') !== pharmacyLabelsCache.join('|')) {
+            pharmacyLabelsCache = normalized;
+        }
+    }
+    if (pharmacyLabelsCache && pharmacyLabelsCache.length) return pharmacyLabelsCache;
+    try {
+        const url = '/api/data/settings';
+        const data = await fetchJson(url);
+        if (data && Array.isArray(data.pharmacy_labels)) {
+            pharmacyLabelsCache = normalizeUserLabels(data.pharmacy_labels);
+        }
+    } catch (err) {
+        console.warn('[pharmacy] failed to load user labels, using defaults', err);
+    }
+    if (!pharmacyLabelsCache || !pharmacyLabelsCache.length) {
+        pharmacyLabelsCache = [...DEFAULT_USER_LABELS];
+    }
+    return pharmacyLabelsCache;
+}
+
+/**
+ * getPharmacyLabels: function-level behavior note for maintainers.
+ * Keep this block synchronized with implementation changes.
+ */
+function getPharmacyLabels() {
+    return pharmacyLabelsCache && pharmacyLabelsCache.length ? [...pharmacyLabelsCache] : [...DEFAULT_USER_LABELS];
+}
+
+/**
+ * renderUserLabelOptions: function-level behavior note for maintainers.
+ * Keep this block synchronized with implementation changes.
+ */
+function renderUserLabelOptions(selectedValue = '') {
+    const selected = (selectedValue || '').trim();
+    const labels = getPharmacyLabels();
+    const isCustom = !!selected && !labels.includes(selected);
+    const options = [
+        '<option value="">Select...</option>',
+        ...labels.map((label) => `<option value="${label}"${label === selected ? ' selected' : ''}>${label}</option>`),
+        `<option value="__custom"${isCustom ? ' selected' : ''}>Custom...</option>`,
+    ];
+    return {
+        optionsHtml: options.join(''),
+        showCustom: isCustom,
+        customValue: isCustom ? selected : '',
+    };
+}
+
+/**
+ * populateNewMedUserLabelSelect: function-level behavior note for maintainers.
+ * Keep this block synchronized with implementation changes.
+ */
+function populateNewMedUserLabelSelect() {
+    const select = document.getElementById('med-new-sort');
+    const custom = document.getElementById('med-new-sort-custom');
+    if (!select || !custom) return;
+    const labels = getPharmacyLabels();
+    const selectVal = select.value;
+    const customVal = custom.value;
+    const current = selectVal === '__custom' ? customVal : selectVal;
+    const isCustom = !!current && !labels.includes(current);
+    const opts = [
+        '<option value="">Select...</option>',
+        ...labels.map((label) => `<option value="${label}">${label}</option>`),
+        '<option value="__custom">Custom...</option>',
+    ];
+    select.innerHTML = opts.join('');
+    select.value = isCustom ? '__custom' : (labels.includes(current) ? current : '');
+    custom.style.display = isCustom ? 'block' : 'none';
+    if (isCustom) custom.value = current;
+    else if (select.value !== '__custom') custom.value = '';
+}
+
+/**
+ * refreshPharmacyLabelsFromSettings: function-level behavior note for maintainers.
+ * Keep this block synchronized with implementation changes.
+ */
+function refreshPharmacyLabelsFromSettings(list) {
+    const normalized = normalizeUserLabels(Array.isArray(list) ? list : pharmacyLabelsCache || DEFAULT_USER_LABELS);
+    pharmacyLabelsCache = normalized;
+    populateNewMedUserLabelSelect();
+    const listEl = document.getElementById('pharmacy-list');
+    if (listEl && pharmacyCache && pharmacyCache.length) {
+        const openIds = getOpenMedIds();
+        const textHeights = getTextareaHeights();
+        renderPharmacy(pharmacyCache, openIds, textHeights);
+    }
+}
+
+/**
+ * handleSortCategoryChange: function-level behavior note for maintainers.
+ * Keep this block synchronized with implementation changes.
+ */
+function handleSortCategoryChange(id) {
+    const select = document.getElementById(`sort-${id}`);
+    const custom = document.getElementById(`sort-custom-${id}`);
+    if (!select || !custom) return;
+    const val = select.value;
+    const isCustom = val === '__custom';
+    custom.style.display = isCustom ? 'block' : 'none';
+    if (!isCustom) {
+        custom.value = '';
+    }
+    // Avoid rerender when switching to custom so the input stays visible while typing
+    scheduleSaveMedication(id, !isCustom);
+}
+
+/**
+ * toggleCustomSortField: function-level behavior note for maintainers.
+ * Keep this block synchronized with implementation changes.
+ */
+function toggleCustomSortField() {
+    const sel = document.getElementById('med-new-sort');
+    const custom = document.getElementById('med-new-sort-custom');
+    if (!sel || !custom) return;
+    const isCustom = sel.value === '__custom';
+    custom.style.display = isCustom ? 'block' : 'none';
+    if (!isCustom) custom.value = '';
+}
+
+/**
+ * Normalize a purchase/expiry entry to ensure consistent structure.
+ * 
+ * This is the **client-side equivalent** of the backend's ensure_purchase_defaults.
+ * Purchase entries (also called expiry entries) represent individual batches or
+ * purchases of a medication. Each entry tracks:
+ * - Expiration date for that specific batch
+ * - Quantity received in that batch  
+ * - Manufacturer and batch/lot number for traceability
+ * - Optional notes about storage or source
+ * 
+ * Multiple purchase entries allow tracking different batches of the same medication
+ * that may have different expiration dates - critical for medical inventory management.
+ * 
+ * UI State Management:
+ * --------------------
+ * The `_open` property is UI-only state (not persisted to backend) that controls
+ * whether the notes textarea is expanded by default. This provides a cleaner UI
+ * for entries without notes while allowing quick access when needed.
+ * 
+ * @param {Object} p - Raw purchase/expiry data from server or user input
+ * @param {boolean} open - Whether notes section should be expanded in UI (default: false)
+ * 
+ * @returns {Object} Normalized purchase entry with structure:
+ *   - id {string}: Unique identifier (ph-<uuid>) - stable across saves
+ *   - date {string}: Expiry date in ISO format (YYYY-MM-DD)
+ *   - quantity {string}: Quantity for this batch (can be partial units)
+ *   - notes {string}: Optional notes about batch/storage/source
+ *   - manufacturer {string}: Manufacturer name for this batch
+ *   - batchLot {string}: Batch or lot number from packaging
+ *   - _open {boolean}: UI state - whether notes are expanded (not saved to DB)
+ * 
+ * @example
+ * // New entry (no ID provided)
+ * ensurePurchaseDefaults({
+ *     date: "2026-12-31",
+ *     quantity: "100"
+ * })
+ * // Returns: { id: "ph-abc123...", date: "2026-12-31", quantity: "100", ... }
+ * 
+ * @example  
+ * // Existing entry from server (ID preserved)
+ * ensurePurchaseDefaults({
+ *     id: "ph-12345",
+ *     date: "2025-06-30",
+ *     quantity: "50",
+ *     manufacturer: "Pfizer"
+ * })
+ * // Returns: { id: "ph-12345", date: "2025-06-30", ..., manufacturer: "Pfizer" }
+ * 
+ * Related Functions:
+ * ------------------
+ * - Backend equivalent: ensure_purchase_defaults() in app.py
+ * - Called by: ensurePharmacyDefaults(), renderPurchaseRows()
+ * - Feeds into: collectPurchaseEntries() when saving
+ */
+function ensurePurchaseDefaults(p, open = false) {
+    return {
+        id: p.id || uid('ph'),                    // Generate unique ID if not present
+        date: p.date || '',                       // ISO date string (YYYY-MM-DD)
+        quantity: p.quantity || '',               // Batch quantity (string to allow decimals)
+        notes: p.notes || '',                     // Additional batch information
+        manufacturer: p.manufacturer || '',       // Manufacturer for this batch
+        batchLot: p.batchLot || '',              // Batch/lot number for traceability
+        _open: open                               // UI state: notes section expanded?
+    };
+}
+
+/**
+ * ensurePharmacyDefaults: function-level behavior note for maintainers.
+ * Keep this block synchronized with implementation changes.
+ */
+function ensurePharmacyDefaults(item) {
+    // Normalize a med record; if legacy top-level manufacturer/batch exists, push into first expiry row.
+    const med = {
+        id: item.id || uid('med'),
+        genericName: item.genericName || '',
+        brandName: item.brandName || '',
+        form: item.form || '',
+        strength: item.strength || '',
+        formStrength: item.formStrength || '',
+        currentQuantity: item.currentQuantity || '', // legacy; derived from purchase history
+        minThreshold: item.minThreshold || '',
+        unit: item.unit || '',
+        storageLocation: item.storageLocation || '',
+        expiryDate: item.expiryDate || '',
+        controlled: !!item.controlled,
+        primaryIndication: item.primaryIndication || '',
+        allergyWarnings: item.allergyWarnings || '',
+        standardDosage: item.standardDosage || '',
+        notes: item.notes || '',
+        sortCategory: item.sortCategory || '',
+        priorityTier: item.priorityTier || '',
+        tierCategory: item.tierCategory || '',
+        verified: !!item.verified,
+        purchaseHistory: Array.isArray(item.purchaseHistory)
+            ? item.purchaseHistory.map(ensurePurchaseDefaults)
+            : [ensurePurchaseDefaults({})],
+        source: item.source || '',
+        excludeFromResources: Boolean(item.excludeFromResources),
+    };
+    // If only a combined formStrength is available, backfill strength to keep validation lenient.
+    if (!med.strength && med.formStrength) {
+        med.strength = med.formStrength;
+    }
+    med.formStrength = med.formStrength || [med.form, med.strength].join(' ').trim();
+    // Backfill manufacturer/batchLot into first purchase entry if present on legacy record
+    if (item.manufacturer && med.purchaseHistory.length && !med.purchaseHistory[0].manufacturer) {
+        med.purchaseHistory[0].manufacturer = item.manufacturer;
+    }
+    if (item.batchLot && med.purchaseHistory.length && !med.purchaseHistory[0].batchLot) {
+        med.purchaseHistory[0].batchLot = item.batchLot;
+    }
+    return med;
+}
+
+/**
+ * handleVerifyToggle: function-level behavior note for maintainers.
+ * Keep this block synchronized with implementation changes.
+ */
+function handleVerifyToggle(medId) {
+    const cb = document.getElementById(`ver-${medId}`);
+    const isVerified = !!cb?.checked;
+    const badge = document.getElementById(`badge-ver-${medId}`);
+    if (badge) {
+        if (isVerified) {
+            badge.textContent = 'Verified';
+            badge.style.background = 'var(--inquiry)';
+            badge.style.color = '#fff';
+            badge.style.border = 'none';
+        } else {
+            badge.textContent = 'Not Verified';
+            badge.style.background = 'transparent';
+            badge.style.color = 'var(--inquiry)';
+            badge.style.border = '1px dashed #b2c7b5';
+        }
+    }
+    // Update cache immediately to avoid form collapse
+    const idx = pharmacyCache.findIndex((m) => m.id === medId);
+    if (idx !== -1) {
+        pharmacyCache[idx].verified = isVerified;
+    }
+    // Save just the verified flag to avoid any expiry validation side-effects.
+    fetch(`/api/data/inventory/${encodeURIComponent(medId)}/verify`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        credentials: 'same-origin',
+        body: JSON.stringify({ verified: isVerified }),
+    })
+        .then((res) => res.json().catch(() => ({})))
+        .then((data) => {
+            if (data && data.error) {
+                showToast(`Save failed: ${data.error}`, true);
+                if (cb) cb.checked = !isVerified; // revert UI on failure
+                // revert cache on failure
+                if (idx !== -1) {
+                    pharmacyCache[idx].verified = !isVerified;
+                }
+            } else {
+                showToast(isVerified ? 'Marked as Verified' : 'Marked as Not Verified');
+                // DO NOT call loadPharmacy() - it causes form to collapse
+            }
+        })
+        .catch((err) => {
+            showToast(`Save failed: ${err.message}`, true);
+            if (cb) cb.checked = !isVerified;
+            // revert cache on error
+            if (idx !== -1) {
+                pharmacyCache[idx].verified = !isVerified;
+            }
+        });
+}
+
+/**
+ * handleExcludeToggle: function-level behavior note for maintainers.
+ * Keep this block synchronized with implementation changes.
+ */
+function handleExcludeToggle(medId) {
+    const cb = document.getElementById(`exclude-${medId}`);
+    const isExcluded = !!cb?.checked;
+    
+    // Update availability badge directly by ID (same pattern as verified badge)
+    const badge = document.getElementById(`badge-avail-${medId}`);
+    if (badge) {
+        badge.style.background = isExcluded ? '#d32f2f' : '#2e7d32';
+        badge.textContent = isExcluded ? 'Resource Currently Unavailable' : 'Resource Available';
+    }
+    
+    // Update header background colors immediately
+    const header = cb?.closest('.history-item')?.querySelector('.col-header');
+    const body = cb?.closest('.history-item')?.querySelector('.col-body');
+    if (header) {
+        header.style.background = isExcluded ? '#ffecef' : '#eef7ff';
+        header.style.borderColor = isExcluded ? '#ffcfe0' : '#c7ddff';
+    }
+    if (body) {
+        body.style.background = isExcluded ? '#fff6f6' : '#f7fff7';
+        body.style.borderColor = isExcluded ? '#ffcfd0' : '#cfe9d5';
+    }
+    
+    // Update cache immediately
+    const idx = pharmacyCache.findIndex((m) => m.id === medId);
+    if (idx !== -1) {
+        pharmacyCache[idx].excludeFromResources = isExcluded;
+    }
+    
+    // Trigger save without rerender to avoid form collapse
+    scheduleSaveMedication(medId, false);
+}
+
+/**
+ * canonicalMedKey: function-level behavior note for maintainers.
+ * Keep this block synchronized with implementation changes.
+ */
+function canonicalMedKey(generic, brand, strength, formStrength = '') {
+    const clean = (val) => (val || '').toLowerCase().replace(/[^a-z0-9]+/g, '');
+    const strengthVal = clean(strength || formStrength).replace(/unspecified/g, '');
+    return `${clean(generic)}|${clean(brand)}|${strengthVal}`;
+}
+
+/**
+ * scheduleSaveMedication: function-level behavior note for maintainers.
+ * Keep this block synchronized with implementation changes.
+ */
+function scheduleSaveMedication(id, rerender = false) {
+    // Debounce saves to prevent form collapse during typing.
+    // Longer delay prevents save/reload while user is still typing.
+    if (pharmacySaveTimers[id]) {
+        clearTimeout(pharmacySaveTimers[id]);
+    }
+    pharmacySaveTimers[id] = setTimeout(() => {
+        saveMedication(id, rerender);
+    }, 800); // 800ms debounce - waits for user to pause typing
+}
+
+/**
+ * getMedicationDisplayName: function-level behavior note for maintainers.
+ * Keep this block synchronized with implementation changes.
+ */
+function getMedicationDisplayName(med) {
+    const clean = (val) => (val || '').trim();
+    const isPlaceholder = (val) => !val || /^medication\b/i.test(val);
+    const generic = clean(med.genericName);
+    const brand = clean(med.brandName);
+    let primary = !isPlaceholder(generic) ? generic : !isPlaceholder(brand) ? brand : '';
+    if (!primary) {
+        primary = med.primaryIndication || med.manufacturer || 'Medication';
+    }
+    const showBrand = brand && !isPlaceholder(brand) && brand.toLowerCase() !== primary.toLowerCase();
+    return `${primary}${showBrand ? ' - ' + brand : ''}`;
+}
+
+/**
+ * getExpiryDate: function-level behavior note for maintainers.
+ * Keep this block synchronized with implementation changes.
+ */
+function getExpiryDate(med) {
+    if (!med || !Array.isArray(med.purchaseHistory)) return med?.expiryDate || '';
+    let earliest = null;
+    med.purchaseHistory.forEach(ph => {
+        if (!ph || !ph.date) return;
+        const d = new Date(ph.date);
+        if (isNaN(d)) return;
+        if (!earliest || d < earliest) earliest = d;
+    });
+    return earliest ? earliest.toISOString().slice(0, 10) : (med.expiryDate || '');
+}
+
+/**
+ * getCurrentQuantity: function-level behavior note for maintainers.
+ * Keep this block synchronized with implementation changes.
+ */
+function getCurrentQuantity(med) {
+    if (!med || !Array.isArray(med.purchaseHistory)) return Number(med.currentQuantity) || 0;
+    return med.purchaseHistory.reduce((sum, ph) => {
+        const n = Number(ph.quantity);
+        return Number.isFinite(n) ? sum + n : sum;
+    }, 0);
+}
+
+/**
+ * sortPharmacyItems: function-level behavior note for maintainers.
+ * Keep this block synchronized with implementation changes.
+ */
+function sortPharmacyItems(items) {
+    const list = Array.isArray(items) ? [...items] : [];
+    const sortSel = document.getElementById('pharmacy-sort');
+    const mode = (sortSel && sortSel.value) || 'sortCategory';
+    const byText = (a, b, pathA, pathB) => {
+        const va = (pathA || '').toLowerCase();
+        const vb = (pathB || '').toLowerCase();
+        return va.localeCompare(vb);
+    };
+    list.sort((a, b) => {
+        if (mode === 'sortCategory') {
+            const hasA = !!(a.sortCategory || '').trim();
+            const hasB = !!(b.sortCategory || '').trim();
+            if (hasA && !hasB) return -1;
+            if (!hasA && hasB) return 1;
+            if (hasA && hasB) {
+                const cat = byText(a, b, a.sortCategory, b.sortCategory);
+                if (cat !== 0) return cat;
+            }
+        }
+        if (mode === 'brand') {
+            return byText(a, b, a.brandName || '', b.brandName || '');
+        }
+        if (mode === 'strength') {
+            return byText(a, b, a.strength || '', b.strength || '');
+        }
+        if (mode === 'expiry') {
+            return byText(a, b, getExpiryDate(a) || '', getExpiryDate(b) || '');
+        }
+        // default generic
+        return byText(a, b, a.genericName || a.brandName || '', b.genericName || b.brandName || '');
+    });
+    return list;
+}
+
+// Primary loader for the Medical Chest list. Pulls server data, normalizes, renders cards,
+// and keeps the count badge in sync. WHO list is lazy-loaded alongside.
+async function preloadPharmacy() {
+    if (pharmacyFetchPromise) return pharmacyFetchPromise;
+    pharmacyFetchPromise = fetchInventory()
+        .then((data) => {
+            pharmacyCache = (Array.isArray(data) ? data : []).map(ensurePharmacyDefaults);
+            return pharmacyCache;
+        })
+        .catch((err) => {
+            pharmacyFetchPromise = null;
+            throw err;
+        });
+    return pharmacyFetchPromise;
+}
+
+// Primary loader for the Medical Chest list. Pulls server data, normalizes, renders cards,
+// and keeps the count badge in sync. WHO list is lazy-loaded on demand.
+async function loadPharmacy() {
+    const list = document.getElementById('pharmacy-list');
+    if (!list) return;
+    list.innerHTML = '<div style="color:#666;">Loading inventory...</div>';
+    
+    // If we already have cached meds, render them immediately for perceived speed
+    if (pharmacyCache.length) {
+        updatePharmacyCount(pharmacyCache.length);
+        renderPharmacy(pharmacyCache);
+        initNewMedTierControls();
+        // Skip - don't block on WHO list
+    }
+
+    try {
+        // Only fetch critical data first (labels needed for dropdowns)
+        const labelsPromise = ensurePharmacyLabels();
+        
+        // Fetch inventory data
+        const data = await fetchInventory();
+        pharmacyCache = (Array.isArray(data) ? data : []).map(ensurePharmacyDefaults);
+        
+        // Wait for labels (needed for render)
+        await labelsPromise;
+        
+        // Render immediately - don't wait for WHO list
+        populateNewMedUserLabelSelect();
+        initNewMedTierControls();
+        observePharmacyList();
+        updatePharmacyCount(pharmacyCache.length);
+        renderPharmacy(pharmacyCache);
+        syncPharmacyCountFromDOM();
+        
+        // Load WHO list in background (non-blocking)
+        loadWhoMedsFromServer().catch(err => console.warn('[pharmacy] WHO list load failed:', err));
+    } catch (err) {
+        updatePharmacyCount(0);
+        list.innerHTML = `<div style="color:red;">Error loading inventory: ${err.message}</div>`;
+    }
+}
+
+/**
+ * handlePharmacySortChange: function-level behavior note for maintainers.
+ * Keep this block synchronized with implementation changes.
+ */
+function handlePharmacySortChange() {
+    const openIds = getOpenMedIds();
+    const textHeights = getTextareaHeights();
+    renderPharmacy(pharmacyCache, openIds, textHeights);
+}
+
+/**
+ * getOpenMedIds: function-level behavior note for maintainers.
+ * Keep this block synchronized with implementation changes.
+ */
+function getOpenMedIds() {
+    return Array.from(document.querySelectorAll('#pharmacy-list .history-item .col-body[data-med-id]'))
+        .filter((el) => el.style.display !== 'none')
+        .map((el) => el.dataset.medId)
+        .filter(Boolean);
+}
+
+/**
+ * renderPharmacy: function-level behavior note for maintainers.
+ * Keep this block synchronized with implementation changes.
+ */
+function renderPharmacy(items, openIds = [], textHeights = {}) {
+    const list = document.getElementById('pharmacy-list');
+    if (!list) return;
+    updatePharmacyCount((items || []).length);
+    if (!items || items.length === 0) {
+        list.innerHTML = '<div style="color:#666; padding:12px;">No medications entered. Add your first item.</div>';
+        return;
+    }
+    const sorted = sortPharmacyItems(items);
+    
+    // For small lists (≤50 items), render immediately without chunking
+    if (sorted.length <= 50) {
+        list.innerHTML = sorted.map((m) => renderMedicationCard(m, openIds.includes(m.id), textHeights)).join('');
+        syncPharmacyCountFromDOM();
+        populateNewMedUserLabelSelect();
+        return;
+    }
+    
+    // For larger lists, use aggressive chunking
+    list.innerHTML = '<div style="color:#666; padding:12px;">Loading medications...</div>';
+    const chunkSize = 100; // Increased from 40 to 100
+    let idx = 0;
+    list.innerHTML = ''; // clear placeholder
+    
+    const renderChunk = () => {
+        if (idx >= sorted.length) {
+            syncPharmacyCountFromDOM();
+            populateNewMedUserLabelSelect();
+            return;
+        }
+        const slice = sorted.slice(idx, idx + chunkSize);
+        const html = slice.map((m) => renderMedicationCard(m, openIds.includes(m.id), textHeights)).join('');
+        list.insertAdjacentHTML('beforeend', html);
+        idx += chunkSize;
+        
+        // Use setTimeout(0) for fastest rendering without blocking
+        setTimeout(renderChunk, 0);
+    };
+    renderChunk();
+}
+
+/**
+ * renderPurchaseRows: function-level behavior note for maintainers.
+ * Keep this block synchronized with implementation changes.
+ */
+function renderPurchaseRows(med) {
+    // Expiry UI contract:
+    //  - Rows carry stable ph-id so deletes map 1:1 to saved rows.
+    //  - Manufacturer / batch live per-row (stock provenance).
+    //  - We keep at least one row visible for usability.
+    const rows = med.purchaseHistory.length ? med.purchaseHistory : [ensurePurchaseDefaults({}, false)];
+    return rows
+        .map((p, idx) => {
+            const rowNum = idx + 1;
+            const expDate = p.date || 'No date';
+            const qty = p.quantity || '0';
+            return `
+                <div class="collapsible purchase-row" data-med-id="${med.id}" data-ph-id="${p.id || ''}" style="margin-bottom:8px;">
+                    <div class="col-header crew-med-header" onclick="toggleCrewSection(this)" style="background:#fff; justify-content:flex-start; align-items:center; padding:8px 12px;">
+                        <span class="toggle-label history-arrow" style="font-size:16px; margin-right:8px;">▸</span>
+                        <span style="font-weight:700; color:#37474f;">Batch ${rowNum}</span>
+                        <span style="margin-left:auto; font-size:12px; color:#555;">Exp: ${expDate} • Qty: ${qty}</span>
+                        <button class="btn btn-sm history-action-btn" style="background:var(--red); padding:4px 10px; margin-left:8px; visibility:hidden;" onclick="event.stopPropagation(); deletePurchaseEntry('${med.id}','${p.id || ''}')" title="Delete this batch entry">Delete</button>
+                    </div>
+                    <div class="col-body" style="padding:10px; display:none; background:#f9fbff; border:1px solid #d9e5f7; border-top:none;">
+                        <div style="display:grid; grid-template-columns: repeat(2, 1fr); gap:10px; margin-bottom:10px;">
+                            <div>
+                                <label style="font-weight:700; font-size:12px; display:block; margin-bottom:4px;">Expiry Date *</label>
+                                <input type="date" class="ph-date" value="${p.date || ''}" style="padding:8px; font-size:14px; width:100%; border:1px solid #d0d7e2; border-radius:4px;" onchange="scheduleSaveMedication('${med.id}')">
+                            </div>
+                            <div>
+                                <label style="font-weight:700; font-size:12px; display:block; margin-bottom:4px;">Quantity *</label>
+                                <input type="number" class="ph-qty" value="${p.quantity || ''}" placeholder="0" style="padding:8px; font-size:14px; width:100%; border:1px solid #d0d7e2; border-radius:4px;" oninput="scheduleSaveMedication('${med.id}')">
+                            </div>
+                        </div>
+                        <div style="display:grid; grid-template-columns: repeat(2, 1fr); gap:10px; margin-bottom:10px;">
+                            <div>
+                                <label style="font-weight:700; font-size:12px; display:block; margin-bottom:4px;">Manufacturer</label>
+                                <input type="text" class="ph-manufacturer" value="${p.manufacturer || ''}" placeholder="Optional" style="padding:8px; font-size:14px; width:100%; border:1px solid #d0d7e2; border-radius:4px;" oninput="scheduleSaveMedication('${med.id}')">
+                            </div>
+                            <div>
+                                <label style="font-weight:700; font-size:12px; display:block; margin-bottom:4px;">Batch / Lot #</label>
+                                <input type="text" class="ph-batch" value="${p.batchLot || ''}" placeholder="Optional" style="padding:8px; font-size:14px; width:100%; border:1px solid #d0d7e2; border-radius:4px;" oninput="scheduleSaveMedication('${med.id}')">
+                            </div>
+                        </div>
+                        <div>
+                            <label style="font-weight:700; font-size:12px; display:block; margin-bottom:4px;">Notes</label>
+                            <textarea class="ph-notes" placeholder="Optional notes about this batch" style="width:100%; padding:8px; min-height:50px; font-size:14px; border:1px solid #d0d7e2; border-radius:4px; resize:vertical;" oninput="scheduleSaveMedication('${med.id}')">${p.notes || ''}</textarea>
+                        </div>
+                    </div>
+                </div>`;
+        })
+        .join('');
+}
+
+/**
+ * renderMedicationCard: function-level behavior note for maintainers.
+ * Keep this block synchronized with implementation changes.
+ */
+function renderMedicationCard(med, isOpen = false, textHeights = {}) {
+    // Render a single medication card with summary badges and collapsible details/expiry tracking.
+    const currentQty = getCurrentQuantity(med);
+    const lowStock = med.minThreshold && Number(currentQty) <= Number(med.minThreshold);
+    const expiryDate = getExpiryDate(med);
+    const days = expiryDate ? daysUntil(expiryDate) : null;
+    const isExpired = Number.isFinite(days) && days < 0;
+    const expirySoon = Number.isFinite(days) && days >= 0 && days <= 60;
+    const expiryText = expiryDate ? `Exp: ${expiryDate}` : 'No expiry set';
+    const headerNote = [
+        lowStock ? 'Low Stock' : null,
+        isExpired ? 'Expired' : null,
+        !isExpired && expirySoon ? 'Expiring Soon' : null
+    ].filter(Boolean).join(' - ');
+    const displayName = getMedicationDisplayName(med);
+    const strength = (med.strength || '').trim();
+    const userLabelRender = renderUserLabelOptions(med.sortCategory || '');
+    const labelChip = med.sortCategory && med.sortCategory.trim()
+        ? `<span style="margin-left:8px; padding:2px 8px; border-radius:999px; background:rgba(46,125,50,0.12); color:var(--inquiry); font-size:11px; white-space:nowrap;">${escapeHtml(med.sortCategory.trim())}</span>`
+        : '';
+    const bodyDisplay = isOpen ? 'display:block;' : 'display:none;';
+    const arrow = isOpen ? '▾' : '▸';
+    const headerBg = med.excludeFromResources ? '#ffecef' : '#eef7ff';
+    const headerBorderColor = med.excludeFromResources ? '#ffcfe0' : '#c7ddff';
+    const bodyBg = med.excludeFromResources ? '#fff6f6' : '#f7fff7';
+    const bodyBorderColor = med.excludeFromResources ? '#ffcfd0' : '#cfe9d5';
+    const badgeColor = med.excludeFromResources ? '#d32f2f' : '#2e7d32';
+    const badgeText = med.excludeFromResources ? 'Resource Currently Unavailable' : 'Resource Available';
+    const availabilityBadge = `<span id="badge-avail-${med.id}" style="padding:2px 10px; border-radius:999px; background:${badgeColor}; color:#fff; font-size:11px; white-space:nowrap;">${badgeText}</span>`;
+    const verifiedBadge = med.verified
+        ? `<span class="dev-tag">dev:med-verified</span><span id="badge-ver-${med.id}" style="padding:2px 10px; border-radius:999px; background:var(--inquiry); color:#fff; font-size:11px; white-space:nowrap;">Verified</span>`
+        : `<span class="dev-tag">dev:med-verified</span><span id="badge-ver-${med.id}" style="padding:2px 10px; border-radius:999px; background:transparent; color:var(--inquiry); font-size:11px; white-space:nowrap; border:1px dashed #b2c7b5;">Not Verified</span>`;
+    const doseHeight = textHeights[`dose-${med.id}`] ? `height:${textHeights[`dose-${med.id}`]};` : '';
+    return `
+            <div class="collapsible history-item">
+        <div class="col-header crew-med-header" onclick="toggleCrewSection(this)" style="justify-content:flex-start; align-items:center; background:${headerBg}; border:1px solid ${headerBorderColor}; padding:8px 12px;">
+            <span class="dev-tag">dev:med-card</span>
+            <span class="toggle-label history-arrow" style="font-size:18px; margin-right:8px;" data-collapse-group="pharmacy">${arrow}</span>
+            <span style="flex:1; white-space:nowrap; overflow:hidden; text-overflow:ellipsis; font-weight:700;">
+                ${displayName}${strength ? ' - ' + strength : ''}
+            </span>
+            ${labelChip}
+            ${headerNote ? `<span class="sidebar-pill" style="margin-right:8px; background:${lowStock ? '#ffebee' : '#fff7e0'}; color:${lowStock ? '#c62828' : '#b26a00'};">${headerNote}</span>` : ''}
+            <button onclick="event.stopPropagation(); deleteMedication('${med.id}')" class="btn btn-sm history-action-btn" style="background:var(--red); visibility:hidden;">Delete Medication</button>
+            <div style="display:flex; align-items:center; gap:6px; margin-left:8px;">${verifiedBadge}${availabilityBadge}</div>
+        </div>
+        <div class="col-body" data-med-id="${med.id}" style="padding:12px; background:${bodyBg}; border:1px solid ${bodyBorderColor}; border-radius:6px; ${bodyDisplay}">
+            <div class="collapsible" style="margin-bottom:10px;">
+                <div class="col-header crew-med-header" onclick="toggleMedDetails(this)" style="background:#fff; justify-content:flex-start; align-items:center;">
+                    <span class="dev-tag">dev:med-details</span>
+                    <span class="detail-icon history-arrow" style="font-size:16px; margin-right:8px;">▾</span>
+                    <span style="font-weight:700;">Medication Details</span>
+                </div>
+            <div class="col-body" style="padding:10px; display:block;" id="details-${med.id}">
+                <div style="display:flex; align-items:center; gap:12px; margin-bottom:12px; flex-wrap:wrap;">
+                    <label style="display:flex; align-items:center; gap:6px; font-size:12px; padding:6px 10px; border:1px solid #ffcfe0; border-radius:6px; background:#fff; margin:0;">
+                        <input id="exclude-${med.id}" type="checkbox" ${med.excludeFromResources ? 'checked' : ''} onchange="handleExcludeToggle('${med.id}')">
+                        Resource Currently Unavailable
+                    </label>
+                    <label style="display:flex; align-items:center; gap:6px; font-size:12px; padding:6px 10px; border:1px solid #c7ddff; border-radius:6px; background:#fff; margin:0;">
+                        <input id="ver-${med.id}" type="checkbox" ${med.verified ? 'checked' : ''} onchange="handleVerifyToggle('${med.id}'); event.stopPropagation();">
+                        Verified
+                    </label>
+                    <label style="display:flex; align-items:center; gap:6px; font-size:12px; padding:6px 10px; border:1px solid #c7ddff; border-radius:6px; background:#fff; margin:0;">
+                        <span style="font-weight:700;">User Label</span>
+                        <select id="sort-${med.id}" style="padding:6px 8px;" onchange="handleSortCategoryChange('${med.id}')">
+                            ${userLabelRender.optionsHtml}
+                        </select>
+                        <input id="sort-custom-${med.id}" type="text" value="${userLabelRender.customValue}" placeholder="Custom label" style="width:160px; padding:6px; margin-left:6px; ${userLabelRender.showCustom ? '' : 'display:none;'}" oninput="scheduleSaveMedication('${med.id}', false)">
+                    </label>
+                </div>
+                        <div style="display:grid; grid-template-columns: repeat(2, minmax(240px, 1fr)); gap:10px; margin-bottom:10px;">
+                        <div>
+                            <label style="font-weight:700; font-size:12px;">Generic Name</label>
+                            <input id="gn-${med.id}" type="text" value="${med.genericName}" style="width:100%; padding:8px;" oninput="scheduleSaveMedication('${med.id}')">
+                        </div>
+                        <div>
+                            <label style="font-weight:700; font-size:12px;">Brand Name</label>
+                            <input id="bn-${med.id}" type="text" value="${med.brandName}" style="width:100%; padding:8px;" oninput="scheduleSaveMedication('${med.id}')">
+                        </div>
+                        <div>
+                            <label style="font-weight:700; font-size:12px;">Form</label>
+                            <input id="form-${med.id}" type="text" value="${med.form}" placeholder="Tablet, Capsule, etc." style="width:100%; padding:8px;" oninput="scheduleSaveMedication('${med.id}')">
+                        </div>
+                        <div>
+                            <label style="font-weight:700; font-size:12px;">Strength</label>
+                            <input id="str-${med.id}" type="text" value="${med.strength}" placeholder="500mg, 10mg/ml" style="width:100%; padding:8px;" oninput="scheduleSaveMedication('${med.id}')">
+                        </div>
+                        <div style="grid-column: 1 / span 2; display:grid; grid-template-columns: repeat(3, minmax(160px, 1fr)); gap:10px;">
+                            <div>
+                                <label style="font-weight:700; font-size:12px;">Minimum Threshold</label>
+                                <input id="min-${med.id}" type="number" value="${med.minThreshold}" style="width:100%; padding:8px;" oninput="scheduleSaveMedication('${med.id}')">
+                            </div>
+                            <div>
+                                <label style="font-weight:700; font-size:12px;">Unit of Measure</label>
+                                <input id="unit-${med.id}" type="text" value="${med.unit}" placeholder="Bottle, Box, Blister" style="width:100%; padding:8px;" oninput="scheduleSaveMedication('${med.id}')">
+                            </div>
+                        </div>
+                        <div style="grid-column: span 2; display:grid; grid-template-columns: repeat(2, minmax(200px, 1fr)); gap:10px;">
+                            <div>
+                                <label style="font-weight:700; font-size:12px;">Priority Tier</label>
+                                <select id="tier-${med.id}" style="width:100%; padding:8px;" onchange="handleMedTierChange('${med.id}')">
+                                    ${buildTierOptions(med.priorityTier)}
+                                </select>
+                            </div>
+                            <div>
+                                <label style="font-weight:700; font-size:12px;">Functional Subcategory</label>
+                                <select id="tiercat-${med.id}" style="width:100%; padding:8px;" onchange="scheduleSaveMedication('${med.id}')">
+                                    ${buildTierSubcategoryOptions(med.priorityTier, med.tierCategory)}
+                                </select>
+                            </div>
+                        </div>
+                        <div>
+                            <label style="font-weight:700; font-size:12px;">Storage Location</label>
+                            <input id="loc-${med.id}" type="text" value="${med.storageLocation}" placeholder="Locker A, Fridge" style="width:100%; padding:8px;" oninput="scheduleSaveMedication('${med.id}')">
+                        </div>
+                        <div>
+                            <label style="font-weight:700; font-size:12px;">Controlled Substance?</label>
+                            <select id="ctrl-${med.id}" style="width:100%; padding:8px;" onchange="scheduleSaveMedication('${med.id}')">
+                                <option value="false" ${!med.controlled ? 'selected' : ''}>No</option>
+                                <option value="true" ${med.controlled ? 'selected' : ''}>Yes</option>
+                            </select>
+                        </div>
+                        <div>
+                            <label style="font-weight:700; font-size:12px;">Primary Indication</label>
+                            <input id="ind-${med.id}" type="text" value="${med.primaryIndication}" style="width:100%; padding:8px;" oninput="scheduleSaveMedication('${med.id}')">
+                        </div>
+                        <div>
+                            <label style="font-weight:700; font-size:12px;">Allergy Warnings</label>
+                            <input id="alg-${med.id}" type="text" value="${med.allergyWarnings}" placeholder="e.g., Contains Sulfa" style="width:100%; padding:8px;" oninput="scheduleSaveMedication('${med.id}')">
+                        </div>
+                        <div style="grid-column: span 2;">
+                            <label style="font-weight:700; font-size:12px;">Standard Dosage (adult reference)</label>
+                            <textarea id="dose-${med.id}" style="width:100%; padding:8px; min-height:60px; ${doseHeight}" oninput="scheduleSaveMedication('${med.id}')">${med.standardDosage || ''}</textarea>
+                        </div>
+                    </div>
+                </div>
+            </div>
+            <div class="collapsible" style="margin-top:12px;">
+                <div class="col-header crew-med-header" onclick="toggleCrewSection(this)" style="background:#fff6e8; border:1px solid #f0d9a8; justify-content:flex-start;">
+                    <span class="dev-tag">dev:med-expiry-shell</span>
+                    <span class="toggle-label history-arrow" style="font-size:18px; margin-right:8px;">▸</span>
+                    <span style="font-weight:700;">Expiry Tracking</span>
+                    <span style="font-size:12px; color:#6a5b3a; margin-left:8px;">${med.purchaseHistory.length} batch(es)</span>
+                </div>
+                <div class="col-body" style="padding:10px; background:#fffdf7; border:1px solid #f0d9a8; border-top:none; display:none;">
+                    <div class="collapsible" style="margin-bottom:10px;">
+                        <div class="col-header crew-med-header" onclick="toggleCrewSection(this)" style="background:#fff; justify-content:flex-start; align-items:center;">
+                            <span class="dev-tag">dev:med-expiry-add-form</span>
+                            <span class="toggle-label history-arrow" style="font-size:16px; margin-right:8px;">▸</span>
+                            <span style="font-weight:700;">Add New Batch Entry</span>
+                        </div>
+                        <div class="col-body" style="padding:10px; display:none; background:#f9fbff; border:1px solid #d9e5f7; border-top:none;">
+                            <div style="display:grid; grid-template-columns: repeat(2, 1fr); gap:10px; margin-bottom:10px;">
+                                <div>
+                                    <label style="font-weight:700; font-size:12px; display:block; margin-bottom:4px;">Expiry Date *</label>
+                                    <input type="date" id="new-exp-date-${med.id}" style="padding:8px; font-size:14px; width:100%; border:1px solid #d0d7e2; border-radius:4px;">
+                                </div>
+                                <div>
+                                    <label style="font-weight:700; font-size:12px; display:block; margin-bottom:4px;">Quantity *</label>
+                                    <input type="number" id="new-exp-qty-${med.id}" placeholder="0" style="padding:8px; font-size:14px; width:100%; border:1px solid #d0d7e2; border-radius:4px;">
+                                </div>
+                            </div>
+                            <div style="display:grid; grid-template-columns: repeat(2, 1fr); gap:10px; margin-bottom:10px;">
+                                <div>
+                                    <label style="font-weight:700; font-size:12px; display:block; margin-bottom:4px;">Manufacturer</label>
+                                    <input type="text" id="new-exp-manu-${med.id}" placeholder="Optional" style="padding:8px; font-size:14px; width:100%; border:1px solid #d0d7e2; border-radius:4px;">
+                                </div>
+                                <div>
+                                    <label style="font-weight:700; font-size:12px; display:block; margin-bottom:4px;">Batch / Lot #</label>
+                                    <input type="text" id="new-exp-batch-${med.id}" placeholder="Optional" style="padding:8px; font-size:14px; width:100%; border:1px solid #d0d7e2; border-radius:4px;">
+                                </div>
+                            </div>
+                            <div>
+                                <label style="font-weight:700; font-size:12px; display:block; margin-bottom:4px;">Notes</label>
+                                <textarea id="new-exp-notes-${med.id}" placeholder="Optional notes about this batch" style="width:100%; padding:8px; min-height:50px; font-size:14px; border:1px solid #d0d7e2; border-radius:4px; resize:vertical;"></textarea>
+                            </div>
+                            <button onclick="addPurchaseEntry('${med.id}')" class="btn btn-sm" style="background:var(--dark); width:100%; margin-top:10px;">Add Batch Entry</button>
+                        </div>
+                    </div>
+                    <div class="dev-tag" style="margin:10px 0 6px;">dev:med-expiry-list</div>
+                    <div id="ph-${med.id}">${renderPurchaseRows(med)}</div>
+                </div>
+            </div>
+        </div>
+    </div>`;
+}
+
+/**
+ * renderWhoMedList: function-level behavior note for maintainers.
+ * Keep this block synchronized with implementation changes.
+ */
+function renderWhoMedList() {
+    const container = document.getElementById('who-med-list');
+    if (!container) return;
+    container.innerHTML = WHO_RECOMMENDED_MEDS.map((m, idx) => {
+        const id = `who-${m.id || idx}`;
+        return `
+            <label style="position:relative; display:block; border:1px solid #d9e5f7; padding:12px 10px 10px 42px; border-radius:8px; background:#fff; transition:background 120ms ease, border-color 120ms ease;">
+                <input type="checkbox" name="who-med-check" value="${id}" style="position:absolute; top:10px; left:10px;" onchange="handleWhoTileSelect(this)">
+                <div style="display:flex; gap:10px; width:100%; align-items:flex-start;">
+                    <div style="flex:1; min-width:0;">
+                        <div style="display:flex; align-items:flex-start; justify-content:space-between; gap:8px; flex-wrap:wrap;">
+                            <div style="font-weight:800; color:#1f2d3d;">${m.genericName}</div>
+                            <button type="button" class="btn btn-xs" style="background:#0b8457; color:#fff; padding:4px 8px; line-height:1.2;" onclick="event.preventDefault(); event.stopPropagation(); addWhoMeds('${id}')">Add</button>
+                        </div>
+                        ${m.alsoKnownAs ? `<div style="font-size:12px; color:#37474f;">Also known as: ${m.alsoKnownAs}</div>` : ''}
+                        ${m.formStrength ? `<div style="font-size:12px; color:#455a64;">Dosage form/strength: ${m.formStrength}</div>` : ''}
+                        ${m.indications ? `<div style="font-size:12px; color:#455a64;">Indications: ${m.indications}</div>` : ''}
+                        ${m.contraindications ? `<div style="font-size:12px; color:#b23b3b;">Contraindications: ${m.contraindications}</div>` : ''}
+                        ${m.consultDoctor ? `<div style="font-size:12px; color:#6a1b9a;">Consult doctor: ${m.consultDoctor}</div>` : ''}
+                        ${m.adultDosage ? `<div style="font-size:12px; color:#455a64;">Adult dosage: ${m.adultDosage}</div>` : ''}
+                        ${m.unwantedEffects ? `<div style="font-size:12px; color:#b23b3b;">Unwanted effects: ${m.unwantedEffects}</div>` : ''}
+                        ${m.remarks ? `<div style="font-size:12px; color:#455a64;">Remarks: ${m.remarks}</div>` : ''}
+                    </div>
+                </div>
+            </label>
+        `;
+    }).join('') || '<div style="color:#666;">WHO list unavailable.</div>';
+}
+
+async function loadWhoMedsFromServer() {
+    if (whoMedLoaded) return;
+    setWhoMedStatus('Loading WHO ship medicine list...');
+    try {
+        const res = await fetch('/api/who/medicines', { credentials: 'same-origin' });
+        if (!res.ok) throw new Error(`Status ${res.status}`);
+        const data = await res.json();
+        WHO_RECOMMENDED_MEDS = Array.isArray(data) ? data : [];
+        whoMedLoaded = true;
+        renderWhoMedList();
+        setWhoMedStatus(`Loaded ${WHO_RECOMMENDED_MEDS.length} WHO medicine(s).`);
+    } catch (err) {
+        whoMedLoaded = false;
+        renderWhoMedList();
+        setWhoMedStatus(`WHO list unavailable: ${err.message}`, true);
+    }
+}
+
+/**
+ * parseWHOListText: function-level behavior note for maintainers.
+ * Keep this block synchronized with implementation changes.
+ */
+function parseWHOListText(text) {
+    if (typeof text !== 'string') return [];
+    const lines = text
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter(Boolean);
+    const now = Date.now();
+    return lines
+        .map((line, idx) => {
+            const cols = line.split('\t');
+            if (idx === 0 && /generic\s+name/i.test(cols[0] || '')) {
+                return null;
+            }
+            return {
+                id: `who-import-${now}-${idx}`,
+                genericName: (cols[0] || '').trim(),
+                alsoKnownAs: (cols[1] || '').trim(),
+                formStrength: (cols[2] || '').trim(),
+                indications: (cols[3] || '').trim(),
+                contraindications: (cols[4] || '').trim(),
+                consultDoctor: (cols[5] || '').trim(),
+                adultDosage: (cols[6] || '').trim(),
+                unwantedEffects: (cols[7] || '').trim(),
+                remarks: (cols[8] || '').trim(),
+            };
+        })
+        .filter((entry) => entry && entry.genericName);
+}
+
+/**
+ * setWhoMedStatus: function-level behavior note for maintainers.
+ * Keep this block synchronized with implementation changes.
+ */
+function setWhoMedStatus(message, isError = false) {
+    const statusEl = document.getElementById('who-med-status');
+    if (!statusEl) return;
+    statusEl.textContent = message;
+    statusEl.style.color = isError ? 'var(--red)' : '#1f2d3d';
+}
+
+/**
+ * openWhoListFilePicker: function-level behavior note for maintainers.
+ * Keep this block synchronized with implementation changes.
+ */
+function openWhoListFilePicker() {
+    const input = document.getElementById('who-list-import-file');
+    if (!input) return;
+    input.value = '';
+    input.click();
+}
+
+async function handleWhoListFileImport(event) {
+    const file = event?.target?.files?.[0];
+    if (!file) return;
+    try {
+        const text = await file.text();
+        const entries = parseWHOListText(text);
+        if (!entries.length) {
+            setWhoMedStatus('No valid WHO medicines found in the file.', true);
+            return;
+        }
+        WHO_RECOMMENDED_MEDS = entries;
+        renderWhoMedList();
+        setWhoMedStatus(`Loaded ${entries.length} WHO medicine(s).`);
+    } catch (err) {
+        setWhoMedStatus(`Unable to load WHO list: ${err.message}`, true);
+    } finally {
+        if (event?.target) event.target.value = '';
+    }
+}
+
+async function addWhoMeds(triggerId = null) {
+    const statusEl = document.getElementById('who-med-status');
+    const setStatus = (msg, isErr = false) => {
+        if (!statusEl) return;
+        statusEl.textContent = msg;
+        statusEl.style.color = isErr ? 'var(--red)' : '#1f2d3d';
+    };
+    const checked = Array.from(document.querySelectorAll('input[name="who-med-check"]:checked')).map((el) => el.value);
+    const targetIds = new Set(checked);
+    if (triggerId) targetIds.add(triggerId);
+    if (!targetIds.size) {
+        setStatus('Select one or more medicines to copy, or use an Add button.', true);
+        return;
+    }
+    try {
+        const data = await fetchInventory();
+        const meds = Array.isArray(data) ? data.map(ensurePharmacyDefaults) : [];
+        let added = 0;
+        let skipped = 0;
+        const addedNames = [];
+        const timestamp = new Date().toISOString();
+        Array.from(targetIds).forEach((targetVal) => {
+            const medTpl = WHO_RECOMMENDED_MEDS.find((m, idx) => `who-${m.id || idx}` === targetVal);
+            if (!medTpl) return;
+            const tplBrand = (medTpl.alsoKnownAs || '').trim().toLowerCase();
+            const tplStrengthRaw = medTpl.formStrength || '';
+            const tplStrengthParts = tplStrengthRaw.split(',');
+            const tplStrength = (tplStrengthParts[1] || tplStrengthParts[0] || '').trim().toLowerCase();
+            const dup = meds.find((m) => {
+                const g = (m.genericName || '').trim().toLowerCase();
+                const b = (m.brandName || '').trim().toLowerCase();
+                const s = (m.strength || '').trim().toLowerCase();
+                return g === (medTpl.genericName || '').trim().toLowerCase() && b === tplBrand && s === tplStrength;
+            });
+            if (dup) {
+                skipped += 1;
+                return;
+            }
+            const newMed = ensurePharmacyDefaults({
+                id: uid('med-who'),
+                genericName: medTpl.genericName || '',
+                brandName: medTpl.alsoKnownAs || '',
+                form: medTpl.formStrength ? medTpl.formStrength.split(',')[0].trim() : '',
+                strength: medTpl.formStrength ? (medTpl.formStrength.split(',')[1] || '').trim() : '',
+                currentQuantity: '',
+                minThreshold: '',
+                unit: '',
+                storageLocation: 'Medical Locker',
+                expiryDate: '',
+                batchLot: '',
+                controlled: false,
+                manufacturer: '',
+                primaryIndication: medTpl.indications || '',
+                allergyWarnings: medTpl.contraindications || medTpl.unwantedEffects || '',
+                standardDosage: medTpl.adultDosage || '',
+                notes: `${medTpl.remarks || medTpl.consultDoctor || 'WHO ship list import'} | Added from WHO list on ${timestamp}`,
+                source: 'who_recommended',
+                purchaseHistory: [],
+                excludeFromResources: true,
+            });
+            meds.push(newMed);
+            added += 1;
+            addedNames.push(medTpl.genericName || 'Unknown');
+        });
+        await fetchInventory({
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(meds),
+        });
+        pharmacyCache = meds;
+        renderPharmacy(pharmacyCache);
+        const summaryMsg = `Added ${added} item(s)${skipped ? `, skipped ${skipped} duplicate(s)` : ''}.`;
+        setStatus(summaryMsg);
+        if (addedNames.length) {
+            alert(`Added to inventory:\\n- ${addedNames.join('\\n- ')}`);
+        }
+    } catch (err) {
+        setStatus(`Unable to add medicines: ${err.message}`, true);
+    }
+}
+
+/**
+ * handleWhoTileSelect: function-level behavior note for maintainers.
+ * Keep this block synchronized with implementation changes.
+ */
+function handleWhoTileSelect(checkbox) {
+    const tile = checkbox?.closest('label');
+    if (!tile) return;
+    const isChecked = !!checkbox.checked;
+    tile.style.background = isChecked ? '#f1fff4' : '#fff';
+    tile.style.borderColor = isChecked ? '#9fd7ac' : '#d9e5f7';
+}
+
+/**
+ * daysUntil: function-level behavior note for maintainers.
+ * Keep this block synchronized with implementation changes.
+ */
+function daysUntil(dateStr) {
+    const now = new Date();
+    const target = new Date(dateStr);
+    if (isNaN(target.getTime())) return 9999;
+    const diff = target.getTime() - now.getTime();
+    return Math.ceil(diff / (1000 * 60 * 60 * 24));
+}
+
+/**
+ * clearExpiryForm: function-level behavior note for maintainers.
+ * Keep this block synchronized with implementation changes.
+ */
+function clearExpiryForm(medId) {
+    const fields = ['new-exp-date', 'new-exp-qty', 'new-exp-manu', 'new-exp-batch', 'new-exp-notes'];
+    fields.forEach(prefix => {
+        const el = document.getElementById(`${prefix}-${medId}`);
+        if (el) el.value = '';
+    });
+}
+
+/**
+ * addPurchaseEntry: function-level behavior note for maintainers.
+ * Keep this block synchronized with implementation changes.
+ */
+function addPurchaseEntry(medId) {
+    // Read values from the add form (like crew vaccine pattern)
+    const date = document.getElementById(`new-exp-date-${medId}`)?.value || '';
+    const qty = document.getElementById(`new-exp-qty-${medId}`)?.value || '';
+    const manu = document.getElementById(`new-exp-manu-${medId}`)?.value || '';
+    const batch = document.getElementById(`new-exp-batch-${medId}`)?.value || '';
+    const notes = document.getElementById(`new-exp-notes-${medId}`)?.value || '';
+    
+    // Validate required fields (like crew vaccine pattern)
+    if (!date) {
+        alert('Please enter an Expiry Date');
+        const dateField = document.getElementById(`new-exp-date-${medId}`);
+        if (dateField) dateField.focus();
+        return;
+    }
+    if (!qty) {
+        alert('Please enter a Quantity');
+        const qtyField = document.getElementById(`new-exp-qty-${medId}`);
+        if (qtyField) qtyField.focus();
+        return;
+    }
+    
+    const container = document.getElementById(`ph-${medId}`);
+    if (!container) return;
+    
+    // Get current batch count for numbering
+    const currentRows = container.querySelectorAll('.purchase-row').length;
+    const rowNum = currentRows + 1;
+    
+    // Create new row with values from form
+    const row = document.createElement('div');
+    row.className = 'purchase-row';
+    row.dataset.medId = medId;
+    const newPhId = uid('ph');
+    row.dataset.phId = newPhId;
+    row.style.cssText = 'border:1px solid #d9e5f7; padding:12px; border-radius:8px; margin-bottom:12px; background:#fff; position:relative;';
+    row.innerHTML = `
+        <div style="display:flex; justify-content:space-between; align-items:center; margin-bottom:10px;">
+            <span style="font-weight:700; color:#37474f;">Batch ${rowNum}</span>
+            <button class="btn btn-sm" style="background:var(--red); padding:4px 10px;" onclick="deletePurchaseEntry('${medId}','${newPhId}')" title="Delete this batch entry">Delete</button>
+        </div>
+        <div style="display:grid; grid-template-columns: repeat(2, 1fr); gap:10px; margin-bottom:10px;">
+            <div>
+                <label style="font-weight:700; font-size:12px; display:block; margin-bottom:4px;">Expiry Date *</label>
+                <input type="date" class="ph-date" value="${date}" style="padding:8px; font-size:14px; width:100%; border:1px solid #d0d7e2; border-radius:4px;" onchange="scheduleSaveMedication('${medId}')">
+            </div>
+            <div>
+                <label style="font-weight:700; font-size:12px; display:block; margin-bottom:4px;">Quantity *</label>
+                <input type="number" class="ph-qty" value="${qty}" placeholder="0" style="padding:8px; font-size:14px; width:100%; border:1px solid #d0d7e2; border-radius:4px;" oninput="scheduleSaveMedication('${medId}')">
+            </div>
+        </div>
+        <div style="display:grid; grid-template-columns: repeat(2, 1fr); gap:10px; margin-bottom:10px;">
+            <div>
+                <label style="font-weight:700; font-size:12px; display:block; margin-bottom:4px;">Manufacturer</label>
+                <input type="text" class="ph-manufacturer" value="${manu}" placeholder="Optional" style="padding:8px; font-size:14px; width:100%; border:1px solid #d0d7e2; border-radius:4px;" oninput="scheduleSaveMedication('${medId}')">
+            </div>
+            <div>
+                <label style="font-weight:700; font-size:12px; display:block; margin-bottom:4px;">Batch / Lot #</label>
+                <input type="text" class="ph-batch" value="${batch}" placeholder="Optional" style="padding:8px; font-size:14px; width:100%; border:1px solid #d0d7e2; border-radius:4px;" oninput="scheduleSaveMedication('${medId}')">
+            </div>
+        </div>
+        <div>
+            <label style="font-weight:700; font-size:12px; display:block; margin-bottom:4px;">Notes</label>
+            <textarea class="ph-notes" placeholder="Optional notes about this batch" style="width:100%; padding:8px; min-height:50px; font-size:14px; border:1px solid #d0d7e2; border-radius:4px; resize:vertical;" oninput="scheduleSaveMedication('${medId}')">${notes}</textarea>
+        </div>
+    `;
+    container.appendChild(row);
+    
+    // Clear the form fields (like crew vaccine pattern)
+    clearExpiryForm(medId);
+    
+    // Save medication with new batch entry
+    scheduleSaveMedication(medId);
+}
+
+// Persist a single medication after client-side validation. Pulls latest list to avoid
+// editing stale data, performs optimistic UI update, then attempts save; on failure it
+// reloads from server to keep UI consistent.
+async function saveMedication(id, rerender = false) {
+    const openMedIds = getOpenMedIds();
+    const textHeights = getTextareaHeights();
+    // Use current cache; if empty, fetch once
+    if (!pharmacyCache.length) {
+        try {
+            const data = await fetchInventory();
+            pharmacyCache = Array.isArray(data) ? data.map(ensurePharmacyDefaults) : [];
+        } catch (err) {
+            showToast(`Unable to load inventory before saving: ${err.message}`, true);
+            return;
+        }
+    }
+    const med = pharmacyCache.find((m) => m.id === id);
+    if (!med) {
+        showToast('Medication not found (stale view). Reloading...', true);
+        return loadPharmacy();
+    }
+    // Duplicate guard stays client-side so the user gets immediate feedback before POST.
+    const genericVal = (document.getElementById(`gn-${id}`)?.value || '').trim();
+    const strengthVal = (document.getElementById(`str-${id}`)?.value || '').trim();
+    const brandVal = (document.getElementById(`bn-${id}`)?.value || '').trim();
+    const formVal = (document.getElementById(`form-${id}`)?.value || '').trim();
+    const targetKey = canonicalMedKey(genericVal, brandVal, strengthVal, `${formVal} ${strengthVal}`.trim());
+    const dup = pharmacyCache.find((m) => {
+        if (m.id === id) return false;
+        return canonicalMedKey(m.genericName, m.brandName, m.strength, m.formStrength) === targetKey;
+    });
+    if (dup) {
+        alert('A medication with the same Generic + Brand + Strength already exists. Please adjust to keep entries unique.');
+        return;
+    }
+    med.genericName = document.getElementById(`gn-${id}`)?.value || '';
+    med.brandName = document.getElementById(`bn-${id}`)?.value || '';
+    med.form = document.getElementById(`form-${id}`)?.value || '';
+    med.strength = document.getElementById(`str-${id}`)?.value || '';
+    med.minThreshold = document.getElementById(`min-${id}`)?.value || '';
+    med.unit = document.getElementById(`unit-${id}`)?.value || '';
+    med.storageLocation = document.getElementById(`loc-${id}`)?.value || '';
+    med.controlled = (document.getElementById(`ctrl-${id}`)?.value || 'false') === 'true';
+    med.primaryIndication = document.getElementById(`ind-${id}`)?.value || '';
+    med.allergyWarnings = document.getElementById(`alg-${id}`)?.value || '';
+    med.standardDosage = document.getElementById(`dose-${id}`)?.value || '';
+    med.excludeFromResources = !!document.getElementById(`exclude-${id}`)?.checked;
+    const sortVal = document.getElementById(`sort-${id}`)?.value || '';
+    const sortCustom = document.getElementById(`sort-custom-${id}`)?.value || '';
+    med.sortCategory = sortVal === '__custom' ? sortCustom : sortVal || sortCustom || '';
+    med.priorityTier = document.getElementById(`tier-${id}`)?.value || '';
+    med.tierCategory = document.getElementById(`tiercat-${id}`)?.value || '';
+    med.verified = !!document.getElementById(`ver-${id}`)?.checked;
+    med.purchaseHistory = collectPurchaseEntries(id);
+    // Auto-sanitize any non-ISO dates so the save doesn't fail; backend also clears invalid dates.
+    let clearedBadDates = false;
+    med.purchaseHistory = (med.purchaseHistory || []).map((ph) => {
+        const ok = !ph.date || !Number.isNaN(new Date(ph.date).getTime());
+        if (!ok) {
+            clearedBadDates = true;
+            return { ...ph, date: '' };
+        }
+        return ph;
+    });
+    if (clearedBadDates) {
+        showToast('Some expiry dates were not valid and were cleared. Please re-enter as YYYY-MM-DD.', true);
+    }
+    med.formStrength = [med.form, med.strength].join(' ').trim();
+    // Keep top-level manufacturer/batch in sync with first purchase entry for compatibility
+    if (med.purchaseHistory.length) {
+        const first = med.purchaseHistory[0];
+        med.manufacturer = first.manufacturer || '';
+        med.batchLot = first.batchLot || '';
+    } else {
+        med.manufacturer = '';
+        med.batchLot = '';
+    }
+
+    // Optimistic rerender before saving to backend for instant UI feedback
+    if (rerender) {
+        renderPharmacy(pharmacyCache, openMedIds, textHeights);
+    }
+
+    // Validate and persist with error handling; on failure, reload from server to avoid stale UI.
+    const validation = validateMedication(med);
+    if (!validation.ok) {
+        showToast(validation.message, true);
+        return;
+    }
+    try {
+        const res = await fetch(`/api/data/inventory/${encodeURIComponent(id)}`, {
+            method: 'PUT',
+            headers: { 'Content-Type': 'application/json' },
+            credentials: 'same-origin',
+            body: JSON.stringify(med),
+        });
+        const data = await res.json().catch(() => ({}));
+        if (!res.ok || data.error) {
+            throw new Error(data.error || `Status ${res.status}`);
+        }
+        showToast('Medication saved');
+        // Update local cache without full reload to prevent form collapse
+        const idx = pharmacyCache.findIndex(m => m.id === id);
+        if (idx !== -1) {
+            pharmacyCache[idx] = med;
+        }
+        // Only rerender if structure changed (labels, availability, etc)
+        if (rerender) {
+            renderPharmacy(pharmacyCache, openMedIds, textHeights);
+        }
+    } catch (err) {
+        showToast(`Save failed: ${err.message}`, true);
+        console.error('[pharmacy] saveMedication error:', err);
+        // On error, reload from server to ensure consistency
+        await loadPharmacy();
+    }
+}
+
+// Basic client-side guardrails before hitting the backend.
+function validateMedication(med) {
+    // Keep this in sync with backend ensure_item_schema/_validate_expiry for consistent rejection reasons.
+    if (!med.genericName || !med.genericName.trim()) {
+        return { ok: false, message: 'Generic name is required.' };
+    }
+    const hasStrengthHint = /\d/.test(med.formStrength || med.form || '');
+    // Allow strength embedded in the form field (e.g., "Tablet 500 mg"). If not present,
+    // backfill a placeholder so legacy items without strength can still be saved/removed.
+    if ((!med.strength || !med.strength.trim()) && !hasStrengthHint) {
+        med.strength = med.strength || 'unspecified';
+        med.formStrength = med.formStrength || (med.form ? `${med.form} ${med.strength}` : med.strength);
+    }
+    // Do not block saves for expiry date/quantity issues; backend will sanitize.
+    return { ok: true };
+}
+
+/**
+ * Collect and serialize all expiry entries from the DOM for a specific medication.
+ * 
+ * This is the **critical serialization function** that bridges UI state → data model.
+ * When a user edits expiry information in the UI, this function extracts all the
+ * values from the DOM and packages them into the purchaseHistory array structure
+ * expected by the backend.
+ * 
+ * Serialization Flow:
+ * -------------------
+ * 1. User edits expiry fields in the UI (date, quantity, manufacturer, batch, notes)
+ * 2. Change triggers scheduleSaveMedication() → saveMedication()
+ * 3. saveMedication() calls **collectPurchaseEntries()** to read current UI state
+ * 4. Serialized data is sent to backend via PUT /api/data/inventory/{id}
+ * 5. Backend validates and persists to database
+ * 
+ * ID Stability Contract:
+ * ---------------------
+ * Purchase entry IDs (ph-xxx) are **stable across saves**. This is critical because:
+ * - Backend uses IDs to determine update vs insert (upsert logic)
+ * - Editing an existing entry preserves its ID → backend updates in place
+ * - Adding a new entry generates new ID → backend creates new record
+ * - Deleting an entry removes its DOM row → backend deletes from database
+ * 
+ * This ID stability enables precise batch-level tracking where each expiry entry
+ * maintains its identity throughout its lifecycle.
+ * 
+ * @param {string} medId - The medication ID whose expiry entries to collect
+ * 
+ * @returns {Array<Object>} Array of purchase/expiry entries with structure:
+ *   - id {string}: Stable purchase entry ID (ph-<uuid>)
+ *   - date {string}: Expiry date from date input (ISO format YYYY-MM-DD)
+ *   - quantity {string}: Quantity from number input (can be decimal)
+ *   - notes {string}: Notes from textarea
+ *   - manufacturer {string}: Manufacturer name from text input
+ *   - batchLot {string}: Batch/lot number from text input
+ * 
+ * @example
+ * // User has edited two expiry entries in the UI
+ * collectPurchaseEntries('med-12345')
+ * // Returns:
+ * [
+ *   {
+ *     id: "ph-abc123",
+ *     date: "2026-12-31",
+ *     quantity: "100",
+ *     manufacturer: "Pfizer",
+ *     batchLot: "LOT-456",
+ *     notes: "Refrigerate"
+ *   },
+ *   {
+ *     id: "ph-def456",
+ *     date: "2025-06-30",
+ *     quantity: "50",
+ *     manufacturer: "Bayer",
+ *     batchLot: "BATCH-789",
+ *     notes: ""
+ *   }
+ * ]
+ * 
+ * Edge Cases Handled:
+ * ------------------
+ * - Missing container: Returns empty array (medication may not exist or not rendered)
+ * - Missing ph-id on row: Generates new ID (defensive - shouldn't happen normally)
+ * - Missing DOM elements: Uses empty string fallbacks (?.value || '')
+ * - Empty values: Preserved as empty strings (backend validates required fields)
+ * 
+ * Data Flow Integration:
+ * ---------------------
+ * This function is part of the critical save path:
+ * ```
+ * User Edit → collectPurchaseEntries() → saveMedication() → 
+ * → Backend PUT → Database persist → UI refresh
+ * ```
+ * 
+ * Related Functions:
+ * ------------------
+ * - Called by: saveMedication() during save operation
+ * - Counterpart: renderPurchaseRows() (data → DOM rendering)
+ * - Feeds into: Backend upsert_inventory_item() for persistence
+ * - Depends on: DOM structure created by renderPurchaseRows()
+ * 
+ * DOM Structure Expected:
+ * ----------------------
+ * Container: #ph-{medId}
+ * Rows: .purchase-row elements with data-ph-id attribute
+ * Fields within each row:
+ *   - .ph-date (date input)
+ *   - .ph-qty (number input)
+ *   - .ph-notes (textarea)
+ *   - .ph-manufacturer (text input)
+ *   - .ph-batch (text input)
+ * 
+ * Business Context:
+ * ----------------
+ * This function enables batch-level inventory tracking - critical for medical
+ * supplies where different batches of the same medication have different:
+ * - Expiration dates (safety compliance)
+ * - Manufacturers (quality traceability)
+ * - Lot numbers (recall management)
+ * - Quantities (stock management)
+ */
+function collectPurchaseEntries(medId) {
+    // Locate the container holding all expiry rows for this medication
+    const container = document.getElementById(`ph-${medId}`);
+    if (!container) return [];
+    
+    // Serialize every row back into a stable structure
+    // IDs are preserved so backend upserts map correctly (update vs insert)
+    return Array.from(container.querySelectorAll('.purchase-row')).map((row) => {
+        // Extract stable purchase entry ID from data attribute
+        // Generate new ID if missing (defensive - shouldn't happen in normal flow)
+        const phId = row.dataset.phId || uid('ph');
+        
+        return {
+            id: phId,                                                    // Stable ID for backend upsert
+            date: row.querySelector('.ph-date')?.value || '',           // Expiry date (ISO format)
+            quantity: row.querySelector('.ph-qty')?.value || '',        // Batch quantity
+            notes: row.querySelector('.ph-notes')?.value || '',         // Additional info
+            manufacturer: row.querySelector('.ph-manufacturer')?.value || '', // Manufacturer name
+            batchLot: row.querySelector('.ph-batch')?.value || '',      // Batch/lot number
+        };
+    });
+}
+
+async function deleteMedication(id) {
+    if (!confirm('Delete this medication from the inventory?')) return;
+    const confirmText = prompt('Type DELETE to confirm:');
+    if (confirmText !== 'DELETE') {
+        alert('Deletion cancelled.');
+        return;
+    }
+    try {
+        const res = await fetch(`/api/data/inventory/${encodeURIComponent(id)}`, {
+            method: 'DELETE',
+            credentials: 'same-origin',
+        });
+        const data = await res.json().catch(() => ({}));
+        if (!res.ok || data.error) {
+            throw new Error(data.error || `Status ${res.status}`);
+        }
+        showToast('Medication deleted');
+        await loadPharmacy();
+    } catch (err) {
+        console.error('[pharmacy] delete failed', err);
+        showToast(`Unable to delete medication: ${err.message}`, true);
+    }
+}
+
+async function deletePurchaseEntry(medId, phId) {
+    const container = document.getElementById(`ph-${medId}`);
+    if (!container) return;
+    const rows = Array.from(container.querySelectorAll('.purchase-row'));
+    if (!rows.length) return;
+    const target = phId ? rows.find((r) => r.dataset.phId === phId) : rows[rows.length - 1];
+    if (!target) return;
+    const proceed = confirm('Delete this expiry entry?');
+    if (!proceed) return;
+    if (rows.length === 1) {
+        // Keep a single empty row for UX; clear instead of remove.
+        target.querySelector('.ph-date').value = '';
+        target.querySelector('.ph-qty').value = '';
+        target.querySelector('.ph-notes').value = '';
+        const manu = target.querySelector('.ph-manufacturer');
+        const batch = target.querySelector('.ph-batch');
+        if (manu) manu.value = '';
+        if (batch) batch.value = '';
+    } else {
+        target.remove();
+    }
+    await saveMedication(medId);
+}
+
+async function addMedication() {
+    const newId = uid('med');
+    const placeholderName = `New medicine ${newId.slice(-6)}`;
+    try {
+        const draft = ensurePharmacyDefaults({
+            id: newId,
+            genericName: placeholderName,
+            strength: '',
+            purchaseHistory: [],
+            verified: false,
+        });
+        pharmacyCache.push(draft);
+        await fetch(`/api/data/inventory/${encodeURIComponent(newId)}`, {
+            method: 'PUT',
+            headers: { 'Content-Type': 'application/json' },
+            credentials: 'same-origin',
+            body: JSON.stringify(draft),
+        });
+        showToast('Draft medication added — please fill required fields.');
+        loadPharmacy();
+    } catch (err) {
+        showToast(`Unable to add medication: ${err.message}`, true);
+    }
+}
+
+// Expose for inline handlers
+window.loadPharmacy = loadPharmacy;
+window.addMedication = addMedication;
+window.saveMedication = saveMedication;
+window.deleteMedication = deleteMedication;
+window.addPurchaseEntry = addPurchaseEntry;
+window.scheduleSaveMedication = scheduleSaveMedication;
+window.handleMedTierChange = handleMedTierChange;
+window.refreshPharmacyLabelsFromSettings = refreshPharmacyLabelsFromSettings;
+window.sortPharmacyList = function(mode) {
+    const openMedIds = getOpenMedIds();
+    const textHeights = getTextareaHeights();
+    renderPharmacy(pharmacyCache, openMedIds, textHeights);
+};
+window.toggleMedDetails = function(el) {
+    const body = el.nextElementSibling;
+    const icon = el.querySelector('.detail-icon');
+    const isExpanded = body && body.style.display === 'block';
+    if (body) body.style.display = isExpanded ? 'none' : 'block';
+    if (icon) icon.textContent = isExpanded ? '▸' : '▾';
+};
+window.deletePurchaseEntry = deletePurchaseEntry;
+window.togglePurchaseNotes = function(el) {
+    const row = el.closest('.purchase-row');
+    if (!row) return;
+    const notes = row.querySelector('.ph-notes-container');
+    if (!notes) return;
+    const isHidden = notes.style.display === 'none';
+    notes.style.display = isHidden ? 'block' : 'none';
+    el.textContent = isHidden ? 'v' : '>';
+};
+window.addWhoMeds = addWhoMeds;
+window.openWhoListFilePicker = openWhoListFilePicker;
+window.handleWhoListFileImport = handleWhoListFileImport;
+window.preloadPharmacy = preloadPharmacy;
+window.ensurePharmacyLabels = ensurePharmacyLabels;
+window.loadWhoMedsFromServer = loadWhoMedsFromServer;

static/js/recovery.js

@@ -0,0 +1,206 @@
+/* =============================================================================
+ * Author: Rick Escher
+ * Project: SailingMedAdvisor
+ * Context: Google HAI-DEF Framework
+ * Models: Google MedGemmas
+ * Program: Kaggle Impact Challenge
+ * ========================================================================== */
+/*
+Fallback interactivity recovery layer.
+Keeps core UI controls usable if inline handlers fail due stale cache or script load issues.
+*/
+
+(function installUiRecovery() {
+    let crewDataRecoveryPromise = null;
+
+    async function ensureCrewDataFallback() {
+        if (crewDataRecoveryPromise) return crewDataRecoveryPromise;
+        crewDataRecoveryPromise = (async () => {
+            const [patientsRes, historyRes, settingsRes] = await Promise.all([
+                fetch('/api/data/patients', { credentials: 'same-origin' }),
+                fetch('/api/data/history', { credentials: 'same-origin' }),
+                fetch('/api/data/settings', { credentials: 'same-origin' }),
+            ]);
+            if (!patientsRes.ok) {
+                throw new Error(`Patients request failed: ${patientsRes.status}`);
+            }
+            const patients = await patientsRes.json();
+            const history = historyRes.ok ? await historyRes.json().catch(() => []) : [];
+            const settings = settingsRes.ok ? await settingsRes.json().catch(() => ({})) : {};
+            if (typeof window.loadCrewData === 'function' && Array.isArray(patients)) {
+                window.loadCrewData(
+                    patients,
+                    Array.isArray(history) ? history : [],
+                    settings && typeof settings === 'object' ? settings : {}
+                );
+                return true;
+            }
+            return false;
+        })().finally(() => {
+            crewDataRecoveryPromise = null;
+        });
+        return crewDataRecoveryPromise;
+    }
+
+    /**
+     * applyBannerControlsFallback: function-level behavior note for maintainers.
+     * Keep this block synchronized with implementation changes.
+     */
+    function applyBannerControlsFallback(activeTab) {
+        const triageControls = document.getElementById('banner-controls-triage');
+        const crewControls = document.getElementById('banner-controls-crew');
+        const medExportAll = document.getElementById('crew-med-export-all-btn');
+        const crewCsvBtn = document.getElementById('crew-csv-btn');
+        const immigrationZipBtn = document.getElementById('crew-immigration-zip-btn');
+        if (triageControls) triageControls.style.display = activeTab === 'Chat' ? 'flex' : 'none';
+        if (crewControls) crewControls.style.display = (activeTab === 'CrewMedical' || activeTab === 'VesselCrewInfo') ? 'flex' : 'none';
+        if (medExportAll) medExportAll.style.display = activeTab === 'CrewMedical' ? 'inline-flex' : 'none';
+        if (crewCsvBtn) crewCsvBtn.style.display = activeTab === 'VesselCrewInfo' ? 'inline-flex' : 'none';
+        if (immigrationZipBtn) immigrationZipBtn.style.display = activeTab === 'VesselCrewInfo' ? 'inline-flex' : 'none';
+    }
+
+    /**
+     * parseTabTargetFromOnclick: function-level behavior note for maintainers.
+     * Keep this block synchronized with implementation changes.
+     */
+    function parseTabTargetFromOnclick(onclickValue) {
+        const raw = (onclickValue || '').toString();
+        const match = raw.match(/'([^']+)'/);
+        return match ? match[1] : '';
+    }
+
+    /**
+     * emergencyShowTab: function-level behavior note for maintainers.
+     * Keep this block synchronized with implementation changes.
+     */
+    function emergencyShowTab(tabName, triggerEl) {
+        if (!tabName) return;
+        document.querySelectorAll('.content').forEach((section) => {
+            section.style.display = 'none';
+        });
+        const target = document.getElementById(tabName);
+        if (target) target.style.display = 'flex';
+        document.querySelectorAll('.tab').forEach((tab) => tab.classList.remove('active'));
+        if (triggerEl && triggerEl.classList) triggerEl.classList.add('active');
+        if (typeof window.toggleBannerControls === 'function') {
+            window.toggleBannerControls(tabName);
+        } else {
+            applyBannerControlsFallback(tabName);
+        }
+        if (tabName === 'Chat' || tabName === 'CrewMedical' || tabName === 'VesselCrewInfo') {
+            ensureCrewDataFallback().catch(() => {});
+        }
+        if (tabName === 'Chat' && typeof window.updateUI === 'function') {
+            window.updateUI();
+        }
+    }
+
+    /**
+     * bindTabRecovery: function-level behavior note for maintainers.
+     * Keep this block synchronized with implementation changes.
+     */
+    function bindTabRecovery() {
+        document.querySelectorAll('.nav .tab').forEach((btn) => {
+            if (btn.dataset.recoveryBound === '1') return;
+            btn.dataset.recoveryBound = '1';
+            btn.addEventListener('click', (ev) => {
+                const tabName = btn.dataset.tabTarget || parseTabTargetFromOnclick(btn.getAttribute('onclick'));
+                if (!tabName) return;
+                ev.preventDefault();
+                ev.stopImmediatePropagation();
+                if (typeof window.showTab === 'function') {
+                    try {
+                        const maybePromise = window.showTab(btn, tabName);
+                        if (maybePromise && typeof maybePromise.then === 'function') {
+                            maybePromise.catch(() => {
+                                emergencyShowTab(tabName, btn);
+                            });
+                        }
+                    } catch (err) {
+                        emergencyShowTab(tabName, btn);
+                    }
+                } else {
+                    emergencyShowTab(tabName, btn);
+                }
+            }, true);
+        });
+    }
+
+    /**
+     * bindSidebarRecovery: function-level behavior note for maintainers.
+     * Keep this block synchronized with implementation changes.
+     */
+    function bindSidebarRecovery() {
+        document.querySelectorAll('.page-sidebar').forEach((sidebar) => {
+            if (sidebar.dataset.recoveryBound === '1') return;
+            sidebar.dataset.recoveryBound = '1';
+            sidebar.addEventListener('click', (ev) => {
+                const toggleBtn = sidebar.querySelector('.sidebar-toggle');
+                if (toggleBtn && !toggleBtn.contains(ev.target)) return;
+                ev.preventDefault();
+                ev.stopImmediatePropagation();
+                if (typeof window.toggleSidebar === 'function') {
+                    window.toggleSidebar(sidebar);
+                    return;
+                }
+                const nextCollapsed = !sidebar.classList.contains('collapsed');
+                document.querySelectorAll('.page-sidebar').forEach((node) => {
+                    node.classList.toggle('collapsed', nextCollapsed);
+                });
+                document.querySelectorAll('.page-body').forEach((body) => {
+                    body.classList.toggle('sidebar-collapsed', nextCollapsed);
+                    body.classList.toggle('sidebar-open', !nextCollapsed);
+                });
+            }, true);
+        });
+    }
+
+    /**
+     * buildCrewLabel: function-level behavior note for maintainers.
+     * Keep this block synchronized with implementation changes.
+     */
+    function buildCrewLabel(crew) {
+        const first = (crew && crew.firstName) ? String(crew.firstName).trim() : '';
+        const last = (crew && crew.lastName) ? String(crew.lastName).trim() : '';
+        const full = `${first} ${last}`.trim();
+        if (full) return full;
+        if (crew && crew.name) return String(crew.name).trim();
+        return 'Unnamed Crew';
+    }
+
+    async function ensureCrewDropdownFallback() {
+        const select = document.getElementById('p-select');
+        if (!select) return;
+        const hasRealOptions = Array.from(select.options || []).some((opt) => (opt.value || '').toString().trim());
+        if (hasRealOptions) return;
+        try {
+            const res = await fetch('/api/data/patients', { credentials: 'same-origin' });
+            if (!res.ok) return;
+            const patients = await res.json();
+            if (!Array.isArray(patients)) return;
+            const current = select.value || '';
+            select.innerHTML = '<option value="">Unnamed Crew Member</option>';
+            patients.forEach((crew) => {
+                const opt = document.createElement('option');
+                opt.value = String((crew && crew.id) || '');
+                opt.textContent = buildCrewLabel(crew);
+                select.appendChild(opt);
+            });
+            if (current) select.value = current;
+        } catch (err) {
+            // Best-effort fallback only.
+        }
+    }
+
+    document.addEventListener('DOMContentLoaded', () => {
+        bindTabRecovery();
+        bindSidebarRecovery();
+        ensureCrewDataFallback().catch(() => {});
+        ensureCrewDropdownFallback();
+        if (typeof window.toggleBannerControls === 'function') {
+            window.toggleBannerControls('Chat');
+        } else {
+            applyBannerControlsFallback('Chat');
+        }
+    });
+})();

static/js/utils.js

@@ -0,0 +1,497 @@
+/* =============================================================================
+ * Author: Rick Escher
+ * Project: SailingMedAdvisor
+ * Context: Google HAI-DEF Framework
+ * Models: Google MedGemmas
+ * Program: Kaggle Impact Challenge
+ * ========================================================================== */
+/*
+File: static/js/utils.js
+Author notes: Shared utility functions for the SailingMedAdvisor frontend.
+
+Key Responsibilities:
+- HTML escaping for XSS prevention
+- Debounce utility for input handlers
+- Workspace header injection (multi-tenant placeholder)
+- Centralized fetch wrapper with error handling
+- Data category fetch helper
+
+Architecture:
+------------
+Implemented as IIFE (Immediately Invoked Function Expression) that:
+1. Creates or extends window.Utils namespace
+2. Registers utility functions
+3. Exposes both namespaced (Utils.escapeHtml) and global (escapeHtml) versions
+
+Usage Pattern:
+```javascript
+// Preferred (namespaced):
+const safe = Utils.escapeHtml(userInput);
+
+// Legacy (global):
+const safe = escapeHtml(userInput);
+```
+
+Integration:
+All modules import these utilities with fallbacks:
+```javascript
+const escapeHtml = (window.Utils && window.Utils.escapeHtml) 
+  ? window.Utils.escapeHtml 
+  : (str) => str;
+```
+
+This allows modules to work even if utils.js fails to load.
+*/
+
+(function registerUtils() {
+    const Utils = window.Utils || {};
+    const CHAT_SECTION_LABELS = new Set(['avoid', 'monitor', 'evacuation', 'questions']);
+
+    /**
+     * normalizeChatSectionMarkdown: function-level behavior note for maintainers.
+     * Keep this block synchronized with implementation changes.
+     */
+    function normalizeChatSectionMarkdown(raw) {
+        return (raw || '')
+            .toString()
+            .replace(/\r\n?/g, '\n')
+            .replace(
+                /(^|\n)\s*(?:\*\*)?\s*(Avoid|Monitor|Evacuation|Questions)\s*(?:\*\*)?\s*[–-]\s+/gim,
+                (_match, lead, label) => `${lead}**${label.charAt(0).toUpperCase()}${label.slice(1).toLowerCase()}:** `
+            );
+    }
+
+    /**
+     * normalizeChecklistMarkdown: function-level behavior note for maintainers.
+     * Keep this block synchronized with implementation changes.
+     */
+    function normalizeChecklistMarkdown(raw) {
+        const lines = (raw || '').toString().replace(/\r\n?/g, '\n').split('\n');
+        const normalized = lines.map((line) => {
+            const heading = line.match(/^\s*\[\s*[xX ]\s*\]\s*\*\*(.+?)\*\*\s*:?\s*$/);
+            if (heading) {
+                return `**${heading[1].trim()}:**`;
+            }
+            const item = line.match(/^\s*\[\s*[xX ]\s*\]\s+(.+)$/);
+            if (item) {
+                return `- ${item[1].trim()}`;
+            }
+            return line;
+        });
+        return normalized.join('\n');
+    }
+
+    /**
+     * normalizeSectionLabelText: function-level behavior note for maintainers.
+     * Keep this block synchronized with implementation changes.
+     */
+    function normalizeSectionLabelText(text) {
+        return (text || '')
+            .toString()
+            .replace(/\*/g, '')
+            .replace(/[:：]\s*$/, '')
+            .trim()
+            .toLowerCase();
+    }
+
+    /**
+     * annotateChatSections: function-level behavior note for maintainers.
+     * Keep this block synchronized with implementation changes.
+     */
+    function annotateChatSections(root) {
+        if (!root || typeof root.querySelectorAll !== 'function') return;
+
+        root.querySelectorAll('strong').forEach((el) => {
+            if (CHAT_SECTION_LABELS.has(normalizeSectionLabelText(el.textContent))) {
+                el.classList.add('chat-section-label');
+            }
+        });
+
+        root.querySelectorAll('p').forEach((p) => {
+            const text = (p.textContent || '').trim();
+            const dashMatch = text.match(/^(Avoid|Monitor|Evacuation|Questions)\s*[–-]\s+(.+)$/i);
+            if (dashMatch) {
+                p.classList.add('chat-section-heading');
+                p.innerHTML = `<strong class="chat-section-label">${dashMatch[1]}:</strong> ${Utils.escapeHtml(dashMatch[2])}`;
+                return;
+            }
+            const strong = p.querySelector('strong');
+            if (strong && CHAT_SECTION_LABELS.has(normalizeSectionLabelText(strong.textContent))) {
+                p.classList.add('chat-section-heading');
+            }
+        });
+    }
+
+    /**
+     * extractJsonCandidateText: function-level behavior note for maintainers.
+     * Keep this block synchronized with implementation changes.
+     */
+    function extractJsonCandidateText(raw) {
+        const trimmed = (raw || '').toString().trim();
+        if (!trimmed) return '';
+        const fenceMatch = trimmed.match(/^```(?:json)?\s*([\s\S]*?)\s*```$/i);
+        return (fenceMatch ? fenceMatch[1] : trimmed).trim();
+    }
+
+    /**
+     * tryParseJsonPayload: function-level behavior note for maintainers.
+     * Keep this block synchronized with implementation changes.
+     */
+    function tryParseJsonPayload(raw) {
+        let candidate = extractJsonCandidateText(raw);
+        if (!candidate || (!candidate.startsWith('{') && !candidate.startsWith('['))) {
+            return null;
+        }
+        for (let i = 0; i < 2; i += 1) {
+            try {
+                const parsed = JSON.parse(candidate);
+                if (typeof parsed === 'string') {
+                    candidate = parsed.trim();
+                    if (!candidate.startsWith('{') && !candidate.startsWith('[')) {
+                        return null;
+                    }
+                    continue;
+                }
+                return parsed;
+            } catch (_err) {
+                return null;
+            }
+        }
+        return null;
+    }
+
+    /**
+     * formatJsonInline: function-level behavior note for maintainers.
+     * Keep this block synchronized with implementation changes.
+     */
+    function formatJsonInline(value) {
+        if (value === null) return 'null';
+        if (typeof value === 'string') return value.trim();
+        if (typeof value === 'number' || typeof value === 'boolean') return String(value);
+        if (Array.isArray(value)) {
+            const primitive = value.every((item) => item === null || ['string', 'number', 'boolean'].includes(typeof item));
+            if (primitive) {
+                return value.map((item) => formatJsonInline(item)).join('; ');
+            }
+        }
+        return JSON.stringify(value);
+    }
+
+    /**
+     * formatJsonSection: function-level behavior note for maintainers.
+     * Keep this block synchronized with implementation changes.
+     */
+    function formatJsonSection(title, value) {
+        if (value === null || ['string', 'number', 'boolean'].includes(typeof value)) {
+            return `**${title}:** ${formatJsonInline(value)}`;
+        }
+        if (Array.isArray(value)) {
+            if (!value.length) return `**${title}:** (none)`;
+            const bullets = value.map((item) => `- ${formatJsonInline(item)}`).join('\n');
+            return `**${title}:**\n${bullets}`;
+        }
+        if (value && typeof value === 'object') {
+            const entries = Object.entries(value);
+            if (!entries.length) return `**${title}:** (none)`;
+            const bullets = entries
+                .map(([k, v]) => `- ${k}: ${formatJsonInline(v)}`)
+                .join('\n');
+            return `**${title}:**\n${bullets}`;
+        }
+        return `**${title}:** ${formatJsonInline(value)}`;
+    }
+
+    /**
+     * jsonToMarkdown: function-level behavior note for maintainers.
+     * Keep this block synchronized with implementation changes.
+     */
+    function jsonToMarkdown(value) {
+        if (value && typeof value === 'object' && !Array.isArray(value)) {
+            const keyMap = {};
+            Object.keys(value).forEach((key) => {
+                keyMap[key.toLowerCase()] = key;
+            });
+            const preferred = ['Avoid', 'Monitor', 'Evacuation', 'Questions'];
+            const used = new Set();
+            const blocks = [];
+
+            preferred.forEach((label) => {
+                const realKey = keyMap[label.toLowerCase()];
+                if (!realKey) return;
+                used.add(realKey);
+                blocks.push(formatJsonSection(label, value[realKey]));
+            });
+
+            Object.keys(value).forEach((key) => {
+                if (used.has(key)) return;
+                blocks.push(formatJsonSection(key, value[key]));
+            });
+
+            if (blocks.length) {
+                return blocks.join('\n\n').trim();
+            }
+        }
+        return `\`\`\`json\n${JSON.stringify(value, null, 2)}\n\`\`\``;
+    }
+
+    /**
+     * Escape HTML special characters to prevent XSS attacks.
+     * 
+     * Character Mappings:
+     * - & → &amp;
+     * - < → &lt;
+     * - > → &gt;
+     * - " → &quot;
+     * - ' → &#39;
+     * 
+     * Use Cases:
+     * - Displaying user-entered text in HTML
+     * - Rendering crew names, medication names
+     * - Chat responses (before markdown parsing)
+     * - Search results
+     * - Any untrusted content inserted into DOM
+     * 
+     * Security:
+     * Essential for preventing XSS when rendering user data. Always
+     * escape before inserting into innerHTML or creating HTML strings.
+     * 
+     * Example:
+     * ```javascript
+     * const name = "<script>alert('xss')</script>";
+     * el.innerHTML = Utils.escapeHtml(name);
+     * // Result: &lt;script&gt;alert(&#39;xss&#39;)&lt;/script&gt;
+     * ```
+     * 
+     * @param {string} str - String to escape
+     * @returns {string} Escaped string safe for HTML insertion
+     */
+    Utils.escapeHtml = function escapeHtml(str) {
+        return (str || '')
+            .replace(/&/g, '&amp;')
+            .replace(/</g, '&lt;')
+            .replace(/>/g, '&gt;')
+            .replace(/"/g, '&quot;')
+            .replace(/'/g, '&#39;');
+    };
+
+    /**
+     * Debounce function calls to reduce execution frequency.
+     * 
+     * Debouncing delays function execution until after a specified time
+     * has elapsed since the last call. Useful for expensive operations
+     * triggered by rapid user input.
+     * 
+     * Use Cases:
+     * - Search input: Wait for user to stop typing
+     * - Auto-save: Batch saves instead of save-per-keystroke
+     * - Window resize handlers: Prevent layout thrashing
+     * - Scroll handlers: Reduce computation during scrolling
+     * 
+     * Behavior:
+     * 1. First call: Starts timer
+     * 2. Subsequent calls: Reset timer
+     * 3. After delay expires: Execute function once with latest arguments
+     * 
+     * Example:
+     * ```javascript
+     * const saveSettings = Utils.debounce(() => {
+     *   fetch('/api/settings', {method: 'POST', ...});
+     * }, 800);
+     * 
+     * // User types rapidly:
+     * saveSettings(); // Timer starts
+     * saveSettings(); // Timer resets
+     * saveSettings(); // Timer resets
+     * // 800ms later: One save executed
+     * ```
+     * 
+     * Common Delays:
+     * - 250ms: Input validation, search
+     * - 400ms: Crew credentials, simple saves
+     * - 600ms: Equipment auto-save
+     * - 800ms: Settings auto-save
+     * 
+     * @param {Function} fn - Function to debounce
+     * @param {number} delay - Delay in milliseconds (default: 250)
+     * @returns {Function} Debounced function
+     */
+    Utils.debounce = function debounce(fn, delay = 250) {
+        let timer = null;
+        return (...args) => {
+            if (timer) clearTimeout(timer);
+            timer = setTimeout(() => fn(...args), delay);
+        };
+    };
+
+    /**
+     * Get current workspace label for display.
+     * 
+     * Multi-Tenant Placeholder:
+     * Currently returns empty string as multi-tenancy not yet implemented.
+     * Future versions will return workspace name (vessel name, user account).
+     * 
+     * Planned Use Cases:
+     * - Display current vessel name in header
+     * - Show workspace in exported files
+     * - Include in error reports
+     * 
+     * @returns {string} Workspace label (currently empty)
+     * @deprecated Not yet implemented
+     */
+    Utils.getWorkspaceLabel = function getWorkspaceLabel() {
+        return '';
+    };
+
+    /**
+     * Generate HTTP headers with workspace context.
+     * 
+     * Multi-Tenant Placeholder:
+     * Currently returns headers unchanged. Future versions will inject
+     * workspace identifier headers for server-side routing.
+     * 
+     * Planned Headers:
+     * - X-Workspace-Id: Unique workspace identifier
+     * - X-Vessel-Name: Vessel name for logging
+     * 
+     * Current Usage:
+     * ```javascript
+     * fetch('/api/data/patients', {
+     *   headers: workspaceHeaders({'Content-Type': 'application/json'})
+     * })
+     * ```
+     * 
+     * Used Throughout:
+     * - equipment.js: Equipment saves
+     * - crew.js: Crew data operations
+     * - pharmacy.js: Medication operations
+     * 
+     * @param {Object} extra - Additional headers to include
+     * @returns {Object} Headers object with workspace context (currently just extra)
+     */
+    Utils.workspaceHeaders = function workspaceHeaders(extra = {}) {
+        return { ...extra };
+    };
+
+    /**
+     * Fetch JSON with enhanced error handling and parsing.
+     * 
+     * Enhanced Fetch Features:
+     * 1. Auto-includes credentials for cookie-based auth
+     * 2. Handles empty responses gracefully (returns {})
+     * 3. Attempts JSON parse even on error responses
+     * 4. Throws detailed errors with response text
+     * 5. Consistent error format across all API calls
+     * 
+     * Error Handling:
+     * - HTTP error: Throws with status code
+     * - JSON parse failure: Returns {} instead of throwing
+     * - API error field: Extracts and throws error message
+     * 
+     * Example Success:
+     * ```javascript
+     * const crew = await fetchJson('/api/data/patients');
+     * // Returns: [{id: 'crew-1', name: 'John'}, ...]
+     * ```
+     * 
+     * Example Error:
+     * ```javascript
+     * try {
+     *   await fetchJson('/api/data/invalid');
+     * } catch (err) {
+     *   // err.message: "Not found" or "Status 404"
+     * }
+     * ```
+     * 
+     * Advantages Over Raw Fetch:
+     * - Consistent error messages
+     * - No need to check res.ok manually
+     * - Handles malformed JSON gracefully
+     * - Credentials included by default
+     * 
+     * Used Throughout:
+     * All modules use this for API calls instead of raw fetch.
+     * 
+     * @param {string} url - API endpoint URL
+     * @param {Object} options - Fetch options (method, headers, body, etc.)
+     * @returns {Promise<Object>} Parsed JSON response
+     * @throws {Error} On HTTP error or API error response
+     */
+    Utils.fetchJson = async function fetchJson(url, options = {}) {
+        const res = await fetch(url, { credentials: 'same-origin', ...options });
+        const text = await res.text();
+        let data = {};
+        try {
+            data = text ? JSON.parse(text) : {};
+        } catch (err) {
+            data = {};
+        }
+        if (!res.ok || data?.error) {
+            const detail = data?.error || text || `Status ${res.status}`;
+            throw new Error(detail);
+        }
+        return data;
+    };
+
+    /**
+     * Fetch data by category shorthand.
+     * 
+     * Convenience wrapper for common /api/data/* endpoints.
+     * 
+     * Categories:
+     * - 'patients': /api/data/patients (crew list)
+     * - 'history': /api/data/history (chat logs)
+     * - 'settings': /api/data/settings (app config)
+     * - 'inventory': /api/data/inventory (medications)
+     * - 'tools': /api/data/tools (equipment/consumables)
+     * - 'vessel': /api/data/vessel (vessel info)
+     * 
+     * Example:
+     * ```javascript
+     * const crew = await Utils.fetchDataCategory('patients');
+     * // Equivalent to: Utils.fetchJson('/api/data/patients')
+     * ```
+     * 
+     * Benefits:
+     * - Shorter, more readable code
+     * - Consistent URL construction
+     * - Type-safe category names (if using TypeScript)
+     * 
+     * @param {string} category - Data category name
+     * @param {Object} options - Fetch options
+     * @returns {Promise<Object>} Parsed JSON response
+     */
+    Utils.fetchDataCategory = async function fetchDataCategory(category, options = {}) {
+        return Utils.fetchJson(`/api/data/${category}`, options);
+    };
+
+    Utils.renderAssistantMarkdown = function renderAssistantMarkdown(raw) {
+        const parsedJson = tryParseJsonPayload(raw);
+        const source = parsedJson === null ? raw : jsonToMarkdown(parsedJson);
+        const normalized = normalizeChatSectionMarkdown(normalizeChecklistMarkdown(source));
+        if (!window.marked || typeof window.marked.parse !== 'function') {
+            return Utils.escapeHtml(normalized).replace(/\n/g, '<br>');
+        }
+        const html = window.marked.parse(normalized, { gfm: true, breaks: true });
+        const wrapper = document.createElement('div');
+        wrapper.innerHTML = html;
+        annotateChatSections(wrapper);
+        return wrapper.innerHTML;
+    };
+
+    // Register Utils namespace globally
+    window.Utils = Utils;
+    
+    /**
+     * Legacy Global Exposure:
+     * Expose escapeHtml directly to window for backward compatibility
+     * with scripts that expect it in global scope.
+     * 
+     * Deprecated Pattern:
+     * Old: window.escapeHtml(str)
+     * New: Utils.escapeHtml(str)
+     * 
+     * Both work, but namespaced version preferred.
+     */
+    window.escapeHtml = Utils.escapeHtml;
+    window.renderAssistantMarkdown = Utils.renderAssistantMarkdown;
+})();

static/style.css

@@ -0,0 +1,30 @@
+/* ============================================================================
+   Author: Rick Escher
+   Project: SailingMedAdvisor
+   Context: Google HAI-DEF Framework
+   Models: Google MedGemmas
+   Program: Kaggle Impact Challenge
+   ========================================================================== */
+
+/* GENERAL STYLING */
+body { font-family: sans-serif; background: #eceff1; margin: 0; padding: 10px; }
+.tab-container { display: flex; background: #263238; border-radius: 5px; padding: 5px; margin-bottom: 10px; }
+.tab-link { flex: 1; background: none; border: none; color: white; padding: 15px; cursor: pointer; }
+.tab-link.active { background: #37474f; border-bottom: 3px solid #00e5ff; font-weight: bold; }
+.tab-content { background: white; padding: 20px; border-radius: 5px; display: none; min-height: 600px; box-shadow: 0 2px 5px rgba(0,0,0,0.2); }
+
+/* CHAT INTERFACE */
+.scroll-area { background: #fdfdfd; border: 1px solid #ddd; border-radius: 5px; overflow-y: auto; display: flex; flex-direction: column; padding: 10px; }
+.user-bubble { background: #e3f2fd; align-self: flex-end; padding: 10px; border-radius: 10px; margin: 5px; border: 1px solid #bbdefb; max-width: 80%; }
+.ai-bubble { background: #f5f5f5; align-self: flex-start; padding: 10px; border-radius: 10px; margin: 5px; border: 1px solid #e0e0e0; max-width: 80%; }
+.emergency-btn { background: #d32f2f; color: white; border: none; padding: 15px 30px; border-radius: 5px; cursor: pointer; font-weight: bold; }
+.emergency-btn:disabled { background: #9e9e9e; }
+
+/* INVENTORY & CREW */
+table { width: 100%; border-collapse: collapse; margin-top: 20px; }
+th, td { border: 1px solid #ddd; padding: 12px; text-align: left; }
+th { background: #f1f1f1; }
+.form-group { display: flex; flex-direction: column; gap: 10px; max-width: 500px; margin-bottom: 20px; }
+textarea { height: 100px; padding: 10px; }
+input[type="text"] { padding: 10px; }
+.card { border-left: 5px solid #00e5ff; background: #f9f9f9; padding: 10px; margin: 10px 0; }