# Quickstart: Provider Identity & Target Scope Neutrality

## Goal

Implement the shared provider connection target-scope contract so generic provider surfaces stop treating Microsoft identity as the default meaning of a connection.

## Implementation Sequence

1. Add the small shared target-scope descriptor and summary helper layer.
2. Refactor shared provider connection and identity-resolution outputs so neutral target-scope truth is available without Microsoft-shaped default labels.
3. Update provider connection list, detail, create, and edit surfaces to use neutral target-scope language by default.
4. Update the onboarding provider setup step and shared audit and validation wording to reuse the same neutral contract.
5. Add focused guardrails that block Microsoft-specific default labels, filters, required fields, validation messages, helper copy, and audit prose from reappearing on shared provider connection surfaces.

## Suggested Code Areas

```text
apps/platform/app/Filament/Resources/ProviderConnectionResource.php
apps/platform/app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php
apps/platform/app/Services/Providers/
apps/platform/app/Support/Providers/TargetScope/
apps/platform/tests/Feature/Audit/
apps/platform/tests/Feature/Filament/
apps/platform/tests/Feature/ProviderConnections/
apps/platform/tests/Feature/Guards/
apps/platform/tests/Unit/Providers/
```

## Verification Commands

Run the narrowest shared-contract proof first:

```bash
export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Unit/Providers/ProviderConnectionTargetScopeDescriptorTest.php tests/Unit/Providers/ProviderIdentityResolutionNeutralityTest.php tests/Unit/Providers/ProviderConnectionBadgeMappingTest.php tests/Unit/Badges/ProviderConnectionBadgesTest.php
```

Then run the shared-surface and onboarding proof:

```bash
export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/ProviderConnections/ProviderConnectionNeutralitySpec238Test.php tests/Feature/ProviderConnections/ProviderConnectionViewsDbOnlyRenderingSpec081Test.php tests/Feature/Filament/ProviderConnectionsUiEnforcementTest.php tests/Feature/ManagedTenantOnboardingWizardTest.php
```

Then run the audit and guardrail proof:

```bash
export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Audit/ProviderConnectionIdentityAuditTest.php tests/Feature/Guards/ProviderConnectionNeutralityGuardTest.php
```

If PHP files changed, finish with formatting:

```bash
export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent
```

## Review Focus

- Confirm shared provider connection forms, tables, and infolists no longer use `Entra tenant ID` as the default shared label or required field.
- Confirm the shared target-scope descriptor remains understandable without provider-specific vocabulary.
- Confirm unsupported provider or target-scope combinations and missing-context paths fail explicitly instead of inheriting Microsoft defaults.
- Confirm Microsoft tenant, directory, and consent details remain available only as contextual provider-owned metadata.
- Confirm unchanged `404` versus `403` behavior and confirmation-gated sensitive actions are preserved on the touched shared surfaces.
- Confirm onboarding uses the same target-scope meaning as the provider connection resource.
- Confirm audit and validation wording follow the same provider and target-scope vocabulary.
- Confirm no broader credential-model, second-provider, or marketplace scope slipped into the slice.

## Guardrail Close-Out

- Validation to complete before final handoff:
  - `export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Unit/Providers/ProviderConnectionTargetScopeDescriptorTest.php tests/Unit/Providers/ProviderIdentityResolutionNeutralityTest.php tests/Unit/Providers/ProviderConnectionBadgeMappingTest.php tests/Unit/Badges/ProviderConnectionBadgesTest.php tests/Feature/ProviderConnections/ProviderConnectionNeutralitySpec238Test.php tests/Feature/ProviderConnections/ProviderConnectionViewsDbOnlyRenderingSpec081Test.php tests/Feature/Filament/ProviderConnectionsUiEnforcementTest.php tests/Feature/ManagedTenantOnboardingWizardTest.php tests/Feature/Audit/ProviderConnectionIdentityAuditTest.php tests/Feature/Guards/ProviderConnectionNeutralityGuardTest.php`
  - `export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent`
- Guardrails checked:
  - No new provider runtime or provider marketplace abstraction.
  - No new persistence or schema rewrite.
  - No Microsoft-specific default labels, filters, required fields, validation messages, helper copy, or audit prose on shared provider connection surfaces.
  - Unchanged `404` versus `403` behavior and confirmation-gated sensitive actions remain intact on the touched shared surfaces.
  - Microsoft contextual identity remains available where current-release workflows genuinely need it.
- Implemented close-out:
  - Shared provider connection surfaces now use `Target scope` vocabulary by default.
  - Provider-owned Microsoft details are carried in `provider_identity_context` and diagnostic labels such as `Microsoft tenant ID`.
  - Create, update, verification, health-check, and onboarding audit metadata carries `target_scope` plus provider context instead of promoting a raw Microsoft tenant field as shared truth.
  - Existing Filament table contracts for provider connections were updated to reflect provider and target scope as default-visible summary columns.
- Close-out decision: `document-in-feature`. The shared provider connection target-scope hotspot is closed here; broader cross-domain provider-boundary work remains separately tracked.