TenantAtlas/specs/069-tenant-onboarding-wizard-v2/quickstart.md

Quickstart: Managed Tenant Onboarding Wizard UI (v2) (069)

This quickstart is for developers validating the onboarding wizard + task board locally.

Prerequisites

• Docker + Docker Compose (Laravel Sail)
• Node.js + npm

Local setup

• Start containers: ./vendor/bin/sail up -d
• Install deps (if needed): ./vendor/bin/sail composer install
• Run migrations: ./vendor/bin/sail artisan migrate --force
• Build assets: ./vendor/bin/sail npm run build

Manual QA scenarios

Scenario A — Start onboarding and link a Provider Connection

1. Sign in as a tenant Owner.
2. Navigate to the onboarding entry point.
3. Create/select a Provider Connection and attach credentials (client secret only).
4. Confirm secrets are never shown after save.

Scenario B — Task board (Step 4+) and evidence-driven statuses

1. Navigate to Step 4.
2. Run “Verify permissions”.
3. Confirm:
   • an OperationRun is created (or reused if already active),
   • task status updates from stored evidence,
   • failures show sanitized reason + message.

Scenario C — Concurrency guard

1. Start a task.
2. Immediately attempt to start it again.
3. Confirm the action is blocked and links to the existing active run.

Scenario D — Collaboration lock

1. User A opens onboarding session and acquires lock.
2. User B opens the same session.
3. Confirm User B sees a lock banner and cannot mutate unless takeover permission is granted.

Testing

Run targeted tests for the feature as they are added:

• ./vendor/bin/sail artisan test --compact --filter=Onboarding

Common issues

• If the UI doesn’t reflect changes, run ./vendor/bin/sail npm run dev or ./vendor/bin/sail npm run build.
• If task runs stay “Queued”, confirm the queue worker is running (Sail queue service).