Activation checklist + MCP OAuth authorize UX (#239)

app/Enums/PostHog/OnboardingEvent.php

@@ -0,0 +1,13 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Enums\PostHog;
+
+enum OnboardingEvent: string
+{
+    case Viewed = 'onboarding.viewed';
+    case StepCompleted = 'onboarding.step_completed';
+    case StepSkipped = 'onboarding.step_skipped';
+    case Completed = 'onboarding.completed';
+}

app/Enums/SocialAccount/Platform.php

@@ -390,6 +390,27 @@ public function isConnectable(): bool
         };
     }
 
+    /**
+     * Connectable platforms shaped for Inertia account/onboarding grids.
+     * Sorted alphabetically by label (ASC, case-insensitive).
+     *
+     * @return list<array{value: string, label: string, color: string, network: string}>
+     */
+    public static function connectableOptions(): array
+    {
+        return collect(self::cases())
+            ->filter(fn (self $platform): bool => $platform->isConnectable())
+            ->sortBy(fn (self $platform): string => mb_strtolower($platform->label()))
+            ->map(fn (self $platform): array => [
+                'value' => $platform->value,
+                'label' => $platform->label(),
+                'color' => $platform->color(),
+                'network' => $platform->network(),
+            ])
+            ->values()
+            ->all();
+    }
+
     /**
      * Static, platform-specific data exposed to the frontend (e.g. TikTok privacy options,
      * compliance URLs). Returns an empty array for platforms with no extra config.

app/Enums/User/ReferralSource.php

@@ -12,10 +12,15 @@ enum ReferralSource: string
     case YouTube = 'youtube';
     case TikTok = 'tiktok';
     case Instagram = 'instagram';
+    case Threads = 'threads';
     case Reddit = 'reddit';
     case ProductHunt = 'product_hunt';
+    case GitHub = 'github';
+    case HackerNews = 'hacker_news';
+    case Directories = 'directories';
     case AiAssistant = 'ai_assistant';
     case Friend = 'friend';
+    case Founder = 'founder';
     case Blog = 'blog';
     case Other = 'other';
 }

app/Events/OnboardingStatusUpdated.php

@@ -0,0 +1,103 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Events;
+
+use App\Actions\Onboarding\ResolveOnboardingStatus;
+use App\Models\Account;
+use App\Models\User;
+use App\Models\Workspace;
+use Illuminate\Broadcasting\InteractsWithSockets;
+use Illuminate\Broadcasting\PrivateChannel;
+use Illuminate\Contracts\Broadcasting\ShouldBroadcast;
+use Illuminate\Contracts\Events\ShouldDispatchAfterCommit;
+use Illuminate\Foundation\Events\Dispatchable;
+use Illuminate\Queue\SerializesModels;
+use Illuminate\Support\Facades\DB;
+
+class OnboardingStatusUpdated implements ShouldBroadcast, ShouldDispatchAfterCommit
+{
+    use Dispatchable, InteractsWithSockets, SerializesModels;
+
+    public function __construct(public string $workspaceId) {}
+
+    /**
+     * Notify every workspace channel that onboarding state changed — no sync.
+     * Use after complete/skip so owner progress banners update immediately
+     * even when dispatchForAccount would early-return on stamped timestamps.
+     */
+    public static function broadcastForAccount(Account $account): void
+    {
+        foreach ($account->workspaces()->pluck('id') as $workspaceId) {
+            static::dispatch((string) $workspaceId);
+        }
+    }
+
+    /**
+     * Sync progress then broadcast to every workspace on the account.
+     * Use when a step is account-scoped (e.g. MCP OAuth).
+     */
+    public static function dispatchForAccount(Account $account, ?User $actor = null): void
+    {
+        if ($account->isOnboardingOpen()) {
+            static::syncAfterCommit($account->id, $actor?->id);
+        }
+    }
+
+    /**
+     * Sync progress for the workspace account, then broadcast.
+     * Actor-less flows (webhooks/jobs) fall back to the account owner.
+     */
+    public static function dispatchForWorkspace(?string $workspaceId, ?User $actor = null): void
+    {
+        $account = filled($workspaceId)
+            ? Workspace::query()->find($workspaceId)?->account
+            : null;
+
+        if ($account?->isOnboardingOpen()) {
+            static::syncAfterCommit($account->id, $actor?->id);
+        }
+    }
+
+    private static function syncAfterCommit(string $accountId, ?string $actorId): void
+    {
+        DB::afterCommit(function () use ($accountId, $actorId): void {
+            $account = Account::query()->find($accountId);
+
+            if ($account?->isOnboardingOpen()) {
+                app(ResolveOnboardingStatus::class)->syncAndNotify($account, $actorId);
+            }
+        });
+    }
+
+    public function broadcastAs(): string
+    {
+        return 'onboarding.status.updated';
+    }
+
+    /**
+     * @return array<int, PrivateChannel>
+     */
+    public function broadcastOn(): array
+    {
+        return [
+            new PrivateChannel("workspace.{$this->workspaceId}"),
+        ];
+    }
+
+    /**
+     * @return array{workspace_id: string}
+     */
+    public function broadcastWith(): array
+    {
+        return [
+            'workspace_id' => $this->workspaceId,
+        ];
+    }
+
+    public function broadcastQueue(): string
+    {
+        return 'broadcasts';
+    }
+}

app/Http/Controllers/App/BillingController.php

@@ -27,21 +27,27 @@ public function processing(Request $request): Response|RedirectResponse
             return redirect()->route('app.calendar');
         }
 
-        $account = $request->user()->account;
-        $sessionId = $request->query('session_id');
+        $user = $request->user();
+        $account = $user->accountOrFail();
+        $sessionId = $request->string('session_id')->toString();
 
         // Consume the checkout session once: `fromCheckout` is true only the first
         // time this session_id is seen, so a back-button/refresh to the success URL
         // can't re-fire `checkout.completed`. `Cache::add` is atomic — it returns
         // true only when the key didn't exist yet.
-        $fromCheckout = is_string($sessionId) && $sessionId !== ''
+        $fromCheckout = filled($sessionId)
             && Cache::add("checkout_tracked:{$sessionId}", true, now()->addDay());
 
+        $subscriptionActive = $account->subscribed(Account::SUBSCRIPTION_NAME);
+        $redirectToOnboarding = $user->isAccountOwner()
+            && $account->isOnboardingOpen();
+
         return Inertia::render('billing/Processing', [
-            'subscriptionActive' => $account && $account->subscribed(Account::SUBSCRIPTION_NAME),
+            'subscriptionActive' => $subscriptionActive,
             'fromCheckout' => $fromCheckout,
-            'persona' => $request->user()->persona?->value,
-            'conversion' => $fromCheckout && $account?->stripe_id
+            'redirectToOnboarding' => $redirectToOnboarding,
+            'persona' => $user->persona?->value,
+            'conversion' => $fromCheckout && $account->stripe_id
                 ? fn () => $this->buildConversionData($account, $sessionId)
                 : null,
         ]);

app/Http/Controllers/App/OnboardingController.php

@@ -0,0 +1,95 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Http\Controllers\App;
+
+use App\Actions\Onboarding\ResolveOnboardingStatus;
+use App\Enums\PostHog\OnboardingEvent;
+use App\Enums\SocialAccount\Platform as SocialPlatform;
+use App\Http\Resources\App\SocialAccountResource;
+use App\Services\PostHogService;
+use Illuminate\Http\RedirectResponse;
+use Illuminate\Http\Request;
+use Inertia\Inertia;
+use Inertia\Response as InertiaResponse;
+use Symfony\Component\HttpFoundation\Response;
+
+class OnboardingController extends Controller
+{
+    public function __construct(
+        private readonly ResolveOnboardingStatus $resolveOnboardingStatus,
+        private readonly PostHogService $postHog,
+    ) {}
+
+    public function index(Request $request): InertiaResponse|RedirectResponse
+    {
+        $user = $request->user();
+        $workspace = $user->currentWorkspace;
+        $account = $user->accountOrFail();
+        // Pure read on GET — observers + POST complete/skip stamp progress.
+        $status = $this->resolveOnboardingStatus->handle($user);
+
+        if (data_get($status, 'dismissed_at') !== null) {
+            return redirect()->route('app.calendar');
+        }
+
+        if (
+            $account->isOnboardingOpen()
+            && $user->isAccountOwner()
+            && ! data_get($status, 'all_complete')
+        ) {
+            $this->postHog->capture(
+                $user->id,
+                OnboardingEvent::Viewed->value,
+                account: $account,
+            );
+        }
+
+        return Inertia::render('onboarding/Index', [
+            'status' => fn (): array => $status,
+            'canSkipSteps' => fn (): bool => $user->isAccountOwner(),
+            'canManageAccounts' => fn (): bool => $user->can('manageAccounts', $workspace),
+            'canCreatePost' => fn (): bool => $user->can('createPost', $workspace),
+            'mcpUrl' => fn (): string => route('mcp.trypost'),
+            'platforms' => fn (): array => SocialPlatform::connectableOptions(),
+            'accounts' => fn (): array => SocialAccountResource::collection(
+                $workspace->socialAccounts()->orderBy('id')->get(),
+            )->resolve(),
+        ]);
+    }
+
+    public function skipMcp(Request $request): RedirectResponse
+    {
+        abort_unless($request->user()->isAccountOwner(), Response::HTTP_FORBIDDEN);
+
+        $this->resolveOnboardingStatus->skipMcp($request->user());
+
+        return back();
+    }
+
+    public function complete(Request $request): RedirectResponse
+    {
+        $user = $request->user();
+
+        abort_unless($user->isAccountOwner(), Response::HTTP_FORBIDDEN);
+
+        $account = $user->accountOrFail();
+
+        if ($account->isOnboardingDismissed()) {
+            return redirect()->route('app.calendar');
+        }
+
+        if ($account->isOnboardingCompleted()) {
+            return redirect()->route('app.onboarding');
+        }
+
+        if (! data_get($this->resolveOnboardingStatus->handle($user), 'all_complete')) {
+            return redirect()->route('app.onboarding');
+        }
+
+        $this->resolveOnboardingStatus->markCompleted($user);
+
+        return redirect()->route('app.onboarding');
+    }
+}

app/Http/Controllers/Auth/SocialController.php

@@ -38,18 +38,9 @@ public function index(Request $request): Response
 
         $this->authorize('manageAccounts', $workspace);
 
-        $platforms = collect(SocialPlatform::cases())
-            ->filter(fn ($platform) => $platform->isConnectable())
-            ->map(fn ($platform) => [
-                'value' => $platform->value,
-                'label' => $platform->label(),
-                'color' => $platform->color(),
-                'network' => $platform->network(),
-            ])->values();
-
         return Inertia::render('accounts/Index', [
             'workspace' => $workspace,
-            'platforms' => $platforms,
+            'platforms' => SocialPlatform::connectableOptions(),
             'connectedAccounts' => SocialAccountResource::collection(
                 $workspace->socialAccounts()->orderBy('id')->get(),
             )->resolve(),

app/Http/Middleware/App/HandleInertiaRequests.php

@@ -4,12 +4,16 @@
 
 namespace App\Http\Middleware\App;
 
+use App\Actions\Onboarding\ResolveOnboardingStatus;
 use App\Enums\PostPlatform\ContentType;
 use App\Http\Resources\App\HandleInertiaRequests\AuthAccountResource;
 use App\Http\Resources\App\HandleInertiaRequests\AuthPlanResource;
 use App\Http\Resources\App\HandleInertiaRequests\AuthUserResource;
 use App\Http\Resources\App\HandleInertiaRequests\AuthWorkspaceResource;
+use App\Models\User;
 use Illuminate\Http\Request;
+use Inertia\DeferProp;
+use Inertia\Inertia;
 use Inertia\Middleware;
 
 class HandleInertiaRequests extends Middleware
@@ -48,6 +52,7 @@ public function share(Request $request): array
             ],
             'usage' => $account && ! $isSelfHosted ? $account->usage() : null,
             'features' => $account && ! $isSelfHosted ? $account->featureLimits() : null,
+            'onboardingProgress' => $this->onboardingProgress($request, $user),
             'sidebarOpen' => ! $request->hasCookie('sidebar_state') || $request->cookie('sidebar_state') === 'true',
             'flash' => $request->session()->get('flash', []),
             'applicationUrl' => config('app.url'),
@@ -74,4 +79,37 @@ public function shareOnce(Request $request): array
             'contentTypeMediaRules' => fn (): array => ContentType::mediaRulesForFrontend(),
         ];
     }
+
+    /**
+     * Defer step queries for mid-activation owners; everyone else gets false inline.
+     *
+     * Never defer on Passport consent *views*: Inertia deferred props re-request the
+     * same URL, Passport rotates `authToken` on every authorize hit, and approve then
+     * fails with InvalidAuthTokenException against the stale token still on the page.
+     */
+    private function onboardingProgress(Request $request, ?User $user): DeferProp|false
+    {
+        if ($this->isPassportConsentViewRequest($request)) {
+            return false;
+        }
+
+        $onboarding = app(ResolveOnboardingStatus::class);
+
+        return $user && $onboarding->canShowProgress($user)
+            ? Inertia::defer(fn (): array|false => $onboarding->sidebarProgress($user))
+            : false;
+    }
+
+    /**
+     * Exact GET consent-view route names only — not approve/deny, and not wildcards
+     * like passport.authorizations.* (those would suppress defer on POST approve too,
+     * which is unnecessary and easy to misread as "all OAuth").
+     */
+    private function isPassportConsentViewRequest(Request $request): bool
+    {
+        return $request->routeIs(
+            'passport.authorizations.authorize',
+            'passport.device.authorizations.authorize',
+        );
+    }
 }

app/Http/Middleware/App/SetLocale.php

@@ -29,8 +29,10 @@ public function handle(Request $request, Closure $next): Response
 
         $response = $next($request);
 
+        // Passport OAuth errors return a raw Symfony Response (no withCookie()).
+        // Attach via headers so both Illuminate and Symfony responses work.
         if (! $isValid) {
-            $response->withCookie(
+            $response->headers->setCookie(
                 cookie()->forever('locale', config('languages.default'), '/', config('session.domain')),
             );
         }

app/Http/Resources/App/HandleInertiaRequests/AuthUserResource.php

@@ -16,6 +16,7 @@ public static function make(User $user): array
         return [
             'id' => $user->id,
             'name' => $user->name,
+            'first_name' => $user->firstName(),
             'email' => $user->email,
             'has_photo' => $user->has_photo,
             'photo_url' => $user->photo_url,