Enhance documentation and CLI functionality

Author: networmix

.github/copilot-instructions.md

@@ -34,14 +34,16 @@ You work as an experienced senior software engineer on the **NetGraph** project,
 
 ---
 
-# Contribution Guidelines for NetGraph
+## Contribution Guidelines for NetGraph
 
 ### 1 – Style & Linting
+
 - Follow **PEP 8** with an 88-character line length.
 - All linting/formatting is handled by **ruff**; import order is automatic.
 - Do not run `black`, `isort`, or other formatters manually—use `make format` instead.
 
 ### 2 – Docstrings
+
 - Use **Google-style** docstrings for every public module, class, function, and method.
 - Single-line docstrings are acceptable for simple private helpers.
 - Keep the prose concise and factual—no marketing fluff or AI verbosity.
@@ -138,11 +140,14 @@ Prioritize **why** over **what**, but include **what** when code is non-obvious.
 * Update `docs/` when adding features.
 * Run `make docs` to generate `docs/reference/api-full.md` from source code.
 * Always check all doc files for accuracy, absence of marketing language, and AI verbosity.
+* **Markdown formatting**: Lists, code blocks, and block quotes require a blank line before them to render correctly.
 
 ## Output rules for the assistant
 
 1. Run Ruff format in your head before responding.
 2. Include Google-style docstrings and type hints.
 3. Write or update unit tests for new functionality; fix code (not tests) when existing tests fail. Exception: tests may be changed after thorough analysis if they are genuinely flawed, requirements have changed, or breaking changes are approved.
 4. Respect existing public API signatures unless the user approves breaking changes.
-5. If you need more information, ask concise clarification questions.
+5. Document all new features and changes in the codebase. Run `make docs` to generate the full API reference.
+6. Run `make check` before finishing to ensure all code passes linting, type checking, and tests.
+7. If you need more information, ask concise clarification questions.

docs/examples/basic.md

@@ -143,6 +143,7 @@ print(f"Sensitivity to capacity decreases: {sensitivity_decrease}")
 ```
 
 This analysis helps identify:
+
 - **Bottleneck edges**: Links that are fully utilized and limit overall flow
 - **High-impact upgrades**: Which capacity increases provide the most benefit
 - **Vulnerability assessment**: How flow decreases when links are degraded

docs/examples/clos-fabric.md

@@ -101,6 +101,7 @@ print(f"Maximum flow with ECMP: {max_flow_ecmp}")
 ## Understanding the Results
 
 The result `{('b1|b2', 'b1|b2'): 256.0}` means:
+
 - **Source**: All t1 nodes in both b1 and b2 segments of my_clos1
 - **Sink**: All t1 nodes in both b1 and b2 segments of my_clos2
 - **Capacity**: Maximum flow of 256.0 units

docs/reference/api-full.md

@@ -10,7 +10,7 @@ For a curated, example-driven API guide, see **[api.md](api.md)**.
 > - **[CLI Reference](cli.md)** - Command-line interface
 > - **[DSL Reference](dsl.md)** - YAML syntax guide
 
-**Generated from source code on:** June 15, 2025 at 18:31 UTC
+**Generated from source code on:** June 16, 2025 at 17:06 UTC
 
 **Modules auto-discovered:** 42
 

docs/reference/cli.md

@@ -15,15 +15,21 @@ pip install ngraph
 The primary command is `run`, which executes scenario files:
 
 ```bash
-# Run a scenario and write results to results.json
+# Run a scenario (execution only, no file output)
 python -m ngraph run scenario.yaml
 
-# Write results to a custom file
+# Run a scenario and export results to results.json
+python -m ngraph run scenario.yaml --results
+
+# Export results to a custom file
 python -m ngraph run scenario.yaml --results output.json
 python -m ngraph run scenario.yaml -r output.json
 
-# Print results to stdout as well
+# Print results to stdout only (no file)
 python -m ngraph run scenario.yaml --stdout
+
+# Export to file AND print to stdout
+python -m ngraph run scenario.yaml --results --stdout
 ```
 
 ## Command Reference
@@ -33,6 +39,7 @@ python -m ngraph run scenario.yaml --stdout
 Execute a NetGraph scenario file.
 
 **Syntax:**
+
 ```bash
 python -m ngraph run <scenario_file> [options]
 ```
@@ -43,7 +50,7 @@ python -m ngraph run <scenario_file> [options]
 
 **Options:**
 
-- `--results`, `-r`: Output file path for results (JSON format)
+- `--results`, `-r`: Optional path to export results as JSON. If provided without a path, defaults to "results.json"
 - `--stdout`: Print results to stdout
 - `--keys`, `-k`: Space-separated list of workflow step names to include in output
 - `--help`, `-h`: Show help message
@@ -53,21 +60,27 @@ python -m ngraph run <scenario_file> [options]
 ### Basic Execution
 
 ```bash
-# Run a scenario (writes results.json)
+# Run a scenario (execution only, no output files)
 python -m ngraph run my_network.yaml
+
+# Run a scenario and export results to default file
+python -m ngraph run my_network.yaml --results
 ```
 
 ### Save Results to File
 
 ```bash
-# Save results to a JSON file
+# Save results to a custom JSON file
 python -m ngraph run my_network.yaml --results analysis.json
+
+# Save to file AND print to stdout
+python -m ngraph run my_network.yaml --results analysis.json --stdout
 ```
 
 ### Running Test Scenarios
 
 ```bash
-# Run one of the included test scenarios
+# Run one of the included test scenarios with results export
 python -m ngraph run tests/scenarios/scenario_1.yaml --results results.json
 ```
 
@@ -76,14 +89,14 @@ python -m ngraph run tests/scenarios/scenario_1.yaml --results results.json
 You can filter the output to include only specific workflow steps using the `--keys` option:
 
 ```bash
-# Only include results from the capacity_probe step
-python -m ngraph run scenario.yaml --keys capacity_probe
+# Only include results from the capacity_probe step (stdout only)
+python -m ngraph run scenario.yaml --keys capacity_probe --stdout
 
-# Include multiple specific steps
-python -m ngraph run scenario.yaml --keys build_graph capacity_probe
+# Include multiple specific steps and export to file
+python -m ngraph run scenario.yaml --keys build_graph capacity_probe --results filtered.json
 
-# Filter and print to stdout
-python -m ngraph run scenario.yaml --keys capacity_probe --stdout
+# Filter and print to stdout while also saving to default file
+python -m ngraph run scenario.yaml --keys capacity_probe --results --stdout
 ```
 
 The `--keys` option filters by the `name` field of workflow steps defined in your scenario YAML file. For example, if your scenario has:
@@ -156,6 +169,44 @@ The exact keys and values depend on:
 - The parameters and results of each step
 - The network topology and analysis performed
 
+## Output Behavior
+
+**NetGraph CLI output behavior changed in recent versions** to provide more flexibility:
+
+### Default Behavior (No Output Flags)
+```bash
+python -m ngraph run scenario.yaml
+```
+- Executes the scenario
+- Logs execution progress to the terminal
+- **Does not create any output files**
+- **Does not print results to stdout**
+
+### Export to File
+```bash
+# Export to default file (results.json)
+python -m ngraph run scenario.yaml --results
+
+# Export to custom file
+python -m ngraph run scenario.yaml --results my_analysis.json
+```
+
+### Print to Terminal
+```bash
+python -m ngraph run scenario.yaml --stdout
+```
+- Prints JSON results to stdout
+- **Does not create any files**
+
+### Combined Output
+```bash
+python -m ngraph run scenario.yaml --results analysis.json --stdout
+```
+- Creates a JSON file AND prints to stdout
+- Useful for viewing results immediately while also saving them
+
+**Migration Note:** If you were relying on automatic `results.json` creation, add the `--results` flag to your commands.
+
 ## Integration with Workflows
 
 The CLI executes the complete workflow defined in your scenario file, running all steps in sequence and accumulating results. This automates complex network analysis tasks without manual intervention.

docs/reference/dsl.md

@@ -587,6 +587,7 @@ When using capturing groups `(...)` in regex patterns, NetGraph groups matching
 **Adjacency Matching:**
 
 In `adjacency` blocks (both in blueprints and top-level network):
+
 - `source` and `target` fields accept regex patterns
 - Blueprint paths can be relative (no leading `/`) or absolute (with leading `/`)
 - Relative paths are resolved relative to the blueprint instance's path

ngraph/cli.py

@@ -15,15 +15,15 @@
 
 def _run_scenario(
     path: Path,
-    output: Path,
+    output: Optional[Path],
     stdout: bool,
     keys: Optional[list[str]] = None,
 ) -> None:
-    """Run a scenario file and store results as JSON.
+    """Run a scenario file and optionally export results as JSON.
 
     Args:
         path: Scenario YAML file.
-        output: Path where results should be written.
+        output: Optional path where JSON results should be written. If None, no JSON export.
         stdout: Whether to also print results to stdout.
         keys: Optional list of workflow step names to include. When ``None`` all steps are
             exported.
@@ -38,23 +38,36 @@ def _run_scenario(
         scenario.run()
         logger.info("Scenario execution completed successfully")
 
-        logger.info("Serializing results to JSON")
-        results_dict: Dict[str, Dict[str, Any]] = scenario.results.to_dict()
-
-        if keys:
-            filtered: Dict[str, Dict[str, Any]] = {}
-            for step, data in results_dict.items():
-                if step in keys:
-                    filtered[step] = data
-            results_dict = filtered
-
-        json_str = json.dumps(results_dict, indent=2, default=str)
-
-        logger.info(f"Writing results to: {output}")
-        output.write_text(json_str)
-        logger.info("Results written successfully")
-
-        if stdout:
+        # Only export JSON if output path is provided
+        if output:
+            logger.info("Serializing results to JSON")
+            results_dict: Dict[str, Dict[str, Any]] = scenario.results.to_dict()
+
+            if keys:
+                filtered: Dict[str, Dict[str, Any]] = {}
+                for step, data in results_dict.items():
+                    if step in keys:
+                        filtered[step] = data
+                results_dict = filtered
+
+            json_str = json.dumps(results_dict, indent=2, default=str)
+
+            logger.info(f"Writing results to: {output}")
+            output.write_text(json_str)
+            logger.info("Results written successfully")
+
+            if stdout:
+                print(json_str)
+        elif stdout:
+            # Print to stdout even without file export
+            results_dict: Dict[str, Dict[str, Any]] = scenario.results.to_dict()
+            if keys:
+                filtered: Dict[str, Dict[str, Any]] = {}
+                for step, data in results_dict.items():
+                    if step in keys:
+                        filtered[step] = data
+                results_dict = filtered
+            json_str = json.dumps(results_dict, indent=2, default=str)
             print(json_str)
 
     except FileNotFoundError:
@@ -90,13 +103,14 @@ def main(argv: Optional[List[str]] = None) -> None:
         "--results",
         "-r",
         type=Path,
-        default=Path("results.json"),
-        help="Path to write JSON results (default: results.json)",
+        nargs="?",
+        const=Path("results.json"),
+        help="Export results to JSON file (default: results.json if no path specified)",
     )
     run_parser.add_argument(
         "--stdout",
         action="store_true",
-        help="Print results to stdout as well",
+        help="Print results to stdout",
     )
     run_parser.add_argument(
         "--keys",

ngraph/workflow/notebook_export.py

@@ -86,9 +86,14 @@ def run(self, scenario: "Scenario") -> None:
 
         if not results_dict:
             if self.allow_empty_results:
-                logger.info("No results found - creating minimal notebook")
+                logger.warning(
+                    "No analysis results found, but proceeding with empty notebook "
+                    "because 'allow_empty_results=True'. This may indicate missing "
+                    "analysis steps in the scenario workflow."
+                )
+                # Always export JSON file, even if empty, for consistency
+                self._save_results_json({}, json_output_path)
                 nb = self._create_empty_notebook()
-                json_output_path = None
             else:
                 raise ValueError(
                     "No analysis results found. Cannot create notebook without data. "
@@ -116,7 +121,9 @@ def run(self, scenario: "Scenario") -> None:
             # Create error notebook as fallback for write errors
             try:
                 nb = self._create_error_notebook(str(e))
-                self._write_notebook(nb, scenario, notebook_output_path, None)
+                self._write_notebook(
+                    nb, scenario, notebook_output_path, json_output_path
+                )
             except Exception as write_error:
                 logger.error(f"Failed to write error notebook: {write_error}")
                 raise

tests/test_cli.py

@@ -25,7 +25,8 @@ def test_cli_run_stdout(tmp_path: Path, capsys, monkeypatch) -> None:
     captured = capsys.readouterr()
     data = json.loads(captured.out)
     assert "build_graph" in data
-    assert (tmp_path / "results.json").exists()
+    # With new behavior, --stdout alone should NOT create a file
+    assert not (tmp_path / "results.json").exists()
 
 
 def test_cli_filter_keys(tmp_path: Path, capsys, monkeypatch) -> None:
@@ -463,3 +464,58 @@ def test_cli_regression_empty_results_with_filter() -> None:
 
         # The probe step should have actual data
         assert len(data["probe_step"]) > 0
+
+
+def test_cli_run_results_default(tmp_path: Path, monkeypatch) -> None:
+    """Test that --results with no path creates results.json."""
+    scenario = Path("tests/scenarios/scenario_1.yaml").resolve()
+    monkeypatch.chdir(tmp_path)
+    cli.main(["run", str(scenario), "--results"])
+    assert (tmp_path / "results.json").exists()
+    data = json.loads((tmp_path / "results.json").read_text())
+    assert "build_graph" in data
+
+
+def test_cli_run_results_custom_path(tmp_path: Path, monkeypatch) -> None:
+    """Test that --results with custom path creates file at that location."""
+    scenario = Path("tests/scenarios/scenario_1.yaml").resolve()
+    monkeypatch.chdir(tmp_path)
+    cli.main(["run", str(scenario), "--results", "custom_output.json"])
+    assert (tmp_path / "custom_output.json").exists()
+    assert not (tmp_path / "results.json").exists()
+    data = json.loads((tmp_path / "custom_output.json").read_text())
+    assert "build_graph" in data
+
+
+def test_cli_run_results_and_stdout(tmp_path: Path, capsys, monkeypatch) -> None:
+    """Test that --results and --stdout work together."""
+    scenario = Path("tests/scenarios/scenario_1.yaml").resolve()
+    monkeypatch.chdir(tmp_path)
+    cli.main(["run", str(scenario), "--results", "--stdout"])
+
+    # Check stdout output
+    captured = capsys.readouterr()
+    stdout_data = json.loads(captured.out)
+    assert "build_graph" in stdout_data
+
+    # Check file output
+    assert (tmp_path / "results.json").exists()
+    file_data = json.loads((tmp_path / "results.json").read_text())
+    assert "build_graph" in file_data
+
+    # Should be the same data
+    assert stdout_data == file_data
+
+
+def test_cli_run_no_output(tmp_path: Path, capsys, monkeypatch) -> None:
+    """Test that running without --results or --stdout creates no files."""
+    scenario = Path("tests/scenarios/scenario_1.yaml").resolve()
+    monkeypatch.chdir(tmp_path)
+    cli.main(["run", str(scenario)])
+
+    # No files should be created
+    assert not (tmp_path / "results.json").exists()
+
+    # No stdout output should be produced
+    captured = capsys.readouterr()
+    assert captured.out == ""