Refine app operator UX

README.md

@@ -195,9 +195,9 @@ yoq validate [-f manifest.toml] [-q] validate a manifest
 
 ```text
 yoq rollback <service>               roll back a service deployment
-yoq rollback --app [name]            print the last app release snapshot
-yoq rollback --app [name] --server host:port --release <id>
-                                     re-apply a prior app release remotely
+yoq rollback --app [name]            re-apply the previous successful app release
+yoq rollback --app [name] [--release <id>] [--print]
+yoq rollback --app [name] --server host:port [--release <id>] [--print]
 yoq history <service>                show service deployment history
 yoq history --app [name]             show local app release history
 yoq history --app [name] --server host:port [--json]
@@ -206,8 +206,10 @@ yoq status [--verbose]               show service status and resources
 yoq status --app [name]              show local app release status
 yoq status --app [name] --server host:port
                                      show remote app release status
-yoq apps [--json]                    list local app release summaries
-yoq apps --server host:port [--json] list remote app release summaries
+yoq apps [--json] [--status s|--failed|--in-progress]
+                                     list local app release summaries
+yoq apps --server host:port [--json] [--status s|--failed|--in-progress]
+                                     list remote app release summaries
 yoq metrics [service]                show service metrics
 yoq metrics --pairs                  show service-to-service metrics
 yoq policy deny <src> <tgt>          block traffic between services
@@ -235,6 +237,8 @@ yoq cert rm <domain>                 remove a certificate
 
 If `--email` is omitted for the standalone ACME flow, yoq uses `YOQ_ACME_EMAIL` when set and otherwise falls back to `admin@<domain>`.
 
+For app rollbacks, omitting `--release` picks the previous successful release before the current one. Use `--print` to inspect the selected stored app snapshot without applying it.
+
 ### server and cluster
 
 ```text

docs/cluster-guide.md

@@ -144,10 +144,10 @@ after deploy, use the app-first day-2 commands:
 yoq apps --server 10.0.0.1:7700
 yoq status --app [name] --server 10.0.0.1:7700
 yoq history --app [name] --server 10.0.0.1:7700
-yoq rollback --app [name] --server 10.0.0.1:7700 --release <release-id>
+yoq rollback --app [name] --server 10.0.0.1:7700 [--release <release-id>] [--print]
 ```
 
-`yoq apps` shows the latest release summary for every app, `status --app` shows the latest release metadata for one app, `history --app` lists prior releases, and remote `rollback --app ... --release` re-applies a stored app snapshot. `yoq run-worker --server ...` and `yoq train ... --server ...` now resolve workers and training jobs from the current app release on the server. Clustered app applies also register cron schedules from the current app snapshot, and the app summary/status views include live training runtime counts for the app.
+`yoq apps` shows the latest release summary for every app, `status --app` shows the latest release metadata for one app, `history --app` lists prior releases, and remote `rollback --app` re-applies the previous successful app release by default. Add `--release` to target a specific stored release or `--print` to inspect the selected snapshot without applying it. `yoq run-worker --server ...` and `yoq train ... --server ...` resolve workers and training jobs from the current app release on the server. Clustered app applies also register cron schedules from the current app snapshot, and the app summary/status views include live training runtime counts plus previous-successful release context for the app.
 
 ---
 
@@ -354,6 +354,7 @@ the important read paths are:
 - `GET /apps`
 - `GET /apps/<name>/status`
 - `GET /apps/<name>/history`
+- `POST /apps/<name>/rollback`
 - `GET /apps/<app>/training/<name>/status`
 - `GET /apps/<app>/training/<name>/logs`
 

docs/users-guide.md

@@ -167,13 +167,16 @@ this gives the operator one app-first day-2 model:
 
 - `yoq status --app [name]` — current app release status
 - `yoq history --app [name]` — app release history
-- `yoq rollback --app [name]` — print the last successful local app snapshot
-- `yoq rollback --app [name] --server host:port --release <id>` — re-apply a prior remote app release
-- `yoq apps` — list app release summaries across all known apps
+- `yoq rollback --app [name]` — re-apply the previous successful app release
+- `yoq rollback --app [name] [--release <id>] [--print]` — target a specific stored release or print the selected app snapshot without applying it
+- `yoq rollback --app [name] --server host:port [--release <id>] [--print]` — do the same against a cluster
+- `yoq apps [--status <status> | --failed | --in-progress]` — list app release summaries across all known apps with optional rollout filtering
 - `yoq run-worker [--server host:port] <name>` — run a worker from the current app release
 - `yoq train start|status|stop|pause|resume|scale|logs [--server host:port] <name>` — manage training jobs from the current app release
 
-`yoq apps` and `yoq status --app` now show both the desired workload mix from the latest app release and the current training runtime summary for that app. On clustered applies, cron definitions from the app snapshot are also registered in cluster state, so rollback restores the active cron schedule set along with the rest of the app snapshot.
+`yoq apps` and `yoq status --app` now show the current release, previous successful release, desired workload mix, rollout target counts, and the current training runtime summary for each app. On clustered applies, cron definitions from the app snapshot are also registered in cluster state, so rollback restores the active cron schedule set along with the rest of the app snapshot.
+
+When `--app` is present and you omit the app name, yoq defaults to the current working directory name for `status --app`, `history --app`, and `rollback --app`. When `rollback --app` omits `--release`, yoq selects the previous successful release before the current one.
 
 Remote `yoq train logs --server ...` now proxies the request to the agent that hosts the selected rank. If that agent is unreachable or does not expose the log endpoint, the API returns an explicit hosting-agent error instead of a misleading empty or missing result.
 
@@ -230,12 +233,12 @@ the cluster API also exposes app-scoped day-2 reads and rollback:
 - `GET /apps` — latest release summary per app
 - `GET /apps/<name>/status` — latest app release metadata
 - `GET /apps/<name>/history` — app release history
-- `POST /apps/<name>/rollback` with `{"release_id":"..."}` — re-apply a stored app release snapshot
+- `POST /apps/<name>/rollback` with optional `{"release_id":"...","print":true|false}` — re-apply or print a stored app release snapshot
 - `POST /apps/<app>/workers/<name>/run` — run a worker from the current app release
 - `POST /apps/<app>/training/<name>/start|stop|pause|resume|scale` — manage training jobs for the current app release
 - `GET /apps/<app>/training/<name>/status|logs` — inspect training jobs for the current app release
 
-The app status surfaces (`GET /apps`, `GET /apps/<name>/status`, `yoq apps`, and `yoq status --app`) also report live training runtime counts for the app: active, paused, and failed jobs.
+The app status surfaces (`GET /apps`, `GET /apps/<name>/status`, `yoq apps`, and `yoq status --app`) also report live training runtime counts for the app: active, paused, and failed jobs. Their JSON output now includes nested `current_release`, `previous_successful_release`, `workloads`, and `training_runtime` sections while keeping the older top-level fields for compatibility.
 For `GET /apps/<app>/training/<name>/logs`, the control plane now proxies the request to the hosting agent for the selected rank. If that agent is unreachable or does not expose the log endpoint, the route returns an explicit hosting-agent error.
 
 ### rolling upgrades