fix: proper process-first CLI invocation instructions and input validation

Co-authored-by: chefgs <7605658+chefgs@users.noreply.github.com>

Author: Copilot

README.md

@@ -91,7 +91,28 @@ source .venv/bin/activate        # macOS / Linux
 pip install -r cli/requirements.txt
 ```
 
-### 2 — Generate a GitHub Actions workflow
+### 2 — Learn the Process-First philosophy *(recommended first step)*
+
+DevOps-OS is built on the **Process-First** SDLC philosophy from [cloudenginelabs.io](https://cloudenginelabs.io). Run the `process-first` command to understand *why* each tool exists before you start using it:
+
+```bash
+# Full overview — what Process-First is, how it maps to DevOps-OS, and learning tips
+python -m cli.devopsos process-first
+
+# Just the 5 core principles
+python -m cli.devopsos process-first --section what
+
+# Table: which scaffold command encodes which principle
+python -m cli.devopsos process-first --section mapping
+
+# AI prompts and book recommendations for beginners
+python -m cli.devopsos process-first --section tips
+```
+
+> **Tip:** Run `--section mapping` to see exactly which `devopsos scaffold` command to use for each DevOps goal before generating any config.  
+> See [docs/PROCESS-FIRST.md](docs/PROCESS-FIRST.md) for the full reference.
+
+### 3 — Generate a GitHub Actions workflow
 
 ```bash
 # Complete CI/CD for a Python + JavaScript project
@@ -101,7 +122,7 @@ python -m cli.scaffold_gha --name my-app --languages python,javascript --type co
 python -m cli.scaffold_gha --name my-app --languages python --kubernetes --k8s-method kustomize
 ```
 
-### 3 — Generate other pipelines & configs
+### 4 — Generate other pipelines & configs
 
 ```bash
 # Jenkins pipeline → Jenkinsfile
@@ -128,7 +149,7 @@ python kubernetes/k8s-config-generator.py --name my-app --image ghcr.io/myorg/my
 
 > See [CLI Commands Reference](docs/CLI-COMMANDS-REFERENCE.md) for the full option tables and every default output path.
 
-### 4 — Interactive wizard (all-in-one)
+### 5 — Interactive wizard (all-in-one)
 
 ```bash
 python -m cli.devopsos init              # interactive project configurator
@@ -138,15 +159,9 @@ python -m cli.devopsos scaffold jenkins  # scaffold Jenkins
 python -m cli.devopsos scaffold argocd       # scaffold ArgoCD / Flux
 python -m cli.devopsos scaffold sre          # scaffold SRE configs
 python -m cli.devopsos scaffold devcontainer # scaffold dev container config
-
-# Learn the Process-First philosophy and how it maps to DevOps-OS tooling
-python -m cli.devopsos process-first                  # full overview
-python -m cli.devopsos process-first --section what   # ideology & core principles
-python -m cli.devopsos process-first --section mapping # principle → tool mapping
-python -m cli.devopsos process-first --section tips   # AI prompts for beginners
 ```
 
-### 5 — Use with AI (MCP Server)
+### 6 — Use with AI (MCP Server)
 
 ```bash
 pip install -r mcp_server/requirements.txt

cli/devopsos.py

@@ -1,3 +1,4 @@
+import enum
 import typer
 from InquirerPy import inquirer
 import json
@@ -14,6 +15,14 @@
 import cli.scaffold_devcontainer as scaffold_devcontainer
 import cli.process_first as process_first
 
+class ProcessFirstSection(str, enum.Enum):
+    """Valid sections for the process-first command."""
+    what = "what"
+    mapping = "mapping"
+    tips = "tips"
+    all = "all"
+
+
 app = typer.Typer(help="Unified DevOps-OS CLI tool")
 
 @app.command()
@@ -154,10 +163,34 @@ def scaffold(
 
 @app.command("process-first")
 def process_first_cmd(
-    section: str = typer.Option("all", help="Section to display: what | mapping | tips | all"),
+    section: ProcessFirstSection = typer.Option(
+        ProcessFirstSection.all,
+        help=(
+            "Section to display:\n\n"
+            "  'what'    — What Process-First is and its 5 core principles\n\n"
+            "  'mapping' — How each principle maps to a devopsos scaffold command\n\n"
+            "  'tips'    — AI prompts and book recommendations for DevOps beginners\n\n"
+            "  'all'     — All sections combined (default)"
+        ),
+        show_choices=True,
+    ),
 ):
-    """Learn about the Process-First SDLC philosophy and how it maps to DevOps-OS tooling."""
-    process_first.display(section)
+    """Learn about the Process-First SDLC philosophy and how it maps to DevOps-OS tooling.
+
+    \b
+    Quick invocation guide:
+
+      python -m cli.devopsos process-first                    # full overview
+      python -m cli.devopsos process-first --section what     # core principles
+      python -m cli.devopsos process-first --section mapping  # tool mapping table
+      python -m cli.devopsos process-first --section tips     # AI prompts for beginners
+
+    You can also run the module directly:
+
+      python -m cli.process_first
+      python -m cli.process_first --section mapping
+    """
+    process_first.display(section.value)
 
 
 if __name__ == "__main__":

cli/test_cli.py

@@ -358,3 +358,14 @@ def test_process_first_module_section_mapping():
     assert result.returncode == 0
     assert "scaffold" in result.stdout.lower()
 
+
+def test_process_first_invalid_section_clean_error():
+    """Invalid --section value gives a clean CLI error, not a Python traceback."""
+    result = _run(["-m", "cli.devopsos", "process-first", "--section", "invalid"])
+    assert result.returncode != 0
+    combined = result.stdout + result.stderr
+    # Typer enum validation produces: "Invalid value for '--section': 'invalid' is not one of ..."
+    assert "Traceback" not in combined, "Expected clean CLI error, not a Python traceback"
+    assert "ValueError" not in combined, "Expected clean CLI error, not a ValueError"
+    assert "is not one of" in combined or "Invalid value" in combined
+