+ SimPaths has been developed through a sequence of research and policy grants across partner institutions.
+ This page brings together the confirmed past and present funding that has supported the model and its applications.
+
+
+
+
+
+
Current Funding
+
+
+
2021-2026
+
Evaluation of the health impacts of Universal Credit: a mixed methods study
+
NIHR
+
+
+
2022-2027
+
Greater Essex Health Determinants Research Collaboration
+
NIHR
+
+
+
2023-2027
+
Sustainable Welfare: Rethinking the roles of Family, Market and State (SUSTAINWELL)
+
Horizon Europe
+
+
+
2024-2028
+
Policy Modelling for Health
+
UKRI PHI
+
+
+
2025-2028
+
WELLSIM: A life course microsimulation perspective on multi-dimensional well-being for five European countries
+
CHANSE/NORFACE
+
+
+
2025-2028
+
Evaluating the impact of major income support policies on health inequalities across the life course: a micro-macro linked modelling study (MicMac)
Investigating Economic Insecurity: A Microsimulation Approach
+
INAPP
+
+
+
2021-2022
+
Understanding the impacts of income and welfare policy responses to COVID-19 on inequalities in mental health: A microsimulation model
+
Health Foundation
+
+
+
2021-2024
+
Caring Over the Lifecycle: the Roles of Families and Welfare States Today and Into the Future
+
JPI
+
+
+
2021-2025
+
Health Equity of Economic Determinants (HEED): A Pan-European Microsimulation model for Health impacts of Income and Social Security Policies
+
ERC
+
+
+
2023-2025
+
Overlapping crises: (Re)shaping the future of regional labour markets (OVERLAP)
+
ESPON
+
+
+
+
+
+
+
diff --git a/documentation/wiki/getting-started/environment-setup.md b/documentation/wiki/getting-started/environment-setup.md
index 99be75070..0a7bcdb51 100644
--- a/documentation/wiki/getting-started/environment-setup.md
+++ b/documentation/wiki/getting-started/environment-setup.md
@@ -1,28 +1,110 @@
# Environment Setup
-!!! warning "In progress"
- This page is under development. Contributions welcome —
- see the [Getting Started](index.md) overview.
+This page covers the local software requirements, repository setup, and the first-time build and database steps needed before SimPaths is ready to run.
-## Requirements
+## 1. Local requirements
-- Java Development Kit (JDK) 19 (the project targets Java 19 — earlier versions will not compile)
+- Java Development Kit (JDK) 19
- Apache Maven 3.8 or later
- Git
-## Cloning the repository
+The project is compiled for Java 19 in `pom.xml`, so earlier Java versions will not build the code correctly.
+
+It is worth checking the toolchain before going further:
+
+```bash
+java -version
+mvn -version
+git --version
+```
+
+## 2. Clone the repository
+
+Clone SimPaths and move into the repository root:
```bash
git clone https://github.com/simpaths/SimPaths.git
cd SimPaths
```
-## Building the project
+## 3. Build the executables
+
+SimPaths uses the Maven Shade plugin to build two runnable jars:
+
+- `singlerun.jar` for single simulations via `simpaths.experiment.SimPathsStart`
+- `multirun.jar` for repeated runs via `simpaths.experiment.SimPathsMultiRun`
+
+Build them from the repository root:
```bash
mvn clean package
```
-This produces `singlerun.jar` and `multirun.jar` at the repository root.
+After a successful package step, both jars are written to the repository root.
+
+If this step fails, fix the Java or Maven setup first. There is no point debugging the model before the jars build cleanly.
+
+## 4. Check the required input layout
+
+Before a real run, SimPaths expects the `input/` directory to contain:
+
+- `InitialPopulations/` for starting population CSV files
+- `EUROMODoutput/` for donor tax-benefit input files
+- Excel workbooks such as `EUROMODpolicySchedule.xlsx`, `DatabaseCountryYear.xlsx`, and the `align_*.xlsx`, `reg_*.xlsx`, `scenario_*.xlsx`, and `projections_*.xlsx` parameter files
+
+The key point here is that SimPaths does **not** run directly from the raw CSV and EUROMOD files. During setup, the code rebuilds the local H2 database `input/input.mv.db` from those sources by calling `Parameters.databaseSetup()`.
+
+## 5. Understand first-time setup
+
+The first-time setup step is what turns the repository from "compiled" into "runnable".
+
+Setup does four important things:
+
+1. writes or refreshes `DatabaseCountryYear.xlsx`
+2. validates or rebuilds `EUROMODpolicySchedule.xlsx`
+3. rebuilds the starting-population database under `input/input.mv.db`
+4. rebuilds the donor tax-benefit database from `input/EUROMODoutput/`
+
+For a clean first headless setup, the most explicit route is:
+
+```bash
+java -jar singlerun.jar -Setup -c UK -s 2019 -g false --rewrite-policy-schedule
+```
+
+Once that succeeds, a run-only check is straightforward:
+
+```bash
+java -jar singlerun.jar -Run -c UK -s 2019 -g false
+```
+
+If you prefer the repeated-run path, the equivalent setup command is:
+
+```bash
+java -jar multirun.jar -DBSetup -config config/default.yml
+```
+
+## 6. Training data fallback
+
+If no top-level CSV files are found in `input/InitialPopulations/`, SimPaths automatically switches to the bundled training data under `input/InitialPopulations/training/` and the associated training donor files. This is useful for documentation, testing, and development, but not for substantive research analysis.
+
+The fallback is helpful for getting the code running locally, but it is not a substitute for the full research inputs.
+
+## 7. Policy schedule file
+
+Single-run setup expects `input/EUROMODpolicySchedule.xlsx` to exist. If you need to rebuild that file from the EUROMOD output filenames, use the `--rewrite-policy-schedule` flag when running `singlerun.jar`.
+
+## 8. Common setup problems
+
+The usual setup failures are:
+
+- **wrong Java version**: the build or runtime fails before the model even starts
+- **missing initial population files**: setup falls back to training data, or database creation fails
+- **missing donor files**: the tax-benefit database cannot be rebuilt
+- **stale policy schedule**: the EUROMOD output files and `EUROMODpolicySchedule.xlsx` do not line up
+- **database needs rebuilding**: donor files or schedule changed, but the old `input/input.mv.db` is still being reused
+
+If donor inputs, donor years, or the policy schedule change, rebuild the database before trying to interpret any results.
+
+## Next step
-Refer to the [Working in GitHub](../developer-guide/working-in-github.md) guide for the full development workflow.
+Once the project is built and the input data are in place, continue to [Running Your First Simulation](first-simulation.md).
diff --git a/documentation/wiki/getting-started/first-simulation.md b/documentation/wiki/getting-started/first-simulation.md
index 1c79c9b09..2cafff871 100644
--- a/documentation/wiki/getting-started/first-simulation.md
+++ b/documentation/wiki/getting-started/first-simulation.md
@@ -1,5 +1,107 @@
# Running Your First Simulation
-!!! warning "In progress"
- This page is under development. Contributions welcome —
- see [Single Runs](../user-guide/single-runs.md) in the User Guide for current guidance.
+This page covers the quickest reliable path to a first successful SimPaths run using `singlerun.jar`.
+
+## Before you run
+
+Make sure you have already completed:
+
+- [Environment Setup](environment-setup.md)
+- [Input Data](data/index.md)
+
+In practice, that means:
+
+- the project builds successfully with Maven
+- `singlerun.jar` exists in the repository root
+- the required input files are present under `input/`
+
+## Recommended first run: headless and explicit
+
+For a first run, the clearest route is to separate setup from execution.
+
+### 1. Build the project
+
+```bash
+mvn clean package
+```
+
+### 2. Run setup only
+
+```bash
+java -jar singlerun.jar -Setup -c UK -s 2019 -g false --rewrite-policy-schedule
+```
+
+This setup phase does not run the simulation itself. It prepares the model by:
+
+- writing or refreshing the policy schedule
+- saving the selected country and start year
+- loading uprating and alignment inputs
+- rebuilding `input/input.mv.db`
+
+If `input/EUROMODpolicySchedule.xlsx` already exists and matches your donor files, you can omit `--rewrite-policy-schedule`.
+
+### 3. Run the simulation only
+
+```bash
+java -jar singlerun.jar -Run -c UK -s 2019 -g false
+```
+
+This starts the JAS-mine engine with:
+
+- `SimPathsModel`
+- `SimPathsCollector`
+- `SimPathsObserver` only when the GUI is enabled
+
+In headless mode, the process runs to completion and then exits.
+
+## What the main flags do
+
+The most useful `singlerun.jar` options are:
+
+- `-c `: country code such as `UK` or `IT`
+- `-s `: simulation start year
+- `-Setup`: perform setup only, then exit
+- `-Run`: skip setup and run the simulation directly
+- `-g true|false`: enable or disable the GUI
+- `--rewrite-policy-schedule`: rebuild `EUROMODpolicySchedule.xlsx` from detected donor policy files
+
+`-Setup` and `-Run` are mutually exclusive. If neither is provided, `SimPathsStart` does both.
+
+## If you want to use the GUI
+
+After the initial setup has succeeded, you can launch the single-run interface with:
+
+```bash
+java -jar singlerun.jar
+```
+
+In GUI mode, SimPaths opens the start-up dialog and then launches the JAS-mine shell. This is useful for interactive exploration, but it is less explicit than the headless route for a first installation check.
+
+## What success looks like
+
+A successful first run should leave you with:
+
+- a rebuilt input database at `input/input.mv.db`
+- no setup error about missing donor files or missing policy schedule
+- a completed simulation run, either in the GUI or in headless mode
+
+If the run fails before the simulation starts, the problem is usually in setup rather than in the model itself.
+
+## Common first-run problems
+
+- `Policy Schedule file ... doesn't exist`
+ - create `input/EUROMODpolicySchedule.xlsx` first, or rerun setup with `--rewrite-policy-schedule`
+- donor or initial-population files are missing
+ - check the contents of `input/InitialPopulations/` and `input/EUROMODoutput/`
+- wrong Java version
+ - SimPaths targets Java 19
+- setup succeeds but the run uses unexpected inputs
+ - rebuild the database after changing donor files or the policy schedule
+
+## Where to go next
+
+Once the first run works, the next useful pages are:
+
+- [Single Runs](../user-guide/single-runs.md)
+- [Multiple Runs](../user-guide/multiple-runs.md)
+- [Modifying Tax-Benefit Parameters](../user-guide/tax-benefit-parameters.md)
diff --git a/documentation/wiki/index.md b/documentation/wiki/index.md
index 3f1e0b464..760b6532a 100644
--- a/documentation/wiki/index.md
+++ b/documentation/wiki/index.md
@@ -6,30 +6,11 @@ hide:
-# SimPaths
+
SimPaths
-
Open-source dynamic microsimulation for life course modelling — projecting careers, families, health, and finances across populations.
+SimPaths is a family of open-source models for individual and household life course events, all sharing common components. The framework is designed to project life histories through time, building up a detailed picture of career paths, family (inter)relations, health, and financial circumstances.
-
- ✓ Open Source
- 🌍 5 Countries
- ☕ Java / JAS-mine
- 🔬 UKRI HealthMod
-
-
----
-
-## About SimPaths
-
-SimPaths builds upon **JAS-mine**, an open-source Java platform designed for discrete-event simulations. Models currently exist for the **UK, Greece, Hungary, Italy, and Poland**.
+The broader SimPaths family spans **the UK and other European countries**.
🇬🇧 United Kingdom
@@ -39,53 +20,47 @@ SimPaths builds upon **JAS-mine**, an open-source Java platform designed for dis
🇵🇱 Poland
---
-!!! tip "New to SimPaths?"
- Start with the [Overview](overview/) to understand what the model does, then follow the [Getting Started](getting-started/) guide to run your first simulation.
+