From 494212088bf828cb522ea1397551dd5d5622090a Mon Sep 17 00:00:00 2001
From: Frank Loesche <loeschef@janelia.hhmi.org>
Date: Wed, 26 Nov 2025 16:55:11 -0500
Subject: [PATCH 1/7] move page structure from js to json

---
 docs/developer-guide.md                       | 1869 ++++-------------
 docs/user-guide.md                            | 1222 +++++------
 .../services/index_generator_service.py       |  176 +-
 templates/data/neurons.js.template.jinja      |   26 +
 templates/index.html.jinja                    |  154 +-
 .../static/js/neuron-search.js.template.jinja |  221 +-
 6 files changed, 1370 insertions(+), 2298 deletions(-)
 create mode 100644 templates/data/neurons.js.template.jinja

diff --git a/docs/developer-guide.md b/docs/developer-guide.md
index c05d65f6..d65b1f25 100644
--- a/docs/developer-guide.md
+++ b/docs/developer-guide.md
@@ -1,27 +1,22 @@
 # neuView Developer Guide
 
-A comprehensive guide for developers working on the neuView neuron visualization platform. This guide covers architecture, development setup, implementation details, and contribution guidelines.
+A comprehensive guide for developers working on the neuView neuron visualization platform.
 
 ## Table of Contents
 
 - [Project Overview](#project-overview)
 - [Architecture Overview](#architecture-overview)
 - [Getting Started](#getting-started)
+- [Neuron Data System](#neuron-data-system)
 - [Core Components](#core-components)
 - [Service Architecture](#service-architecture)
 - [Data Processing Pipeline](#data-processing-pipeline)
-- [Visualization System](#visualization-system)
 - [Template System](#template-system)
 - [Performance & Caching](#performance--caching)
-- [Development Patterns](#development-patterns)
 - [Testing Strategy](#testing-strategy)
-- [Dataset Aliases](#dataset-aliases)
 - [Configuration](#configuration)
-- [API Reference](#api-reference)
 - [Dataset-Specific Implementations](#dataset-specific-implementations)
-- [Feature Implementation Guides](#feature-implementation-guides)
 - [Troubleshooting](#troubleshooting)
-- [Contributing](#contributing)
 
 ## Project Overview
 
@@ -30,11 +25,11 @@ neuView is a modern Python CLI tool that generates beautiful HTML pages for neur
 ### Key Features
 
 - **🔌 NeuPrint Integration**: Direct data fetching with intelligent caching
-- **📱 Modern Web Interface**: Responsive design with advanced filtering
-- **⚡ High Performance**: Up to 97.9% speed improvement with persistent caching
+- **📱 Modern Web Interface**: Responsive design with advanced filtering and search
+- **⚡ High Performance**: Persistent caching with optimal data loading strategies
 - **🧠 Multi-Dataset Support**: Automatic adaptation for CNS, Hemibrain, Optic-lobe, FAFB
 - **🎨 Beautiful Reports**: Clean, accessible HTML pages with interactive features
-- **🔍 Advanced Search**: Real-time filtering by cell count, neurotransmitter, brain regions
+- **🔍 Advanced Search**: Real-time autocomplete search with synonym and FlyWire type support
 
 ### Technology Stack
 
@@ -47,25 +42,13 @@ neuView is a modern Python CLI tool that generates beautiful HTML pages for neur
 
 ### Architecture Overview
 
-neuView follows a layered architecture pattern with four distinct layers:
+neuView follows a layered architecture pattern:
 
 - **Presentation Layer**: CLI Commands, Templates, Static Assets, HTML Generation
 - **Application Layer**: Services, Orchestrators, Command Handlers, Factories
 - **Domain Layer**: Entities, Value Objects, Domain Services, Business Logic
 - **Infrastructure Layer**: Database, File System, External APIs, Caching, Adapters
 
-For detailed architecture implementation, see `src/neuview/` directory structure.
-
-### Key Architectural Principles
-
-- **Separation of Concerns**: Clear boundaries between layers
-- **Dependency Inversion**: High-level modules don't depend on low-level modules
-- **Single Responsibility**: Each component has one well-defined purpose
-- **Open/Closed Principle**: Open for extension, closed for modification
-- **Command/Query Separation**: Clear distinction between data modification and retrieval
-- **Result Pattern**: Explicit error handling with Result<T> types
-- **Service Container**: Dependency injection for loose coupling
-
 ## Getting Started
 
 ### Prerequisites
@@ -77,1642 +60,558 @@ For detailed architecture implementation, see `src/neuview/` directory structure
 
 ### Development Setup
 
-1. **Clone the repository:**
-Clone the repository and navigate to the project directory.
-
-2. **Install dependencies:**
-Install dependencies using `pixi install`.
-
-3. **Set up environment:**
-Set up the environment using `pixi run setup-env` and edit the .env file with your NeuPrint token.
-
-4. **Verify setup:**
-Test the connection using `pixi run neuview test-connection`.
+1. **Clone the repository**
+2. **Install dependencies**: `pixi install`
+3. **Set up environment**: `pixi run setup-env` and edit `.env` with your NeuPrint token
+4. **Verify setup**: `pixi run neuview test-connection`
 
 ### Development Commands
 
-neuView uses pixi for task management with separate commands for different types of work:
+**Testing:**
+- `pixi run unit-test` - Run all unit tests
+- `pixi run integration-test` - Run integration tests
+- `pixi run test` - Run all tests
 
-#### Testing Tasks
+**Code Quality:**
+- `pixi run lint` - Run ruff linter
+- `pixi run format` - Format code with ruff
 
-**Unit Tests** - Fast, isolated tests for individual components:
-**Unit Test Commands** (defined in `pixi.toml`):
-- `pixi run unit-test` - Run all unit tests
-- `pixi run unit-test-verbose` - Detailed output with specific file/test targeting support
+**Content Generation:**
+- `pixi run neuview build` - Generate website
+- `pixi run neuview inspect <type>` - Inspect neuron type data
 
-**Integration Tests** - End-to-end tests for component interactions:
-**Integration Test Commands** (defined in `pixi.toml`):
-- `pixi run integration-test` - Run all integration tests
-- `pixi run integration-test-verbose` - Detailed output with specific file targeting support
+## Neuron Data System
 
-**General Testing**:
-**Combined Test Commands** (defined in `pixi.toml`):
-- `pixi run test` - Run all tests (unit + integration)
-- `pixi run test-verbose` - Detailed output for all tests
-- `pixi run test-coverage` - Generate coverage reports
+The neuron search functionality uses a dual-source data loading system that provides universal compatibility and external API access.
 
-#### Code Quality Tasks
+### Architecture
 
-**Code Quality Commands** (defined in `pixi.toml`):
-- `pixi run format` - Format code with ruff
-- `pixi run check` - Run linting and quality checks
+```
+output/
+├── data/
+│   ├── neurons.json          # Primary: JSON for external services & HTTP(S)
+│   └── neurons.js            # Fallback: JavaScript wrapper for file:// access
+└── static/
+    └── js/
+        └── neuron-search.js  # Search logic (no embedded data)
+```
 
-#### Content Generation Tasks
+### Data Format (Version 2.0)
 
-**Content Generation Commands** (defined in `pixi.toml`):
-- `pixi run clean-output` - Clean generated output
-- `pixi run fill-all` - Fill processing queue with all neuron types
-- `pixi run pop-all` - Process all items in queue
-- `pixi run create-list` - Generate index page
-- `pixi run create-all-pages` - Complete workflow automation
+**Structure:**
+```json
+{
+  "names": ["AN07B013", "AOTU001", ...],
+  "neurons": [
+    {
+      "name": "AN07B013",
+      "urls": {
+        "combined": "AN07B013.html",
+        "left": "AN07B013_L.html",
+        "right": "AN07B013_R.html"
+      },
+      "types": {
+        "flywire": ["AN_GNG_60"],
+        "synonyms": ["Cachero 2010: aSP-j"]
+      }
+    }
+  ],
+  "metadata": {
+    "generated": "2025-01-26 15:04:31",
+    "total_types": 28,
+    "version": "2.0"
+  }
+}
+```
 
-Queue management implemented in `src/neuview/services/queue_service.py`.
+**Key Points:**
+- URLs stored WITHOUT `types/` prefix (added dynamically in JavaScript)
+- `types.flywire` and `types.synonyms` are arrays
+- `types` field only included when it has content
+- Same structure for both `neurons.json` and `neurons.js`
 
-#### Development Support Tasks
+### Data Loading Flow
 
-**Development Support Commands** (defined in `pixi.toml`):
-- `pixi run setup-env` - Setup development environment
-- `pixi run help` - CLI help system
-- `pixi run subset-medium` / `pixi run subset-medium-no-index` - Generate medium-sized test datasets
-- `pixi run subset-small` / `pixi run subset-small-no-index` - Generate small test datasets
-- `pixi run extract-and-fill` - Batch processing from config files
+**Web Server (HTTP/HTTPS):**
+1. neuron-search.js loads
+2. Attempts `fetch('data/neurons.json')`
+3. Success → Uses JSON data (optimal)
+4. neurons.js never downloaded
 
-Implementation in `scripts/extract_and_fill.py` and CLI modules.
+**Local Files (file://):**
+1. neuron-search.js loads
+2. Attempts `fetch('data/neurons.json')`
+3. Fails (CORS restriction)
+4. Dynamically loads `<script src="data/neurons.js">`
+5. Script tag bypasses CORS → Success
 
-#### Version Management Tasks
+### CORS Bypass Mechanism
 
-The project includes automated version management for releases:
+- `fetch()` requests are subject to CORS policy (blocked on file://)
+- `<script>` tags are NOT subject to CORS (works on file://)
+- Dynamic script injection used as fallback
 
-**Version Management** (defined in `pixi.toml`):
-- `pixi run increment-version` - Increment patch version and create git tag
+### Search Functionality
 
-Implementation in `scripts/increment_version.py` with `--dry-run` support for testing.
+The search system searches in three places:
+1. **Neuron names** (e.g., "AN07B013")
+2. **Synonyms** (e.g., "Cachero 2010: aSP-j")
+3. **FlyWire types** (e.g., "CB3127")
 
-**Version Increment Script**
+**Synonym Matching:**
+- Full text match: "cachero" matches "Cachero 2010: aSP-j"
+- Name after colon: "asp-j" matches "aSP-j" part
 
-The `increment_version.py` script automatically manages project versioning by:
+### External API Access
 
-1. **Reading current version**: Uses `git tag --list --sort=-version:refname` to find the latest semantic version tag
-2. **Incrementing patch version**: Increases patch by 1 (e.g., `v2.7.1` → `v2.7.2`)
-3. **Creating git tag**: Creates an annotated tag with descriptive message
+**Python Example:**
+```python
+import requests
 
-**Version Format**
+data = requests.get('https://site.com/data/neurons.json').json()
+neuron_names = data['names']
+neurons = data['neurons']
 
-- Expects/creates semantic versioning: `v{major}.{minor}.{patch}`
-- The `v` prefix is optional when reading, always added when creating
-- Handles missing patch numbers by defaulting to 0
+for neuron in neurons:
+    if 'types' in neuron:
+        flywire = neuron['types'].get('flywire', [])
+        synonyms = neuron['types'].get('synonyms', [])
+```
 
-**Safety Features**
+**JavaScript Example:**
+```javascript
+const response = await fetch('https://site.com/data/neurons.json');
+const data = await response.json();
 
-- Validates version format before processing
-- Warns about uncommitted changes but continues
-- Checks for duplicate tags to prevent conflicts
-- Does not auto-push tags (manual `git push origin <tag>` required)
-- Supports `--dry-run` mode for testing
+const names = data.names;
+const neurons = data.neurons;
+```
 
-**Example Output**
+**cURL Example:**
+```bash
+curl -s https://site.com/data/neurons.json | jq '.names'
+curl -s https://site.com/data/neurons.json | jq '.neurons[] | select(.types.flywire[]? == "CB3127")'
+```
 
-The version increment process analyzes the current version, calculates the new version, creates a git tag, and reports the successful increment.
+### Generation Process
 
-**Error Handling**
+Data files are generated automatically during build by `IndexGeneratorService.generate_neuron_search_js()`:
 
-The script will exit with error code 1 if:
-- No valid semantic version tags are found
-- Git commands fail
-- Tag already exists
-- Version format is invalid
+1. Prepares neuron data structure from NeuPrint data
+2. Strips `types/` prefix from URLs
+3. Converts `flywire_types` string to `types.flywire` array
+4. Converts `synonyms` string to `types.synonyms` array
+5. Generates `output/data/neurons.json`
+6. Generates `output/data/neurons.js`
+7. Generates `output/static/js/neuron-search.js`
 
-#### Task Usage Patterns
+**File:** `src/neuview/services/index_generator_service.py`
 
-**Development Workflow**:
-1. Setup environment: `pixi run setup-env` (first time)
-2. Development testing: `pixi run unit-test-verbose`
-3. Code quality: `pixi run format` and `pixi run check`
-4. Pre-commit testing: `pixi run test-verbose`
+### URL Handling
 
-**Content Generation Workflow**:
-- Complete automation: `pixi run create-all-pages`
-- Manual steps: clean → fill → process → index
+**In Data (JSON/JS):**
+- URLs stored without `types/` prefix
+- Example: `"combined": "AN07B013.html"`
 
-**Testing Workflow**:
-- Development: `pixi run unit-test` for fast feedback
-- Release preparation: `pixi run integration-test` and `pixi run test-coverage`
+**In JavaScript:**
+```javascript
+// Prefix added dynamically based on context
+this.urlPrefix = this.isNeuronPage ? '' : 'types/';
+targetUrl = this.urlPrefix + neuronEntry.urls.combined;
 
-#### Performance Notes
+// From index.html: 'types/AN07B013.html'
+// From neuron page: 'AN07B013.html'
+```
 
-- **Unit tests**: Complete in ~1 second
-- **Integration tests**: May take several seconds due to I/O
-- **Full test suite**: Typically < 10 seconds
-- **Page generation**: Varies based on dataset size
+### Testing
 
-#### Environment Requirements
+**Test page:** `docs/neuron-data-test.html`
+- Tests JSON loading
+- Tests JS fallback loading
+- Shows data statistics
+- Provides debugging tools
 
-Most development tasks require the `dev` environment, which is automatically used by the configured tasks. Some tasks require authentication:
-- Set in `.env` file or environment variables
+**Verify data source in browser console:**
+```javascript
+console.log(window.neuronSearch.dataSource);
+// Returns: 'json' or 'js-fallback'
+```
 
 ## Core Components
 
 ### PageGenerator
 
-The main orchestrator that coordinates page generation across all services.
+Main class responsible for generating HTML pages. Coordinates template rendering, data fetching, and file writing.
 
-**PageGenerator** (`src/neuview/page_generator.py`):
-- Core page generation orchestration
-- Automatic soma side detection and page creation
-- Service container integration
-- Key methods: `generate_page()`, `generate_index()`, `test_connection()`
+**Location:** `src/neuview/core/page_generator.py`
 
 ### PageGenerationOrchestrator
 
-Coordinates the complex page generation workflow through a multi-step process including request validation, data fetching, connectivity processing, visualization generation, template rendering, and output saving.
+Orchestrates the entire page generation process, managing parallelization and error handling.
 
-**PageGenerationOrchestrator** (`src/neuview/services/page_generation_orchestrator.py`):
-- Coordinates the complete page generation workflow
-- Handles request validation, data fetching, processing, and rendering
-- Manages service dependencies and error handling
+**Location:** `src/neuview/application/orchestrators/page_generation_orchestrator.py`
 
 ### NeuronType Class
 
-Core domain entity representing a neuron type with methods for cache key generation, neuron counting, and synapse statistics.
+Domain model representing a neuron type with all its properties and behaviors.
 
-**NeuronType** (`src/neuview/domain/neuron_type.py`):
-- Domain entity representing a neuron type
-- Properties: name, description, custom_query
-- Methods: `get_cache_key()`, `get_neuron_count()`, `get_synapse_stats()`
+**Location:** `src/neuview/domain/entities/neuron_type.py`
 
 ## Service Architecture
 
 ### Core Services
 
-The application is built around a comprehensive service architecture:
-
-#### Data Services
-- **NeuPrintConnector**: Database connection and query execution
-- **DatabaseQueryService**: Structured query building and execution
-- **CacheService**: Multi-level caching with persistence
-- **DataProcessingService**: Data transformation and validation
-- **ROIDataService**: Dynamic ROI data fetching from Google Cloud Storage with caching
-
-#### Analysis Services
-- **PartnerAnalysisService**: Connectivity analysis and partner identification
-- **ROIAnalysisService**: Region of interest analysis and statistics
-- **ConnectivityCombinationService**: Automatic L/R hemisphere combination for connectivity
-- **ROICombinationService**: Automatic L/R hemisphere combination for ROI data
-
-#### Content Services
-- **TemplateContextService**: Template data preparation and processing
-- **ResourceManagerService**: Static asset management
-- **NeuroglancerJSService**: Neuroglancer integration and URL generation
-- **URLGenerationService**: Dynamic URL creation
-- **CitationService**: Citation data management and HTML link generation
-- **CitationLoggingService**: Automatic tracking and logging of missing citations
-
-#### Infrastructure Services
-- **FileService**: File operations and path management
-- **ConfigurationService**: Configuration loading and validation
-- **LoggingService**: Structured logging and monitoring
+**Data Services:**
+- `DatabaseQueryService` - NeuPrint queries
+- `ConnectivityQueryService` - Connectivity data
+- `ROIDataService` - Brain region data
 
-### Service Container Pattern
+**Analysis Services:**
+- `StatisticsService` - Statistical calculations
+- `CVCalculatorService` - Coefficient of variation
 
-Dependency injection using a service container with service registration and singleton management.
+**Content Services:**
+- `CitationService` - Citation generation
+- `ImageService` - Image handling
+- `IndexGeneratorService` - Index page and data file generation
 
-See the `ServiceContainer` class in `src/neuview/services/page_generation_container.py` for the complete implementation including the `__init__`, `register`, and `get` methods.
+**Infrastructure Services:**
+- `CacheService` - Data caching
+- `ConfigurationService` - Configuration management
 
-### Service Development Pattern
+### Service Container Pattern
 
-Standard pattern for implementing new services with configuration injection, caching integration, error handling, input validation, and core processing logic.
+Services are registered in a dependency injection container for loose coupling.
 
-Refer to any service class in `src/neuview/services/` for examples of this pattern, such as `DatabaseQueryService` in `src/neuview/services/database_query_service.py` or `CacheService` in `src/neuview/services/cache_service.py`.
+**Location:** `src/neuview/infrastructure/container.py`
 
 ## Data Processing Pipeline
 
 ### Dataset Adapters
 
-Different datasets require different data processing approaches:
+Different datasets (CNS, Hemibrain, FAFB) require different handling. Adapters normalize the differences.
 
-**Dataset Adapters** (`src/neuview/services/dataset_adapters/`):
-- Base adapter pattern for dataset-specific processing
-- `DatasetAdapter` - Abstract base class with common interface
-- `CNSAdapter`, `HemibrainAdapter`, `FAFBAdapter` - Dataset-specific implementations
-- Key methods: `extract_soma_side()`, `normalize_columns()`, `categorize_rois()`
-- Factory pattern in `DatasetAdapterFactory` for automatic adapter selection
+**Base Adapter:** `src/neuview/infrastructure/adapters/base_adapter.py`
 
-### Data Flow
+**Implementations:**
+- `CNSAdapter` - For CNS datasets
+- `FafbAdapter` - For FAFB/FlyWire datasets
 
-Raw NeuPrint Data → Dataset Adapter → Cache Layer → Service Processing → Template Rendering
+### Data Flow
 
-1. **Data Extraction**: NeuPrint queries return raw database results
-2. **Adaptation**: Dataset-specific adapters normalize the data
-3. **Caching**: Processed data is cached for performance
-4. **Analysis**: Services perform connectivity and ROI analysis with CV calculation
-5. **Rendering**: Template system generates final HTML
+1. **Query** - Fetch data from NeuPrint
+2. **Adapt** - Normalize dataset-specific differences
+3. **Process** - Calculate statistics, generate visualizations
+4. **Cache** - Store processed data
+5. **Render** - Generate HTML with templates
+6. **Write** - Output to file system
 
 ### Connectivity Data Processing with CV
 
-The connectivity processing pipeline includes statistical analysis including coefficient of variation (CV) calculation. See the connectivity query methods and CV calculation logic in `src/neuview/services/data_processing_service.py` and `src/neuview/services/connectivity_combination_service.py`.
-
-The partner data structure includes the calculated CV value for template rendering.
-
-### Automatic Page Generation System
-
-neuView features automatic page generation that eliminates the need for manual soma-side specification. The system intelligently analyzes neuron data and generates the optimal set of pages.
-
-#### Architecture Overview
-
-The automatic page generation system analyzes soma side distribution, determines which pages to generate based on data availability, and creates appropriate side-specific and combined pages. See the `SomaDetectionService` and its `generate_pages_with_auto_detection` method in the relevant service files.
-
-#### Detection Logic
-
-The system uses sophisticated logic to determine which pages to generate based on soma side distribution, counting sides with data, and handling unknown soma side counts. See the `_should_generate_combined_page` function implementation for the complete logic.
-
-#### Page Generation Scenarios
-
-**Scenario 1: Multi-hemisphere neuron type (e.g., Dm4)**
-- Data: 45 left neurons, 42 right neurons
-- Generated pages: `Dm4_L.html`, `Dm4_R.html`, `Dm4.html` (combined)
-- Rationale: Multiple hemispheres warrant both individual and combined views
-
-**Scenario 2: Single-hemisphere neuron type (e.g., LC10)**
-- Data: 0 left neurons, 23 right neurons
-- Generated pages: `LC10_R.html` only
-- Rationale: No combined page needed for single-hemisphere types
-
-**Scenario 3: Mixed data with unknowns**
-- Data: 15 left neurons, 8 unknown-side neurons
-- Generated pages: `NeuronType_L.html`, `NeuronType.html` (combined)
-- Rationale: Unknown neurons justify a combined view alongside specific side
-
-**Scenario 4: No soma side information**
-- Data: 30 neurons, all unknown sides
-- Generated pages: `NeuronType.html` (combined only)
-- Rationale: Without hemisphere data, only combined view is meaningful
-
-#### System Integration
-
-The automatic page generation system maintains backward compatibility while removing user-facing complexity. The `GeneratePageCommand` class has been simplified by removing the `soma_side` parameter, allowing the system to auto-detect appropriate pages to generate. See `src/neuview/models/page_generation.py` for the updated command structure.
-
-#### Performance Considerations
-
-- **Data Analysis**: Single query analyzes all soma sides simultaneously
-- **Parallel Generation**: Individual pages generated concurrently when possible
-- **Cache Efficiency**: Shared data fetching across multiple page generations
-- **Memory Management**: Automatic cleanup after page generation completes
-
-### ROI Query Strategies
-
-Different strategies for querying region of interest data:
-
-**ROI Query Strategies** (`src/neuview/services/roi_analysis_service.py`):
-- Strategy pattern for region-specific ROI queries
-- Methods: `query_central_brain_rois()`, `categorize_rois()`
-- Handles different brain region categorizations
-
-## Visualization System
+Connectivity tables include coefficient of variation (CV) to show variability in synapse counts.
 
-### Hexagon Grid Generator
+**Formula:** `CV = (standard deviation / mean) × 100`
 
-**HexagonGridGenerator** (`src/neuview/services/visualization/hexagon_grid_generator.py`):
-- Generates spatial visualizations for neuron distribution
-- Configurable hex size and spacing parameters
-- Key methods: `generate_region_hexagonal_grids()`, `generate_single_region_grid()`
-- Outputs SVG format for web display
-
-### Coordinate System
-
-**Coordinate Functions** (`src/neuview/services/visualization/coordinate_utils.py`):
-- Mathematical functions for hexagonal grid coordinate conversion
-- Key functions: `hex_to_axial()`, `axial_to_pixel()`
-- Handles hexagonal to Cartesian coordinate transformations
-
-### Color Mapping
-
-**Color Mapping Functions** (`src/neuview/services/visualization/color_utils.py`):
-- Dynamic color assignment based on data values
-- Key function: `get_color_for_value()`
-- Supports multiple color schemes (viridis, plasma)
-- Handles edge cases like constant values
+**Implementation:** `src/neuview/services/cv_calculator_service.py`
 
 ## Template System
 
 ### Template Architecture
 
-**Template Strategy Pattern** (`src/neuview/services/template_service.py`):
-- Jinja2-based template system with custom extensions
-- `TemplateStrategy` - Abstract base class for template handling
-- `JinjaTemplateStrategy` - Jinja2 implementation with custom filters
-- Key methods: `load_template()`, `render_template()`, `_setup_filters()`
-- Custom filters registered for number formatting and URL safety
+Templates are organized hierarchically with inheritance and includes.
 
-### Template Structure
+**Base Templates:**
+- `base.html.jinja` - Main page structure
+- `macros.html.jinja` - Reusable components
 
-**Template Organization** (`templates/` directory):
-- `base.html.jinja` - Base layout template
-- `neuron-page.html.jinja` - Individual neuron type pages
-- `index.html.jinja` - Main index with search functionality
-- `types.html.jinja` - Neuron type listing pages
-- `static/js/` - JavaScript template files (neuroglancer integration, page interactions)
-- `static/css/` - CSS template files with dynamic styling
+**Page Templates:**
+- `neuron_page.html.jinja` - Individual neuron pages
+- `index.html.jinja` - Landing page
+- `types.html.jinja` - Neuron type listing
+- `help.html.jinja` - Help page
 
-### Template Context
+**Partial Templates:**
+- `sections/header.html.jinja` - Page header with search
+- `sections/footer.html.jinja` - Page footer
+- `sections/connectivity_table.html.jinja` - Connectivity tables
 
-**Template Context Management** (`src/neuview/services/template_context_service.py`):
-- Structured data preparation for template rendering
-- `TemplateContext` class organizing neuron, connectivity, ROI, and visualization data
-- Key method: `to_dict()` for template consumption
-- Handles data serialization and context validation
+### Template Context
 
-### Connectivity Table Template Processing
+Templates receive context dictionaries with data:
 
-**Connectivity Tables** (`templates/sections/connectivity_table.html.jinja`):
-- Handles CV display with proper fallbacks for coefficient of variation data
-- Safe fallback patterns using Jinja2 `get()` method with default values
-- Descriptive tooltips for CV column explaining statistical meaning
-- Consistent implementation across upstream and downstream tables
-- Custom filters for number and percentage formatting
+```python
+context = {
+    'neuron': neuron_type,
+    'config': configuration,
+    'statistics': stats,
+    'connectivity': conn_data,
+    'citations': citations
+}
+```
 
 ### Custom Template Filters
 
-**Template Filters** (`src/neuview/services/template_service.py`):
-- `format_number_filter()` - Formats numbers with precision and thousand separators (K, M suffixes)
-- `format_percentage()` - Handles percentage formatting with appropriate precision
-- `safe_url()` - URL encoding and sanitization for dynamic links
-- Registered automatically during Jinja2 environment setup
+**Location:** `src/neuview/templates/filters/`
+
+Custom Jinja2 filters for formatting data in templates.
 
 ## Performance & Caching
 
 ### Multi-Level Cache System
 
-neuView implements a sophisticated caching system with multiple levels:
-
-**CacheService** (`src/neuview/services/cache_service.py`):
-- Multi-level caching system with memory, file, and database backends
-- Key method: `get_cached_data()` with fallback chain across cache levels
-- Automatic cache population and eviction policies
-- Backend implementations in respective cache backend modules
+1. **Memory Cache** - In-process cache for current session
+2. **Persistent Cache** - SQLite database for cross-session caching
+3. **File Cache** - Generated HTML and static assets
 
 ### Cache Types
 
-- **Memory Cache**: In-memory LRU cache for immediate access
-- **File Cache**: Persistent file-based cache surviving process restarts
-- **Database Cache**: SQLite-based cache for complex queries
-- **HTTP Cache**: Response caching for NeuPrint API calls
+- **Query Cache** - NeuPrint query results
+- **Synapse Cache** - Connectivity statistics
+- **ROI Cache** - Brain region data
+- **Image Cache** - Neuroglancer screenshots
 
 ### Performance Optimizations
 
-Key optimizations implemented:
-
-- **Database Connection Pooling**: Reuse connections across requests
-- **Batch Query Processing**: Combine multiple queries into single requests
-- **Lazy Loading**: Load data only when needed
-- **Asynchronous Processing**: Non-blocking I/O for improved throughput
-- **Compressed Storage**: Gzip compression for cached data
-
-### Performance Monitoring
-
-**PerformanceMonitor** (`src/neuview/services/performance_monitor.py`):
-- Operation timing and metrics collection
-- Key methods: `start_timer()`, `end_timer()` for performance measurement
-- Metrics aggregation and reporting functionality
-- Integration with logging system for performance analysis
-
-### Cache Management Patterns
-
-The neuView system follows consistent patterns for cache organization and management across all services.
-
-#### Cache Directory Structure
-
-All caches are organized under the output directory to maintain consistency. Standard structure includes roi_data, neuprint, templates, and performance subdirectories. See `src/neuview/services/` for cache organization patterns.
-
-#### Cache Location Pattern
-
-**Cache Location Pattern**: Services derive cache locations from container-provided output directory. Implementation pattern demonstrated in `ROIDataService.__init__()` and other service constructors.
-
-**Benefits**:
-- ✅ Consistent cache organization across all services
-- ✅ Configurable output directory support
-- ✅ No hardcoded cache paths
-- ✅ Clean separation by service type
-
-#### Cache Key Strategy
-
-**Cache Key Strategy**: Use descriptive, collision-resistant cache keys incorporating dataset, type, and version information. Examples: "fullbrain_roi_v4.json", "vnc_neuropil_roi_v0.json". Implementation in `ROIDataService._get_cache_filename()`.
-
-#### Cache Lifecycle Management
-
-**Cache Lifecycle Management**: Implement cache validation and refresh mechanisms with time-based expiration. See `ROIDataService._is_cache_valid()` and `_fetch_and_parse_roi_data()` for reference implementation patterns.
-
-#### Error-Resilient Caching
+- Parallel page generation with asyncio
+- Lazy loading of heavy data
+- Incremental regeneration (only changed pages)
+- Efficient template rendering
 
-**Error-Resilient Caching**: Implement graceful fallback to stale cache on network failures. Reference implementation in `ROIDataService._fetch_and_parse_roi_data()` demonstrates try-catch patterns with fallback logic.
+### Cache Management
 
-#### Container Integration Pattern
-
-**Container Integration Pattern**: Register cache-aware services with output directory injection. See `roi_data_service_factory()` in `PageGenerationContainer` for reference implementation.
-
-#### Migration Considerations
-
-When updating cache locations:
-
-1. **Automatic Migration**: Cache files regenerate automatically from sources
-2. **No Data Loss**: Old cache files can be safely removed
-3. **Backward Compatibility**: Fallback paths maintain functionality
-4. **Clean Transition**: Remove old cache files after verification
-
-**Migration Pattern**: Services support automatic migration from previous cache locations. The ROI Data Service demonstrates output directory adoption with automatic cleanup.
-
-## Development Patterns
-
-### Error Handling
-
-**Error Handling Pattern** (`src/neuview/services/` - various service implementations):
-- Consistent use of Result pattern for error handling
-- Comprehensive exception catching with specific error types
-- Reference implementation in `PageGenerationOrchestrator.generate_page()`
-- Key pattern: validate input → fetch data → process → return Result
-- Logging integration for debugging and monitoring
-
-### Configuration Management
-
-**Configuration Management** (`src/neuview/config/config.py`):
-- Hierarchical configuration system with dataclass structure
-- Key config classes: `Config`, `NeuPrintConfig`, `CacheConfig`, `OutputConfig`, `HtmlConfig`
-- Class methods: `from_file()` for YAML loading, `from_env()` for environment variables
-- Configuration validation with `__post_init__()` methods
-
-### Service Registration
-
-**Service Registration** (`src/neuview/services/page_generation_container.py`):
-- Dependency injection setup through `PageGenerationContainer`
-- Factory functions for service creation with proper dependency resolution
-- Key services registered: cache_service, database_service, connectivity_service, template_service
-- Service lifecycle management and singleton patterns
-- Reference implementation in container `__init__()` method
-
-### Type Safety
+**Clear cache:**
+```bash
+pixi run neuview build --clear-cache
+```
 
-Using type hints and validation:
-**Type Safety** (`src/neuview/domain/` and service modules):
-- Comprehensive use of dataclasses and type hints throughout codebase
-- Domain models with strict typing in `src/neuview/domain/`
-- Example classes: `AnalysisRequest`, `NeuronType`, `ConnectivityData`
-- Function signatures with explicit return types using `Result` pattern
+**Cache location:**
+- Default: `.neuview_cache/`
+- Configurable via environment variable
 
 ## Testing Strategy
 
-### Overview
-
-neuView uses a comprehensive testing strategy with clear separation between unit and integration tests. Tests are organized by type and use pytest markers for selective execution.
-
 ### Test Categories
 
-#### Unit Tests (`@pytest.mark.unit`)
-Fast, isolated tests that focus on individual components without external dependencies.
-
-**Characteristics:**
-- Fast execution (< 1 second total)
-- No file I/O operations
-- No external service dependencies
-- Test single methods/functions
-- Mock external dependencies when needed
-
-**Example:**
-```python
-@pytest.mark.unit
-class TestDatasetAdapterFactory:
-    """Unit tests for DatasetAdapterFactory."""
-
-    @pytest.mark.unit
-**Example Unit Test** (`test/test_dataset_adapters.py`):
-- `TestDatasetAdapterFactory.test_male_cns_alias_resolution()` - Tests adapter factory with dataset aliases
-- Verifies that "male-cns" resolves to correct CNSAdapter instance
-```
-
-#### Integration Tests (`@pytest.mark.integration`)
-End-to-end tests that verify component interactions and real-world scenarios.
+**Unit Tests** (`@pytest.mark.unit`):
+- Fast, isolated tests
+- No external dependencies
+- Mock all services
 
-**Characteristics:**
-- Slower execution (may involve file I/O)
+**Integration Tests** (`@pytest.mark.integration`):
 - Test component interactions
-- Uses real configuration files
-- Tests end-to-end workflows
-- May use temporary files/resources
-
-**Example Integration Test** (`test/test_male_cns_integration.py`):
-- `TestMaleCNSIntegration.test_config_with_male_cns_creates_cns_adapter()` - End-to-end configuration testing
-- Creates temporary config files and tests full component integration
-- Validates that configuration properly creates expected adapter instances
+- May use real NeuPrint connection
+- Slower but more comprehensive
 
 ### Test Execution
 
-#### Test Execution Commands
-
-**Test execution tasks are defined in `pixi.toml`:**
-- Unit tests: `pixi run unit-test` (fast feedback)
-- Integration tests: `pixi run integration-test` (comprehensive testing)
-- All tests: `pixi run test` (complete test suite)
-- Coverage reports: `pixi run test-coverage`
-- Verbose output: Add `-verbose` suffix to any test command
-
-**Selective execution supports targeting specific files, classes, or methods using pytest syntax.**
-
-### Test Structure
-
-**Test Organization** (`test/` directory):
-- `test_dataset_adapters.py` - Unit tests for factory and adapters
-- `test_male_cns_integration.py` - Integration tests for end-to-end scenarios
-- `services/` - Service-specific test modules
-- `visualization/` - Visualization component tests
-- `fixtures/` - Test data and fixture files
-
-### Naming Conventions
-
-- **Unit tests**: Focus on single method/function behavior
-  - Format: `test_[specific_behavior]`
-  - Example: `test_male_cns_base_name_alias_resolution`
-
-- **Integration tests**: Focus on component interactions
-  - Format: `test_[workflow_or_integration_scenario]`
-  - Example: `test_end_to_end_male_cns_workflow`
-
-### Performance Guidelines
-
-- **Unit tests**: Should complete in under 1 second total
-- **Integration tests**: May take several seconds due to file I/O and component setup
-- **Full test suite**: Typically < 10 seconds
-
-### CI/CD Integration
-
-**CI/CD Integration** (`.github/workflows/` directory):
-- Separate GitHub Actions jobs for unit and integration tests
-- Unit tests provide fast feedback with `pixi run unit-test-verbose`
-- Integration tests use secure token injection for NeuPrint access
-- Parallel execution for efficient CI pipeline
-
-### Test Data and Fixtures
-
-#### Unit Test Data
-- Hardcoded test values for predictable behavior
-- Use of mock objects for external dependencies
-- Parameterized tests for multiple similar scenarios
-
-#### Integration Test Data
-- Temporary configuration files created during test execution
-- Real project configuration files when available
-- Cleanup of temporary resources after tests
-
-### Dataset Alias Testing
-
-**Dataset Alias Testing**: Special focus on testing dataset alias functionality with comprehensive test cases for versioned aliases. See `test_male_cns_versioned_alias_resolution()` and `test_end_to_end_male_cns_workflow()` in test files for reference implementations.
-
-### Debugging Failed Tests
-
-#### Unit Test Failures
-Run specific failing tests with verbose output using pytest selection syntax. Check test markers to understand test categorization.
-
-#### Integration Test Failures
-Verify environment setup, token configuration, and run tests with verbose debugging and traceback options to diagnose integration test issues.
-
-### Adding New Tests
-
-When adding new features:
-
-1. **Add unit tests** for individual components
-2. **Add integration tests** if the feature involves multiple components
-3. **Use appropriate markers** (`@pytest.mark.unit` or `@pytest.mark.integration`)
-4. **Follow naming conventions**
-5. **Ensure proper cleanup** of resources in integration tests
-
-### Test Data Factory
-
-**TestDataFactory** (`test/fixtures/test_data_factory.py`):
-- Centralized test data creation for consistent testing
-- Key methods: `create_neuron_data()`, `create_connectivity_data()`
-- Provides standardized test data structures for neuron and connectivity testing
-- Parameterizable factory methods for different test scenarios
-
-### Script Management
-
-The neuView project follows specific patterns for managing utility scripts in the `scripts/` directory.
-
-#### Script Categories
-
-**Permanent Scripts** (Keep):
-- Regular maintenance utilities
-- Reusable development tools
-- System health checks
-- Data migration tools for ongoing use
-- Performance monitoring scripts
-
-**Temporary Scripts** (Remove after use):
-- One-time migration scripts
-- Debugging scripts for specific issues
-- Verification scripts for completed work
-- Testing scripts for specific features
-
-#### Script Lifecycle Management
-
-**Script Classification Examples**:
-- **Permanent**: `scripts/increment_version.py` - Reusable version management functionality
-- **Temporary**: Issue-specific debugging scripts - Should be removed after resolution
-
-See current utility scripts in `scripts/` directory for reference implementations.
-
-#### Cleanup Best Practices
-
-1. **Mark Temporary Scripts**: Use clear naming and documentation
-2. **Clean After Completion**: Remove debugging scripts once issues are resolved
-3. **Document Purpose**: Include clear descriptions of script intent
-4. **Regular Cleanup**: Periodically review and remove obsolete scripts
-
-#### Script Documentation Pattern
+```bash
+# Run all tests
+pixi run test
 
-**Documentation Requirements**: All permanent scripts should include comprehensive docstrings with purpose, usage, and requirements. See `scripts/increment_version.py` and `scripts/extract_and_fill.py` for reference documentation patterns.
+# Run only unit tests
+pixi run unit-test
 
+# Run only integration tests
+pixi run integration-test
 
+# Run specific test file
+pixi run pytest test/unit/test_neuron_type.py
 
-#### Current Utility Scripts
+# Run with coverage
+pixi run pytest --cov=src
+```
 
-**Version Management**:
-**Current Utility Scripts** (see `scripts/` directory):
-- `increment_version.py`: Automatically increments project version and creates git tags (supports `--dry-run`)
-- `extract_and_fill.py`: Extracts neuron types from config files and runs fill-queue commands
+### Test Structure
 
-**Usage**: See script docstrings and `scripts/README.md` for detailed usage instructions and examples.
+```
+test/
+├── unit/              # Unit tests
+│   ├── domain/
+│   ├── services/
+│   └── utils/
+├── integration/       # Integration tests
+│   ├── test_full_pipeline.py
+│   └── test_neuprint_integration.py
+└── fixtures/          # Test data and fixtures
+```
 
 ## Configuration
 
 ### Configuration Files
 
-**Configuration Structure** (`config.yaml` and `src/neuview/config/config.py`):
-- YAML-based configuration system with hierarchical structure
-- Key sections: neuprint, cache, templates, performance, visualization
-- Reference configuration examples in project root `config.yaml`
-- Configuration dataclasses define structure and validation rules
-
-### Environment Variables
-
-Environment variable support for sensitive configuration:
+**Main Config:** `config.yaml`
+```yaml
+neuprint:
+  server: neuprint.janelia.org
+  dataset: optic-lobe:v1.0
+  
+html:
+  title_prefix: "Optic Lobe"
+  github_repo: "https://github.com/..."
+  
+performance:
+  max_workers: 4
+  cache_enabled: true
+```
 
-- `NEUPRINT_APPLICATION_CREDENTIALS`: NeuPrint API token
-- `NEUVIEW_CONFIG_PATH`: Custom configuration file path
-- `NEUVIEW_CACHE_DIR`: Cache directory override
-- `NEUVIEW_DEBUG`: Enable debug logging
-- `NEUVIEW_PROFILE`: Enable performance profiling
+**Environment Variables:**
+- `NEUPRINT_APPLICATION_CREDENTIALS` - NeuPrint token (required)
+- `NEUVIEW_CACHE_DIR` - Cache directory location
+- `NEUVIEW_LOG_LEVEL` - Logging verbosity
 
 ### Configuration Validation
 
-**Configuration Validation** (`src/neuview/config/config.py`):
-- Automatic validation with clear error messages using dataclass `__post_init__()` methods
-- Example: `NeuPrintConfig.__post_init__()` validates required server and dataset fields
-- Validation occurs at configuration loading time with descriptive error messages
-
-## API Reference
-
-### Core Classes
-
-#### PageGenerator
-
-**PageGenerator** (`src/neuview/page_generator.py`):
-- Main interface for page generation with configuration and service container integration
-- Key methods: `generate_page()`, `generate_index()`, `test_connection()`
-- Handles automatic soma-side detection and page creation orchestration
-
-#### NeuronType
-
-**NeuronType** (`src/neuview/domain/neuron_type.py`):
-- Core domain entity with properties: name, description, custom_query
-- Represents neuron type metadata and configuration
-
-#### Result Pattern
-
-**Result Pattern** (`src/neuview/domain/result.py`):
-- Explicit error handling pattern used throughout the codebase
-- Static methods: `success()`, `failure()` for result creation
-- Properties: `is_success()`, `value`, `error` for result handling
-- Ensures predictable error handling across all services
-
-### Service Interfaces
-
-#### DatabaseQueryService
-
-**DatabaseQueryService** (`src/neuview/services/database_query_service.py`):
-- Database query execution with parameter binding
-- Key method: `execute_query()` returns Result pattern for error handling
-- Handles NeuPrint API interactions and query optimization
-
-#### CacheService
-
-**CacheService** (`src/neuview/services/cache_service.py`):
-- Multi-level caching with memory, file, and database backends
-- Key methods: `get()`, `set()` with optional TTL support
-- Automatic cache eviction and persistence management
-
-#### CitationService
-
-**CitationService** (`src/neuview/services/citation_service.py`):
-- Citation management and HTML link generation from CSV data
-- Key methods: `load_citations()`, `get_citation()`, `create_citation_link()`
-- Automatic missing citation logging and validation
-- Supports custom link text and output directory configuration
-
-## Dataset Aliases
-
-### Overview
-
-neuView supports dataset aliases to handle different naming conventions for the same underlying dataset type. This is particularly useful when working with datasets that may have different names but use the same database structure and query patterns.
-
-### Current Aliases
-
-#### CNS Dataset Aliases
-The following aliases are configured to use the CNS adapter:
-
-- `male-cns` → `cns`
-- `male-cns:v0.9` → `cns` (versioned)
-
-### Implementation
-
-**DatasetAdapterFactory** (`src/neuview/services/dataset_adapters/dataset_adapter_factory.py`):
-- Handles dataset alias resolution and adapter creation
-- Maintains adapter registry and alias mappings
-- Key method: `create_adapter()` with versioned dataset name support
-- Aliases: `male-cns` → `cns` with version handling
-        base_name = dataset_name.split(":")[0] if ":" in dataset_name else dataset_name
-
-- Alias resolution and adapter creation logic
-- Automatic fallback to CNSAdapter for unknown datasets
-- Version string handling for dataset names
-
-### Configuration Example
-
-**Configuration Usage** (see `config.yaml` for examples):
-- Dataset names support aliases: `male-cns:v0.9` resolves to CNS adapter
-- Server configuration points to appropriate NeuPrint instance
-- Automatic adapter selection based on dataset name patterns
-
-This configuration will:
-- Resolve `male-cns:v0.9` → `male-cns` (base name) → `cns` (alias resolution)
-- Create a `CNSAdapter` instance
-- Set `dataset_info.name` to `"cns"`
-- **Not produce any warnings**
-
-### Adding New Aliases
-
-**Adding New Aliases**: Modify the `_aliases` dictionary in `DatasetAdapterFactory` class (`src/neuview/services/dataset_adapters/dataset_adapter_factory.py`). Example aliases: `male-cns` → `cns`, `female-cns` → `cns`.
-
-### Versioned Datasets
-
-Dataset aliases work with versioned dataset names:
-- `male-cns:v0.9` → `cns`
-- `male-cns` → `cns`
-- `female-cns` → `cns`
-
-### Error Handling
-
-If a dataset name (including aliases) is not recognized:
-1. Prints a warning message
-2. Falls back to using the `CNSAdapter` as the default
-3. Continues execution
-
-Example warning: "Warning: Unknown dataset 'unknown-dataset:latest', using CNS adapter as default"
+Configuration is validated at startup with clear error messages for issues.
 
 ## Dataset-Specific Implementations
 
 ### FAFB Dataset Handling
 
-FAFB (FlyWire Adult Fly Brain) requires special handling due to data structure differences:
-
-#### Soma Side Property Differences
-
-FAFB stores soma side information differently than other datasets:
-
-**Standard Datasets (CNS, Hemibrain)**:
-- Property: `somaSide`
-- Values: "L", "R", "M"
-
-**FAFB Dataset**:
-- Property: `side` OR `somaSide`
-- Values: "LEFT", "RIGHT", "CENTER" or "left", "right", "center"
-
-#### FAFB Adapter Implementation
-
-**FAFBAdapter** (`src/neuview/services/dataset_adapters/fafb_adapter.py`):
-- Custom soma side extraction handling FAFB-specific property differences
-- `extract_soma_side()` method with fallback logic for `somaSide` vs `side` properties
-- Property value mapping: LEFT/RIGHT → L/R, CENTER/MIDDLE → C
-- Handles case variations and FAFB-specific nomenclature
-
-#### FAFB Query Modifications
-
-**FAFB Query Patterns** (`src/neuview/services/database_query_service.py`):
-- Database queries use CASE statements for property fallback handling
-- Cypher queries account for `somaSide` vs `side` property differences
-- Automatic value mapping within query logic for consistent results
-- Reference implementation in FAFB-specific query methods
-
-#### FAFB ROI Checkbox Behavior
-
-FAFB datasets don't support ROI visualization in Neuroglancer, requiring conditional UI:
-
-**Implementation**: Dataset-aware JavaScript that disables ROI checkboxes for FAFB:
-
-**FAFB ROI Checkbox Behavior** (`templates/static/js/neuroglancer-url-generator.js.jinja`):
-- Dataset detection: `IS_FAFB_DATASET` variable for conditional behavior
-- `syncRoiCheckboxes()` function skips checkbox creation for FAFB datasets
-- Automatic width adjustment for FAFB ROI cells to maintain layout consistency
-- Prevents user confusion by hiding non-functional checkboxes
-
-#### Connectivity Checkbox Self-Reference Detection
-
-Automatic checkbox disabling when partner type matches current neuron type and bodyId is already visible in neuroglancer:
-
-**Problem**: Users could add the same neuron instance multiple times to the neuroglancer viewer by selecting connectivity partners that reference the current neuron itself.
-
-**Solution**: Detect self-reference conditions and disable checkboxes automatically.
-
-**Implementation**:
-
-1. **HTML Template Changes** (`templates/sections/connectivity.html.jinja`):
-**Connectivity Template Data** (`templates/sections/connectivity_table.html.jinja`):
-- Template data attributes: `data-body-ids` for JavaScript access
-- Jinja2 filters: `get_partner_body_ids()` for body ID extraction
-- Partner type information embedded for self-reference detection
-
-2. **JavaScript Data** (`templates/sections/neuron_page_scripts.html.jinja`):
-**JavaScript Data Integration** (`templates/sections/neuron_page_scripts.html.jinja`):
-- `neuroglancerData.currentNeuronType` populated from template context
-- Enables self-reference detection in connectivity checkbox logic
-
-3. **Checkbox Logic** (`templates/static/js/neuroglancer-url-generator.js.jinja`):
-**Self-Reference Detection Logic** (JavaScript in connectivity templates):
-- Compares partner type with current neuron type
-- Checks if body IDs are in visible neurons list
-- Automatic checkbox disabling with `self-reference` CSS class application
-- Prevents circular selections in Neuroglancer interface
-
-4. **CSS Styling** (`static/css/neuron-page.css`):
-**Self-Reference Styling** (`static/css/neuron-page.css`):
-- `.p-c.self-reference input[type="checkbox"]` styling for disabled self-reference checkboxes
-- Visual indicators: gray background, disabled cursor, reduced opacity
-
-**Logic Flow**:
-**Decision Logic Flow**:
-1. Empty bodyIds → Disable (existing behavior)
-2. Partner type matches current type → Check visibility
-3. Body IDs in visible neurons → Disable as self-reference
-4. Otherwise → Enable normally
-
-**Example**: For neuron type AN02A005 with visible neurons [123456, 789012]:
-- LC10 partner with [111111, 222222] → Enabled ✅
-- AN02A005 partner with [123456] → Disabled ❌ (self-reference)
-- T4 partner with [333333, 444444] → Enabled ✅
-
-**Testing**:
-- Manual: Use `test_checkbox/test_checkbox_disable.html` for demonstration
-- Integration: Generate pages for self-connecting neuron types (e.g., AN02A005)
-- Console: Check for debug messages like `[CHECKBOX] Disabling checkbox for self-reference`
-
-**Performance**: O(n×m) complexity where n = partners, m = visible neurons. Minimal impact due to small datasets.
-
-**Browser Support**: Standard JavaScript (IE11+) using `dataset` API, `Array.includes()`, and CSS `:disabled`.
+FAFB (FlyWire) has different property names and behaviors:
 
-**Troubleshooting**:
-1. **Checkbox not disabling**: Verify `currentNeuronType` in pageData
-2. **Styling issues**: Confirm `.self-reference` CSS class is applied and styles are loaded
-3. **Console errors**: Check neuroglancer data initialization and function load order
+**Soma Side Property:**
+- Other datasets: `somaLocation` or `somaSide`
+- FAFB: `side` (values: "L", "R", "M")
 
-#### FAFB Neuroglancer Template Selection
+**Adapter:** `src/neuview/infrastructure/adapters/fafb_adapter.py`
 
-Automatic template selection based on dataset:
+### CNS, Hemibrain, and Optic-Lobe Datasets
 
-**Template Selection** (`src/neuview/services/neuroglancer_js_service.py`):
-- `get_neuroglancer_template()` method selects dataset-appropriate templates
-- FAFB datasets use specialized `neuroglancer-fafb.js.jinja` template
-- Other datasets use standard `neuroglancer.js.jinja` template
+Standard property names:
+- `somaLocation` or `somaSide`
+- ROI information from `roiInfo` property
 
-### Dataset Detection Patterns
+**Adapter:** `src/neuview/infrastructure/adapters/cns_adapter.py`
 
-Centralized dataset type detection:
+### Dataset Detection
 
-**Dataset Detection Patterns** (`src/neuview/services/dataset_type_detector.py`):
-- Static methods for dataset type detection: `is_fafb()`, `is_cns()`, `is_hemibrain()`
-- String pattern matching for dataset categorization
-- Used throughout system for conditional dataset-specific behavior
-
-## Feature Implementation Guides
-
-### Connectivity Combination Implementation
-
-For combined pages (automatically generated when multiple hemispheres exist), connectivity entries are automatically merged:
-
-#### Problem
-Combined pages showed separate entries:
-- `L1 (R)` - 300 connections
-- `L1 (L)` - 245 connections
-
-#### Solution
-`ConnectivityCombinationService` merges these into:
-- `L1` - 545 connections (combined)
-
-#### Implementation
-
-**ConnectivityCombinationService** (`src/neuview/services/connectivity_combination_service.py`):
-- Combines L/R partners for the same neuron types automatically
-- Key methods: `combine_connectivity_partners()`, `_combine_partners()`
-- Groups partners by base type and combines statistics (weight, connection_count)
-- Handles body ID aggregation and neurotransmitter selection logic
-- Automatic soma side label removal for combined view presentation
-
-### ROI Combination Implementation
-
-Similar to connectivity, ROI entries are automatically combined for multi-hemisphere pages:
-
-#### Problem
-Combined pages showed separate ROI entries:
-- `ME_L` - 2500 pre, 1800 post synapses
-- `ME_R` - 2000 pre, 1200 post synapses
-
-#### Solution
-`ROICombinationService` merges these into:
-- `ME` - 4500 pre, 3000 post synapses (combined)
-
-#### Implementation
-
-**ROICombinationService** (`src/neuview/services/roi_combination_service.py`):
-- Combines L/R ROI entries for multi-hemisphere pages automatically
-- Supports multiple ROI naming patterns: `ME_L/ME_R`, `ME(L)/ME(R)`, layered patterns
-- Key methods: `combine_roi_data()`, `_combine_roi_entries()`
-- Aggregates synaptic statistics: pre, post, downstream, upstream counts
-- Pattern matching for flexible ROI name detection and grouping
-
-### Dynamic ROI Data System
-
-The Dynamic ROI Data System replaces hardcoded ROI arrays in Neuroglancer templates with live data fetched from Google Cloud Storage, ensuring ROI information is always up-to-date.
-
-#### Problem Statement
-
-Previously, the `neuroglancer-url-generator.js.jinja` template contained hardcoded arrays:
-
-```javascript
-// Hardcoded ROI data (maintenance burden)
-const ROI_IDS = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, ...];
-const ALL_ROIS = ["AL(L)", "AL(R)", "AME(L)", "AME(R)", ...];
-const VNC_IDS = [4, 5, 6, 7, 8, 9, 10, 11, 12, 13, ...];
-const VNC_NAMES = ["CV-posterior", "LegNp(T1)(L)", ...];
-```
-
-This approach had significant drawbacks:
-- **Manual Maintenance**: Required manual updates when ROI data changed
-- **Data Inconsistency**: Risk of hardcoded data becoming stale
-- **Version Mismatch**: Potential conflicts between different dataset versions
-
-#### Solution Architecture
-
-The system now uses a `ROIDataService` that:
-
-1. **Fetches Live Data**: Retrieves ROI segment properties from GCS endpoints
-2. **Caches Locally**: Stores data in `output/.cache/roi_data/` for performance
-3. **Template Integration**: Automatically injects ROI data as Jinja globals
-4. **Error Resilience**: Falls back to cached data if network requests fail
-
-#### ROIDataService Implementation
-
-```python
-class ROIDataService:
-    """Service for fetching and caching ROI data from Google Cloud Storage."""
-
-    def __init__(self, output_dir: Optional[Path] = None):
-        self.output_dir = output_dir or Path("output")
-        self.cache_dir = self.output_dir / ".cache" / "roi_data"
-        self.cache_dir.mkdir(parents=True, exist_ok=True)
-
-    def get_fullbrain_roi_data(self) -> Tuple[List[int], List[str]]:
-        """Fetch fullbrain ROI segment IDs and names."""
-        url = "gs://flyem-male-cns/rois/fullbrain-roi-v4/segment_properties/info"
-        data = self._fetch_and_parse_roi_data(url, "fullbrain_roi_v4.json")
-        return data.get("ids", []), data.get("names", [])
-
-    def get_vnc_roi_data(self) -> Tuple[List[int], List[str]]:
-        """Fetch VNC ROI segment IDs and names."""
-        url = "gs://flyem-male-cns/rois/malecns-vnc-neuropil-roi-v0/segment_properties/info"
-        data = self._fetch_and_parse_roi_data(url, "vnc_neuropil_roi_v0.json")
-        return data.get("ids", []), data.get("names", [])
-```
-
-#### Data Sources and Format
-
-**Fullbrain ROIs**:
-- **Endpoint**: `gs://flyem-male-cns/rois/fullbrain-roi-v4/segment_properties/info`
-- **Count**: 90 ROIs
-- **Template Variables**: `roi_ids`, `all_rois`
-
-**VNC ROIs**:
-- **Endpoint**: `gs://flyem-male-cns/rois/malecns-vnc-neuropil-roi-v0/segment_properties/info`
-- **Count**: 24 ROIs
-- **Template Variables**: `vnc_ids`, `vnc_names`
-
-The GCS endpoints return Neuroglancer segment properties format:
-
-```json
-{
-  "@type": "neuroglancer_segment_properties",
-  "inline": {
-    "ids": ["1", "2", "3", ...],
-    "properties": [{
-      "id": "source",
-      "type": "label",
-      "values": ["AL(L)", "AL(R)", "AME(L)", ...]
-    }]
-  }
-}
-```
-
-#### Template Integration
-
-The service integrates seamlessly with the Jinja2 template system:
-
-```javascript
-// Dynamic template variables (automatically populated)
-const ROI_IDS = {{ roi_ids|tojson }};
-const ALL_ROIS = {{ all_rois|tojson }};
-const VNC_IDS = {{ vnc_ids|tojson }};
-const VNC_NAMES = {{ vnc_names|tojson }};
-```
-
-#### Caching Strategy
-
-- **Cache Location**: `output/.cache/roi_data/` (follows project cache patterns)
-- **Cache Duration**: 1 hour (configurable)
-- **Fallback Behavior**: Uses stale cache if network requests fail
-- **Cache Files**:
-  - `fullbrain_roi_v4.json`
-  - `vnc_neuropil_roi_v0.json`
-
-#### Container Integration
-
-The service is automatically registered in the dependency injection container:
-
-```python
-def roi_data_service_factory(container: ServiceContainer) -> ROIDataService:
-    """Factory for ROI data service with container integration."""
-    config = container.get("config")
-    output_dir = Path(config.output.directory) if config.output.directory else None
-    return ROIDataService(output_dir=output_dir)
-```
-
-ROI data is automatically added as template globals during environment configuration:
-
-```python
-# ROI data automatically available in all templates
-roi_data = self.roi_data_service.get_all_roi_data()
-for key, value in roi_data.items():
-    self.env.globals[key] = value
-```
-
-#### Jinja Template Processing Fix
-
-A critical bug was resolved where Jinja placeholders weren't being processed correctly.
-
-**Problem**: The entire JavaScript template was wrapped in `{% raw %}` tags, preventing Jinja expression processing:
-
-```javascript
-// Template variables (processed)
-const NEUROGLANCER_BASE_URL = "{{ neuroglancer_base_url }}";
-
-{% raw %}
-// Everything here is literal text - Jinja expressions NOT processed
-const ROI_IDS = {{ roi_ids|tojson }};  // ❌ Not processed!
-{% endraw %}
-```
-
-**Solution**: Moved ROI data declarations outside the `{% raw %}` block:
-
-```javascript
-// Template variables (processed by Jinja)
-const NEUROGLANCER_BASE_URL = "{{ neuroglancer_base_url }}";
-const ROI_IDS = {{ roi_ids|tojson }};
-const ALL_ROIS = {{ all_rois|tojson }};
-
-{% raw %}
-// Static JavaScript code (not processed by Jinja)
-// ... rest of JavaScript
-{% endraw %}
-```
-
-#### ROI ID Collision Fix
-
-A sophisticated fix was implemented to resolve ROI ID collisions between brain and VNC datasets.
-
-**Problem**: ROI segment IDs overlap between datasets:
-- ID 7: "AOTU(L)" in brain dataset, "LegNp(T2)(L)" in VNC dataset
-- Clicking brain ROI checkboxes incorrectly toggled VNC layers
-
-**Root Cause**: Layer assignment logic used only ID values without dataset context:
-
-```javascript
-// Problematic code
-if (VNC_IDS.includes(parseInt(roiId))) {
-    // Always assigned to VNC layer, even for brain ROIs with same ID
-}
-```
-
-**Solution**: Introduced context tracking with `selectedRoiContexts` map:
-
-```javascript
-// Context-aware ROI management
-const selectedRoiContexts = new Map(); // Tracks 'brain' or 'vnc' context
-
-function addBrainRoiIds(roiIds) {
-    roiIds.forEach(id => selectedRoiContexts.set(id, 'brain'));
-    updateNeuroglancerLayers();
-}
-
-function addVncRoiIds(roiIds) {
-    roiIds.forEach(id => selectedRoiContexts.set(id, 'vnc'));
-    updateNeuroglancerLayers();
-}
-
-function updateNeuroglancerLayers() {
-    const brainRoiIds = [];
-    const vncRoiIds = [];
-
-    selectedRoiContexts.forEach((context, roiId) => {
-        if (context === 'brain') {
-            brainRoiIds.push(roiId);
-        } else if (context === 'vnc') {
-            vncRoiIds.push(roiId);
-        }
-    });
-
-    // Assign to correct layers based on context
-    setBrainNeuropilsLayer(brainRoiIds);
-    setVncNeuropilsLayer(vncRoiIds);
-}
-```
-
-This ensures ROI selections are always assigned to the correct Neuroglancer layer regardless of ID overlap.
-
-#### Benefits
-
-✅ **Always Current**: ROI data reflects latest source changes automatically
-✅ **Zero Maintenance**: Eliminates manual hardcoded array updates
-✅ **Data Integrity**: Single source of truth prevents inconsistencies
-✅ **Performance**: Local caching minimizes network overhead
-✅ **Reliability**: Graceful fallback handling for network issues
-✅ **Correct Behavior**: ROI ID collision resolution ensures proper layer assignment
-
-#### Testing and Validation
-
-Comprehensive test coverage ensures system reliability:
-
-- **Service Tests**: Validate GCS connectivity and data parsing
-- **Template Integration Tests**: Verify Jinja2 rendering with ROI data
-- **Cache Tests**: Confirm caching behavior and fallback mechanisms
-- **Collision Tests**: Verify correct layer assignment for overlapping IDs
-
-### Coefficient of Variation (CV) Implementation
-
-The CV feature adds variability analysis to connectivity tables, showing how consistent connection strengths are within each partner type.
-
-#### Problem
-Connectivity tables only showed average connection counts but provided no insight into the variability of connections across individual partner neurons.
-
-#### Solution
-Added coefficient of variation calculation and display:
-- CV = standard deviation / mean of connections per neuron
-- Values range from 0 (no variation) to higher values (more variation)
-- Provides normalized measure comparable across different scales
-
-#### Data Collection Implementation
-
-Modified `neuprint_connector.py` to track individual partner neuron weights:
-
-```python
-# In connectivity query processing
-type_soma_data[key] = {
-    "type": record["partner_type"],
-    "soma_side": soma_side,
-    "total_weight": 0,
-    "connection_count": 0,
-    "neurotransmitters": {},
-    "partner_body_ids": set(),
-    "partner_weights": {},  # NEW: Track weights per partner neuron
-}
-
-# Track weights per partner neuron for CV calculation
-partner_id = record["partner_bodyId"]
-if partner_id not in type_soma_data[key]["partner_weights"]:
-    type_soma_data[key]["partner_weights"][partner_id] = 0
-type_soma_data[key]["partner_weights"][partner_id] += int(record["weight"])
-
-### Synonym and Flywire Type Filtering Implementation
-
-The Types page includes specialized filtering functionality for synonym and Flywire type tags that allows users to filter neuron types based on additional naming information.
-
-#### Problem
-Users needed a way to quickly identify neuron types that have:
-1. Synonyms (alternative names from various naming conventions)
-2. Flywire types that are different from the neuron type name (meaningful cross-references)
-
-The challenge was ensuring that clicking on Flywire tags only shows cards with displayable Flywire types (different from the neuron name), not just any Flywire synonym.
-
-#### Solution
-Implemented independent filtering for synonym and Flywire type tags with proper handling of displayable vs. non-displayable Flywire types.
-
-#### Template Data Structure
-
-The template receives processed data with separate attributes:
-
-**Template Data Structure** (`templates/index.html.jinja`):
-- Data attributes embedded in neuron card wrappers for JavaScript access
-- Key attributes: `data-synonyms`, `data-processed-synonyms`, `data-flywire-types`, `data-processed-flywire-types`
-- Raw vs processed data separation for filtering logic
-- Template processing handles empty values and type differences
-
-#### JavaScript Filter Implementation
-
-Independent filter variables track each filter type:
-
-**JavaScript Filter Implementation** (`templates/static/js/filtering.js`):
-- Independent filter variables for each filter type: `currentSynonymFilter`, `currentFlywireTypeFilter`
-- Separate click handlers for synonym-tag and flywire-type-tag elements
-- Toggle behavior between "all" and specific filter states
-- State management prevents filter conflicts
-
-#### Filter Logic Implementation
-
-**Synonym Filter:**
-**Filter Logic Implementation** (`templates/static/js/filtering.js`):
-- **Synonym Filter**: `matchesSynonym()` checks both raw synonyms and processed synonyms data
-- **Flywire Filter**: `matchesFlywireType()` uses only processed flywire types for displayable differences
-- Closure pattern for encapsulated filter logic with data attribute access
-- Handles empty data gracefully with fallback to empty strings
-
-#### Visual Feedback Implementation
-
-Independent highlighting for each filter type:
-
-**Visual Feedback Implementation** (`templates/static/js/filtering.js`):
-- Dynamic CSS class management for filter tag highlighting
-- `selected` class application based on current filter state
-- Separate handling for synonym-tag and flywire-type-tag elements
-- jQuery-based DOM manipulation for visual state updates
-
-#### Key Implementation Details
-
-1. **Displayable Flywire Types**: The critical distinction is that `processedFlywireTypes` contains only Flywire synonyms that differ from the neuron type name. For example:
-   - AOTU019 with Flywire synonym "AOTU019" → Not in `processedFlywireTypes`
-   - Tm3 with Flywire synonym "CB1031" → Included in `processedFlywireTypes`
-
-2. **Independent Filtering**: Each filter type works independently - only one can be active at a time.
-
-3. **Filter Reset**: Clicking a tag of a different type automatically resets the other filter and switches to the new one.
-
-4. **CSS Integration**: Uses existing CSS classes `.synonym-tag.selected` and `.flywire-type-tag.selected` for visual feedback.
-
-#### Data Flow
-
-1. **Backend Processing**: Creates `processed_synonyms` and `processed_flywire_types` with only displayable items
-2. **Template Rendering**: Outputs data attributes for both raw and processed data
-3. **JavaScript Filtering**: Uses appropriate data attribute based on filter type
-4. **Visual Feedback**: Highlights all tags of the active filter type
-
-This implementation ensures perfect alignment between what users see (displayed tags) and what the filter shows (matching cards).
-
-#### CSS Integration
-
-The filtering system uses existing CSS classes for visual feedback:
-
-**CSS Integration** (`static/css/neuron-page.css`):
-- Tag styling for synonym-tag and flywire-type-tag elements
-- Selected state styling with color inversions and shadow effects
-- Cursor pointer for interactive elements
-- Color schemes: blue for synonyms, green for flywire types
-
-#### Performance Considerations
-
-1. **DOM Queries**: Filters cache jQuery selections to avoid repeated DOM queries
-2. **Event Delegation**: Uses delegated event handlers for dynamic content
-3. **Debouncing**: Text search includes debouncing to prevent excessive filtering
-4. **Data Attributes**: Uses data attributes for efficient filtering logic
-
-#### Testing Strategy
-
-The filtering implementation can be tested with:
-
-**Testing Strategy** (JavaScript console testing):
-- State management assertions for initial filter states
-- Filter logic validation with test card data
-- Visual feedback verification through DOM element counting
-- Console logging for debugging filter behavior
-
-#### Future Enhancements
-
-Planned improvements:
-1. **Filter Combinations**: Allow synonym AND Flywire filters simultaneously
-2. **Filter Persistence**: Save filter state in URL parameters
-3. **Advanced Search**: Boolean operators for complex queries
-4. **Performance**: Virtual scrolling for large datasets
-
-
-#### CV Calculation
-
-**CV Implementation** (`src/neuview/services/partner_analysis_service.py`):
-- Coefficient of variation calculation for connections per neuron
-- Statistical analysis: variance, standard deviation, and CV computation
-- Handles edge cases: single partner neurons (CV = 0), division by zero
-- Integration with partner data structure for upstream/downstream analysis
-
-#### CV Combination for L/R Entries
-
-**CV Combination Logic** (`src/neuview/services/connectivity_combination_service.py`):
-- Enhanced `_merge_partner_group()` method with CV field support
-- Weighted average calculation for combined CV values
-- Partner neuron count weighting for statistical accuracy
-- Proper handling of missing CV data and edge cases
-
-#### Template Integration
-
-**Template CV Integration** (`templates/sections/connectivity_table.html.jinja`):
-- CV column headers with descriptive tooltips
-- Safe template rendering with `partner.get('coefficient_of_variation', 0)` pattern
-- Consistent upstream and downstream table structure
-- Fallback value handling for missing CV data
-
-#### CV Interpretation
-
-| CV Range | Interpretation | Biological Meaning |
-|----------|---------------|-------------------|
-| 0.0 | No variation | Single partner neuron |
-| 0.0 - 0.3 | Low variation | Consistent connection strengths |
-| 0.3 - 0.7 | Medium variation | Moderate variability |
-| 0.7+ | High variation | Some partners much stronger |
-
-#### Testing Implementation
-
-**CV Testing** (`test/test_cv_implementation.py`):
-- `test_cv_calculation()` - Tests CV computation with various scenarios (high/low variation)
-- `test_cv_combination()` - Validates weighted average calculation for L/R entry combinations
-- Comprehensive test cases covering edge cases and statistical accuracy
-- Assertion-based validation for CV calculation correctness
-
-### Neuroglancer Integration Fixes
-
-#### Problem
-Neuroglancer JavaScript errors due to placeholder mismatches:
-
-**Problem**: Neuroglancer JavaScript errors due to placeholder type mismatches with expected array format.
-
-#### Solution
-**Template Variable Correction** (`src/neuview/services/neuroglancer_js_service.py`):
-- Correct placeholder types in template generation
-- Empty array initialization instead of string placeholders
-- Proper JSON array format for Neuroglancer compatibility
-
-#### Flexible Dataset Layer Detection
-
-**Multi-Dataset Layer Detection** (`templates/static/js/neuroglancer-url-generator.js.jinja`):
-- Enhanced layer detection logic for multiple dataset types
-- Flexible segmentation layer identification by type and properties
-- Support for both CNS ("cns-seg") and FAFB ("flywire-fafb:v783b") layer names
-
-### HTML Tooltip System Implementation
-
-Rich tooltips for enhanced user experience:
-
-#### Basic Structure
-
-**HTML Tooltip Structure** (`templates/sections/tooltips.html.jinja`):
-- Rich HTML content containers with formatted text, lists, and styling
-- Tooltip content wrapper with trigger elements
-- Flexible content structure supporting headings, paragraphs, and lists
-
-#### JavaScript Implementation
-
-**Tooltip JavaScript** (`templates/static/js/tooltip-system.js`):
-- `initializeHtmlTooltips()` - Sets up event listeners for tooltip elements
-- `positionTooltip()` - Dynamic positioning with screen boundary detection
-- Mouseenter/mouseleave event handling for show/hide behavior
-- Automatic positioning adjustment to prevent off-screen display
+Automatic detection based on dataset name in configuration.
 
 ## Troubleshooting
 
 ### Common Issues
 
-#### NeuPrint Connection Failures
+**"No neuron types found"**
+- Check NeuPrint credentials
+- Verify dataset name in config.yaml
+- Check network connectivity
 
-**Symptoms**:
-- Connection timeout errors
-- Authentication failures
-- Dataset not found errors
+**"Template rendering failed"**
+- Check template syntax
+- Verify all required context variables
+- Look for missing filters or macros
 
-**Debugging**:
-```bash
-# Test connection
-neuview test-connection
-
-# Check configuration
-neuview --verbose test-connection
-
-# Verify token
-echo $NEUPRINT_APPLICATION_CREDENTIALS
-```
-
-**Solutions**:
-- Verify NeuPrint token is valid and not expired
-- Check network connectivity to neuprint.janelia.org
-- Ensure dataset name matches exactly (case-sensitive)
-- Try different NeuPrint server endpoints
-
-#### Template Rendering Errors
-
-**Symptoms**:
-- Jinja2 template syntax errors
-- Missing template files
-- Context variable errors
-
-**Debugging**:
-```python
-def validate_template(template_path: str) -> Result[bool]:
-    """Validate template syntax and required variables."""
-    try:
-        env = Environment(loader=FileSystemLoader(os.path.dirname(template_path)))
-        template = env.get_template(os.path.basename(template_path))
-
-        # Test render with minimal context
-        template.render({})
-        return Result.success(True)
-    except Exception as e:
-        return Result.failure(f"Template error: {e}")
-```
+**"Cache issues"**
+- Clear cache with `--clear-cache` flag
+- Check cache directory permissions
+- Verify disk space
 
-**Solutions**:
-- Check template syntax with Jinja2 linter
-- Verify all required template variables are provided
-- Check file permissions on template directory
-- Ensure template inheritance chain is correct
+**Search not working:**
+- Check browser console for errors
+- Verify neurons.json and neurons.js were generated
+- Check data source: `window.neuronSearch.dataSource`
 
-#### Cache Issues
+### Debug Mode
 
-**Symptoms**:
-- Stale data being served
-- Cache corruption errors
-- Excessive memory usage
-
-**Solutions**:
+Enable verbose logging:
 ```bash
-# Clear all caches manually
-rm -rf output/.cache/
-
-# Check cache directory contents
-ls -la output/.cache/
-
-# Check cache file sizes
-du -sh output/.cache/*
+pixi run neuview build --verbose
 ```
 
-#### Performance Issues
-
-**Symptoms**:
-- Slow page generation
-- High memory usage
-- Database timeouts
-
-**Investigation**:
-- Enable performance profiling: `NEUVIEW_PROFILE=1`
-- Check cache hit rates
-- Monitor database query performance
-- Review memory usage patterns
-
-### Debugging Tools
-
-#### Log Configuration
-
-Enable detailed logging:
-
-```python
-import logging
-logging.basicConfig(
-    level=logging.DEBUG,
-    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
-    handlers=[
-        logging.FileHandler('debug.log'),
-        logging.StreamHandler()
-    ]
-)
+Or set environment variable:
+```bash
+export NEUVIEW_LOG_LEVEL=DEBUG
 ```
 
-#### Citation Logging
-
-neuView includes dedicated citation logging for tracking missing citations:
+### Performance Issues
 
-```python
-# Citation logging is automatically configured
-# Log files are created in output/.log/missing_citations.log
-
-# View citation issues
-cat output/.log/missing_citations.log
-
-# Monitor in real-time
-tail -f output/.log/missing_citations.log
-
-Citation logging is automatically enabled when an output directory is provided to text processing utilities. See the `TextUtils.process_synonyms` method and related text processing functions for automatic citation logging integration.
-
-**Citation Log Features**:
-- Rotating log files (1MB max, keeps 5 backups)
-- Timestamped entries with context information
-- UTF-8 encoding for international characters
-- Dedicated logger (`neuview.missing_citations`)
-- No interference with other system logs
-
-#### Development Mode
-
-Enable development mode by setting the `NEUVIEW_DEBUG` and `NEUVIEW_PROFILE` environment variables and running neuview with the `--verbose` flag.
-
-This enables:
-- Detailed operation logging
-- Performance timing information
-- Memory usage tracking
-- Cache operation details
-- Database query logging
-
-### Logging Architecture
-
-neuView uses a multi-layer logging system for different concerns including main application logging and dedicated citation logging with isolated loggers.
-
-#### System Loggers
-
-The system uses separate loggers for main application events and citation tracking. See the logging configuration in the service files for logger setup and configuration.
-
-#### Citation Logging Implementation
+**Slow generation:**
+- Enable caching
+- Use `--parallel` flag
+- Reduce `max_types` in discovery config
 
-The citation logging system automatically tracks missing citations with dedicated logger setup, log directory creation, file rotation handling, and custom formatting. See the `_setup_citation_logger` method in the citation service for the complete implementation including rotating file handlers and UTF-8 encoding support.
+**Large output size:**
+- Minimize HTML (default in production)
+- Compress images
+- Limit number of neuron types
 
-#### Integration Points
+### Citation Issues
 
-Citation logging is integrated into:
+**Missing citations:**
+- Verify citation format in source data
+- Check CitationService logs
+- Ensure proper DOI formatting
 
-1. **TextUtils.process_synonyms()**: Logs missing citations during synonym processing
-2. **CitationService.create_citation_link()**: Logs missing citations during link creation
-3. **Template rendering**: Automatic context passing for logging
+**Duplicate citations:**
+- Use citation deduplication
+- Check citation key generation
 
-#### Log File Management
+## File Organization
 
-- **Location**: `output/.log/missing_citations.log`
-- **Rotation**: Automatic when file reaches 1MB
-- **Backups**: Up to 5 backup files kept
-- **Format**: Timestamped with context information
-- **Encoding**: UTF-8 for international support
+```
+neuview/
+├── config.yaml              # Main configuration
+├── src/neuview/
+│   ├── core/               # Core components
+│   ├── domain/             # Domain models
+│   ├── application/        # Application services
+│   ├── infrastructure/     # Infrastructure layer
+│   ├── services/           # Business services
+│   └── templates/          # Jinja2 templates
+├── output/                 # Generated website
+│   ├── data/
+│   │   ├── neurons.json   # Neuron data (JSON)
+│   │   └── neurons.js     # Neuron data (JS fallback)
+│   ├── static/
+│   │   ├── js/
+│   │   │   └── neuron-search.js
+│   │   ├── css/
+│   │   └── icons/
+│   ├── types/             # Individual neuron pages
+│   ├── index.html         # Landing page
+│   ├── types.html         # Type listing
+│   └── help.html          # Help page
+├── test/                   # Tests
+├── docs/                   # Documentation
+└── .neuview_cache/        # Cache directory
+```
 
 ## Contributing
 
-### Code Style
-
-Follow these coding standards:
-
-- **PEP 8**: Python code style guide
-- **Type Hints**: Use type annotations for all public APIs
-- **Docstrings**: Google-style docstrings for all classes and functions
-- **Error Handling**: Use Result pattern for fallible operations
-- **Testing**: Minimum 90% test coverage for new code
-
-### Pull Request Process
-
-1. **Fork** the repository and create a feature branch
-2. **Implement** changes following coding standards
-3. **Test** thoroughly with unit and integration tests
-4. **Document** changes in relevant documentation files
-5. **Submit** pull request with clear description of changes
-
 ### Development Workflow
 
-#### Setting Up Development Environment
-
-Clone the repository, install dependencies with pixi, create feature branches using git, and install pre-commit hooks for code quality.
+1. Create feature branch from `main`
+2. Make changes with tests
+3. Run tests: `pixi run test`
+4. Format code: `pixi run format`
+5. Lint code: `pixi run lint`
+6. Submit pull request
 
-#### Running Tests
-
-Run various test suites including unit tests, coverage reporting, integration tests, and performance tests using the appropriate pixi run commands.
-
-### Adding New Services
+### Code Style
 
-When adding new services, follow this pattern:
+- Follow PEP 8
+- Use type hints
+- Write docstrings for public APIs
+- Keep functions focused and small
+- Prefer composition over inheritance
 
-1. **Define Interface**: Create abstract base class defining the service contract
-2. **Implement Service**: Create concrete implementation with proper error handling
-3. **Register Service**: Add to service container factory
-4. **Write Tests**: Comprehensive unit and integration tests
-5. **Update Documentation**: Add to this developer guide
+### Testing Requirements
 
-### Performance Considerations
+- Unit tests for new functions
+- Integration tests for new features
+- Maintain or improve coverage
+- All tests must pass
 
-When contributing code:
+### Documentation
 
-- **Cache Appropriately**: Use existing cache layers for expensive operations
-- **Minimize Database Queries**: Batch queries when possible
-- **Handle Large Datasets**: Consider memory usage for large neuron types
-- **Profile Changes**: Use performance profiling to verify no regressions
-- **Optimize Critical Paths**: Focus on page generation performance
+- Update user guide for user-facing changes
+- Update developer guide for architecture changes
+- Add inline comments for complex logic
+- Update configuration examples
 
----
+## Additional Resources
 
-This developer guide provides comprehensive coverage of neuView's architecture, implementation patterns, and development practices. For user-focused documentation, see the [User Guide](user-guide.md).
+- **GitHub Repository**: Project source code and issues
+- **NeuPrint Documentation**: https://neuprint.janelia.org/
+- **Jinja2 Documentation**: https://jinja.palletsprojects.com/
+- **pytest Documentation**: https://docs.pytest.org/
\ No newline at end of file
diff --git a/docs/user-guide.md b/docs/user-guide.md
index ca9f6ba2..768ba7c9 100644
--- a/docs/user-guide.md
+++ b/docs/user-guide.md
@@ -1,6 +1,6 @@
 # neuView User Guide
 
-A comprehensive guide for users of neuView, a modern Python CLI tool that generates interactive HTML pages for neuron types using data from NeuPrint. This guide covers installation, configuration, usage, and troubleshooting for all supported datasets.
+A comprehensive guide for users of the neuView neuron visualization platform.
 
 ## Table of Contents
 
@@ -8,8 +8,8 @@ A comprehensive guide for users of neuView, a modern Python CLI tool that genera
 - [Installation](#installation)
 - [Configuration](#configuration)
 - [Basic Usage](#basic-usage)
-- [Advanced Features](#advanced-features)
 - [Generated Website Features](#generated-website-features)
+- [Search Functionality](#search-functionality)
 - [Dataset-Specific Features](#dataset-specific-features)
 - [Understanding the Interface](#understanding-the-interface)
 - [Troubleshooting](#troubleshooting)
@@ -17,841 +17,699 @@ A comprehensive guide for users of neuView, a modern Python CLI tool that genera
 
 ## Quick Start
 
-Get up and running with neuView in minutes:
-
-1. **Install neuView**: Clone repository and run `pixi install`
+```bash
+# Install dependencies
+pixi install
 
-2. **Configure your connection**: Run `pixi run setup-env` and add your NeuPrint token to `.env`
+# Set up environment (creates .env file)
+pixi run setup-env
 
-3. **Generate your first page**: `pixi run neuview generate -n Dm4`
+# Edit .env file with your NeuPrint token
+# NEUPRINT_APPLICATION_CREDENTIALS=your_token_here
 
-4. **View the results**:
-   Open `output/types/Dm4.html` in your browser to see your interactive neuron catalog
+# Test connection
+pixi run neuview test-connection
 
-5. **Generate a complete set of pages**: `pixi run subset-medium`
+# Generate website
+pixi run neuview build
+```
 
-6. **View the start page**: Open `output/index.html` in your browser.
+Your website will be in the `output/` directory. Open `output/index.html` in a browser.
 
 ## Installation
 
 ### Prerequisites
 
-- **pixi** package manager ([installation guide](https://pixi.sh/latest/))
-- **Git** for cloning the repository
-- **NeuPrint access token** (get from [neuprint.janelia.org](https://neuprint.janelia.org/account))
+- Python 3.11 or higher
+- pixi package manager ([installation guide](https://pixi.sh))
+- NeuPrint access token
+- Git for version control
 
 ### Installation Steps
 
-**Installation Steps**:
-1. Clone the repository and navigate to directory (`git clone https://github.com/reiserlab/neuview; cd neuview`)
-2. [Optional]: Install dependencies: `pixi install`
-3. Verify installation: `pixi run neuview --version` and `pixi run neuview --help`
+1. **Clone the repository:**
+   ```bash
+   git clone <repository-url>
+   cd neuview
+   ```
+
+2. **Install dependencies:**
+   ```bash
+   pixi install
+   ```
+
+3. **Set up environment:**
+   ```bash
+   pixi run setup-env
+   ```
+   
+   This creates a `.env` file. Edit it to add your NeuPrint token:
+   ```
+   NEUPRINT_APPLICATION_CREDENTIALS=your_token_here
+   ```
+
+4. **Test connection:**
+   ```bash
+   pixi run neuview test-connection
+   ```
 
 ### Setting Up Authentication
 
-**Option 1: Environment File (Recommended with pixi)**
-**Authentication Methods**:
-1. **Environment file**: Run `pixi run setup-env`, then edit `.env` with your token
-2. **Environment variable**: `export NEUPRINT_APPLICATION_CREDENTIALS="your-token-here"`
+You need a NeuPrint authentication token:
 
-**Getting Your Token**:
-1. Visit [neuprint.janelia.org](https://neuprint.janelia.org/account)
-2. Log in with your Google account
-3. Click on your profile icon → "Account"
-4. Copy your "Auth Token"
+1. Go to your NeuPrint server (e.g., https://neuprint.janelia.org)
+2. Click "Account" → "Auth Token"
+3. Copy the token
+4. Add to `.env` file or set as environment variable:
+   ```bash
+   export NEUPRINT_APPLICATION_CREDENTIALS="your_token_here"
+   ```
 
 ## Configuration
 
 ### Basic Configuration
 
-neuView uses a `config.yaml` file for project settings. Each project generates a set of output files for the specified dataset. A default configuration is included:
-
-**Basic Configuration** - See `config.yaml` for complete structure:
-- **neuprint**: Server, dataset, and token configuration
-- **output**: Directory settings and JSON generation options
-- **html**: Title prefix and connectivity inclusion settings
-
-### Dataset-Specific Configurations
-
-neuView includes pre-configured settings for different datasets:
+Edit `config.yaml` to configure your build:
 
-- `config/config.cns.yaml` - Central Nervous System dataset
-- `config/config.optic-lobe.yaml` - Optic Lobe dataset
-- `config/config.fafb.yaml` - FAFB (FlyWire) dataset
-- `config/config.example.yaml` - Template configuration
-
-Use a specific configuration, create a symlink or copy with the name `config.yaml` in the project directory.
-
-#### Usage Example
-
-**Configuration Example** - `config.yaml`:
-Dataset aliases like `male-cns:v0.9` automatically resolve to appropriate adapters (CNS in this case). See configuration reference for complete examples.
+```yaml
+neuprint:
+  server: neuprint.janelia.org
+  dataset: optic-lobe:v1.0
 
-This configuration will work seamlessly without any warnings. The system automatically:
-- Recognizes `male-cns:v0.9` as a CNS dataset
-- Uses the appropriate CNS adapter
-- Handles all CNS-specific database queries correctly
+html:
+  title_prefix: "Optic Lobe"
+  github_repo: "https://github.com/your-repo"
+  youtube_channel: "https://youtube.com/your-channel"
 
-### Auto-Discovery Configuration
+performance:
+  max_workers: 4
+  cache_enabled: true
+```
 
-If no additional parameters are given, the command `neuview fill-queue` uses an auto-discovery mechanism to determine which neuron types to include in the queue. Configure automatic neuron type discovery settings:
+### Dataset-Specific Configurations
 
-**Discovery Settings** - Add under `discovery` section in `config.yaml`:
-- `max_types` (default: 10): Maximum number of neuron types to discover
-- `type_filter` (optional): Regex pattern to filter neuron type names
-- `exclude_types` (optional): List of neuron types to exclude from discovery
-- `include_only` (optional): If specified, only include these specific types
-- `randomize` (default: true): Randomize selection vs alphabetical order
+Different datasets may require specific settings:
 
-**Example Configuration:**
 ```yaml
-discovery:
-  max_types: 15
-  type_filter: "^(T|L)"  # Only types starting with T or L
-  exclude_types:
-    - "Test_Type"
-    - "Debug_Neuron"
-  randomize: false  # Use alphabetical order
+# For CNS dataset
+neuprint:
+  server: neuprint.janelia.org
+  dataset: hemibrain:v1.2.1
+
+# For FAFB/FlyWire dataset
+neuprint:
+  server: flywire.ai
+  dataset: production
 ```
 
 ### Neuron Type Subsets
 
-For testing and batching purposes, you can define neuron type subsets in your `config.yaml`:
+You can generate pages for a subset of neuron types:
 
-> **Note**: Neuron type selection is done through CLI options (e.g., `--neuron-type`) rather than configuration files. Use the command-line interface to specify which neuron types to process.
 ```yaml
 subsets:
-  subset-medium:
-    - "SAD103"
-    - "Tm3"
-    - "AOTU019"
-  subset-small:
-    - "SAD103"
-    - "Tm3"
+  small-test:
+    neuron_types:
+      - "Tm3"
+      - "Mi1"
+      - "T4"
+    generate_index: true
+    
+  medium-sample:
+    max_types: 50
+    randomize: true
+    generate_index: true
+```
+
+Use subsets with:
+```bash
+pixi run neuview build --subset small-test
 ```
 
 ## Basic Usage
 
 ### Essential Commands
 
-**Basic Commands**:
-- Test connection: `pixi run neuview test-connection`
-- Generate single page: `pixi run neuview generate -n Dm4`
-- Generate index page: `pixi run neuview create-list`
-- Generate a subset including index page: `pixi run subset-medium`
-- Generate all pages: `pixi run neuview fill-queue --all` then process with `pixi run neuview pop` or use the pixi shortcut task `pixi run create-all-pages`
-
-### Command Options
-
-| Option | Description | Example |
-|--------|-------------|---------|
-| `-n, --neuron-type` | Specify neuron type | `-n Dm4` |
-| `--image-format` | Image format for grids | `--image-format svg` |
-| `--embed/--no-embed` | Embed images in HTML | `--embed` |
-| `--minify/--no-minify` | HTML minification | `--no-minify` |
-| `-c, --config` | Use custom config | `-c config.yaml` |
-| `--verbose` | Enable detailed output | `--verbose` |
-
-### Neuron Type Inspection
-
-Get detailed information about specific neuron types:
-
-**Neuron Type Details**:
-Use the `inspect` command to get detailed information about specific neuron types:
 ```bash
-pixi run neuview inspect Dm4
-```
+# Generate complete website
+pixi run neuview build
 
-## Advanced Features
+# Generate with cache clearing
+pixi run neuview build --clear-cache
 
-### Batch Processing with Queue System
+# Inspect a specific neuron type
+pixi run neuview inspect "Tm3"
 
-Process multiple neuron types efficiently using the queue system:
+# Generate for specific neuron types
+pixi run neuview build --types "Tm3,Mi1,T4"
 
-**Queue Operations**:
-- Add single type: `pixi run neuview fill-queue --neuron-type Dm4`
-- Add all types: `pixi run neuview fill-queue --all`
-- Process queue: `pixi run neuview pop`
-- View queue status: `ls -la output/.queue/`
-- Clear queue: `rm -rf output/.queue/`
+# Use a subset from config
+pixi run neuview build --subset small-test
 
-### Automatic Page Generation
+# Verbose output for debugging
+pixi run neuview build --verbose
+```
 
-neuView automatically detects available soma sides and generates all appropriate pages:
+### Command Options
 
-**Automatic Page Generation**:
-- Multi-hemisphere data: Creates individual hemisphere pages (Dm4_L.html, Dm4_R.html) plus combined view (Dm4.html)
-- Single-hemisphere data: Creates only the relevant side-specific page
-- Detection happens automatically based on your neuron data distribution
+**`build` command:**
+- `--clear-cache` - Clear all caches before building
+- `--types <list>` - Comma-separated list of neuron types
+- `--subset <name>` - Use a predefined subset from config
+- `--parallel` - Enable parallel processing
+- `--verbose` - Detailed logging output
+- `--output <dir>` - Custom output directory
 
-**Automatic Detection Logic**:
-- **Multiple hemispheres**: Creates individual side pages + combined page
-- **Single hemisphere**: Creates only the relevant side page
-- **Mixed data**: Handles unknown/unassigned soma sides intelligently
-- **No user intervention required**: System analyzes data and creates optimal page set
+**`inspect` command:**
+- `neuview inspect <type>` - Show detailed information about a neuron type
+- Displays: neuron count, soma distribution, connectivity stats
 
-### Citation Management
+## Generated Website Features
 
-neuView automatically tracks missing citations and logs them for easy maintenance:
+### Interactive Index Page
 
-**Citation Management Commands**:
-- Check missing citations: `cat output/.log/missing_citations.log`
-- Monitor in real-time: `tail -f output/.log/missing_citations.log`
-- Count unique missing: Use grep and sort commands on the log file
+The landing page (`index.html`) includes:
 
-**Adding Missing Citations**: Add entries to `input/citations.csv` in format: `citation_key,DOI,display_text`
+- **Quick Search**: Real-time autocomplete search with synonym support
+- **Featured Types**: Highlighted neuron types
+- **Statistics**: Dataset overview and neuron counts
+- **Navigation**: Links to types list and help pages
 
-**Citation Log Features**:
-- **Automatic Tracking**: Missing citations logged during page generation
-- **Context Information**: Shows which neuron type and operation encountered missing citation
-- **Rotating Logs**: Files rotate at 1MB (keeps 5 backups)
-- **Timestamped Entries**: Each entry includes timestamp of missing citation encounter
+**Quick Search:**
+- Type to see autocomplete suggestions
+- Searches neuron names, synonyms, and FlyWire types
+- Click a result to navigate to that neuron type
+- Keyboard navigation: ↑↓ arrows, Enter to select, Esc to close
 
-### Verbose Mode and Debugging
+### Individual Neuron Type Pages
 
-Get detailed information about processing:
+Each neuron type has dedicated pages showing:
 
-**Verbose Mode Commands**:
-- Enable verbose output: `pixi run neuview --verbose generate -n Dm4`
-- Enable debug mode: Set `NEUVIEW_DEBUG=1` then run neuview commands
+**Overview Section:**
+- Neuron type name and description
+- Cell count and soma distribution
+- Synonyms and alternative names
+- FlyWire type identifiers
 
-## Generated Website Features
+**Connectivity Tables:**
+- Upstream partners (inputs)
+- Downstream partners (outputs)
+- Connection weights and synapse counts
+- Coefficient of Variation (CV) showing connection variability
+- Neurotransmitter information
 
-### Interactive Index Page
+**ROI (Brain Region) Information:**
+- Synapse distribution across brain regions
+- Input/output counts per region
+- Interactive region selection
 
-The main `index.html` provides:
+**Neuroglancer Integration:**
+- 3D visualization links
+- Interactive neuron selection
+- ROI overlay capabilities
 
-- **Real-time search** with autocomplete for neuron types
-- **Advanced filtering** by cell count, neurotransmitter, brain region
-- **Interactive cell count tags** - click to filter by count ranges
-- **Automatic hemisphere detection** - generates appropriate pages for available data
-- **Responsive design** for mobile and desktop
-- **Export functionality** for filtered results
+### Interactive Features
 
-### Individual Neuron Type Pages
+**Search:**
+- Header search bar on all pages
+- Real-time autocomplete
+- Searches by: neuron name, synonym, FlyWire type
+- Side-specific navigation (L/R/Combined)
+
+**Filtering (Types Page):**
+- Filter by cell count
+- Filter by neurotransmitter
+- Filter by brain regions
+- Text search across all fields
+- Tag-based filtering (synonyms, FlyWire types)
+
+**Neuroglancer:**
+- Click checkboxes to add neurons to 3D viewer
+- Select multiple connectivity partners
+- Toggle ROI visibility
+- Automatic URL generation for sharing
+
+## Search Functionality
+
+### How Search Works
+
+The search system loads neuron data from JSON (or JavaScript fallback) and provides instant autocomplete suggestions.
+
+**Data Sources:**
+- **Primary**: `data/neurons.json` - Used when served from web server
+- **Fallback**: `data/neurons.js` - Used when opening local files
+
+### Search Features
+
+**Searches across:**
+1. **Neuron names** (e.g., "AN07B013")
+2. **Synonyms** (e.g., "Cachero 2010: aSP-j")
+3. **FlyWire types** (e.g., "CB3127")
+
+**Smart matching:**
+- Exact match (highest priority)
+- Starts with query
+- Contains query
+- Synonym author/year matching
+- Synonym name-only matching
+
+**Example:** For neuron "AOTU001" with synonym "Cachero 2010: aSP-j"
+- Typing "aotu" → matches name
+- Typing "cachero" → matches synonym author
+- Typing "asp-j" → matches synonym name
+
+### Using Search
+
+**On any page:**
+1. Click in the search box
+2. Start typing (minimum 2 characters)
+3. See autocomplete dropdown
+4. Use ↑↓ arrows to navigate
+5. Press Enter or click to select
+6. Navigate to neuron page
+
+**Side selection:**
+- Some neurons show (L, R, M) links
+- Click to go directly to that hemisphere
+- Combined page shows all hemispheres
+
+### Search Data Format
+
+The search uses a structured JSON format:
+
+```json
+{
+  "names": ["AN07B013", "AOTU001", ...],
+  "neurons": [
+    {
+      "name": "AN07B013",
+      "urls": {
+        "combined": "AN07B013.html",
+        "left": "AN07B013_L.html",
+        "right": "AN07B013_R.html"
+      },
+      "types": {
+        "flywire": ["AN_GNG_60"],
+        "synonyms": ["Cachero 2010: aSP-j"]
+      }
+    }
+  ]
+}
+```
 
-Each neuron type page includes comprehensive information:
+### Accessing Search Data Externally
 
-**Summary Statistics**:
-- Cell counts by hemisphere (L, R, combined)
-- Neurotransmitter predictions with confidence scores
-- Brain region innervation summary
-- Morphological classifications
+External services can access the neuron data:
 
-**3D Visualization**:
-- Direct links to Neuroglancer with pre-loaded neuron data
-- Interactive 3D neuron models
-- Layer-by-layer anatomical analysis
-- Coordinate system integration
+**Python example:**
+```python
+import requests
 
-**Connectivity Analysis**:
-- Input/output connection tables with partner details
-- Connection strength metrics and statistics
-- Partner neuron links for cross-referencing
-- Hemisphere-specific connectivity patterns
+response = requests.get('https://your-site.com/data/neurons.json')
+data = response.json()
 
-**Spatial Coverage**:
-- Hexagonal grid visualizations showing neuron distribution
-- Brain region distribution maps
-- Hemisphere comparison views
-- ROI (Region of Interest) innervation analysis
+# Get all neuron names
+names = data['names']
 
-### Interactive Features
+# Find neurons with specific FlyWire type
+neurons_with_type = [
+    n for n in data['neurons']
+    if n.get('types', {}).get('flywire', []) == ['CB3127']
+]
+```
 
-**Data Tables**:
-- Sortable columns for all data types
-- Searchable content with real-time filtering
-- Pagination controls for large datasets
-- Exportable data in multiple formats
-
-**Filtering Controls**:
-- Connection strength sliders for fine-tuning
-- Brain region selections with hierarchical organization
-- Hemisphere toggles (L/R/Combined)
-- Cell count range selectors
-- **Synonym and Flywire Type Filtering**: Click on synonym tags (blue) or Flywire type tags (green) to filter neuron types by additional naming information
-
-#### Advanced Filtering System
-
-The Types page provides comprehensive filtering capabilities through multiple mechanisms designed for efficient neuron type exploration.
-
-##### Basic Filters
-
-Available through dropdown controls:
-
-- **ROI (Region of Interest)**: Filter by brain regions where neurons are found
-- **Neurotransmitter**: Filter by consensus or predicted neurotransmitter type
-- **Dimorphism**: Filter by sexual dimorphism characteristics
-- **Cell Class Hierarchy**: Filter by superclass, class, or subclass
-- **Soma Side**: Filter by hemisphere (left, right, middle, undefined)
-
-##### Tag-Based Filters
-
-Advanced filters activated by clicking colored tags within neuron type cards:
-
-**Synonym Filtering**:
-- **Purpose**: Find all neuron types that have alternative names or synonyms from various naming conventions
-- **How to Use**:
-  1. Look for blue synonym tags on neuron type cards
-  2. Click any synonym tag to activate the synonym filter
-  3. Only neuron types with synonyms will be displayed
-  4. All synonym tags across all visible cards will be highlighted in blue
-  5. Click any synonym tag again to deactivate the filter
-- **Use Cases**:
-  - Finding neuron types with historical or alternative naming
-  - Identifying types referenced in multiple studies
-  - Discovering naming conventions across different datasets
-
-**Flywire Type Filtering**:
-- **Purpose**: Find neuron types that have meaningful Flywire cross-references (Flywire synonyms that differ from the neuron type name)
-- **How to Use**:
-  1. Look for green Flywire type tags on neuron type cards
-  2. Click any Flywire type tag to activate the Flywire filter
-  3. Only neuron types with displayable Flywire types will be shown
-  4. All Flywire type tags across all visible cards will be highlighted in green
-  5. Click any Flywire type tag again to deactivate the filter
-- **Important Note**: This filter only shows neuron types where the Flywire synonym is different from the neuron type name:
-  - ✅ `Tm3` with Flywire synonym `CB1031` → Will be shown (meaningful cross-reference)
-  - ❌ `AOTU019` with Flywire synonym `AOTU019` → Will not be shown (not meaningful)
-- **Use Cases**:
-  - Finding neuron types with cross-dataset references
-  - Identifying types mapped to Flywire connectome
-  - Discovering meaningful alternative identifiers for comparative analysis
-
-##### Text Search Filter
-
-**Real-time text-based search** that searches across:
-- Neuron type names
-- Synonym names
-- Flywire type names
-- Instant filtering as you type
-
-##### Filter Behavior
-
-**Independence**:
-- Each filter type works independently
-- Multiple basic filters can be combined (ROI + neurotransmitter, etc.)
-- Only one tag-based filter (synonym OR Flywire) can be active at a time
-
-**Interaction Rules**:
-- Clicking a synonym tag while a Flywire filter is active will switch to synonym filtering
-- Clicking a Flywire tag while a synonym filter is active will switch to Flywire filtering
-- Basic dropdown filters can be combined with tag-based filters
-
-**Visual Feedback**:
-- Active filters are clearly indicated through:
-  - Highlighted tags (blue for synonyms, green for Flywire types)
-  - Updated filter status messages
-  - Real-time count updates of visible results
-
-**Reset Options**:
-- **Individual Reset**: Click the same tag type again to deactivate
-- **Clear All**: Use the "Clear Filters" button to reset all filters
-- **Filter Switch**: Click a different tag type to switch filters
-- **Page Refresh**: Reloads with no active filters
-
-##### Troubleshooting Filters
-
-**Common Issues**:
-
-*"No results found"*
-- Check if multiple restrictive filters are applied
-- Try clearing all filters and starting over
-- Verify the dataset contains the expected data
-
-*"Flywire filter shows no results"*
-- This dataset may not have meaningful Flywire cross-references
-- Remember that identical Flywire synonyms are not considered displayable
-
-*"Tags not highlighting correctly"*
-- Ensure JavaScript is enabled
-- Check for browser console errors
-- Try refreshing the page
-
-**Performance Considerations**:
-- Large datasets (>1000 neuron types) may experience slower filter response
-- Consider using basic filters first to reduce the working set
-- Text search is debounced to prevent excessive filtering during typing
-
-##### Best Practices
-
-1. **Start Broad**: Use basic filters first to narrow down the dataset
-2. **Combine Strategically**: Combine complementary filters (e.g., ROI + neurotransmitter)
-3. **Use Tag Filters for Discovery**: Use synonym/Flywire filters to find cross-referenced types
-4. **Check Filter Status**: Always verify which filters are active via visual indicators
-
-This comprehensive filtering system helps researchers quickly identify neuron types that have been cross-referenced with external databases or have alternative naming information available, making data exploration and comparative analysis more efficient.
-
-**Navigation**:
-- Breadcrumb navigation for easy orientation
-- Quick neuron type switcher in header
-- Cross-referenced links between related neurons
-- Mobile-friendly hamburger menus
+**JavaScript example:**
+```javascript
+fetch('https://your-site.com/data/neurons.json')
+  .then(r => r.json())
+  .then(data => {
+    console.log('Total neurons:', data.names.length);
+    console.log('Neurons:', data.neurons);
+  });
+```
 
 ## Dataset-Specific Features
 
 ### FAFB (FlyWire) Dataset
 
-**Special Features**:
-- Adapted for FlyWire-specific data structures
-- Handles different soma side nomenclature (CENTER vs MIDDLE)
-- Optimized queries for FAFB database schema
-
-**Important Notes**:
-- **ROI Checkboxes**: Not available for FAFB datasets due to neuroglancer limitations
-- **Soma Sides**: Uses "C" for center instead of "M" for middle
-- **Template Selection**: Automatically uses FAFB-specific neuroglancer templates
+**Special behaviors:**
+- Uses `side` property instead of `somaSide`
+- Different Neuroglancer template
+- ROI checkboxes automatically disabled
+- FlyWire-specific visualizations
 
-**Why No ROI Checkboxes?**
-FAFB neuroglancer data lacks reliable ROI visualization support. The system automatically detects FAFB datasets and removes ROI checkboxes to prevent user confusion. ROI statistics are still displayed for reference.
+**Configuration:**
+```yaml
+neuprint:
+  server: flywire.ai
+  dataset: production
+```
 
 ### CNS, Hemibrain, and Optic-Lobe Datasets
 
-**Full Feature Set**:
-- Complete ROI checkbox functionality for 3D visualization
-- Standard soma side classifications (L, R, M)
-- Full neuroglancer integration with mesh overlays
-- Complete connectivity visualization
+**Standard features:**
+- Full ROI visualization support
+- Standard Neuroglancer integration
+- Hemisphere-specific pages (L/R)
+- Combined views for bilateral types
 
-### Dataset Detection
+**Configuration:**
+```yaml
+neuprint:
+  server: neuprint.janelia.org
+  dataset: hemibrain:v1.2.1  # or cns:v1.0, optic-lobe:v1.0
+```
 
-The system automatically detects dataset type and adapts functionality:
+### Dataset Detection
 
-- **FAFB Detection**: Dataset name contains "fafb" (case-insensitive)
-- **Other Datasets**: Assume full ROI visualization capability
-- **Automatic Adaptation**: No user configuration required
+The system automatically detects dataset type and adjusts:
+- Property names for data extraction
+- Neuroglancer template selection
+- ROI visualization capabilities
+- Page generation logic
 
 ## Understanding the Interface
 
 ### ROI (Region of Interest) Features
 
-**For CNS, Hemibrain, and Optic-Lobe Datasets**:
-
-**Interactive ROI Table** (for CNS/Hemibrain/Optic-Lobe datasets):
-- Checkbox column for toggling ROI visibility in neuroglancer
-- ROI Name with innervation statistics (∑ In, % In, % Out)
-- Real-time interaction with 3D viewer
-
-**Interactive Behavior**:
-1. **Click to Toggle**: Click any ROI checkbox to show/hide that region in neuroglancer
-2. **Visual Feedback**: Checked boxes (☑) show active ROIs, unchecked (☐) show inactive
-3. **Real-time Updates**: Neuroglancer viewer updates immediately when checkboxes change
-4. **Multi-selection**: Multiple ROIs can be selected simultaneously
-5. **Persistent State**: ROI selections maintained during navigation
-
-**For FAFB Dataset**:
+**ROI Tables show:**
+- Brain regions where neurons have synapses
+- Input (upstream) and output (downstream) counts
+- Relative distribution across regions
 
-**View-Only ROI Table** (for FAFB datasets):
-- Statistical reference without interactive checkboxes
-- ROI Name with innervation data for analysis
-- Clean interface without false interaction promises
+**Neuroglancer ROI Checkboxes:**
+- Available for CNS/Hemibrain/Optic-lobe datasets
+- Disabled for FAFB (not supported)
+- Click to overlay regions in 3D viewer
+- Multiple regions can be selected
 
-**View-Only Mode**:
-1. **Statistical Reference**: ROI table provides innervation data for analysis
-2. **No Interactive Elements**: Checkboxes not displayed to avoid confusion
-3. **Clean Interface**: Maintains professional appearance without false promises
-4. **Data Accuracy**: All ROI statistics remain accurate and useful
-
-#### ROI Data Quality and Reliability
-
-The neuView system has been enhanced with significant improvements to ROI data quality and reliability:
-
-**Always Up-to-Date Data**:
-- ROI information is automatically fetched from the latest source datasets
-- No more outdated or inconsistent ROI lists
-- Data reflects the most current brain atlas information
-
-**Improved ROI Selection Accuracy**:
-- Fixed issue where brain ROI selections could incorrectly affect VNC regions
-- Each ROI selection now correctly targets its intended brain region
-- Enhanced layer assignment ensures proper neuroglancer visualization
-
-**Enhanced Data Consistency**:
-- ROI names and IDs are synchronized with source datasets
-- Corrected naming inconsistencies (e.g., proper "WTct" vs "NTct" labels)
-- Accurate ROI ordering that matches actual segment IDs
-
-**Reliability Features**:
-- Local caching ensures fast performance
-- Automatic fallback to cached data if network issues occur
-- Error-resistant design maintains functionality under various conditions
-
-**What This Means for Users**:
-- ✅ More reliable ROI checkbox behavior
-- ✅ Accurate region highlighting in neuroglancer
-- ✅ Current and consistent ROI information
-- ✅ Better performance with intelligent caching
-- ✅ Seamless experience even with network issues
-
-These improvements ensure that ROI interactions work correctly and reliably across all supported datasets.
+**ROI Data:**
+- Dynamically loaded from authoritative sources
+- Cached locally for performance
+- Automatically updated with dataset changes
 
 ### Connectivity Tables
 
-**Table Columns**:
-- **Partner**: Neuron type that connects to/from the main neuron type
-- **#**: Number of partner neurons of this type
-- **NT**: Neurotransmitter (ACh, Glu, GABA, etc.)
-- **Conns**: Average connections per neuron of the main type
-- **CV**: Coefficient of variation for connections per neuron (measures variability)
-- **%**: Percentage of total input/output connections
-
-**Coefficient of Variation (CV)**:
-- Measures how variable the connection strengths are across partner neurons
-- Formula: CV = standard deviation / mean of connections per neuron
-- Provides normalized measure comparable across different connection scales
-- **Interpretation Guide**:
-  - **CV = 0.0**: No variation (single partner neuron)
-  - **Low CV (0.0-0.3)**: Consistent connection strengths across partners
-  - **Medium CV (0.3-0.7)**: Moderate variation in connection strengths
-  - **High CV (0.7+)**: High variation, some partners much stronger than others
-
-**CV Usage Examples**:
-- CV = 0.25 for L1 partners: Most L1 neurons have similar connection counts
-- CV = 0.75 for Tm9 partners: Few strong Tm9 connections, many weak ones
-- CV = 0.0 for Mi1 partners: Only one Mi1 neuron connects (no variation)
-
-**Combined Pages (e.g., Dm4.html)**:
-- Shows merged entries: "L1 - 545 connections" (combining L1(L) + L1(R))
-- CV values are weighted averages: CV = Σ(cv_i × count_i) / Σ(count_i)
-- Example: L1(L) CV=0.25 (20 neurons) + L1(R) CV=0.30 (8 neurons) → L1 CV=0.268
-- Cleaner visualization with reduced redundancy
-- Neuroglancer links include neurons from both hemispheres
-
-**Individual Hemisphere Pages (e.g., Dm4_L.html)**:
-- Automatically generated when hemisphere-specific data exists
-- Shows hemisphere-specific data exactly as stored in database
-- No combination or modification of original data
-- Direct neuroglancer links to hemisphere-specific neurons
-
-**CV Applications and Benefits**:
-
-*Research Applications*:
-- **Connection Pattern Analysis**: Identify partner types with consistent vs variable connectivity
-- **Circuit Reliability**: Low CV indicates reliable circuit components, high CV suggests specialization
-- **Developmental Studies**: Compare CV across developmental stages to study connection refinement
-- **Comparative Analysis**: Use CV to compare connection reliability across different neuron types
-
-*Data Quality Assessment*:
-- **Reconstruction Quality**: Unusually high CV may indicate incomplete reconstructions
-- **Biological vs Technical Variation**: Distinguish natural biological variation from technical artifacts
-- **Partner Classification**: CV helps validate partner type classifications and groupings
-
-*Practical Usage*:
-- **Circuit Modeling**: Use CV to inform computational models of circuit variability
-- **Experimental Design**: Target high-CV partners for detailed experimental validation
-- **Literature Comparison**: Compare CV values with published electrophysiology data
-
-### Tooltip System
-
-Rich HTML tooltips provide additional context throughout the interface:
-
-**Basic Tooltips**:
-- Hover over "?" icons for detailed explanations
-- Rich HTML content with formatted text and lists
-- Automatic positioning to stay within viewport
-
-**Usage Examples**:
-- Neuroglancer explanations and usage tips
-- Data field definitions and calculations
-- Feature descriptions and limitations
-
-**Mobile Support**:
-- Touch-friendly sizing and positioning
-- Simplified layouts for small screens
-- Responsive text sizing
+**Understanding the columns:**
+
+| Column | Description |
+|--------|-------------|
+| Partner Type | Name of connected neuron type |
+| # | Number of individual partner neurons |
+| Total Weight | Sum of all connections |
+| Avg. Weight | Average connections per neuron |
+| CV | Coefficient of Variation (connection consistency) |
+| NT | Primary neurotransmitter |
+
+**Coefficient of Variation (CV):**
+- Shows connection variability
+- CV = (standard deviation / mean) × 100
+- Low CV (0-30): Consistent connections
+- Medium CV (30-70): Moderate variation
+- High CV (70+): Some partners much stronger
+
+**Neurotransmitter Abbreviations:**
+- ACH: Acetylcholine
+- GABA: Gamma-aminobutyric acid
+- GLU: Glutamate
+- DA: Dopamine
+- 5HT: Serotonin
+- OCT: Octopamine
+
+### Neuroglancer Integration
+
+**Opening in Neuroglancer:**
+1. Click "Open in Neuroglancer" button
+2. 3D viewer opens with the neuron highlighted
+3. Use checkboxes to add connectivity partners
+4. Select ROIs to visualize regions
+
+**Checkbox features:**
+- Empty bodyIds → Checkbox disabled
+- Self-reference detection → Prevents duplicates
+- Multiple selection → Build complex views
+- URL updates automatically
+
+**Tips:**
+- Start with just the main neuron
+- Add partners one at a time
+- Use ROI overlays sparingly
+- Save URLs to share specific views
 
 ### Understanding the Data
 
-**Neuron Counts**:
-- Based on reconstructed neurons in the dataset
-- May vary between hemispheres due to reconstruction completeness
-- Combined counts represent total across both hemispheres
-
-**Connectivity**:
-- Verified synaptic connections from electron microscopy
-- Connection weights represent synapse counts
-- Partner percentages calculated relative to total connections
-
-**Hemisphere Classifications**:
-- Based on anatomical position of cell body (soma)
-- L = Left hemisphere, R = Right hemisphere
-- C/M = Center/Middle (combined or midline neurons)
+**Neuron Counts:**
+- Total count includes all hemispheres
+- L/R counts show distribution
+- Unknown soma side may exist
 
-**ROI Data**:
-- Regions of Interest with innervation statistics
-- Pre/Post counts indicate input/output synapses
-- Percentages show relative innervation strength
+**Connection Weights:**
+- Weight = number of synapses
+- Higher weight = stronger connection
+- Directional: upstream vs downstream
 
-**Neurotransmitter Predictions**:
-- Computational predictions requiring experimental validation
-- Confidence scores indicate prediction reliability
-- Multiple predictions possible for single neuron type
+**Soma Sides:**
+- L: Left hemisphere
+- R: Right hemisphere
+- M: Middle/central
+- Combined pages show all
 
 ## Troubleshooting
 
-### Citation Issues
-
-**Missing Citations in Pages**
-
-If you notice citations are missing or showing as broken links:
-
-1. Check the citation log file: `cat output/.log/missing_citations.log`
-
-2. Add missing citations to `input/citations.csv` in format: `citation_key,DOI,display_text`
-
-3. Regenerate affected pages: `pixi run neuview generate -n YourNeuronType`
-
-**Citation Log File Not Created**
-
-If `output/.log/missing_citations.log` doesn't exist:
-- Ensure the output directory is writable
-- Check that pages are being generated (citations are only logged during generation)
-- Verify that there are actually missing citations to log
-
-**Large Citation Log Files**
-
-Citation logs automatically rotate when they reach 1MB:
-- Up to 5 backup files are kept (`.log.1`, `.log.2`, etc.)
-- Check for repeated missing citations that should be added to `citations.csv`
-- Old backup files can be safely deleted if disk space is needed
-
 ### Common Issues
 
-**Authentication Problems**
-**Connection Troubleshooting Commands**:
-- Verify token: `echo $NEUPRINT_APPLICATION_CREDENTIALS`
+**"No neuron types found"**
+- Check NeuPrint credentials in `.env`
+- Verify dataset name matches exactly
 - Test connection: `pixi run neuview test-connection`
-- Verbose connection test: `pixi run neuview --verbose test-connection`
-
-**Connection Issues**
-**Advanced Connection Debugging**:
-- Verbose connection testing: `pixi run neuview --verbose test-connection`
-- Server configuration: Edit `neuprint.server` setting in `config.yaml`
-- Network connectivity: `ping neuprint.janelia.org`
-
-**Performance Issues**
-**Performance Issue Commands**:
-- Check output directory for cached files: `ls -la output/.cache/`
-- Clear corrupted cache: `rm -rf output/.cache/`
-- Enable performance monitoring: Set `NEUVIEW_PROFILE=1`
-
-**Missing Output**
-**Missing Output Troubleshooting**:
-- Verify generation: `ls -la output/`
-- Regenerate with verbose output: `pixi run neuview --verbose generate -n YourNeuronType`
-- Check index generation: `pixi run neuview --verbose create-list`
-
-**ROI Checkboxes Not Working**
-
-For CNS/Hemibrain/Optic-Lobe datasets:
-
-Recent improvements have resolved most ROI checkbox issues:
-- ✅ Fixed ROI ID collision issues (brain vs VNC regions)
-- ✅ Improved layer assignment accuracy
-- ✅ Enhanced data consistency and reliability
-
-If you still experience issues:
-1. **Refresh the page**: Recent fixes may require a page reload
-2. **Check browser console**: Look for JavaScript errors (F12 → Console)
-3. **Verify neuroglancer loads**: Ensure the 3D viewer appears properly
-4. **Try different ROIs**: Test with various brain regions
-
-**Common Solutions**:
-- Clear browser cache and reload the page
-- Ensure JavaScript is enabled in your browser
-- Try a different supported browser (Chrome/Firefox recommended)
-
-For FAFB datasets:
-- This is expected behavior - FAFB doesn't support ROI checkboxes
-- ROI data is still accurate for analysis purposes
-- Use other navigation methods in neuroglancer
+- Check network connectivity
+
+**"Template rendering failed"**
+- Check for syntax errors in custom templates
+- Verify all required template variables present
+- Look at verbose output: `--verbose` flag
+
+**"Cache issues"**
+- Clear cache: `pixi run neuview build --clear-cache`
+- Check cache directory permissions
+- Verify sufficient disk space
+
+**Search not working:**
+- Open browser console (F12)
+- Check for JavaScript errors
+- Verify `neurons.json` and `neurons.js` exist in `output/data/`
+- Check data source in console: `window.neuronSearch.dataSource`
+
+**Page generation slow:**
+- Enable caching (default)
+- Reduce parallelization if memory constrained
+- Use subsets for testing
+- Check NeuPrint server response time
 
 ### Debug Mode
 
-Enable detailed troubleshooting:
+Enable detailed logging:
 
-**Debug Mode Setup**: Set `NEUVIEW_DEBUG=1` and `NEUVIEW_PROFILE=1`, then run `pixi run neuview --verbose generate -n Dm4`
-
-This provides:
-- Detailed operation logging
-- Performance timing information
-- Database query details
-- Cache operation tracking
-- Memory usage statistics
+```bash
+# Verbose output
+pixi run neuview build --verbose
 
-### Getting Help
+# Or set environment variable
+export NEUVIEW_LOG_LEVEL=DEBUG
+pixi run neuview build
+```
 
-1. **Check built-in help**: `pixi run neuview --help`
-2. **Test connection**: `pixi run neuview test-connection`
-3. **Review configuration**: Verify your `config.yaml`
-4. **Check cache**: Check `output/.cache/` directory for cached files
-5. **Use verbose mode**: Add `--verbose` to any command
-6. **Check logs**: Look for error messages in console output
+Check log output for:
+- Data fetching progress
+- Cache hit/miss information
+- Template rendering steps
+- Error stack traces
 
 ### Browser Compatibility
 
-**Recommended Browsers**:
-- Chrome 90+ (recommended for best performance)
+**Recommended browsers:**
+- Chrome/Chromium 90+
 - Firefox 88+
 - Safari 14+
 - Edge 90+
 
-**Required Features**:
-- JavaScript enabled
-- SVG support for visualizations
-- CSS3 support for responsive design
+**Known issues:**
+- IE 11: Not supported
+- Older browsers: May lack ES6 support
+- Mobile browsers: Limited Neuroglancer support
+
+**JavaScript requirements:**
+- ES6 features (async/await, fetch, promises)
+- localStorage for preferences
+- Dynamic script loading for search fallback
 
-**Mobile Support**:
-- Responsive design works on tablets and phones
-- Touch-friendly interface elements
-- Optimized for smaller screens
+### Getting Help
+
+**Before reporting issues:**
+1. Check this guide's troubleshooting section
+2. Run with `--verbose` flag
+3. Check browser console for errors
+4. Verify configuration file syntax
+
+**Information to include:**
+- neuView version
+- Dataset name and version
+- Error messages (full stack trace)
+- Configuration file (without tokens)
+- Browser and version
 
 ## Reference
 
 ### File Organization
 
-**Generated Output Structure**:
-- **Main files**: `index.html` (navigation/search), `types.html` (filterable list), `help.html` (documentation)
-- **Individual pages**: `types/` directory with hemisphere-specific pages (e.g., `Dm4.html`, `Dm4_L.html`, `Dm4_R.html`)
-- **Visualizations**: `eyemaps/` directory with region-specific spatial images
-- **Assets**: `static/` directory containing CSS, JavaScript, and image resources
-- **System files**: `.log/` (citation tracking, rotation backups), `.cache/` (performance optimization)
+```
+output/
+├── index.html              # Landing page with search
+├── types.html              # Neuron type listing
+├── help.html               # Help documentation
+├── data/
+│   ├── neurons.json        # Search data (JSON format)
+│   └── neurons.js          # Search data (JS fallback)
+├── types/
+│   ├── Tm3.html           # Individual neuron pages
+│   ├── Tm3_L.html         # Left hemisphere
+│   └── Tm3_R.html         # Right hemisphere
+└── static/
+    ├── js/
+    │   └── neuron-search.js  # Search functionality
+    ├── css/
+    │   └── *.css             # Stylesheets
+    └── icons/
+        └── *.svg             # Icons
+```
 
 ### Configuration Reference
 
-**Complete Configuration Structure** - See `config.yaml` for full examples:
-- **neuprint**: Server, dataset, and token configuration
-- **output**: Directory settings
-- **html**: Title prefix, GitHub/YouTube links, and analytics settings (including Fathom analytics)
-- **cache**: Performance caching configuration (TTL, memory limits, directories)
-- **visualization**: Hexagon size, spacing, and color palette settings
-- **neuroglancer**: Base URL configuration for Neuroglancer integration
-- **discovery**: Auto-discovery settings (max_types, type_filter, exclude_types, include_only, randomize)
+**Complete config.yaml example:**
 
-- **subsets**: Predefined sets of neuron types for validation and testing purposes
+```yaml
+neuprint:
+  server: neuprint.janelia.org
+  dataset: hemibrain:v1.2.1
 
-#### HTML Configuration
+html:
+  title_prefix: "Hemibrain"
+  github_repo: "https://github.com/your-org/your-repo"
+  youtube_channel: "https://youtube.com/@yourchannel"
+  fathom_id: "YOUR_FATHOM_ID"  # Optional analytics
 
-The `html` section controls website appearance and integrations:
+output:
+  directory: "output"
+  clean_before_build: false
 
-```yaml
-html:
-  title_prefix: "Male CNS"                    # Prefix for page titles
-  github_repo: "https://github.com/..."       # Optional GitHub repository link
-  youtube_channel: "https://www.youtube.com/..." # Optional YouTube channel link
-  fathom_id: "YOUR_FATHOM_SITE_ID"           # Optional Fathom analytics site ID
-```
+performance:
+  max_workers: 4
+  cache_enabled: true
+  parallel_generation: true
 
-**Analytics Integration**:
-- **Fathom Analytics**: Add your Fathom site ID to enable privacy-focused analytics
-- The analytics script is automatically included on all generated pages when configured
-- No additional setup required - just uncomment and set your site ID
+templates:
+  minify_html: true
+  minify_js: false
+  minify_css: false
 
-### Command Reference
+discovery:
+  max_types: 100
+  randomize: false
+  exclude_types:
+    - "test_type"
+    - "incomplete_type"
 
-Available commands include `generate` for creating neuron type pages, `create-list` for generating index pages, `fill-queue` for creating queue entries, `pop` for processing queue files, `inspect` for examining neuron types, and `test-connection` for verifying NeuPrint access. All commands are run with the `pixi run neuview` prefix.
+subsets:
+  small:
+    neuron_types:
+      - "Tm3"
+      - "Mi1"
+    generate_index: true
+```
 
-### Performance Tips
+### Environment Variables
 
-1. **Use Caching**: Cache provides up to 97.9% speed improvement on subsequent runs
-2. **Process in Batches**: Use queue system for multiple neuron types
-3. **Clean Cache Periodically**: Remove old cache files with `rm -rf output/.cache/` when needed
-4. **Monitor Progress**: Use verbose mode for long-running operations
-5. **Optimize Configuration**: Adjust cache settings based on available memory
+- `NEUPRINT_APPLICATION_CREDENTIALS` - NeuPrint auth token (required)
+- `NEUVIEW_CONFIG_PATH` - Custom config file path
+- `NEUVIEW_CACHE_DIR` - Custom cache directory
+- `NEUVIEW_LOG_LEVEL` - Logging level (DEBUG, INFO, WARNING, ERROR)
+- `NEUVIEW_OUTPUT_DIR` - Override output directory
 
-### Data Citation
+### Performance Tips
 
-When using neuView-generated data in publications:
+**For large datasets:**
+- Enable caching (default)
+- Use parallel generation
+- Increase max_workers if you have CPU cores
+- Generate subsets first for testing
 
-**Required Citations**:
-1. **Original neuPrint database** and dataset version
-2. **neuView version** used for generation
-3. **Generation date** of the catalog
-4. **Specific filtering** or configuration applied
+**For faster iterations:**
+- Don't clear cache unless necessary
+- Use `--types` flag to regenerate specific pages
+- Disable HTML minification during development
+- Use subsets for testing changes
 
-**Example Citation**:
-**Citation Example**: "Neuron data analysis generated using neuView from neuPrint database (neuprint.janelia.org), dataset: hemibrain v1.2.1, catalog generated: 2024-01-15. Connectivity data from Scheffer et al. (2020). ROI analysis performed using standard neuView configuration with automatic hemisphere detection."
+**Cache management:**
+- Cache stored in `.neuview_cache/` by default
+- Safe to delete - will regenerate from NeuPrint
+- Old cache automatically cleaned
+- No manual maintenance needed
 
-### Environment Variables
+### Data Citation
 
-| Variable | Description | Example |
-|----------|-------------|---------|
-| `NEUPRINT_APPLICATION_CREDENTIALS` | NeuPrint API token | `your-token-string` |
-| `NEUVIEW_CONFIG_PATH` | Custom config file path | `/path/to/config.yaml` |
-| `NEUVIEW_CACHE_DIR` | Cache directory override | `/tmp/neuview_cache` |
-| `NEUVIEW_DEBUG` | Enable debug logging | `1` or `true` |
-| `NEUVIEW_PROFILE` | Enable performance profiling | `1` or `true` |
+When using neuView-generated websites, cite:
 
-### Keyboard Shortcuts
+1. **The dataset:** Check NeuPrint for proper citation
+2. **neuView tool:** (If publishing using neuView)
+3. **Original data sources:** Listed in connectivity tables
 
-When viewing generated pages:
+**Example citation:**
+```
+Neuron visualizations generated using neuView (https://github.com/your-org/neuview).
+Data from NeuPrint (https://neuprint.janelia.org), 
+Hemibrain dataset v1.2.1 (Scheffer et al., 2020).
+```
 
-| Shortcut | Action |
-|----------|--------|
-| `Ctrl/Cmd + F` | Search within page |
-| `Ctrl/Cmd + Shift + F` | Search across all tables |
-| `Escape` | Clear search filters |
-| `Tab` | Navigate between interactive elements |
-| `Enter` | Activate focused element |
+### Keyboard Shortcuts
 
-### Dataset-Specific Notes
+**Search:**
+- Type to activate
+- ↑/↓ arrows to navigate
+- Enter to select
+- Esc to close
 
-**Hemibrain Dataset**:
-- Most complete connectivity data
-- Full ROI visualization support
-- Standard soma side classifications
-- Comprehensive neurotransmitter predictions
-
-**CNS Dataset**:
-- Focus on central nervous system
-- Complete feature support
-- Standard data format
-- Good performance characteristics
-
-**Optic-Lobe Dataset**:
-- Specialized for visual system neurons
-- Full neuroglancer integration
-- Rich connectivity analysis
-- Optimized eyemap visualizations
-
-**FAFB (FlyWire) Dataset**:
-- Largest dataset with ongoing updates
-- Limited ROI visualization (by design)
-- Special soma side handling (CENTER vs MIDDLE)
-- Automated template selection
+**Browser:**
+- Ctrl/Cmd + F: Find in page
+- Ctrl/Cmd + Click: Open link in new tab
 
 ### Frequently Asked Questions
 
-**Q: Why don't I see ROI checkboxes for my FAFB dataset?**
-A: This is intentional. FAFB neuroglancer data doesn't support reliable ROI visualization, so checkboxes are hidden to prevent confusion. ROI statistics are still accurate and displayed.
-
-**Q: How do I generate pages for all neuron types?**
-A: Use `pixi run neuview fill-queue --all` to create queue entries for all neuron types, then process them with `pixi run neuview pop` repeatedly, or use the queue system for more control.
+**Q: Can I use this offline?**
+A: Yes! Open `output/index.html` directly. Search works via JavaScript fallback.
 
-**Q: Can I customize the HTML output?**
-A: Yes, you can provide custom templates by modifying the built-in template files in the templates directory.
+**Q: How do I share the website?**
+A: Upload the `output/` folder to any web server or GitHub Pages.
 
-**Q: How do I improve generation speed?**
-A: Enable caching (default), use batch processing with queues, and ensure adequate memory allocation. Cache provides significant performance improvements.
+**Q: Can I customize the styling?**
+A: Yes. Edit templates in `templates/` and CSS in `static/css/`.
 
-**Q: What browsers are supported?**
-A: Modern browsers (Chrome, Firefox, Safari, Edge) with JavaScript enabled. Chrome is recommended for optimal performance.
+**Q: How often should I rebuild?**
+A: When dataset updates, or when you want to include new neuron types.
 
-**Q: How do I export data from the generated pages?**
-A: Use the export functions in data tables, or enable JSON export in configuration to generate machine-readable data alongside HTML.
+**Q: Does search work offline?**
+A: Yes. It uses `neurons.js` fallback for local file access.
 
-**Q: Have there been recent improvements to ROI functionality?**
-A: Yes! Recent updates include: (1) Fixed ROI ID collision issues between brain and VNC datasets, (2) Improved ROI checkbox accuracy and reliability, (3) Dynamic ROI data fetching for always up-to-date information, (4) Enhanced error handling and caching. These improvements ensure ROI selections work correctly and consistently across all datasets.
+**Q: Can I add custom neuron types?**
+A: Currently only NeuPrint datasets are supported. Manual additions require code changes.
 
-**Q: How does automatic page generation work?**
-A: neuView analyzes your neuron data and automatically creates the appropriate pages:
-- For neuron types with multiple hemispheres (L/R/M): Creates individual hemisphere pages AND a combined page
-- For neuron types with only one hemisphere: Creates only that hemisphere's page (no combined page)
-- No soma-side specification needed - the system detects and generates optimal page sets automatically
+**Q: How do I update to a new dataset version?**
+A: Update `config.yaml` with new dataset name, clear cache, rebuild.
 
-**Q: Can I still generate hemisphere-specific pages?**
-A: Yes, but it's automatic! neuView will generate hemisphere-specific pages (e.g., Dm4_L.html, Dm4_R.html) whenever hemisphere-specific data exists. The system automatically detects available hemispheres and creates appropriate pages.
+**Q: Can external services access the neuron data?**
+A: Yes! The `data/neurons.json` file is a standard JSON API endpoint.
 
----
+**Q: What's the difference between neurons.json and neurons.js?**
+A: Same data, different formats. JSON for web servers/APIs, JS for local file access.
 
-This user guide provides comprehensive coverage of neuView's features and functionality. For technical implementation details, see the [Developer Guide](developer-guide.md).
+**Q: Why do some neurons have L/R pages and others don't?**
+A: Automatically determined by soma distribution. Bilateral neurons get separate pages.
\ No newline at end of file
diff --git a/src/neuview/services/index_generator_service.py b/src/neuview/services/index_generator_service.py
index fa55e810..0a994381 100644
--- a/src/neuview/services/index_generator_service.py
+++ b/src/neuview/services/index_generator_service.py
@@ -5,11 +5,11 @@
 README documentation, help pages, and landing pages.
 """
 
-import logging
 import json
-from pathlib import Path
+import logging
 from datetime import datetime
-from typing import List, Dict, Any, Optional
+from pathlib import Path
+from typing import Any, Dict, List, Optional
 
 logger = logging.getLogger(__name__)
 
@@ -23,43 +23,73 @@ def __init__(self, page_generator):
     async def generate_neuron_search_js(
         self, output_dir: Path, neuron_data: List[Dict[str, Any]], generation_time
     ) -> Optional[str]:
-        """Generate the neuron-search.js file with embedded neuron types data."""
+        """
+        Generate neuron search files: neuron-search.js, neurons.json, and neurons.js fallback.
+
+        Returns:
+            Path to the generated neuron-search.js file, or None if generation failed
+        """
         # Prepare neuron types data for JavaScript
         neuron_types_for_js = []
 
         for neuron in neuron_data:
+            # Helper function to remove "types/" prefix from URLs
+            def strip_types_prefix(url):
+                if url and url.startswith("types/"):
+                    return url[6:]  # Remove "types/" prefix
+                return url
+
             # Create an entry with the neuron name and available URLs
             neuron_entry = {
                 "name": neuron["name"],
                 "urls": {},
-                "synonyms": neuron.get("synonyms", ""),
-                "flywire_types": neuron.get("flywire_types", ""),
             }
 
-            # Add available URLs for this neuron type
+            # Add available URLs for this neuron type (without "types/" prefix)
             if neuron.get("combined_url") or neuron.get("both_url"):
-                combined_url = neuron.get("combined_url")
-                neuron_entry["urls"]["combined"] = combined_url
+                combined_url = neuron.get("combined_url") or neuron.get("both_url")
+                neuron_entry["urls"]["combined"] = strip_types_prefix(combined_url)
             if neuron["left_url"]:
-                neuron_entry["urls"]["left"] = neuron["left_url"]
+                neuron_entry["urls"]["left"] = strip_types_prefix(neuron["left_url"])
             if neuron["right_url"]:
-                neuron_entry["urls"]["right"] = neuron["right_url"]
+                neuron_entry["urls"]["right"] = strip_types_prefix(neuron["right_url"])
             if neuron["middle_url"]:
-                neuron_entry["urls"]["middle"] = neuron["middle_url"]
-
-            # Set primary URL (prefer 'combined' if available, otherwise first available)
-            if neuron.get("combined_url") or neuron.get("both_url"):
-                neuron_entry["primary_url"] = neuron.get("combined_url") or neuron.get(
-                    "both_url"
+                neuron_entry["urls"]["middle"] = strip_types_prefix(
+                    neuron["middle_url"]
                 )
-            elif neuron["left_url"]:
-                neuron_entry["primary_url"] = neuron["left_url"]
-            elif neuron["right_url"]:
-                neuron_entry["primary_url"] = neuron["right_url"]
-            elif neuron["middle_url"]:
-                neuron_entry["primary_url"] = neuron["middle_url"]
-            else:
-                neuron_entry["primary_url"] = f"{neuron['name']}.html"  # fallback
+
+            # Build types dictionary with flywire and synonyms
+            types_dict = {}
+
+            # Add FlyWire types
+            if neuron.get("flywire_types"):
+                flywire_value = neuron.get("flywire_types")
+                # Split by comma if multiple values
+                if isinstance(flywire_value, str):
+                    flywire_list = [
+                        t.strip() for t in flywire_value.split(",") if t.strip()
+                    ]
+                    if flywire_list:
+                        types_dict["flywire"] = flywire_list
+                elif isinstance(flywire_value, list):
+                    types_dict["flywire"] = flywire_value
+
+            # Add synonyms
+            if neuron.get("synonyms"):
+                synonyms_value = neuron.get("synonyms")
+                # Parse synonyms (format: "Author Year: name; Author Year: name")
+                if isinstance(synonyms_value, str):
+                    synonym_list = [
+                        s.strip() for s in synonyms_value.split(";") if s.strip()
+                    ]
+                    if synonym_list:
+                        types_dict["synonyms"] = synonym_list
+                elif isinstance(synonyms_value, list):
+                    types_dict["synonyms"] = synonyms_value
+
+            # Only add types field if it has content
+            if types_dict:
+                neuron_entry["types"] = types_dict
 
             neuron_types_for_js.append(neuron_entry)
 
@@ -69,30 +99,88 @@ async def generate_neuron_search_js(
         # Extract just the names for the simple search functionality
         neuron_names = [neuron["name"] for neuron in neuron_types_for_js]
 
-        # Prepare template data
-        js_template_data = {
-            "neuron_types_json": json.dumps(neuron_names, indent=2),
-            "neuron_types_data_json": json.dumps(neuron_types_for_js, indent=2),
-            "generation_timestamp": generation_time.strftime("%Y-%m-%d %H:%M:%S")
+        # Prepare timestamp
+        timestamp = (
+            generation_time.strftime("%Y-%m-%d %H:%M:%S")
             if generation_time
-            else datetime.now().strftime("%Y-%m-%d %H:%M:%S"),
-            "neuron_types": neuron_types_for_js,
+            else datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+        )
+
+        # Prepare data structure for JSON and JS fallback
+        data_structure = {
+            "names": neuron_names,
+            "neurons": neuron_types_for_js,
+            "metadata": {
+                "generated": timestamp,
+                "total_types": len(neuron_names),
+                "version": "2.0",
+            },
         }
 
-        # Load and render the neuron-search.js template
-        js_template = self.page_generator.env.get_template(
-            "static/js/neuron-search.js.template.jinja"
-        )
-        js_content = js_template.render(js_template_data)
+        # Ensure data directory exists
+        data_dir = output_dir / "data"
+        data_dir.mkdir(parents=True, exist_ok=True)
 
-        # Ensure static/js directory exists
-        js_dir = output_dir / "static" / "js"
-        js_dir.mkdir(parents=True, exist_ok=True)
+        # 1. Generate neurons.json (for external services & web servers)
+        try:
+            json_path = data_dir / "neurons.json"
+            json_path.write_text(
+                json.dumps(data_structure, separators=(",", ":"), ensure_ascii=False),
+                encoding="utf-8",
+            )
+            logger.info(f"Generated neurons.json at {json_path}")
+        except Exception as e:
+            logger.error(f"Failed to generate neurons.json: {e}")
 
-        # Write the neuron-search.js file
-        js_path = js_dir / "neuron-search.js"
-        js_path.write_text(js_content, encoding="utf-8")
-        return str(js_path)
+        # 2. Generate neurons.js (fallback for CORS-restricted environments)
+        try:
+            js_fallback_template = self.page_generator.env.get_template(
+                "data/neurons.js.template.jinja"
+            )
+            js_fallback_content = js_fallback_template.render(
+                {
+                    "neuron_data": data_structure,
+                    "neuron_data_json": json.dumps(
+                        data_structure, indent=2, ensure_ascii=False
+                    ),
+                    "generation_timestamp": timestamp,
+                }
+            )
+
+            js_fallback_path = data_dir / "neurons.js"
+            js_fallback_path.write_text(js_fallback_content, encoding="utf-8")
+            logger.info(f"Generated neurons.js fallback at {js_fallback_path}")
+        except Exception as e:
+            logger.error(f"Failed to generate neurons.js: {e}")
+
+        # 3. Generate neuron-search.js (search logic only, no embedded data)
+        try:
+            # Prepare template data
+            js_template_data = {
+                "neuron_types_json": json.dumps(neuron_names, indent=2),
+                "neuron_types_data_json": json.dumps(neuron_types_for_js, indent=2),
+                "generation_timestamp": timestamp,
+                "neuron_types": neuron_types_for_js,
+            }
+
+            # Load and render the neuron-search.js template
+            js_template = self.page_generator.env.get_template(
+                "static/js/neuron-search.js.template.jinja"
+            )
+            js_content = js_template.render(js_template_data)
+
+            # Ensure static/js directory exists
+            js_dir = output_dir / "static" / "js"
+            js_dir.mkdir(parents=True, exist_ok=True)
+
+            # Write the neuron-search.js file
+            js_path = js_dir / "neuron-search.js"
+            js_path.write_text(js_content, encoding="utf-8")
+            logger.info(f"Generated neuron-search.js at {js_path}")
+            return str(js_path)
+        except Exception as e:
+            logger.error(f"Failed to generate neuron-search.js: {e}")
+            return None
 
     async def generate_readme(
         self, output_dir: Path, template_data: Dict[str, Any]
diff --git a/templates/data/neurons.js.template.jinja b/templates/data/neurons.js.template.jinja
new file mode 100644
index 00000000..af29a770
--- /dev/null
+++ b/templates/data/neurons.js.template.jinja
@@ -0,0 +1,26 @@
+/**
+ * Neuron Data - Fallback for CORS-restricted environments
+ *
+ * This file is loaded only when neurons.json cannot be fetched
+ * (e.g., when opening HTML files via file:// protocol)
+ *
+ * This file is generated at build time with embedded neuron data.
+ * Do not edit manually - it will be overwritten during the build process.
+ *
+ * Generated on: {{ generation_timestamp }}
+ * Total neuron types: {{ neuron_data.names|length }}
+ */
+
+(function() {
+  'use strict';
+
+  const neuronData = {{ neuron_data_json|safe }};
+
+  // If callback exists, call it immediately
+  if (typeof window.neuronDataCallback === 'function') {
+    window.neuronDataCallback(neuronData);
+  } else {
+    // Otherwise store for later retrieval
+    window.NEURON_DATA_FALLBACK = neuronData;
+  }
+})();
diff --git a/templates/index.html.jinja b/templates/index.html.jinja
index aec93b28..596c9dc5 100644
--- a/templates/index.html.jinja
+++ b/templates/index.html.jinja
@@ -290,44 +290,123 @@
 
 <script>
 {# Quick search functionality that mirrors the header search behavior #}
-document.addEventListener('DOMContentLoaded', function() {
+document.addEventListener('DOMContentLoaded', async function() {
     const landingSearch = document.getElementById('landing-search');
 
     if (!landingSearch) return;
 
-    {#  Wait for NEURON_DATA to be available #}
-    setTimeout(() => {
-        if (typeof NEURON_DATA !== 'undefined') {
-            new QuickNeuronSearch('landing-search');
-        }
-    }, 100);
+    {# Wait for the main neuron search to load data, then initialize quick search #}
+    if (window.neuronSearch) {
+        {# Use data from main search if already loaded #}
+        await window.neuronSearch.init();
+        const quickSearch = new QuickNeuronSearch('landing-search');
+        await quickSearch.init();
+    } else {
+        {# Initialize quick search independently #}
+        const quickSearch = new QuickNeuronSearch('landing-search');
+        await quickSearch.init();
+    }
 });
 
 class QuickNeuronSearch {
     constructor(inputId) {
         this.inputElement = document.getElementById(inputId);
-        this.neuronTypes = typeof NEURON_TYPES_DATA !== 'undefined' ? NEURON_TYPES_DATA : [];
-        this.neuronData = typeof NEURON_DATA !== 'undefined' ? NEURON_DATA : [];
+        this.neuronTypes = [];
+        this.neuronData = [];
         this.filteredTypes = [];
         this.currentIndex = -1;
         this.isDropdownVisible = false;
         this.clickingDropdown = false;
+        this.isReady = false;
 
         {# Create autocomplete dropdown #}
         this.dropdown = this.createDropdown();
-
-        {# Initialize the search functionality #}
-        this.init();
     }
 
-    init() {
+    async init() {
         if (!this.inputElement) {
             return;
         }
 
+        {# Load neuron data #}
+        const data = await this.loadNeuronData();
+        this.neuronTypes = data.names || [];
+        this.neuronData = data.neurons || [];
+        this.isReady = true;
+
         this.setupEventListeners();
     }
 
+    async loadNeuronData() {
+        {# Try to use data from main neuron search if available #}
+        if (window.neuronSearch && window.neuronSearch.isReady) {
+            return {
+                names: window.neuronSearch.neuronTypes,
+                neurons: window.neuronSearch.neuronData
+            };
+        }
+
+        {# Otherwise load independently #}
+        try {
+            const response = await fetch('data/neurons.json');
+            if (!response.ok) throw new Error('JSON load failed');
+            const data = await response.json();
+            return {
+                names: data.names || [],
+                neurons: data.neurons || []
+            };
+        } catch (jsonError) {
+            {# Fall back to JS file #}
+            try {
+                return await this.loadFromJSFallback();
+            } catch (jsError) {
+                console.error('Failed to load neuron data for quick search');
+                return { names: [], neurons: [] };
+            }
+        }
+    }
+
+    loadFromJSFallback() {
+        return new Promise((resolve, reject) => {
+            window.quickSearchDataCallback = (data) => {
+                delete window.quickSearchDataCallback;
+                resolve({
+                    names: data.names || [],
+                    neurons: data.neurons || []
+                });
+            };
+
+            const script = document.createElement('script');
+            script.src = 'data/neurons.js';
+            script.async = true;
+
+            script.onload = () => {
+                if (window.NEURON_DATA_FALLBACK && window.quickSearchDataCallback) {
+                    const data = window.NEURON_DATA_FALLBACK;
+                    delete window.NEURON_DATA_FALLBACK;
+                    delete window.quickSearchDataCallback;
+                    resolve({
+                        names: data.names || [],
+                        neurons: data.neurons || []
+                    });
+                }
+                setTimeout(() => {
+                    if (window.quickSearchDataCallback) {
+                        delete window.quickSearchDataCallback;
+                        reject(new Error('Callback not invoked'));
+                    }
+                }, 100);
+            };
+
+            script.onerror = () => {
+                delete window.quickSearchDataCallback;
+                reject(new Error('Failed to load neurons.js'));
+            };
+
+            document.head.appendChild(script);
+        });
+    }
+
     createDropdown() {
         const dropdown = document.createElement("div");
         dropdown.className = "neuron-search-dropdown";
@@ -404,19 +483,18 @@ class QuickNeuronSearch {
 
             {# Search in neuron data for synonyms and flywire types #}
             const neuronEntry = this.neuronData.find(entry => entry.name === type);
-            if (neuronEntry) {
+            if (neuronEntry && neuronEntry.types) {
                 {# Search in synonyms #}
-                if (neuronEntry.synonyms) {
-                    const synonymsLower = neuronEntry.synonyms.toLowerCase();
-                    if (synonymsLower.includes(query)) {
-                        return true;
-                    }
-                    {# Also search in just the part after colon (the actual name) #}
-                    const synonyms = synonymsLower.split(';').map(s => s.trim());
-                    for (const synonym of synonyms) {
-                        const colonIndex = synonym.indexOf(':');
+                if (neuronEntry.types.synonyms && Array.isArray(neuronEntry.types.synonyms)) {
+                    for (const synonym of neuronEntry.types.synonyms) {
+                        const synonymLower = synonym.toLowerCase();
+                        if (synonymLower.includes(query)) {
+                            return true;
+                        }
+                        {# Also search in just the part after colon (the actual name) #}
+                        const colonIndex = synonymLower.indexOf(':');
                         if (colonIndex !== -1) {
-                            const nameAfterColon = synonym.substring(colonIndex + 1).trim();
+                            const nameAfterColon = synonymLower.substring(colonIndex + 1).trim();
                             if (nameAfterColon.includes(query)) {
                                 return true;
                             }
@@ -425,8 +503,12 @@ class QuickNeuronSearch {
                 }
 
                 {# Search in flywire types #}
-                if (neuronEntry.flywire_types && neuronEntry.flywire_types.toLowerCase().includes(query)) {
-                    return true;
+                if (neuronEntry.types.flywire && Array.isArray(neuronEntry.types.flywire)) {
+                    for (const flywireType of neuronEntry.types.flywire) {
+                        if (flywireType.toLowerCase().includes(query)) {
+                            return true;
+                        }
+                    }
                 }
             }
 
@@ -583,7 +665,7 @@ class QuickNeuronSearch {
                         sideLink.addEventListener('mousedown', (e) => {
                             e.preventDefault();
                             e.stopPropagation();
-                            window.location.href = neuronEntry.urls[sideInfo.side];
+                            window.location.href = 'types/' + neuronEntry.urls[sideInfo.side];
                         });
 
                         {# Keep click handler for backup #}
@@ -668,12 +750,12 @@ class QuickNeuronSearch {
     navigateToSomaSide(neuronType, side) {
         const neuronEntry = this.neuronData.find(entry => entry.name === neuronType);
 
-        if (neuronEntry && neuronEntry.urls[side]) {
+        if (neuronEntry && neuronEntry.urls && neuronEntry.urls[side]) {
             {# Close dropdown and update input #}
             this.inputElement.value = neuronType;
             this.hideDropdown();
-            {# Navigate to the specific side page #}
-            window.location.href = neuronEntry.urls[side];
+            {# Navigate to the specific side page - add types/ prefix #}
+            window.location.href = 'types/' + neuronEntry.urls[side];
         } else {
             {# Fallback to primary URL #}
             this.navigateToNeuronType(neuronType);
@@ -684,9 +766,15 @@ class QuickNeuronSearch {
         {# Find the neuron data entry for this type #}
         const neuronEntry = this.neuronData.find(entry => entry.name === neuronType);
 
-        if (neuronEntry && neuronEntry.primary_url) {
-            {# Use the primary URL from the data #}
-            window.location.href = neuronEntry.primary_url;
+        if (neuronEntry && neuronEntry.urls) {
+            {# Get primary URL (prefer combined, then left, then right, then middle) #}
+            const primaryUrl = neuronEntry.urls.combined ||
+                              neuronEntry.urls.left ||
+                              neuronEntry.urls.right ||
+                              neuronEntry.urls.middle ||
+                              `${neuronType}.html`;
+            {# Navigate with types/ prefix #}
+            window.location.href = 'types/' + primaryUrl;
         } else {
             {# Fallback to the old detection method #}
             this.navigateToNeuronTypeWithDetection(neuronType);
diff --git a/templates/static/js/neuron-search.js.template.jinja b/templates/static/js/neuron-search.js.template.jinja
index 2ce14872..3a6554f6 100644
--- a/templates/static/js/neuron-search.js.template.jinja
+++ b/templates/static/js/neuron-search.js.template.jinja
@@ -2,37 +2,36 @@
  * Neuron Type Search and Autocomplete
  * Provides client-side search functionality for neuron types
  *
- * This file is generated at build time with embedded neuron types data.
+ * This file is generated at build time.
  * Do not edit manually - it will be overwritten during the build process.
  *
  * Generated on: {{ generation_timestamp }}
  * Total neuron types: {{ neuron_types|length }}
  */
 
-// Neuron types data embedded at build time
-const NEURON_TYPES_DATA = {{ neuron_types_json|safe }};
-
-// Detailed neuron data with URLs for navigation
-const NEURON_DATA = {{ neuron_types_data_json|safe }};
-
 class NeuronSearch {
   constructor(inputId = "menulines") {
     this.inputElement = document.getElementById(inputId);
-    this.neuronTypes = NEURON_TYPES_DATA;
-    this.neuronData = NEURON_DATA;
+    this.neuronTypes = [];
+    this.neuronData = [];
     this.filteredTypes = [];
     this.currentIndex = -1;
     this.isDropdownVisible = false;
     this.clickingDropdown = false;
+    this.isReady = false;
+    this.dataSource = null;
 
     // Detect if we're on a neuron page (inside types folder) based on current path
     this.isNeuronPage = this.detectNeuronPageContext();
 
+    // Set path prefix for loading resources
+    this.pathPrefix = this.isNeuronPage ? '../' : '';
+
+    // Set URL prefix for neuron pages
+    this.urlPrefix = this.isNeuronPage ? '' : 'types/';
+
     // Create autocomplete dropdown
     this.dropdown = this.createDropdown();
-
-    // Initialize the search functionality
-    this.init();
   }
 
   /**
@@ -60,16 +59,135 @@ class NeuronSearch {
   /**
    * Initialize the search functionality
    */
-  init() {
+  async init() {
     if (!this.inputElement) {
       console.warn("Search input element not found");
       return;
     }
 
+    // Load neuron data
+    const data = await this.loadNeuronData();
+    this.neuronTypes = data.names || [];
+    this.neuronData = data.neurons || [];
+    this.isReady = true;
+
     // Set up event listeners
     this.setupEventListeners();
 
-    console.log(`Loaded ${this.neuronTypes.length} neuron types for search`);
+    console.log(
+      `Loaded ${this.neuronTypes.length} neuron types (source: ${this.dataSource})`
+    );
+  }
+
+  /**
+   * Load neuron data with fallback mechanism
+   * Try JSON first, fall back to JS file if that fails
+   */
+  async loadNeuronData() {
+    // Try loading from JSON first
+    try {
+      const data = await this.loadFromJSON();
+      this.dataSource = 'json';
+      return data;
+    } catch (jsonError) {
+      console.warn('JSON loading failed, trying fallback JS file:', jsonError.message);
+
+      // Fall back to loading JS file
+      try {
+        const data = await this.loadFromJSFallback();
+        this.dataSource = 'js-fallback';
+        return data;
+      } catch (jsError) {
+        console.error('Both JSON and JS fallback loading failed:', jsError.message);
+        this.dataSource = 'none';
+
+        // Return empty data as last resort
+        return {
+          types: [],
+          details: [],
+          metadata: { error: true }
+        };
+      }
+    }
+  }
+
+  /**
+   * Load data from JSON file (preferred method)
+   */
+  async loadFromJSON() {
+    const url = `${this.pathPrefix}data/neurons.json`;
+    const response = await fetch(url);
+
+    if (!response.ok) {
+      throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+    }
+
+    const data = await response.json();
+    return {
+      names: data.names || [],
+      neurons: data.neurons || []
+    };
+  }
+
+  /**
+   * Load data from JS fallback file (for CORS-restricted environments)
+   * Uses dynamic script loading which bypasses CORS
+   */
+  loadFromJSFallback() {
+    return new Promise((resolve, reject) => {
+      // Set up callback for the JS file to call
+      window.neuronDataCallback = (data) => {
+        delete window.neuronDataCallback; // Clean up
+        resolve({
+          names: data.names || [],
+          neurons: data.neurons || []
+        });
+      };
+
+      // Create script element
+      const script = document.createElement('script');
+      script.src = `${this.pathPrefix}data/neurons.js`;
+      script.async = true;
+
+      // Handle successful load
+      script.onload = () => {
+        // If data was already set globally instead of using callback
+        if (window.NEURON_DATA_FALLBACK && window.neuronDataCallback) {
+          const data = window.NEURON_DATA_FALLBACK;
+          delete window.NEURON_DATA_FALLBACK; // Clean up
+          delete window.neuronDataCallback;
+          resolve({
+            names: data.names || [],
+            neurons: data.neurons || []
+          });
+        }
+        // If callback hasn't been called within 100ms, something went wrong
+        setTimeout(() => {
+          if (window.neuronDataCallback) {
+            delete window.neuronDataCallback;
+            reject(new Error('JS fallback loaded but callback not invoked'));
+          }
+        }, 100);
+      };
+
+      // Handle load error
+      script.onerror = () => {
+        delete window.neuronDataCallback;
+        reject(new Error('Failed to load neurons.js fallback file'));
+      };
+
+      // Add script to document
+      document.head.appendChild(script);
+
+      // Timeout after 5 seconds
+      setTimeout(() => {
+        if (window.neuronDataCallback) {
+          delete window.neuronDataCallback;
+          script.remove();
+          reject(new Error('Timeout loading neuron data fallback'));
+        }
+      }, 5000);
+    });
   }
 
   /**
@@ -164,22 +282,21 @@ class NeuronSearch {
         return true;
       }
 
-      // Search in synonyms and flywire types from detailed data
+      // Search in types (synonyms and flywire) from detailed data
       const neuronEntry = this.neuronData.find(entry => entry.name === type);
-      if (neuronEntry) {
+      if (neuronEntry && neuronEntry.types) {
         // Search in synonyms
-        if (neuronEntry.synonyms) {
-          const synonymsLower = neuronEntry.synonyms.toLowerCase();
-          // Search in full synonym text
-          if (synonymsLower.includes(query)) {
-            return true;
-          }
-          // Also search in just the part after colon (the actual name)
-          const synonyms = synonymsLower.split(';').map(s => s.trim());
-          for (const synonym of synonyms) {
-            const colonIndex = synonym.indexOf(':');
+        if (neuronEntry.types.synonyms && Array.isArray(neuronEntry.types.synonyms)) {
+          for (const synonym of neuronEntry.types.synonyms) {
+            const synonymLower = synonym.toLowerCase();
+            // Search in full synonym text
+            if (synonymLower.includes(query)) {
+              return true;
+            }
+            // Also search in just the part after colon (the actual name)
+            const colonIndex = synonymLower.indexOf(':');
             if (colonIndex !== -1) {
-              const nameAfterColon = synonym.substring(colonIndex + 1).trim();
+              const nameAfterColon = synonymLower.substring(colonIndex + 1).trim();
               if (nameAfterColon.includes(query)) {
                 return true;
               }
@@ -188,8 +305,12 @@ class NeuronSearch {
         }
 
         // Search in flywire types
-        if (neuronEntry.flywire_types && neuronEntry.flywire_types.toLowerCase().includes(query)) {
-          return true;
+        if (neuronEntry.types.flywire && Array.isArray(neuronEntry.types.flywire)) {
+          for (const flywireType of neuronEntry.types.flywire) {
+            if (flywireType.toLowerCase().includes(query)) {
+              return true;
+            }
+          }
         }
       }
 
@@ -439,18 +560,16 @@ class NeuronSearch {
     // Find the neuron data entry for this type
     const neuronEntry = this.neuronData.find(entry => entry.name === neuronType);
 
-    if (neuronEntry && neuronEntry.primary_url) {
-      // Adjust the URL based on current page context
-      let targetUrl = neuronEntry.primary_url;
+    if (neuronEntry && neuronEntry.urls) {
+      // Get primary URL (prefer combined, then left, then right, then middle)
+      let targetUrl = neuronEntry.urls.combined ||
+                      neuronEntry.urls.left ||
+                      neuronEntry.urls.right ||
+                      neuronEntry.urls.middle ||
+                      `${neuronType}.html`;
 
-      // If we're on a neuron page and the URL starts with 'types/', remove the prefix
-      if (this.isNeuronPage && targetUrl.startsWith('types/')) {
-        targetUrl = targetUrl.substring(6); // Remove 'types/' prefix
-      }
-      // If we're not on a neuron page and the URL doesn't start with 'types/', add the prefix
-      else if (!this.isNeuronPage && !targetUrl.startsWith('types/')) {
-        targetUrl = 'types/' + targetUrl;
-      }
+      // Add URL prefix (types/ for non-neuron pages, empty for neuron pages)
+      targetUrl = this.urlPrefix + targetUrl;
 
       window.location.href = targetUrl;
     } else {
@@ -512,22 +631,13 @@ class NeuronSearch {
   navigateToSomaSide(neuronType, side) {
     const neuronEntry = this.neuronData.find(entry => entry.name === neuronType);
 
-    if (neuronEntry && neuronEntry.urls[side]) {
+    if (neuronEntry && neuronEntry.urls && neuronEntry.urls[side]) {
       // Close dropdown and update input
       this.inputElement.value = neuronType;
       this.hideDropdown();
 
-      // Adjust the URL based on current page context
-      let targetUrl = neuronEntry.urls[side];
-
-      // If we're on a neuron page and the URL starts with 'types/', remove the prefix
-      if (this.isNeuronPage && targetUrl.startsWith('types/')) {
-        targetUrl = targetUrl.substring(6); // Remove 'types/' prefix
-      }
-      // If we're not on a neuron page and the URL doesn't start with 'types/', add the prefix
-      else if (!this.isNeuronPage && !targetUrl.startsWith('types/')) {
-        targetUrl = 'types/' + targetUrl;
-      }
+      // Add URL prefix (types/ for non-neuron pages, empty for neuron pages)
+      let targetUrl = this.urlPrefix + neuronEntry.urls[side];
 
       // Navigate to the specific side page
       window.location.href = targetUrl;
@@ -569,9 +679,12 @@ class NeuronSearch {
 }
 
 // Initialize the search functionality when the DOM is loaded
-document.addEventListener("DOMContentLoaded", () => {
+document.addEventListener("DOMContentLoaded", async () => {
   // Initialize neuron search
-  window.neuronSearch = new NeuronSearch("menulines");
+  if (document.getElementById('menulines')) {
+    window.neuronSearch = new NeuronSearch("menulines");
+    await window.neuronSearch.init();
+  }
 });
 
 // Export for module use if needed

From b01de8ec0f82f166c0958cc824adf94c0321fc3a Mon Sep 17 00:00:00 2001
From: Frank Loesche <loeschef@janelia.hhmi.org>
Date: Wed, 26 Nov 2025 16:58:44 -0500
Subject: [PATCH 2/7] cleanup filenames

---
 src/neuview/services/index_generator_service.py          | 8 +++-----
 src/neuview/services/neuron_search_service.py            | 9 +++++----
 templates/{README_template.md.jinja => README.md.jinja}  | 0
 .../data/{neurons.js.template.jinja => neurons.js.jinja} | 0
 ...n-search.js.template.jinja => neuron-search.js.jinja} | 0
 5 files changed, 8 insertions(+), 9 deletions(-)
 rename templates/{README_template.md.jinja => README.md.jinja} (100%)
 rename templates/data/{neurons.js.template.jinja => neurons.js.jinja} (100%)
 rename templates/static/js/{neuron-search.js.template.jinja => neuron-search.js.jinja} (100%)

diff --git a/src/neuview/services/index_generator_service.py b/src/neuview/services/index_generator_service.py
index 0a994381..1d7e867f 100644
--- a/src/neuview/services/index_generator_service.py
+++ b/src/neuview/services/index_generator_service.py
@@ -135,7 +135,7 @@ def strip_types_prefix(url):
         # 2. Generate neurons.js (fallback for CORS-restricted environments)
         try:
             js_fallback_template = self.page_generator.env.get_template(
-                "data/neurons.js.template.jinja"
+                "data/neurons.js.jinja"
             )
             js_fallback_content = js_fallback_template.render(
                 {
@@ -165,7 +165,7 @@ def strip_types_prefix(url):
 
             # Load and render the neuron-search.js template
             js_template = self.page_generator.env.get_template(
-                "static/js/neuron-search.js.template.jinja"
+                "static/js/neuron-search.js.jinja"
             )
             js_content = js_template.render(js_template_data)
 
@@ -188,9 +188,7 @@ async def generate_readme(
         """Generate README.md documentation for the generated website."""
         try:
             # Load the README template
-            readme_template = self.page_generator.env.get_template(
-                "README_template.md.jinja"
-            )
+            readme_template = self.page_generator.env.get_template("README.md.jinja")
             readme_content = readme_template.render(template_data)
 
             # Write the README.md file
diff --git a/src/neuview/services/neuron_search_service.py b/src/neuview/services/neuron_search_service.py
index 92147714..99709e3d 100644
--- a/src/neuview/services/neuron_search_service.py
+++ b/src/neuview/services/neuron_search_service.py
@@ -5,11 +5,12 @@
 neuron type data for client-side search functionality.
 """
 
-from pathlib import Path
 import json
 import logging
 from datetime import datetime
-from typing import List, Optional, Dict, Any
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
 from jinja2 import Environment
 
 logger = logging.getLogger(__name__)
@@ -65,7 +66,7 @@ def generate_neuron_search_js(self, force_regenerate: bool = False) -> bool:
             neuron_types = self._get_neuron_types()
 
             # Load the template
-            template_path = "static/js/neuron-search.js.template.jinja"
+            template_path = "static/js/neuron-search.js.jinja"
 
             if not self._template_exists(template_path):
                 logger.warning(f"Neuron search template not found: {template_path}")
@@ -263,7 +264,7 @@ def generate_with_custom_data(
                 context.update(template_vars)
 
             # Load and render template
-            template_path = "static/js/neuron-search.js.template.jinja"
+            template_path = "static/js/neuron-search.js.jinja"
 
             if not self._template_exists(template_path):
                 logger.error(f"Template not found: {template_path}")
diff --git a/templates/README_template.md.jinja b/templates/README.md.jinja
similarity index 100%
rename from templates/README_template.md.jinja
rename to templates/README.md.jinja
diff --git a/templates/data/neurons.js.template.jinja b/templates/data/neurons.js.jinja
similarity index 100%
rename from templates/data/neurons.js.template.jinja
rename to templates/data/neurons.js.jinja
diff --git a/templates/static/js/neuron-search.js.template.jinja b/templates/static/js/neuron-search.js.jinja
similarity index 100%
rename from templates/static/js/neuron-search.js.template.jinja
rename to templates/static/js/neuron-search.js.jinja

From 1e534a9b02dbadccf93465a83fe0a47d68ee2a71 Mon Sep 17 00:00:00 2001
From: Frank Loesche <loeschef@janelia.hhmi.org>
Date: Wed, 26 Nov 2025 17:08:21 -0500
Subject: [PATCH 3/7] improve caching

---
 src/neuview/services/roi_data_service.py | 12 +++++++++---
 1 file changed, 9 insertions(+), 3 deletions(-)

diff --git a/src/neuview/services/roi_data_service.py b/src/neuview/services/roi_data_service.py
index 5f8ec31f..9cdf433c 100644
--- a/src/neuview/services/roi_data_service.py
+++ b/src/neuview/services/roi_data_service.py
@@ -7,10 +7,11 @@
 
 import json
 import logging
-import requests
-from typing import Dict, List, Tuple, Any, Optional
-from pathlib import Path
 import time
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Tuple
+
+import requests
 
 logger = logging.getLogger(__name__)
 
@@ -87,6 +88,11 @@ def _fetch_json_from_gcs(self, url: str, cache_filename: str) -> Dict[str, Any]:
 
             data = response.json()
 
+            # Validate that we have actual data before caching
+            if not data or (isinstance(data, dict) and not any(data.values())):
+                logger.warning(f"Received empty data from {url}, not caching")
+                raise ValueError("Empty data received from GCS endpoint")
+
             # Cache the result
             try:
                 with open(cache_file, "w") as f:

From 38aea5fbd655d8e6289bb30bfd2a49bade00f0e0 Mon Sep 17 00:00:00 2001
From: Frank Loesche <loeschef@janelia.hhmi.org>
Date: Wed, 26 Nov 2025 17:20:41 -0500
Subject: [PATCH 4/7] fix warnings from subset-medium generation

---
 .../services/layer_analysis_service.py        | 10 ++--
 .../services/resource_manager_service.py      | 46 ++++++++++---------
 src/neuview/services/roi_data_service.py      | 24 +++++++++-
 src/neuview/services/roi_hierarchy_service.py |  8 ++--
 4 files changed, 55 insertions(+), 33 deletions(-)

diff --git a/src/neuview/services/layer_analysis_service.py b/src/neuview/services/layer_analysis_service.py
index ed5278a0..5eb00d28 100644
--- a/src/neuview/services/layer_analysis_service.py
+++ b/src/neuview/services/layer_analysis_service.py
@@ -9,8 +9,9 @@
 
 import logging
 import re
+from typing import Any, Dict, List, Optional, Tuple
+
 import pandas as pd
-from typing import Dict, Any, List, Optional, Tuple
 
 logger = logging.getLogger(__name__)
 
@@ -42,7 +43,7 @@ def analyze_layer_roi_data(
         Args:
             roi_counts_df: DataFrame with ROI count data
             neurons_df: DataFrame with neuron data
-            soma_side: Side of soma (left/right)
+            soma_side: Side of soma ('left', 'right', 'middle', or 'combined')
             neuron_type: Name of the neuron type
             connector: Database connector for additional queries
 
@@ -143,13 +144,14 @@ def _filter_roi_data_by_optic_lobe_side(
         """Filter ROI data to include only ROIs from the ipsilateral optic lobe
         side to the soma side. Use the ipsilateral side to ensure that the layer
          table data matches the hexagonal eyemap plots."""
-        if soma_side == "combined":
+        if soma_side in ["combined", "middle"]:
+            # For combined and middle soma sides, include all layer ROIs
             layer_rois_filtered = layer_rois
         else:
             side_key = {"left": "_L_", "right": "_R_"}
             if soma_side not in side_key:
                 raise ValueError(
-                    f"Unsupported soma_side: {soma_side!r} (use 'left', 'right', or 'combined')"
+                    f"Unsupported soma_side: {soma_side!r} (use 'left', 'right', 'middle', or 'combined')"
                 )
             pattern = side_key[soma_side]
             mask = (
diff --git a/src/neuview/services/resource_manager_service.py b/src/neuview/services/resource_manager_service.py
index a5557750..b390cf12 100644
--- a/src/neuview/services/resource_manager_service.py
+++ b/src/neuview/services/resource_manager_service.py
@@ -6,13 +6,13 @@
 directories, and handling other file system operations.
 """
 
-import shutil
 import logging
+import shutil
 from pathlib import Path
-from typing import Dict, Any, Optional, List
+from typing import Any, Dict, List, Optional
 
+from ..utils import get_project_root, get_static_dir, get_templates_dir
 from .neuroglancer_js_service import NeuroglancerJSService
-from ..utils import get_templates_dir, get_static_dir, get_project_root
 
 logger = logging.getLogger(__name__)
 
@@ -196,30 +196,32 @@ def copy_static_files(self, mode: str = "check_exists") -> bool:
                         "Failed to generate neuroglancer JavaScript file - this is a critical error"
                     )
                     return False
-            else:
+
+                # Verify the generated file exists and contains expected content
+                if not generated_file.exists():
+                    logger.error(
+                        "Neuroglancer JavaScript file does not exist after generation"
+                    )
+                    return False
+
+                with open(generated_file, "r") as f:
+                    content = f.read()
+                newline = "\n"
                 logger.debug(
-                    "Neuroglancer JavaScript file already exists, skipping generation"
+                    f"Generated file exists, size: {len(content)} chars, lines: {len(content.split(newline))}"
                 )
 
-            # Verify the file exists and contains expected content
-            if not generated_file.exists():
-                logger.error("Neuroglancer JavaScript file does not exist")
-                return False
-
-            with open(generated_file, "r") as f:
-                content = f.read()
-            newline = "\n"
-            logger.debug(
-                f"Generated file exists, size: {len(content)} chars, lines: {len(content.split(newline))}"
-            )
+                if "function initializeNeuroglancerLinks" not in content:
+                    logger.error(
+                        "Generated neuroglancer JavaScript file is missing required function 'initializeNeuroglancerLinks'"
+                    )
+                    return False
 
-            if "function initializeNeuroglancerLinks" not in content:
-                logger.error(
-                    "Generated neuroglancer JavaScript file is missing required function 'initializeNeuroglancerLinks'"
+                logger.debug("✓ Neuroglancer JavaScript file generated successfully")
+            else:
+                logger.debug(
+                    "Neuroglancer JavaScript file already exists, skipping generation"
                 )
-                return False
-
-            logger.debug("✓ Neuroglancer JavaScript file generated successfully")
 
             # Copy other static assets (images, fonts, etc.) - Enhanced version
             # Copy all directories and files not already handled
diff --git a/src/neuview/services/roi_data_service.py b/src/neuview/services/roi_data_service.py
index 9cdf433c..3bca5e9d 100644
--- a/src/neuview/services/roi_data_service.py
+++ b/src/neuview/services/roi_data_service.py
@@ -79,6 +79,14 @@ def _fetch_json_from_gcs(self, url: str, cache_filename: str) -> Dict[str, Any]:
                         return data
                 except (json.JSONDecodeError, IOError) as e:
                     logger.warning(f"Failed to load cache file {cache_filename}: {e}")
+                    # Delete corrupted cache file to force refetch
+                    try:
+                        cache_file.unlink()
+                        logger.debug(f"Deleted corrupted cache file: {cache_filename}")
+                    except OSError as unlink_error:
+                        logger.warning(
+                            f"Failed to delete corrupted cache file {cache_filename}: {unlink_error}"
+                        )
 
         # Fetch from GCS
         logger.info(f"Fetching ROI data from: {url}")
@@ -115,8 +123,20 @@ def _fetch_json_from_gcs(self, url: str, cache_filename: str) -> Dict[str, Any]:
                             f"Using stale cache for {cache_filename} due to fetch failure"
                         )
                         return data
-                except (json.JSONDecodeError, IOError):
-                    pass
+                except (json.JSONDecodeError, IOError) as fallback_error:
+                    logger.warning(
+                        f"Stale cache file is also corrupted for {cache_filename}: {fallback_error}"
+                    )
+                    # Delete corrupted cache file
+                    try:
+                        cache_file.unlink()
+                        logger.debug(
+                            f"Deleted corrupted stale cache file: {cache_filename}"
+                        )
+                    except OSError as unlink_error:
+                        logger.warning(
+                            f"Failed to delete corrupted stale cache file {cache_filename}: {unlink_error}"
+                        )
 
             raise
 
diff --git a/src/neuview/services/roi_hierarchy_service.py b/src/neuview/services/roi_hierarchy_service.py
index 78ebd871..5334d02f 100644
--- a/src/neuview/services/roi_hierarchy_service.py
+++ b/src/neuview/services/roi_hierarchy_service.py
@@ -4,10 +4,10 @@
 Handles ROI hierarchy caching, parent lookup logic, and ROI data management.
 """
 
-import logging
-from pathlib import Path
 import json
+import logging
 import time
+from pathlib import Path
 
 logger = logging.getLogger(__name__)
 
@@ -81,9 +81,7 @@ def get_roi_hierarchy_cached(self, connector, output_dir=None):
 
             if not self._roi_hierarchy_cache:
                 # Cache miss - fetch from database
-                logger.warning(
-                    "ROI hierarchy not found in cache, fetching from database"
-                )
+                logger.info("ROI hierarchy not found in cache, fetching from database")
                 try:
                     # Use connector's cached ROI hierarchy method
                     self._roi_hierarchy_cache = connector._get_roi_hierarchy()

From 6a02430301d1e87c145aa90c500a59164570e798 Mon Sep 17 00:00:00 2001
From: Frank Loesche <loeschef@janelia.hhmi.org>
Date: Mon, 1 Dec 2025 14:53:44 -0500
Subject: [PATCH 5/7] fix linter docu

---
 docs/developer-guide.md                     | 4 ++--
 test/services/test_statistics_calculator.py | 2 --
 2 files changed, 2 insertions(+), 4 deletions(-)

diff --git a/docs/developer-guide.md b/docs/developer-guide.md
index b030832f..6ca5bf83 100644
--- a/docs/developer-guide.md
+++ b/docs/developer-guide.md
@@ -73,7 +73,7 @@ neuView follows a layered architecture pattern:
 - `pixi run test` - Run all tests
 
 **Code Quality:**
-- `pixi run lint` - Run ruff linter
+- `pixi run check` - Run ruff linter
 - `pixi run format` - Format code with ruff
 
 **Content Generation:**
@@ -648,4 +648,4 @@ neuview/
 - **GitHub Repository**: Project source code and issues
 - **NeuPrint Documentation**: https://neuprint.janelia.org/
 - **Jinja2 Documentation**: https://jinja.palletsprojects.com/
-- **pytest Documentation**: https://docs.pytest.org/
\ No newline at end of file
+- **pytest Documentation**: https://docs.pytest.org/
diff --git a/test/services/test_statistics_calculator.py b/test/services/test_statistics_calculator.py
index 00fc890d..73e4708e 100644
--- a/test/services/test_statistics_calculator.py
+++ b/test/services/test_statistics_calculator.py
@@ -3,8 +3,6 @@
 This module tests the calculator classes that compute statistics from raw data.
 """
 
-import pytest
-
 from neuview.services.statistics_calculator import (
     CombinedStatisticsCalculator,
     SideStatisticsCalculator,

From b0ecaa18c17e34102a1fba0d68a9a792cf98bdab Mon Sep 17 00:00:00 2001
From: Frank Loesche <loeschef@janelia.hhmi.org>
Date: Mon, 1 Dec 2025 15:06:56 -0500
Subject: [PATCH 6/7] fix generate and coverage

---
 docs/developer-guide.md | 11 +++++++----
 1 file changed, 7 insertions(+), 4 deletions(-)

diff --git a/docs/developer-guide.md b/docs/developer-guide.md
index 6ca5bf83..995bb365 100644
--- a/docs/developer-guide.md
+++ b/docs/developer-guide.md
@@ -77,8 +77,11 @@ neuView follows a layered architecture pattern:
 - `pixi run format` - Format code with ruff
 
 **Content Generation:**
-- `pixi run neuview build` - Generate website
+- `pixi run neuview generate` - Generate website for 10 random neuron types
+    - `pixi run neuview generate -n Dm4` - Generate website for a specific neuron type, here *Dm4*
 - `pixi run neuview inspect <type>` - Inspect neuron type data
+- `pixi run create-all-pages` - Generate website with all neurons in the data set. **Note:** This command will also increment the version in git.
+
 
 ## Neuron Data System
 
@@ -448,11 +451,11 @@ pixi run unit-test
 # Run only integration tests
 pixi run integration-test
 
+# Run with coverage
+pixi run test-coverage
+
 # Run specific test file
 pixi run pytest test/unit/test_neuron_type.py
-
-# Run with coverage
-pixi run pytest --cov=src
 ```
 
 ### Test Structure

From 5b45ed1afb8a7593d3292bbb340bd9350206b709 Mon Sep 17 00:00:00 2001
From: Frank Loesche <loeschef@janelia.hhmi.org>
Date: Mon, 1 Dec 2025 15:12:21 -0500
Subject: [PATCH 7/7] fix verbose documentation

---
 docs/developer-guide.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/developer-guide.md b/docs/developer-guide.md
index 995bb365..799ae843 100644
--- a/docs/developer-guide.md
+++ b/docs/developer-guide.md
@@ -552,7 +552,7 @@ Automatic detection based on dataset name in configuration.
 
 Enable verbose logging:
 ```bash
-pixi run neuview build --verbose
+pixi run neuview --verbose generate
 ```
 
 Or set environment variable: