Merge pull request #64 from Funz/docs/restructure-context-doc-and-skill-wrappers

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

Author: yannrichet-asnr

.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.mdcontext/INDEX.md renamed to 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.mdcontext/README.md renamed to 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/calculators.md doc/calculators.mdcontext/calculators.md renamed to doc/calculators.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