TenantAtlas/specs/139-verify-access-permissions-assist/research.md

# Research — Spec 139 (Verify Access Required Permissions Assist)

## Decisions

### 1) Use a page action slideover on the existing onboarding wizard
- Decision: Implement the contextual assist as a Filament action on `ManagedTenantOnboardingWizard` that opens a slideover from the existing Verify Access step.
- Rationale:
  - The page already uses Filament v5 `Action::make(...)->slideOver()` successfully for other in-place workflows.
  - This preserves wizard continuity, satisfies the no-new-route requirement, and keeps the assist visually subordinate to the main step progression.
- Alternatives considered:
  - Full-page navigation only: rejected because it breaks onboarding continuity and duplicates the exact problem this spec is meant to solve.
  - A separate onboarding-only page or route: rejected because the spec explicitly forbids new routes and parallel surfaces.

### 2) Reuse the existing Required Permissions builder as the source of compact diagnostics
- Decision: Reuse `TenantRequiredPermissionsViewModelBuilder` as the canonical source for summary counts, overall status, freshness, missing application permissions, missing delegated permissions, and copy payloads.
- Rationale:
  - The builder already provides DB-only permission diagnostics and copy payload semantics.
  - Reusing it avoids forking permission summary logic and keeps the onboarding assist consistent with the full-page deep dive.
- Alternatives considered:
  - Recomputing a second onboarding-specific summary from verification-report evidence alone: rejected because it would drift from the Required Permissions page and violate the additive-only intent.

### 3) Classify deep-dive links by behavior, not only by absolute URL scheme
- Decision: Harden Verify Access next-step link rendering with a shared internal-vs-deep-dive classification rule so relevant internal diagnostic links also open in a new tab.
- Rationale:
  - The current Blade template opens only absolute external URLs in a new tab.
  - Spec 139 requires internal diagnostic links from the verification report to stop replacing the onboarding tab, including pages other than Required Permissions.
- Alternatives considered:
  - Hardcoding `Open required permissions` as the only new-tab internal link: rejected because the spec explicitly calls out other internal diagnostic links.
  - Opening every internal `/admin/*` link in a new tab: rejected because not every internal link is a deep-dive escape hatch, and broad behavior changes would be too risky.

### 4) Keep the full-page Required Permissions page as the only deep-dive surface
- Decision: The assist will expose `Open full page` as a clearly secondary action that points to the existing `TenantRequiredPermissions` page via `RequiredPermissionsLinks::requiredPermissions()`.
- Rationale:
  - This preserves the current product role of the page and avoids route sprawl.
  - The deep dive remains available for advanced investigation while the onboarding tab stays on task.
- Alternatives considered:
  - Replacing the full page with the slideover: rejected because the spec accepts that some advanced investigation still belongs on the full page.

### 5) Copy feedback should follow an explicit visible confirmation pattern
- Decision: Copy actions will only render when the relevant copy payload exists, and each copy action will provide explicit confirmation through a visible copied state, toast, or equivalent inline acknowledgement.
- Rationale:
  - The spec requires clear feedback and safe handling when no copyable data exists.
  - Reusing an existing clipboard feedback pattern is lower risk than inventing a new one.
- Alternatives considered:
  - Silent clipboard copy: rejected because it gives poor operator feedback.
  - Always-rendered disabled copy buttons for empty payloads: rejected because omitted or replaced actions are clearer in degraded states.

### 6) Extend existing onboarding verification tests instead of creating a separate test pyramid
- Decision: Add focused coverage in the existing onboarding verification feature, Livewire, and browser test areas.
- Rationale:
  - The current repository already has strong seams around verification report rendering, slideover actions, stale verification continuity, and clustered checks.
  - Extending those tests gives the best regression value with minimal new scaffolding.
- Alternatives considered:
  - Creating a new isolated end-to-end-only suite for the assist: rejected because visibility rules and degraded-state rendering are faster and more deterministically covered in feature/Livewire tests.

## Resolved Clarifications

### How should the assist determine whether it is relevant?
- Decision: Relevance is driven by the stored verification report plus the existing permission diagnostics summary for the selected tenant.
- Rationale:
  - The verification report already communicates permission-related blockers and next steps.
  - The Required Permissions builder already exposes the underlying permission state needed for compact rendering.

### What should happen when permission detail is incomplete or stale?
- Decision: The assist still renders but degrades to safe fallback messaging, surfaces freshness/needs-attention context when available, and preserves rerun/deep-dive options instead of showing broken controls.
- Rationale:
  - This matches the spec’s degraded-state requirements and keeps the recovery surface trustworthy.

### Does this feature need new backend persistence?
- Decision: No. The feature is computed entirely from existing onboarding draft state, the stored verification report, and existing permission diagnostics services.
- Rationale:
  - This keeps the implementation additive and low risk.