Funz · yannrichet · Oct 1, 2026 · Sep 30, 2026 · Sep 30, 2026 · Oct 1, 2026
diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml
@@ -28,11 +28,12 @@ jobs:
 
       - name: Install dependencies
         run: |
-          pip install mkdocs mkdocs-material pymdown-extensions
+          pip install -r requirements.txt
 
       - name: Build documentation
         run: |
-          mkdocs build
+          mkdocs build --strict
+          python test_site_structure.py
 
       - name: Deploy to GitHub Pages
         if: github.event_name == 'push' && github.ref == 'refs/heads/main'

diff --git a/README.md b/README.md
@@ -1,87 +1,47 @@
 # FZ Documentation Website
 
-This repository hosts the documentation website for [FZ - Parametric Scientific Computing Framework](https://github.com/Funz/fz).
+Source of the documentation site of [FZ](https://github.com/Funz/fz) (PyPI `funz-fz`),
+published at **https://funz.github.io/fz.github.io**.
 
-## 📚 Documentation Site
+## Structure
 
-Visit the live documentation at: **https://funz.github.io/fz.github.io**
+| Section | Directory | Content |
+|---------|-----------|---------|
+| Getting Started | `docs/getting-started/` | Installation, quick start, concepts |
+| User Guide — Templates & Models | `docs/user-guide/templates/`, `docs/user-guide/models/` | Template syntax, formulas, model fields, output extraction |
+| User Guide — Core Functions | `docs/user-guide/core-functions/` | `fzi`, `fzc`, `fzo`, `fzr`, `fzd`, `fzl` |
+| User Guide — Calculators | `docs/user-guide/calculators/` | `sh://`, `ssh://`, `slurm://`/`slurm-array://`, `funz://`, `cache://`, aliases |
+| User Guide — Running Studies | `docs/user-guide/running/` | Parallelism, timeouts, caching, results/manifest, interrupts |
+| User Guide — other | `docs/user-guide/` | Writing algorithms, installing models, AI agents |
+| Plugins | `docs/plugins/` | `fz-<code>` wrappers and algorithms |
+| Examples | `docs/examples/` | Perfect gas, Modelica, HPC, Colab |
+| Reference | `docs/reference/` | CLI, Python API, `.fz` directory, environment variables, constraints, security, troubleshooting, release notes |
+| Contributing | `docs/contributing/` | Development and testing of fz |
 
-## 🚀 Quick Links
+Notebooks for Colab are in `notebooks/`. Moved pages are redirected (`redirects` plugin
+in `mkdocs.yml`).
 
-- [Installation Guide](https://funz.github.io/fz.github.io/getting-started/installation/)
-- [Quick Start](https://funz.github.io/fz.github.io/getting-started/quickstart/)
-- [Core Functions](https://funz.github.io/fz.github.io/user-guide/core-functions/fzr/)
-- [Plugins](https://funz.github.io/fz.github.io/plugins/)
-- [Google Colab Notebooks](https://funz.github.io/fz.github.io/examples/colab/)
-
-## 📓 Google Colab Examples
-
-Try FZ directly in your browser:
-
-- [Perfect Gas Example](https://colab.research.google.com/github/Funz/fz.github.io/blob/main/notebooks/perfectgas_example.ipynb)
-- [OpenModelica Integration](https://colab.research.google.com/github/Funz/fz.github.io/blob/main/notebooks/modelica_example.ipynb)
-
-## 🔌 FZ Plugins
-
-- [FZ-Moret](https://github.com/Funz/fz-moret) - Moret model plugin
-- [FZ-MCNP](https://github.com/Funz/fz-mcnp) - Monte Carlo N-Particle Transport
-- [FZ-Cathare](https://github.com/Funz/fz-cathare) - Thermal-hydraulic system code
-- [FZ-Cristal](https://github.com/Funz/fz-cristal) - Cristal simulation plugin
-- [FZ-Scale](https://github.com/Funz/fz-scale) - Scale nuclear analysis code
-- [FZ-Telemac](https://github.com/Funz/fz-telemac) - Hydrodynamics simulation system
-
-## 🛠️ Building the Documentation
-
-This site is built with [MkDocs](https://www.mkdocs.org/) and the [Material theme](https://squidfunk.github.io/mkdocs-material/).
-
-### Prerequisites
+## Build
 
 ```bash
-pip install mkdocs mkdocs-material pymdown-extensions
+pip install -r requirements.txt      # MkDocs 1.x + Material; MkDocs 2.0 is not supported
+mkdocs serve                         # http://127.0.0.1:8000
+mkdocs build --strict                # fails on broken links or anchors
+python test_site_structure.py        # every navigation page and redirect was built
 ```
 
-### Local Development
-
-```bash
-# Clone the repository
-git clone https://github.com/Funz/fz.github.io.git
-cd fz.github.io
-
-# Serve locally with live reload
-mkdocs serve
-
-# Open http://127.0.0.1:8000 in your browser
-```
-
-### Build
-
-```bash
-# Build static site
-mkdocs build
-
-# Output in site/ directory
-```
-
-### Deploy
-
-The documentation is automatically deployed to GitHub Pages when changes are pushed to the `main` branch via GitHub Actions.
-
-## 📝 Contributing
-
-Contributions to the documentation are welcome! Please:
-
-1. Fork this repository
-2. Create a feature branch
-3. Make your changes
-4. Test locally with `mkdocs serve`
-5. Submit a pull request
+Pushes to `main` are built with `--strict` and deployed to GitHub Pages by
+`.github/workflows/deploy.yml`.
 
-### Adding Content
+## Writing rules
 
-- Documentation pages are in `docs/`
-- Notebooks are in `notebooks/`
-- Configuration is in `mkdocs.yml`
+- Content must match the code of fz: check behavior by running it, not only by reading
+  other docs. Constraints that surprise users go to `docs/reference/limitations.md`
+  (mirrors `doc/limitations.md` in the fz repository).
+- Python examples call `fz.fzr(...)` with `calculators=` and `results_dir=` as keywords.
+- Models in examples set `"delim"` explicitly.
+- One topic per page; link instead of repeating.
 
-## 📄 License
+## License
 
-BSD 3-Clause License - see the [FZ repository](https://github.com/Funz/fz) for details.
+BSD 3-Clause, as [FZ](https://github.com/Funz/fz).
diff --git a/SUMMARY.md b/SUMMARY.md
diff --git a/docs/contributing/development.md b/docs/contributing/development.md
@@ -13,22 +13,32 @@ python -m venv venv && source venv/bin/activate
 pip install -e ".[dev]"
 ```
 
-Optional extras: `paramiko` (SSH/SLURM), `pandas` (DataFrame output), `rpy2` + R
-(R interpreter and R algorithm plugins), `h5py` (HDF5 outputs).
+`paramiko` and `pandas` are required dependencies. Optional: `rpy2` + R (R formulas and
+algorithms, extra `[r]`), `mcp` (extra `[mcp]`, Python ≥ 3.10), `h5py`, `jq`, `yq`,
+`xmllint`.
 
 ## Package Layout
 
 | Module | Responsibility |
 |--------|----------------|
-| `fz/core.py` | The public functions `fzi`, `fzc`, `fzo`, `fzr`, `fzd` |
+| `fz/core.py` | Public functions `fzi`, `fzc`, `fzo`, `fzr`, `fzd`, `fzl` |
+| `fz/cli.py` | Entry points `fz`, `fzi`, `fzc`, `fzo`, `fzr`, `fzd`, `fzl` |
 | `fz/interpreter.py` | Variable parsing, formula evaluation (Python / R) |
-| `fz/runners.py` | Calculator backends — `sh://`, `ssh://`, `slurm://`, `funz://`, `cache://` |
-| `fz/helpers.py` | Parallel scheduling, retry, interrupt handling |
-| `fz/io.py` | File staging, hashing, `.fz_hash` caching |
-| `fz/algorithms.py` | Algorithm framework for `fzd` |
-| `fz/shell.py` | Shell utilities, `FZ_SHELL_PATH` binary resolution |
-| `fz/cli.py` | `fz`, `fzi`, `fzc`, `fzo`, `fzr`, `fzd`, `fzl` entry points |
-| `fz/config.py` | Environment-variable configuration |
+| `fz/outparsers.py` | `python://`, `jq://`, `yq://`, `xpath://` output extractors |
+| `fz/runners/` | Calculator backends: `sh`, `ssh`, `slurm`, `slurm_array`, `funz`, `cache`, plus `dispatch`, `manager`, `resolve`, `base` |
+| `fz/slurm_async.py` | Job-array batching and `sacct` monitoring |
+| `fz/helpers.py` | Case scheduling, retries, calculator/model resolution |
+| `fz/io.py` | File staging, `.fz_hash`, cache matching |
+| `fz/manifest.py`, `fz/uri.py` | `manifest.json` / RO-Crate, URI password redaction |
+| `fz/algorithms.py` | `fzd` algorithm loading and output expressions |
+| `fz/installer.py` | `fz install` / `fz uninstall` |
+| `fz/mcp_server.py` | `fz-mcp` |
+| `fz/config.py`, `fz/logging.py`, `fz/shell.py` | Configuration (`FZ_*`), logs, bash / `FZ_SHELL_PATH` resolution |
+
+Documentation lives in three places that must stay consistent when the API or the CLI
+changes: `README.md` (overview, under 300 lines), `doc/` (one file per topic), and the agent skill `skills/fz/` (tested by
+`tests/test_skill_static.py`). This website is a separate repository,
+[Funz/fz.github.io](https://github.com/Funz/fz.github.io).
 
 ## Workflow
 
@@ -41,13 +51,13 @@ Optional extras: `paramiko` (SSH/SLURM), `pandas` (DataFrame output), `rpy2` + R
 
 ## Releasing
 
-Version lives in `fz/__init__.py` (`pyproject.toml` reads it dynamically). A release
-commit bumps that, folds `## Unreleased` into a dated `## Version X.Y` section in
+`fz/_version.py` is stamped by CI (`scripts/stamp_version.py`) and must not be edited by
+hand; `pyproject.toml` reads the version dynamically. A release commit folds `## Unreleased` into a dated `## Version X.Y` section in
 `NEWS.md`, and aligns the Claude Code plugin version. Publishing a GitHub Release with
 the matching tag triggers `release.yml`, which pushes to PyPI.
 
 ## See Also
 
 - [Testing](testing.md)
-- [Writing Custom Algorithms](../user-guide/core-functions/fzd.md#writing-custom-algorithms)
+- [Writing Algorithms](../user-guide/design/algorithms.md)
 - [Plugin templates](../plugins/index.md#creating-your-own-plugin) — `fz-Model`, `fz-Algorithm`, `fz-AlgorithmR`
diff --git a/docs/contributing/testing.md b/docs/contributing/testing.md
@@ -10,14 +10,20 @@ pip install -e ".[dev]"
 python -m pytest tests/ -v                 # everything
 python -m pytest tests/test_fzd.py -v      # one file
 python -m pytest tests/ -k parallel -v     # by keyword
+python -m pytest tests/test_skill_static.py  # agent skill claims vs code
 FZ_LOG_LEVEL=DEBUG python -m pytest tests/test_interrupt_handling.py -v
 ```
 
+Every test runs in a fresh temporary directory under `./tmp` (autouse fixture in
+`tests/conftest.py`): reference test data by absolute path. Markers (`slow`,
+`integration`, `requires_ssh`, `requires_docker`, ...) are declared in `pytest.ini`
+(`--strict-markers`). SSH, SLURM, Funz and example tests run in dedicated CI workflows.
+
 ## Notable Test Areas
 
 | File(s) | Covers |
 |---------|--------|
-| `test_parallel.py` | Concurrent execution, load balancing |
+| `test_parallel_simple.py`, `test_complete_parallel_execution.py` | Concurrent execution, load balancing |
 | `test_interrupt_handling.py` | Ctrl+C graceful shutdown, resume |
 | `test_fzd*.py` | Design of experiments, vector / multi-objective outputs |
 | `test_static_files*.py` | `input_static` (local and real SFTP over `ssh://`) |
@@ -35,7 +41,7 @@ from pathlib import Path
 def test_my_model():
     with tempfile.TemporaryDirectory() as tmp:
         inp = Path(tmp) / "input.txt"
-        inp.write_text("Parameter: $param\n")
+        inp.write_text("param=$param\n")
 
         calc = Path(tmp) / "calc.sh"
         calc.write_text('#!/bin/bash\nsource "$1"\necho "result=$param" > output.txt\n')