From 02f6cb116c6a04d2a973ea7a083f14af915b8858 Mon Sep 17 00:00:00 2001
From: timlichtenberg <lichtenberg.tim@gmail.com>
Date: Sun, 8 Nov 2026 02:01:28 +0100
Subject: [PATCH 01/14] Test an optional output_dir for the standalone output
 files

With [Output] output_dir the profile, the summary, the profile plot, the mantle P-T plot (named with id_mass) and the CLI log go into that folder and nothing into <root>/output or the working directory; without it a library call keeps <root>/output. The key takes an existing folder; other types, an empty value and a missing folder raise ValueError.
---
 tests/test_output_dir.py | 236 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 236 insertions(+)
 create mode 100644 tests/test_output_dir.py

diff --git a/tests/test_output_dir.py b/tests/test_output_dir.py
new file mode 100644
index 00000000..f1d4f1f8
--- /dev/null
+++ b/tests/test_output_dir.py
@@ -0,0 +1,236 @@
+"""The optional ``[Output] output_dir``: the one folder of the standalone output files.
+
+``post_processing``, the two plot writers and the CLI log write into ``output_dir`` when it
+is given; without it a library call keeps ``<ZALMOXIS_ROOT>/output`` and the CLI sets that
+folder itself.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import runpy
+from pathlib import Path
+from unittest.mock import patch
+
+import numpy as np
+import pytest
+from hypothesis import HealthCheck, given, settings
+from hypothesis import strategies as st
+
+from tests.test_config_validators_extra import _make_minimal_config
+from tests.test_output import _base_config, fake_solver, fake_solver_results  # noqa: F401
+from zalmoxis import output as output_mod
+from zalmoxis.config import validate_config
+from zalmoxis.plots import plot_phase_vs_radius, plot_profiles
+
+pytestmark = [pytest.mark.unit, pytest.mark.timeout(30)]
+
+
+@pytest.fixture
+def fake_root(monkeypatch, tmp_path):
+    """A ZALMOXIS_ROOT with an empty output/ for the writers that fall back to it."""
+    root = tmp_path / 'root'
+    (root / 'output').mkdir(parents=True)
+    for mod in (output_mod, plot_profiles, plot_phase_vs_radius):
+        monkeypatch.setattr(mod, 'get_zalmoxis_root', lambda: str(root))
+    return root
+
+
+def _plotting_config(**overrides):
+    """A config that writes data, plots and the mantle P-T plot (a melting-curve mantle)."""
+    cfg = _base_config(plotting_enabled=True)
+    cfg['layer_eos_config'] = {'core': 'Seager2007:iron', 'mantle': 'WolfBower2018:MgSiO3'}
+    cfg.update(overrides)
+    return cfg
+
+
+@pytest.mark.usefixtures('fake_solver')
+def test_post_processing_writes_every_file_into_output_dir(fake_root, tmp_path, monkeypatch):
+    """Profile, summary, profile plot and P-T plot go to output_dir; root/output and cwd stay empty."""
+    run, cwd = tmp_path / 'run', tmp_path / 'cwd'
+    run.mkdir()
+    cwd.mkdir()
+    monkeypatch.chdir(cwd)
+    output_mod.post_processing(_plotting_config(output_dir=str(run)), id_mass='1.0')
+    assert sorted(p.name for p in run.iterdir()) == [
+        'calculated_planet_mass_radius.txt',
+        'mantle_PT_profile1.0.pdf',
+        'planet_profile1.0.png',
+        'planet_profile1.0.txt',
+    ]
+    assert list((fake_root / 'output').iterdir()) == []
+    assert list(cwd.iterdir()) == []
+
+
+@pytest.mark.usefixtures('fake_solver')
+def test_post_processing_without_output_dir_keeps_the_root_output(fake_root):
+    """A library call without the key writes the same files into <root>/output."""
+    output_mod.post_processing(_plotting_config())
+    assert sorted(p.name for p in (fake_root / 'output').iterdir()) == [
+        'calculated_planet_mass_radius.txt',
+        'mantle_PT_profile.pdf',
+        'planet_profile.png',
+        'planet_profile.txt',
+    ]
+    assert 'output_dir' not in _plotting_config()
+
+
+@pytest.mark.usefixtures('fake_solver')
+def test_summary_appends_in_output_dir(fake_root, tmp_path):
+    """Two calls append 2 rows under one header in <output_dir>/calculated_planet_mass_radius.txt."""
+    run = tmp_path / 'run'
+    run.mkdir()
+    for _ in range(2):
+        output_mod.post_processing(_base_config(output_dir=run))
+    lines = (run / 'calculated_planet_mass_radius.txt').read_text().splitlines()
+    assert lines[0] == 'Calculated Mass (kg)\tCalculated Radius (m)'
+    assert len(lines) == 3
+    assert not (fake_root / 'output' / 'calculated_planet_mass_radius.txt').exists()
+
+
+@pytest.mark.parametrize(
+    'id_mass, name', [(None, 'mantle_PT_profile.pdf'), ('7', 'mantle_PT_profile7.pdf')]
+)
+def test_mantle_pt_plot_takes_the_id_mass_and_the_folder(fake_root, tmp_path, id_mass, name):
+    """The P-T plot is named like the profiles (id_mass suffix) and written into the given folder."""
+    r = np.linspace(3.5e6, 6.4e6, 20)
+    phases = ['solid_mantle'] * 10 + ['melted_mantle'] * 10
+    plot_phase_vs_radius.plot_PT_with_phases(
+        np.linspace(1.3e11, 1e5, 20),
+        np.linspace(4000, 1500, 20),
+        r,
+        phases,
+        3.5e6,
+        id_mass=id_mass,
+        output_dir=tmp_path,
+    )
+    assert (tmp_path / name).is_file()
+    assert list((fake_root / 'output').iterdir()) == []
+
+
+class TestOutputDirValidation:
+    """The optional output_dir: a folder that exists, or absent."""
+
+    @pytest.mark.parametrize(
+        'value', [123, True, ['x'], b'/tmp'], ids=['int', 'bool', 'list', 'bytes']
+    )
+    def test_wrong_type_is_refused_by_name(self, value):
+        """A value that is not a path string raises ValueError naming the key and the value."""
+        with pytest.raises(ValueError, match='output_dir') as err:
+            validate_config(_make_minimal_config(output_dir=value))
+        assert repr(value) in str(err.value)
+
+    def test_empty_values_are_refused_by_name(self):
+        """'' and Path('') (which is '.') are refused as empty; a blank name is no folder."""
+        for value in ('', Path('')):
+            with pytest.raises(ValueError, match='output_dir must not be empty'):
+                validate_config(_make_minimal_config(output_dir=value))
+        with pytest.raises(ValueError, match='is not an existing folder'):
+            validate_config(_make_minimal_config(output_dir=' '))
+
+    def test_missing_folder_is_refused_and_not_created(self, tmp_path):
+        """A path that is not an existing folder raises ValueError naming it; nothing is created."""
+        missing = tmp_path / 'not_there'
+        with pytest.raises(ValueError, match='output_dir.*not_there'):
+            validate_config(_make_minimal_config(output_dir=str(missing)))
+        assert not missing.exists()
+
+    def test_existing_folder_and_absent_key_pass(self, tmp_path):
+        """An existing folder (str or Path), '.' and a config without the key validate."""
+        for value in (str(tmp_path), tmp_path, '.'):
+            assert validate_config(_make_minimal_config(output_dir=value)) is None
+        assert validate_config(_make_minimal_config()) is None
+
+
+@settings(max_examples=60, deadline=None)
+@given(
+    st.one_of(
+        st.none(),
+        st.booleans(),
+        st.integers(),
+        st.floats(allow_nan=True, allow_infinity=True),
+        st.lists(st.text(max_size=3), max_size=2),
+        st.dictionaries(st.text(max_size=2), st.integers(), max_size=1),
+        st.binary(max_size=4),
+    )
+)
+def test_any_non_path_output_dir_is_refused(value):
+    """None, bool, int, float (0, negative, NaN, inf) and containers raise ValueError."""
+    with pytest.raises(ValueError, match='output_dir must be a folder path'):
+        validate_config(_make_minimal_config(output_dir=value))
+
+
+@settings(
+    max_examples=60, deadline=None, suppress_health_check=[HealthCheck.function_scoped_fixture]
+)
+@given(st.text(alphabet='abcXYZ019_- .', min_size=1, max_size=12))
+def test_any_output_dir_that_is_not_a_folder_is_refused(tmp_path, name):
+    """A name under a missing folder, and a regular file, raise ValueError; nothing is created."""
+    with pytest.raises(ValueError, match='is not an existing folder'):
+        validate_config(_make_minimal_config(output_dir=os.path.join(tmp_path, 'absent', name)))
+    afile = tmp_path / 'a_file.txt'
+    afile.write_text('x')
+    with pytest.raises(ValueError, match='is not an existing folder'):
+        validate_config(_make_minimal_config(output_dir=str(afile)))
+    assert sorted(p.name for p in tmp_path.iterdir()) == ['a_file.txt']
+
+
+def test_output_dir_set_in_the_toml_reaches_the_config(tmp_path):
+    """A folder named in [Output] is in the returned dict; without the line the key is absent."""
+    from zalmoxis import get_zalmoxis_root
+    from zalmoxis.config import load_zalmoxis_config
+
+    text = open(os.path.join(get_zalmoxis_root(), 'input', 'default.toml')).read()
+    assert text.count('[Output]\n') == 1
+    run = tmp_path / 'run'
+    run.mkdir()
+    for line, name in ((f"output_dir = '{run}'", 'with.toml'), ('', 'without.toml')):
+        (tmp_path / name).write_text(text.replace('[Output]\n', f'[Output]\n{line}\n'))
+    assert load_zalmoxis_config(str(tmp_path / 'with.toml'))['output_dir'] == str(run)
+    assert 'output_dir' not in load_zalmoxis_config(str(tmp_path / 'without.toml'))
+
+
+@pytest.fixture
+def reset_logging():
+    """Restore the root logger handlers and level after a runpy CLI call."""
+    logger = logging.getLogger()
+    saved, level = list(logger.handlers), logger.level
+    yield
+    for h in list(logger.handlers):
+        logger.removeHandler(h)
+        h.close()
+    for h in saved:
+        logger.addHandler(h)
+    logger.setLevel(level)
+
+
+def _run_cli(root, config):
+    """Run ``python -m zalmoxis`` with a loader that logs one line and returns ``config``."""
+
+    def load():
+        logging.getLogger('zalmoxis.config').info('loading the test config')
+        return config
+
+    with patch('zalmoxis.get_zalmoxis_root', return_value=str(root)):
+        with patch('zalmoxis.config.load_zalmoxis_config', side_effect=load):
+            with patch('zalmoxis.output.post_processing') as post:
+                runpy.run_module('zalmoxis', run_name='__main__')
+    return post
+
+
+@pytest.mark.parametrize('given_dir', [True, False], ids=['output_dir-given', 'root-default'])
+def test_cli_log_and_post_processing_follow_the_output_folder(
+    tmp_path, reset_logging, given_dir
+):
+    """The CLI log, with the lines of the config load, goes to output_dir or to <root>/output."""
+    root, run = tmp_path / 'root', tmp_path / 'run'
+    (root / 'output').mkdir(parents=True)
+    run.mkdir()
+    config = {'output_dir': str(run)} if given_dir else {}
+    post = _run_cli(root, config)
+    folder = run if given_dir else root / 'output'
+    assert post.call_args.args[0]['output_dir'] == str(folder)
+    assert 'loading the test config' in (folder / 'zalmoxis.log').read_text()
+    other = root / 'output' if given_dir else run
+    assert list(other.iterdir()) == []

From 1d66d816d50350c33e1b635794af6cda9798ce44 Mon Sep 17 00:00:00 2001
From: timlichtenberg <lichtenberg.tim@gmail.com>
Date: Sun, 8 Nov 2026 02:21:17 +0100
Subject: [PATCH 02/14] Write the standalone output files into an optional
 [Output] output_dir

post_processing, the profile plot, the mantle P-T plot and the log of python -m zalmoxis write into output_dir when the config names it, an existing folder (the validator refuses other types, an empty value and a missing folder). Without the key a library call keeps <root>/output and the CLI sets that folder. The CLI holds the log lines of the config load in memory until the folder is known. The mantle P-T plot carries id_mass in its file name, as the profiles do.
---
 AGENTS.md                                  |  2 +-
 docs/How-to/configuration.md               |  3 ++-
 docs/How-to/usage.md                       |  8 ++++---
 input/default.toml                         |  1 +
 src/zalmoxis/__main__.py                   | 19 ++++++++++-----
 src/zalmoxis/config.py                     | 15 ++++++++++++
 src/zalmoxis/output.py                     | 17 +++++++-------
 src/zalmoxis/plots/plot_phase_vs_radius.py | 11 +++++++--
 src/zalmoxis/plots/plot_profiles.py        |  9 +++++---
 tests/test_main_cli.py                     | 27 +---------------------
 tests/test_output.py                       | 11 ++++++---
 11 files changed, 69 insertions(+), 54 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 9cd6ac0e..1818fdfc 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -128,7 +128,7 @@ The `[project.scripts]` entry in `pyproject.toml` registers `zalmoxis` as
 `zalmoxis.solver:main`. This bypasses `load_zalmoxis_config()` and is useful
 mainly for in-process callers; humans should prefer `python -m zalmoxis`.
 
-Outputs (under `output/`):
+Outputs (under `output/`, or the existing folder `[Output] output_dir` names):
 
 - `planet_profile.txt`: six-column TSV with r, ρ, M(r), P(r), g(r), T(r).
 - `calculated_planet_mass_radius.txt`: appended one-line summary per run.
diff --git a/docs/How-to/configuration.md b/docs/How-to/configuration.md
index 85e52746..7d8f2fdd 100644
--- a/docs/How-to/configuration.md
+++ b/docs/How-to/configuration.md
@@ -482,7 +482,8 @@ Controls what the model writes after a run.
 
 | Parameter | Type | Default | Description |
 |---|---|---|---|
-| `data_enabled` | bool | true | Write the computed radial profiles (radius, density, gravity, pressure, temperature, enclosed mass) to a text file in `output/`. |
+| `data_enabled` | bool | true | Write the computed radial profiles (radius, density, gravity, pressure, temperature, enclosed mass) to a text file in the output folder. |
 | `plots_enabled` | bool | false | Generate profile plots after the run. |
+| `output_dir` | string | absent | Output folder: an existing folder for the profiles, the mass-radius summary, the plots and the log of `python -m zalmoxis`. Absent: `output/` of the Zalmoxis root, created on the first run. An empty string or a folder that does not exist raises `ValueError`. |
 
 Convergence diagnostics are controlled by the Python logging level. Set `logging.getLogger('fwl.zalmoxis').setLevel(logging.DEBUG)` to see per-iteration convergence info and write iteration pressure/density profiles.
diff --git a/docs/How-to/usage.md b/docs/How-to/usage.md
index d27e0261..8e5ab6d4 100644
--- a/docs/How-to/usage.md
+++ b/docs/How-to/usage.md
@@ -14,7 +14,7 @@ Run the default configuration (1 Earth-mass planet with a PALEOS iron core and M
 python -m zalmoxis -c input/default.toml
 ```
 
-Output files appear in `output/`. The PALEOS data files must be downloaded first (see [installation](installation.md)).
+Output files appear in `output/`, or in the folder `[Output] output_dir` names. The PALEOS data files must be downloaded first (see [installation](installation.md)).
 
 ## What happens when you run Zalmoxis
 
@@ -50,7 +50,7 @@ For the full list of parameters (EOS selection, temperature modes, solver settin
 
 ## Output files
 
-All output files are written to the `output/` directory (created automatically on first run). The directory structure looks like:
+All output files are written to the output folder: the existing folder that `[Output] output_dir` names, or else `output/` of the Zalmoxis root (created on the first run). The folder looks like:
 
 ```
 output/
@@ -58,6 +58,8 @@ output/
 ├── planet_profile5.0.txt         # radial profiles (batch run, mass in filename)
 ├── calculated_planet_mass_radius.txt  # summary: mass and radius per run
 ├── planet_profile.png            # 6-panel structure plot (if plots_enabled)
+├── mantle_PT_profile.pdf         # mantle P-T plot (if plots_enabled and the mantle EOS uses melting curves)
+├── zalmoxis.log                  # log of python -m zalmoxis
 ├── grid_results/                 # grid runner output (if using run_grid)
 │   ├── grid_summary.csv
 │   └── *.json
@@ -115,7 +117,7 @@ When `plots_enabled = true` in the `[Output]` section, Zalmoxis automatically ge
 plots_enabled = true
 ```
 
-This produces a six-panel figure showing the radial profiles of density, pressure, temperature, gravity, phase state, and mass enclosed:
+With a batch run the plot files carry the mass in their names, as the profiles do (`planet_profile5.0.png`, `mantle_PT_profile5.0.pdf`). This produces a six-panel figure showing the radial profiles of density, pressure, temperature, gravity, phase state, and mass enclosed:
 
 ![Example profile plot](../img/example_profile_plot.png)
 
diff --git a/input/default.toml b/input/default.toml
index a6cf9f28..706be0d1 100644
--- a/input/default.toml
+++ b/input/default.toml
@@ -147,3 +147,4 @@ target_surface_pressure    = 101325 	# Target surface pressure (Pa); default 1 a
 [Output]
 data_enabled               = true 		# Write radial profiles to output/
 plots_enabled              = false 		# Generate profile plots after the run
+# output_dir               = '/path/to/folder'	# Output folder (an existing folder); default output/ of the Zalmoxis root
diff --git a/src/zalmoxis/__main__.py b/src/zalmoxis/__main__.py
index 67809646..e7172d8d 100644
--- a/src/zalmoxis/__main__.py
+++ b/src/zalmoxis/__main__.py
@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import logging
+import logging.handlers
 import os
 
 from . import get_zalmoxis_root
@@ -10,11 +11,17 @@
 if __name__ == '__main__':
     root = get_zalmoxis_root()
 
-    logging.basicConfig(
-        filename=os.path.join(root, 'output', 'zalmoxis.log'),
-        level=logging.INFO,
-        format='%(asctime)s - %(levelname)s - %(message)s',
-        filemode='w',
-    )
+    # The log goes to the output folder of the config, so the lines of the config load wait in memory.
+    log = logging.getLogger()
+    early = logging.handlers.MemoryHandler(capacity=10_000, flushLevel=logging.CRITICAL + 1)
+    log.addHandler(early)
+    log.setLevel(logging.INFO)
     config_params = load_zalmoxis_config()
+    output_dir = config_params.setdefault('output_dir', os.path.join(root, 'output'))
+    log_file = logging.FileHandler(os.path.join(output_dir, 'zalmoxis.log'), mode='w')
+    log_file.setFormatter(logging.Formatter('%(asctime)s - %(levelname)s - %(message)s'))
+    early.setTarget(log_file)
+    early.close()
+    log.removeHandler(early)
+    log.addHandler(log_file)
     post_processing(config_params)
diff --git a/src/zalmoxis/config.py b/src/zalmoxis/config.py
index 2c6f2401..5059faa1 100644
--- a/src/zalmoxis/config.py
+++ b/src/zalmoxis/config.py
@@ -712,6 +712,19 @@ def validate_config(config_params):
                 f'fractions may converge but are outside the tested range.'
             )
 
+    if 'output_dir' in config_params:
+        _check_folder('output_dir', config_params['output_dir'])
+
+
+def _check_folder(key, folder):
+    """Raise ValueError unless ``folder`` names an existing folder (a str or os.PathLike)."""
+    if not isinstance(folder, str | os.PathLike):
+        raise ValueError(f'{key} must be a folder path, got {folder!r}.')
+    if not os.fspath(folder) or (not isinstance(folder, str) and os.fspath(folder) == '.'):
+        raise ValueError(f'{key} must not be empty; leave it out for the default folder.')
+    if not os.path.isdir(folder):
+        raise ValueError(f'{key} {os.fspath(folder)!r} is not an existing folder.')
+
 
 def choose_config_file(temp_config_path=None):
     """
@@ -835,6 +848,8 @@ def load_zalmoxis_config(temp_config_path=None):
         'data_output_enabled': config['Output'].get('data_enabled', True),
         'plotting_enabled': config['Output'].get('plots_enabled', False),
     }
+    if 'output_dir' in config['Output']:
+        config_params['output_dir'] = config['Output']['output_dir']
 
     # Numerical solver params are optional in the TOML. If present, include
     # them so they override the mass-adaptive defaults in solver._solve().
diff --git a/src/zalmoxis/output.py b/src/zalmoxis/output.py
index 90981d7b..5d8c2241 100644
--- a/src/zalmoxis/output.py
+++ b/src/zalmoxis/output.py
@@ -43,6 +43,9 @@ def post_processing(config_params, id_mass=None, output_file=None, model_results
 
     data_output_enabled = config_params['data_output_enabled']
     plotting_enabled = config_params['plotting_enabled']
+    output_dir = config_params.get('output_dir')
+    if output_dir is None:
+        output_dir = os.path.join(get_zalmoxis_root(), 'output')
 
     if model_results is None:
         from .config import load_material_dictionaries
@@ -160,12 +163,7 @@ def post_processing(config_params, id_mass=None, output_file=None, model_results
             'Radius (m)\tDensity (kg/m^3)\tGravity (m/s^2)\t'
             'Pressure (Pa)\tTemperature (K)\tMass Enclosed (kg)'
         )
-        # Ensure the output directory exists. Local dev workstations
-        # typically have it from prior runs, but a fresh CI runner does
-        # not, and np.savetxt's writability probe fails there with
-        # FileNotFoundError. Creating it here keeps the writers
-        # independent of caller setup.
-        output_dir = os.path.join(get_zalmoxis_root(), 'output')
+        # A fresh checkout has no <root>/output; np.savetxt needs the folder.
         os.makedirs(output_dir, exist_ok=True)
         if id_mass is None:
             np.savetxt(
@@ -180,9 +178,7 @@ def post_processing(config_params, id_mass=None, output_file=None, model_results
                 header=header,
             )
         if output_file is None:
-            output_file = os.path.join(
-                get_zalmoxis_root(), 'output', 'calculated_planet_mass_radius.txt'
-            )
+            output_file = os.path.join(output_dir, 'calculated_planet_mass_radius.txt')
         if not os.path.exists(output_file):
             header = 'Calculated Mass (kg)\tCalculated Radius (m)'
             with open(output_file, 'w') as file:
@@ -206,6 +202,7 @@ def post_processing(config_params, id_mass=None, output_file=None, model_results
             mass_enclosed,
             id_mass,
             layer_eos_config=layer_eos_config,
+            output_dir=output_dir,
         )
 
         if uses_phase_detection:
@@ -215,4 +212,6 @@ def post_processing(config_params, id_mass=None, output_file=None, model_results
                 mantle_radii,
                 mantle_phases,
                 radii[cmb_index],
+                id_mass=id_mass,
+                output_dir=output_dir,
             )
diff --git a/src/zalmoxis/plots/plot_phase_vs_radius.py b/src/zalmoxis/plots/plot_phase_vs_radius.py
index e5d7b8c7..2dc87e83 100644
--- a/src/zalmoxis/plots/plot_phase_vs_radius.py
+++ b/src/zalmoxis/plots/plot_phase_vs_radius.py
@@ -9,7 +9,9 @@
 from zalmoxis import get_zalmoxis_root
 
 
-def plot_PT_with_phases(pressure, temperature, radii, mantle_phases, cmb_radius):
+def plot_PT_with_phases(
+    pressure, temperature, radii, mantle_phases, cmb_radius, id_mass=None, output_dir=None
+):
     """
     Plot pressure–temperature profile highlighting solid/mixed/melted mantle regions.
     Parameters:
@@ -18,6 +20,8 @@ def plot_PT_with_phases(pressure, temperature, radii, mantle_phases, cmb_radius)
     radii (array-like): Radial positions corresponding to the pressure and temperature profiles in meters.
     mantle_phases (array-like): List of mantle phases ("solid_mantle", "mixed_mantle", "melted_mantle") corresponding to each radial position.
     cmb_radius (float or None): Radius of the core-mantle boundary in meters. If None, CMB line is not plotted.
+    id_mass (str or None): Planet mass identifier, appended to the file name as for the profiles.
+    output_dir (str, os.PathLike or None): Folder of the PDF; None writes into <ZALMOXIS_ROOT>/output.
     """
 
     # Convert pressure to GPa and temperature to kK for readability
@@ -48,5 +52,8 @@ def plot_PT_with_phases(pressure, temperature, radii, mantle_phases, cmb_radius)
     ax.legend()
     ax.grid(alpha=0.3)
     plt.tight_layout()
-    plt.savefig(os.path.join(get_zalmoxis_root(), 'output', 'mantle_PT_profile.pdf'))
+    if output_dir is None:
+        output_dir = os.path.join(get_zalmoxis_root(), 'output')
+    name = 'mantle_PT_profile.pdf' if id_mass is None else f'mantle_PT_profile{id_mass}.pdf'
+    plt.savefig(os.path.join(output_dir, name))
     # plt.show()
diff --git a/src/zalmoxis/plots/plot_profiles.py b/src/zalmoxis/plots/plot_profiles.py
index 5e442e19..0cce9e3d 100644
--- a/src/zalmoxis/plots/plot_profiles.py
+++ b/src/zalmoxis/plots/plot_profiles.py
@@ -176,6 +176,7 @@ def plot_planet_profile_single(
     mass_enclosed,
     id_mass,
     layer_eos_config=None,
+    output_dir=None,
 ):
     """Generate a 6-panel interior structure plot.
 
@@ -207,6 +208,8 @@ def plot_planet_profile_single(
     layer_eos_config : dict or None
         Per-layer EOS config for phase lookup. If None, phase panel
         shows "unknown" throughout.
+    output_dir : str, os.PathLike or None
+        Folder of the PNG; None writes into ``<ZALMOXIS_ROOT>/output``.
     """
     radii_re = radii / earth_radius
     cmb_r = cmb_radius / earth_radius
@@ -317,7 +320,7 @@ def add_cmb(ax):
     fig.tight_layout(rect=[0, 0, 1, 0.96])
 
     fname = 'planet_profile.png' if id_mass is None else f'planet_profile{id_mass}.png'
-    fig.savefig(
-        os.path.join(get_zalmoxis_root(), 'output', fname), dpi=200, bbox_inches='tight'
-    )
+    if output_dir is None:
+        output_dir = os.path.join(get_zalmoxis_root(), 'output')
+    fig.savefig(os.path.join(output_dir, fname), dpi=200, bbox_inches='tight')
     plt.close(fig)
diff --git a/tests/test_main_cli.py b/tests/test_main_cli.py
index 917ad0fa..40398b0d 100644
--- a/tests/test_main_cli.py
+++ b/tests/test_main_cli.py
@@ -10,8 +10,7 @@
 several seconds and pull in EOS data), both downstream calls are
 mocked. Tests verify the CLI plumbing only:
 
-* ``get_zalmoxis_root()`` is consulted for the log path
-* logging.basicConfig is configured with the expected file path
+* the log file path is tested in ``tests/test_output_dir.py``
 * ``load_zalmoxis_config`` is invoked with no arguments
 * ``post_processing`` is invoked with the loaded config
 """
@@ -66,30 +65,6 @@ def test_main_invokes_load_then_post_process(self, tmp_path, reset_logging):
                     mock_load.assert_called_once_with()
                     mock_post.assert_called_once_with(sentinel_config)
 
-    def test_main_configures_log_file_under_zalmoxis_root(self, tmp_path, reset_logging):
-        """The log file path must be ``{ZALMOXIS_ROOT}/output/zalmoxis.log``,
-        constructed via ``os.path.join`` with the resolved root.
-
-        ``logging.basicConfig`` is a no-op once the root logger already
-        has handlers (which it does in a long pytest session), so the
-        cleanest assertion is that the CLI passes the expected
-        ``filename`` keyword to ``basicConfig`` rather than checking the
-        on-disk file."""
-        import os
-
-        with patch('zalmoxis.get_zalmoxis_root', return_value=str(tmp_path)):
-            with patch('zalmoxis.config.load_zalmoxis_config', return_value={}):
-                with patch('zalmoxis.output.post_processing'):
-                    with patch('logging.basicConfig') as mock_basicconfig:
-                        runpy.run_module('zalmoxis', run_name='__main__')
-
-        mock_basicconfig.assert_called_once()
-        kwargs = mock_basicconfig.call_args.kwargs
-        expected_filename = os.path.join(str(tmp_path), 'output', 'zalmoxis.log')
-        assert kwargs.get('filename') == expected_filename
-        assert kwargs.get('level') == logging.INFO
-        assert kwargs.get('filemode') == 'w'
-
     def test_main_does_not_swallow_load_config_errors(self, tmp_path, reset_logging):
         """If ``load_zalmoxis_config`` raises, the exception must
         propagate (no silent catch). Important for CI where a malformed
diff --git a/tests/test_output.py b/tests/test_output.py
index 6a8fb792..d220e71f 100644
--- a/tests/test_output.py
+++ b/tests/test_output.py
@@ -457,6 +457,7 @@ def _profile_mock(
             mass_enclosed,
             id_mass,
             layer_eos_config=None,
+            output_dir=None,
         ):
             profile_calls.append(
                 {
@@ -465,6 +466,7 @@ def _profile_mock(
                     'cmb_mass': float(cmb_mass),
                     'id_mass': id_mass,
                     'layer_eos_config': layer_eos_config,
+                    'output_dir': output_dir,
                 }
             )
 
@@ -486,6 +488,7 @@ def _phase_mock(*a, **k):
         c = profile_calls[0]
         assert c['radii_size'] == 60
         assert c['id_mass'] == 'earth'
+        assert c['output_dir'] == os.path.join(str(zalmoxis_tmp_root), 'output')
         assert c['cmb_mass'] == pytest.approx(1.97e24, rel=1e-12)
         # Negative branch: phase plot only fires when uses_phase_detection is True.
         assert phase_calls == []
@@ -510,8 +513,8 @@ def _fake_tdep(P, T, sol, liq):
         fake_profiles.plot_planet_profile_single = lambda *a, **k: None
         fake_phase = types.ModuleType('zalmoxis.plots.plot_phase_vs_radius')
 
-        def _phase_mock(P, T, R, phases, cmb_radius):
-            phase_calls.append({'n_pts': P.size, 'cmb_radius': float(cmb_radius)})
+        def _phase_mock(P, T, R, phases, cmb_radius, id_mass=None, output_dir=None):
+            phase_calls.append({'n_pts': P.size, 'id_mass': id_mass, 'output_dir': output_dir})
 
         fake_phase.plot_PT_with_phases = _phase_mock
         monkeypatch.setitem(sys.modules, 'zalmoxis.plots.plot_profiles', fake_profiles)
@@ -524,10 +527,12 @@ def _phase_mock(P, T, R, phases, cmb_radius):
                 'mantle': 'PALEOS-2phase:MgSiO3',
             },
         )
-        output_mod.post_processing(cfg)
+        output_mod.post_processing(cfg, id_mass='2Me')
 
         assert len(phase_calls) == 1
         assert phase_calls[0]['n_pts'] > 0
+        assert phase_calls[0]['id_mass'] == '2Me'
+        assert phase_calls[0]['output_dir'] == os.path.join(str(zalmoxis_tmp_root), 'output')
 
 
 # ---------------------------------------------------------------------------

From efe973dae80dc558e178a9f203b39a9e6d23e681 Mon Sep 17 00:00:00 2001
From: timlichtenberg <lichtenberg.tim@gmail.com>
Date: Sun, 8 Nov 2026 02:22:17 +0100
Subject: [PATCH 03/14] Test that the CLI keeps the log lines of a refused
 config

---
 tests/test_output_dir.py | 20 ++++++++++++++++++++
 1 file changed, 20 insertions(+)

diff --git a/tests/test_output_dir.py b/tests/test_output_dir.py
index f1d4f1f8..079e24c5 100644
--- a/tests/test_output_dir.py
+++ b/tests/test_output_dir.py
@@ -234,3 +234,23 @@ def test_cli_log_and_post_processing_follow_the_output_folder(
     assert 'loading the test config' in (folder / 'zalmoxis.log').read_text()
     other = root / 'output' if given_dir else run
     assert list(other.iterdir()) == []
+
+
+def test_cli_keeps_the_log_lines_of_a_refused_config(tmp_path, reset_logging):
+    """A config load that logs and then raises: the error propagates, the lines reach <root>/output."""
+    root = tmp_path / 'root'
+    (root / 'output').mkdir(parents=True)
+
+    def load():
+        logging.getLogger('zalmoxis.config').info('reading the refused config')
+        raise ValueError('output_dir must not be empty')
+
+    with patch('zalmoxis.get_zalmoxis_root', return_value=str(root)):
+        with patch('zalmoxis.config.load_zalmoxis_config', side_effect=load):
+            with patch('zalmoxis.output.post_processing') as post:
+                with pytest.raises(ValueError, match='must not be empty'):
+                    runpy.run_module('zalmoxis', run_name='__main__')
+    post.assert_not_called()
+    log = root / 'output' / 'zalmoxis.log'
+    assert log.is_file()
+    assert 'reading the refused config' in log.read_text()

From 94de85f5073fe2c08bb0912ea7b8e8619b26b3fd Mon Sep 17 00:00:00 2001
From: timlichtenberg <lichtenberg.tim@gmail.com>
Date: Sun, 8 Nov 2026 02:22:55 +0100
Subject: [PATCH 04/14] Test that the CLI creates the output folder of a fresh
 checkout for its log

---
 tests/test_output_dir.py | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/tests/test_output_dir.py b/tests/test_output_dir.py
index 079e24c5..7393d9b4 100644
--- a/tests/test_output_dir.py
+++ b/tests/test_output_dir.py
@@ -254,3 +254,15 @@ def load():
     log = root / 'output' / 'zalmoxis.log'
     assert log.is_file()
     assert 'reading the refused config' in log.read_text()
+
+
+def test_cli_creates_the_root_output_of_a_fresh_checkout(tmp_path, reset_logging):
+    """A root without output/: the CLI creates it for the log, and a refused config still raises."""
+    root = tmp_path / 'root'
+    root.mkdir()
+    with patch('zalmoxis.get_zalmoxis_root', return_value=str(root)):
+        with patch('zalmoxis.config.load_zalmoxis_config', side_effect=ValueError('refused')):
+            with pytest.raises(ValueError, match='refused'):
+                runpy.run_module('zalmoxis', run_name='__main__')
+    assert (root / 'output' / 'zalmoxis.log').is_file()
+    assert sorted(p.name for p in root.iterdir()) == ['output']

From 2ade1b25a8149ac53386c64996d72881ce34a2ff Mon Sep 17 00:00:00 2001
From: timlichtenberg <lichtenberg.tim@gmail.com>
Date: Sun, 8 Nov 2026 02:22:55 +0100
Subject: [PATCH 05/14] Keep the CLI log lines of a refused config in
 <root>/output

The buffered log lines of the config load reach <output_dir>/zalmoxis.log also when the load raises; then the folder is <root>/output, which the CLI creates on a fresh checkout so that the config error is not hidden.
---
 src/zalmoxis/__main__.py | 20 ++++++++++++--------
 1 file changed, 12 insertions(+), 8 deletions(-)

diff --git a/src/zalmoxis/__main__.py b/src/zalmoxis/__main__.py
index e7172d8d..22565c4d 100644
--- a/src/zalmoxis/__main__.py
+++ b/src/zalmoxis/__main__.py
@@ -16,12 +16,16 @@
     early = logging.handlers.MemoryHandler(capacity=10_000, flushLevel=logging.CRITICAL + 1)
     log.addHandler(early)
     log.setLevel(logging.INFO)
-    config_params = load_zalmoxis_config()
-    output_dir = config_params.setdefault('output_dir', os.path.join(root, 'output'))
-    log_file = logging.FileHandler(os.path.join(output_dir, 'zalmoxis.log'), mode='w')
-    log_file.setFormatter(logging.Formatter('%(asctime)s - %(levelname)s - %(message)s'))
-    early.setTarget(log_file)
-    early.close()
-    log.removeHandler(early)
-    log.addHandler(log_file)
+    config_params = {}
+    try:
+        config_params = load_zalmoxis_config()
+    finally:  # a refused config logs into <root>/output
+        output_dir = config_params.setdefault('output_dir', os.path.join(root, 'output'))
+        os.makedirs(output_dir, exist_ok=True)
+        log_file = logging.FileHandler(os.path.join(output_dir, 'zalmoxis.log'), mode='w')
+        log_file.setFormatter(logging.Formatter('%(asctime)s - %(levelname)s - %(message)s'))
+        early.setTarget(log_file)
+        early.close()
+        log.removeHandler(early)
+        log.addHandler(log_file)
     post_processing(config_params)

From 737a2efb836df0c4534474603675ad62171e7932 Mon Sep 17 00:00:00 2001
From: timlichtenberg <lichtenberg.tim@gmail.com>
Date: Sun, 8 Nov 2026 02:32:20 +0100
Subject: [PATCH 06/14] Test the edges of output_dir and of the CLI log

An unwritable folder is refused; post_processing checks a given folder it gets from a dict; plots alone create the default folder; a refused config keeps its error when the log cannot be opened and logs that error; the log is overwritten, formatted and at INFO; the real loader of a default.toml with output_dir sends the log there. Names at the edges replace the generated names.
---
 tests/test_output_dir.py | 152 +++++++++++++++++++++++++++++++++++----
 1 file changed, 139 insertions(+), 13 deletions(-)

diff --git a/tests/test_output_dir.py b/tests/test_output_dir.py
index 7393d9b4..b7ea95f8 100644
--- a/tests/test_output_dir.py
+++ b/tests/test_output_dir.py
@@ -9,13 +9,14 @@
 
 import logging
 import os
+import re
 import runpy
 from pathlib import Path
 from unittest.mock import patch
 
 import numpy as np
 import pytest
-from hypothesis import HealthCheck, given, settings
+from hypothesis import given, settings
 from hypothesis import strategies as st
 
 from tests.test_config_validators_extra import _make_minimal_config
@@ -161,19 +162,70 @@ def test_any_non_path_output_dir_is_refused(value):
         validate_config(_make_minimal_config(output_dir=value))
 
 
-@settings(
-    max_examples=60, deadline=None, suppress_health_check=[HealthCheck.function_scoped_fixture]
+@pytest.mark.parametrize(
+    'name, ok',
+    [
+        ('a\0b', False),
+        ('trailing ', False),
+        ('~', False),
+        ('n' * 300, False),
+        ('link', True),
+        ('rel', True),
+    ],
+    ids=['NUL', 'trailing-space', 'tilde', 'long-name', 'symlink-to-folder', 'relative'],
 )
-@given(st.text(alphabet='abcXYZ019_- .', min_size=1, max_size=12))
-def test_any_output_dir_that_is_not_a_folder_is_refused(tmp_path, name):
-    """A name under a missing folder, and a regular file, raise ValueError; nothing is created."""
-    with pytest.raises(ValueError, match='is not an existing folder'):
-        validate_config(_make_minimal_config(output_dir=os.path.join(tmp_path, 'absent', name)))
-    afile = tmp_path / 'a_file.txt'
-    afile.write_text('x')
-    with pytest.raises(ValueError, match='is not an existing folder'):
-        validate_config(_make_minimal_config(output_dir=str(afile)))
-    assert sorted(p.name for p in tmp_path.iterdir()) == ['a_file.txt']
+def test_output_dir_names_at_the_edges(tmp_path, monkeypatch, name, ok):
+    """NUL, a trailing space, '~' (not expanded) and a long name are no folder; a symlink and a relative path are."""
+    (tmp_path / 'rel').mkdir()
+    (tmp_path / 'link').symlink_to(tmp_path / 'rel')
+    monkeypatch.chdir(tmp_path)
+    cfg = _make_minimal_config(output_dir=name)
+    if ok:
+        assert validate_config(cfg) is None
+    else:
+        with pytest.raises(ValueError, match='is not an existing folder'):
+            validate_config(cfg)
+    assert sorted(p.name for p in tmp_path.iterdir()) == ['link', 'rel']
+
+
+@pytest.mark.skipif(os.geteuid() == 0, reason='root writes into a read-only folder')
+def test_output_dir_that_is_not_writable_is_refused(tmp_path):
+    """An existing folder without write permission raises ValueError naming it."""
+    ro = tmp_path / 'ro'
+    ro.mkdir()
+    ro.chmod(0o500)
+    try:
+        with pytest.raises(ValueError, match="output_dir .*ro' is not writable"):
+            validate_config(_make_minimal_config(output_dir=str(ro)))
+    finally:
+        ro.chmod(0o700)
+    assert validate_config(_make_minimal_config(output_dir=str(ro))) is None
+
+
+@pytest.mark.usefixtures('fake_solver')
+@pytest.mark.parametrize(
+    'value, match', [('', 'must not be empty'), ('missing/run', 'is not an existing folder')]
+)
+def test_post_processing_checks_a_given_output_dir(
+    fake_root, tmp_path, monkeypatch, value, match
+):
+    """A library dict that skipped validate_config: '' and a missing folder raise ValueError, nothing is made."""
+    monkeypatch.chdir(tmp_path)
+    with pytest.raises(ValueError, match=match):
+        output_mod.post_processing(_base_config(output_dir=value))
+    assert not (tmp_path / 'missing').exists()
+    assert list((fake_root / 'output').iterdir()) == []
+
+
+@pytest.mark.usefixtures('fake_solver')
+def test_plots_alone_create_the_root_output_of_a_fresh_checkout(tmp_path, monkeypatch):
+    """data_enabled false, plots on, no <root>/output: the folder is made and holds the PNG."""
+    root = tmp_path / 'root'
+    root.mkdir()
+    for mod in (output_mod, plot_profiles, plot_phase_vs_radius):
+        monkeypatch.setattr(mod, 'get_zalmoxis_root', lambda: str(root))
+    output_mod.post_processing(_base_config(data_output_enabled=False, plotting_enabled=True))
+    assert sorted(p.name for p in (root / 'output').iterdir()) == ['planet_profile.png']
 
 
 def test_output_dir_set_in_the_toml_reaches_the_config(tmp_path):
@@ -266,3 +318,77 @@ def test_cli_creates_the_root_output_of_a_fresh_checkout(tmp_path, reset_logging
                 runpy.run_module('zalmoxis', run_name='__main__')
     assert (root / 'output' / 'zalmoxis.log').is_file()
     assert sorted(p.name for p in root.iterdir()) == ['output']
+
+
+@pytest.mark.skipif(os.geteuid() == 0, reason='root writes into a read-only folder')
+def test_cli_keeps_the_config_error_when_the_log_cannot_be_opened(tmp_path, reset_logging):
+    """A refused config with a read-only <root>/output: the config error escapes, not the log error."""
+    root = tmp_path / 'root'
+    (root / 'output').mkdir(parents=True)
+    (root / 'output').chmod(0o500)
+    try:
+        with patch('zalmoxis.get_zalmoxis_root', return_value=str(root)):
+            with patch(
+                'zalmoxis.config.load_zalmoxis_config', side_effect=ValueError('refused')
+            ):
+                with pytest.raises(Exception) as err:
+                    runpy.run_module('zalmoxis', run_name='__main__')
+    finally:
+        (root / 'output').chmod(0o700)
+    assert type(err.value) is ValueError
+    assert list((root / 'output').iterdir()) == []
+
+
+def test_cli_log_names_the_error_of_a_refused_config(tmp_path, reset_logging):
+    """The log of a refused config holds the error that stopped the run."""
+    root = tmp_path / 'root'
+    (root / 'output').mkdir(parents=True)
+    with patch('zalmoxis.get_zalmoxis_root', return_value=str(root)):
+        with patch('zalmoxis.config.load_zalmoxis_config', side_effect=KeyError('planet_mass')):
+            with pytest.raises(KeyError):
+                runpy.run_module('zalmoxis', run_name='__main__')
+    text = (root / 'output' / 'zalmoxis.log').read_text()
+    assert ' - ERROR - ' in text
+    assert 'planet_mass' in text
+
+
+def test_cli_log_is_overwritten_formatted_and_at_info(tmp_path, reset_logging):
+    """An old log is replaced; each line reads '<time> - <LEVEL> - <message>'; DEBUG lines are left out."""
+    root, run = tmp_path / 'root', tmp_path / 'run'
+    (root / 'output').mkdir(parents=True)
+    run.mkdir()
+    (run / 'zalmoxis.log').write_text('OLD LINE\n')
+
+    def load():
+        logging.getLogger('fwl.zalmoxis.config').debug('a debug line')
+        logging.getLogger('fwl.zalmoxis.config').info('an info line')
+        return {'output_dir': str(run)}
+
+    with patch('zalmoxis.get_zalmoxis_root', return_value=str(root)):
+        with patch('zalmoxis.config.load_zalmoxis_config', side_effect=load):
+            with patch('zalmoxis.output.post_processing'):
+                runpy.run_module('zalmoxis', run_name='__main__')
+    lines = (run / 'zalmoxis.log').read_text().splitlines()
+    assert lines == [lines[0]] and lines[0].endswith(' - INFO - an info line')
+    assert re.fullmatch(r'\d{4}-\d\d-\d\d \d\d:\d\d:\d\d,\d{3} - INFO - an info line', lines[0])
+
+
+def test_cli_with_the_real_loader_logs_into_the_folder_of_the_toml(tmp_path, reset_logging):
+    """The real load_zalmoxis_config of a default.toml with output_dir: the log and the call go there."""
+    from zalmoxis import get_zalmoxis_root
+
+    root, run = tmp_path / 'root', tmp_path / 'run'
+    (root / 'input').mkdir(parents=True)
+    run.mkdir()
+    text = open(os.path.join(get_zalmoxis_root(), 'input', 'default.toml')).read()
+    (root / 'input' / 'default.toml').write_text(
+        text.replace('[Output]\n', f"[Output]\noutput_dir = '{run}'\n")
+    )
+    with patch('zalmoxis.get_zalmoxis_root', return_value=str(root)):
+        with patch('zalmoxis.config.get_zalmoxis_root', return_value=str(root)):
+            with patch('sys.argv', ['zalmoxis']):
+                with patch('zalmoxis.output.post_processing') as post:
+                    runpy.run_module('zalmoxis', run_name='__main__')
+    assert post.call_args.args[0]['output_dir'] == str(run)
+    assert 'Reading default config file' in (run / 'zalmoxis.log').read_text()
+    assert not (root / 'output').exists()

From 4a658d3fe08cdf634adfa01b0c8b27593c237a59 Mon Sep 17 00:00:00 2001
From: timlichtenberg <lichtenberg.tim@gmail.com>
Date: Sun, 8 Nov 2026 02:33:11 +0100
Subject: [PATCH 07/14] Refuse an unwritable output_dir and keep the config
 error of the CLI

The folder check also refuses a folder without write permission, and post_processing applies it to a given output_dir; without one it creates <root>/output for the data and the plots alike. The CLI logs the error of a refused config, logs to stderr when the folder cannot take the log, and swaps the buffer for the log file without a gap. The docs name the folder rules (relative paths, no ~ expansion, writable) and the DEBUG profile files that stay in <root>/output.
---
 AGENTS.md                    |  3 ++-
 docs/How-to/configuration.md |  2 +-
 docs/How-to/installation.md  |  2 +-
 docs/How-to/usage.md         |  6 ++++--
 docs/Tutorials/firstrun.md   |  4 ++--
 src/zalmoxis/__main__.py     | 16 +++++++++++-----
 src/zalmoxis/config.py       |  4 +++-
 src/zalmoxis/output.py       |  9 +++++----
 tests/test_main_cli.py       |  5 ++---
 9 files changed, 31 insertions(+), 20 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 1818fdfc..41832a6a 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -134,7 +134,8 @@ Outputs (under `output/`, or the existing folder `[Output] output_dir` names):
 - `calculated_planet_mass_radius.txt`: appended one-line summary per run.
 - `zalmoxis.log`: per-run log (overwritten each invocation).
 - Optional debug: `density_profiles.txt`, `pressure_profiles.txt` per Picard
-  iteration when the Python logging level is `DEBUG`.
+  iteration when the Python logging level is `DEBUG`; these two files are
+  written into `<root>/output`, not into `output_dir`.
 
 Recommended workflow:
 
diff --git a/docs/How-to/configuration.md b/docs/How-to/configuration.md
index 7d8f2fdd..e6b8ec3d 100644
--- a/docs/How-to/configuration.md
+++ b/docs/How-to/configuration.md
@@ -484,6 +484,6 @@ Controls what the model writes after a run.
 |---|---|---|---|
 | `data_enabled` | bool | true | Write the computed radial profiles (radius, density, gravity, pressure, temperature, enclosed mass) to a text file in the output folder. |
 | `plots_enabled` | bool | false | Generate profile plots after the run. |
-| `output_dir` | string | absent | Output folder: an existing folder for the profiles, the mass-radius summary, the plots and the log of `python -m zalmoxis`. Absent: `output/` of the Zalmoxis root, created on the first run. An empty string or a folder that does not exist raises `ValueError`. |
+| `output_dir` | string | absent | Output folder: an existing, writable folder for the profiles, the mass-radius summary, the plots and the log of `python -m zalmoxis`. A relative path is taken from the working directory, and `~` is not expanded. Absent: `output/` of the Zalmoxis root, created on the first run. An empty string, a folder that does not exist and a folder without write permission raise `ValueError`; the log of such a refused config goes to `output/` of the Zalmoxis root. |
 
 Convergence diagnostics are controlled by the Python logging level. Set `logging.getLogger('fwl.zalmoxis').setLevel(logging.DEBUG)` to see per-iteration convergence info and write iteration pressure/density profiles.
diff --git a/docs/How-to/installation.md b/docs/How-to/installation.md
index 4e292eb0..44306c8f 100644
--- a/docs/How-to/installation.md
+++ b/docs/How-to/installation.md
@@ -112,7 +112,7 @@ This error indicates that the tabulated EOS data files have not been downloaded.
 
 ### A `data/` link points nowhere
 
-Each folder in `data/` is a link into `$FWL_DATA`. After `fwl-io prune` removes a superseded version, or after `$FWL_DATA` moves, a link can point at a folder that no longer exists. The error names the cause, `Data file ... is missing: .../data/<folder> links to ..., which does not exist`: for an EOS table it is the first ERROR line in `output/zalmoxis.log` (the run itself stops with a `StructureSolveError`), and for a melting curve it is in the traceback. Run `bash tools/setup/get_zalmoxis.sh` again with `FWL_DATA` set: it fetches what is missing and replaces every link it made, every dangling link and every empty folder; a folder with files in it, or a link to another place, is kept and listed at the end with the line that removes it; remove it and run the script again.
+Each folder in `data/` is a link into `$FWL_DATA`. After `fwl-io prune` removes a superseded version, or after `$FWL_DATA` moves, a link can point at a folder that no longer exists. The error names the cause, `Data file ... is missing: .../data/<folder> links to ..., which does not exist`: for an EOS table it is the first ERROR line in `zalmoxis.log` of the output folder (`output/`, or `[Output] output_dir`) (the run itself stops with a `StructureSolveError`), and for a melting curve it is in the traceback. Run `bash tools/setup/get_zalmoxis.sh` again with `FWL_DATA` set: it fetches what is missing and replaces every link it made, every dangling link and every empty folder; a folder with files in it, or a link to another place, is kept and listed at the end with the line that removes it; remove it and run the script again.
 
 ### Import errors
 
diff --git a/docs/How-to/usage.md b/docs/How-to/usage.md
index 8e5ab6d4..293092c7 100644
--- a/docs/How-to/usage.md
+++ b/docs/How-to/usage.md
@@ -63,7 +63,7 @@ output/
 ├── grid_results/                 # grid runner output (if using run_grid)
 │   ├── grid_summary.csv
 │   └── *.json
-└── pressure_profiles.txt         # iteration diagnostics (if enabled)
+└── pressure_profiles.txt         # iteration diagnostics (if enabled; always in output/ of the Zalmoxis root)
 ```
 
 ### Profile files
@@ -117,10 +117,12 @@ When `plots_enabled = true` in the `[Output]` section, Zalmoxis automatically ge
 plots_enabled = true
 ```
 
-With a batch run the plot files carry the mass in their names, as the profiles do (`planet_profile5.0.png`, `mantle_PT_profile5.0.pdf`). This produces a six-panel figure showing the radial profiles of density, pressure, temperature, gravity, phase state, and mass enclosed:
+The profile plot is a six-panel figure showing the radial profiles of density, pressure, temperature, gravity, phase state, and mass enclosed:
 
 ![Example profile plot](../img/example_profile_plot.png)
 
+A call of `post_processing` with `id_mass` puts the mass label into the names of the plot files, as it does for the profiles (`planet_profile5.0.png`, `mantle_PT_profile5.0.pdf`).
+
 **Example**: 1 $M_\oplus$ planet with a PALEOS iron core and MgSiO$_3$ mantle at $T_s$ = 3000 K (adiabatic mode). The dashed vertical line marks the core-mantle boundary (CMB).
 
 - **Density** (top left): drops from ~14,000 kg/m$^3$ at the center (iron core) to ~3,000 kg/m$^3$ at the surface (silicate mantle). The sharp step at the CMB reflects the iron-to-silicate transition.
diff --git a/docs/Tutorials/firstrun.md b/docs/Tutorials/firstrun.md
index a3d17f14..495301f6 100644
--- a/docs/Tutorials/firstrun.md
+++ b/docs/Tutorials/firstrun.md
@@ -104,7 +104,7 @@ Runtime on a recent laptop is roughly 30 to 90 seconds for this configuration.
 Most of that goes into the outermost mass-radius loop; it iterates a Picard step on the central pressure until the surface mass and pressure both match their targets.
 The solver has three nested loops: a structure ODE for `(M(r), g(r), P(r))` (innermost), a density Picard iteration that re-evaluates the EOS at the new `(P, T)`, and the outer mass-radius loop just mentioned.
 
-Progress goes to `output/zalmoxis.log` (the path is hard-coded in `src/zalmoxis/__main__.py`).
+Progress goes to `output/zalmoxis.log`, or to `zalmoxis.log` in the folder `[Output] output_dir` names.
 On a successful run you should see lines along the lines of:
 
 ```console
@@ -128,7 +128,7 @@ After a successful run the `output/` directory contains:
 
 | File | Contents |
 | --- | --- |
-| `zalmoxis.log` | Run log (overwritten on every run, `filemode='w'`). |
+| `zalmoxis.log` | Run log (overwritten on every run). |
 | `planet_profile.txt` | Radial profile. Six tab-separated columns: radius (m), density (kg m$^{-3}$), gravity (m s$^{-2}$), pressure (Pa), temperature (K), enclosed mass (kg). Header line begins with `#`. |
 | `calculated_planet_mass_radius.txt` | One row appended per run: total mass (kg) and total radius (m). |
 
diff --git a/src/zalmoxis/__main__.py b/src/zalmoxis/__main__.py
index 22565c4d..e72e7d0c 100644
--- a/src/zalmoxis/__main__.py
+++ b/src/zalmoxis/__main__.py
@@ -19,13 +19,19 @@
     config_params = {}
     try:
         config_params = load_zalmoxis_config()
-    finally:  # a refused config logs into <root>/output
+    except Exception:
+        logging.getLogger('fwl.zalmoxis').exception('The config was refused.')
+        raise
+    finally:  # a refused config logs into <root>/output, an unwritable folder to stderr
         output_dir = config_params.setdefault('output_dir', os.path.join(root, 'output'))
-        os.makedirs(output_dir, exist_ok=True)
-        log_file = logging.FileHandler(os.path.join(output_dir, 'zalmoxis.log'), mode='w')
+        try:
+            os.makedirs(output_dir, exist_ok=True)
+            log_file = logging.FileHandler(os.path.join(output_dir, 'zalmoxis.log'), mode='w')
+        except OSError:
+            log_file = logging.StreamHandler()
         log_file.setFormatter(logging.Formatter('%(asctime)s - %(levelname)s - %(message)s'))
         early.setTarget(log_file)
-        early.close()
-        log.removeHandler(early)
         log.addHandler(log_file)
+        log.removeHandler(early)
+        early.close()
     post_processing(config_params)
diff --git a/src/zalmoxis/config.py b/src/zalmoxis/config.py
index 5059faa1..1eae8b1e 100644
--- a/src/zalmoxis/config.py
+++ b/src/zalmoxis/config.py
@@ -717,13 +717,15 @@ def validate_config(config_params):
 
 
 def _check_folder(key, folder):
-    """Raise ValueError unless ``folder`` names an existing folder (a str or os.PathLike)."""
+    """Raise ValueError unless ``folder`` names an existing, writable folder (str or PathLike)."""
     if not isinstance(folder, str | os.PathLike):
         raise ValueError(f'{key} must be a folder path, got {folder!r}.')
     if not os.fspath(folder) or (not isinstance(folder, str) and os.fspath(folder) == '.'):
         raise ValueError(f'{key} must not be empty; leave it out for the default folder.')
     if not os.path.isdir(folder):
         raise ValueError(f'{key} {os.fspath(folder)!r} is not an existing folder.')
+    if not os.access(folder, os.W_OK):
+        raise ValueError(f'{key} {os.fspath(folder)!r} is not writable.')
 
 
 def choose_config_file(temp_config_path=None):
diff --git a/src/zalmoxis/output.py b/src/zalmoxis/output.py
index 5d8c2241..60c7a950 100644
--- a/src/zalmoxis/output.py
+++ b/src/zalmoxis/output.py
@@ -9,7 +9,7 @@
 import numpy as np
 
 from . import get_zalmoxis_root
-from .config import _NEEDS_MELTING_CURVES, load_solidus_liquidus_functions
+from .config import _NEEDS_MELTING_CURVES, _check_folder, load_solidus_liquidus_functions
 from .constants import earth_mass, earth_radius
 from .eos import get_Tdep_material
 from .mixing import parse_layer_components
@@ -44,8 +44,11 @@ def post_processing(config_params, id_mass=None, output_file=None, model_results
     data_output_enabled = config_params['data_output_enabled']
     plotting_enabled = config_params['plotting_enabled']
     output_dir = config_params.get('output_dir')
-    if output_dir is None:
+    if output_dir is None:  # a fresh checkout has no <root>/output
         output_dir = os.path.join(get_zalmoxis_root(), 'output')
+        os.makedirs(output_dir, exist_ok=True)
+    else:
+        _check_folder('output_dir', output_dir)
 
     if model_results is None:
         from .config import load_material_dictionaries
@@ -163,8 +166,6 @@ def post_processing(config_params, id_mass=None, output_file=None, model_results
             'Radius (m)\tDensity (kg/m^3)\tGravity (m/s^2)\t'
             'Pressure (Pa)\tTemperature (K)\tMass Enclosed (kg)'
         )
-        # A fresh checkout has no <root>/output; np.savetxt needs the folder.
-        os.makedirs(output_dir, exist_ok=True)
         if id_mass is None:
             np.savetxt(
                 os.path.join(output_dir, 'planet_profile.txt'),
diff --git a/tests/test_main_cli.py b/tests/test_main_cli.py
index 40398b0d..c65d9e3a 100644
--- a/tests/test_main_cli.py
+++ b/tests/test_main_cli.py
@@ -37,6 +37,7 @@ def reset_logging():
     yield
     for h in list(logger.handlers):
         logger.removeHandler(h)
+        h.close()
     for h in saved_handlers:
         logger.addHandler(h)
     logger.setLevel(saved_level)
@@ -51,14 +52,12 @@ def test_main_invokes_load_then_post_process(self, tmp_path, reset_logging):
         return value into ``post_processing``."""
         sentinel_config = {'sentinel': 'cli-test-config'}
 
-        # Fake root so basicConfig writes to a tmp file rather than the
-        # repo's output/ directory.
+        # Fake root so the CLI log goes to a tmp folder, not the repo's output/.
         with patch('zalmoxis.get_zalmoxis_root', return_value=str(tmp_path)):
             with patch(
                 'zalmoxis.config.load_zalmoxis_config', return_value=sentinel_config
             ) as mock_load:
                 with patch('zalmoxis.output.post_processing') as mock_post:
-                    # Ensure output/ exists for basicConfig's filename
                     (tmp_path / 'output').mkdir(exist_ok=True)
                     runpy.run_module('zalmoxis', run_name='__main__')
 

From 34223f17ff82d6af40f47a7ca8c3fae31ab3b842 Mon Sep 17 00:00:00 2001
From: timlichtenberg <lichtenberg.tim@gmail.com>
Date: Sun, 8 Nov 2026 02:47:32 +0100
Subject: [PATCH 08/14] Test the folder modes, a post_processing that writes
 nothing and the log fallback warning

A folder without search permission is refused like one without write permission; post_processing with data and plots off makes no folder; the CLI warns on stderr when zalmoxis.log cannot be opened. The logging fixtures close only the handlers they added.
---
 tests/test_main_cli.py   |  3 ++-
 tests/test_output_dir.py | 50 ++++++++++++++++++++++++++++++++++------
 2 files changed, 45 insertions(+), 8 deletions(-)

diff --git a/tests/test_main_cli.py b/tests/test_main_cli.py
index c65d9e3a..021293ce 100644
--- a/tests/test_main_cli.py
+++ b/tests/test_main_cli.py
@@ -37,7 +37,8 @@ def reset_logging():
     yield
     for h in list(logger.handlers):
         logger.removeHandler(h)
-        h.close()
+        if h not in saved_handlers:
+            h.close()
     for h in saved_handlers:
         logger.addHandler(h)
     logger.setLevel(saved_level)
diff --git a/tests/test_output_dir.py b/tests/test_output_dir.py
index b7ea95f8..837e45e1 100644
--- a/tests/test_output_dir.py
+++ b/tests/test_output_dir.py
@@ -26,6 +26,7 @@
 from zalmoxis.plots import plot_phase_vs_radius, plot_profiles
 
 pytestmark = [pytest.mark.unit, pytest.mark.timeout(30)]
+_ROOT_USER = getattr(os, 'geteuid', lambda: 1)() == 0
 
 
 @pytest.fixture
@@ -188,12 +189,13 @@ def test_output_dir_names_at_the_edges(tmp_path, monkeypatch, name, ok):
     assert sorted(p.name for p in tmp_path.iterdir()) == ['link', 'rel']
 
 
-@pytest.mark.skipif(os.geteuid() == 0, reason='root writes into a read-only folder')
-def test_output_dir_that_is_not_writable_is_refused(tmp_path):
-    """An existing folder without write permission raises ValueError naming it."""
+@pytest.mark.skipif(_ROOT_USER, reason='root writes into a read-only folder')
+@pytest.mark.parametrize('mode', [0o500, 0o600, 0o200], ids=['r-x', 'rw-', '-w-'])
+def test_output_dir_that_is_not_writable_is_refused(tmp_path, mode):
+    """A folder without write or search permission (no file can be made in it) raises ValueError."""
     ro = tmp_path / 'ro'
     ro.mkdir()
-    ro.chmod(0o500)
+    ro.chmod(mode)
     try:
         with pytest.raises(ValueError, match="output_dir .*ro' is not writable"):
             validate_config(_make_minimal_config(output_dir=str(ro)))
@@ -251,7 +253,8 @@ def reset_logging():
     yield
     for h in list(logger.handlers):
         logger.removeHandler(h)
-        h.close()
+        if h not in saved:
+            h.close()
     for h in saved:
         logger.addHandler(h)
     logger.setLevel(level)
@@ -320,7 +323,7 @@ def test_cli_creates_the_root_output_of_a_fresh_checkout(tmp_path, reset_logging
     assert sorted(p.name for p in root.iterdir()) == ['output']
 
 
-@pytest.mark.skipif(os.geteuid() == 0, reason='root writes into a read-only folder')
+@pytest.mark.skipif(_ROOT_USER, reason='root writes into a read-only folder')
 def test_cli_keeps_the_config_error_when_the_log_cannot_be_opened(tmp_path, reset_logging):
     """A refused config with a read-only <root>/output: the config error escapes, not the log error."""
     root = tmp_path / 'root'
@@ -380,7 +383,7 @@ def test_cli_with_the_real_loader_logs_into_the_folder_of_the_toml(tmp_path, res
     root, run = tmp_path / 'root', tmp_path / 'run'
     (root / 'input').mkdir(parents=True)
     run.mkdir()
-    text = open(os.path.join(get_zalmoxis_root(), 'input', 'default.toml')).read()
+    text = Path(get_zalmoxis_root(), 'input', 'default.toml').read_text()
     (root / 'input' / 'default.toml').write_text(
         text.replace('[Output]\n', f"[Output]\noutput_dir = '{run}'\n")
     )
@@ -392,3 +395,36 @@ def test_cli_with_the_real_loader_logs_into_the_folder_of_the_toml(tmp_path, res
     assert post.call_args.args[0]['output_dir'] == str(run)
     assert 'Reading default config file' in (run / 'zalmoxis.log').read_text()
     assert not (root / 'output').exists()
+
+
+@pytest.mark.usefixtures('fake_solver')
+@pytest.mark.skipif(_ROOT_USER, reason='root writes into a read-only folder')
+def test_post_processing_that_writes_nothing_needs_no_folder(tmp_path, monkeypatch):
+    """Data and plots off, a read-only root: no folder is made and nothing raises."""
+    root = tmp_path / 'root'
+    root.mkdir()
+    root.chmod(0o500)
+    for mod in (output_mod, plot_profiles, plot_phase_vs_radius):
+        monkeypatch.setattr(mod, 'get_zalmoxis_root', lambda: str(root))
+    try:
+        output_mod.post_processing(_base_config(data_output_enabled=False))
+    finally:
+        root.chmod(0o700)
+    assert list(root.iterdir()) == []
+
+
+def test_cli_warns_when_the_log_file_cannot_be_opened(tmp_path, reset_logging, capsys):
+    """A folder named zalmoxis.log in output_dir: the log goes to stderr with a warning that names the file."""
+    root, run = tmp_path / 'root', tmp_path / 'run'
+    (root / 'output').mkdir(parents=True)
+    (run / 'zalmoxis.log').mkdir(parents=True)
+    with patch('zalmoxis.get_zalmoxis_root', return_value=str(root)):
+        with patch(
+            'zalmoxis.config.load_zalmoxis_config', return_value={'output_dir': str(run)}
+        ):
+            with patch('zalmoxis.output.post_processing') as post:
+                runpy.run_module('zalmoxis', run_name='__main__')
+    post.assert_called_once()
+    err = capsys.readouterr().err
+    assert ' - WARNING - ' in err
+    assert 'zalmoxis.log' in err and 'is written to stderr' in err

From d203120c1677ee5894b42cc765420d70554fc465 Mon Sep 17 00:00:00 2001
From: timlichtenberg <lichtenberg.tim@gmail.com>
Date: Sun, 8 Nov 2026 02:47:50 +0100
Subject: [PATCH 09/14] Refuse a folder without search permission and make the
 default folder only when a file is written

The folder check takes write and search permission, which a new file needs. post_processing makes <root>/output only when it writes data or plots. The CLI warns when zalmoxis.log cannot be opened and the log goes to stderr.
---
 docs/How-to/configuration.md |  2 +-
 src/zalmoxis/__main__.py     | 11 ++++++++---
 src/zalmoxis/config.py       |  2 +-
 src/zalmoxis/output.py       |  5 +++--
 4 files changed, 13 insertions(+), 7 deletions(-)

diff --git a/docs/How-to/configuration.md b/docs/How-to/configuration.md
index e6b8ec3d..8c9d9ffc 100644
--- a/docs/How-to/configuration.md
+++ b/docs/How-to/configuration.md
@@ -484,6 +484,6 @@ Controls what the model writes after a run.
 |---|---|---|---|
 | `data_enabled` | bool | true | Write the computed radial profiles (radius, density, gravity, pressure, temperature, enclosed mass) to a text file in the output folder. |
 | `plots_enabled` | bool | false | Generate profile plots after the run. |
-| `output_dir` | string | absent | Output folder: an existing, writable folder for the profiles, the mass-radius summary, the plots and the log of `python -m zalmoxis`. A relative path is taken from the working directory, and `~` is not expanded. Absent: `output/` of the Zalmoxis root, created on the first run. An empty string, a folder that does not exist and a folder without write permission raise `ValueError`; the log of such a refused config goes to `output/` of the Zalmoxis root. |
+| `output_dir` | string | absent | Output folder: an existing, writable folder for the profiles, the mass-radius summary, the plots and the log of `python -m zalmoxis`. A relative path is taken from the working directory, and `~` is not expanded. Absent: `output/` of the Zalmoxis root, created on the first run. An empty string, a folder that does not exist and a folder in which no file can be made (no write or search permission) raise `ValueError`; the log of such a refused config goes to `output/` of the Zalmoxis root, or to stderr with a warning when that folder cannot take it. |
 
 Convergence diagnostics are controlled by the Python logging level. Set `logging.getLogger('fwl.zalmoxis').setLevel(logging.DEBUG)` to see per-iteration convergence info and write iteration pressure/density profiles.
diff --git a/src/zalmoxis/__main__.py b/src/zalmoxis/__main__.py
index e72e7d0c..f978c03a 100644
--- a/src/zalmoxis/__main__.py
+++ b/src/zalmoxis/__main__.py
@@ -24,14 +24,19 @@
         raise
     finally:  # a refused config logs into <root>/output, an unwritable folder to stderr
         output_dir = config_params.setdefault('output_dir', os.path.join(root, 'output'))
+        path, failed = os.path.join(output_dir, 'zalmoxis.log'), None
         try:
             os.makedirs(output_dir, exist_ok=True)
-            log_file = logging.FileHandler(os.path.join(output_dir, 'zalmoxis.log'), mode='w')
-        except OSError:
-            log_file = logging.StreamHandler()
+            log_file = logging.FileHandler(path, mode='w')
+        except OSError as err:
+            log_file, failed = logging.StreamHandler(), err
         log_file.setFormatter(logging.Formatter('%(asctime)s - %(levelname)s - %(message)s'))
         early.setTarget(log_file)
         log.addHandler(log_file)
         log.removeHandler(early)
         early.close()
+        if failed:
+            logging.getLogger('fwl.zalmoxis').warning(
+                f'{path} cannot be opened ({failed}); the log is written to stderr.'
+            )
     post_processing(config_params)
diff --git a/src/zalmoxis/config.py b/src/zalmoxis/config.py
index 1eae8b1e..7fa6706f 100644
--- a/src/zalmoxis/config.py
+++ b/src/zalmoxis/config.py
@@ -724,7 +724,7 @@ def _check_folder(key, folder):
         raise ValueError(f'{key} must not be empty; leave it out for the default folder.')
     if not os.path.isdir(folder):
         raise ValueError(f'{key} {os.fspath(folder)!r} is not an existing folder.')
-    if not os.access(folder, os.W_OK):
+    if not os.access(folder, os.W_OK | os.X_OK):  # a new file needs write and search
         raise ValueError(f'{key} {os.fspath(folder)!r} is not writable.')
 
 
diff --git a/src/zalmoxis/output.py b/src/zalmoxis/output.py
index 60c7a950..456cf454 100644
--- a/src/zalmoxis/output.py
+++ b/src/zalmoxis/output.py
@@ -44,9 +44,10 @@ def post_processing(config_params, id_mass=None, output_file=None, model_results
     data_output_enabled = config_params['data_output_enabled']
     plotting_enabled = config_params['plotting_enabled']
     output_dir = config_params.get('output_dir')
-    if output_dir is None:  # a fresh checkout has no <root>/output
+    if output_dir is None:
         output_dir = os.path.join(get_zalmoxis_root(), 'output')
-        os.makedirs(output_dir, exist_ok=True)
+        if data_output_enabled or plotting_enabled:  # a fresh checkout has no <root>/output
+            os.makedirs(output_dir, exist_ok=True)
     else:
         _check_folder('output_dir', output_dir)
 

From 374c6e4054c4c5629517cc02c19750d980b9c4e7 Mon Sep 17 00:00:00 2001
From: timlichtenberg <lichtenberg.tim@gmail.com>
Date: Sun, 8 Nov 2026 03:04:42 +0100
Subject: [PATCH 10/14] Test a regular file as output_dir and give every
 output_dir test an assertion path

---
 tests/test_output_dir.py | 40 ++++++++++++++++++++++++++++++++--------
 1 file changed, 32 insertions(+), 8 deletions(-)

diff --git a/tests/test_output_dir.py b/tests/test_output_dir.py
index 837e45e1..130dd04f 100644
--- a/tests/test_output_dir.py
+++ b/tests/test_output_dir.py
@@ -141,7 +141,10 @@ def test_missing_folder_is_refused_and_not_created(self, tmp_path):
     def test_existing_folder_and_absent_key_pass(self, tmp_path):
         """An existing folder (str or Path), '.' and a config without the key validate."""
         for value in (str(tmp_path), tmp_path, '.'):
-            assert validate_config(_make_minimal_config(output_dir=value)) is None
+            try:
+                assert validate_config(_make_minimal_config(output_dir=value)) is None
+            except ValueError as err:
+                pytest.fail(f'{value!r} refused: {err}')
         assert validate_config(_make_minimal_config()) is None
 
 
@@ -172,13 +175,27 @@ def test_any_non_path_output_dir_is_refused(value):
         ('n' * 300, False),
         ('link', True),
         ('rel', True),
+        ('a_file', False),
+        ('an_exe', False),
+    ],
+    ids=[
+        'NUL',
+        'trailing-space',
+        'tilde',
+        'long-name',
+        'symlink-to-folder',
+        'relative',
+        'regular-file',
+        'executable-file',
     ],
-    ids=['NUL', 'trailing-space', 'tilde', 'long-name', 'symlink-to-folder', 'relative'],
 )
 def test_output_dir_names_at_the_edges(tmp_path, monkeypatch, name, ok):
-    """NUL, a trailing space, '~' (not expanded) and a long name are no folder; a symlink and a relative path are."""
+    """NUL, a trailing space, '~', a long name and files are no folder; a symlink and a relative path are."""
     (tmp_path / 'rel').mkdir()
     (tmp_path / 'link').symlink_to(tmp_path / 'rel')
+    (tmp_path / 'a_file').write_text('x')
+    (tmp_path / 'an_exe').write_text('x')
+    (tmp_path / 'an_exe').chmod(0o755)
     monkeypatch.chdir(tmp_path)
     cfg = _make_minimal_config(output_dir=name)
     if ok:
@@ -186,7 +203,7 @@ def test_output_dir_names_at_the_edges(tmp_path, monkeypatch, name, ok):
     else:
         with pytest.raises(ValueError, match='is not an existing folder'):
             validate_config(cfg)
-    assert sorted(p.name for p in tmp_path.iterdir()) == ['link', 'rel']
+    assert sorted(p.name for p in tmp_path.iterdir()) == ['a_file', 'an_exe', 'link', 'rel']
 
 
 @pytest.mark.skipif(_ROOT_USER, reason='root writes into a read-only folder')
@@ -226,7 +243,12 @@ def test_plots_alone_create_the_root_output_of_a_fresh_checkout(tmp_path, monkey
     root.mkdir()
     for mod in (output_mod, plot_profiles, plot_phase_vs_radius):
         monkeypatch.setattr(mod, 'get_zalmoxis_root', lambda: str(root))
-    output_mod.post_processing(_base_config(data_output_enabled=False, plotting_enabled=True))
+    try:
+        output_mod.post_processing(
+            _base_config(data_output_enabled=False, plotting_enabled=True)
+        )
+    except OSError as err:
+        pytest.fail(f'the plot could not be written: {err!r}')
     assert sorted(p.name for p in (root / 'output').iterdir()) == ['planet_profile.png']
 
 
@@ -241,7 +263,7 @@ def test_output_dir_set_in_the_toml_reaches_the_config(tmp_path):
     run.mkdir()
     for line, name in ((f"output_dir = '{run}'", 'with.toml'), ('', 'without.toml')):
         (tmp_path / name).write_text(text.replace('[Output]\n', f'[Output]\n{line}\n'))
-    assert load_zalmoxis_config(str(tmp_path / 'with.toml'))['output_dir'] == str(run)
+    assert load_zalmoxis_config(str(tmp_path / 'with.toml')).get('output_dir') == str(run)
     assert 'output_dir' not in load_zalmoxis_config(str(tmp_path / 'without.toml'))
 
 
@@ -285,7 +307,7 @@ def test_cli_log_and_post_processing_follow_the_output_folder(
     config = {'output_dir': str(run)} if given_dir else {}
     post = _run_cli(root, config)
     folder = run if given_dir else root / 'output'
-    assert post.call_args.args[0]['output_dir'] == str(folder)
+    assert post.call_args.args[0].get('output_dir') == str(folder)
     assert 'loading the test config' in (folder / 'zalmoxis.log').read_text()
     other = root / 'output' if given_dir else run
     assert list(other.iterdir()) == []
@@ -392,7 +414,7 @@ def test_cli_with_the_real_loader_logs_into_the_folder_of_the_toml(tmp_path, res
             with patch('sys.argv', ['zalmoxis']):
                 with patch('zalmoxis.output.post_processing') as post:
                     runpy.run_module('zalmoxis', run_name='__main__')
-    assert post.call_args.args[0]['output_dir'] == str(run)
+    assert post.call_args.args[0].get('output_dir') == str(run)
     assert 'Reading default config file' in (run / 'zalmoxis.log').read_text()
     assert not (root / 'output').exists()
 
@@ -408,6 +430,8 @@ def test_post_processing_that_writes_nothing_needs_no_folder(tmp_path, monkeypat
         monkeypatch.setattr(mod, 'get_zalmoxis_root', lambda: str(root))
     try:
         output_mod.post_processing(_base_config(data_output_enabled=False))
+    except OSError as err:
+        pytest.fail(f'a call that writes nothing touched the folder: {err!r}')
     finally:
         root.chmod(0o700)
     assert list(root.iterdir()) == []

From 7d0f15d3fcb6c7f350beafdee47bad70170a537e Mon Sep 17 00:00:00 2001
From: timlichtenberg <lichtenberg.tim@gmail.com>
Date: Sun, 8 Nov 2026 10:15:35 +0100
Subject: [PATCH 11/14] Test that the DEBUG profile dump follows the output
 folder

---
 tests/test_main_cli.py | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/tests/test_main_cli.py b/tests/test_main_cli.py
index 7a464b64..561411db 100644
--- a/tests/test_main_cli.py
+++ b/tests/test_main_cli.py
@@ -66,13 +66,16 @@ def test_main_invokes_load_then_post_process(self, tmp_path, reset_logging):
                     mock_post.assert_called_once_with(sentinel_config)
 
     def test_main_passes_its_output_folder_for_the_debug_dump(self, tmp_path, reset_logging):
-        """The CLI keeps its DEBUG profile dump in {ZALMOXIS_ROOT}/output, unless the config names one."""
+        """The CLI writes its DEBUG profile dump into its output folder, unless the config names one."""
         import os
 
         (tmp_path / 'output').mkdir(exist_ok=True)
+        own = str(tmp_path / 'own')
         for loaded, want in (
             ({}, os.path.join(str(tmp_path), 'output')),
+            ({'output_dir': own}, own),
             ({'debug_profile_dir': 'x'}, 'x'),
+            ({'output_dir': own, 'debug_profile_dir': 'x'}, 'x'),
         ):
             with patch('zalmoxis.get_zalmoxis_root', return_value=str(tmp_path)):
                 with patch('zalmoxis.config.load_zalmoxis_config', return_value=dict(loaded)):

From c780566cd4890c689e9bd9bbb2f95497f51b7227 Mon Sep 17 00:00:00 2001
From: timlichtenberg <lichtenberg.tim@gmail.com>
Date: Sun, 8 Nov 2026 10:17:57 +0100
Subject: [PATCH 12/14] Write the DEBUG profile dump of the command-line run
 into its output folder

Without debug_profile_dir, python -m zalmoxis sets it to output_dir, so a DEBUG run keeps every file of the run in one folder.
---
 AGENTS.md                    | 2 +-
 docs/How-to/configuration.md | 2 +-
 docs/How-to/usage.md         | 2 +-
 src/zalmoxis/__main__.py     | 2 +-
 4 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index f0b33967..96cda13f 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -135,7 +135,7 @@ Outputs (under `output/`, or the existing folder `[Output] output_dir` names):
 - `zalmoxis.log`: per-run log (overwritten each invocation).
 - Optional debug: `density_profiles.txt`, `pressure_profiles.txt` per Picard
   iteration when the Python logging level is `DEBUG`, into the folder that the
-  config key `debug_profile_dir` names (the command-line run uses `output/`).
+  config key `debug_profile_dir` names (the command-line run uses its output folder, `output_dir`).
 
 Recommended workflow:
 
diff --git a/docs/How-to/configuration.md b/docs/How-to/configuration.md
index 3b2fe7fa..830dcd27 100644
--- a/docs/How-to/configuration.md
+++ b/docs/How-to/configuration.md
@@ -484,7 +484,7 @@ Controls what the model writes after a run.
 |---|---|---|---|
 | `data_enabled` | bool | true | Write the computed radial profiles (radius, density, gravity, pressure, temperature, enclosed mass) to a text file in the output folder. |
 | `plots_enabled` | bool | false | Generate profile plots after the run. |
-| `debug_profile_dir` | string | not set | Existing folder for the iteration pressure and density profiles of a `DEBUG` run. Not set: no profile file (the command-line run uses `output/`). `load_zalmoxis_config` and `validate_config` raise `ValueError` on a wrong type, an empty string or `Path('')`, or a missing folder. |
+| `debug_profile_dir` | string | not set | Existing folder for the iteration pressure and density profiles of a `DEBUG` run. Not set: no profile file (the command-line run uses its output folder, `output_dir`). `load_zalmoxis_config` and `validate_config` raise `ValueError` on a wrong type, an empty string or `Path('')`, or a missing folder. |
 | `output_dir` | string | absent | Output folder: an existing, writable folder for the profiles, the mass-radius summary, the plots and the log of `python -m zalmoxis`. A relative path is taken from the working directory, and `~` is not expanded. Absent: `output/` of the Zalmoxis root, created on the first run. An empty string, a folder that does not exist and a folder in which no file can be made (no write or search permission) raise `ValueError`; the log of such a refused config goes to `output/` of the Zalmoxis root, or to stderr with a warning when that folder cannot take it. |
 
 Convergence diagnostics are controlled by the Python logging level. Set `logging.getLogger('fwl.zalmoxis').setLevel(logging.DEBUG)` to see per-iteration convergence info; with `debug_profile_dir` set, the run also writes the iteration pressure and density profiles.
diff --git a/docs/How-to/usage.md b/docs/How-to/usage.md
index a272fa91..a06ea1cd 100644
--- a/docs/How-to/usage.md
+++ b/docs/How-to/usage.md
@@ -105,7 +105,7 @@ When the Python logging level is set to `DEBUG` and the configuration names a fo
 - **`pressure_profiles.txt`**: Pressure vs. radius for every iteration of the pressure adjustment loop.
 - **`density_profiles.txt`**: Density vs. radius for every iteration.
 
-Enable with `logging.getLogger('fwl.zalmoxis').setLevel(logging.DEBUG)`. Set `debug_profile_dir` in the `[Output]` table of the TOML file, or as a key of the configuration dict that you pass to `solver.main()`; it must name a folder that exists. `load_zalmoxis_config` checks the key; `solver.main()` does not, so call `validate_config` on a dict that you build yourself. The command-line run (`python -m zalmoxis`) sets the key to `output/` when it is not set; it logs at `INFO`, so it writes the files only when the level of `fwl.zalmoxis` is `DEBUG`. Without the key, a `DEBUG` solve logs and writes no profile file. These files are useful for diagnosing convergence behavior. They grow large quickly (about 50 MB each for a 1 Earth-mass planet). The files start again at the first pressure solve of each structure solve (each call of `_solve`, so each Newton step and each retry of `solver.main()`), so after a run they hold the last structure solve; a later run below `DEBUG` or without the key leaves them as they are.
+Enable with `logging.getLogger('fwl.zalmoxis').setLevel(logging.DEBUG)`. Set `debug_profile_dir` in the `[Output]` table of the TOML file, or as a key of the configuration dict that you pass to `solver.main()`; it must name a folder that exists. `load_zalmoxis_config` checks the key; `solver.main()` does not, so call `validate_config` on a dict that you build yourself. The command-line run (`python -m zalmoxis`) sets the key to its output folder, `output_dir`, when it is not set; it logs at `INFO`, so it writes the files only when the level of `fwl.zalmoxis` is `DEBUG`. Without the key, a `DEBUG` solve logs and writes no profile file. These files are useful for diagnosing convergence behavior. They grow large quickly (about 50 MB each for a 1 Earth-mass planet). The files start again at the first pressure solve of each structure solve (each call of `_solve`, so each Newton step and each retry of `solver.main()`), so after a run they hold the last structure solve; a later run below `DEBUG` or without the key leaves them as they are.
 
 Adjust `tolerance_outer`, `tolerance_inner`, `max_iterations_outer`, `max_iterations_inner` in the `[IterativeProcess]` block (see [Configuration](configuration.md#iterativeprocess)) if convergence is slow.
 
diff --git a/src/zalmoxis/__main__.py b/src/zalmoxis/__main__.py
index 042fcd73..1cb4e453 100644
--- a/src/zalmoxis/__main__.py
+++ b/src/zalmoxis/__main__.py
@@ -39,5 +39,5 @@
             logging.getLogger('fwl.zalmoxis').warning(
                 f'{path} cannot be opened ({failed}); the log is written to stderr.'
             )
-    config_params.setdefault('debug_profile_dir', os.path.join(root, 'output'))
+    config_params.setdefault('debug_profile_dir', output_dir)
     post_processing(config_params)

From eb8c4189a784b5ff457b5603619b3e4ffb28d0ff Mon Sep 17 00:00:00 2001
From: timlichtenberg <lichtenberg.tim@gmail.com>
Date: Sun, 8 Nov 2026 10:17:57 +0100
Subject: [PATCH 13/14] Cite the EOS and melting curve sources as footnotes

The configuration reference and the first-run tutorial cite each paper as Author (year) with a footnote that gives the authors, title, journal, volume, pages, year, DOI and SciX link. The PALEOS liquidus row cites Belonoshko et al. (2005) in Physical Review Letters and Fei et al. (2021) in Nature Communications, the papers that the PALEOS tables use.
---
 docs/How-to/configuration.md | 66 +++++++++++++++++++++---------------
 docs/Tutorials/firstrun.md   | 20 ++++++-----
 2 files changed, 51 insertions(+), 35 deletions(-)

diff --git a/docs/How-to/configuration.md b/docs/How-to/configuration.md
index 830dcd27..bb9aa9aa 100644
--- a/docs/How-to/configuration.md
+++ b/docs/How-to/configuration.md
@@ -26,7 +26,7 @@ Initial guesses and assumptions for the planetary structure.
 
 | Parameter | Type | Unit | Validated range | Description |
 |---|---|---|---|---|
-| `core_mass_fraction` | float | -- | 0.01 to 0.999 | Core mass as a fraction of total mass. Also used in the Seager et al. (2007) scaling relation for the initial radius guess. Earth: ~0.325. Extreme values (pure iron at 0.999, pure rock at 0.01) converge. |
+| `core_mass_fraction` | float | -- | 0.01 to 0.999 | Core mass as a fraction of total mass. Also used in the Seager et al. (2007)[^cite-seager2007] scaling relation for the initial radius guess. Earth: ~0.325. Extreme values (pure iron at 0.999, pure rock at 0.01) converge. |
 | `mantle_mass_fraction` | float | -- | 0 to 0.99 | Mantle mass as a fraction of total mass. Set to 0 for a 2-layer model where the mantle fills the remainder (1 - `core_mass_fraction`). Must be > 0 when using a 3-layer model with an ice layer. |
 | `temperature_mode` | string | -- | -- | Temperature profile type. One of: `"isothermal"`, `"linear"`, `"prescribed"`, `"adiabatic"`. See [Temperature profiles](#temperature-profiles). |
 | `surface_temperature` | float | K | 300 to 5000 | Surface temperature. Used when `temperature_mode` is `"isothermal"`, `"linear"`, or `"adiabatic"`. Validated across 300-5000 K for all compositions. Values above 5000 K produce a warning. |
@@ -100,24 +100,24 @@ Rules:
 
 | EOS string | Source | Composition | Temperature | Data files required | Notes |
 |---|---|---|---|---|---|
-| `Seager2007:iron` | [Seager et al. (2007)](https://iopscience.iop.org/article/10.1086/521346) | Fe (epsilon phase) | Fixed 300 K | Yes | Vinet EOS + DFT, tabulated $\rho(P)$. |
-| `Seager2007:MgSiO3` | [Seager et al. (2007)](https://iopscience.iop.org/article/10.1086/521346) | MgSiO3 perovskite | Fixed 300 K | Yes | 4th-order Birch-Murnaghan + DFT, tabulated $\rho(P)$. |
-| `Seager2007:H2O` | [Seager et al. (2007)](https://iopscience.iop.org/article/10.1086/521346) | Water ice (phases VII, VIII, X) | Fixed 300 K | Yes | Experimental + DFT, tabulated $\rho(P)$. |
-| `WolfBower2018:MgSiO3` | [Wolf & Bower (2018)](https://www.sciencedirect.com/science/article/pii/S0031920117301449) | MgSiO3 (melt + solid) | T-dependent | Yes | RTpress EOS with phase-aware melting (solid EOS derived from [Mosenfelder et al. 2009](https://doi.org/10.1029/2008JB005900)). **Limited to $\leq 7\,M_\oplus$** (table max ~1 TPa; out-of-bounds pressures clamped; $T$ outside 0 to 16500 K raises an error; beyond the valid $T$ band of a pressure the band-edge density, see EOS physics). Requires `temperature_mode` configuration. Uses [Monteux et al.](https://doi.org/10.1016/j.epsl.2016.05.010) solidus/liquidus curves. |
-| `RTPress100TPa:MgSiO3` | Extended RTpress melt table | MgSiO3 (melt + solid) | T-dependent | Yes | Extended melt EOS to 100 TPa ($P$: $10^3$ to $10^{14}$ Pa, $T$: 400 to 50000 K). Solid phase uses [Wolf & Bower (2018)](https://www.sciencedirect.com/science/article/pii/S0031920117301449) table (clamped at 1 TPa, band-edge fill as for `WolfBower2018:MgSiO3`). **Limited to $\leq 50\,M_\oplus$**. Requires `temperature_mode` configuration. |
+| `Seager2007:iron` | Seager et al. (2007)[^cite-seager2007] | Fe (epsilon phase) | Fixed 300 K | Yes | Vinet EOS + DFT, tabulated $\rho(P)$. |
+| `Seager2007:MgSiO3` | Seager et al. (2007)[^cite-seager2007] | MgSiO3 perovskite | Fixed 300 K | Yes | 4th-order Birch-Murnaghan + DFT, tabulated $\rho(P)$. |
+| `Seager2007:H2O` | Seager et al. (2007)[^cite-seager2007] | Water ice (phases VII, VIII, X) | Fixed 300 K | Yes | Experimental + DFT, tabulated $\rho(P)$. |
+| `WolfBower2018:MgSiO3` | Wolf & Bower (2018)[^cite-wolf2018] | MgSiO3 (melt + solid) | T-dependent | Yes | RTpress EOS with phase-aware melting (solid EOS derived from Mosenfelder et al. (2009)[^cite-mosenfelder2009]). **Limited to $\leq 7\,M_\oplus$** (table max ~1 TPa; out-of-bounds pressures clamped; $T$ outside 0 to 16500 K raises an error; beyond the valid $T$ band of a pressure the band-edge density, see EOS physics). Requires `temperature_mode` configuration. Uses the solidus and liquidus curves of Monteux et al. (2016)[^cite-monteux2016]. |
+| `RTPress100TPa:MgSiO3` | Extended RTpress melt table | MgSiO3 (melt + solid) | T-dependent | Yes | Extended melt EOS to 100 TPa ($P$: $10^3$ to $10^{14}$ Pa, $T$: 400 to 50000 K). Solid phase uses Wolf & Bower (2018)[^cite-wolf2018] table (clamped at 1 TPa, band-edge fill as for `WolfBower2018:MgSiO3`). **Limited to $\leq 50\,M_\oplus$**. Requires `temperature_mode` configuration. |
 | `PALEOS-2phase:MgSiO3` | PALEOS (Zenodo 19680050, v1.1.0) | MgSiO3 (solid + liquid) | T-dependent | Yes | Separate solid and liquid tables providing density and $\nabla_{\mathrm{ad}}$ (P: 1 bar to 100 TPa, T: 300 to 100000 K, 150 ppd log-uniform grid). Enables phase-aware adiabatic temperature profiles using nabla_ad from both phases. **Limited to $\leq 50\,M_\oplus$**. Requires `temperature_mode` configuration. |
 | `PALEOS:iron` | PALEOS (Zenodo 22776069, v1.3.0) | Fe (5 phases) | T-dependent | Yes | Unified single-file table with all stable Fe phases (alpha-bcc, delta-bcc, gamma-fcc, epsilon-hcp, liquid). P: 1 bar to 100 TPa, T: 300 to 100000 K. Phase boundary encoded in table. **Limited to $\leq 50\,M_\oplus$**. Enables T-dependent core with its own adiabat. |
 | `PALEOS:MgSiO3` | PALEOS (Zenodo 22776069, v1.3.0) | MgSiO3 (6 phases) | T-dependent | Yes | Unified single-file table with all stable MgSiO3 phases (3 pyroxene, bridgmanite, postperovskite, liquid). P: 1 bar to 100 TPa, T: 300 to 100000 K. Phase boundary encoded in table. **Limited to $\leq 50\,M_\oplus$**. |
 | `PALEOS:H2O` | PALEOS (Zenodo 22776069, v1.3.0) | H2O (7 EOS) | T-dependent | Yes | Unified single-file table with all stable H2O phases (ice Ih to X, liquid, vapor, superionic). P: 1 bar to 100 TPa, T: 100 to 100000 K. Phase boundary encoded in table. **Limited to $\leq 50\,M_\oplus$**. Use as `ice_layer` for 3-layer models. |
-| `Chabrier:H` | [Chabrier et al. (2019)](https://doi.org/10.3847/1538-4357/aaf99f), [Chabrier & Debras (2021)](https://doi.org/10.3847/1538-4357/abfc48) | Pure H$_2$ (molecular, atomic, ionized) | T-dependent | Yes | DirEOS2021 table for pure hydrogen. Grid: 121 $\times$ 441 ($\log T$, $\log P$), $T = 100$ to $10^8$ K, $P = 1$ Pa to $10^{22}$ Pa. Provides $\rho$, $\nabla_{\mathrm{ad}}$, $c_p$, $c_v$, $\alpha$, and phase identifier. Loaded through the same `paleos_unified` reader. Use as a mixing component in the mantle (e.g., `"PALEOS:MgSiO3:0.97+Chabrier:H:0.03"`) for sub-Neptune interiors. **No standalone mass limit** (pressure range far exceeds any planet). In H$_2$ dissociation zones ($T \sim 3000$ to $30000$ K), $\nabla_{\mathrm{ad}}$ is clamped at 0.100 in the source tables. |
-| `Analytic:iron` | [Seager et al. (2007)](https://iopscience.iop.org/article/10.1086/521346) Table 3 | Fe (epsilon) | Fixed 300 K | No | Modified polytrope: $\rho(P) = \rho_0 + c \cdot P^n$. |
-| `Analytic:MgSiO3` | [Seager et al. (2007)](https://iopscience.iop.org/article/10.1086/521346) Table 3 | MgSiO3 perovskite | Fixed 300 K | No | Modified polytrope. |
-| `Analytic:MgFeSiO3` | [Seager et al. (2007)](https://iopscience.iop.org/article/10.1086/521346) Table 3 | (Mg,Fe)SiO3 | Fixed 300 K | No | Modified polytrope. |
-| `Analytic:H2O` | [Seager et al. (2007)](https://iopscience.iop.org/article/10.1086/521346) Table 3 | Water ice | Fixed 300 K | No | Modified polytrope. |
-| `Analytic:graphite` | [Seager et al. (2007)](https://iopscience.iop.org/article/10.1086/521346) Table 3 | C (graphite) | Fixed 300 K | No | Modified polytrope. |
-| `Analytic:SiC` | [Seager et al. (2007)](https://iopscience.iop.org/article/10.1086/521346) Table 3 | Silicon carbide | Fixed 300 K | No | Modified polytrope. |
+| `Chabrier:H` | Chabrier et al. (2019)[^cite-chabrier2019], Chabrier & Debras (2021)[^cite-chabrier2021] | Pure H$_2$ (molecular, atomic, ionized) | T-dependent | Yes | DirEOS2021 table for pure hydrogen. Grid: 121 $\times$ 441 ($\log T$, $\log P$), $T = 100$ to $10^8$ K, $P = 1$ Pa to $10^{22}$ Pa. Provides $\rho$, $\nabla_{\mathrm{ad}}$, $c_p$, $c_v$, $\alpha$, and phase identifier. Loaded through the same `paleos_unified` reader. Use as a mixing component in the mantle (e.g., `"PALEOS:MgSiO3:0.97+Chabrier:H:0.03"`) for sub-Neptune interiors. **No standalone mass limit** (pressure range far exceeds any planet). In H$_2$ dissociation zones ($T \sim 3000$ to $30000$ K), $\nabla_{\mathrm{ad}}$ is clamped at 0.100 in the source tables. |
+| `Analytic:iron` | Seager et al. (2007)[^cite-seager2007] Table 3 | Fe (epsilon) | Fixed 300 K | No | Modified polytrope: $\rho(P) = \rho_0 + c \cdot P^n$. |
+| `Analytic:MgSiO3` | Seager et al. (2007)[^cite-seager2007] Table 3 | MgSiO3 perovskite | Fixed 300 K | No | Modified polytrope. |
+| `Analytic:MgFeSiO3` | Seager et al. (2007)[^cite-seager2007] Table 3 | (Mg,Fe)SiO3 | Fixed 300 K | No | Modified polytrope. |
+| `Analytic:H2O` | Seager et al. (2007)[^cite-seager2007] Table 3 | Water ice | Fixed 300 K | No | Modified polytrope. |
+| `Analytic:graphite` | Seager et al. (2007)[^cite-seager2007] Table 3 | C (graphite) | Fixed 300 K | No | Modified polytrope. |
+| `Analytic:SiC` | Seager et al. (2007)[^cite-seager2007] Table 3 | Silicon carbide | Fixed 300 K | No | Modified polytrope. |
 
-**Analytic EOS details.** The analytic options use the modified polytropic fit from Seager et al. (2007, Eq. 11, Table 3):
+**Analytic EOS details.** The analytic options use the modified polytropic fit from Seager et al. (2007, Eq. 11, Table 3)[^cite-seager2007]:
 
 $$\rho(P) = \rho_0 + c \cdot P^n$$
 
@@ -127,7 +127,7 @@ where $\rho_0$ is the zero-pressure density, $c$ and $n$ are fitted constants. T
 
 1. **Separate solid/liquid tables** (`WolfBower2018:MgSiO3`, `RTPress100TPa:MgSiO3`, `PALEOS-2phase:MgSiO3`): use separate $\rho(P, T)$ grids for solid and melt phases, with linear melt-fraction interpolation between external solidus and liquidus melting curves.
 2. **Unified PALEOS tables** (`PALEOS:iron`, `PALEOS:MgSiO3`, `PALEOS:H2O`): single file per material containing all stable phases. The thermodynamically stable phase at each $(P, T)$ is encoded in the table, and the phase boundary (liquidus) is extracted automatically. No external melting curves needed. A configurable `mushy_zone_factor` controls the width of an artificial mushy zone below the liquidus.
-3. **Chabrier H/He tables** (`Chabrier:H`): DirEOS2021 tables from [Chabrier et al. (2019)](https://doi.org/10.3847/1538-4357/aaf99f) and [Chabrier & Debras (2021)](https://doi.org/10.3847/1538-4357/abfc48). Same 10-column format as unified PALEOS. Intended for use as a mixing component in sub-Neptune mantles, combined with binodal (miscibility) suppression.
+3. **Chabrier H/He tables** (`Chabrier:H`): DirEOS2021 tables from Chabrier et al. (2019)[^cite-chabrier2019] and Chabrier & Debras (2021)[^cite-chabrier2021]. Same 10-column format as unified PALEOS. Intended for use as a mixing component in sub-Neptune mantles, combined with binodal (miscibility) suppression.
 
 When any T-dependent EOS is assigned to any layer, the `temperature_mode`, `surface_temperature`, and `center_temperature` parameters in `[AssumptionsAndInitialGuesses]` become active.
 
@@ -135,7 +135,7 @@ When any T-dependent EOS is assigned to any layer, the `temperature_mode`, `surf
 
 | Field | Required | Default | Description |
 |---|---|---|---|
-| `mushy_zone_factor` | No | `1.0` | Global default cryoscopic depression factor for all unified PALEOS tables. Controls the width of the artificial mushy (mixed solid+liquid) zone below the liquidus extracted from the table. Valid range: [0.7, 1.0]. `1.0` = no mushy zone (sharp phase boundary). `< 1.0` = solidus at this fraction of the liquidus temperature ($T_\mathrm{sol} = T_\mathrm{liq} \times f$). E.g., `0.8` gives a mushy zone similar to the Stixrude (2014) cryoscopic depression. Values below 0.7 are rejected (unphysically wide mushy zones cause solver instabilities). In the mushy zone, density is volume-averaged between solid-side and liquid-side table values. Relevant for `PALEOS:iron`, `PALEOS:MgSiO3`, `PALEOS:H2O`. For a two-phase mantle (`PALEOS-2phase:MgSiO3`) a value below 1.0 is accepted only with `rock_liquidus = "PALEOS-liquidus"`, which sets the solidus to `mushy_zone_factor * liquidus`; with the default Stixrude 2014 curves it is rejected. |
+| `mushy_zone_factor` | No | `1.0` | Global default cryoscopic depression factor for all unified PALEOS tables. Controls the width of the artificial mushy (mixed solid+liquid) zone below the liquidus extracted from the table. Valid range: [0.7, 1.0]. `1.0` = no mushy zone (sharp phase boundary). `< 1.0` = solidus at this fraction of the liquidus temperature ($T_\mathrm{sol} = T_\mathrm{liq} \times f$). E.g., `0.8` gives a mushy zone similar to the Stixrude (2014)[^cite-stixrude2014] cryoscopic depression. Values below 0.7 are rejected (unphysically wide mushy zones cause solver instabilities). In the mushy zone, density is volume-averaged between solid-side and liquid-side table values. Relevant for `PALEOS:iron`, `PALEOS:MgSiO3`, `PALEOS:H2O`. For a two-phase mantle (`PALEOS-2phase:MgSiO3`) a value below 1.0 is accepted only with `rock_liquidus = "PALEOS-liquidus"`, which sets the solidus to `mushy_zone_factor * liquidus`; with the default Stixrude 2014 curves it is rejected. |
 | `mushy_zone_factor_iron` | No | global value | Per-material override for `PALEOS:iron`. Same range and semantics as `mushy_zone_factor`. Only validated when `PALEOS:iron` is configured. |
 | `mushy_zone_factor_MgSiO3` | No | global value | Per-material override for `PALEOS:MgSiO3`. |
 | `mushy_zone_factor_H2O` | No | global value | Per-material override for `PALEOS:H2O`. |
@@ -172,8 +172,8 @@ Both parameters must be positive. The validation rejects non-positive values at
 When `Chabrier:H` is mixed with silicate or water components, an additional binodal (miscibility) suppression determines whether H$_2$ participates in the harmonic mean at each $(P, T)$ point.
 Two independent binodal models are evaluated automatically:
 
-- **H$_2$-MgSiO$_3$**: [Rogers, Young & Schlichting (2025)](https://doi.org/10.1093/mnras/staf1940) analytic binodal fit.
-- **H$_2$-H$_2$O**: [Gupta, Stixrude & Schlichting (2025)](https://doi.org/10.3847/2041-8213/adb631) Gibbs free energy model.
+- **H$_2$-MgSiO$_3$**: Rogers et al. (2025)[^cite-rogers2025] analytic binodal fit.
+- **H$_2$-H$_2$O**: Gupta et al. (2025)[^cite-gupta2025] Gibbs free energy model.
 
 Above the binodal temperature, H$_2$ is miscible with its partner and participates fully in the density calculation.
 Below the binodal, H$_2$ is suppressed via a smooth sigmoid transition.
@@ -199,16 +199,16 @@ The `rock_solidus` and `rock_liquidus` fields control which melting curves are u
 
 | Identifier | Type | Source | Notes |
 |---|---|---|---|
-| `Monteux16-solidus` | Analytic | [Monteux et al. (2016)](https://doi.org/10.1016/j.epsl.2016.05.010) Eqs. 10/12 | Default. Piecewise Simon-Glatzel, valid to ~500 GPa. |
-| `Stixrude14-solidus` | Analytic | [Stixrude (2014)](https://doi.org/10.1098/rsta.2013.0076) Eqs. 1.9+1.10 | Power law with cryoscopic depression ($x_0 = 0.79$). Valid at all $P$. |
-| `Monteux16-liquidus-A-chondritic` | Analytic | [Monteux et al. (2016)](https://doi.org/10.1016/j.epsl.2016.05.010) Eqs. 11/13 | Default. A-chondritic composition. Valid to ~500 GPa. |
-| `Monteux16-liquidus-F-peridotitic` | Analytic | [Monteux et al. (2016)](https://doi.org/10.1016/j.epsl.2016.05.010) Eqs. 11/13 | F-peridotitic composition. Valid to ~660 GPa. |
-| `Stixrude14-liquidus` | Analytic | [Stixrude (2014)](https://doi.org/10.1098/rsta.2013.0076) Eq. 1.9 | Simon-like power law for pure MgSiO$_3$. Valid at all $P$. Liquidus always above solidus (constant ratio). |
-| `PALEOS-liquidus` | Analytic | [Belonoshko et al. (2005)](https://doi.org/10.1103/PhysRevB.72.104107) / [Fei et al. (2021)](https://doi.org/10.1103/PhysRevLett.127.135701) | Piecewise Simon-Glatzel fit: Belonoshko+2005 ($P < 2.55$ GPa) / Fei+2021 ($P \geq 2.55$ GPa). This is the melting curve used internally by the PALEOS unified MgSiO$_3$ table. Use it with `PALEOS-2phase:MgSiO3` for consistency with the unified table's phase boundary. Valid at all $P$. |
-| `Monteux600-solidus-tabulated` | Tabulated | Monteux et al. (2016) with fixed 600 K gap | Legacy. Returns NaN outside table range ($P > 999$ GPa). |
-| `Monteux600-liquidus-tabulated` | Tabulated | Monteux et al. (2016) with fixed 600 K gap | Legacy. Returns NaN outside table range. |
+| `Monteux16-solidus` | Analytic | Monteux et al. (2016)[^cite-monteux2016] Eqs. 10/12 | Default. Piecewise Simon-Glatzel, valid to ~500 GPa. |
+| `Stixrude14-solidus` | Analytic | Stixrude (2014)[^cite-stixrude2014] Eqs. 1.9+1.10 | Power law with cryoscopic depression ($x_0 = 0.79$). Valid at all $P$. |
+| `Monteux16-liquidus-A-chondritic` | Analytic | Monteux et al. (2016)[^cite-monteux2016] Eqs. 11/13 | Default. A-chondritic composition. Valid to ~500 GPa. |
+| `Monteux16-liquidus-F-peridotitic` | Analytic | Monteux et al. (2016)[^cite-monteux2016] Eqs. 11/13 | F-peridotitic composition. Valid to ~660 GPa. |
+| `Stixrude14-liquidus` | Analytic | Stixrude (2014)[^cite-stixrude2014] Eq. 1.9 | Simon-like power law for pure MgSiO$_3$. Valid at all $P$. Liquidus always above solidus (constant ratio). |
+| `PALEOS-liquidus` | Analytic | Belonoshko et al. (2005)[^cite-belonoshko2005] / Fei et al. (2021)[^cite-fei2021] | Piecewise Simon-Glatzel fit: Belonoshko et al. (2005)[^cite-belonoshko2005] ($P < 2.55$ GPa) / Fei et al. (2021)[^cite-fei2021] ($P \geq 2.55$ GPa). This is the melting curve used internally by the PALEOS unified MgSiO$_3$ table. Use it with `PALEOS-2phase:MgSiO3` for consistency with the unified table's phase boundary. Valid at all $P$. |
+| `Monteux600-solidus-tabulated` | Tabulated | Monteux et al. (2016)[^cite-monteux2016] with fixed 600 K gap | Legacy. Returns NaN outside table range ($P > 999$ GPa). |
+| `Monteux600-liquidus-tabulated` | Tabulated | Monteux et al. (2016)[^cite-monteux2016] with fixed 600 K gap | Legacy. Returns NaN outside table range. |
 
-The Monteux+2016 piecewise parameterization has a solidus/liquidus crossing above ~500 GPa (beyond the experimental calibration range). The Stixrude (2014) power laws avoid this issue entirely: the cryoscopic depression produces a constant solidus/liquidus ratio, guaranteeing liquidus > solidus at all pressures. Old TOML files without `rock_solidus`/`rock_liquidus` fields use the Stixrude14 defaults.
+The Monteux et al. (2016)[^cite-monteux2016] piecewise parameterization has a solidus/liquidus crossing above ~500 GPa (beyond the experimental calibration range). The Stixrude (2014)[^cite-stixrude2014] power laws avoid this issue entirely: the cryoscopic depression produces a constant solidus/liquidus ratio, guaranteeing liquidus > solidus at all pressures. Old TOML files without `rock_solidus`/`rock_liquidus` fields use the Stixrude14 defaults.
 
 !!! warning "Mass limits for temperature-dependent EOS"
     **WolfBower2018:MgSiO3**: Tables cover pressures up to ~1 TPa. For planets above ~2 $M_\oplus$, deep-mantle pressures begin to exceed this limit. The Brent pressure solver with out-of-bounds clamping handles this gracefully up to $7\,M_\oplus$. Beyond $7\,M_\oplus$, clamped densities become unreliable and the code raises a `ValueError`. Use `RTPress100TPa:MgSiO3` or `PALEOS-2phase:MgSiO3` for higher-mass planets with a temperature-dependent mantle.
@@ -488,3 +488,15 @@ Controls what the model writes after a run.
 | `output_dir` | string | absent | Output folder: an existing, writable folder for the profiles, the mass-radius summary, the plots and the log of `python -m zalmoxis`. A relative path is taken from the working directory, and `~` is not expanded. Absent: `output/` of the Zalmoxis root, created on the first run. An empty string, a folder that does not exist and a folder in which no file can be made (no write or search permission) raise `ValueError`; the log of such a refused config goes to `output/` of the Zalmoxis root, or to stderr with a warning when that folder cannot take it. |
 
 Convergence diagnostics are controlled by the Python logging level. Set `logging.getLogger('fwl.zalmoxis').setLevel(logging.DEBUG)` to see per-iteration convergence info; with `debug_profile_dir` set, the run also writes the iteration pressure and density profiles.
+
+[^cite-seager2007]: S. Seager, M. Kuchner, C. A. Hier-Majumder, B. Militzer, *[Mass-Radius Relationships for Solid Exoplanets](https://doi.org/10.1086/521346)*, The Astrophysical Journal, 669(2), 1279-1297, 2007. [SciX](https://scixplorer.org/abs/2007ApJ...669.1279S/abstract).
+[^cite-wolf2018]: A. S. Wolf, D. J. Bower, *[An equation of state for high pressure-temperature liquids (RTpress) with application to MgSiO$_3$ melt](https://doi.org/10.1016/j.pepi.2018.02.004)*, Physics of the Earth and Planetary Interiors, 278, 59-74, 2018. [SciX](https://scixplorer.org/abs/2018PEPI..278...59W/abstract).
+[^cite-mosenfelder2009]: J. L. Mosenfelder, P. D. Asimow, D. J. Frost, D. C. Rubie, T. J. Ahrens, *[The MgSiO3 system at high pressure: Thermodynamic properties of perovskite, postperovskite, and melt from global inversion of shock and static compression data](https://doi.org/10.1029/2008JB005900)*, Journal of Geophysical Research (Solid Earth), 114(B1), B01203, 2009. [SciX](https://scixplorer.org/abs/2009JGRB..114.1203M/abstract).
+[^cite-chabrier2019]: G. Chabrier, S. Mazevet, F. Soubiran, *[A New Equation of State for Dense Hydrogen-Helium Mixtures](https://doi.org/10.3847/1538-4357/aaf99f)*, The Astrophysical Journal, 872(1), 51, 2019. [SciX](https://scixplorer.org/abs/2019ApJ...872...51C/abstract).
+[^cite-chabrier2021]: G. Chabrier, F. Debras, *[A New Equation of State for Dense Hydrogen-Helium Mixtures. II. Taking into Account Hydrogen-Helium Interactions](https://doi.org/10.3847/1538-4357/abfc48)*, The Astrophysical Journal, 917(1), 4, 2021. [SciX](https://scixplorer.org/abs/2021ApJ...917....4C/abstract).
+[^cite-stixrude2014]: L. Stixrude, *[Melting in super-earths](https://doi.org/10.1098/rsta.2013.0076)*, Philosophical Transactions of the Royal Society A: Mathematical, Physical and Engineering Sciences, 372(2014), 20130076, 2014. [SciX](https://scixplorer.org/abs/2014RSPTA.37230076S/abstract).
+[^cite-rogers2025]: J. G. Rogers, E. D. Young, H. E. Schlichting, *[Redefining interiors and envelopes: hydrogen-silicate miscibility and its consequences for the structure and evolution of sub-Neptunes](https://doi.org/10.1093/mnras/staf1940)*, Monthly Notices of the Royal Astronomical Society, 544(4), 3496-3511, 2025. [SciX](https://scixplorer.org/abs/2025MNRAS.544.3496R/abstract).
+[^cite-gupta2025]: A. Gupta, L. Stixrude, H. E. Schlichting, *[The Miscibility of Hydrogen and Water in Planetary Atmospheres and Interiors](https://doi.org/10.3847/2041-8213/adb631)*, The Astrophysical Journal Letters, 982(2), L35, 2025. [SciX](https://scixplorer.org/abs/2025ApJ...982L..35G/abstract).
+[^cite-monteux2016]: J. Monteux, D. Andrault, H. Samuel, *[On the cooling of a deep terrestrial magma ocean](https://doi.org/10.1016/j.epsl.2016.05.010)*, Earth and Planetary Science Letters, 448, 140-149, 2016. [SciX](https://scixplorer.org/abs/2016E%26PSL.448..140M/abstract).
+[^cite-belonoshko2005]: A. B. Belonoshko, N. V. Skorodumova, A. Rosengren, R. Ahuja, B. Johansson, L. Burakovsky, D. L. Preston, *[High-pressure melting of MgSiO$_3$](https://doi.org/10.1103/PhysRevLett.94.195701)*, Physical Review Letters, 94(19), 195701, 2005. [SciX](https://scixplorer.org/abs/2005PhRvL..94s5701B/abstract).
+[^cite-fei2021]: Y. Fei, C. T. Seagle, J. P. Townsend, C. A. McCoy, A. Boujibar, P. Driscoll, L. Shulenburger, M. D. Furnish, *[Melting and density of MgSiO$_3$ determined by shock compression of bridgmanite to 1254 GPa](https://doi.org/10.1038/s41467-021-21170-y)*, Nature Communications, 12, 876, 2021. [SciX](https://scixplorer.org/abs/2021NatCo..12..876F/abstract).
diff --git a/docs/Tutorials/firstrun.md b/docs/Tutorials/firstrun.md
index 495301f6..53cdafbb 100644
--- a/docs/Tutorials/firstrun.md
+++ b/docs/Tutorials/firstrun.md
@@ -1,7 +1,7 @@
 # First run
 
-This tutorial walks a 1 $M_\oplus$ rocky planet through Zalmoxis end to end.
-By the end you will have written a minimal config file, run the structure solver, plotted a radial density profile, and verified the result against the [Zeng et al. (2019)](https://ui.adsabs.harvard.edu/abs/2019PNAS..116.9723Z) Earth-like mass-radius curve and the [Seager et al. (2007)](https://ui.adsabs.harvard.edu/abs/2007ApJ...669.1279S) tabulated density profile.
+This tutorial takes a 1 $M_\oplus$ rocky planet through Zalmoxis from start to finish.
+By the end you will have written a minimal config file, run the structure solver, plotted a radial density profile, and verified the result against the Zeng et al. (2019)[^cite-zeng2019] Earth-like mass-radius curve and the Seager et al. (2007)[^cite-seager2007] tabulated density profile.
 
 You should already have Zalmoxis installed in a working conda environment.
 If not, follow [Installation](../How-to/installation.md) first; the steps below assume `python -m zalmoxis` runs without an `ImportError`.
@@ -31,7 +31,7 @@ export FWL_DATA=/path/to/fwl_data
 bash tools/setup/get_zalmoxis.sh
 ```
 
-This fetches the Seager+2007 lookups, PALEOS tables and Zeng+2019 reference curves into `$FWL_DATA`, links each folder of `data/` inside the repository to them, and creates an empty `output/` directory.
+This fetches the Seager et al. (2007)[^cite-seager2007] lookups, PALEOS tables and Zeng et al. (2019)[^cite-zeng2019] reference curves into `$FWL_DATA`, links each folder of `data/` inside the repository to them, and creates an empty `output/` directory.
 You should now see populated subdirectories under `data/`, for example `data/EOS_Seager2007/` and `data/EOS_PALEOS_iron/`.
 
 !!! note "Within PROTEUS"
@@ -81,7 +81,7 @@ A few notes on what each block does:
   `temperature_mode = "adiabatic"` integrates the layer adiabats with `surface_temperature` as the upper boundary and `center_temperature` as the initial guess for the inner boundary.
   Other choices are `"isothermal"`, `"linear"`, and `"prescribed"` (reads `temperature_profile_file`); see [Configuration](../How-to/configuration.md) for the full list.
 - `[EOS]` selects the per-layer equation of state.
-  `PALEOS:iron` and `PALEOS:MgSiO3` are unified multi-phase PALEOS tables ([Attia et al. (2026)](https://ui.adsabs.harvard.edu/abs/2026arXiv260503741A/abstract)) that handle pressures up to 100 TPa and masses up to 50 $M_\oplus$.
+  `PALEOS:iron` and `PALEOS:MgSiO3` are the unified multi-phase PALEOS tables of Attia et al. (2026)[^cite-attia2026]; they handle pressures up to 100 TPa and masses up to 50 $M_\oplus$.
   `ice_layer = ""` keeps the model two-layer (core + mantle).
 - `[Calculations]` controls the radial grid resolution.
   150 points is enough for a 3 % radius match; double it for tighter convergence at high mass.
@@ -117,7 +117,7 @@ INFO - Pressure at Center: 3.65e+11 Pa
 INFO - Overall Convergence Status: True with Pressure: True, Density: True, Mass: True
 ```
 
-Note that the "Earth radii" comparison uses Zalmoxis's reference value `earth_radius = 6.335e6` m (Seager+2007 volumetric mean), not the IAU 6.371e6 m.
+Note that the "Earth radii" comparison uses Zalmoxis's reference value `earth_radius = 6.335e6` m (the volumetric mean of Seager et al. (2007)[^cite-seager2007]), not the IAU 6.371e6 m.
 That convention is intentional and matches the Seager reference data shipped in `data/`.
 
 If the final line shows `Convergence Status: False`, see [Convergence failures](../How-to/installation.md#convergence-failures) for the standard remedies (looser tolerance, larger pressure bracket, or a different mantle EOS for high-mass configurations).
@@ -168,7 +168,7 @@ You should see a sharp density jump near $r \approx 3500$ km (the core-mantle bo
 The smoke test `tests/test_MR_rocky.py::test_rocky_1Mearth_vs_zeng_and_seager` exercises the same code path you just ran, with two reference checks bolted on.
 You can reproduce them by hand.
 
-**Mass-radius (Zeng+2019).**
+**Mass-radius after Zeng et al. (2019)[^cite-zeng2019].**
 The reference curve `data/mass_radius_curves/massradiusEarthlikeRocky.txt` is an Earth-like rocky composition (32.5 % iron core, 67.5 % MgSiO3 mantle, 300 K).
 Interpolate it at your computed mass and compare:
 
@@ -194,7 +194,7 @@ print(f'M = {m_e:.3f} M_earth, R = {r_e:.3f} R_earth, '
 The smoke test asserts `rtol = 0.03` (3 %).
 Your run should be well inside that envelope.
 
-**Density profile (Seager+2007).**
+**Density profile after Seager et al. (2007)[^cite-seager2007].**
 The file `data/radial_profiles/radiusdensitySeagerEarthbymass.txt` carries tabulated Earth-mass density profiles from the same paper.
 Loading the 1 $M_\oplus$ slice and overlaying it on your `planet_profile.txt` should match within 10 % everywhere except for a narrow band around the core-mantle boundary.
 The CMB lies between Seager's grid points, so interpolating across the discontinuity inflates the residual artificially; the smoke test masks $\pm 3$ grid points around any density jump greater than 2000 kg m$^{-3}$ before comparing.
@@ -234,7 +234,7 @@ Outputs land in `output/grid_firstrun/`:
 - `<label>.json`: per-run summary mirroring the CSV row;
 - `<label>.csv`: per-run radial profile (because `save_profiles = true`); a six-column body with SI-unit columns plus a `# key: value` comment header that records the EOS strings, melting-curve ids, and convergence flag.
 
-Filter to converged rows (`converged == True`) and overlay the three radii on the Zeng+2019 curve to check that you reproduce the expected shallow $R \propto M^{0.27}$ slope for rocky bodies in this mass range.
+Filter to converged rows (`converged == True`) and overlay the three radii on the Zeng et al. (2019)[^cite-zeng2019] curve to check that you reproduce the expected shallow $R \propto M^{0.27}$ slope for rocky bodies in this mass range.
 The `tools/grids/plot_grid.py` helper does this for you:
 
 ```console
@@ -249,3 +249,7 @@ Browse `input/grids/` for richer examples: `mass_radius.toml` is a 7-point versi
 - For the equations behind the structure ODE, the EOS dispatch, and the mushy-zone mixing model, read [Model overview](../Explanations/model.md) and [Equation of state physics](../Explanations/eos_physics.md).
 - For the function-call coupling used when Zalmoxis runs inside PROTEUS (the `python -m zalmoxis` invocation in this tutorial does *not* apply there), read [Coupling Zalmoxis to PROTEUS](../How-to/proteus_coupling.md) and [Coupling to PROTEUS (theory)](../Explanations/proteus_coupling.md).
 - For first-principles verification cases (analytic polytropes, hydrostatic equilibrium tests, mass conservation), read the [Validation](../Validation/index.md) tab.
+
+[^cite-zeng2019]: L. Zeng, S. B. Jacobsen, D. D. Sasselov, M. I. Petaev, A. Vanderburg, M. Lopez-Morales, J. Perez-Mercader, T. R. Mattsson, G. Li, M. Z. Heising, A. S. Bonomo, M. Damasso, T. A. Berger, H. Cao, A. Levi, R. D. Wordsworth, *[Growth model interpretation of planet size distribution](https://doi.org/10.1073/pnas.1812905116)*, Proceedings of the National Academy of Sciences, 116(20), 9723-9728, 2019. [SciX](https://scixplorer.org/abs/2019PNAS..116.9723Z/abstract).
+[^cite-seager2007]: S. Seager, M. Kuchner, C. A. Hier-Majumder, B. Militzer, *[Mass-Radius Relationships for Solid Exoplanets](https://doi.org/10.1086/521346)*, The Astrophysical Journal, 669(2), 1279-1297, 2007. [SciX](https://scixplorer.org/abs/2007ApJ...669.1279S/abstract).
+[^cite-attia2026]: M. Attia, T. Lichtenberg, E. Jungová, M. Sastre, *[PALEOS: Multiphase equations of state and mass-radius relations for exoplanet interiors](https://doi.org/10.1051/0004-6361/202660790)*, Astronomy and Astrophysics, 713, A225, 2026. [SciX](https://scixplorer.org/abs/2026A%26A...713A.225A/abstract).

From 9ed4e7c9a9ca9d33257a849a4d42604252639334 Mon Sep 17 00:00:00 2001
From: timlichtenberg <lichtenberg.tim@gmail.com>
Date: Sun, 8 Nov 2026 12:04:35 +0100
Subject: [PATCH 14/14] Say which output the output folder holds and where the
 grid runner and the EOS caches write

The output folder holds the files of python -m zalmoxis. The grid runner writes into the folder of its grid file and still needs a valid output_dir in its base config when that config sets one; the EOS caches stay beside their tables and in data/EOS_PALEOS_API.
---
 docs/How-to/usage.md | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)

diff --git a/docs/How-to/usage.md b/docs/How-to/usage.md
index a06ea1cd..a93e793a 100644
--- a/docs/How-to/usage.md
+++ b/docs/How-to/usage.md
@@ -50,7 +50,7 @@ For the full list of parameters (EOS selection, temperature modes, solver settin
 
 ## Output files
 
-All output files are written to the output folder: the existing folder that `[Output] output_dir` names, or else `output/` of the Zalmoxis root (created on the first run). The folder looks like:
+`python -m zalmoxis` writes all its files into its output folder: the existing folder that `[Output] output_dir` names, or else `output/` of the Zalmoxis root (created on the first run). The folder looks like:
 
 ```
 output/
@@ -60,13 +60,14 @@ output/
 ├── planet_profile.png            # 6-panel structure plot (if plots_enabled)
 ├── mantle_PT_profile.pdf         # mantle P-T plot (if plots_enabled and the mantle EOS uses melting curves)
 ├── zalmoxis.log                  # log of python -m zalmoxis
-├── grid_results/                 # grid runner output (if using run_grid)
-│   ├── grid_summary.csv
-│   └── *.json
 ├── pressure_profiles.txt         # iteration diagnostics (DEBUG, command-line run)
 └── density_profiles.txt          # iteration diagnostics (DEBUG, command-line run)
 ```
 
+The grid runner `tools/grids/run_grid.py` does not use `output_dir`. It writes `grid_summary.csv`, a `<label>.json` result per grid point and, with `[output] save_profiles = true`, a `<label>.csv` profile per grid point into the folder that `[output] dir` of the grid file names, relative to the Zalmoxis root, by default `output/grid_results/`. It loads its base config with `load_zalmoxis_config`, which checks `output_dir`, so a base config that sets `output_dir` must still name an existing, writable folder, although the grid runner writes nothing there.
+
+The EOS caches are written outside the output folder: the binary cache `<table>.cache.pkl` beside each unified PALEOS table file (under `data/` for the downloaded tables), and the PALEOS API cache in `data/EOS_PALEOS_API/` of the Zalmoxis root.
+
 ### Profile files
 
 When `data_enabled = true` (the default), the solver writes radial profiles as tab-separated text: