Funz · yannrichet · Oct 1, 2026 · Sep 30, 2026 · Oct 1, 2026
diff --git a/NEWS.md b/NEWS.md
@@ -2,6 +2,55 @@
 
 ## Unreleased
 
+### Usability fixes found while reviewing the documentation
+
+- **`0` means "no timeout" everywhere**: `timeout=0` and `FZ_RUN_TIMEOUT=0` made every
+  case time out immediately; they now disable the timeout, like a model `"timeout": 0`.
+  A negative `timeout=` raises `ValueError`.
+- **Default variable delimiters**: a model without `delim`/`var_delim` now recognizes
+  both `$(x)` and `${x}` (it only recognized `$(x)`, so `${x}` was silently left in the
+  compiled files), and the CLI without `--model` uses the same default (it used `{}`
+  only). A model with an explicit `delim` is unchanged. Templates containing other
+  `${...}` text (e.g. shell snippets) with a model that sets no `delim` now report those
+  names as variables: set `delim` in such models.
+- **`fzr()` rejects a `results_dir` that looks like a calculator URI** (`ValueError`):
+  `fzr(path, vars, model, "sh://bash run.sh")` used to create a directory named after the
+  URI and run every case without calculator.
+- **`fz list` / `fzl`**: calculator aliases are listed by file name with their `uri`
+  and `path`; `--check` validates the command of each entry of an alias's `models` map,
+  so installed-wrapper aliases (`{"uri": "sh://", "models": {...}}`) no longer fail with
+  `Empty sh:// command`. A project alias shadows a global one with the same name.
+  The `fzl` and `fz list` output code is shared.
+- **Global installs**: `.fz/...` paths in a calculator alias are resolved against the
+  `.fz/` directory the alias was loaded from, so `fz install model <X> --global` wrappers
+  (`bash .fz/calculators/<X>.sh`) run from any directory.
+- **`.fz/tmp/`**: empty `fz_temp_*` directories are removed after each run (files left
+  behind are still kept for inspection).
+- New `tests/test_usability_fixes.py`.
+
+### Documentation: constraints page, corrected examples, skill review
+
+- New `doc/limitations.md`: constraints and pitfalls checked by running fz (argument
+  order, parallelism, timeouts, `sh://` argument appending, reserved file names, cache
+  key, CLI/Python differences, SSH, `fz list`, `--global` installs, security).
+- Fixed ~130 `fz.fzr(...)` examples in `doc/` and `examples/` that passed the calculator
+  as the 4th positional argument (that slot is `results_dir`: a directory named after the
+  URI was created and every case failed); they now use `calculators=`/`results_dir=`.
+- Examples changing `os.environ["FZ_..."]` after `import fz` now call
+  `fz.reload_config()` / `fz.set_log_level()`; `fz.shell_path` imports replaced by
+  `fz.shell`; nonexistent `funz://...?timeout=` removed.
+- Behaviors now documented as they are:
+  - `?var` is not converted to `$var` (needs `"varprefix": "?"`); notebook 02 fixed;
+  - `fzc` writes one sub-directory per case even for scalar values; `fzo` must target
+    case directories (the skill's verification ladder used `compiled/input.txt`);
+  - first Ctrl+C terminates running cases and `fzr` returns (it does not wait for them);
+  - `cache://_` resumes into the same `results_dir`;
+  - no interactive SSH password prompt; `funz://` port is the UDP discovery port;
+  - `fzd` has no `--format`; `fz list` does not list algorithms; DataFrame designs are
+    Python-only.
+- Agent skill and `/fz:run`: status values, `FZ_MAX_WORKERS` only caps, function-model
+  `fzd` concurrency, `slurm-array://`, reserved file names, timeouts.
+
 ### Fix: potentially wrong results with `sh://` commands (P0-8)
 
 - Path resolution in `sh://` commands converted every word that looked like a

diff --git a/README.md b/README.md
@@ -225,7 +225,7 @@ Details: [MCP server](doc/mcp-server.md).
 
 ## Documentation
 
-- **Documentation in `doc/`** (one file per topic; start at [`doc/INDEX.md`](doc/INDEX.md)): [CLI](doc/cli-usage.md), [Python API](doc/core-functions.md), [models](doc/model-definition.md), [calculators](doc/calculators.md), [parallelism and caching](doc/parallel-and-caching.md), [configuration](doc/configuration.md), [troubleshooting](doc/troubleshooting.md), [examples](doc/quick-examples.md), [custom `fzd` algorithms](doc/custom-algorithms.md), [plugins](doc/installing-models.md), [development](doc/development.md), [breaking changes](doc/breaking-changes.md), [MCP server](doc/mcp-server.md).
+- **Documentation in `doc/`** (one file per topic; start at [`doc/INDEX.md`](doc/INDEX.md)): [CLI](doc/cli-usage.md), [Python API](doc/core-functions.md), [models](doc/model-definition.md), [calculators](doc/calculators.md), [parallelism and caching](doc/parallel-and-caching.md), [configuration](doc/configuration.md), [troubleshooting](doc/troubleshooting.md), [examples](doc/quick-examples.md), [custom `fzd` algorithms](doc/custom-algorithms.md), [plugins](doc/installing-models.md), [development](doc/development.md), [breaking changes](doc/breaking-changes.md), [MCP server](doc/mcp-server.md), [constraints and pitfalls](doc/limitations.md).
 - **Examples**: [`examples/examples.md`](examples/examples.md), [`examples/`](examples/) notebooks and scripts.
 - **All resources and test examples**: [Resources](doc/resources.md).
 - **Release notes**: [`NEWS.md`](NEWS.md).

diff --git a/commands/run.md b/commands/run.md
@@ -8,14 +8,18 @@ Request: $ARGUMENTS
 
 - If the simulation is not wrapped and verified yet, do that first (`fzi` → `fzc` →
   one manual run → `fzo` on a single case) before launching the batch.
-- Build `input_variables` as a dict of lists (full factorial — Cartesian product) or
-  as a DataFrame / CSV with one row per case (LHS, constrained or imported designs).
+- Build `input_variables` as a dict of lists (full factorial — Cartesian product) or,
+  from Python only, as a DataFrame with one row per case (LHS, constrained or imported
+  designs; read a CSV with `pandas.read_csv`). The CLI only takes the dict form.
 - Choose calculators: `sh://` local, `ssh://user@host/command` remote, `slurm://`
   for HPC. Repeat a URI or pass a list to run cases in parallel. Put
   `cache://<previous results dir>` first in the list to resume or extend a run —
   only the missing cases are computed.
 - Use `--format json` on the CLI (data → stdout, logs → stderr; `fzr` exits 1 when no
   case succeeds).
-- After the run, report the `status` counts (`done`/`error`/`cached`) and show the
-  results table. For any `error` or `null`-output case, read that case's
+- In Python, pass `calculators=` and `results_dir=` as keywords (`results_dir` is the
+  4th positional parameter of `fz.fzr`).
+- After the run, report the `status` counts (`done`/`failed`/`error`/`timeout`/
+  `interrupted`; cache hits are `done` with a `cache://` calculator) and show the
+  results table. For any non-`done` or `null`-output case, read that case's
   `err.txt` / `log.txt` before concluding.
diff --git a/doc/INDEX.md b/doc/INDEX.md
@@ -18,6 +18,7 @@ Quick reference index for finding specific topics in the FZ context documentatio
 - [Examples by Use Case](#examples-by-use-case)
 - [CLI Usage](#cli-usage)
 - [Troubleshooting](#troubleshooting)
+- [Constraints and pitfalls](limitations.md)
 
 ## Where the former README went
 
@@ -211,6 +212,7 @@ exists in the code and that all relative links in `doc/` resolve.
 
 | Topic | File | Section |
 |-------|------|---------|
+| Constraints and pitfalls (checked against the code) | limitations.md | - |
 | Debug single case | quick-examples.md | "Troubleshooting Examples" → "Debug Single Case" |
 | Test calculator manually | quick-examples.md | "Troubleshooting Examples" → "Test Calculator Manually" |
 | Verify cache matching | quick-examples.md | "Troubleshooting Examples" → "Verify Cache Matching" |

diff --git a/doc/README.md b/doc/README.md
@@ -106,6 +106,22 @@ Ready-to-use examples for:
 
 **Use when**: Looking for example code for specific use cases
 
+### 9. `limitations.md` - Constraints, Limits and Pitfalls
+Verified list of behaviors that surprise users:
+- `fzr` argument order (`results_dir` before `calculators`), config read at import
+- Parallelism = number of calculator entries; timeout rules (`0` does not disable)
+- `sh://` argument appending; reserved file names in case directories
+- Cache key contents, CLI/Python differences, SSH host keys, security model
+
+**Use when**: Before writing a model/calculator, or when a run behaves unexpectedly
+
+### Other files
+- `mcp-server.md` - the `fz-mcp` MCP server for AI agents
+- `slurm-architecture.md` - design notes on `slurm://` vs `slurm-array://`
+- `funz-protocol.md` - legacy Java Funz TCP/UDP protocol
+- `shell-path.md` - `FZ_SHELL_PATH` (bash location, Windows)
+- `fzd_content_format.md` - formats of `fzd` analysis content
+
 ## How to Use This Documentation
 
 ### For LLM Integration
@@ -126,7 +142,7 @@ These files can be used as context for LLMs in several ways:
 | Configuring models | model-definition.md, syntax-guide.md |
 | Setting up execution | calculators.md, parallel-and-caching.md |
 | Performance tuning | parallel-and-caching.md, calculators.md |
-| Troubleshooting | quick-examples.md (troubleshooting section) |
+| Troubleshooting | limitations.md, quick-examples.md (troubleshooting section) |
 
 ### Example Usage in LLM Prompts
 
@@ -167,6 +183,9 @@ doc/
 ├── parallel-and-caching.md             # Parallel execution and caching
 ├── fzd_content_format.md               # fzd analysis content formats
 ├── quick-examples.md                   # Common patterns and examples
+├── limitations.md                      # Constraints, limits and pitfalls
+├── mcp-server.md                       # fz-mcp server for AI agents
+├── slurm-architecture.md               # slurm:// vs slurm-array:// design notes
 ├── funz-protocol.md                    # Legacy Funz server protocol
 └── shell-path.md                       # FZ_SHELL_PATH configuration
 ```
@@ -198,6 +217,6 @@ To improve this documentation:
 
 ## Version
 
-These docs are for **fz version 1.0+**
+These docs are for **fz version 1.2+** (including unreleased changes listed in `NEWS.md`)
 
-Last updated: 2026-06-13
+Last updated: 2026-09-30