TenantAtlas/specs/283-provider-capability-registry/quickstart.md

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, plan.md, research.md, and 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

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)

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)

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)

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.