docs(config): fix CLI command examples and clarify templates vs examples

Corrected CLI invocation syntax throughout documentation by adding the
missing 'run_sim' subcommand. The correct format is:
`python -m fusion.cli.run_sim run_sim --config_path ...`

Added comprehensive "Templates vs Examples" section to configs/README.md
explaining the distinction between generic reusable templates and
specific ready-to-run example configurations.

Changes include:
- Fix CLI command examples in cli/README.md and configs/examples/README.md
- Add "Templates vs Examples" section with comparison table and usage guidance
- Add TODO for YAML/JSON configuration file input support
- Add TODO for single entry point CLI architecture (fusion run_sim)
- Add TODO for schema system consolidation (schema.py vs schemas/*.json)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: ryanmccann1024

fusion/cli/README.md

@@ -36,7 +36,7 @@ config = setup_config_from_cli(args)
 ### Entry Point Usage
 ```bash
 # Run simulation
-python -m fusion.cli.run_sim --config_path config.ini
+python -m fusion.cli.run_sim run_sim --config_path config.ini
 
 # Train an agent
 python -m fusion.cli.run_train --agent_type rl --config_path config.ini

fusion/cli/TODO.md

@@ -26,3 +26,23 @@
 - **Issue**: Multi-processing functionality is no longer supported in the current implementation
 - **Impact**: Users cannot run parallel simulations across multiple processes, limiting scalability for large-scale experiments
 - **Solution**: Re-implement multi-processing support with proper process management, configuration handling, and result aggregation
+
+## Medium Priority
+
+### Single Entry Point CLI Architecture
+- **Issue**: Current CLI design requires redundant subcommand pattern (`python -m fusion.cli.run_sim run_sim`)
+- **Files**: `run_sim.py`, `run_train.py`, `run_gui.py`, `main_parser.py`, `registry.py`
+- **Description**: The current architecture uses separate module entry points (run_sim.py, run_train.py, run_gui.py) each with their own subcommand parser, resulting in awkward invocation patterns like `python -m fusion.cli.run_sim run_sim` where "run_sim" appears twice
+- **Impact**: Confusing user experience, inconsistent with modern CLI tools, harder to discover available commands
+- **Proposed Solution**: Create single unified entry point with cleaner subcommand structure:
+  - `fusion run_sim` instead of `python -m fusion.cli.run_sim run_sim`
+  - `fusion train` instead of `python -m fusion.cli.run_train`
+  - `fusion gui` instead of `python -m fusion.cli.run_gui`
+  - `fusion analyze` for future analysis commands
+- **Next Steps**:
+  1. Create main `fusion` entry point script
+  2. Consolidate all subcommands under single parser
+  3. Update setup.py/pyproject.toml with console_scripts entry point
+  4. Migrate existing entry points to subcommand handlers
+  5. Update all documentation with new invocation patterns
+  6. Maintain backward compatibility during transition period

fusion/configs/README.md

@@ -139,6 +139,51 @@ config_manager.merge_cli_args({'max_iters': 5})
 | `rl_training.ini` | RL experiments | Epsilon-greedy, medium loads |
 | `cross_platform.ini` | CI/CD | OS-agnostic paths, simple config |
 
+## Templates vs Examples
+
+The `configs/` directory contains both **templates** and **examples** - understanding the difference is important:
+
+### Templates (`templates/`)
+**Generic, reusable base configurations** designed as starting points:
+- Loaded programmatically via `ConfigRegistry.load_template('minimal')`
+- Used with profiles and overrides for customization
+- Broad, general-purpose settings applicable to many scenarios
+- Minimal comments, focused on being a foundation to build upon
+
+**When to use:** Starting a new simulation or creating custom configurations
+
+```python
+# Programmatic usage
+registry = ConfigRegistry()
+config = registry.create_custom_config('minimal', overrides={'erlang_start': 500})
+```
+
+### Examples (`examples/`)
+**Specific, ready-to-run scenarios** demonstrating particular features:
+- Complete configurations for specific use cases (link failures, RL evaluation, etc.)
+- Heavily documented with context explaining the scenario
+- Ready to run without modification
+- Reference implementations showing how to configure advanced features
+
+**When to use:** Learning the system, reproducing specific experiments, or as reference
+
+```bash
+# Direct usage
+python -m fusion.cli.run_sim run_sim --config_path fusion/configs/examples/link_failure_ksp_ff.ini
+```
+
+### Quick Comparison
+
+| Aspect | Templates | Examples |
+|--------|-----------|----------|
+| **Purpose** | Generic starting points | Specific use cases |
+| **Scope** | Broad, reusable | Narrow, scenario-focused |
+| **Usage** | Customize via code or CLI overrides | Run directly or copy |
+| **Documentation** | Minimal comments | Heavily documented |
+| **Registry support** | Yes (`load_template()`) | No (just files) |
+
+**Analogy:** Templates are like "Basic Soup" recipes you customize; Examples are like "Minestrone Soup" recipes you follow exactly.
+
 ## Migration Notes
 - Legacy INI files work without modification
 - New features (validation, templates) are opt-in

fusion/configs/TODO.md

@@ -24,6 +24,18 @@ This file tracks known issues and future improvements for the FUSION configurati
   2. Ensure save_step aligns with Unity's requirements
   3. Add validation for compatible save_step values
 
+### YAML and JSON Configuration File Input
+- **Issue**: YAML and JSON configuration file input needs implementation and validation
+- **Files**: `cli_to_config.py`
+- **Description**: While the system supports INI files, YAML and JSON configuration file formats have not been fully implemented or validated
+- **Impact**: Limits configuration flexibility and integration with modern tooling that expects YAML/JSON formats
+- **Next Steps**:
+  1. Implement YAML configuration file parser
+  2. Implement JSON configuration file parser
+  3. Validate parsing against existing INI-based configurations
+  4. Add comprehensive tests for both formats
+  5. Update documentation with examples for each format
+
 ## Medium Priority
 
 ### Template System Enhancements
@@ -50,6 +62,30 @@ This file tracks known issues and future improvements for the FUSION configurati
   2. Implement enhanced schema validation
   3. Add informative error messages
 
+### Schema System Consolidation
+- **Issue**: Redundant schema systems with overlapping responsibilities
+- **Files**: `schema.py`, `schemas/main.json`, `schemas/survivability.json`, `validate.py`
+- **Description**: The codebase has two separate schema systems serving different purposes:
+  - `schema.py`: Python dictionaries mapping fields to type converter functions (e.g., `float`, `str_to_bool`)
+  - `schemas/*.json`: JSON Schema files for validation with constraints (e.g., `minimum: 0`, `enum` values)
+  - This creates redundancy and maintenance burden as changes must be made in both places
+- **Impact**:
+  - Duplication of field definitions across two systems
+  - Increased maintenance overhead when adding/modifying fields
+  - Confusion about which system is authoritative
+  - Risk of inconsistencies between the two schemas
+- **Proposed Solution**: Consolidate to single schema system
+  - **Option A**: Use only JSON Schema as single source of truth, generate type converters from it
+  - **Option B**: Use Python dataclasses with validation decorators (e.g., Pydantic)
+  - **Option C**: Keep JSON Schema for validation, auto-generate `schema.py` from JSON files
+- **Next Steps**:
+  1. Evaluate consolidation options (JSON Schema-only vs dataclasses vs hybrid)
+  2. Choose approach based on maintainability and Python ecosystem best practices
+  3. Design migration path that maintains backward compatibility
+  4. Implement schema generation/consolidation tooling
+  5. Update all configuration loading code to use unified system
+  6. Remove deprecated schema system after validation
+
 ## Low Priority
 
 ### Template Description Injection

fusion/configs/examples/README.md

@@ -18,7 +18,7 @@ This directory contains example configurations for common survivability experime
 
 **Run**:
 ```bash
-python -m fusion.cli.run_sim --config_path fusion/configs/examples/link_failure_ksp_ff.ini
+python -m fusion.cli.run_sim run_sim --config_path fusion/configs/examples/link_failure_ksp_ff.ini
 ```
 
 ---
@@ -37,7 +37,7 @@ python -m fusion.cli.run_sim --config_path fusion/configs/examples/link_failure_
 
 **Run**:
 ```bash
-python -m fusion.cli.run_sim --config_path fusion/configs/examples/geo_failure_protection.ini
+python -m fusion.cli.run_sim run_sim --config_path fusion/configs/examples/geo_failure_protection.ini
 ```
 
 ---
@@ -57,7 +57,7 @@ python -m fusion.cli.run_sim --config_path fusion/configs/examples/geo_failure_p
 
 **Run**:
 ```bash
-python -m fusion.cli.run_sim --config_path fusion/configs/examples/rl_policy_eval.ini
+python -m fusion.cli.run_sim run_sim --config_path fusion/configs/examples/rl_policy_eval.ini
 ```
 
 **Note**: Requires trained BC model at `models/bc_model.pt`.
@@ -78,7 +78,7 @@ python -m fusion.cli.run_sim --config_path fusion/configs/examples/rl_policy_eva
 
 **Run**:
 ```bash
-python -m fusion.cli.run_sim --config_path fusion/configs/examples/dataset_generation.ini
+python -m fusion.cli.run_sim run_sim --config_path fusion/configs/examples/dataset_generation.ini
 ```
 
 **Output**: JSONL dataset at `datasets/training_dataset.jsonl`
@@ -130,15 +130,15 @@ python -m fusion.cli.run_sim --config_path fusion/configs/examples/dataset_gener
 ### Running with Different Seeds
 
 ```bash
-python -m fusion.cli.run_sim \
+python -m fusion.cli.run_sim run_sim \
   --config_path fusion/configs/examples/link_failure_ksp_ff.ini \
   --seed 43
 ```
 
 ### Changing Failure Parameters
 
 ```bash
-python -m fusion.cli.run_sim \
+python -m fusion.cli.run_sim run_sim \
   --config_path fusion/configs/examples/geo_failure_protection.ini \
   --geo_center_node 7 \
   --geo_hop_radius 3
@@ -159,7 +159,7 @@ Run multiple configurations with different seeds for statistical significance:
 ```bash
 #!/bin/bash
 for seed in 42 43 44 45 46; do
-  python -m fusion.cli.run_sim \
+  python -m fusion.cli.run_sim run_sim \
     --config_path fusion/configs/examples/rl_policy_eval.ini \
     --seed $seed
 done