luxlabs 1.0.15 → 1.0.17

package/commands/ab-tests.js

@@ -20,7 +20,7 @@ const chalk = require('chalk');
 const fs = require('fs');
 const path = require('path');
 const ora = require('ora');
-const { loadConfig, getProjectId, getStudioApiUrl } = require('../lib/config');
+const { loadConfig, getProjectId, getStudioApiUrl, getInterfaceRepoDir, getInterfacesDir } = require('../lib/config');
 
 /**
  * Show help for ab-tests commands
@@ -52,65 +52,58 @@ function showHelp() {
 
 /**
  * Get the path to ab-tests.json for an interface
- * Supports both interface ID and interface name
+ * Uses ~/.lux-studio/{orgId}/projects/{projectId}/interfaces/{interfaceId}/repo/.lux/ab-tests.json
  */
 function getABTestsPath(interfaceIdentifier) {
-  const interfacesDir = path.join(process.cwd(), 'interfaces');
-
-  if (!fs.existsSync(interfacesDir)) {
-    return null;
+  // First try the config-based path (preferred - used by Electron app)
+  if (interfaceIdentifier) {
+    const repoDir = getInterfaceRepoDir(interfaceIdentifier);
+    if (repoDir) {
+      const configPath = path.join(repoDir, '.lux', 'ab-tests.json');
+      if (fs.existsSync(configPath)) {
+        return configPath;
+      }
+    }
   }
 
-  // If no identifier provided, try to find the only interface
-  if (!interfaceIdentifier) {
+  // Try to find from interfaces dir if no identifier given
+  const interfacesDir = getInterfacesDir();
+  if (interfacesDir && fs.existsSync(interfacesDir)) {
     const entries = fs.readdirSync(interfacesDir, { withFileTypes: true });
     const dirs = entries.filter(e => e.isDirectory());
 
-    if (dirs.length === 0) {
-      return null;
+    if (!interfaceIdentifier && dirs.length === 1) {
+      // Auto-select the only interface
+      const repoDir = path.join(interfacesDir, dirs[0].name, 'repo');
+      const configPath = path.join(repoDir, '.lux', 'ab-tests.json');
+      if (fs.existsSync(configPath)) {
+        return configPath;
+      }
     }
 
-    if (dirs.length === 1) {
-      // Auto-select the only interface
-      interfaceIdentifier = dirs[0].name;
-    } else {
-      // Multiple interfaces - need to specify
-      console.log(chalk.yellow('Multiple interfaces found. Please specify which one:'));
-      for (const dir of dirs) {
-        const metaPath = path.join(interfacesDir, dir.name, 'metadata.json');
-        let name = dir.name;
+    // Search by name if identifier doesn't match directly
+    if (interfaceIdentifier) {
+      for (const entry of entries) {
+        if (!entry.isDirectory()) continue;
+
+        const metaPath = path.join(interfacesDir, entry.name, 'metadata.json');
         if (fs.existsSync(metaPath)) {
           try {
             const meta = JSON.parse(fs.readFileSync(metaPath, 'utf-8'));
-            name = meta.name || dir.name;
+            if (meta.name && meta.name.toLowerCase() === interfaceIdentifier.toLowerCase()) {
+              const repoDir = path.join(interfacesDir, entry.name, 'repo');
+              return path.join(repoDir, '.lux', 'ab-tests.json');
+            }
           } catch (e) { /* ignore */ }
         }
-        console.log(chalk.dim(`  - ${name} (${dir.name})`));
       }
-      return null;
     }
   }
 
-  // Check if it's a direct interface ID (directory exists)
-  let interfaceDir = path.join(interfacesDir, interfaceIdentifier, 'repo');
-  if (fs.existsSync(interfaceDir)) {
-    return path.join(interfaceDir, '.lux', 'ab-tests.json');
-  }
-
-  // Try to find by name
-  const entries = fs.readdirSync(interfacesDir, { withFileTypes: true });
-  for (const entry of entries) {
-    if (!entry.isDirectory()) continue;
-
-    const metaPath = path.join(interfacesDir, entry.name, 'metadata.json');
-    if (fs.existsSync(metaPath)) {
-      try {
-        const meta = JSON.parse(fs.readFileSync(metaPath, 'utf-8'));
-        if (meta.name && meta.name.toLowerCase() === interfaceIdentifier.toLowerCase()) {
-          return path.join(interfacesDir, entry.name, 'repo', '.lux', 'ab-tests.json');
-        }
-      } catch (e) { /* ignore */ }
-    }
+  // Fallback: try cwd-based path (for running from interface repo directory)
+  const cwdPath = path.join(process.cwd(), '.lux', 'ab-tests.json');
+  if (fs.existsSync(cwdPath)) {
+    return cwdPath;
   }
 
   return null;

package/commands/data.js

@@ -182,6 +182,12 @@ ${chalk.bold('Table Commands:')}
   tables export <table-name> [file]     Export table to CSV
   tables import <table-name> <csv-file> Import CSV to table
 
+${chalk.bold('Column Commands:')}
+  tables add-column <table> <name> <type> [--not-null] [--default <val>]  Add column
+  tables drop-column <table> <column>   Delete column
+  tables rename-column <table> <old> <new>  Rename column
+  tables change-type <table> <column> <type>  Change column type (if empty)
+
 ${chalk.bold('KV Commands:')}
   kv list                               List all KV namespaces
   kv init <name> [description]          Create new KV namespace
@@ -585,6 +591,121 @@ ${chalk.bold('Examples:')}
           break;
         }
 
+        // ============ COLUMN OPERATIONS ============
+
+        case 'add-column': {
+          requireArgs(args.slice(2), 3, 'lux data tables add-column <table-name> <column-name> <type> [--not-null] [--default <value>]');
+          const tableName = args[2];
+          const columnName = args[3];
+          const columnType = args[4].toUpperCase();
+
+          // Parse flags
+          const notNull = args.includes('--not-null');
+          const defaultIndex = args.indexOf('--default');
+          const defaultValue = defaultIndex !== -1 ? args[defaultIndex + 1] : undefined;
+
+          info(`Adding column '${columnName}' to table '${tableName}'...`);
+          const tablesApiUrl = getTablesApiUrl();
+
+          const columnDef = {
+            name: columnName,
+            type: columnType,
+            notNull,
+          };
+          if (defaultValue !== undefined) {
+            // Try to parse as number or keep as string
+            const parsed = Number(defaultValue);
+            columnDef.defaultValue = isNaN(parsed) ? defaultValue : parsed;
+          }
+
+          const { data } = await axios.post(
+            `${tablesApiUrl}/${encodeURIComponent(tableName)}/columns`,
+            { column: columnDef },
+            { headers: getStudioAuthHeaders() }
+          );
+
+          success(`Column '${columnName}' added!`);
+          console.log(`   Type: ${data.column.type}`);
+          if (data.column.notNull) console.log(`   NOT NULL: Yes`);
+          break;
+        }
+
+        case 'drop-column': {
+          requireArgs(args.slice(2), 2, 'lux data tables drop-column <table-name> <column-name>');
+          const tableName = args[2];
+          const columnName = args[3];
+
+          info(`Dropping column '${columnName}' from table '${tableName}'...`);
+          const tablesApiUrl = getTablesApiUrl();
+
+          await axios.delete(
+            `${tablesApiUrl}/${encodeURIComponent(tableName)}/columns/${encodeURIComponent(columnName)}`,
+            { headers: getStudioAuthHeaders() }
+          );
+
+          success(`Column '${columnName}' deleted!`);
+          break;
+        }
+
+        case 'rename-column': {
+          requireArgs(args.slice(2), 3, 'lux data tables rename-column <table-name> <old-name> <new-name>');
+          const tableName = args[2];
+          const oldName = args[3];
+          const newName = args[4];
+
+          info(`Renaming column '${oldName}' to '${newName}'...`);
+          const tablesApiUrl = getTablesApiUrl();
+
+          await axios.patch(
+            `${tablesApiUrl}/${encodeURIComponent(tableName)}/columns/${encodeURIComponent(oldName)}`,
+            { newName },
+            { headers: getStudioAuthHeaders() }
+          );
+
+          success(`Column renamed from '${oldName}' to '${newName}'!`);
+          break;
+        }
+
+        case 'change-type': {
+          requireArgs(args.slice(2), 3, 'lux data tables change-type <table-name> <column-name> <new-type>');
+          const tableName = args[2];
+          const columnName = args[3];
+          const newType = args[4].toUpperCase();
+
+          // Validate type
+          const validTypes = ['TEXT', 'INTEGER', 'REAL'];
+          if (!validTypes.includes(newType)) {
+            error(`Invalid type '${newType}'. Must be one of: ${validTypes.join(', ')}`);
+            process.exit(1);
+          }
+
+          // First check if column has data
+          info(`Checking if column '${columnName}' has data...`);
+          const tablesApiUrl = getTablesApiUrl();
+
+          const { data: countData } = await axios.get(
+            `${tablesApiUrl}/${encodeURIComponent(tableName)}/columns/${encodeURIComponent(columnName)}/count`,
+            { headers: getStudioAuthHeaders() }
+          );
+
+          if (countData.hasData) {
+            error(`Cannot change type: column '${columnName}' has ${countData.recordCount} non-null values.`);
+            console.log(chalk.yellow('  Clear the column data first, or drop and recreate the column.'));
+            process.exit(1);
+          }
+
+          info(`Changing column type to ${newType}...`);
+
+          await axios.put(
+            `${tablesApiUrl}/${encodeURIComponent(tableName)}/columns/${encodeURIComponent(columnName)}/type`,
+            { newType },
+            { headers: getStudioAuthHeaders() }
+          );
+
+          success(`Column '${columnName}' type changed to ${newType}!`);
+          break;
+        }
+
         default:
           error(`Unknown table subcommand: ${subCommand}`);
       }

package/commands/webview.js

@@ -233,6 +233,27 @@ async function wait(interfaceId, ms) {
   return result;
 }
 
+/**
+ * Refresh the webview (soft or hard refresh)
+ */
+async function refresh(interfaceId, hard = false) {
+  const id = generateId();
+  const result = await sendCommand({
+    id,
+    type: 'refresh',
+    appId: interfaceId,
+    payload: { hard },
+  });
+
+  if (result.success) {
+    console.log(chalk.green(hard ? 'Hard refresh completed!' : 'Refresh completed!'));
+  } else {
+    console.log(chalk.red('Refresh failed:'), result.error);
+  }
+
+  return result;
+}
+
 /**
  * Start the interface preview in Lux Studio
  */
@@ -265,6 +286,7 @@ function showHelp() {
   console.log('  lux test url <interface-id>                       Get current URL');
   console.log('  lux test navigate <interface-id> <url>            Navigate to URL');
   console.log('  lux test wait <interface-id> <ms>                 Wait for duration');
+  console.log('  lux test refresh <interface-id> [--hard]          Refresh the page');
   console.log('');
   console.log(chalk.cyan('Examples:'));
   console.log('  lux test screenshot my-interface ./screenshot.png');
@@ -272,6 +294,7 @@ function showHelp() {
   console.log('  lux test type my-interface "#email" "user@example.com"');
   console.log('  lux test eval my-interface "document.title"');
   console.log('  lux test navigate my-interface "http://localhost:3000/login"');
+  console.log('  lux test refresh my-interface --hard');
   console.log('');
   console.log(chalk.dim('Note: <interface-id> is the interface ID or name from "lux servers"'));
   console.log('');
@@ -370,6 +393,18 @@ async function handleTest(args = []) {
         break;
       }
 
+      case 'refresh': {
+        const [interfaceId, ...flags] = rest;
+        if (!interfaceId) {
+          console.log(chalk.red('Error: interface-id is required'));
+          showHelp();
+          return;
+        }
+        const hard = flags.includes('--hard') || flags.includes('-h');
+        await refresh(interfaceId, hard);
+        break;
+      }
+
       default:
         console.log(chalk.red(`Unknown test command: ${subcommand}`));
         showHelp();
@@ -388,6 +423,7 @@ module.exports = {
   getUrl,
   navigate,
   wait,
+  refresh,
   startPreview,
   sendCommand,
 };

package/commands/workflows.js

@@ -102,6 +102,11 @@ ${chalk.bold('Commands:')}
   delete <id>                 Delete a local workflow
   diff <id>                   Show local vs published differences
 
+${chalk.bold('Execution History:')}
+  executions <flow-id> [--limit N]  List execution history for a flow
+  execution <flow-id> <exec-id>     Get full execution details
+  node <flow-id> <exec-id> <node-id>  Get specific node execution details
+
 ${chalk.bold('Sync Status:')}
   draft     - Never published, local only
   synced    - Matches published version
@@ -127,6 +132,12 @@ ${chalk.bold('Examples:')}
   lux workflows publish flow_123
   lux workflows diff flow_123
 
+  ${chalk.bold('Execution history:')}
+  lux flow executions my-flow-id
+  lux flow executions my-flow-id --limit 50
+  lux flow execution my-flow-id exec_abc123
+  lux flow node my-flow-id exec_abc123 node-1
+
   ${chalk.bold('Webhook workflow:')}
   lux flow webhook-url flow_123
   lux flow webhook-listen flow_123
@@ -851,6 +862,229 @@ ${chalk.bold('Examples:')}
         break;
       }
 
+      // ============ EXECUTION HISTORY COMMANDS ============
+
+      case 'executions': {
+        requireArgs(args.slice(1), 1, 'lux flow executions <flow-id> [--limit N]');
+        const flowId = args[1];
+
+        // Parse --limit flag
+        const limitIndex = args.indexOf('--limit');
+        const limit = limitIndex !== -1 && args[limitIndex + 1] ? parseInt(args[limitIndex + 1], 10) : 20;
+
+        info(`Fetching execution history for: ${flowId}`);
+
+        const { data } = await axios.get(
+          `${apiUrl}/api/flows/${flowId}/executions?limit=${limit}`,
+          { headers: getAuthHeaders() }
+        );
+
+        if (!data.executions || data.executions.length === 0) {
+          console.log(chalk.dim('\nNo executions found for this flow.\n'));
+          break;
+        }
+
+        console.log(`\n📊 Execution History for: ${flowId}\n`);
+
+        // Status colors
+        const statusColors = {
+          completed: chalk.green,
+          running: chalk.cyan,
+          failed: chalk.red,
+          cancelled: chalk.yellow,
+        };
+
+        const formatted = data.executions.map((exec) => {
+          const statusColor = statusColors[exec.status] || chalk.white;
+          const duration = exec.durationMs ? `${exec.durationMs}ms` : '-';
+          const startedAt = exec.startedAt ? new Date(exec.startedAt).toLocaleString() : '-';
+          const nodeCount = exec.nodeExecutions?.length || 0;
+
+          return {
+            id: exec.id.substring(0, 16) + '...',
+            status: statusColor(exec.status),
+            trigger: exec.triggerType || '-',
+            duration: duration,
+            nodes: nodeCount,
+            started: startedAt,
+            test: exec.isTest ? chalk.yellow('test') : '',
+          };
+        });
+
+        formatTable(formatted);
+
+        if (data.pagination?.hasMore) {
+          console.log(chalk.dim(`\nShowing ${data.executions.length} of ${data.pagination.total} executions.`));
+          console.log(chalk.dim(`Use --limit N to see more.\n`));
+        }
+
+        console.log(chalk.gray(`\nTo see full details: lux flow execution ${flowId} <execution-id>\n`));
+        break;
+      }
+
+      case 'execution': {
+        requireArgs(args.slice(1), 2, 'lux flow execution <flow-id> <execution-id>');
+        const flowId = args[1];
+        const executionId = args[2];
+
+        info(`Fetching execution: ${executionId}`);
+
+        const { data } = await axios.get(
+          `${apiUrl}/api/flows/${flowId}/executions/${executionId}`,
+          { headers: getAuthHeaders() }
+        );
+
+        if (!data.execution) {
+          error(`Execution not found: ${executionId}`);
+          break;
+        }
+
+        const exec = data.execution;
+        const statusColors = {
+          completed: chalk.green,
+          running: chalk.cyan,
+          failed: chalk.red,
+          cancelled: chalk.yellow,
+        };
+        const statusColor = statusColors[exec.status] || chalk.white;
+
+        console.log(`\n📋 Execution Details\n`);
+        console.log(`   ID: ${exec.id}`);
+        console.log(`   Flow: ${exec.flowId}`);
+        console.log(`   Status: ${statusColor(exec.status)}`);
+        console.log(`   Trigger: ${exec.triggerType || '-'}`);
+        console.log(`   Duration: ${exec.durationMs ? exec.durationMs + 'ms' : '-'}`);
+        console.log(`   Started: ${exec.startedAt ? new Date(exec.startedAt).toLocaleString() : '-'}`);
+        console.log(`   Completed: ${exec.completedAt ? new Date(exec.completedAt).toLocaleString() : '-'}`);
+        console.log(`   Version: ${exec.flowVersion || '-'}`);
+        console.log(`   Test Run: ${exec.isTest ? chalk.yellow('Yes') : 'No'}`);
+
+        if (exec.error) {
+          console.log(`\n${chalk.red('❌ Error:')}`);
+          console.log(`   ${exec.error}`);
+        }
+
+        // Show input data
+        if (exec.inputData && Object.keys(exec.inputData).length > 0) {
+          console.log(`\n${chalk.cyan('📥 Input Data:')}`);
+          console.log(formatJson(exec.inputData));
+        }
+
+        // Show output data
+        if (exec.outputData && Object.keys(exec.outputData).length > 0) {
+          console.log(`\n${chalk.cyan('📤 Output Data:')}`);
+          console.log(formatJson(exec.outputData));
+        }
+
+        // Show node executions summary
+        if (exec.nodeExecutions && exec.nodeExecutions.length > 0) {
+          console.log(`\n${chalk.cyan('🔗 Node Executions:')} (${exec.nodeExecutions.length} nodes)\n`);
+
+          const nodeFormatted = exec.nodeExecutions.map((node) => {
+            const nodeStatus = node.status || 'unknown';
+            const nodeStatusColor = statusColors[nodeStatus] || chalk.white;
+            const nodeDuration = node.durationMs ? `${node.durationMs}ms` : '-';
+
+            return {
+              node_id: node.nodeId || node.id,
+              type: node.nodeType || '-',
+              status: nodeStatusColor(nodeStatus),
+              duration: nodeDuration,
+              error: node.error ? chalk.red('⚠') : '',
+            };
+          });
+
+          formatTable(nodeFormatted);
+
+          console.log(chalk.gray(`\nTo see node details: lux flow node ${flowId} ${executionId} <node-id>\n`));
+        }
+
+        break;
+      }
+
+      case 'node': {
+        requireArgs(args.slice(1), 3, 'lux flow node <flow-id> <execution-id> <node-id>');
+        const flowId = args[1];
+        const executionId = args[2];
+        const nodeId = args[3];
+
+        info(`Fetching node execution: ${nodeId}`);
+
+        const { data } = await axios.get(
+          `${apiUrl}/api/flows/${flowId}/executions/${executionId}`,
+          { headers: getAuthHeaders() }
+        );
+
+        if (!data.execution) {
+          error(`Execution not found: ${executionId}`);
+          break;
+        }
+
+        const exec = data.execution;
+        const nodeExec = exec.nodeExecutions?.find(
+          (n) => n.nodeId === nodeId || n.id === nodeId
+        );
+
+        if (!nodeExec) {
+          error(`Node not found in execution: ${nodeId}`);
+          console.log(chalk.dim(`\nAvailable nodes:`));
+          exec.nodeExecutions?.forEach((n) => {
+            console.log(chalk.dim(`  - ${n.nodeId || n.id} (${n.nodeType || 'unknown'})`));
+          });
+          break;
+        }
+
+        const statusColors = {
+          completed: chalk.green,
+          running: chalk.cyan,
+          failed: chalk.red,
+          cancelled: chalk.yellow,
+          skipped: chalk.gray,
+        };
+        const statusColor = statusColors[nodeExec.status] || chalk.white;
+
+        console.log(`\n🔗 Node Execution Details\n`);
+        console.log(`   Node ID: ${nodeExec.nodeId || nodeExec.id}`);
+        console.log(`   Type: ${nodeExec.nodeType || '-'}`);
+        console.log(`   Label: ${nodeExec.label || '-'}`);
+        console.log(`   Status: ${statusColor(nodeExec.status || 'unknown')}`);
+        console.log(`   Duration: ${nodeExec.durationMs ? nodeExec.durationMs + 'ms' : '-'}`);
+        console.log(`   Started: ${nodeExec.startedAt ? new Date(nodeExec.startedAt).toLocaleString() : '-'}`);
+        console.log(`   Completed: ${nodeExec.completedAt ? new Date(nodeExec.completedAt).toLocaleString() : '-'}`);
+
+        if (nodeExec.error) {
+          console.log(`\n${chalk.red('❌ Error:')}`);
+          console.log(`   ${nodeExec.error}`);
+        }
+
+        // Show node config
+        if (nodeExec.config && Object.keys(nodeExec.config).length > 0) {
+          console.log(`\n${chalk.cyan('⚙️  Node Config:')}`);
+          console.log(formatJson(nodeExec.config));
+        }
+
+        // Show input
+        if (nodeExec.input !== undefined) {
+          console.log(`\n${chalk.cyan('📥 Input:')}`);
+          console.log(formatJson(nodeExec.input));
+        }
+
+        // Show output
+        if (nodeExec.output !== undefined) {
+          console.log(`\n${chalk.cyan('📤 Output:')}`);
+          console.log(formatJson(nodeExec.output));
+        }
+
+        // Show raw data if nothing else
+        if (!nodeExec.input && !nodeExec.output && !nodeExec.config) {
+          console.log(`\n${chalk.cyan('📋 Raw Node Data:')}`);
+          console.log(formatJson(nodeExec));
+        }
+
+        console.log('');
+        break;
+      }
+
       default:
         error(
           `Unknown command: ${command}\n\nRun 'lux workflows' to see available commands`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "luxlabs",
-  "version": "1.0.15",
+  "version": "1.0.17",
   "description": "CLI tool for Lux - Upload and deploy interfaces from your terminal",
   "author": "Jason Henkel <jason@uselux.ai>",
   "license": "SEE LICENSE IN LICENSE",

package/templates/interface-boilerplate/components/providers/posthog-provider.tsx

@@ -11,9 +11,22 @@ const LUX_INTERFACE_ID = process.env.NEXT_PUBLIC_LUX_INTERFACE_ID
 const LUX_ORG_ID = process.env.NEXT_PUBLIC_LUX_ORG_ID
 
 /**
- * Parse Lux Studio flag overrides from URL query params.
+ * LUX STUDIO A/B TEST PREVIEW MODE
+ *
  * When previewing A/B test variants in Lux Studio, the preview URL includes
  * ?__lux_flag_overrides={"flag-key":"variant-key"} to force specific variants.
+ *
+ * If no real PostHog API key is configured (NEXT_PUBLIC_POSTHOG_KEY), we use a
+ * fake/dummy key ('phc_lux_preview_mode') to initialize PostHog just enough for
+ * the feature flag override system to work. This allows A/B test previews to
+ * function during local development without a real PostHog account.
+ *
+ * The dummy key disables all analytics (autocapture, session recording, etc.)
+ * so no data is sent to PostHog - it's purely for local flag overrides.
+ */
+
+/**
+ * Parse Lux Studio flag overrides from URL query params.
  */
 function getLuxFlagOverrides(): Record<string, string> | undefined {
   if (typeof window === 'undefined') return undefined
@@ -32,24 +45,37 @@ function getLuxFlagOverrides(): Record<string, string> | undefined {
   return undefined
 }
 
+/** Check if we're in Lux Studio preview mode (have flag overrides in URL) */
+function isLuxPreviewMode(): boolean {
+  return getLuxFlagOverrides() !== undefined
+}
+
 export function PostHogProvider({ children }: { children: React.ReactNode }) {
   const initialized = useRef(false)
   const searchParams = useSearchParams()
 
-  // Initialize PostHog once
+  // Initialize PostHog - use a dummy key for preview mode if no real key
   useEffect(() => {
-    if (!POSTHOG_KEY || initialized.current) {
-      if (!POSTHOG_KEY) {
-        console.log('[PostHog] No API key configured, skipping initialization')
-      }
+    if (initialized.current) return
+
+    const hasOverrides = isLuxPreviewMode()
+    // Use real key if available, otherwise use dummy key for preview mode only
+    // The dummy key 'phc_lux_preview_mode' is NOT a real PostHog key - it just
+    // allows the PostHog SDK to initialize so flag overrides work locally
+    const keyToUse = POSTHOG_KEY || (hasOverrides ? 'phc_lux_preview_mode' : null)
+
+    if (!keyToUse) {
+      console.log('[PostHog] No API key configured and not in preview mode, skipping initialization')
       return
     }
 
-    posthog.init(POSTHOG_KEY, {
+    posthog.init(keyToUse, {
       api_host: POSTHOG_HOST,
       persistence: 'localStorage',
       capture_pageview: false, // We capture manually for better control
-      capture_pageleave: true,
+      capture_pageleave: !hasOverrides, // Don't capture in preview mode without real key
+      autocapture: POSTHOG_KEY ? true : false, // Disable autocapture without real key
+      disable_session_recording: !POSTHOG_KEY, // Disable recording without real key
       loaded: (ph) => {
         // Register lux properties with all events for filtering
         const props: Record<string, string> = {}
@@ -65,25 +91,32 @@ export function PostHogProvider({ children }: { children: React.ReactNode }) {
   }, [])
 
   // Apply Lux Studio flag overrides whenever URL changes
-  // This uses posthog.featureFlags.override() which works even after init
+  // Uses posthog.featureFlags.overrideFeatureFlags() - the correct API
   useEffect(() => {
-    if (!POSTHOG_KEY) return
+    // Only skip if PostHog not initialized at all
+    if (!initialized.current && !POSTHOG_KEY && !isLuxPreviewMode()) return
 
     const flagOverrides = getLuxFlagOverrides()
-    if (flagOverrides) {
-      // Override feature flags for Lux Studio preview
-      posthog.featureFlags.override(flagOverrides)
+
+    if (flagOverrides && Object.keys(flagOverrides).length > 0) {
+      // IMPORTANT: overrideFeatureFlags expects { flags: { [key]: value } }
+      posthog.featureFlags.overrideFeatureFlags({
+        flags: flagOverrides,
+      })
       console.log('[PostHog] Applied Lux Studio flag overrides:', flagOverrides)
 
       // Force reload to make React hooks aware of the change
       posthog.reloadFeatureFlags()
-    } else {
+    } else if (initialized.current) {
       // Clear any previous overrides when not in preview mode
-      posthog.featureFlags.override(false)
+      posthog.featureFlags.overrideFeatureFlags({ flags: {} })
     }
   }, [searchParams])
 
-  if (!POSTHOG_KEY) {
+  // Always use PHProvider if we're initialized (either with real key or preview mode)
+  const shouldUsePHProvider = POSTHOG_KEY || isLuxPreviewMode()
+
+  if (!shouldUsePHProvider) {
     return <>{children}</>
   }
 

package/templates/interface-boilerplate/lib/knowledge.ts

@@ -0,0 +1,404 @@
+/**
+ * Lux Knowledge Upload Library
+ *
+ * UI-agnostic utilities for uploading files to your project's knowledge bucket.
+ * Uses presigned URLs for efficient large file support without base64 encoding.
+ *
+ * @example
+ * // Basic upload
+ * import { uploadToKnowledge } from '@/lib/knowledge';
+ *
+ * const result = await uploadToKnowledge(file);
+ * console.log('Uploaded to:', result.path);
+ *
+ * @example
+ * // Upload to specific folder
+ * const result = await uploadToKnowledge(file, {
+ *   folder: 'documents/invoices',
+ * });
+ *
+ * @example
+ * // Upload with landing zone (files go to 'uploads/' first)
+ * const knowledge = createKnowledgeUploader({
+ *   landingZone: 'uploads',
+ * });
+ * const result = await knowledge.upload(file);
+ *
+ * @example
+ * // Upload with progress tracking
+ * const result = await uploadToKnowledge(file, {
+ *   onProgress: (percent) => setProgress(percent),
+ * });
+ */
+
+// ============================================
+// Types
+// ============================================
+
+export interface UploadOptions {
+  /** Subfolder path within knowledge (e.g., 'documents/invoices') */
+  folder?: string;
+  /** Custom filename (defaults to original file name) */
+  filename?: string;
+  /** Override content type (defaults to file.type or 'application/octet-stream') */
+  contentType?: string;
+  /** Progress callback (0-100) */
+  onProgress?: (percent: number) => void;
+  /** Device ID for sync tracking */
+  deviceId?: string;
+}
+
+export interface UploadResult {
+  /** Whether the upload succeeded */
+  success: boolean;
+  /** Full path within knowledge bucket */
+  path: string;
+  /** File size in bytes */
+  size: number;
+  /** Any error message if failed */
+  error?: string;
+}
+
+export interface KnowledgeConfig {
+  /** API base URL (defaults to env or window config) */
+  apiUrl?: string;
+  /** API key for authentication */
+  apiKey?: string;
+  /** Project ID */
+  projectId?: string;
+  /** Default folder for all uploads */
+  landingZone?: string;
+  /** Device ID for sync tracking */
+  deviceId?: string;
+}
+
+// ============================================
+// Configuration
+// ============================================
+
+let globalConfig: KnowledgeConfig = {};
+
+/**
+ * Configure the knowledge uploader globally
+ */
+export function configureKnowledge(config: KnowledgeConfig): void {
+  globalConfig = { ...globalConfig, ...config };
+}
+
+/**
+ * Get API URL from config, window, or environment
+ */
+function getApiUrl(): string {
+  if (globalConfig.apiUrl) return globalConfig.apiUrl;
+
+  if (typeof window !== 'undefined') {
+    if ((window as any).__LUX_API_URL__) {
+      return (window as any).__LUX_API_URL__;
+    }
+    if ((window as any).__LUX_LOCAL_MODE__) {
+      return 'http://localhost:3001';
+    }
+  }
+
+  if (typeof process !== 'undefined' && process.env) {
+    return process.env.NEXT_PUBLIC_LUX_API_URL || process.env.LUX_API_URL || 'https://v2.uselux.ai';
+  }
+
+  return 'https://v2.uselux.ai';
+}
+
+/**
+ * Get API key from config, window, or environment
+ */
+function getApiKey(): string {
+  if (globalConfig.apiKey) return globalConfig.apiKey;
+
+  if (typeof window !== 'undefined' && (window as any).__LUX_API_KEY__) {
+    return (window as any).__LUX_API_KEY__;
+  }
+
+  if (typeof process !== 'undefined' && process.env) {
+    return process.env.NEXT_PUBLIC_LUX_API_KEY || process.env.LUX_API_KEY || '';
+  }
+
+  return '';
+}
+
+/**
+ * Get project ID from config, window, or environment
+ */
+function getProjectId(): string {
+  if (globalConfig.projectId) return globalConfig.projectId;
+
+  if (typeof window !== 'undefined' && (window as any).__LUX_PROJECT_ID__) {
+    return (window as any).__LUX_PROJECT_ID__;
+  }
+
+  if (typeof process !== 'undefined' && process.env) {
+    return process.env.NEXT_PUBLIC_LUX_PROJECT_ID || process.env.LUX_PROJECT_ID || '';
+  }
+
+  return '';
+}
+
+// ============================================
+// Core Upload Function
+// ============================================
+
+/**
+ * Upload a file to the knowledge bucket
+ *
+ * @param file - File or Blob to upload
+ * @param options - Upload options (folder, filename, progress callback)
+ * @returns Upload result with path and size
+ *
+ * @example
+ * const input = document.querySelector('input[type="file"]');
+ * const file = input.files[0];
+ * const result = await uploadToKnowledge(file, {
+ *   folder: 'user-uploads',
+ *   onProgress: (p) => console.log(`${p}% uploaded`),
+ * });
+ */
+export async function uploadToKnowledge(
+  file: File | Blob,
+  options: UploadOptions = {}
+): Promise<UploadResult> {
+  const apiUrl = getApiUrl();
+  const apiKey = getApiKey();
+  const projectId = getProjectId();
+
+  if (!projectId) {
+    return {
+      success: false,
+      path: '',
+      size: 0,
+      error: 'Project ID not configured. Set LUX_PROJECT_ID or configure globally.',
+    };
+  }
+
+  const filename = options.filename || (file instanceof File ? file.name : 'upload');
+  const contentType = options.contentType || file.type || 'application/octet-stream';
+  const folder = options.folder || globalConfig.landingZone;
+  const deviceId = options.deviceId || globalConfig.deviceId || 'web-upload';
+
+  try {
+    // Step 1: Get presigned upload URL
+    const urlResponse = await fetch(`${apiUrl}/api/projects/${projectId}/knowledge/upload-url`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Authorization': `Bearer ${apiKey}`,
+      },
+      body: JSON.stringify({
+        path: filename,
+        contentType,
+        folder,
+      }),
+    });
+
+    if (!urlResponse.ok) {
+      const error = await urlResponse.json().catch(() => ({ error: 'Failed to get upload URL' }));
+      return {
+        success: false,
+        path: '',
+        size: 0,
+        error: error.error || `Failed to get upload URL: ${urlResponse.status}`,
+      };
+    }
+
+    const { uploadUrl, path } = await urlResponse.json();
+
+    // Step 2: Upload directly to R2
+    if (options.onProgress) {
+      // Use XMLHttpRequest for progress tracking
+      await uploadWithProgress(uploadUrl, file, contentType, options.onProgress);
+    } else {
+      // Use fetch for simpler uploads
+      const uploadResponse = await fetch(uploadUrl, {
+        method: 'PUT',
+        headers: {
+          'Content-Type': contentType,
+        },
+        body: file,
+      });
+
+      if (!uploadResponse.ok) {
+        return {
+          success: false,
+          path: '',
+          size: 0,
+          error: `Upload failed: ${uploadResponse.status}`,
+        };
+      }
+    }
+
+    // Step 3: Confirm upload and trigger sync broadcast
+    const confirmResponse = await fetch(`${apiUrl}/api/projects/${projectId}/knowledge/confirm-upload`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Authorization': `Bearer ${apiKey}`,
+        'X-Device-Id': deviceId,
+      },
+      body: JSON.stringify({ path }),
+    });
+
+    if (!confirmResponse.ok) {
+      // Upload succeeded but confirmation failed - file is still there
+      console.warn('[knowledge] Upload succeeded but confirmation failed');
+    }
+
+    const result = await confirmResponse.json();
+
+    return {
+      success: true,
+      path,
+      size: result.size || file.size,
+    };
+  } catch (error: any) {
+    return {
+      success: false,
+      path: '',
+      size: 0,
+      error: error.message || 'Upload failed',
+    };
+  }
+}
+
+/**
+ * Upload with XMLHttpRequest for progress tracking
+ */
+function uploadWithProgress(
+  url: string,
+  file: File | Blob,
+  contentType: string,
+  onProgress: (percent: number) => void
+): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const xhr = new XMLHttpRequest();
+
+    xhr.upload.addEventListener('progress', (event) => {
+      if (event.lengthComputable) {
+        const percent = Math.round((event.loaded / event.total) * 100);
+        onProgress(percent);
+      }
+    });
+
+    xhr.addEventListener('load', () => {
+      if (xhr.status >= 200 && xhr.status < 300) {
+        onProgress(100);
+        resolve();
+      } else {
+        reject(new Error(`Upload failed: ${xhr.status}`));
+      }
+    });
+
+    xhr.addEventListener('error', () => {
+      reject(new Error('Upload failed: Network error'));
+    });
+
+    xhr.open('PUT', url);
+    xhr.setRequestHeader('Content-Type', contentType);
+    xhr.send(file);
+  });
+}
+
+// ============================================
+// Batch Upload
+// ============================================
+
+/**
+ * Upload multiple files to knowledge
+ *
+ * @param files - Array of files to upload
+ * @param options - Upload options applied to all files
+ * @returns Array of upload results
+ *
+ * @example
+ * const input = document.querySelector('input[type="file"][multiple]');
+ * const results = await uploadMultiple(Array.from(input.files), {
+ *   folder: 'batch-uploads',
+ * });
+ */
+export async function uploadMultiple(
+  files: (File | Blob)[],
+  options: UploadOptions = {}
+): Promise<UploadResult[]> {
+  const results: UploadResult[] = [];
+
+  for (const file of files) {
+    const result = await uploadToKnowledge(file, options);
+    results.push(result);
+  }
+
+  return results;
+}
+
+// ============================================
+// Factory Function
+// ============================================
+
+/**
+ * Create a configured knowledge uploader instance
+ *
+ * @param config - Configuration options
+ * @returns Uploader instance with bound config
+ *
+ * @example
+ * const knowledge = createKnowledgeUploader({
+ *   landingZone: 'user-uploads',
+ *   projectId: 'my-project-id',
+ * });
+ *
+ * // All uploads go to 'user-uploads/' folder
+ * await knowledge.upload(file);
+ * await knowledge.uploadMultiple(files);
+ */
+export function createKnowledgeUploader(config: KnowledgeConfig = {}) {
+  const mergedConfig = { ...globalConfig, ...config };
+
+  return {
+    /**
+     * Upload a single file
+     */
+    upload: (file: File | Blob, options: UploadOptions = {}) => {
+      const prevConfig = globalConfig;
+      globalConfig = mergedConfig;
+      const result = uploadToKnowledge(file, options);
+      globalConfig = prevConfig;
+      return result;
+    },
+
+    /**
+     * Upload multiple files
+     */
+    uploadMultiple: (files: (File | Blob)[], options: UploadOptions = {}) => {
+      const prevConfig = globalConfig;
+      globalConfig = mergedConfig;
+      const result = uploadMultiple(files, options);
+      globalConfig = prevConfig;
+      return result;
+    },
+
+    /**
+     * Update configuration
+     */
+    configure: (newConfig: Partial<KnowledgeConfig>) => {
+      Object.assign(mergedConfig, newConfig);
+    },
+  };
+}
+
+// ============================================
+// Convenience Exports
+// ============================================
+
+export const knowledge = {
+  upload: uploadToKnowledge,
+  uploadMultiple,
+  configure: configureKnowledge,
+  createUploader: createKnowledgeUploader,
+};
+
+export default knowledge;