@rune-kit/rune 2.8.0 → 2.11.0

package/extensions/saas/skills/onboarding-flow.md

@@ -1,139 +1,139 @@
----
-name: "onboarding-flow"
-pack: "@rune/saas"
-description: "User onboarding patterns — progressive disclosure, setup wizards, product tours, activation metrics (AARRR), empty states, re-engagement, and invite flows."
-model: sonnet
-tools: [Read, Edit, Write, Grep, Glob, Bash]
----
-
-# onboarding-flow
-
-User onboarding patterns — progressive disclosure, setup wizards, product tours, activation metrics (AARRR), empty states, re-engagement, and invite flows.
-
-#### Workflow
-
-**Step 1 — Detect onboarding state**
-Use Grep to find onboarding code: `onboarding`, `setup`, `wizard`, `tour`, `welcome`, `getting-started`, `empty-state`, `invite`. Read the signup/post-registration flow to understand what happens after account creation.
-
-**Step 2 — Audit activation funnel**
-Check for: signup → empty dashboard (no guidance), missing setup wizard for critical config, no progress indicator during multi-step setup, empty states without action prompts, invite flow that doesn't pre-populate team context, no activation metric tracking.
-
-**Step 3 — Emit onboarding patterns**
-Emit: multi-step setup wizard with progress persistence (resume on reload), context-aware empty states with primary action, team invite flow with role selection, activation checklist component, and analytics event tracking for funnel steps.
-
-**Step 4 — Activation metric framework (AARRR)**
-Define your "Aha moment" — the single action that correlates with long-term retention. Common patterns: "created first project + invited one teammate" (Slack), "connected data source" (analytics tools), "ran first workflow" (automation tools). Instrument this event explicitly: `analytics.track('activation_achieved', { userId, tenantId, daysFromSignup })`. Track activation rate weekly. If <40% of signups activate in 7 days, the onboarding is broken.
-
-**Step 5 — Re-engagement for dormant users**
-Detect dormant: user signed up but never achieved activation, OR activated user with no activity in 14 days. Trigger: Day 3 after signup with no activation → in-app banner + email tip. Day 7 → personalized email with "here's what you haven't tried yet". Day 14 → offer a guided setup call or live demo. Track re-engagement conversion rate separately from organic activation.
-
-#### Example
-
-```typescript
-// Onboarding wizard with progress persistence + analytics
-const ONBOARDING_STEPS = ['profile', 'workspace', 'invite_team', 'first_project'] as const;
-type Step = typeof ONBOARDING_STEPS[number];
-
-function useOnboarding() {
-  const [progress, setProgress] = useLocalStorage<Record<Step, boolean>>('onboarding', {
-    profile: false, workspace: false, invite_team: false, first_project: false,
-  });
-
-  const currentStep = ONBOARDING_STEPS.find(step => !progress[step]) ?? null;
-  const complete = (step: Step) => {
-    setProgress(prev => ({ ...prev, [step]: true }));
-    analytics.track('onboarding_step_complete', { step, totalSteps: ONBOARDING_STEPS.length });
-  };
-  const isComplete = currentStep === null;
-  const percentComplete = (Object.values(progress).filter(Boolean).length / ONBOARDING_STEPS.length) * 100;
-  return { currentStep, complete, isComplete, percentComplete, progress };
-}
-
-// Empty state library — 5 common SaaS empty states
-const EMPTY_STATES = {
-  no_projects: {
-    icon: 'FolderIcon',
-    title: 'No projects yet',
-    description: 'Create your first project to get started.',
-    cta: { label: 'Create Project', href: '/projects/new' },
-  },
-  no_team_members: {
-    icon: 'UsersIcon',
-    title: 'You\'re working alone',
-    description: 'Invite your team to collaborate.',
-    cta: { label: 'Invite Teammates', href: '/settings/members' },
-  },
-  no_data: {
-    icon: 'ChartIcon',
-    title: 'No data yet',
-    description: 'Connect your first data source to see analytics.',
-    cta: { label: 'Connect Source', href: '/integrations' },
-  },
-  no_integrations: {
-    icon: 'PlugIcon',
-    title: 'No integrations connected',
-    description: 'Connect your tools to unlock automation.',
-    cta: { label: 'Browse Integrations', href: '/integrations' },
-  },
-  no_billing: {
-    icon: 'CreditCardIcon',
-    title: 'No payment method',
-    description: 'Add a payment method to unlock Pro features.',
-    cta: { label: 'Add Payment Method', href: '/settings/billing' },
-  },
-} as const;
-
-// Product tour — step-by-step spotlight with dismiss/snooze
-interface TourStep { target: string; title: string; description: string; position: 'top' | 'bottom' | 'left' | 'right'; }
-
-function useProductTour(tourId: string, steps: TourStep[]) {
-  const [state, setState] = useLocalStorage<{ completed: boolean; dismissed: boolean; step: number }>(`tour:${tourId}`, {
-    completed: false, dismissed: false, step: 0,
-  });
-
-  const advance = () => {
-    if (state.step + 1 >= steps.length) {
-      setState(s => ({ ...s, completed: true }));
-      analytics.track('product_tour_completed', { tourId });
-    } else {
-      setState(s => ({ ...s, step: s.step + 1 }));
-    }
-  };
-
-  const dismiss = (snoozeMinutes?: number) => {
-    if (snoozeMinutes) {
-      const snoozeUntil = Date.now() + snoozeMinutes * 60_000;
-      setState(s => ({ ...s, dismissed: true }));
-      localStorage.setItem(`tour:${tourId}:snooze`, String(snoozeUntil));
-    } else {
-      setState(s => ({ ...s, dismissed: true }));
-      analytics.track('product_tour_dismissed', { tourId, atStep: state.step });
-    }
-  };
-
-  const isSnoozed = () => {
-    const snoozeUntil = Number(localStorage.getItem(`tour:${tourId}:snooze`) ?? 0);
-    return Date.now() < snoozeUntil;
-  };
-
-  const active = !state.completed && !state.dismissed && !isSnoozed();
-  return { active, currentStep: steps[state.step], stepIndex: state.step, advance, dismiss };
-}
-
-// Re-engagement detection — server-side cron
-const detectDormantUsers = async () => {
-  const sevenDaysAgo = new Date(Date.now() - 7 * 24 * 60 * 60 * 1000);
-  const dormant = await prisma.user.findMany({
-    where: {
-      createdAt: { lt: sevenDaysAgo },
-      activatedAt: null, // never completed activation
-      lastReEngagementEmailAt: null,
-    },
-    take: 500,
-  });
-  for (const user of dormant) {
-    await emailQueue.add('re-engagement', { userId: user.id });
-    await prisma.user.update({ where: { id: user.id }, data: { lastReEngagementEmailAt: new Date() } });
-  }
-};
-```
+---
+name: "onboarding-flow"
+pack: "@rune/saas"
+description: "User onboarding patterns — progressive disclosure, setup wizards, product tours, activation metrics (AARRR), empty states, re-engagement, and invite flows."
+model: sonnet
+tools: [Read, Edit, Write, Grep, Glob, Bash]
+---
+
+# onboarding-flow
+
+User onboarding patterns — progressive disclosure, setup wizards, product tours, activation metrics (AARRR), empty states, re-engagement, and invite flows.
+
+#### Workflow
+
+**Step 1 — Detect onboarding state**
+Use Grep to find onboarding code: `onboarding`, `setup`, `wizard`, `tour`, `welcome`, `getting-started`, `empty-state`, `invite`. Read the signup/post-registration flow to understand what happens after account creation.
+
+**Step 2 — Audit activation funnel**
+Check for: signup → empty dashboard (no guidance), missing setup wizard for critical config, no progress indicator during multi-step setup, empty states without action prompts, invite flow that doesn't pre-populate team context, no activation metric tracking.
+
+**Step 3 — Emit onboarding patterns**
+Emit: multi-step setup wizard with progress persistence (resume on reload), context-aware empty states with primary action, team invite flow with role selection, activation checklist component, and analytics event tracking for funnel steps.
+
+**Step 4 — Activation metric framework (AARRR)**
+Define your "Aha moment" — the single action that correlates with long-term retention. Common patterns: "created first project + invited one teammate" (Slack), "connected data source" (analytics tools), "ran first workflow" (automation tools). Instrument this event explicitly: `analytics.track('activation_achieved', { userId, tenantId, daysFromSignup })`. Track activation rate weekly. If <40% of signups activate in 7 days, the onboarding is broken.
+
+**Step 5 — Re-engagement for dormant users**
+Detect dormant: user signed up but never achieved activation, OR activated user with no activity in 14 days. Trigger: Day 3 after signup with no activation → in-app banner + email tip. Day 7 → personalized email with "here's what you haven't tried yet". Day 14 → offer a guided setup call or live demo. Track re-engagement conversion rate separately from organic activation.
+
+#### Example
+
+```typescript
+// Onboarding wizard with progress persistence + analytics
+const ONBOARDING_STEPS = ['profile', 'workspace', 'invite_team', 'first_project'] as const;
+type Step = typeof ONBOARDING_STEPS[number];
+
+function useOnboarding() {
+  const [progress, setProgress] = useLocalStorage<Record<Step, boolean>>('onboarding', {
+    profile: false, workspace: false, invite_team: false, first_project: false,
+  });
+
+  const currentStep = ONBOARDING_STEPS.find(step => !progress[step]) ?? null;
+  const complete = (step: Step) => {
+    setProgress(prev => ({ ...prev, [step]: true }));
+    analytics.track('onboarding_step_complete', { step, totalSteps: ONBOARDING_STEPS.length });
+  };
+  const isComplete = currentStep === null;
+  const percentComplete = (Object.values(progress).filter(Boolean).length / ONBOARDING_STEPS.length) * 100;
+  return { currentStep, complete, isComplete, percentComplete, progress };
+}
+
+// Empty state library — 5 common SaaS empty states
+const EMPTY_STATES = {
+  no_projects: {
+    icon: 'FolderIcon',
+    title: 'No projects yet',
+    description: 'Create your first project to get started.',
+    cta: { label: 'Create Project', href: '/projects/new' },
+  },
+  no_team_members: {
+    icon: 'UsersIcon',
+    title: 'You\'re working alone',
+    description: 'Invite your team to collaborate.',
+    cta: { label: 'Invite Teammates', href: '/settings/members' },
+  },
+  no_data: {
+    icon: 'ChartIcon',
+    title: 'No data yet',
+    description: 'Connect your first data source to see analytics.',
+    cta: { label: 'Connect Source', href: '/integrations' },
+  },
+  no_integrations: {
+    icon: 'PlugIcon',
+    title: 'No integrations connected',
+    description: 'Connect your tools to unlock automation.',
+    cta: { label: 'Browse Integrations', href: '/integrations' },
+  },
+  no_billing: {
+    icon: 'CreditCardIcon',
+    title: 'No payment method',
+    description: 'Add a payment method to unlock Pro features.',
+    cta: { label: 'Add Payment Method', href: '/settings/billing' },
+  },
+} as const;
+
+// Product tour — step-by-step spotlight with dismiss/snooze
+interface TourStep { target: string; title: string; description: string; position: 'top' | 'bottom' | 'left' | 'right'; }
+
+function useProductTour(tourId: string, steps: TourStep[]) {
+  const [state, setState] = useLocalStorage<{ completed: boolean; dismissed: boolean; step: number }>(`tour:${tourId}`, {
+    completed: false, dismissed: false, step: 0,
+  });
+
+  const advance = () => {
+    if (state.step + 1 >= steps.length) {
+      setState(s => ({ ...s, completed: true }));
+      analytics.track('product_tour_completed', { tourId });
+    } else {
+      setState(s => ({ ...s, step: s.step + 1 }));
+    }
+  };
+
+  const dismiss = (snoozeMinutes?: number) => {
+    if (snoozeMinutes) {
+      const snoozeUntil = Date.now() + snoozeMinutes * 60_000;
+      setState(s => ({ ...s, dismissed: true }));
+      localStorage.setItem(`tour:${tourId}:snooze`, String(snoozeUntil));
+    } else {
+      setState(s => ({ ...s, dismissed: true }));
+      analytics.track('product_tour_dismissed', { tourId, atStep: state.step });
+    }
+  };
+
+  const isSnoozed = () => {
+    const snoozeUntil = Number(localStorage.getItem(`tour:${tourId}:snooze`) ?? 0);
+    return Date.now() < snoozeUntil;
+  };
+
+  const active = !state.completed && !state.dismissed && !isSnoozed();
+  return { active, currentStep: steps[state.step], stepIndex: state.step, advance, dismiss };
+}
+
+// Re-engagement detection — server-side cron
+const detectDormantUsers = async () => {
+  const sevenDaysAgo = new Date(Date.now() - 7 * 24 * 60 * 60 * 1000);
+  const dormant = await prisma.user.findMany({
+    where: {
+      createdAt: { lt: sevenDaysAgo },
+      activatedAt: null, // never completed activation
+      lastReEngagementEmailAt: null,
+    },
+    take: 500,
+  });
+  for (const user of dormant) {
+    await emailQueue.add('re-engagement', { userId: user.id });
+    await prisma.user.update({ where: { id: user.id }, data: { lastReEngagementEmailAt: new Date() } });
+  }
+};
+```

package/extensions/saas/skills/subscription-flow.md

@@ -1,95 +1,95 @@
----
-name: "subscription-flow"
-pack: "@rune/saas"
-description: "Subscription UI flows — pricing page, checkout, plan upgrades/downgrades, plan migration, annual/monthly toggle with proration preview, coupon codes, lifetime deal support, and cancellation with retention."
-model: sonnet
-tools: [Read, Edit, Write, Grep, Glob, Bash]
----
-
-# subscription-flow
-
-Subscription UI flows — pricing page, checkout, plan upgrades/downgrades, plan migration, annual/monthly toggle with proration preview, coupon codes, lifetime deal support, and cancellation with retention.
-
-#### Workflow
-
-**Step 1 — Detect subscription model**
-Use Grep to find plan/tier definitions, feature flags, trial logic, checkout components. Read pricing config to understand: plan tiers, billing intervals, trial duration, feature gates, and upgrade/downgrade rules.
-
-**Step 2 — Audit subscription UX**
-Check for: pricing page without annual toggle, checkout without error recovery, no trial-to-paid conversion flow, plan change without proration explanation, cancellation without retention offer, missing feature gates on protected API routes.
-
-**Step 3 — Emit subscription patterns**
-Emit: type-safe plan configuration, feature gate middleware/hook, checkout flow with error handling, plan change with proration preview, cancellation flow with feedback collection, and trial expiry handling.
-
-**Step 4 — Plan migration on downgrade**
-When a user downgrades to a lower plan that has stricter limits (e.g., Pro 50 projects → Free 3 projects): DO NOT hard-delete over-limit data. Three options: (a) **Read-only grace period** — over-limit items become read-only for 30 days, user prompted to delete or upgrade; (b) **Hard limit** — block new item creation when at limit, existing items preserved; (c) **Grace period + export** — email user with export link, mark items for deletion after 60 days. Default recommendation: option (a) for good UX.
-
-**Step 5 — Annual/monthly toggle + proration + coupons + lifetime deals**
-Show annual price with savings badge ("Save 20%"). On plan change, call Stripe's proration preview endpoint and display "You'll be charged $X today" before confirming. For coupon codes: validate via `stripe.promotionCodes.list`, display discount amount/percentage and expiry. For lifetime deals (AppSumo, LemonSqueezy): create a one-time payment product, on `order_created` webhook set `subscription.plan = 'lifetime'` with `expiresAt = null` — lifetime access never expires.
-
-#### Example
-
-```typescript
-// Type-safe plan configuration + feature gating
-const PLANS = {
-  free:     { price: 0,   limits: { projects: 3,   members: 1,   storage: '100MB' }, features: ['basic_analytics'] },
-  pro:      { price: 29,  limits: { projects: 50,  members: 10,  storage: '10GB'  }, features: ['basic_analytics', 'advanced_analytics', 'api_access', 'priority_support'] },
-  team:     { price: 79,  limits: { projects: -1,  members: -1,  storage: '100GB' }, features: ['basic_analytics', 'advanced_analytics', 'api_access', 'priority_support', 'sso', 'audit_log'] },
-  lifetime: { price: 199, limits: { projects: -1,  members: 25,  storage: '50GB'  }, features: ['basic_analytics', 'advanced_analytics', 'api_access', 'priority_support'] },
-} as const;
-
-type PlanId = keyof typeof PLANS;
-type Feature = typeof PLANS[PlanId]['features'][number];
-
-function useFeatureGate(feature: Feature): { allowed: boolean; upgradeRequired: PlanId | null } {
-  const { plan } = useSubscription();
-  const allowed = (PLANS[plan].features as readonly string[]).includes(feature);
-  if (allowed) return { allowed: true, upgradeRequired: null };
-  const requiredPlan = (Object.entries(PLANS) as [PlanId, typeof PLANS[PlanId]][])
-    .find(([_, p]) => (p.features as readonly string[]).includes(feature));
-  return { allowed: false, upgradeRequired: requiredPlan?.[0] ?? null };
-}
-
-// Proration preview before plan change
-const getProrationPreview = async (tenantId: string, newPriceId: string): Promise<number> => {
-  const sub = await db.subscription.findUnique({ where: { tenantId } });
-  const preview = await stripe.invoices.retrieveUpcoming({
-    customer: sub!.stripeCustomerId,
-    subscription: sub!.stripeSubscriptionId,
-    subscription_items: [{ id: sub!.stripeItemId, price: newPriceId }],
-    subscription_proration_behavior: 'create_prorations',
-  });
-  return preview.amount_due / 100; // dollars
-};
-
-// Coupon validation
-const validateCoupon = async (code: string) => {
-  const promos = await stripe.promotionCodes.list({ code, active: true, limit: 1 });
-  if (!promos.data.length) throw new Error('Invalid or expired coupon');
-  const promo = promos.data[0];
-  const coupon = promo.coupon;
-  return {
-    id: promo.id,
-    discount: coupon.percent_off ? `${coupon.percent_off}% off` : `$${(coupon.amount_off! / 100).toFixed(2)} off`,
-    duration: coupon.duration,
-  };
-};
-
-// Lifetime deal — LemonSqueezy one-time payment webhook
-app.post('/billing/webhook/lemonsqueezy', express.raw({ type: 'application/json' }), async (req, res) => {
-  // ...signature check...
-  const payload = JSON.parse(req.body.toString());
-  if (payload.meta.event_name === 'order_created') {
-    const email = payload.data.attributes.user_email;
-    const user = await db.user.findUnique({ where: { email } });
-    if (user) {
-      await db.subscription.upsert({
-        where: { userId: user.id },
-        update: { plan: 'lifetime', expiresAt: null },
-        create: { userId: user.id, plan: 'lifetime', expiresAt: null },
-      });
-    }
-  }
-  res.json({ received: true });
-});
-```
+---
+name: "subscription-flow"
+pack: "@rune/saas"
+description: "Subscription UI flows — pricing page, checkout, plan upgrades/downgrades, plan migration, annual/monthly toggle with proration preview, coupon codes, lifetime deal support, and cancellation with retention."
+model: sonnet
+tools: [Read, Edit, Write, Grep, Glob, Bash]
+---
+
+# subscription-flow
+
+Subscription UI flows — pricing page, checkout, plan upgrades/downgrades, plan migration, annual/monthly toggle with proration preview, coupon codes, lifetime deal support, and cancellation with retention.
+
+#### Workflow
+
+**Step 1 — Detect subscription model**
+Use Grep to find plan/tier definitions, feature flags, trial logic, checkout components. Read pricing config to understand: plan tiers, billing intervals, trial duration, feature gates, and upgrade/downgrade rules.
+
+**Step 2 — Audit subscription UX**
+Check for: pricing page without annual toggle, checkout without error recovery, no trial-to-paid conversion flow, plan change without proration explanation, cancellation without retention offer, missing feature gates on protected API routes.
+
+**Step 3 — Emit subscription patterns**
+Emit: type-safe plan configuration, feature gate middleware/hook, checkout flow with error handling, plan change with proration preview, cancellation flow with feedback collection, and trial expiry handling.
+
+**Step 4 — Plan migration on downgrade**
+When a user downgrades to a lower plan that has stricter limits (e.g., Pro 50 projects → Free 3 projects): DO NOT hard-delete over-limit data. Three options: (a) **Read-only grace period** — over-limit items become read-only for 30 days, user prompted to delete or upgrade; (b) **Hard limit** — block new item creation when at limit, existing items preserved; (c) **Grace period + export** — email user with export link, mark items for deletion after 60 days. Default recommendation: option (a) for good UX.
+
+**Step 5 — Annual/monthly toggle + proration + coupons + lifetime deals**
+Show annual price with savings badge ("Save 20%"). On plan change, call Stripe's proration preview endpoint and display "You'll be charged $X today" before confirming. For coupon codes: validate via `stripe.promotionCodes.list`, display discount amount/percentage and expiry. For lifetime deals (AppSumo, LemonSqueezy): create a one-time payment product, on `order_created` webhook set `subscription.plan = 'lifetime'` with `expiresAt = null` — lifetime access never expires.
+
+#### Example
+
+```typescript
+// Type-safe plan configuration + feature gating
+const PLANS = {
+  free:     { price: 0,   limits: { projects: 3,   members: 1,   storage: '100MB' }, features: ['basic_analytics'] },
+  pro:      { price: 29,  limits: { projects: 50,  members: 10,  storage: '10GB'  }, features: ['basic_analytics', 'advanced_analytics', 'api_access', 'priority_support'] },
+  team:     { price: 79,  limits: { projects: -1,  members: -1,  storage: '100GB' }, features: ['basic_analytics', 'advanced_analytics', 'api_access', 'priority_support', 'sso', 'audit_log'] },
+  lifetime: { price: 199, limits: { projects: -1,  members: 25,  storage: '50GB'  }, features: ['basic_analytics', 'advanced_analytics', 'api_access', 'priority_support'] },
+} as const;
+
+type PlanId = keyof typeof PLANS;
+type Feature = typeof PLANS[PlanId]['features'][number];
+
+function useFeatureGate(feature: Feature): { allowed: boolean; upgradeRequired: PlanId | null } {
+  const { plan } = useSubscription();
+  const allowed = (PLANS[plan].features as readonly string[]).includes(feature);
+  if (allowed) return { allowed: true, upgradeRequired: null };
+  const requiredPlan = (Object.entries(PLANS) as [PlanId, typeof PLANS[PlanId]][])
+    .find(([_, p]) => (p.features as readonly string[]).includes(feature));
+  return { allowed: false, upgradeRequired: requiredPlan?.[0] ?? null };
+}
+
+// Proration preview before plan change
+const getProrationPreview = async (tenantId: string, newPriceId: string): Promise<number> => {
+  const sub = await db.subscription.findUnique({ where: { tenantId } });
+  const preview = await stripe.invoices.retrieveUpcoming({
+    customer: sub!.stripeCustomerId,
+    subscription: sub!.stripeSubscriptionId,
+    subscription_items: [{ id: sub!.stripeItemId, price: newPriceId }],
+    subscription_proration_behavior: 'create_prorations',
+  });
+  return preview.amount_due / 100; // dollars
+};
+
+// Coupon validation
+const validateCoupon = async (code: string) => {
+  const promos = await stripe.promotionCodes.list({ code, active: true, limit: 1 });
+  if (!promos.data.length) throw new Error('Invalid or expired coupon');
+  const promo = promos.data[0];
+  const coupon = promo.coupon;
+  return {
+    id: promo.id,
+    discount: coupon.percent_off ? `${coupon.percent_off}% off` : `$${(coupon.amount_off! / 100).toFixed(2)} off`,
+    duration: coupon.duration,
+  };
+};
+
+// Lifetime deal — LemonSqueezy one-time payment webhook
+app.post('/billing/webhook/lemonsqueezy', express.raw({ type: 'application/json' }), async (req, res) => {
+  // ...signature check...
+  const payload = JSON.parse(req.body.toString());
+  if (payload.meta.event_name === 'order_created') {
+    const email = payload.data.attributes.user_email;
+    const user = await db.user.findUnique({ where: { email } });
+    if (user) {
+      await db.subscription.upsert({
+        where: { userId: user.id },
+        update: { plan: 'lifetime', expiresAt: null },
+        create: { userId: user.id, plan: 'lifetime', expiresAt: null },
+      });
+    }
+  }
+  res.json({ received: true });
+});
+```