{
  "stack": {
    "workspaces": {
      "server": {
        "analytics": {
          "provider": "posthog",
          "packages": {
            "server": "posthog-node",
            "client": "posthog-js"
          }
        }
      }
    }
  },
  "features": {
    "analytics": {
      "enabled": true,
      "provider": "posthog"
    }
  },
  "notion": {
    "teamspace": "MyTeamspace",
    "idPrefix": "KODO",
    "_populated_by_init": {
      "databases": {
        "events": { "dataSourceId": "collection://..." },
        "eventProperties": { "dataSourceId": "collection://..." },
        "featureFlags": { "dataSourceId": "collection://..." },
        "experiments": { "dataSourceId": "collection://..." },
        "dashboards": { "dataSourceId": "collection://..." }
      }
    }
  },
  "posthog": {
    "projectId": "",
    "organizationSlug": "",
    "environments": {
      "development": {
        "apiKey": "phc_dev_...",
        "host": "https://app.posthog.com"
      },
      "production": {
        "apiKey": "phc_prod_...",
        "host": "https://app.posthog.com"
      }
    }
  }
}

- General user interactions (clicks, pageviews)
- Form interactions
- Link clicks and navigation
- Rapid prototyping/MVP analytics

- Business-critical actions (purchase, signup, subscription)
- Feature-specific tracking with custom properties
- Backend events (API calls, webhooks, jobs)
- Events requiring precise timing or context
- Cross-platform consistency

{domain}_{action}_{object}

Examples:
- user_signed_up
- subscription_created
- payment_completed
- feature_flag_evaluated
- experiment_variant_assigned
- dashboard_viewed
- report_exported

interface StandardEventProperties {
  // Identity
  $user_id?: string;
  $session_id?: string;

  // Context
  $current_url?: string;
  $pathname?: string;
  $referrer?: string;

  // Custom context
  feature_area?: string;
  component?: string;
  action_source?: 'button' | 'keyboard' | 'api' | 'automated';

  // Business context
  plan_type?: string;
  organization_id?: string;

  // Technical
  client_timestamp?: string;
  sdk_version?: string;
}

// lib/posthog.ts
import posthog from 'posthog-js';

const POSTHOG_KEY = import.meta.env.VITE_POSTHOG_KEY;
const POSTHOG_HOST = import.meta.env.VITE_POSTHOG_HOST || 'https://app.posthog.com';

export function initPostHog() {
  if (typeof window !== 'undefined' && POSTHOG_KEY) {
    posthog.init(POSTHOG_KEY, {
      api_host: POSTHOG_HOST,
      capture_pageview: true,
      capture_pageleave: true,
      autocapture: true,
      persistence: 'localStorage+cookie',

      // Session recording
      session_recording: {
        maskAllInputs: true,
        maskTextSelector: '[data-mask]',
      },

      // Performance
      loaded: (posthog) => {
        if (import.meta.env.DEV) {
          posthog.debug();
        }
      },
    });
  }
}

// Custom event helper with type safety
export function trackEvent<T extends Record<string, unknown>>(
  eventName: string,
  properties?: T
) {
  posthog.capture(eventName, {
    ...properties,
    client_timestamp: new Date().toISOString(),
  });
}

// Feature flag helper
export function isFeatureEnabled(flagKey: string): boolean {
  return posthog.isFeatureEnabled(flagKey) ?? false;
}

// Get feature flag payload
export function getFeatureFlagPayload<T>(flagKey: string): T | undefined {
  return posthog.getFeatureFlagPayload(flagKey) as T | undefined;
}

// Identify user
export function identifyUser(
  userId: string,
  properties?: Record<string, unknown>
) {
  posthog.identify(userId, properties);
}

// Reset on logout
export function resetAnalytics() {
  posthog.reset();
}

// lib/posthog-server.ts
import { PostHog } from 'posthog-node';

const client = new PostHog(process.env.POSTHOG_API_KEY!, {
  host: process.env.POSTHOG_HOST || 'https://app.posthog.com',
  flushAt: 20,
  flushInterval: 10000,
});

// Graceful shutdown
process.on('SIGTERM', async () => {
  await client.shutdown();
});

export function trackServerEvent(
  distinctId: string,
  eventName: string,
  properties?: Record<string, unknown>
) {
  client.capture({
    distinctId,
    event: eventName,
    properties: {
      ...properties,
      $lib: 'posthog-node',
      server_timestamp: new Date().toISOString(),
    },
  });
}

export function identifyServerUser(
  distinctId: string,
  properties: Record<string, unknown>
) {
  client.identify({
    distinctId,
    properties,
  });
}

export async function getFeatureFlag(
  flagKey: string,
  distinctId: string,
  options?: {
    personProperties?: Record<string, unknown>;
    groupProperties?: Record<string, Record<string, unknown>>;
  }
): Promise<boolean | string | undefined> {
  return client.getFeatureFlag(flagKey, distinctId, options);
}

export async function getAllFlags(
  distinctId: string
): Promise<Record<string, boolean | string>> {
  return client.getAllFlags(distinctId);
}

export { client as posthog };

{scope}_{feature}_{variant_type}

Examples:
- release_new_dashboard_enabled
- experiment_pricing_page_variant
- ops_maintenance_mode_enabled
- beta_ai_assistant_enabled

// hooks/useFeatureFlag.ts
import { useEffect, useState } from 'react';
import { isFeatureEnabled, getFeatureFlagPayload } from '@/lib/posthog';

export function useFeatureFlag(flagKey: string): boolean {
  const [enabled, setEnabled] = useState(false);

  useEffect(() => {
    setEnabled(isFeatureEnabled(flagKey));
  }, [flagKey]);

  return enabled;
}

export function useFeatureFlagPayload<T>(flagKey: string): T | undefined {
  const [payload, setPayload] = useState<T | undefined>();

  useEffect(() => {
    setPayload(getFeatureFlagPayload<T>(flagKey));
  }, [flagKey]);

  return payload;
}

// Usage
function MyComponent() {
  const showNewFeature = useFeatureFlag('release_new_feature_enabled');
  const experimentVariant = useFeatureFlagPayload<{ variant: 'A' | 'B' }>('experiment_checkout');

  if (!showNewFeature) return <LegacyComponent />;

  return experimentVariant?.variant === 'B'
    ? <NewCheckoutB />
    : <NewCheckoutA />;
}

# List existing experiments
mcp__posthog__experiment-get-all

# Create new experiment
mcp__posthog__experiment-create with:
- name: Descriptive experiment name
- feature_flag_key: experiment_feature_key
- primary_metrics: [{ metric_type: 'funnel', event_name: 'purchase_completed' }]
- variants: [{ key: 'control', rollout_percentage: 50 }, { key: 'test', rollout_percentage: 50 }]

# Get experiment results
mcp__posthog__experiment-results-get with experimentId

# List dashboards
mcp__posthog__dashboards-get-all

# Create dashboard
mcp__posthog__dashboard-create with:
- name: Dashboard name
- description: Purpose and audience
- pinned: true/false

# Add insights to dashboard
mcp__posthog__add-insight-to-dashboard with:
- insightId: ID from insight creation
- dashboardId: Target dashboard ID

kodo query "analytics events"
kodo query "feature flags"

kodo reflect  # Capture tracking decisions as learnings