[timlichtenberg]

Description

python -m zalmoxis now writes all its files into one output folder: the profiles, the summary, the plots, zalmoxis.log and, at the DEBUG level, the 2 iteration profile files. The folder is the new [Output] key output_dir (an existing, writable folder), or else output/ of the Zalmoxis root, which the run creates on a fresh checkout. Without debug_profile_dir, the command-line run puts the DEBUG dump into the same folder; a library or PROTEUS caller that sets neither key writes no file, as with #128.

• load_zalmoxis_config and validate_config refuse an output_dir that is not a string or path, is empty, or is not an existing, writable folder.
• plot_PT_with_phases adds the mass to its file name (mantle_PT_profile<mass>.pdf), so a batch run no longer overwrites one file per mass.
• The CLI log is a file handler in write mode at INFO; if the file cannot be opened, the log goes to stderr with a warning that names the file.
• The grid runner tools/grids/run_grid.py does not use output_dir; usage.md says where it writes and which files stay outside the output folder (the EOS caches under data/).
• Docs: configuration, usage, first run and installation pages; citations on the edited pages use footnotes.

The branch merges main after #128 (merge commit d1ff740); the conflicts were in input/default.toml, config.py, __main__.py, AGENTS.md, configuration.md, usage.md and test_main_cli.py. The main test that mocked logging.basicConfig for the log path is replaced by tests on the real log file (path, overwrite, level, format) in tests/test_output_dir.py.

No related issue.

Validation of changes

• Nightly at eb8c418, all 8 jobs green (main job: 2686 passed, 5 skipped, total coverage 96.94 %): https://github.com/FormingWorlds/Zalmoxis/actions/runs/42466604775. The last commit (9ed4e7c) changes only docs/How-to/usage.md.
• On the branch source at eb8c418 (macOS arm64, Python 3.12): pytest tests/test_output_dir.py tests/test_output.py tests/test_main_cli.py tests/test_debug_profile_output.py tests/test_config_validators_extra.py gives 100 passed. Patch coverage of the changed source lines from these files: 28 of 30 (diff-cover); the 2 other lines are 1 plot call in each of plot_phase_vs_radius.py and plot_profiles.py.
• The DEBUG dump of a command-line run: tests/test_main_cli.py::TestZalmoxisCli::test_main_passes_its_output_folder_for_the_debug_dump checks that the CLI passes its output folder as debug_profile_dir (unless the config names one), and tests/test_debug_profile_output.py::test_debug_solve_writes_the_dump_into_the_given_folder checks that a DEBUG solve writes both profile files into that folder.
• Docs: every citation on the edited pages is a footnote.

Behaviour to know:

• post_processing checks output_dir even when data output and plots are both off. With data output or plots on and no output_dir, it creates the default folder before the solve.
• output_dir=None in a library dict is refused by validate_config but means the default folder in post_processing; one rule for both is a follow-up.

Lines by category (pr-breakdown 4a6fbd6 9ed4e7c):

Category	Files	Lines added / removed	Size on disk (KiB)	Compressed (KiB)
tests	3	+470 / -33	+18.0	+4.6
source	5	+73 / -24	+2.5	+0.8
docs text	5	+71 / -49	+5.9	+2.4
other	1	+1 / -0	+0.1	+0.0

Checklist

• I have followed the contributing guidelines
• My code follows the style guidelines of this project
• I have performed a self-review of my code
• My changes generate no new warnings or errors
• I have checked that the tests still pass on my computer
• I have updated the docs, as appropriate
• I have added tests for these changes, as appropriate
• I have checked that all dependencies have been updated, as required