# Quickstart: Provider Capability Registry

## Purpose

Use this guide to review or later implement Spec `283` as one bounded provider-capability slice.

## Preconditions

1. Spec `281` provider-boundary groundwork is already present on the implementation branch.
2. Work stays inside `apps/platform` and this spec package.
3. No application implementation from adjacent Specs `284` through `287` is pulled in.

## Reviewer flow

1. Read [spec.md](./spec.md), [plan.md](./plan.md), [research.md](./research.md), and [data-model.md](./data-model.md) together.
2. Confirm the package introduces one derived capability registry and no new persistence.
3. Confirm the initial capability-key set stays bounded to current repo workflows only.
4. Confirm provider-owned evidence such as raw Graph permission names remains nested, not primary operator vocabulary.
5. Confirm provider-connections, onboarding, required-permissions diagnostics, blocked-operation messaging, and support guidance all point at the same capability contract.

## Suggested implementation order

1. Add the small provider capability registry, status enum, and evaluator.
2. Map current provider-backed operations to capability keys in the shared provider operation registry.
3. Update the shared provider-operation start gate and blocked-result context.
4. Update provider-connections summaries and onboarding capability assist.
5. Update required-permissions grouping and shared provider reason translation.
6. Run the exact bounded proof commands below.

## Narrow proof commands

```bash
export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && REPO_ROOT="$(git rev-parse --show-toplevel)" && \
  (cd "$REPO_ROOT/apps/platform" && ./vendor/bin/sail artisan test --compact \
    tests/Unit/Providers/ProviderCapabilityRegistryTest.php \
    tests/Unit/Verification/TenantPermissionCapabilityMappingTest.php)
```

```bash
export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && REPO_ROOT="$(git rev-parse --show-toplevel)" && \
  (cd "$REPO_ROOT/apps/platform" && ./vendor/bin/sail artisan test --compact \
    tests/Feature/Providers/ProviderCapabilityEvaluationTest.php \
    tests/Feature/Providers/ProviderOperationCapabilityGateTest.php \
    tests/Feature/Filament/ProviderConnectionCapabilitySummaryTest.php \
    tests/Feature/Onboarding/ManagedTenantOnboardingCapabilityAssistTest.php \
    tests/Feature/RequiredPermissions/RequiredPermissionsCapabilityGroupingTest.php \
    tests/Feature/SupportDiagnostics/ProviderCapabilityReasonTranslationTest.php)
```

```bash
export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && REPO_ROOT="$(git rev-parse --show-toplevel)" && \
  (cd "$REPO_ROOT/apps/platform" && ./vendor/bin/sail artisan test --compact \
    tests/Browser/Spec283ProviderCapabilityRegistrySmokeTest.php)
```

```bash
export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && REPO_ROOT="$(git rev-parse --show-toplevel)" && \
  (cd "$REPO_ROOT/apps/platform" && ./vendor/bin/sail bin pint --dirty --format agent)
```

## Expected smoke path

1. Open one provider connection.
2. Verify the page shows a capability-first summary for at least one workflow.
3. Use the required-permissions or onboarding assist entry point.
4. Confirm the diagnostic page shows the same capability label and supporting permission evidence.
5. Trigger one blocked or allowed provider-backed workflow and confirm the shared start outcome uses the same capability language.

## Stop conditions

- Stop if implementation tries to add a provider-capability table or provider ledger.
- Stop if new capability keys describe workflows that do not yet exist in repo truth.
- Stop if raw Graph permission names return as the primary operator-facing summary on the touched surfaces.
- Stop if the slice widens into routing, RBAC, taxonomy, copy, or quality-gate work reserved for later specs.