docs: rename context/→doc/, document the installer, restructure skill wrapper guides

.gitignore

@@ -25,3 +25,6 @@ results*/
 output/
 # notebook work directories (generated by examples/)
 examples/work_*/
+# fz run scratch under examples/ (re-excluded: the !examples/** rule above
+# would otherwise un-ignore the global .fz rule for this path)
+examples/.fz/

CLAUDE.md

@@ -9,7 +9,7 @@ codes to run parameter studies locally, over SSH, or on SLURM. Python rewrite of
   `cli.py` (entry points `fz`, `fzi`, ... defined in pyproject.toml), `runners.py`
   (sh/ssh/slurm/funz/cache calculators), `interpreter.py` (variable/formula parsing,
   Python and R evaluation), `io.py`, `config.py` (env vars), `installer.py` (`fz install`).
-- `tests/` — pytest suite. `context/` — modular user docs. `skills/fz/` — Agent Skill
+- `tests/` — pytest suite. `doc/` — modular user docs. `skills/fz/` — Agent Skill
   (workflow + condensed reference). `examples/` — example models, algorithms, notebooks.
 - `fz/_version.py` is stamped by CI (`scripts/stamp_version.py`) — never edit manually.
 
@@ -68,7 +68,7 @@ R-dependent code or tests.
   Python signatures consistent — every core function has a CLI twin with the same
   semantics, and CLI output must stay parseable with `--format json`.
 - When changing the public API or CLI flags, update **all three** doc surfaces:
-  `README.md`, `context/`, and `skills/fz/reference.md` (the agent skill ships to users).
+  `README.md`, `doc/`, and `skills/fz/reference.md` (the agent skill ships to users).
 - Default values live in `fz/config.py` and are env-overridable (`FZ_LOG_LEVEL`,
   `FZ_MAX_WORKERS`, `FZ_MAX_RETRIES` (default 5), `FZ_SSH_*`, `FZ_SHELL_PATH`).
 - User-facing release notes go in `NEWS.md`.

README.md

@@ -1550,7 +1550,7 @@ results = fz.fzr("input.txt", input_variables, model, calculators=calculators)
 - Broadcasts UDP message on port 19001
 - Servers respond with their host, port, and supported codes
 - Useful for dynamic calculator allocation in cluster environments
-- See `context/funz-protocol.md` for detailed protocol documentation
+- See `doc/funz-protocol.md` for detailed protocol documentation
 
 **Protocol**:
 - Text-based TCP socket communication
@@ -2430,7 +2430,7 @@ model = {
 # C:\msys64\usr\bin\grep.exe 'pressure' output.txt | C:\msys64\usr\bin\awk.exe '{print $2}'
 ```
 
-See `context/shell-path.md` and `examples/shell_path_example.md` for detailed documentation.
+See `doc/shell-path.md` and `examples/shell_path_example.md` for detailed documentation.
 
 ### Timeout Configuration
 
@@ -3185,7 +3185,7 @@ The skill contains:
 
 - **skills/fz/SKILL.md** - Step-by-step workflow for wrapping a simulation code
 - **skills/fz/reference.md** - Condensed API/CLI reference, JSON schemas, environment variables
-- **skills/fz/algorithms.md** - Interface for writing custom fzd algorithms
+- **skills/fz/algorithm-wrapper.md** - Interface for writing custom fzd algorithms
 
 See **[skills/howto.md](skills/howto.md)** for a complete walkthrough with example prompts
 (parametric studies, SSH execution, cache reuse, optimization, headless usage).
@@ -3196,22 +3196,23 @@ See **[skills/howto.md](skills/howto.md)** for a complete walkthrough with examp
 
 - **README.md** (this file) - Complete user guide with examples
 - **NEWS.md** - Release notes and changelog (version 0.9.1 and later)
-- **context/funz-protocol.md** - Funz protocol and UDP discovery documentation
-- **context/shell-path.md** - FZ_SHELL_PATH configuration details
+- **doc/funz-protocol.md** - Funz protocol and UDP discovery documentation
+- **doc/shell-path.md** - FZ_SHELL_PATH configuration details
 
 ### Context Documentation
 
-Modular documentation in the `context/` directory:
-
-- **context/INDEX.md** - Documentation overview and navigation
-- **context/overview.md** - High-level FZ concepts and design
-- **context/core-functions.md** - API reference for fzi, fzc, fzo, fzr, fzl, fzd
-- **context/calculators.md** - Calculator types, URIs, and configuration
-- **context/model-definition.md** - Model structure, aliases, and output parsing
-- **context/formulas-and-interpreters.md** - Formula evaluation (Python/R)
-- **context/syntax-guide.md** - Input template syntax reference
-- **context/parallel-and-caching.md** - Performance optimization strategies
-- **context/quick-examples.md** - Common usage patterns and snippets
+Modular documentation in the `doc/` directory:
+
+- **doc/INDEX.md** - Documentation overview and navigation
+- **doc/overview.md** - High-level FZ concepts and design
+- **doc/core-functions.md** - API reference for fzi, fzc, fzo, fzr, fzl, fzd
+- **doc/installing-models.md** - Installing models and algorithms (`fz install`)
+- **doc/calculators.md** - Calculator types, URIs, and configuration
+- **doc/model-definition.md** - Model structure, aliases, and output parsing
+- **doc/formulas-and-interpreters.md** - Formula evaluation (Python/R)
+- **doc/syntax-guide.md** - Input template syntax reference
+- **doc/parallel-and-caching.md** - Performance optimization strategies
+- **doc/quick-examples.md** - Common usage patterns and snippets
 
 ### Examples
 

context/INDEX.md → doc/INDEX.md

@@ -5,6 +5,7 @@ Quick reference index for finding specific topics in the FZ context documentatio
 ## Table of Contents
 
 - [Getting Started](#getting-started)
+- [Installing Models & Algorithms](#installing-models--algorithms)
 - [Variable Substitution](#variable-substitution)
 - [Formula Evaluation](#formula-evaluation)
 - [Core Functions](#core-functions)
@@ -23,10 +24,21 @@ Quick reference index for finding specific topics in the FZ context documentatio
 | What is FZ? | overview.md | "What is FZ?" |
 | When to use FZ | overview.md | "When to Use FZ" |
 | Quick example | overview.md | "Quick Example" |
-| Four core functions | overview.md | "Four Core Functions" |
+| Core functions | overview.md | "Core Functions" |
 | Typical workflow | overview.md | "Typical Workflow" |
 | Installation | *(see README.md)* | - |
 
+## Installing Models & Algorithms
+
+| Topic | File | Section |
+|-------|------|---------|
+| Install a model | installing-models.md | "CLI" / "Python API" |
+| Install an fzd algorithm | installing-models.md | "CLI" / "Python API" |
+| Uninstall a model/algorithm | installing-models.md | "CLI" |
+| Source resolution (name/URL/zip) | installing-models.md | "Source resolution" |
+| `fz-<code>` repository convention | installing-models.md | "Source resolution" |
+| Project-local vs global install | installing-models.md | "Install location and discovery" |
+
 ## Variable Substitution
 
 | Topic | File | Section |
@@ -186,6 +198,7 @@ Quick reference index for finding specific topics in the FZ context documentatio
 | Task | Start Here |
 |------|-----------|
 | Get started with FZ | overview.md |
+| Install a ready-made model or algorithm | installing-models.md |
 | Write an input template | syntax-guide.md |
 | Use formulas to calculate values | formulas-and-interpreters.md |
 | Parse input variables | core-functions.md → "fzi" |
@@ -221,6 +234,9 @@ Quick reference index for finding specific topics in the FZ context documentatio
 Quick keyword search:
 
 - **Variables**: syntax-guide.md
+- **Install**: installing-models.md
+- **fz install**: installing-models.md → "CLI"
+- **Algorithm install**: installing-models.md
 - **Formulas**: syntax-guide.md, formulas-and-interpreters.md
 - **Python**: formulas-and-interpreters.md
 - **R**: formulas-and-interpreters.md

context/README.md → doc/README.md

@@ -16,7 +16,7 @@ These context files are designed to:
 ### 1. `overview.md` - Framework Introduction
 High-level overview of FZ including:
 - What FZ is and when to use it
-- The four core functions (fzi, fzc, fzo, fzr)
+- The six core functions (fzi, fzc, fzo, fzr, fzl, fzd)
 - Key concepts and typical workflows
 - Common patterns for different scenarios
 
@@ -32,16 +32,27 @@ Detailed syntax reference for:
 **Use when**: Writing input templates or working with formulas
 
 ### 3. `core-functions.md` - API Reference
-Comprehensive guide to the four main functions:
+Comprehensive guide to the six core functions:
 - `fzi()` - Parse input variables
 - `fzc()` - Compile input files
 - `fzo()` - Read output files
 - `fzr()` - Run parametric calculations
+- `fzl()` - List and validate installed models / calculators
+- `fzd()` - Adaptive design of experiments
 - Function signatures, parameters, and return values
 - Examples for each function
 
 **Use when**: Using FZ API functions in Python code
 
+### 3b. `installing-models.md` - Installing Models and Algorithms
+How to obtain ready-made wrappers and `fzd` algorithms:
+- `fz install model|algorithm` and `fz uninstall` (CLI)
+- `install_model`/`install_algorithm`/`list_installed_*` (Python API)
+- Source resolution (short name, GitHub URL, local zip) and the `fz-<code>` convention
+- Project-local vs `--global` install locations
+
+**Use when**: Wrapping a known code, or adding an optimization/sampling algorithm
+
 ### 4. `model-definition.md` - Model Configuration
 Complete model definition guide covering:
 - Model structure and all fields
@@ -56,6 +67,8 @@ Complete model definition guide covering:
 Guide to all calculator types:
 - `sh://` - Local shell execution
 - `ssh://` - Remote SSH execution
+- `slurm://` - SLURM workload manager
+- `funz://` - Legacy Funz server
 - `cache://` - Cached result reuse
 - Calculator aliases and configuration
 - Parallel execution and fallback chains
@@ -138,17 +151,21 @@ Task: How do I speed up my parametric study with 1000 cases?
 ## File Organization
 
 ```
-context/
+doc/
 ├── README.md                           # This file
 ├── INDEX.md                            # Table of contents with sections
 ├── overview.md                         # High-level framework introduction
 ├── syntax-guide.md                     # Variable and formula syntax
-├── core-functions.md                   # API reference (fzi, fzc, fzo, fzr)
+├── core-functions.md                   # API reference (fzi, fzc, fzo, fzr, fzl, fzd)
+├── installing-models.md                # Installing models and algorithms
 ├── model-definition.md                 # Model configuration guide
 ├── calculators.md                      # Calculator types and configuration
 ├── formulas-and-interpreters.md        # Formula evaluation (Python/R)
-├── parallel-and-caching.md            # Parallel execution and caching
-└── quick-examples.md                   # Common patterns and examples
+├── parallel-and-caching.md             # Parallel execution and caching
+├── fzd_content_format.md               # fzd analysis content formats
+├── quick-examples.md                   # Common patterns and examples
+├── funz-protocol.md                    # Legacy Funz server protocol
+└── shell-path.md                       # FZ_SHELL_PATH configuration
 ```
 
 ## Updating This Documentation
@@ -178,6 +195,6 @@ To improve this documentation:
 
 ## Version
 
-These context files are for **FZ version 0.9.0+**
+These docs are for **fz version 1.0+**
 
-Last updated: 2025-01-XX
+Last updated: 2026-06-13

context/funz-protocol.md → doc/funz-protocol.md

@@ -663,6 +663,6 @@ Client                          Funz Server
 
 - **Funz protocol tests**: `tests/test_funz_protocol.py`
 - **Integration tests**: `tests/test_funz_integration.py`
-- **Calculator types**: `context/calculators.md`
+- **Calculator types**: `doc/calculators.md`
 - **Implementation**: `fz/runners.py` (run_funz_calculation function)
 - **Java Funz**: https://github.com/Funz/funz-calculator

doc/installing-models.md

@@ -0,0 +1,83 @@
+# Installing Models and Algorithms
+
+fz can install ready-made **models** (simulation-code wrappers) and **fzd algorithms**
+(design-of-experiments / optimization strategies) from GitHub or local zip files, so you
+don't have to author them by hand. This is the first thing to try when wrapping a known
+code: an official wrapper may give you the parameterization syntax and output parsers for
+free.
+
+## CLI
+
+```bash
+# Install a model into the current project (./.fz/models/)
+fz install model perfectgas
+fz install model https://github.com/Funz/fz-modelica
+fz install model ./fz-mycode.zip
+
+# Install globally (~/.fz/models/) so every project can use it
+fz install model perfectgas --global
+
+# Install an fzd algorithm (into ./.fz/algorithms/ or, with --global, ~/.fz/algorithms/)
+fz install algorithm brent
+fz install algorithm https://github.com/Funz/fz-montecarlo
+
+# Remove an installed resource (by name)
+fz uninstall model perfectgas
+fz uninstall algorithm brent
+fz uninstall model perfectgas --global
+
+# See what is installed (models and calculators), optionally validating each
+fz list
+fz list --check
+```
+
+`fz install` requires fz 1.0+.
+
+## Python API
+
+```python
+import fz
+
+fz.install_model("perfectgas")                 # → ./.fz/models/
+fz.install_model("perfectgas", global_install=True)   # → ~/.fz/models/
+fz.install_algorithm("brent")
+fz.uninstall_model("perfectgas")
+fz.uninstall_algorithm("brent")
+
+fz.list_installed_models()       # dict of installed models
+fz.list_installed_algorithms()   # dict of installed algorithms
+```
+
+## Source resolution
+
+The `source` argument accepts three forms (resolved by `normalize_github_url`):
+
+| Form | Example | Resolves to |
+|------|---------|-------------|
+| Short name | `perfectgas` | `https://github.com/Funz/fz-perfectgas` (the `fz-` prefix and `Funz` org are assumed) |
+| Full GitHub URL | `https://github.com/you/fz-mycode` | that repository's `main` archive |
+| Local zip / path | `./fz-mycode.zip` | the local file, unpacked directly |
+
+By convention an installable repository is named `fz-<code>` and ships a `.fz/` directory:
+
+```
+fz-mycode/
+└── .fz/
+    ├── models/MyCode.json          # the model definition (id, varprefix, output parsers)
+    ├── calculators/*.json|*.sh     # optional calculator aliases wired to the model
+    └── algorithms/*.py|*.R         # for algorithm repositories
+```
+
+On install, fz copies the model JSON into `.fz/models/` (or `~/.fz/models/` with
+`--global`) and any accompanying `.fz/` subdirectories (calculators, algorithms, …)
+alongside it.
+
+## Install location and discovery
+
+- **Project-local** (default): `./.fz/` — visible only inside the current project.
+- **Global** (`--global`): `~/.fz/` — visible from every project for the current user.
+
+Installed models are then referenced by id (`--model MyCode`), and installed calculator
+aliases are auto-discovered, so a single-case run needs no `--calculators` argument. See
+[Calculators](calculators.md) for calculator aliases and [Model definition](model-definition.md)
+for the model JSON structure, and [Core functions](core-functions.md) for `fzl` / `fz list`.

context/overview.md → doc/overview.md

@@ -32,7 +32,9 @@ Use FZ when you need to:
 4. **Scale calculations**: Execute on local machines, HPC clusters, or both
 5. **Resume interrupted runs**: Gracefully handle Ctrl+C and resume using cache
 
-## Four Core Functions
+## Core Functions
+
+fz exposes six core functions, each with a CLI twin of the same name:
 
 ```python
 import fz
@@ -57,8 +59,19 @@ results = fz.fzr(
     results_dir="results"
 )
 # Returns: DataFrame with all results
+
+# 5. fzl - List and validate installed models / calculators
+fz.fzl()
+
+# 6. fzd - Adaptive design of experiments (optimization, sampling, inverse problems)
+results = fz.fzd("input.txt", {"x": "[0;10]"}, model, "result",
+                 algorithm="brent", calculators="sh://bash calc.sh")
 ```
 
+See [Core functions](core-functions.md) for full signatures, and
+[Installing models and algorithms](installing-models.md) to obtain ready-made wrappers
+and `fzd` algorithms.
+
 ## Quick Example
 
 **Input template** (`input.txt`):

context/shell-path.md → doc/shell-path.md

@@ -421,7 +421,7 @@ jobs:
 ## See Also
 
 - **Shell path example**: `examples/shell_path_example.md`
-- **Configuration guide**: `context/overview.md`
-- **Calculator types**: `context/calculators.md`
+- **Configuration guide**: `doc/overview.md`
+- **Calculator types**: `doc/calculators.md`
 - **Source code**: `fz/shell_path.py`
 - **Tests**: `tests/test_shell_path.py`

llms.txt

@@ -24,13 +24,14 @@ extract outputs; *calculators* (URIs like `sh://cmd`, `ssh://user@host/cmd`,
 ## Documentation
 
 - [README](README.md): complete user guide with examples
-- [Core functions](context/core-functions.md): fzi, fzc, fzo, fzr, fzl, fzd in detail
-- [Input syntax guide](context/syntax-guide.md): variables, formulas, defaults
-- [Model definition](context/model-definition.md): model structure, aliases, output parsing
-- [Calculators](context/calculators.md): calculator types, URIs, configuration
-- [Formulas and interpreters](context/formulas-and-interpreters.md): Python/R formula evaluation
-- [Parallelism and caching](context/parallel-and-caching.md): performance strategies
-- [Quick examples](context/quick-examples.md): common usage patterns
+- [Core functions](doc/core-functions.md): fzi, fzc, fzo, fzr, fzl, fzd in detail
+- [Installing models and algorithms](doc/installing-models.md): fz install model|algorithm, the fz-<code> convention
+- [Input syntax guide](doc/syntax-guide.md): variables, formulas, defaults
+- [Model definition](doc/model-definition.md): model structure, aliases, output parsing
+- [Calculators](doc/calculators.md): calculator types, URIs, configuration
+- [Formulas and interpreters](doc/formulas-and-interpreters.md): Python/R formula evaluation
+- [Parallelism and caching](doc/parallel-and-caching.md): performance strategies
+- [Quick examples](doc/quick-examples.md): common usage patterns
 
 ## Examples
 
@@ -41,5 +42,5 @@ extract outputs; *calculators* (URIs like `sh://cmd`, `ssh://user@host/cmd`,
 ## Optional
 
 - [Release notes](NEWS.md)
-- [Funz protocol](context/funz-protocol.md): legacy Java Funz server protocol
-- [Shell path configuration](context/shell-path.md): bash on Windows (FZ_SHELL_PATH)
+- [Funz protocol](doc/funz-protocol.md): legacy Java Funz server protocol
+- [Shell path configuration](doc/shell-path.md): bash on Windows (FZ_SHELL_PATH)