Docs/skill review + usability fixes found while documenting

[yannrichet]

Pull Request

Description

Two commits:

1. Documentation and agent-skill review (03a5b6d), rebased on the doc/ restructuring of P0-8 sh:// path fix + P0-1/P0-3/P0-4/P0-5 follow-ups, README reduction (P1-5) #98 and the sh:// fix P0-8. Every finding was checked by running fz on current main.
2. Code fixes for the defects that review uncovered (086be68), with tests and docs.

Related Issues

Relates to #98 (doc restructuring), P0-8 (sh:// path resolution).

Type of Change

• Bug fix (non-breaking change which fixes an issue)
• Documentation update
• Test addition/modification
• Breaking change — see "Behavior changes" below; none breaks a model that sets delim

Changes Made

Code fixes (086be68)

Defect (verified on main)	Fix
timeout=0 / FZ_RUN_TIMEOUT=0 made every case time out immediately (only a model "timeout": 0 disabled it)	0 means "no timeout" at every level (fz/runners/manager.py); a negative timeout= raises ValueError
A model without delim only recognized $(x) (${x} silently left in compiled files) while the CLI without --model only recognized ${x}	Without delim/var_delim, both $(x) and ${x} are recognized (DEFAULT_VAR_DELIM = "(){}", get_var_delim(), _delim_pairs() in fz/interpreter.py); the CLI default model no longer forces {}
fzr(path, vars, model, "sh://bash run.sh") created a directory named sh:/bash run.sh and ran every case without calculator	fzr() raises ValueError when results_dir looks like a URI
fz list showed aliases by uri and --check reported installed-wrapper aliases ({"uri": "sh://", "models": {...}}) as failed (Empty sh:// command); a global alias overwrote a project one with the same name	Aliases listed by file name with path/uri; --check validates each models command; project shadows global; fzl and fz list share _print_fzl_result()
fz install model X --global wrappers failed outside the install directory (bash .fz/calculators/X.sh resolved against the launch dir)	.fz/... paths of an alias are anchored to the .fz/ it was loaded from (_anchor_fz_paths() in fz/helpers.py)
One empty .fz/tmp/fz_temp_* directory left per run	Empty directories removed after the run; leftover files still kept

Not changed on purpose: a case without parsable outputs keeps status="done" (the reason is in error). I first changed it to failed, then reverted it: tests/test_examples_advanced.py::test_non_numeric_variables states this is deliberate ("do not expect failed, as it is a failure due to wrong input, not calculation failure"). The doc now says so explicitly.

Behavior changes to note

• A model without delim now also reads ${...} as variables: a template containing other ${...} text (shell snippets) with such a model will report those names. Models that set delim are unchanged. Documented in NEWS.md.
• fz list --format json: calculator keys are alias names (previously URIs) and gain path/uri.
• timeout=0 / FZ_RUN_TIMEOUT=0 change meaning from "immediate timeout" to "no timeout".

Documentation (03a5b6d, updated by 086be68)

• New doc/limitations.md: constraints and pitfalls checked by running fz.
• 106 fz.fzr(...) examples in doc/ and examples/ passed the calculator positionally; they now use keywords.
• Documented as they behave: no ?var conversion (notebook 02 fixed), fzc per-case sub-directories, first Ctrl+C terminates running cases, cache://_, sh:// argument appending, SSH auth/host keys, funz:// UDP port, fzd has no --format, DataFrame designs Python-only, config read at import (reload_config()), fz.shell imports.
• skills/fz/, /fz:run, NEWS.md updated.

Testing Performed

Automated Tests

• New tests/test_usability_fixes.py (14 tests: each fix, plus the explicit-delim and missing-output cases)
• Full CI selection (ci.yml ignore list), FZ_SKILL_E2E=0: 1055 passed, 92 skipped, 5 failed — the same 5 fail on main in this environment (permission tests run as root, local yq version): test_fzi_with_permission_denied, test_install_model_with_permission_error, test_fzc_with_readonly_output_directory, test_evaluate_yq_scalar, test_evaluate_yq_prefix_detection_and_stripping
• test_cli_commands.py, test_examples_*.py, test_interrupt_handling.py (-m "not slow"): 71 passed, 7 skipped (same as main)
• flake8 fz/ --select=E9,F63,F7,F82: 0
• test_skill_e2e.py not run on the branch (runs real Claude sessions)

Manual Testing

• Linux: each fix reproduced before/after with scratch scripts; --global checked with the real fz-Modelica wrapper installed into a separate HOME

Additional Notes

The companion site PR is Funz/fz.github.io#3 (documents the fixed behavior, with notes for fz ≤ 1.2). It links to doc/limitations.md, so this PR should be merged first.

🤖 Generated with Claude Code

https://claude.ai/code/session_012GxLbauyVHBQPCeSow8hdh