# Quickstart: System Operations Surface Alignment

## Goal

Bring the system-panel Operations surfaces into conformance with the declared read-only registry contract by removing inline triage from the list rows, standardizing visible naming to `Operations` / `Operation`, adding explicit list CTAs, and keeping triage on the canonical operation detail page.

## Prerequisites

1. Start the local stack:

```bash
vendor/bin/sail up -d
```

2. Work on branch `170-system-operations-surface-alignment`.

## Implementation Steps

1. Update the three list pages:
   - `app/Filament/System/Pages/Ops/Runs.php`
   - `app/Filament/System/Pages/Ops/Failures.php`
   - `app/Filament/System/Pages/Ops/Stuck.php`
2. Remove the `retry`, `cancel`, and `mark_investigated` table actions from each list page.
3. Keep `recordUrl()` row-click navigation intact for each list page.
4. Update visible navigation labels, headings, empty-state copy, and page CTA behavior so the changed surfaces use `Operations` / `Operation` vocabulary.
5. Update each list page's `actionSurfaceDeclaration()` explanation text so it reflects detail-owned triage rather than row-level triage.
6. Update `app/Filament/System/Pages/Ops/ViewRun.php` and `resources/views/filament/system/pages/ops/view-run.blade.php` so the detail page keeps triage ownership, uses `Operation #...` copy, and exposes `Show all operations`.
7. Leave `app/Services/SystemConsole/OperationRunTriageService.php` unchanged unless a small refactor is needed to support the page move without changing behavior.

## Tests To Update

1. `tests/Feature/System/Spec114/OpsTriageActionsTest.php`
   - Replace row-action execution assertions on `Runs` with detail-page action visibility/execution assertions on `ViewRun`.
   - Keep view-only versus manage-capable separation explicit.
   - Add assertions for visible `Operations` / `Operation` copy and the `Show all operations` return path.
2. `tests/Feature/Guards/ActionSurfaceContractTest.php`
   - Replace the three expectations for direct row triage with expectations that the row action set is empty while `recordUrl()` still points to `SystemOperationRunLinks::view($run)`.
   - Assert the list CTA behavior and canonical Operations naming on the changed surfaces.
3. Keep the existing page-access tests for failures/stuck passing.

## Focused Verification

Run the smallest relevant test set first:

```bash
vendor/bin/sail artisan test --compact tests/Feature/System/Spec114/OpsTriageActionsTest.php
vendor/bin/sail artisan test --compact tests/Feature/Guards/ActionSurfaceContractTest.php
```

If implementation touches other platform-ops behavior, add the page access tests:

```bash
vendor/bin/sail artisan test --compact tests/Feature/System/Spec114/OpsFailuresViewTest.php
vendor/bin/sail artisan test --compact tests/Feature/System/Spec114/OpsStuckViewTest.php
```

## Formatting

After code changes, run:

```bash
vendor/bin/sail bin pint --dirty --format agent
```

## Manual Review Checklist

1. The `Runs`, `Failures`, and `Stuck` tables still navigate by row click.
2. None of the three lists exposes inline triage actions.
3. The changed system surfaces use `Operations` / `Operation` as the visible noun.
4. The Operations list exposes `Go to runbooks`, while Failed operations and Stuck operations expose `Show all operations` as the single header and empty-state CTA.
5. The system operation detail page still shows `Retry`, `Cancel`, and `Mark investigated` only for manage-capable operators and exposes `Show all operations` as the return path.
6. `Cancel` still requires confirmation.
7. Retry still produces the existing queued toast with a `View run` link.