quorum-ux 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jason Shearer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,196 @@
+# QuorumUX
+
+**Multi-model consensus UX analysis from E2E test artifacts.**
+
+QuorumUX sends your Playwright screenshots and video recordings to multiple AI vision models, then synthesizes their findings into a single prioritized report with consensus-weighted severity. Issues flagged by 2+ models are high confidence. Video analysis catches temporal friction (hesitation, confusion, loading delays) that screenshots miss.
+
+## How It Works
+
+<div align="center">
+
+![QuorumUX Pipeline Diagram](docs/pipeline.svg)
+
+</div>
+
+## What Makes This Different
+
+Most visual testing tools compare pixels. QuorumUX asks AI models to think like UX researchers.
+
+- **Multi-model consensus** — 3 models analyze independently, a 4th synthesizes. Issues flagged by 2+ models are high confidence. Single-model findings need human review. Disagreements are surfaced explicitly.
+- **Video temporal analysis** — Gemini watches your screen recordings and identifies hesitation (cursor pauses), confusion (backtracking), interaction patterns (rage clicks), and loading delays. This catches friction invisible to static screenshots.
+- **Persona-aware context** — Feed your test runner's persona summaries (pass/fail/friction counts, known issues) into the analysis. Models evaluate against user intent, not just visual state.
+- **Severity synthesis** — Opus weighs evidence from all sources (3 screenshot models + video + test results) and assigns P0/P1/P2 severity with effort estimates.
+- **$3-5 per full run** — 10 personas × 3 models + video + synthesis costs pennies via OpenRouter.
+
+## Quickstart
+
+```bash
+# Install
+npm install quorum-ux
+
+# Interactive setup — walks you through API key, personas, and model selection
+npx quorumux init
+
+# Preview what the pipeline will do and estimated cost
+npx quorumux --dry-run
+
+# Run the full pipeline
+npx quorumux
+```
+
+Or configure manually:
+
+```bash
+cat > quorumux.config.ts << 'EOF'
+import type { QuorumUXConfig } from 'quorum-ux';
+
+const config: QuorumUXConfig = {
+  name: 'MyApp',
+  description: 'A project management tool for distributed teams',
+  domain: 'productivity',
+  appUrl: 'https://myapp.com',
+  userJourney: 'Signup → Create Project → Invite Team → Assign Tasks → Daily Standup',
+  artifactsDir: './test-artifacts',
+  models: {
+    screenshot: [
+      { id: 'anthropic/claude-sonnet-4.6', name: 'claude' },
+      { id: 'google/gemini-2.0-flash-001', name: 'gemini' },
+      { id: 'openai/gpt-4o-2024-11-20', name: 'gpt4o' },
+    ],
+    video: { id: 'google/gemini-2.0-flash-001', name: 'gemini' },
+    synthesis: { id: 'anthropic/claude-opus-4.5', name: 'opus' },
+  },
+};
+
+export default config;
+EOF
+
+OPENROUTER_API_KEY=sk-or-... npx quorumux
+```
+
+## Prerequisites
+
+- **Node.js** >= 18
+- **OpenRouter API key** — [openrouter.ai/keys](https://openrouter.ai/keys)
+- **ffmpeg** — for video frame extraction (`brew install ffmpeg` / `apt install ffmpeg`)
+- **ImageMagick** — for screenshot grids (`brew install imagemagick` / `apt install imagemagick`)
+- **Test artifacts** — screenshots and/or video recordings from your E2E test runner (Playwright recommended)
+
+## Artifact Directory Structure
+
+QuorumUX expects your test runner to produce artifacts in this structure:
+
+```
+test-artifacts/
+└── run-2026-02-22T09-00/           # Timestamped run directory
+    ├── videos/
+    │   └── P01-maria/               # One subdir per persona
+    │       └── abc123.webm          # Playwright video recording
+    ├── screenshots/
+    │   └── P01-maria/
+    │       ├── P01-maria-step01-PASS-login.png
+    │       ├── P01-maria-step02-PASS-signup.png
+    │       └── P01-maria-step03-FRICTION-onboarding.png
+    ├── summaries/
+    │   └── P01-maria-summary.json   # Test runner's structured results
+    └── executive-summary.md          # Optional: test runner's summary
+```
+
+Naming conventions are flexible — QuorumUX discovers personas from subdirectory names.
+
+## CLI Reference
+
+```
+npx quorumux [command] [options]
+
+Commands:
+  init               Interactive project setup wizard
+  run [options]       Run the analysis pipeline (default)
+
+Options:
+  --config <path>      Path to quorumux.config.ts (default: ./quorumux.config.ts)
+  --run-dir <path>     Specific run directory (auto-detects latest run-*)
+  --start-stage <n>    Start from stage 1, 2, 3, or 4 (default: 1)
+  --skip-video         Skip Stage 2b video analysis
+  --dry-run            Show what would run without making API calls
+  --verbose            Verbose output
+  --help               Show help
+
+Environment:
+  OPENROUTER_API_KEY   API key for OpenRouter (preferred).
+                       Also reads from .env / .env.local or ~/.quorumux/config.json.
+```
+
+## Pipeline Stages
+
+| Stage | Input | Output | Models Used |
+|-------|-------|--------|-------------|
+| **1: Extract** | videos/, screenshots/ | frames/, grids/ | None (ffmpeg + ImageMagick) |
+| **2: Analyze Screenshots** | grids/, summaries/ | all-analyses-raw.json | All `config.models.screenshot` |
+| **2b: Analyze Video** | videos/, summaries/ | all-video-analyses-raw.json | `config.models.video` |
+| **3: Synthesize** | All Stage 2/2b output + summaries + exec summary | synthesis.json | `config.models.synthesis` |
+| **4: Report** | synthesis.json | ux-analysis-report.md, github-issues.md | None (templating) |
+
+Stages 2 and 2b run in parallel. You can start from any stage with `--start-stage`.
+
+## Persona Archetypes
+
+QuorumUX includes 10 built-in persona archetypes for universal UX testing. Select them during `quorumux init` or reference them in your config:
+
+| Archetype | Testing Focus | Device |
+|-----------|--------------|--------|
+| **Happy Path Hero** | Ideal journey, full completion | Desktop |
+| **Speed Runner** | Skip/rush behavior, task efficiency | Desktop |
+| **Cautious Explorer** | Reads everything, hesitates | Desktop |
+| **Mobile-First User** | Touch interactions, small viewport | Mobile |
+| **Accessibility User** | Screen reader, keyboard nav | Desktop |
+| **Distracted Multitasker** | Tab switching, mid-flow pauses | Desktop |
+| **Error-Prone Novice** | Wrong inputs, recovery paths | Desktop |
+| **Power User** | Keyboard shortcuts, advanced features | Desktop |
+| **Skeptical Evaluator** | Edge cases, competitor comparison | Desktop |
+| **International User** | i18n, locale, long text | Desktop |
+
+When persona IDs match an archetype, QuorumUX automatically injects behavioral context into the analysis prompts so models know what to look for.
+
+## Output: What You Get
+
+### ux-analysis-report.md
+
+- **Overall assessment**: UX score (1-10), launch readiness, strengths, critical path
+- **Consensus issues**: High-confidence findings from 2+ models, with video insight annotations
+- **Video-only issues**: Temporal friction invisible to screenshots (hesitation, loading, confusion)
+- **Model-unique issues**: Single-model findings that need human review
+- **Disagreements**: Where models actively contradict each other
+
+### github-issues.md
+
+Ready-to-paste `gh issue create` commands for every finding, with severity labels and structured descriptions.
+
+### synthesis.json
+
+Raw structured data for programmatic consumption or custom reporting.
+
+## Integrating with Your Test Runner
+
+QuorumUX is test-runner agnostic. It consumes artifacts, not test code. Any runner that produces screenshots and/or video works:
+
+- **Playwright** (recommended): Use `recordVideo` on browser context + `page.screenshot()` at checkpoints
+- **Cypress**: Use `cy.screenshot()` + video recording config
+- **Puppeteer**: Use `page.screenshot()` + screen recording via Chrome DevTools Protocol
+
+The optional `summaries/*.json` files give QuorumUX additional context (pass/fail counts, known issues) but aren't required. Without them, analysis is purely visual.
+
+## Cost
+
+Typical cost for a 10-persona run via OpenRouter:
+
+| Stage | Models | ~Cost |
+|-------|--------|-------|
+| Screenshots | 3 models × 10 personas | ~$1.50 |
+| Video | Gemini × 10-12 videos | ~$0.50 |
+| Synthesis | Opus × 1 call (~60K tokens) | ~$1.50 |
+| **Total** | | **~$3.50** |
+
+## License
+
+MIT

package/dist/commands/init.d.ts

@@ -0,0 +1,7 @@
+/**
+ * `quorumux init` — Interactive Project Setup Wizard
+ *
+ * Walks the user through configuring a new project and generates quorumux.config.ts.
+ */
+export declare function runInit(): Promise<void>;
+//# sourceMappingURL=init.d.ts.map

package/dist/commands/init.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../src/commands/init.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAkEH,wBAAsB,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAgE7C"}

package/dist/commands/init.js

@@ -0,0 +1,223 @@
+/**
+ * `quorumux init` — Interactive Project Setup Wizard
+ *
+ * Walks the user through configuring a new project and generates quorumux.config.ts.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { ask, select, confirm, closePrompt } from '../utils/prompt';
+import { resolveApiKey, loadGlobalConfig, saveGlobalConfig } from '../config/global';
+import { PERSONA_BUNDLES, getArchetypeSubset } from '../personas';
+const DOMAINS = [
+    { label: 'Career Tech', value: 'career-tech' },
+    { label: 'Fintech', value: 'fintech' },
+    { label: 'Healthcare', value: 'healthcare' },
+    { label: 'E-commerce', value: 'e-commerce' },
+    { label: 'SaaS', value: 'saas' },
+    { label: 'Social', value: 'social' },
+    { label: 'Education', value: 'education' },
+    { label: 'Other', value: 'other' },
+];
+const TESTING_DEPTHS = [
+    {
+        label: 'Fast (~$1)',
+        value: 'fast',
+        description: '1 screenshot model, no video, Gemini synthesis',
+        models: {
+            screenshot: [{ id: 'google/gemini-2.0-flash-001', name: 'gemini' }],
+            video: { id: 'google/gemini-2.0-flash-001', name: 'gemini' },
+            synthesis: { id: 'google/gemini-2.0-flash-001', name: 'gemini' },
+        },
+    },
+    {
+        label: 'Balanced (~$4)',
+        value: 'balanced',
+        description: '3 screenshot models, video, Opus synthesis (recommended)',
+        models: {
+            screenshot: [
+                { id: 'anthropic/claude-sonnet-4.6', name: 'claude' },
+                { id: 'google/gemini-2.0-flash-001', name: 'gemini' },
+                { id: 'openai/gpt-4o-2024-11-20', name: 'gpt4o' },
+            ],
+            video: { id: 'google/gemini-2.0-flash-001', name: 'gemini' },
+            synthesis: { id: 'anthropic/claude-opus-4.5', name: 'opus' },
+        },
+    },
+    {
+        label: 'Thorough (~$8)',
+        value: 'thorough',
+        description: '3 screenshot models (high token limits), video, Opus synthesis with extended analysis',
+        models: {
+            screenshot: [
+                { id: 'anthropic/claude-sonnet-4.6', name: 'claude', maxTokens: 5000 },
+                { id: 'google/gemini-2.0-flash-001', name: 'gemini', maxTokens: 5000 },
+                { id: 'openai/gpt-4o-2024-11-20', name: 'gpt4o', maxTokens: 5000 },
+            ],
+            video: { id: 'google/gemini-2.0-flash-001', name: 'gemini', maxTokens: 6000 },
+            synthesis: { id: 'anthropic/claude-opus-4.5', name: 'opus', maxTokens: 12000 },
+        },
+    },
+];
+export async function runInit() {
+    console.log('\n  QuorumUX — Project Setup\n');
+    try {
+        // Step 1: API Key
+        const apiKey = await resolveApiKeyStep();
+        // Step 2: Project Basics
+        const name = await ask('Project name');
+        const description = await ask('One-line description');
+        const domain = await select('What domain is your app in?', [...DOMAINS]);
+        const appUrl = await ask('App URL (e.g. https://myapp.com)');
+        // Step 3: User Journey
+        const userJourney = await ask('Describe the primary user flow to test');
+        // Step 4: Personas
+        const personaIds = await selectPersonas();
+        // Step 5: Testing Depth
+        const depth = await select('Testing depth?', TESTING_DEPTHS);
+        const models = TESTING_DEPTHS.find((d) => d.value === depth).models;
+        // Step 6: Artifacts Directory
+        const artifactsDir = await ask('Artifacts directory', './test-artifacts');
+        // Step 7: Skip video?
+        const skipVideo = depth === 'fast';
+        // Generate config file
+        const configContent = generateConfig({
+            name,
+            description,
+            domain,
+            appUrl,
+            userJourney,
+            artifactsDir,
+            models,
+            personaIds,
+            skipVideo,
+        });
+        const configPath = path.join(process.cwd(), 'quorumux.config.ts');
+        if (fs.existsSync(configPath)) {
+            const overwrite = await confirm('quorumux.config.ts already exists. Overwrite?', false);
+            if (!overwrite) {
+                console.log('\n  Aborted. Existing config preserved.\n');
+                return;
+            }
+        }
+        fs.writeFileSync(configPath, configContent);
+        console.log('\n  Config written to quorumux.config.ts');
+        console.log(`  Selected ${personaIds.length} persona archetype(s): ${personaIds.join(', ')}`);
+        console.log(`  Testing depth: ${depth}`);
+        console.log(`\n  Next steps:`);
+        console.log(`    1. Place test artifacts in ${artifactsDir}/`);
+        console.log(`    2. Run: npx quorumux --dry-run`);
+        console.log(`    3. Run: npx quorumux\n`);
+    }
+    finally {
+        closePrompt();
+    }
+}
+async function resolveApiKeyStep() {
+    const existing = resolveApiKey();
+    if (existing) {
+        console.log('  API key found.\n');
+        return existing;
+    }
+    console.log('  No OpenRouter API key found.\n');
+    console.log('  Get one at: https://openrouter.ai/keys\n');
+    const key = await ask('Enter your OpenRouter API key');
+    if (!key) {
+        console.log('\n  No key provided. You can set OPENROUTER_API_KEY later.\n');
+        return '';
+    }
+    const saveChoice = await select('Where should the key be stored?', [
+        {
+            label: 'Global config (~/.quorumux/config.json)',
+            value: 'global',
+            description: 'Convenient but stored in plaintext',
+        },
+        {
+            label: 'Show env var command (recommended)',
+            value: 'env',
+            description: 'More secure, add to your shell profile',
+        },
+    ]);
+    if (saveChoice === 'global') {
+        const config = loadGlobalConfig();
+        config.apiKey = key;
+        saveGlobalConfig(config);
+        process.env.OPENROUTER_API_KEY = key;
+        console.log('\n  Saved to ~/.quorumux/config.json\n');
+    }
+    else {
+        console.log(`\n  Add this to your shell profile (.zshrc, .bashrc, etc.):`);
+        console.log(`    export OPENROUTER_API_KEY="${key}"\n`);
+        process.env.OPENROUTER_API_KEY = key;
+    }
+    return key;
+}
+async function selectPersonas() {
+    const bundle = await select('Which persona set?', [
+        { label: 'Quick (3)', value: 'quick', description: 'happy-path, mobile-first, accessibility' },
+        { label: 'Standard (5)', value: 'standard', description: '+ speed-runner, novice' },
+        {
+            label: 'Comprehensive (8)',
+            value: 'comprehensive',
+            description: '+ cautious-explorer, power-user, skeptic',
+        },
+        { label: 'Full (10)', value: 'full', description: 'All archetypes' },
+    ]);
+    // "Custom" would be handled via the "Other" auto-option in a real interactive UI,
+    // but for now bundles cover the main use cases
+    const ids = PERSONA_BUNDLES[bundle];
+    // Validate they all exist
+    getArchetypeSubset([...ids]);
+    return [...ids];
+}
+function generateConfig(input) {
+    const modelSpecToString = (spec, indent) => {
+        const parts = [`id: '${spec.id}'`, `name: '${spec.name}'`];
+        if (spec.maxTokens)
+            parts.push(`maxTokens: ${spec.maxTokens}`);
+        return `${indent}{ ${parts.join(', ')} }`;
+    };
+    const screenshotModels = input.models.screenshot
+        .map((m) => modelSpecToString(m, '      '))
+        .join(',\n');
+    const videoModel = modelSpecToString(input.models.video, '    ');
+    const synthesisModel = modelSpecToString(input.models.synthesis, '    ');
+    const personaArray = input.personaIds.map((id) => `'${id}'`).join(', ');
+    return `import type { QuorumUXConfig } from './src/types';
+
+/**
+ * ${input.name} — QuorumUX Configuration
+ *
+ * Generated by \`quorumux init\`
+ */
+const config: QuorumUXConfig = {
+  name: '${escapeStr(input.name)}',
+  description: '${escapeStr(input.description)}',
+  domain: '${escapeStr(input.domain)}',
+  appUrl: '${escapeStr(input.appUrl)}',
+  userJourney: '${escapeStr(input.userJourney)}',
+  artifactsDir: '${escapeStr(input.artifactsDir)}',
+
+  /** Persona archetypes selected during init */
+  personas: [${personaArray}],
+
+  models: {
+    screenshot: [
+${screenshotModels},
+    ],
+    video: ${videoModel},
+    synthesis: ${synthesisModel},
+  },
+
+  video: {
+    maxSizeMB: 20,
+    frameRate: 1,
+  },
+};
+
+export default config;
+`;
+}
+function escapeStr(s) {
+    return s.replace(/\\/g, '\\\\').replace(/'/g, "\\'");
+}
+//# sourceMappingURL=init.js.map

package/dist/commands/init.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"init.js","sourceRoot":"","sources":["../../src/commands/init.ts"],"names":[],"mappings":"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"}

package/dist/config/global.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Global Config Management (~/.quorumux/config.json)
+ *
+ * Handles global settings that persist across projects:
+ * - API key storage (env var preferred, global config as fallback)
+ * - Default model configuration
+ */
+import { GlobalConfig } from '../types';
+/** Load global config from ~/.quorumux/config.json. Returns empty config if not found. */
+export declare function loadGlobalConfig(): GlobalConfig;
+/** Save global config to ~/.quorumux/config.json. Creates ~/.quorumux/ if needed. */
+export declare function saveGlobalConfig(config: GlobalConfig): void;
+/**
+ * Resolve API key using the priority chain:
+ * 1. OPENROUTER_API_KEY env var
+ * 2. .env / .env.local in project dir
+ * 3. ~/.quorumux/config.json → apiKey
+ *
+ * Returns the key or undefined if not found anywhere.
+ */
+export declare function resolveApiKey(): string | undefined;
+//# sourceMappingURL=global.d.ts.map

package/dist/config/global.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"global.d.ts","sourceRoot":"","sources":["../../src/config/global.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAKxC,0FAA0F;AAC1F,wBAAgB,gBAAgB,IAAI,YAAY,CAW/C;AAED,qFAAqF;AACrF,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,YAAY,GAAG,IAAI,CAK3D;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,IAAI,MAAM,GAAG,SAAS,CAqBlD"}

package/dist/config/global.js

@@ -0,0 +1,87 @@
+/**
+ * Global Config Management (~/.quorumux/config.json)
+ *
+ * Handles global settings that persist across projects:
+ * - API key storage (env var preferred, global config as fallback)
+ * - Default model configuration
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+const QUORUMUX_DIR = path.join(process.env.HOME || '~', '.quorumux');
+const CONFIG_PATH = path.join(QUORUMUX_DIR, 'config.json');
+/** Load global config from ~/.quorumux/config.json. Returns empty config if not found. */
+export function loadGlobalConfig() {
+    if (!fs.existsSync(CONFIG_PATH)) {
+        return {};
+    }
+    try {
+        const raw = fs.readFileSync(CONFIG_PATH, 'utf-8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return {};
+    }
+}
+/** Save global config to ~/.quorumux/config.json. Creates ~/.quorumux/ if needed. */
+export function saveGlobalConfig(config) {
+    if (!fs.existsSync(QUORUMUX_DIR)) {
+        fs.mkdirSync(QUORUMUX_DIR, { recursive: true });
+    }
+    fs.writeFileSync(CONFIG_PATH, JSON.stringify(config, null, 2) + '\n');
+}
+/**
+ * Resolve API key using the priority chain:
+ * 1. OPENROUTER_API_KEY env var
+ * 2. .env / .env.local in project dir
+ * 3. ~/.quorumux/config.json → apiKey
+ *
+ * Returns the key or undefined if not found anywhere.
+ */
+export function resolveApiKey() {
+    // 1. Env var (highest priority)
+    if (process.env.OPENROUTER_API_KEY) {
+        return process.env.OPENROUTER_API_KEY;
+    }
+    // 2. .env / .env.local in cwd
+    const envKey = readEnvFile('.env.local') || readEnvFile('.env');
+    if (envKey) {
+        process.env.OPENROUTER_API_KEY = envKey;
+        return envKey;
+    }
+    // 3. Global config
+    const globalConfig = loadGlobalConfig();
+    if (globalConfig.apiKey) {
+        process.env.OPENROUTER_API_KEY = globalConfig.apiKey;
+        return globalConfig.apiKey;
+    }
+    return undefined;
+}
+/** Read OPENROUTER_API_KEY from a dotenv file (simple parser, no deps) */
+function readEnvFile(filename) {
+    const filePath = path.join(process.cwd(), filename);
+    if (!fs.existsSync(filePath))
+        return undefined;
+    try {
+        const content = fs.readFileSync(filePath, 'utf-8');
+        for (const line of content.split('\n')) {
+            const trimmed = line.trim();
+            if (trimmed.startsWith('#') || !trimmed.includes('='))
+                continue;
+            const eqIndex = trimmed.indexOf('=');
+            const key = trimmed.slice(0, eqIndex).trim();
+            if (key === 'OPENROUTER_API_KEY') {
+                let value = trimmed.slice(eqIndex + 1).trim();
+                // Strip surrounding quotes
+                if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+                    value = value.slice(1, -1);
+                }
+                return value || undefined;
+            }
+        }
+    }
+    catch {
+        // Ignore read errors
+    }
+    return undefined;
+}
+//# sourceMappingURL=global.js.map

package/dist/config/global.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"global.js","sourceRoot":"","sources":["../../src/config/global.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+/**
+ * QuorumUX CLI — Entry Point
+ *
+ * Subcommands:
+ *   init        Interactive project setup wizard
+ *   run [opts]  Run the analysis pipeline (default)
+ *   --help      Show help
+ *
+ * Orchestrates the 4-stage UX analysis pipeline:
+ * Stage 1: Extract frames and generate grids from videos
+ * Stage 2: Analyze screenshots with multiple AI models
+ * Stage 2b: Analyze videos for temporal insights (parallel with Stage 2)
+ * Stage 3: Synthesize analyses across models and test data
+ * Stage 4: Generate reports and GitHub issues
+ */
+export type { QuorumUXConfig, ModelConfig, ModelSpec, VideoConfig, PersonaArchetype } from './types';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;GAcG;AAQH,YAAY,EAAE,cAAc,EAAE,WAAW,EAAE,SAAS,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC"}