# Quickstart — External Support Desk / PSA Handoff

## Prereqs

- Docker is running.
- Laravel Sail dependencies are installed.
- The support-request foundation from Spec 246 is already present in the workspace.
- One application-configured external support desk target is available through `apps/platform/config/support_desk.php`, or a fake target is available for implementation tests.

## Run locally after implementation

- Start containers:
  - `export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail up -d`
- Run targeted unit proof:
  - `export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Unit/Support/SupportRequests/ExternalSupportDeskHandoffServiceTest.php tests/Unit/Support/SupportRequests/SupportRequestLatestHandoffSummaryTest.php`
- Run targeted feature proof:
  - `export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/SupportRequests/TenantSupportRequestExternalHandoffTest.php tests/Feature/SupportRequests/OperationRunSupportRequestExternalHandoffTest.php tests/Feature/SupportRequests/SupportRequestExternalHandoffAuthorizationTest.php tests/Feature/SupportRequests/SupportRequestExternalHandoffAuditTest.php`
- Format after implementation:
  - `export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent`

## Manual smoke after implementation

1. Sign in to `/admin` as a workspace member with tenant entitlement and `support_requests.create` capability.
2. Open one tenant at `/admin/t/{tenant}` and trigger `Request support`.
3. Verify the action shows the existing context summary plus the new handoff mode controls. If no external target is configured in `config/support_desk.php`, verify the action clearly stays in `internal_only` mode.
4. Submit the tenant-context flow with `create_external_ticket` and verify the success notification includes the internal support reference plus the created external ticket reference.
5. Reopen the tenant-context action and verify the latest-handoff summary names the same internal support reference and external ticket reference.
6. Submit the tenant-context flow with `link_existing_ticket` and verify the stored summary shows the linked external reference without issuing a create call.
7. Force the external create path to fail, including the five-second timeout path, and verify the action returns explicit partial-success or warning feedback, the internal support request still exists, and the latest-handoff summary shows the persisted failure summary.
8. Open one canonical run detail page at `/admin/operations/{run}` for a run that resolves to the same entitled tenant scope and repeat create, link, and failure checks there.
9. Verify a non-member or non-entitled actor receives `404`, while an in-scope member without `support_requests.create` sees the action disabled and receives `403` on execution.
10. Verify no new support-request resource, support queue, global-search result, or `OperationRun` side effect appears in this slice.

## Notes

- Filament v5 remains on Livewire v4.0+ in this repo; the feature stays inside native Filament page actions.
- No provider registration change is part of this slice; Laravel 12 panel providers remain registered in `bootstrap/providers.php`.
- No globally searchable resource is added, so there is no new global-search contract to satisfy.
- No destructive action is introduced, so `->requiresConfirmation()` is not newly involved here.
- No asset strategy changes are required. The general deploy step `cd apps/platform && php artisan filament:assets` remains unchanged.

## Implementation Close-Out Expectations

- The targeted unit and feature commands above pass.
- Manual smoke proves create, link, and explicit failure handling from both existing support-aware surfaces.
- Audit review shows `support_request.created`, `support_request.external_ticket_created`, `support_request.external_ticket_linked`, and `support_request.external_handoff_failed` events with the expected bounded metadata.
- Internal-only support-request submission still works when the external target is unavailable or intentionally bypassed.
- No new support product surface appears beyond the two existing actions.