nexu-io
diff --git a/‎apps/web/src/App.tsx‎
Lines changed: 22 additions & 0 deletions b/‎apps/web/src/App.tsx‎
Lines changed: 22 additions & 0 deletions
diff --git a/‎apps/web/src/analytics/client.ts‎
Lines changed: 18 additions & 0 deletions b/‎apps/web/src/analytics/client.ts‎
Lines changed: 18 additions & 0 deletions
diff --git a/‎apps/web/src/analytics/events.ts‎
Lines changed: 59 additions & 0 deletions b/‎apps/web/src/analytics/events.ts‎
Lines changed: 59 additions & 0 deletions
diff --git a/‎apps/web/src/analytics/identity.ts‎
Lines changed: 45 additions & 0 deletions b/‎apps/web/src/analytics/identity.ts‎
Lines changed: 45 additions & 0 deletions
diff --git a/‎apps/web/src/analytics/provider.tsx‎
Lines changed: 8 additions & 0 deletions b/‎apps/web/src/analytics/provider.tsx‎
Lines changed: 8 additions & 0 deletions
diff --git a/‎apps/web/src/components/ChatPane.tsx‎
Lines changed: 25 additions & 2 deletions b/‎apps/web/src/components/ChatPane.tsx‎
Lines changed: 25 additions & 2 deletions
@@ -9,6 +9,10 @@ import {
 import { deriveUploadCohort } from './analytics/upload-tracking';
 import { setPendingDesignSystemCreateEntry } from './analytics/ds-create-entry';
 import { detectClientType } from './analytics/identity';
+import {
+  stashOnboardingEntryForProject,
+  type OnboardingEntry,
+} from './onboarding/onboarding-entry';
 import {
   deriveConfigureGlobals,
   projectKindFromMetadataToTracking,
@@ -140,6 +144,7 @@ type AppCreateProjectInput = Omit<CreateInput, 'metadata'> & {
   pendingFiles?: File[];
   userWorkingDirToken?: string;
   linkedDirs?: string[] | null;
+  onboardingEntry?: OnboardingEntry;
 };
 
 const APP_CONFIG_CHANGED_EVENT = 'open-design:app-config-changed';
@@ -1576,6 +1581,23 @@ function AppInner() {
              back to manual send. */
         }
       }
+      // Home recommendation handoff: now that the project exists and its id is
+      // known, stash the onboarding entry keyed by that id. Studio consumes it
+      // by the same id on mount. Keying by id (instead of a single global slot
+      // written before create) removes the race where opening an unrelated
+      // project mid-create could steal the personalized funnel context, and
+      // means a failed/aborted create leaves nothing behind.
+      if (input.onboardingEntry) {
+        // Cache the prefilled seed prompt WITH the entry so the first-prompt
+        // funnel's `has_prefilled_prompt` comparison base survives a
+        // reopen-before-send (project.pendingPrompt is wiped on first mount).
+        stashOnboardingEntryForProject(result.project.id, {
+          ...input.onboardingEntry,
+          ...(derivedPendingPrompt
+            ? { seedPrompt: derivedPendingPrompt.trim() }
+            : {}),
+        });
+      }
       const project = result.appliedPluginSnapshotId
         ? {
             ...result.project,
 
@@ -15,13 +15,18 @@ import {
   clearExceptionTrackingContext,
   setExceptionTrackingContext,
 } from './error-tracking';
+import { pinFirstSessionForCapture } from './identity';
 
 interface AnalyticsContext {
   anonymousId: string;
   sessionId: string;
   clientType: AnalyticsClientType;
   locale: string;
   appVersion: string;
+  // Whether this is the install's first analytics session (see
+  // identity.ts#isFirstSession). Optional so callers that don't care
+  // (error tracking) can omit it.
+  isFirstSession?: boolean;
 }
 
 let client: PostHog | null = null;
@@ -337,6 +342,10 @@ export async function getAnalyticsClient(
             client_type: context.clientType,
             locale: context.locale,
             session_id: context.sessionId,
+            // Onboarding-funnel dimension (spec §11.1 common fields).
+            ...(context.isFirstSession !== undefined
+              ? { is_first_session: context.isFirstSession }
+              : {}),
             // v2 rename: was `anonymous_id`. Value is unchanged — the same
             // installationId / local-UUID fallback.
             device_id: distinctId,
@@ -363,6 +372,15 @@ export async function getAnalyticsClient(
         },
       });
       client = posthog;
+      // Pin the first-analytics-session marker only now — init returned without
+      // throwing and capture is live. This is the single consent gate every
+      // caller (mount, locale effect, track(), and the setConsent opt-in
+      // re-init) funnels through, so an install that first booted with
+      // analytics OFF and opts in later records its real first analytics
+      // session as first. Pinning earlier (before import()/init) would burn the
+      // marker on a boot where init actually failed and no session was ever
+      // captured (see identity.ts#isFirstSession). Idempotent + best-effort.
+      pinFirstSessionForCapture();
       flushPersonProperties();
       return posthog;
     } catch {
 
@@ -73,6 +73,10 @@ import type {
   AmrAuthResultProps,
   AmrEntryClickProps,
   RunFailedToastSurfaceViewProps,
+  HomeRecommendationClickProps,
+  HomeRecommendationSurfaceViewProps,
+  StudioOnboardingHintClickProps,
+  StudioOnboardingHintSurfaceViewProps,
   ChatPanelResourcesPopoverClickProps,
   ChatPanelMessageQueueClickProps,
   FileManagerClickProps,
@@ -131,6 +135,9 @@ import type {
   OnboardingClickProps,
   OnboardingRuntimeScanResultProps,
   OnboardingCompleteResultProps,
+  OnboardingPromptPrefilledProps,
+  OnboardingFirstPromptSentProps,
+  OnboardingFirstGenerationCompletedProps,
   DesignSystemSourceIngestResultProps,
   DesignSystemCreateResultProps,
   DesignSystemReviewResultProps,
@@ -258,6 +265,36 @@ export function trackRunFailedToastGoAmrClick(
   send(track, 'ui_click', props);
 }
 
+// Personalized first-run recommendation on Home (spec §7).
+export function trackHomeRecommendationSurfaceView(
+  track: Track,
+  props: HomeRecommendationSurfaceViewProps,
+): void {
+  send(track, 'surface_view', props);
+}
+
+export function trackHomeRecommendationClick(
+  track: Track,
+  props: HomeRecommendationClickProps,
+): void {
+  send(track, 'ui_click', props);
+}
+
+// First-generation Studio hint (spec §8.3).
+export function trackStudioOnboardingHintSurfaceView(
+  track: Track,
+  props: StudioOnboardingHintSurfaceViewProps,
+): void {
+  send(track, 'surface_view', props);
+}
+
+export function trackStudioOnboardingHintClick(
+  track: Track,
+  props: StudioOnboardingHintClickProps,
+): void {
+  send(track, 'ui_click', props);
+}
+
 export function trackAmrEntryClick(
   track: Track,
   props: AmrEntryClickProps,
@@ -1082,6 +1119,28 @@ export function trackOnboardingCompleteResult(
   send(track, 'onboarding_complete_result', props);
 }
 
+// First-generation funnel (spec §11.1).
+export function trackOnboardingPromptPrefilled(
+  track: Track,
+  props: OnboardingPromptPrefilledProps,
+): void {
+  send(track, 'onboarding_prompt_prefilled', props);
+}
+
+export function trackOnboardingFirstPromptSent(
+  track: Track,
+  props: OnboardingFirstPromptSentProps,
+): void {
+  send(track, 'onboarding_first_prompt_sent', props);
+}
+
+export function trackOnboardingFirstGenerationCompleted(
+  track: Track,
+  props: OnboardingFirstGenerationCompletedProps,
+): void {
+  send(track, 'onboarding_first_generation_completed', props);
+}
+
 // ---- Design-system lifecycle ---------------------------------------------
 //
 // `trackDesignSystem*Result` cover the five lifecycle moments in the
 
@@ -56,6 +56,51 @@ export function getSessionId(): string {
   }
 }
 
+const FIRST_SESSION_ID_KEY = 'open-design:analytics.first_session_id';
+
+// Whether the current browser session is this install's FIRST analytics
+// session. The first analytics session's `getSessionId()` value is pinned in
+// localStorage by `pinFirstSessionForCapture()`; the flag stays true for the
+// whole lifetime of that tab session (repeat calls compare against the pin
+// rather than re-deriving) and is false for every later session. Registered as
+// the `is_first_session` super property so onboarding funnels can split
+// first-run behavior from returning visits.
+//
+// This read is PURE: it never writes the pin. Persisting the pin is deferred to
+// `pinFirstSessionForCapture()`, which runs only once capture is actually
+// enabled (post-consent). Otherwise an install that first boots with analytics
+// OFF and opts in later would have its real first *analytics* session
+// mislabeled `is_first_session=false`, systematically skewing the onboarding
+// funnel split. Rollout caveat: installs that predate this marker report one
+// mislabeled `true` session on their first captured boot. Storage-denied
+// contexts report false — we'd rather under-count first sessions than throw.
+export function isFirstSession(): boolean {
+  if (typeof window === 'undefined') return false;
+  try {
+    const pinned = window.localStorage.getItem(FIRST_SESSION_ID_KEY);
+    if (!pinned) return true;
+    return pinned === getSessionId();
+  } catch {
+    return false;
+  }
+}
+
+// Persist the first-analytics-session marker. Call this ONLY from the consented
+// analytics-init path (i.e. once `/api/analytics/config` confirms capture is
+// enabled), never on unconditional provider mount — see `isFirstSession()` for
+// why. No-op once a pin already exists, and never throws in storage-denied
+// contexts.
+export function pinFirstSessionForCapture(): void {
+  if (typeof window === 'undefined') return;
+  try {
+    if (window.localStorage.getItem(FIRST_SESSION_ID_KEY)) return;
+    window.localStorage.setItem(FIRST_SESSION_ID_KEY, getSessionId());
+  } catch {
+    // Privacy mode / quota — losing the pin only risks a later session being
+    // mislabeled first; never throw out of an analytics path.
+  }
+}
+
 // Claim the next 0-based run turn index for the current browser analytics
 // session and advance the counter. Lives in sessionStorage so it shares the
 // exact lifetime of the `session_id` above — both reset together when the tab
 
@@ -33,6 +33,7 @@ import {
   detectClientType,
   getAnonymousId,
   getSessionId,
+  isFirstSession,
 } from './identity';
 import { randomUUID } from '../utils/uuid';
 
@@ -166,6 +167,8 @@ export function AnalyticsProvider({ children }: { children: ReactNode }) {
       anonymousId: getAnonymousId(),
       sessionId: getSessionId(),
       clientType: detectClientType(),
+      // Pinned once per tab session (spec §11.1 common field).
+      isFirstSession: isFirstSession(),
     }),
     [],
   );
@@ -188,13 +191,15 @@ export function AnalyticsProvider({ children }: { children: ReactNode }) {
         anonymousId: identity.anonymousId,
         sessionId: identity.sessionId,
         clientType: identity.clientType,
+        isFirstSession: identity.isFirstSession,
         locale,
         appVersion: resolvedAppVersion,
       });
       await getAnalyticsClient({
         anonymousId: identity.anonymousId,
         sessionId: identity.sessionId,
         clientType: identity.clientType,
+        isFirstSession: identity.isFirstSession,
         locale,
         appVersion: resolvedAppVersion,
       });
@@ -252,6 +257,7 @@ export function AnalyticsProvider({ children }: { children: ReactNode }) {
         anonymousId: identity.anonymousId,
         sessionId: identity.sessionId,
         clientType: identity.clientType,
+        isFirstSession: identity.isFirstSession,
         locale: locale,
         appVersion: resolvedAppVersion,
       });
@@ -310,6 +316,7 @@ export function AnalyticsProvider({ children }: { children: ReactNode }) {
           anonymousId: identity.anonymousId,
           sessionId: identity.sessionId,
           clientType: identity.clientType,
+          isFirstSession: identity.isFirstSession,
           locale: locale,
           appVersion: resolvedAppVersion,
         });
@@ -350,6 +357,7 @@ export function AnalyticsProvider({ children }: { children: ReactNode }) {
               anonymousId: identity.anonymousId,
               sessionId: identity.sessionId,
               clientType: identity.clientType,
+              isFirstSession: identity.isFirstSession,
               locale,
               appVersion: resolvedAppVersion,
             });
 
@@ -20,6 +20,8 @@ import { getResolvedDeviceId } from '../analytics/client';
 import { trackChatPanelClick, trackMessageQueueClick, trackRunFailedToastSurfaceView } from '../analytics/events';
 import { amrHandoffDeviceId, attributedAmrUrl, recordAmrEntry } from '../analytics/amr-attribution';
 import { useT } from '../i18n';
+import { startersForProduct, type ProductType } from '../onboarding/recommendation';
+import { starterCopyFor } from '../onboarding/starter-copy';
 import {
   FEATURED_DESIGN_TOOLBOX_ACTION_IDS,
   findDesignToolboxSkill,
@@ -95,6 +97,7 @@ type TranslateFn = (key: keyof Dict, vars?: Record<string, string | number>) =>
 type StarterPrompt = {
   icon: string;
   title: string;
+  // Empty for path-scoped onboarding starters, which have no category tag.
   tag: string;
   prompt: string;
 };
@@ -510,6 +513,10 @@ interface Props {
   // time before the full `tool_use` arrives. Never persisted.
   liveToolInput?: Record<string, { name: string; text: string; seq?: number }>;
   initialDraft?: string;
+  // Product path of the Home recommendation that started this project. When
+  // set (and concrete), the empty-conversation starter cards show that path's
+  // starters — one-click composer replacements — instead of the generic set.
+  onboardingStarterPath?: ProductType | null;
   composerPlaceholder?: string;
   // Focus the right-hand Questions tab from the chat banner.
   onOpenQuestions?: (request?: QuestionFormOpenRequest) => void;
@@ -796,6 +803,7 @@ export function ChatPane({
   forceStreamingMessageIds,
   liveToolInput,
   initialDraft,
+  onboardingStarterPath = null,
   composerPlaceholder,
   onOpenQuestions,
   onContinueRemainingTasks,
@@ -1029,6 +1037,19 @@ export function ChatPane({
     })),
     [projectMetadata, t],
   );
+  // Empty-conversation starter cards. A recommendation-started project shows
+  // its OWN product path's starters — clicking replaces the composer draft, so
+  // the pre-filled first request and the cards complement rather than compete.
+  // The general fallback path and every other project keep the generic set.
+  const starterTemplateCards = useMemo<StarterPrompt[]>(() => {
+    if (onboardingStarterPath && onboardingStarterPath !== 'general') {
+      return startersForProduct(onboardingStarterPath).map((starter) => {
+        const copy = starterCopyFor(starter.id);
+        return { icon: '✦', title: t(copy.title), tag: '', prompt: t(copy.firstPrompt) };
+      });
+    }
+    return pickStarters(projectMetadata, t);
+  }, [onboardingStarterPath, projectMetadata, t]);
   const followUpComposerScenarios = useMemo<PlaceholderScenario[]>(() => {
     if (nextStepVariant === 'design-system') {
       return DESIGN_SYSTEM_NEXT_STEP_ACTIONS.map((action) => ({
@@ -2209,7 +2230,7 @@ export function ChatPane({
                         </span>
                       </div>
                       <div className="chat-examples" role="list">
-                        {pickStarters(projectMetadata, t).map((ex, i) => (
+                        {starterTemplateCards.map((ex, i) => (
                           <button
                             key={`${ex.title}-${i}`}
                             type="button"
@@ -2232,7 +2253,9 @@ export function ChatPane({
                             <span className="chat-example-body">
                               <span className="chat-example-head">
                                 <span className="chat-example-title">{ex.title}</span>
-                                <span className="chat-example-tag">{ex.tag}</span>
+                                {ex.tag ? (
+                                  <span className="chat-example-tag">{ex.tag}</span>
+                                ) : null}
                               </span>
                               <span className="chat-example-prompt">{ex.prompt}</span>
                             </span>