# Implementation Plan: Managed Tenant Onboarding Wizard V1 (Enterprise)

**Branch**: `073-unified-managed-tenant-onboarding-wizard` | **Date**: 2026-02-04 | **Spec**: specs/073-unified-managed-tenant-onboarding-wizard/spec.md
**Input**: Feature specification from specs/073-unified-managed-tenant-onboarding-wizard/spec.md

## Summary

Deliver a single onboarding entry point at `/admin/onboarding` that is workspace-first and tenantless until activation. Verification and optional bootstrap actions run asynchronously as `OperationRun`s and are viewable via a tenantless URL `/admin/operations/{run}` with workspace-membership based 404 semantics.

This requires:
- Updating onboarding routing and removing legacy entry points.
- Making the operations run viewer safe and usable without a selected workspace and without tenant routing.
- Ensuring RBAC-UX semantics (non-member → 404, member missing capability → 403) while keeping UI discoverability (disabled+tooltip).

## Technical Context

**Language/Version**: PHP 8.4 (Laravel 12)
**Primary Dependencies**: Filament v5, Livewire v4
**Storage**: PostgreSQL (Sail)
**Testing**: Pest v4
**Target Platform**: macOS dev + Sail containers; deployed in containers (Dokploy)
**Project Type**: Web application
**Performance Goals**: Wizard + Monitoring pages render DB-only (no external calls); queued work for Graph
**Constraints**:
- Canonical entry `/admin/onboarding` only
- Tenantless operations viewer `/admin/operations/{run}` must not require selected workspace and must not auto-switch workspaces
- Secrets never rendered after capture; no secrets in operation run failures/audits
**Scale/Scope**: Multi-workspace admin app; onboarding must be safe, resumable, and regression-tested

## Constitution Check

*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*

- Inventory-first: Not directly impacted.
- Read/write separation: activation + overrides are write paths → audit + tests.
- Graph contract path: verification/bootstrap Graph calls only via `GraphClientInterface` and `config/graph_contracts.php` (including connectivity probes like `organization` and service-principal permission lookups).
- Deterministic capabilities: wizard uses canonical capability registry; no role-string checks.
- RBAC-UX: enforce 404/403 semantics; server-side authorizes all actions; UI disabled state is informational only.
- Authorization planes: tenant plane (Entra users) only; no platform plane (`/system`) routes or cross-plane behavior.
- Run observability: verification/bootstrap runs use `OperationRun`; render remains DB-only.
- Data minimization: never persist secrets in session/state/report/audit.
- Badge semantics: status chips use centralized badge mapping.

## Project Structure

### Documentation (this feature)

```text
specs/073-unified-managed-tenant-onboarding-wizard/
├── plan.md
├── research.md
├── data-model.md
├── quickstart.md
├── contracts/
│   ├── http.openapi.yaml
│   └── onboarding-actions.md
└── tasks.md
```

### Source Code (repository root)

```text
app/
├── Filament/Pages/
├── Filament/Resources/
├── Http/Middleware/
├── Models/
├── Policies/
├── Services/
└── Support/

database/migrations/
tests/Feature/
```

**Structure Decision**: Implement onboarding as a Filament Page under `app/Filament/Pages` and keep operations viewing on `OperationRunResource`, but change authorization/middleware to support tenantless viewing.

## Phase 0 — Research

See: specs/073-unified-managed-tenant-onboarding-wizard/research.md

## Phase 1 — Design & Contracts

See:
- specs/073-unified-managed-tenant-onboarding-wizard/data-model.md
- specs/073-unified-managed-tenant-onboarding-wizard/contracts/http.openapi.yaml
- specs/073-unified-managed-tenant-onboarding-wizard/contracts/onboarding-actions.md
- specs/073-unified-managed-tenant-onboarding-wizard/quickstart.md

## Phase 2 — Planning (implementation outline)

1) Routing
- Add `/admin/onboarding` (canonical, sole entry point).
- Remove legacy entry points (404; no redirects): `/admin/new`, `/admin/managed-tenants/onboarding`, and any tenant-scoped onboarding/create entry points.

2) Tenantless operations run viewer
- Exempt `/admin/operations/{run}` from forced workspace selection (`EnsureWorkspaceSelected`) and from tenant auto-selection side effects when needed.
- Authorize `OperationRun` viewing by workspace membership derived from the run (non-member → 404).

3) OperationRun model + schema alignment
- Add `operation_runs.workspace_id` and support tenantless runs (`tenant_id` nullable) if onboarding verification/bootstraps start before activation.
- Preserve DB-level active-run dedupe with partial unique indexes for both tenant-bound and tenantless runs.

4) Wizard authorization model
- Gate wizard actions per canonical capabilities; keep controls visible-but-disabled with tooltip; server-side returns 403 for execution.
- Activation is owner-only; blocked override requires reason + audit.

5) Tests
- Add/extend Pest feature tests for:
  - canonical `/admin/onboarding` routing
  - legacy entry points 404
  - `/admin/operations/{run}` membership→404 behavior without selected workspace
  - 403 for member action attempts without capability
  - owner-only activation + override audit reason

## Complexity Tracking

No constitution violations expected; changes are localized and gated by tests.