# Quickstart: Action Surface Contract v1.1

## Goal

Validate that the action-surface contract now governs behavior, not just declaration presence: every enrolled reference surface declares an explicit constitution-aligned `surfaceType`, the primary validator discovers the enrolled system-panel list pages, clickable-row and explicit-inspect rules are enforced, and representative `More` menus keep helpers first, workflow actions next, and destructive actions last.

## Prerequisites

1. Start Sail.
2. Ensure the database and factories are available for the current test suite.
3. Keep the current baseline exemptions intact for deferred choosers, dashboards, widgets, onboarding flows, and non-enrolled system pages.
4. Ensure representative tenant-plane and system-plane test helpers continue to work:
   - tenant helper for standard resources and monitoring pages
   - platform helper for system-panel pages

## Implementation Validation Order

### 1. Run low-level validator coverage

```bash
vendor/bin/sail artisan test --compact tests/Feature/Guards/ActionSurfaceValidatorTest.php
```

Expected outcome:
- Missing `surfaceType` fails.
- Invalid `surfaceType` and inspect-affordance combinations fail with actionable messages.
- `PrimaryLinkColumn` requires an explicit reason when used.

### 2. Run representative rendered action-surface guards

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

Expected outcome:
- Clickable-row references still render `recordUrl()` and do not expose redundant lone `View` actions.
- Explicit-inspect history and queue references preserve context and do not regress to row click.
- Reporting and evidence registers remain scan-first clickable-row registries rather than being misclassified as audit surfaces.
- System-panel reference pages are discovered by the primary validator without stale baseline exemptions.
- Representative `More` menus keep helpers first, workflow actions next, destructive actions last, and do not render empty placeholder groups.

### 3. Run RBAC-aware tenant reference coverage

```bash
vendor/bin/sail artisan test --compact tests/Feature/Rbac/TenantActionSurfaceConsistencyTest.php
```

Expected outcome:
- Tenant resource row-click and overflow behavior remains aligned with disabled-vs-forbidden capability semantics.
- Existing `More`-menu placement still cooperates with RBAC visibility rules.

### 4. Format touched implementation files

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

Expected outcome:
- Touched PHP files follow the repo’s Pint rules.

## Manual Smoke Check

1. Open `/admin/operations` and confirm the list still opens records through row click without a redundant row-level `View` action.
2. Open `/admin/audit-log` and confirm inspection stays explicit and context-preserving rather than row-click navigation.
3. Open `/admin/finding-exceptions/queue` and confirm inspection remains explicit while decision actions stay tied to the selected record context.
4. Open `/system/ops/runs` and `/system/directory/tenants` as a platform user and confirm those pages still behave as read-only registries while now also belonging to the main validator discovery pass.
5. Confirm deferred surfaces such as chooser pages, dashboards, widgets, and runbooks remain out of scope.

## Non-Goals For This Slice

- No new database migration or persisted artifact.
- No new asset or `filament:assets` deployment change.
- No new policy or capability family.
- No new public HTTP API; the contract artifact is internal planning documentation only.