# Quickstart: Deferred Operator Surfaces Retrofit

## Goal

Retrofit the tenant-detail and onboarding embedded operation surfaces so they present one clear primary action per state, keep scope truthful before navigation, and leave existing `OperationRun` routes, authorization, and lifecycle behavior unchanged.

## Prerequisites

1. Start the local stack:

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

2. Work on branch `172-deferred-operator-surfaces-retrofit`.

## Implementation Steps

1. Align the tenant-detail embedded surfaces first:
   - `app/Filament/Resources/TenantResource/Pages/ViewTenant.php`
   - `app/Filament/Widgets/Tenant/RecentOperationsSummary.php`
   - `resources/views/filament/widgets/tenant/recent-operations-summary.blade.php`
   - `app/Filament/Widgets/Tenant/TenantVerificationReport.php`
   - `resources/views/filament/widgets/tenant/tenant-verification-report.blade.php`
   - `app/Support/OperationRunLinks.php` only if a secondary collection affordance needs clearer admin-scope copy
2. Make the CTA hierarchy explicit on tenant detail:
   - recent-operations summary keeps row-level inspect links primary and any collection link secondary
   - verification widget uses `Start verification` only when no run exists and relies on the existing tenant-detail header action for reruns once a run exists
3. Align the onboarding verification surfaces without changing workflow semantics:
   - `app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php`
   - `resources/views/filament/forms/components/managed-tenant-onboarding-verification-report.blade.php`
   - `resources/views/filament/modals/onboarding-verification-technical-details.blade.php`
   - keep the wizard's existing next-step controls (`Start verification`, `Refresh`) authoritative
   - keep current-run inspect links singular and keep previous-run/monitoring links diagnostics-secondary only
4. Narrow the governance story instead of creating a new framework:
   - update `app/Support/Ui/ActionSurface/ActionSurfaceExemptions.php` only if the baseline reason needs to become more specific
   - update `tests/Feature/Guards/ActionSurfaceContractTest.php` if the exemption or dedicated-conformance expectation changes
5. Re-run a final pass over the covered views to ensure there is no equal-weight combination of:
   - collection CTA plus row/detail CTA on the same embedded summary
   - `Start verification` plus `Open operation` inside the same tenant-detail widget state
   - `Open operation`, `Open previous operation`, and `Open operation in Monitoring (advanced)` all appearing as peer actions on the onboarding report surface

## Tests To Update

1. Tenant-detail embedded surface coverage:
   - `tests/Feature/Filament/RecentOperationsSummaryWidgetTest.php`
   - `tests/Feature/Filament/TenantVerificationReportWidgetTest.php`
2. Onboarding verification coverage:
   - `tests/Feature/Onboarding/OnboardingVerificationTest.php`
   - `tests/Feature/Onboarding/OnboardingVerificationClustersTest.php`
   - `tests/Feature/Onboarding/OnboardingVerificationV1_5UxTest.php`
3. Governance coverage:
   - `tests/Feature/Guards/ActionSurfaceContractTest.php`

## Focused Verification

Run the narrow regression set first:

```bash
vendor/bin/sail artisan test --compact tests/Feature/Filament/RecentOperationsSummaryWidgetTest.php
vendor/bin/sail artisan test --compact tests/Feature/Filament/TenantVerificationReportWidgetTest.php
vendor/bin/sail artisan test --compact tests/Feature/Onboarding/OnboardingVerificationTest.php
vendor/bin/sail artisan test --compact tests/Feature/Onboarding/OnboardingVerificationClustersTest.php
vendor/bin/sail artisan test --compact tests/Feature/Onboarding/OnboardingVerificationV1_5UxTest.php
vendor/bin/sail artisan test --compact tests/Feature/Guards/ActionSurfaceContractTest.php
```

If the implementation touches shared operation-link wording or helper text used outside the immediate surfaces, run the smallest additional focused tests that render those helpers.

## Formatting

After code changes, run:

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

## Manual Review Checklist

1. The tenant-detail recent-operations summary does not present a header-level collection link with the same visual weight as row-level inspect links.
2. The tenant verification widget shows `Start verification` only when no current run exists and otherwise shows one primary inspect link for the current run.
3. The onboarding flow keeps one workflow-next-step control per state and does not present current-run, previous-run, and advanced-monitoring links as peer primary actions.
4. Any remaining broader-scope operations collection link makes that broader admin scope explicit through context or nearby copy.
5. Any remaining advanced monitoring/admin link is visibly secondary and only appears when the operator can access that destination.
6. No route, capability, persistence artifact, provider registration, or `OperationRun` lifecycle behavior changed.