fix: address inconcsistencies with --sys and --drop-privileges + update docs

Author: ra0x3

docs/docs/how-it-works/commands/index.md

@@ -13,7 +13,7 @@ $ sysg stop                      # Stop services
 $ sysg restart                   # Restart services
 $ sysg status                    # Check health
 $ sysg logs                      # View output
-$ sysg inspect api               # View metrics
+$ sysg inspect --service api     # View metrics
 $ sysg spawn --name w1 -- cmd    # Create child
 $ sysg purge                     # Clear all state
 ```

docs/docs/how-it-works/commands/inspect.md

@@ -8,18 +8,18 @@ title: inspect
 View detailed metrics for a specific service.
 
 ```sh
-$ sysg inspect myservice
+$ sysg inspect --service myservice
 ```
 
 ## Options
 
 | Option | Description |
 |--------|------------|
+| `-s, --service` | Name of the service to inspect |
 | `--stream` | Continuously refresh output and render a rolling metrics window of the provided duration (e.g., `5`, `1s`, `2m`) |
 | `--config` | Path to configuration file |
 | `--json` | Emit machine-readable JSON output instead of a report |
 | `--sys` | Opt into privileged system mode. Requires running as root |
-| `--drop-privileges` | Drop privileges after performing privileged setup |
 | `--no-color` | Disable ANSI colors in output |
 | `--log-level` | Set verbosity (`debug`, `info`, `warn`, `error`) |
 
@@ -28,7 +28,7 @@ $ sysg inspect myservice
 ### View service metrics
 
 ```sh
-$ sysg inspect api
+$ sysg inspect --service api
 ```
 
 Shows CPU and memory usage chart:
@@ -54,15 +54,7 @@ CPU: 45.2% (current)  Memory: 23.1% (current)
 ### Stream with a longer rolling window
 
 ```sh
-$ sysg inspect api --stream 24h
-```
-
-### Inspect by hash
-
-Useful for cron jobs:
-
-```sh
-$ sysg inspect 3abad7ffa39c
+$ sysg inspect --service api --stream 24h
 ```
 
 ## Metrics shown

docs/docs/how-it-works/commands/logs.md

@@ -21,7 +21,6 @@ $ sysg logs
 | `--kind` | Kind of logs to show: stdout, stderr, or supervisor (default: stderr) |
 | `--stream` | Continuously refresh the latest log snapshot at the provided interval (e.g., `5`, `1s`, `2m`) |
 | `--sys` | Opt into privileged system mode. Requires running as root |
-| `--drop-privileges` | Drop privileges after performing privileged setup |
 | `--log-level` | Set verbosity (`debug`, `info`, `warn`, `error`) |
 
 ## Examples

docs/docs/how-it-works/commands/purge.md

@@ -18,7 +18,6 @@ $ sysg purge
 | Option | Description |
 |--------|------------|
 | `--sys` | Opt into privileged system mode. Requires running as root |
-| `--drop-privileges` | Drop privileges after performing privileged setup |
 | `--log-level` | Set verbosity (`debug`, `info`, `warn`, `error`) |
 
 ## What gets removed

docs/docs/how-it-works/commands/restart.md

@@ -47,7 +47,8 @@ $ sudo sysg restart --sys
 
 ### `--drop-privileges`
 
-Drop privileges after performing privileged setup.
+Drop child service privileges during spawn. When enabled in root/system mode,
+services without an explicit `user` run as `nobody`.
 
 ```sh
 $ sudo sysg restart --sys --drop-privileges

docs/docs/how-it-works/commands/spawn.md

@@ -19,7 +19,6 @@ $ sysg spawn --name worker_1 -- python worker.py
 | `--ttl` | Time-to-live in seconds (optional) |
 | `--parent-pid` | Parent process ID (defaults to caller's parent PID if not specified) |
 | `--sys` | Opt into privileged system mode. Requires running as root |
-| `--drop-privileges` | Drop privileges after performing privileged setup |
 | `--log-level` | Override the logging verbosity for the spawned process |
 
 ## Examples

docs/docs/how-it-works/commands/start.md

@@ -47,7 +47,8 @@ $ sudo sysg start --sys
 
 ### `--drop-privileges`
 
-Drop privileges after performing privileged setup.
+Drop child service privileges during spawn. When enabled in root/system mode,
+services without an explicit `user` run as `nobody`.
 
 ```sh
 $ sudo sysg start --sys --drop-privileges

docs/docs/how-it-works/commands/status.md

@@ -19,7 +19,6 @@ $ sysg status
 | `--service` | Show specific service details |
 | `--all` | Show all services including orphaned state (services not in current config) |
 | `--sys` | Opt into privileged system mode. Requires running as root |
-| `--drop-privileges` | Drop privileges after performing privileged setup |
 | `--json` | Emit machine-readable JSON output instead of a table |
 | `--no-color` | Disable ANSI colors in output |
 | `--stream` | Continuously refresh status at the provided interval (e.g., `5`, `1s`, `2m`) |

docs/docs/how-it-works/commands/stop.md

@@ -37,14 +37,6 @@ Opt into privileged system mode. Requires running as root.
 $ sudo sysg stop --sys
 ```
 
-### `--drop-privileges`
-
-Drop privileges after performing privileged setup.
-
-```sh
-$ sudo sysg stop --sys --drop-privileges
-```
-
 ### `--log-level`
 
 Set logging verbosity for this invocation. Accepts named levels (`trace`, `debug`, `info`, `warn`, `error`, `off`) or numeric values (5-0).

docs/docs/how-it-works/privileged-mode.md

@@ -22,6 +22,9 @@ Enable privileged mode to:
 $ sudo sysg --sys start --daemonize
 ```
 
+If you also pass `--drop-privileges`, it applies to child service processes at
+spawn time (not to read-only control commands like `status` or `logs`).
+
 The `--sys` flag moves state to system directories:
 - `/var/lib/systemg/` - Runtime state
 - `/var/log/systemg/` - Logs