docs: add deployment guide, update env docs and changelog

.env.example

@@ -1,102 +1,205 @@
+# =============================================================================
 # .env.example
+# =============================================================================
 #
-# 1) Copy to .env.local
-# 2) Choose deployment mode:
-#    - NEXT_PUBLIC_DEPLOYMENT_MODE=staging|production (recommended)
-#    - NEXT_PUBLIC_DEPLOYMENT_MODE=manual for strict override mode (requires vars below)
+# This file documents every environment variable used by the ModelSEED UI.
 #
-# Local Poplar tunnel example:
-# ssh -L 8000:localhost:8000 YOUR_USERNAME@poplar.cels.anl.gov
+# HOW TO USE THIS FILE:
+#   1. Copy this file to .env.local
+#      cp .env.example .env.local
+#   2. Choose a deployment mode (see DEPLOYMENT MODE section below)
+#   3. Fill in any required overrides for your environment
+#   4. Restart the dev server or rebuild for changes to take effect
+#
+# DEPLOYMENT MODES:
+#   There are two ways to configure endpoints: by deployment mode, or by
+#   manual override. Deployment mode is the recommended approach.
+#
+#   staging    - Points all endpoints at staging.modelseed.org.
+#                Requires zero override configuration. This is the default
+#                when NEXT_PUBLIC_DEPLOYMENT_MODE is unset.
+#
+#   production - Points all endpoints at modelseed.org.
+#                Requires zero override configuration.
+#
+#   manual     - Disables automatic endpoint resolution. Every URL must be
+#                provided explicitly via *_BASE_URL override variables.
+#                Useful for local development against custom backends.
+#                If any required override is missing in manual mode, the app
+#                will throw an error at startup.
+#
+# RESOLUTION ORDER (for every URL-type variable):
+#   1. Override (highest precedence) -- e.g. NEXT_PUBLIC_SITE_BASE_URL
+#   2. Mode-specific default          -- e.g. NEXT_PUBLIC_SITE_BASE_URL_STAGING
+#   3. Hardcoded fallback built into config.ts
+#
+# OPTIONAL vs REQUIRED:
+#   - "optional" means the app has a sensible default and will work if you
+#     leave it blank or unset.
+#   - "required in manual mode" means you must set it yourself when
+#     NEXT_PUBLIC_DEPLOYMENT_MODE=manual, but it is ignored otherwise.
+#   - "required" means the app will not function without it in any mode.
+#
+# =============================================================================
 
-# =========================
-# Deployment Mode (required - set to staging, production, or manual)
-# =========================
+# =============================================================================
+# DEPLOYMENT MODE
+# =============================================================================
+
+# Controls which set of endpoint defaults the application uses.
+#
+# Values:  staging | production | manual
+# Default: staging (when unset or empty)
+# Required: No (optional; defaults to staging when unset or empty)
+#
+# Set to "staging" or "production" for automatic endpoint configuration.
+# Set to "manual" if you want to provide every endpoint URL yourself.
 NEXT_PUBLIC_DEPLOYMENT_MODE=staging
 
-# =========================
-# Site URL defaults + override
-# =========================
-# Override (highest precedence, no trailing slash)
+# =============================================================================
+# SITE BASE URL
+# =============================================================================
+# The base origin used to derive all relative backend paths.
+# No trailing slash.
+#
+# Override:       Required in manual mode, otherwise optional (mode default used)
+# Mode default:   staging=https://staging.modelseed.org | production=https://modelseed.org
+# Hardcoded:      staging=https://staging.modelseed.org | production=https://modelseed.org
 NEXT_PUBLIC_SITE_BASE_URL=
-# Mode defaults
 NEXT_PUBLIC_SITE_BASE_URL_STAGING=https://staging.modelseed.org
 NEXT_PUBLIC_SITE_BASE_URL_PRODUCTION=https://modelseed.org
 
-# =========================
-# modelseed-api defaults + override
-# =========================
-# Override (highest precedence, no trailing slash)
-# Example local tunnel:
-NEXT_PUBLIC_API_BASE_URL=http://localhost:8000
-# Mode defaults
+# =============================================================================
+# MODELSEED-API BASE URL (modelseed_support / PMS)
+# =============================================================================
+# Base URL for the modelseed-api service. No trailing slash.
+#
+# Override:       Required in manual mode, otherwise optional (mode default used)
+# Mode default:   staging=https://staging.modelseed.org/PMS | production=https://modelseed.org/PMS
+# Fallback:       {MODELSEED_SITE_BASE_URL}/PMS
+NEXT_PUBLIC_API_BASE_URL=
 NEXT_PUBLIC_API_BASE_URL_STAGING=https://staging.modelseed.org/PMS
 NEXT_PUBLIC_API_BASE_URL_PRODUCTION=https://modelseed.org/PMS
 
-# =========================
-# Legacy REST defaults + override (/api/v0)
-# =========================
+# =============================================================================
+# LEGACY REST BASE URL (/api/v0)
+# =============================================================================
+# Base URL for the legacy ModelSEED REST v0 API. No trailing slash.
+#
+# Override:       Required in manual mode, otherwise optional (mode default used)
+# Mode default:   staging=https://staging.modelseed.org/api/v0 | production=https://modelseed.org/api/v0
+# Fallback:       {MODELSEED_SITE_BASE_URL}/api/v0
 NEXT_PUBLIC_REST_BASE_URL=
 NEXT_PUBLIC_REST_BASE_URL_STAGING=https://staging.modelseed.org/api/v0
 NEXT_PUBLIC_REST_BASE_URL_PRODUCTION=https://modelseed.org/api/v0
 
-# =========================
-# Status endpoint defaults + override (/about/version)
-# =========================
+# =============================================================================
+# STATUS API URL (/about/version)
+# =============================================================================
+# Endpoint used by the /about/version page to report build and service status.
+# No trailing slash.
+#
+# Override:       Required in manual mode, otherwise optional (mode default used)
+# Mode default:   staging=https://staging.modelseed.org/api/test-service | production=https://modelseed.org/api/test-service
+# Fallback:       {MODELSEED_SITE_BASE_URL}/api/test-service
 NEXT_PUBLIC_STATUS_API_URL=
 NEXT_PUBLIC_STATUS_API_URL_STAGING=https://staging.modelseed.org/api/test-service
 NEXT_PUBLIC_STATUS_API_URL_PRODUCTION=https://modelseed.org/api/test-service
 
-# =========================
-# Solr base defaults + override
-# =========================
-# Override (highest precedence, with or without trailing slash)
+# =============================================================================
+# SOLR BASE URL
+# =============================================================================
+# Base URL for the Solr search backend. Trailing slash is stripped at runtime.
+#
+# Override:       Required in manual mode, otherwise optional (mode default used)
+# Mode default:   staging=https://staging.modelseed.org/solr/ | production=https://modelseed.org/solr/
+# Fallback:       {MODELSEED_SITE_BASE_URL}/solr/
 NEXT_PUBLIC_SOLR_BASE_URL=
-# Mode defaults
 NEXT_PUBLIC_SOLR_BASE_URL_STAGING=https://staging.modelseed.org/solr/
 NEXT_PUBLIC_SOLR_BASE_URL_PRODUCTION=https://modelseed.org/solr/
 
-# =========================
-# Solr collection/core defaults + override
-# =========================
-# Overrides (highest precedence)
+# =============================================================================
+# SOLR COLLECTION / CORE NAMES
+# =============================================================================
+# The Solr core names for the reactions and compounds collections.
+# These must match the names configured in your Solr instance.
+#
+# Override:       Required in manual mode, otherwise optional (mode default used)
+# Mode default:   staging=reactions_staging / compounds_staging
+#                 production=reactions / compounds
+# Fallback:       staging: "reactions_staging" / "compounds_staging"
+#                 production: "reactions" / "compounds"
 NEXT_PUBLIC_SOLR_REACTIONS_COLLECTION=
 NEXT_PUBLIC_SOLR_COMPOUNDS_COLLECTION=
-# Mode defaults
 NEXT_PUBLIC_SOLR_REACTIONS_COLLECTION_STAGING=reactions_staging
-NEXT_PUBLIC_SOLR_REACTIONS_COLLECTION_PRODUCTION=reactions
 NEXT_PUBLIC_SOLR_COMPOUNDS_COLLECTION_STAGING=compounds_staging
+NEXT_PUBLIC_SOLR_REACTIONS_COLLECTION_PRODUCTION=reactions
 NEXT_PUBLIC_SOLR_COMPOUNDS_COLLECTION_PRODUCTION=compounds
 
-# =========================
-# Feature Flags
-# =========================
+# =============================================================================
+# FEATURE FLAGS
+# =============================================================================
+
+# Enables the modelseed-api proxy for workspace operations.
+# When false, falls back to the legacy direct Workspace URL.
+# Values: true | false
+# Default: true
 NEXT_PUBLIC_USE_MODELSEED_API=true
+
+# Enables the new proxy layer for backend services.
+# When false, certain services (ProbModelSEED, Workspace) fall back to
+# legacy direct endpoints.
+# Values: true | false
+# Default: true
 NEXT_PUBLIC_USE_NEW_PROXY=true
 
-# =========================
-# ProbModelSEED URL Override
-# =========================
-# Override for ProbModelSEED API endpoint (no trailing slash)
-# Defaults to {SITE_BASE}/api/model when USE_NEW_PROXY=true
+# =============================================================================
+# PROBMODELSEED URL
+# =============================================================================
+# Override for the ProbModelSEED API endpoint. No trailing slash.
+#
+# When NEXT_PUBLIC_USE_NEW_PROXY=true and this is unset, defaults to:
+#   {MODELSEED_SITE_BASE_URL}/api/model
+#
+# When NEXT_PUBLIC_USE_NEW_PROXY=false, this is ignored and the legacy URL
+#   https://p3.theseed.org/services/ProbModelSEED
+# is used instead.
+#
+# Override:  Optional (computed from SITE_BASE_URL when using new proxy)
 NEXT_PUBLIC_PROBMODELSEED_URL=
 
-# =========================
-# RDKit.js URL Override (optional)
-# =========================
-# Override for RDKit.js assets (no trailing slash)
-# Defaults to unpkg CDN when unset - no need to set unless self-hosting
+# =============================================================================
+# RDKIT.JS URL
+# =============================================================================
+# Override for self-hosted RDKit.js assets. No trailing slash.
+#
+# When unset, the app loads RDKit.js from the unpkg CDN:
+#   https://unpkg.com/@rdkit/rdkit@{VERSION}/dist
+#
+# Set this only if you are self-hosting RDKit.js.
+# If the assets are in public/rdkit, set NEXT_PUBLIC_RDKIT_BASE_URL=/rdkit.
+# Value will have trailing slash stripped at runtime.
+#
+# Override:  Optional. Defaults to unpkg CDN.
 # NEXT_PUBLIC_RDKIT_BASE_URL=
 
-# =========================
-# Build Metadata (/about/version)
-# =========================
-NEXT_PUBLIC_GIT_VERSION=3.0.0
-NEXT_PUBLIC_GIT_BRANCH=staging
+# =============================================================================
+# BUILD METADATA
+# =============================================================================
+# These values are injected at build time by CI/CD and displayed on the
+# /about/version page. They do not affect runtime behavior.
+#
+# Default: (populated by CI; safe to leave blank for local dev)
+NEXT_PUBLIC_GIT_VERSION=
+NEXT_PUBLIC_GIT_BRANCH=
 NEXT_PUBLIC_GIT_COMMIT=
 NEXT_PUBLIC_DEPLOY_DATE=
 
-# =========================
-# Test Credentials
-# =========================
-# PATRIC token for API testing (get from PATRIC website)
-PATRIC_TOKEN=
+# =============================================================================
+# TEST CREDENTIALS
+# =============================================================================
+# PATRIC authentication token for integration testing.
+# Get a token from https://p3.theseed.org/user/authenticate
+#
+# Optional. Not required for application functionality.
+PATRIC_TOKEN=

CHANGELOG.md

@@ -5,33 +5,66 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [{{VERSION}}] - 2026-04-06
+## [Unreleased] - TBD
+
+### Known Issues
+- RAST MS FBA not working
+- PATRIC-only model submission
+- Workspace write operations limited
+
+### Expected Behaviors
+- Models/Media differ between RAST and PATRIC (intentional system design)
+
+---
+
+## [3.0.1] - 2026-05-12
 
 ### Added
-- Compound structure images on reaction pages with click-through to compound detail pages
-- Comprehensive troubleshooting documentation and enhanced README with SSH tunnel setup instructions
+- Find-in-page style search replacing the legacy search bar across the application
+- Multiple filter rows with AND/OR logic in the DataControlHeader toolbar
+- Case-insensitive Solr matching via case-variant filter clauses
+- Hover tooltips and popup dialog for pathway visualization in the reactions table
+- Reaction comments API route with modal UI integration
+- PlantSEED copy functionality with editing restrictions for reconstructed models
+- Branch name and upstream repository link displayed on the `/about/version` screen
+- Compound synonym formatting with chemistry-aware scripts and improved list layout
+- Gene reactions rendered as linked chips on model detail pages
+- Production-quality polish applied to 8 secondary pages
 
 ### Changed
-- Version display updated to show v{{VERSION}} from environment
+- Compound detail and reaction detail pages stabilized with improved metadata presentation
+- Reaction structure cards fixed and compound detail refined
 
 ### Fixed
-- Invalid gapfill URL handling to gracefully return empty results instead of 404 errors
-- Improved Reaction/Compound detail drawer with better typography and monospace formatting
-
-### Documentation
-- SSH tunnel requirements, environment variables, and account separation expectations
+- Compounds Solr quick search repaired (was using invalid ontology field)
+- DataControlHeader hardened across all grid consumers to prevent filter state loss
+- Dual-backend filtering in search hardened
+- Grid state preserved when using `onApplyFilterModel` for server-side pagination
+- Toolbar filter intent preserved correctly across community grid constraint changes
+- FBA detail data now loaded by `fba_id` instead of incorrect reference
+- Model detail pages now use canonical model ref for both FBA and gapfill data
+- Gapfill page fixed to properly parse solution data and handle incorrect API refs
+- Explicit unavailable-image placeholders added to prevent broken image UI
+- Filtered row count now used in CustomPagination for accurate display
+- JSON parse error handling in the comments route returns 400 on malformed input
+- Boolean parsing in the comments route fixed with explicit `typeof` check
+- React key uniqueness enforced in ChemicalEquation token rendering
+- Next.js upgraded to patched **16.2.6** to resolve high-severity advisories
 
 ---
 
-## [Unreleased] - TBD
+## [3.0.0] - 2026-04-06
 
-### Known Issues
-- RAST MS FBA not working
-- PATRIC-only model submission
-- Workspace write operations limited
+### Added
+- Compound structure images on reaction pages with click-through to compound detail pages
+- Comprehensive troubleshooting documentation and enhanced README with SSH tunnel setup instructions
 
-### Expected Behaviors
-- Models/Media differ between RAST and PATRIC (intentional system design)
+### Changed
+- Version display updated to show v{{VERSION}} from environment
+
+### Fixed
+- Invalid gapfill URL handling to gracefully return empty results instead of 404 errors
+- Improved Reaction/Compound detail drawer with better typography and monospace formatting
 
 ---
 
@@ -138,7 +171,7 @@ Below contains a summary of notable changes and deploy dates for each release fr
 
 ## [1.3.1-beta] - 2016-03-03
 
-- Add permalink compound and reaction pages. e.g., [cpd00001](http://modelseed.org/biochem/compounds/cpd00001) and [rxn00001](http://modelseed.org/biochem/reactions/rxn00001)
+- Add permalink compound and reaction pages
 - Add [Fusions](http://modelseed.org/projects/fusions) project
 - Stylistic fixes