# Research: Managed Tenant Onboarding Draft Identity & Resume Semantics

## Decision 1: Use explicit draft identity in the URL

- **Decision**: Use a hybrid model with `/admin/onboarding` as a landing route and `/admin/onboarding/{onboardingDraft}` as the canonical route for an active draft.
- **Rationale**: This gives operators a concrete mental model, makes refresh deterministic, and removes silent wizard-state heuristics as the primary resume mechanism.
- **Alternatives considered**:
  - Keep landing-only heuristic resume: rejected because it is ambiguous and not bookmarkable.
  - Query parameter only: acceptable technically, but rejected as the primary enterprise representation because the path route is clearer and easier to reason about.

## Decision 2: Resume stage comes from persisted state, not only `current_step`

- **Decision**: Derive the resumed wizard step from persisted confirmed data completeness plus verification and bootstrap state.
- **Rationale**: Persisted data is more trustworthy than a stale step marker and tolerates partial inconsistencies better.
- **Alternatives considered**:
  - Resume purely from `current_step`: rejected because it can lie when required state is missing.

## Decision 3: Keep unsaved edits transient

- **Decision**: Persist only at explicit step-confirmation boundaries. Unsaved current-step edits may be lost on refresh.
- **Rationale**: This keeps the model understandable, avoids partial write complexity, and matches the enterprise requirement that confirmed work be durable without implying autosave.
- **Alternatives considered**:
  - Autosave every input: rejected as out of scope and higher risk for misleading partial persistence semantics.

## Decision 4: Use workspace-shared draft visibility for continuity

- **Decision**: Authorized onboarding operators in the current workspace may see resumable drafts, regardless of creator.
- **Rationale**: Enterprise admin workflows require continuity across operators and should not become fragile when one user is unavailable.
- **Alternatives considered**:
  - Creator-only visibility: rejected because it harms operational continuity and creates unnecessary support burden.

## Decision 5: Completed and cancelled drafts are non-resumable

- **Decision**: Completed and cancelled drafts remain historical or summary records and do not reopen in edit mode.
- **Rationale**: This avoids unsafe reopening and preserves operator trust around lifecycle meaning.
- **Alternatives considered**:
  - Allow reopening completed drafts: rejected because it blurs activation completion semantics.

## Decision 6: Browser-level validation is mandatory

- **Decision**: Add browser tests for hard refresh on the canonical draft route.
- **Rationale**: The main trust defect is visible only in real reload behavior, not just unit or Livewire state transitions.
- **Alternatives considered**:
  - Feature tests only: rejected because they do not prove real browser reload semantics.