TenantAtlas/specs/240-tenant-onboarding-readiness/spec.md

Feature Specification: Self-Service Tenant Onboarding & Connection Readiness

Feature Branch: [240-tenant-onboarding-readiness]
Created: 2026-04-25
Status: Draft
Input: User description: "Promote the roadmap-fit candidate 'Self-Service Tenant Onboarding & Connection Readiness' as a narrow, implementation-ready slice that turns the existing managed-tenant onboarding flow into an operator-facing readiness workflow. The slice should reuse existing onboarding session, provider connection, verification, and checkpoint foundations to show guided setup progress, provider connection health, permission and consent diagnostics, freshness, and concrete next actions before deeper governance workflows begin. It should explicitly reduce founder-led manual onboarding and make the current onboarding state understandable without raw run inspection. Out of scope: CRM/trial pipeline, billing, marketplace/provider expansion, autonomous remediation, or broad new onboarding persistence if existing onboarding/session/provider models are sufficient."

Spec Candidate Check (mandatory — SPEC-GATE-001)

• Problem: Managed-tenant onboarding truth is fragmented across onboarding drafts, provider connection status, verification runs, permission posture, and checkpoint progression, so an operator cannot quickly tell whether a tenant is genuinely ready without founder guidance or raw run inspection.
• Today's failure: Onboarding stalls behind generic failure or incomplete-state messaging, operators cannot reliably distinguish missing consent from missing permissions or stale verification, and founder-led walkthroughs fill the product gap.
• User-visible improvement: The existing onboarding workflow becomes a guided readiness view that shows setup progress, connection health, permission and consent blockers, freshness, and one concrete next action in the same place the operator resumes onboarding.
• Smallest enterprise-capable version: Reuse the current onboarding session, provider connection, verification, permission diagnostics, and checkpoint foundations to add one derived readiness summary inside the existing managed-tenant onboarding workflow, with canonical links to existing evidence and actions.
• Explicit non-goals: CRM or trial pipeline work, billing or entitlement changes, provider marketplace expansion, autonomous remediation, a second onboarding persistence model, a generalized multi-provider onboarding framework, or a numeric onboarding completion score for this slice.
• Permanent complexity imported: A bounded derived readiness composition for the existing onboarding surface, readiness-specific copy/state mapping on the current wizard, and focused feature tests for readiness, freshness, and authorization; no new persisted entity, capability family, or cross-domain framework.
• Why now: This is the first roadmap item in the self-service foundation cluster and directly removes founder-led onboarding work while making later support diagnostic and trial flows smaller and safer.
• Why not local: The pain spans onboarding checkpoint state, provider connection status, permission posture, verification freshness, and supporting evidence links; isolated copy changes in one step would preserve drift and false-green risk.
• Approval class: Core Enterprise
• Red flags triggered: 4 foundation-sounding theme. Defense: this slice is explicitly constrained to current onboarding routes and existing truth, with no new persistence or platform framework.
• Score: Nutzen: 2 | Dringlichkeit: 2 | Scope: 2 | Komplexität: 1 | Produktnähe: 2 | Wiederverwendung: 2 | Gesamt: 11/12
• Decision: approve

Spec Scope Fields (mandatory)

• Scope: workspace
• Primary Routes: /admin/onboarding, /admin/onboarding/{onboardingDraft}, linked /admin/consent/start and /admin/consent/callback flows, and canonical /admin/operations/{run} deep links for supporting evidence
• Data Ownership: TenantOnboardingSession remains the workspace-owned workflow record; linked ProviderConnection, permission/verification truth, and OperationRun evidence remain existing tenant-owned or run-owned records; readiness stays derived and non-persistent
• RBAC: Workspace membership is mandatory. Capabilities::WORKSPACE_MANAGED_TENANT_ONBOARD gates view/update of the readiness workflow, Capabilities::WORKSPACE_MANAGED_TENANT_ONBOARD_CANCEL gates destructive cancellation, linked-tenant visibility still passes tenant-bound administrative viewability checks, non-members or wrong workspace/tenant scope return 404, and members lacking capability return 403.

For canonical-view specs, the spec MUST define:

• Default filter behavior when tenant-context is active: N/A - this slice stays in the workspace onboarding workflow, not a canonical cross-tenant register
• Explicit entitlement checks preventing cross-tenant leakage: Existing workspace membership plus linked-tenant viewability checks continue to deny as not found before any readiness data or supporting operation detail is revealed

Cross-Cutting / Shared Pattern Reuse (mandatory when the feature touches notifications, status messaging, action links, header actions, dashboard signals/cards, alerts, navigation entry points, evidence/report viewers, or any other existing shared operator interaction family; otherwise write N/A - no shared interaction family touched)

• Cross-cutting feature?: yes
• Interaction class(es): status messaging, action links, embedded diagnostics, navigation
• Systems touched: managed-tenant onboarding workflow, onboarding lifecycle snapshot/stage resolution, provider connection summary rendering, permission diagnostics, canonical operation links
• Existing pattern(s) to extend: onboarding lifecycle snapshot, embedded verification-report and provider-connection summary patterns, canonical operation link helper
• Shared contract / presenter / builder / renderer to reuse: App\Services\Onboarding\OnboardingLifecycleService, App\Services\Onboarding\OnboardingDraftStageResolver, App\Support\Providers\TargetScope\ProviderConnectionSurfaceSummary, and App\Support\OperationRunLinks
• Why the existing shared path is sufficient or insufficient: These paths already compute checkpoint progression, verification state, bootstrap summaries, provider connection readiness wording, and canonical operation navigation. The slice only needs to compose them into one operator-facing readiness view.
• Allowed deviation and why: Provider-specific Microsoft permission names and consent details may remain inside provider-owned diagnostic detail because exact remediation still depends on the current provider.
• Consistency impact: Readiness labels, freshness cues, next-action verbs, and Open operation/consent link semantics must stay aligned across onboarding checkpoints and linked diagnostics.
• Review focus: Verify that no second readiness taxonomy, local status palette, or page-specific operation-link language appears outside the shared paths above, and that any shared builder change stays additive and behavior-preserving for non-onboarding consumers while onboarding-specific action prioritization remains page-local.

OperationRun UX Impact (mandatory when the feature creates, queues, deduplicates, resumes, blocks, completes, or deep-links to an OperationRun; otherwise write N/A - no OperationRun start or link semantics touched)

• Touches OperationRun start/completion/link UX?: yes
• Shared OperationRun UX contract/layer reused: App\Support\OperationRunLinks for canonical tenantless Open operation links, the existing onboarding tenantlessOperationRunUrl(...) helper, and App\Services\OperationRunService as the only owner of run status/outcome transitions for any reused verification/bootstrap actions
• Delegated start/completion UX behaviors: canonical Open operation link resolution, tenant/workspace-safe operation URL resolution, existing queued-intent behavior for reused verification starts, dedupe-or-blocked messaging for existing verification actions, and terminal lifecycle notifications through the current shared run UX path
• Local surface-owned behavior that remains: readiness explanation, freshness wording, and prioritization of the one next action inside the onboarding workflow
• Queued DB-notification policy: no new queued or running DB notification is introduced in this slice; any terminal notification remains explicit and central
• Terminal notification path: central lifecycle mechanism already used by the underlying run flow
• Exception required?: none

Provider Boundary / Platform Core Check (mandatory when the feature changes shared provider/platform seams, identity scope, governed-subject taxonomy, compare strategy selection, provider connection descriptors, or operator vocabulary that may leak provider-specific semantics into platform-core truth; otherwise write N/A - no shared provider/platform boundary touched)

• Shared provider/platform boundary touched?: yes
• Boundary classification: mixed
• Seams affected: provider connection descriptors, consent and permission diagnostics, readiness copy, next-action labels, freshness messaging
• Neutral platform terms preserved or introduced: provider connection, readiness, diagnostics, next action, freshness, onboarding step
• Provider-specific semantics retained and why: Microsoft consent and permission names remain inside contextual diagnostic detail because the operator needs exact remediation instructions for the only supported provider.
• Why this does not deepen provider coupling accidentally: No new platform-core enum, persisted state, or canonical taxonomy becomes Microsoft-shaped. Top-level readiness stays a derived composition of existing onboarding and provider connection truth.
• Follow-up path: none

UI / Surface Guardrail Impact (mandatory when operator-facing surfaces are changed; otherwise write N/A)

Use this section to classify UI and surface risk once. If the feature does not change an operator-facing surface, write N/A - no operator-facing surface change here and do not invent duplicate prose in the downstream surface tables.

Surface / Change	Operator-facing surface change?	Native vs Custom	Shared-Family Relevance	State Layers Touched	Exception Needed?	Low-Impact / N/A Note
Managed tenant onboarding workflow	yes	Native Filament + shared primitives	status messaging, action links, badges, embedded diagnostics	page, workflow step, derived readiness summary	no	Guided-flow surface; no new route family

Decision-First Surface Role (mandatory when operator-facing surfaces are changed)

If this feature adds or materially changes an operator-facing surface, fill out one row per affected surface. This role is orthogonal to the Action Surface Class / Surface Type below. Reuse the exact surface names and classifications from the UI / Surface Guardrail Impact section above.

Surface	Decision Role	Human-in-the-loop Moment	Immediately Visible for First Decision	On-Demand Detail / Evidence	Why This Is Primary or Why Not	Workflow Alignment	Attention-load Reduction
Managed tenant onboarding workflow	Primary Decision Surface	Decide whether onboarding can proceed now or which blocker to resolve first	Current checkpoint, readiness summary, freshness, linked tenant/provider scope, and one primary next action	Full permission diff, provider-specific diagnostic detail, canonical operation detail	Primary because this is the place where the operator resumes or completes onboarding work, not a secondary diagnostic register	Follows identify → connect provider → verify access → bootstrap → activate progression inside one workflow context	Removes the need to open raw operation detail or separate provider screens just to understand what to do next

UI/UX Surface Classification (mandatory when operator-facing surfaces are changed)

If this feature adds or materially changes an operator-facing list, detail, queue, audit, config, or report surface, fill out one row per affected surface. Declare the broad Action Surface Class first, then the detailed Surface Type. Keep this table in sync with the Decision-First Surface Role section above and avoid renaming the same surface a second time.

Surface	Action Surface Class	Surface Type	Likely Next Operator Action	Primary Inspect/Open Model	Row Click	Secondary Actions Placement	Destructive Actions Placement	Canonical Collection Route	Canonical Detail Route	Scope Signals	Canonical Noun	Critical Truth Visible by Default	Exception Type / Justification
Managed tenant onboarding workflow	Workflow / Guided action entry	Guided onboarding / readiness workflow	Resolve the current blocker or continue to the next checkpoint	In-page readiness section on the current draft route	forbidden	Supporting diagnostics and collection navigation stay secondary within section reveals or footer links	Header-only destructive actions, confirmation-protected	/admin/onboarding	/admin/onboarding/{onboardingDraft}	Workspace context, linked tenant identity, provider connection summary	Onboarding / Onboarding readiness	Current checkpoint, connection health, permission/consent blocker, freshness, and next action	Guided-workflow exception; this is a wizard surface, not a CRUD resource, but it still keeps one primary decision context

Operator Surface Contract (mandatory when operator-facing surfaces are changed)

If this feature adds a new operator-facing page or materially refactors one, fill out one row per affected page/surface. The contract MUST show how one governance case or operator task becomes decidable without unnecessary cross-page reconstruction.

Surface	Primary Persona	Decision / Operator Action Supported	Surface Type	Primary Operator Question	Default-visible Information	Diagnostics-only Information	Status Dimensions Used	Mutation Scope	Primary Actions	Dangerous Actions
Managed tenant onboarding workflow	Workspace operator managing tenant setup	Decide whether onboarding can proceed and execute the next readiness action	Guided workflow	What is blocking this tenant from being ready, and what do I do next?	Checkpoint progress, readiness summary, provider connection health, consent/permission status, freshness of latest evidence, and the primary next action	Full permission diff, provider-specific identifiers, raw verification payloads, and canonical operation detail	workflow checkpoint, readiness outcome, freshness, execution outcome	TenantPilot only for draft progression; Microsoft tenant only when operator follows existing consent or verification actions	Continue onboarding, grant or regrant consent when needed, run or rerun verification when needed, open operation	Cancel onboarding, delete draft

Proportionality Review (mandatory when structural complexity is introduced)

Fill this section if the feature introduces any of the following:

• a new source of truth

• a new persisted entity, table, or artifact

• a new abstraction (interface, contract, registry, resolver, strategy, factory, orchestration layer)

• a new enum, status family, reason code family, or lifecycle category

• a new cross-domain UI framework, taxonomy, or classification system

• New source of truth?: no

• New persisted entity/table/artifact?: no

• New abstraction?: no

• New enum/state/reason family?: no

• New cross-domain UI framework/taxonomy?: no

• Current operator problem: Operators cannot trust or explain onboarding readiness from the current workflow without opening raw diagnostics or asking the founder.

• Existing structure is insufficient because: The current truth exists, but it is spread across workflow state, provider connection state, verification evidence, and permission posture with no single operator-facing readiness composition.

• Narrowest correct implementation: Compose existing onboarding lifecycle, provider connection summary, permission diagnostics, and operation evidence inside the current onboarding workflow, with no new persistence or platform-wide framework.

• Ownership cost: A small amount of readiness mapping and focused feature-test coverage must be maintained, but there is no new stored truth, capability family, or cross-domain taxonomy.

• Alternative intentionally rejected: A new onboarding-readiness table/state machine or generic provider-onboarding framework was rejected as overproduction for the current release.

• Release truth: current-release truth

Compatibility posture

This feature assumes a pre-production environment.

Backward compatibility, legacy aliases, migration shims, historical fixtures, and compatibility-specific tests are out of scope unless explicitly required by this spec.

Canonical replacement is preferred over preservation.

Testing / Lane / Runtime Impact (mandatory for runtime behavior changes)

For docs-only or template-only changes, state concise N/A or none. For runtime- or test-affecting work, classification MUST follow the proving purpose of the change rather than the file path or folder name.

• Test purpose / classification: Feature, Unit
• Validation lane(s): fast-feedback
• Why this classification and these lanes are sufficient: Livewire/Filament feature tests prove readiness mapping, next-action guidance, retained action behavior, freshness truth, and deny semantics on the onboarding surface, while targeted unit and policy coverage proves reused permission-freshness and authorization seams without browser automation or heavy-governance breadth.
• New or expanded test families: extend onboarding feature coverage plus targeted unit and policy coverage for onboarding authorization and reused permission-freshness behavior only
• Fixture / helper cost impact: workspace membership, onboarding draft, linked tenant, provider connection, and operation-run states are required; avoid new browser harnesses, new heavy fixtures, or provider mocks beyond the current readiness scenarios
• Heavy-family visibility / justification: none
• Special surface test profile: standard-native-filament
• Standard-native relief or required special coverage: ordinary onboarding feature coverage plus focused policy and freshness regressions only
• Reviewer handoff: Confirm that negative authorization still distinguishes 404 vs 403 correctly, retained start and destructive actions keep their existing guardrails, no browser-only proof was added for a server-driven workflow, and proof commands remain limited to onboarding, onboarding-authorization, and freshness-policy coverage.
• Budget / baseline / trend impact: none expected beyond ordinary feature-local runtime
• Escalation needed: none
• Active feature PR close-out entry: Guardrail
• Planned validation commands: cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/ManagedTenantOnboardingWizardTest.php; cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Onboarding/OnboardingDraftPickerTest.php tests/Feature/Onboarding/OnboardingDraftAuthorizationTest.php; cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Unit/Policies/TenantOnboardingSessionPolicyTest.php tests/Unit/TenantRequiredPermissionsFreshnessTest.php

User Scenarios & Testing (mandatory)

User Story 1 - Resume Onboarding With Trustworthy Readiness (Priority: P1)

An authorized workspace operator opens an onboarding draft and immediately sees the current setup step, whether the tenant is actually ready, what evidence is fresh or stale, and what the next action is without needing to inspect raw operations first.

Why this priority: This is the smallest slice that directly removes founder-led manual walkthroughs and turns the current onboarding state into a self-explanatory workflow.

Independent Test: Seed onboarding drafts in multiple lifecycle states with linked provider connections and verification outcomes, open the onboarding routes, and confirm the workflow shows checkpoint progress, readiness, freshness, and one primary next action.

Acceptance Scenarios:

1. Given an authorized operator opens an existing onboarding draft with a linked provider connection, When the workflow loads, Then it shows the current checkpoint, readiness summary, freshness, and one primary next action without requiring raw run inspection.
2. Given an operator opens the onboarding landing page while resumable drafts already exist, When the landing context renders, Then it shows enough progress and blocker context to choose the correct draft to resume.

---

User Story 2 - Diagnose Consent And Permission Blockers (Priority: P2)

An authorized operator can tell whether onboarding is blocked by missing consent, missing permissions, disabled or unhealthy provider connection state, or an unresolved verification result, and receives explicit guidance for the next corrective action.

Why this priority: Trustworthy blocker classification is the part that prevents false-green readiness and generic error handling from turning into support work.

Independent Test: Seed drafts with missing consent, permission gaps, disabled connections, and blocked verification outcomes, then confirm each scenario shows distinct blocker language and the appropriate next action.

Acceptance Scenarios:

1. Given consent is missing or revoked, When the operator opens the readiness workflow, Then the blocker is labeled explicitly and the primary action points to the consent follow-up flow rather than generic failure copy.
2. Given required permissions are missing or insufficient, When the operator opens the readiness workflow, Then the operator sees explicit permission diagnostics in provider-owned terms and a concrete remediation path.

---

User Story 3 - Trust Freshness And Supporting Evidence (Priority: P3)

An authorized operator can tell whether supporting verification or bootstrap evidence is current enough to trust, and can open the canonical supporting operation when more detail is necessary.

Why this priority: Freshness and evidence linkage prevent the workflow from becoming a false-ready facade while still keeping raw diagnostics secondary.

Independent Test: Seed matching, stale, and mismatched verification runs for the same draft, then confirm the workflow surfaces freshness truth and a single canonical operation link only when evidence exists.

Acceptance Scenarios:

1. Given the latest verification run is stale or tied to a different selected provider connection, When the operator opens the workflow, Then readiness falls back to a non-ready state with explicit freshness or mismatch guidance instead of reporting ready.
2. Given a supporting verification or bootstrap run exists, When the operator wants more detail, Then the workflow offers one canonical Open operation link that respects authorization.

Edge Cases

• An onboarding draft exists before any tenant is linked; the workflow must show identity and connection prerequisites without implying the tenant is ready.
• The latest verification run belongs to a different provider connection than the currently selected one; the workflow must treat it as mismatched evidence and require attention.
• A provider connection was previously healthy but is now disabled or its consent was revoked; the workflow must not keep showing the older ready state.
• Health or verification evidence is older than the accepted freshness window; the workflow must show stale evidence and a rerun or refresh next action.
• An actor still has workspace membership but no longer has linked-tenant entitlement; the workflow must return 404 rather than partial readiness data.

Requirements (mandatory)

Constitution alignment (required): This feature does not introduce a new Microsoft Graph domain, a new tenant-changing workflow, or a new queued-work family. It reuses existing onboarding, consent, verification, and bootstrap actions. Any reused verification or bootstrap action continues to rely on the current contract-registry-backed provider execution, existing safety gates, tenant isolation, OperationRun observability, and onboarding audit events.

Constitution alignment (PROP-001 / ABSTR-001 / PERSIST-001 / STATE-001 / BLOAT-001): The slice is derived-only. It must not add a new persisted readiness model, a new cross-provider onboarding abstraction, or a new canonical readiness state family. Existing onboarding lifecycle, provider consent/verification states, and supporting evidence remain the source of truth.

Constitution alignment (XCUT-001): The slice extends existing onboarding lifecycle composition, provider connection summary rendering, and canonical operation-link paths. No parallel onboarding health language or page-local operation-link system may appear.

Constitution alignment (PROV-001): Top-level readiness language stays platform-neutral, while Microsoft-specific consent and permission details remain contextual and provider-owned. The feature must not turn Microsoft permission or consent semantics into new platform-core truth.

Constitution alignment (TEST-GOV-001): Implementation must stay in fast-feedback feature coverage, keep fixtures opt-in and onboarding-local, and avoid creating a new heavy-governance or browser family for a server-driven readiness workflow.

Constitution alignment (OPS-UX): If the workflow exposes existing verification or bootstrap start actions, those actions must continue to use the existing queued-intent feedback contract, canonical Open operation links, central OperationRunService status ownership, and no new queued or running DB notifications.

Constitution alignment (OPS-UX-START-001): Any OperationRun deep link or reused start action in this workflow must delegate URL resolution and run-link behavior to the shared operation-link path rather than page-local URLs.

Constitution alignment (RBAC-UX): Non-members, wrong-workspace actors, and actors lacking linked-tenant entitlement continue to receive 404. Members missing onboarding capability receive 403 on protected workflow actions. Existing destructive onboarding actions remain confirmation-protected and server-authorized.

Constitution alignment (BADGE-001): Consent and verification badges remain driven by the central badge domains already used by provider connection summaries; no page-local color or label mapping is introduced.

Constitution alignment (UI-FIL-001): The workflow continues to use native Filament sections, cards, badges, and shared primitives. The slice may reorganize emphasis, but it must not replace the workflow with custom fake-native controls.

Constitution alignment (UI-NAMING-001): Primary operator-facing labels remain grounded in onboarding vocabulary such as Continue onboarding, Grant consent, Run verification, Open operation, Cancel onboarding, and Delete draft. Implementation-first language stays in secondary diagnostics only.

Constitution alignment (DECIDE-001): The onboarding workflow remains the one primary decision surface for onboarding readiness. It must present enough truth to decide the next action without forcing cross-page reconstruction from raw operations.

Constitution alignment (UI-CONST-001 / UI-SURF-001 / ACTSURF-001 / UI-HARD-001 / UI-EX-001 / UI-REVIEW-001 / HDR-001): This guided workflow remains a bounded exception to list/detail table rules, but it must still keep one primary next action, preserve header-action discipline, keep destructive actions separated by risk, and avoid mixed catch-all action groups.

Constitution alignment (ACTSURF-001 - action hierarchy): Navigation, mutation, and destructive onboarding actions remain visibly separated. Secondary diagnostics do not compete with the primary next action.

Constitution alignment (OPSURF-001): The default-visible content must stay operator-first, with raw provider detail and full operation diagnostics deliberately secondary. Mutation scope remains explicit when the workflow points to provider actions.

Constitution alignment (UI-SEM-001 / LAYER-001 / TEST-TRUTH-001): Any new readiness wording remains a thin adapter over existing onboarding, provider connection, and verification truth. Tests must prove business consequences such as blocker classification, freshness, and authorization rather than a thin presentation layer alone.

Constitution alignment (Filament Action Surfaces): The managed-tenant onboarding page remains an explicit guided-workflow exception rather than a CRUD resource. Action inventory must still preserve one primary next action, avoid redundant inspect affordances, and keep destructive actions gated and confirmation-protected.

Constitution alignment (UX-001 — Layout & Information Architecture): The onboarding page continues to use native sections and cards, puts default-visible readiness truth ahead of diagnostics, and keeps empty/start states focused on one clear CTA.

Functional Requirements

• FR-001: The system MUST compose onboarding readiness from the existing onboarding session, provider connection state, verification evidence, permission diagnostics, and checkpoint progression instead of introducing a second onboarding-readiness persistence model.
• FR-002: The system MUST show the current checkpoint, completed progress, derived readiness summary, freshness, and one primary next action on the existing onboarding landing surfaces: the route-bound draft at /admin/onboarding/{onboardingDraft}, and the /admin/onboarding landing experience when multiple resumable drafts exist. If /admin/onboarding resolves directly to a single resumable draft, the existing redirect behavior remains in place.
• FR-003: The workflow MUST distinguish operator-visible conditions for not started, in progress, blocked, needs attention, stale evidence, and ready-to-proceed scenarios instead of collapsing them into generic incomplete-state copy.
• FR-004: When a linked provider connection exists, the workflow MUST reuse the existing provider connection summary path to show consent state, verification state, contextual identity details, and readiness wording.
• FR-005: Missing or insufficient permissions MUST produce explicit provider-owned diagnostics and a concrete next action, while top-level readiness vocabulary remains platform-neutral.
• FR-006: The workflow MUST display freshness for the latest verification or health evidence using the existing permission freshness threshold (currently 30 days) plus selected-provider-connection mismatch signals, and MUST mark stale or mismatched evidence as needing attention rather than ready.
• FR-007: Supporting verification or bootstrap evidence MUST deep-link through the canonical tenantless operation route and MUST expose only one primary Open operation affordance per supporting record.
• FR-008: If the workflow exposes existing start or rerun actions for consent, verification, or bootstrap follow-up, those actions MUST preserve existing authorization, audit, dedupe, and shared Ops-UX behavior and MUST NOT create new run-start paths.
• FR-009: Non-members, wrong-workspace actors, and actors without linked-tenant entitlement MUST receive 404 for readiness routes and supporting evidence routes; entitled members lacking the required onboarding capability MUST receive 403 on protected actions.
• FR-010: Existing destructive onboarding actions retained in the workflow, including cancel or delete draft behavior, MUST remain confirmation-protected and capability-gated, and this slice MUST NOT introduce new destructive behavior.
• FR-011: The workflow MUST reuse existing onboarding lifecycle and verification truth and MUST NOT introduce a new persisted readiness enum, new onboarding table, or generalized provider-onboarding framework.
• FR-012: The readiness outcome and next-action summary MUST remain structured as derived onboarding truth so later support diagnostic and trial/demo work can consume the same underlying composition, but cross-surface reuse beyond onboarding is explicitly deferred from this slice and MUST NOT introduce a new shared abstraction or second source of truth now.
• FR-013: Microsoft-specific consent and permission details MUST stay contextual and secondary to the operator-first readiness summary.
• FR-014: When no supporting verification or diagnostic evidence exists yet, the workflow MUST state that the check has not run yet and point to the correct next action rather than exposing empty diagnostics.
• FR-015: The workflow MUST continue to use native Filament sections, cards, and shared badge semantics instead of page-local status cards or custom color logic.

UI Action Matrix (mandatory when Filament is changed)

If this feature adds/modifies any Filament Resource / RelationManager / Page, fill out the matrix below.

For each surface, list the exact action labels, whether they are destructive (confirmation? typed confirmation?), RBAC gating (capability + enforcement helper), whether the mutation writes an audit log, and any exemption or exception used.

Surface	Location	Header Actions	Inspect Affordance (List/Table)	Row Actions (max 2 visible)	Bulk Actions (grouped)	Empty-State CTA(s)	View Header Actions	Create/Edit Save+Cancel	Audit log?	Notes / Exemptions
Managed tenant onboarding workflow	app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php	Existing Start onboarding and draft-selection affordances remain; readiness-specific header additions stay non-destructive	N/A - guided workflow page, not a list table	Draft-picker context may expose Resume onboarding; readiness panels expose one primary Open operation link when evidence exists	none	Start onboarding on empty/start state	Existing Cancel onboarding and Delete draft remain in header placements by risk; Open operation and Open tenant stay contextual in-section links when legitimate	Existing wizard next/back/save/cancel behavior remains	yes for existing draft lifecycle mutations and reused start actions	Guided-workflow exception. Action Surface Contract remains satisfied through one primary next action in-page; destructive actions stay confirmation-protected and capability-gated.

Key Entities (include if feature involves data)

• Tenant Onboarding Session: The existing workspace-scoped workflow record that tracks onboarding checkpoint progression, resumability, and optional linkage to a tenant.
• Provider Connection: The existing tenant-owned provider access record whose consent state, verification state, target-scope summary, and readiness wording inform onboarding readiness.
• Onboarding Readiness Summary: A derived, non-persistent operator view composed from onboarding lifecycle, provider connection truth, permission diagnostics, freshness, supporting operation evidence, and the next recommended action.

Success Criteria (mandatory)

Measurable Outcomes

• SC-001: In each in-scope onboarding scenario, an authorized operator can identify the current blocker and next action from the onboarding workflow in 30 seconds or less without opening raw operation detail first.
• SC-002: In scripted scenarios covering missing consent, permission gaps, disabled or unhealthy provider connection state, stale verification, verification blocked, and ready-for-activation, 100% of rendered states show distinct operator-readable outcomes rather than generic incomplete-state messaging.
• SC-003: When supporting verification or bootstrap evidence exists, the operator can reach the canonical supporting operation from the onboarding workflow in one interaction.
• SC-004: In negative authorization scenarios for wrong workspace, non-member, or non-entitled linked-tenant access, 100% of requests hide onboarding readiness data behind 404 responses, while capability-denied members receive 403 on protected actions.

Assumptions

• Existing onboarding session, provider connection, verification, and permission-posture foundations are sufficient for the first readiness slice.
• The current provider remains Microsoft-first, but provider-specific details stay contextual rather than becoming new platform-core truth.
• Later support diagnostic and trial/demo flows are expected to consume the same derived readiness truth, but any reuse beyond onboarding is deferred from this slice and must not force a new abstraction or second onboarding state model now.