uDALES · madDipanjan · Jul 23, 2026 · Jul 18, 2026 · Jul 18, 2026 · Jul 18, 2026
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -187,7 +187,7 @@ jobs:
       shell: bash -l {0}
       run: |
         mkdocs build --site-dir build/html
-        ford docs/udales-docs-software.md
+        ford ford.md
 
     - name: Upload docs artifact
       uses: actions/upload-artifact@v7

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -1,6 +1,6 @@
 # How to contribute
 
-In general, you can contribute by reporting an issue or by directly contributing to the source code. For the latter, clone the repository, make your changes, and create a pull request (PR) with a **clear description** of your changes -- if you are unfamiliar with creating PRs, please see [this guide](https://guides.github.com/activities/forking/#making-a-pull-request) first. Please also read the [development notes](./DEVELOP.md) before opening an issue or create a PR. For specific instructions on how to report a bug or how to submit a feature request, please see below:
+In general, you can contribute by reporting an issue or by directly contributing to the source code. For the latter, clone the repository, make your changes, and create a pull request (PR) with a **clear description** of your changes -- if you are unfamiliar with creating PRs, please see [this guide](https://guides.github.com/activities/forking/#making-a-pull-request) first. Please also read the [development notes](https://udales.github.io/u-dales/udales-development/) before opening an issue or creating a PR. For specific instructions on how to report a bug or how to submit a feature request, please see below:
 
 - [How to contribute](#how-to-contribute)
   - [Report a bug](#report-a-bug)
@@ -9,7 +9,7 @@ In general, you can contribute by reporting an issue or by directly contributing
 
 ## Report a bug
 
-Before creating bug reports, please check if similar issue have already been reported [here](https://github.com/uDALES/u-dales/issues). If none exist please create a new issue and include as many details as possible using the required template.
+Before creating bug reports, please check if similar issues have already been reported [here](https://github.com/uDALES/u-dales/issues). If none exist please create a new issue and include as many details as possible using the required template.
 
 ## Request a new feature
 

diff --git a/DEVELOP.md b/DEVELOP.md
@@ -2,7 +2,7 @@
 
 ## Set up
 
-Install all required packages for uDALES described in the [prerequisites section](https://udales.github.io/u-dales/udales-getting-started/#prerequisites-when-not-using-singularity), plus optionally [Graphviz](https://graphviz.org/) for generating graphs in the code viewer. E.g. installing all the required packages using Ubuntu's APT:
+Install all required packages for uDALES described in the [prerequisites section](https://udales.github.io/u-dales/udales-installation/#prerequisites), plus optionally [Graphviz](https://graphviz.org/) for generating graphs in the code viewer. E.g. installing all the required packages using Ubuntu's APT:
 
 ```sh
 sudo apt update && sudo apt install -y gfortran libopenmpi-dev openmpi-bin libnetcdf-dev libnetcdff-dev graphviz
@@ -16,59 +16,46 @@ conda env create -f environment.yml
 
 Then activate with `conda activate udales`.
 
-If a shared virtual environment already exists at `../.venv/`, you can
-also use that directly for Python tooling and tests, for example:
+For the Python tooling (pre-processing and the Python package tests), create the project virtual environment with:
 
 ```sh
-../.venv/bin/python -m unittest tools/python/tests/test_namelist.py
+./tools/python/setup_venv.sh common
 ```
 
-The Python radiation tooling also requires the compiled View3D executable and
-the `directshortwave_f2py` wrapper. The simplest setup path is:
+This creates the environment at `tools/python/.venv`, installs all dependencies, and builds the compiled preprocessing extensions (View3D and the f2py modules). See [tools/python/README_VENV.md](https://github.com/uDALES/u-dales/blob/master/tools/python/README_VENV.md) for details.
 
-```sh
-PYTHON_BIN=/opt/pbs/python/bin/python3 ./tools/python/setup_venv.sh
-```
-
-Use another interpreter only if it provides the matching Python development
-headers needed by f2py.
-
-New Linux/WSL setups now default to `../.venv/`, matching the Windows
-setup script. If you already have a repo-local `.venv/`, the setup script will
-keep using it until you migrate manually.
-
-## Installation
+## Building for development
 
-To install uDALES on Linux, macOS, and WSL, use the following commands from the command prompt:
+Building the model is described in the [installation guide](https://udales.github.io/u-dales/udales-installation/); the same instructions apply for development. In addition, developers will usually want a `Debug` build, which enables runtime checks and floating-point exception trapping:
 
 ```sh
-mkdir -p build/release
-pushd build/release
-cmake ../..
+mkdir -p build/debug
+pushd build/debug
+cmake -DCMAKE_BUILD_TYPE=Debug ../..
 make
 ```
 
-To know more about build options, please see [build/default options](https://udales.github.io/u-dales/udales-getting-started/#build-defaultsoptions).
-
-## Running
-
-A uDALES simulation needs to be executed from a directory containing all required input files. Examples of experiments and required inputs are in the `examples` directory. To run a uDALES simulation you need to specify the number of cpus `<NCPU>`, the path to the build file `<BUILD>` and the simulation configuration file `<NAMOPTIONS>` and execute the simulation with the following command:
+For quick testing without the wrapper scripts, the solver can be run directly from a directory containing all input files:
 
 ``` sh
 mpiexec -n <NCPU> <BUILD> <NAMOPTIONS>
 ```
 
 ## Testing
 
-Please refer to [Test docs](https://github.com/uDALES/u-dales/blob/master/tests/README.md).
+Tests are dispatched from a manifest with `tests/run_tests.py` (suites are defined in `tests/test_suites.yml`). Please refer to the [test docs](https://github.com/uDALES/u-dales/blob/master/tests/README.md) for the test layout and execution contracts.
 
 ## Documentation
 
+The user documentation is built with [MkDocs](https://www.mkdocs.org/) (Material theme) and the software docs with [FORD](https://github.com/Fortran-FOSS-Programmers/ford); both are installed by the conda environment above. To build:
+
 ```sh
 mkdocs build --site-dir build/html
-ford docs/udales-docs-software.md
+ford ford.md
 ```
 
+For live preview while editing, use `mkdocs serve`.
+
 ### Examples input plots
 
 To create domain plots of the examples, run the following from your command line (requires MATLAB):
@@ -77,7 +64,7 @@ To create domain plots of the examples, run the following from your command line
  matlab -nosplash -nodesktop -r "cd('tools/examples'); plot_blocks('<CASE_NUMBER>'); quit"
 ```
 
-where `<CASE_NUMBER>` is e.g. `201`. Plots are then saved in their respective example folders.   
+where `<CASE_NUMBER>` is e.g. `201`. Plots are then saved in their respective example folders.
 
 ### Examples outputs and plots
 
@@ -93,7 +80,6 @@ Then, to create a sample plot for case `102` run the following from your command
 matlab -nosplash -nodesktop -r "cd('tools/examples'); plot_fielddump_slice('102','u','y',32,1); quit"
 ```
 
-
 ## Versioning
 
 This project uses [semantic versioning](https://semver.org/).
diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md
diff --git a/docs/DEVELOP.md b/docs/DEVELOP.md
diff --git a/docs/cluster_workflows.md b/docs/cluster_workflows.md
@@ -85,14 +85,15 @@ Use the gather wrapper to collect outputs after the run:
 
 ## Python Environment
 
-Use the repo-local virtual environment created by `setup_venv.sh`:
+Create the project virtual environment with the setup script, which also
+builds the preprocessing tools (View3D and the f2py extension modules):
 
 ```bash
-tools/python/.venv
+./tools/python/setup_venv.sh icl
 ```
 
-When activating that environment on the cluster, load the matching Python module
-first so the runtime libraries are available:
+When activating the environment on the cluster, load the matching Python
+module first so the runtime libraries are available:
 
 ```bash
 module load Python/3.13.1-GCCcore-14.2.0
@@ -101,7 +102,7 @@ source tools/python/.venv/bin/activate
 
 Use the same Python module for repo Python workflows on the cluster. In
 particular, the `f2py`-based extensions in this repository are expected to be
-built and run with the same Python runtime rather than whichever `python3`
+built and run with the same Python runtime environment above rather than whichever `python3`
 happens to be first on `PATH`.
 
 ## Interactive Analysis
@@ -129,14 +130,14 @@ job environment. In particular:
   `PATH` after loading modules
 - batch-style output redirection patterns may fail interactively even when they
   work inside submitted jobs
-- Codex sandboxed sessions can add another layer of difference: a launcher
-  failure seen inside the sandbox may be a sandbox socket restriction rather
-  than a real cluster-side problem
+- sandboxed agent sessions (Codex, Claude Code) can add another layer of
+  difference: a launcher failure seen inside the sandbox may be a sandbox
+  socket restriction rather than a real cluster-side problem
 
 So for interactive debugging:
 
 - prefer reproducing the environment from the repo wrappers
-- if a login-node MPI launch fails inside Codex, retry it outside the sandbox
+- if a login-node MPI launch fails inside an agent sandbox, retry it outside the sandbox
   before treating it as a solver or cluster configuration issue
 - keep the launcher invocation minimal
 - avoid changing MPI launcher behavior and output handling unless you have

diff --git a/docs/index.md b/docs/index.md
@@ -1,12 +1,67 @@
-# uDALES Docs
+# uDALES
 
-This is the documentation for uDALES, an open-source multi-physics microscale urban modelling tool, capable of performing large-eddy simulation (LES) of urban airflow, heat transfer, and pollutant dispersion. This documentation contains user's guides and general reference documentation.
+uDALES is an open-source multi-physics microscale urban modelling tool, capable of performing large-eddy simulation (LES) of urban airflow, heat transfer, and pollutant dispersion. It resolves buildings with a conservative immersed boundary method, includes a full urban surface energy balance with radiation, vegetation, and moisture, and scales to large domains on HPC systems. See the [model overview](udales-model-overview.md) for what uDALES can do.
 
 | | | |
 |:--:|:--:|:--:|
 | ![uDALES Temperature](./assets/images/T_5fps.gif) | ![uDALES Momentum](./assets/images/M_5fps.gif) | ![uDALES Vertical Velocity](./assets/images/w_5fps.gif) |
 
-For a quick introduction and instructions on installing and running uDALES, see the "Installation and First Run" page: [Installation and First Run](./udales-installation.md).
+<div class="grid cards" markdown>
 
-For contributor guidance on using agents in this repo, see:
-[Using Agents](./udales-agents.md).
+-   :material-download:{ .lg .middle } **Installation**
+
+    ---
+
+    Build uDALES on Linux, macOS, WSL, or HPC clusters.
+
+    [:octicons-arrow-right-24: Installation and first run](udales-installation.md)
+
+-   :material-map-marker-path:{ .lg .middle } **Workflow overview**
+
+    ---
+
+    The end-to-end simulation workflow: set up, pre-process, run, and post-process.
+
+    [:octicons-arrow-right-24: Workflow overview](udales-workflow.md)
+
+-   :material-tune:{ .lg .middle } **Simulation inputs**
+
+    ---
+
+    Configure your simulation via the `namoptions` input parameters and generate urban geometries.
+
+    [:octicons-arrow-right-24: Input parameters](udales-namoptions-overview.md)
+
+-   :material-play:{ .lg .middle } **Example simulations**
+
+    ---
+
+    Ready-to-run example cases, from neutral flow over cubes to full urban energy balance setups.
+
+    [:octicons-arrow-right-24: Example simulations](udales-example-simulations.md)
+
+-   :material-chart-line:{ .lg .middle } **Post-processing tutorials**
+
+    ---
+
+    Load and analyse uDALES output with the `udbase` class: fields, statistics, and facet data.
+
+    [:octicons-arrow-right-24: Tutorials](udales-udbase-tutorial.md)
+
+-   :material-language-python:{ .lg .middle } **Python package**
+
+    ---
+
+    The next-generation pre- and post-processing toolchain, currently under active testing.
+
+    [:octicons-arrow-right-24: Python package](udales-python-package.md)
+
+</div>
+
+## Citing uDALES
+
+When using uDALES or data generated by uDALES, please cite the model papers — see [How to cite](udales-how-to-cite.md). A list of publications using uDALES is available in the [publication list](udales-pub-list.md).
+
+## Contributing
+
+uDALES is developed openly on [GitHub](https://github.com/uDALES/u-dales). See the [developer documentation](udales-development.md) and [contribution guide](udales-contributing.md) to get involved.
diff --git a/docs/javascripts/mathjax.js b/docs/javascripts/mathjax.js
@@ -0,0 +1,16 @@
+window.MathJax = {
+  tex: {
+    inlineMath: [["\\(", "\\)"]],
+    displayMath: [["\\[", "\\]"]],
+    processEscapes: true,
+    processEnvironments: true
+  },
+  options: {
+    ignoreHtmlClass: ".*|",
+    processHtmlClass: "arithmatex"
+  }
+};
+
+document$.subscribe(() => {
+  MathJax.typesetPromise();
+});
diff --git a/docs/references.bib b/docs/references.bib
@@ -1,9 +1,53 @@
+@article{Wilson2026,
+  author = {Wilson, C. E. and Shonk, J. K. P. and Bohnenstengel, S. I. and Paschalis, A. and van Reeuwijk, M.},
+  title = {Parameter investigation for urban surface-energy balance: A large-eddy simulation study},
+  journal = {Q. J. Roy. Met. Soc.},
+  volume = {152},
+  number = {777},
+  pages = {e70154},
+  year = {2026},
+  doi = {10.1002/qj.70154}
+}
+
+@article{Fellini2026,
+  author = {Fellini, S. and Majumdar, D. and Salizzoni, P. and van Reeuwijk, M.},
+  title = {Three-dimensional pollutant dispersion in tree-lined urban canyons: Combined wind-tunnel and LES analysis},
+  journal = {Atmos. Env.},
+  volume = {367},
+  pages = {121748},
+  year = {2026},
+  doi = {10.1016/j.atmosenv.2025.121748}
+}
+
 @article{Owens2025,
-  url={https://dx.doi.org/10.2139/ssrn.5125973}, 
-  year = {(awaiting publication)},
   author = {Owens, S. and Beckett, O. and Acred, A. and van Reeuwijk, M.},
-  title = {Large-Eddy Simulation of a Diurnal Cycle in a Coastal Urban Environment.},
-  journal = {Building and Environment}
+  title = {Large-Eddy Simulation of a Diurnal Cycle in a Coastal Urban Environment},
+  journal = {Building and Environment},
+  volume = {281},
+  pages = {112999},
+  year = {2025},
+  doi = {10.1016/j.buildenv.2025.112999}
+}
+
+@article{Wilson2025,
+  author = {Wilson, C. and Shonk, J. K. P. and Bohnenstengel, S. I. and Paschalis, A. and van Reeuwijk, M.},
+  title = {Microscale to neighbourhood scale: Impact of shading on urban climate},
+  journal = {Building and Environment},
+  volume = {275},
+  pages = {112721},
+  year = {2025},
+  doi = {10.1016/j.buildenv.2025.112721}
+}
+
+@article{Reeuwijk2025,
+  author = {van Reeuwijk, M. and Huang, J.},
+  title = {Multi-scale Analysis of Flow over Heterogeneous Urban Environments},
+  journal = {Bound.-Lay. Met.},
+  volume = {191},
+  number = {11},
+  pages = {47},
+  year = {2025},
+  doi = {10.1007/s10546-025-00941-w}
 }
 
 @article{Majumdar2025,

diff --git a/docs/udales-agents.md b/docs/udales-agents.md
@@ -1,7 +1,13 @@
 # Using Agents
 
-This page describes how we use Codex agents for uDALES development work.
-It is aimed at contributors working on this repository.
+This page describes how we use AI coding agents — currently OpenAI Codex and
+Anthropic Claude Code — for uDALES development work. It is aimed at
+contributors working on this repository.
+
+!!! note "Improved agent instructions coming"
+    A revised, expanded set of agent instructions is under development on the
+    [`performance` branch](https://github.com/uDALES/u-dales/tree/performance)
+    and will supersede parts of this page once merged.
 
 ## When to use an agent
 
@@ -22,7 +28,7 @@ Use an agent when the task benefits from:
 
 Project-specific instructions for agents live in:
 
-- `AGENTS.md` (repo-level guidance)
+- `AGENTS.md` (repo-level guidance, read by both Codex and Claude Code)
 - `.github/skills/udales-exec/` (cluster execution runbook skill)
 - `.github/skills/udales-detect/` (environment detection skill)