docs: document lifecycle triggers and deprecate trigger-running

docs/experiments.md

@@ -68,7 +68,8 @@ Available Commands:
   scorch          Start a Scorch run for experiment
   start           Start an experiment
   stop            Stop an experiment
-  trigger-running Trigger running stage for app(s) in experiment
+  trigger            Trigger lifecycle stage for app(s) in experiment
+  trigger-running Trigger running stage for app(s) in experiment (deprecated - use `trigger`)
 
 Flags:
   -h, --help   help for experiment
@@ -227,3 +228,75 @@ Then apply the desired schedule with the following command.
 ```
 $> phenix experiment schedule <experiment name> <algorithm>
 ```
+
+## Triggering App Lifecycle Stages
+
+You can manually trigger specific app lifecycle stages for a running or stopped
+experiment without needing to stop and restart it.
+
+### From the Command Line
+
+The `phenix exp trigger` command allows you to invoke app lifecycle stages on demand:
+
+```
+$> phenix exp trigger <lifecycle> <experiment name> [<app name> ...]
+```
+
+Where `<lifecycle>` can be one of:
+- `configure` (or `config`)
+- `pre-start` (or `pre`)
+- `post-start` (or `post`)
+- `running` (or `run`)
+- `cleanup` (or `clean`)
+
+**Examples:**
+
+Trigger the running stage for all apps in an experiment:
+```
+$> phenix exp trigger running my-experiment
+```
+
+Trigger the running stage for a specific app:
+```
+$> phenix exp trigger running my-experiment soh
+```
+
+Trigger configure stage for all experiments:
+```
+$> phenix exp trigger configure all
+```
+
+### `trigger configure` vs. `reconfigure`
+
+`phenix exp trigger configure` and `phenix experiment reconfigure` both re-run
+the `configure` lifecycle stage, but they serve different purposes and are not
+interchangeable:
+
+| | `phenix exp trigger configure` | `phenix experiment reconfigure` |
+|---|---|---|
+| Use case | Manually re-run a specific app's (or apps') configure hook on demand, e.g. for debugging | Re-apply configuration after editing an experiment's stored topology, scenario, or deployment settings |
+| Targets specific apps | Yes, via `[<app name> ...]` | No, always applies to every app |
+| Validates the experiment config | No | Yes |
+| Runs registered config hooks | No | Yes |
+| Resets the minimega bridge | No | Yes (deletes it so it's recreated with current settings, unless using the GRE mesh) |
+| Guards against running experiments | No | Yes (refuses to run if the experiment is running) |
+
+Use `phenix experiment reconfigure` after changing an experiment's stored
+settings. Use `phenix exp trigger configure` for targeted, on-demand
+re-invocation of one or more apps' configure hooks, such as when debugging an
+app.
+
+### Deprecated Command
+
+The `phenix exp trigger-running` command is deprecated and will be removed in a
+future release. Please use `phenix exp trigger running` instead.
+
+The deprecated command:
+```
+$> phenix exp trigger-running my-experiment [<app name> ...]
+```
+
+Is equivalent to:
+```
+$> phenix exp trigger running my-experiment [<app name> ...]
+```

docs/state-of-health.md

@@ -164,7 +164,11 @@ details. (In this screenshot, the mouse is hovering over the traffic for IP
   when some processes are not healthy immediately at experiment start. This
   only delays SoH when it first runs at the experiment start. It will not delay
   SoH when run manually later by clicking the 'Run SoH' button in the UI or
-  using the command line `trigger-running` command. The default is no delay.
+  using the command line with either:
+  - `phenix exp trigger running <experiment name>`
+  - `phenix exp trigger-running <experiment name>` (deprecated)
+
+  The default is no delay.
 
 * `hostCustomTests`: If present, a map of custom tests to run on the given
   hosts.