analyzthis_design 2.5.1 → 2.6.0

package/dist/lib/orchestrator/run.js

@@ -30,6 +30,7 @@ const fs   = require('fs');
 const path = require('path');
 const os   = require('os');
 const https = require('https');
+const crypto = require('crypto');
 const session  = require('../session');
 const retrieve = require('../retrieve');
 const cache    = require('../cache');
@@ -40,7 +41,10 @@ const ranker = require('../ranker');
 const knowledge = require('../knowledge');
 const chunkRun = require('../chunk-run');
 const chunkModels = require('../chunk-models');
+const modelPolicy = require('../model-policy');
+const modelRegistry = require('../model-registry');
 const referencePack = require('../reference-pack');
+const outputQuality = require('../output-quality');
 const { callHostLlm, createRun, HostLlmPendingError, printDeviInstructions, findLatestRun, loadManifest: loadHostManifest } = require('../host-llm');
 const { resolveDefaultProvider, resolveTierProvider } = require('../provider');
 const synthesis = require('../synthesis');
@@ -229,7 +233,7 @@ function classifyEffort({ routing, digest, manifest, scopedMode, fullChain, isDe
  *   3. chain.tiers[manifest.tier]         (legacy fallback, v1.9)
  *   4. manifest.max_output_tokens         (last resort for the cap)
  */
-function resolveModel({ manifest, effort, chain, config, defaultProvider, defaultModel, gateName }) {
+function resolveModel({ manifest, effort, chain, config, defaultProvider, defaultModel, gateName, explicitProvider, explicitModel }) {
   let effKey = effort;
   const gateOverride = chain.gate_override;
   if (gateName && gateOverride && (gateOverride.applies_to || []).includes(gateName)) {
@@ -240,12 +244,35 @@ function resolveModel({ manifest, effort, chain, config, defaultProvider, defaul
   const matrix   = (chain.effort_matrix && chain.effort_matrix[effKey]) || {};
   const legacy   = (config.orchestrator?.tiers && config.orchestrator?.tiers[manifest.tier]) || {};
 
-  const provider = override.provider || matrix.provider || legacy.provider || defaultProvider;
-  const model    = override.model    || matrix.model    || legacy.model    || defaultModel;
+  let provider = override.provider || matrix.provider || legacy.provider || defaultProvider;
+  let model    = override.model    || matrix.model    || legacy.model    || defaultModel;
+  let requestedModel = explicitModel;
+  if (explicitProvider && !requestedModel) {
+    if (config.orchestrator?.provider === explicitProvider && config.orchestrator?.model) {
+      requestedModel = config.orchestrator.model;
+    } else if (explicitProvider === 'ollama') {
+      requestedModel = config.ollama?.model || 'qwen2.5';
+    } else {
+      const known = modelRegistry.MODELS.find((item) =>
+        item.provider === explicitProvider && (!item.effort || item.effort.includes(effKey)));
+      requestedModel = known?.model;
+    }
+  }
+  const policy = modelPolicy.resolveAssignment({
+    persona: manifest.id,
+    effort: effKey,
+    config,
+    explicitProvider,
+    explicitModel: requestedModel,
+  });
+  if (policy) {
+    provider = policy.spec.provider;
+    model = policy.spec.model;
+  }
   const resolvedProvider = resolveTierProvider(provider, defaultProvider);
   const maxTokens = override.max_output_tokens || matrix.max_output_tokens
     || config.orchestrator?.max_tokens?.[manifest.tier] || manifest.max_output_tokens;
-  return { provider: resolvedProvider, model, maxTokens, effort: effKey };
+  return { provider: resolvedProvider, model, maxTokens, effort: effKey, policy: policy && policy.source };
 }
 
 function ollamaJson(baseUrl, model, system, user, maxTokens) {
@@ -500,6 +527,7 @@ async function runUnchunked(opts = {}) {
     state = session.show({ project: init.projectId });
   }
   const projectId = state.project_id;
+  const runId = 'run-' + Date.now() + '-' + crypto.randomBytes(4).toString('hex');
 
   // Host LLM run directory (Devi bridge — no API keys)
   let hostContext = null;
@@ -554,6 +582,8 @@ async function runUnchunked(opts = {}) {
   session.update({
     project: projectId,
     patch: {
+      active_run: { id: runId, mode: 'unchunked', at: new Date().toISOString() },
+      persona_outputs: {},
       routing_decision: routing,
       figma_node: figma ? { url: figma, confirmed: false } : state.figma_node,
       mode: 'assess_only',
@@ -603,8 +633,13 @@ async function runUnchunked(opts = {}) {
   let cacheHits = 0;
   let costUsd = 0;
 
-  async function loadPersonaContext(personaId, { isProduceRound, isObjectionRound }) {
+  async function loadPersonaContext(personaId, { isProduceRound, isObjectionRound, gateName = null }) {
     const manifest = loadManifest(personaId);
+    const effectiveGateName = gateName || (
+      personaId === 'arjun' && dsAtRisk.length
+        ? 'ds_gate'
+        : null
+    );
     const useDeepWireframe = ideation_chain && wireframePersonas.has(personaId);
     const isReviewRound = isObjectionRound && !isProduceRound;
 
@@ -645,7 +680,9 @@ async function runUnchunked(opts = {}) {
     });
     const resolved = resolveModel({
       manifest, effort: isObjectionRound ? 'trivial' : effort, chain, config,
-      defaultProvider: provider, defaultModel: model, gateName: null,
+      defaultProvider: provider, defaultModel: model, gateName: effectiveGateName,
+      explicitProvider: opts.provider && opts.provider !== 'auto' ? opts.provider : (opts.model ? provider : null),
+      explicitModel: opts.model || null,
     });
 
     let finalSystem = system;
@@ -701,7 +738,12 @@ async function runUnchunked(opts = {}) {
     });
     const inTok = Math.ceil((system.length + user.length) / 4);
     const outTok = Math.ceil(text.length / 4);
-    const price = config.pricing && config.pricing[callOpts.model];
+    const actualModel = callOpts.provider === 'host' ? 'unknown' : callOpts.model;
+    const quality = outputQuality.validateOutput(text, {
+      persona: personaId,
+      outputFormat: 'persona_lite',
+    });
+    const price = callOpts.provider !== 'host' && config.pricing && config.pricing[callOpts.model];
     if (price) {
       costUsd += (inTok / 1e6) * (price.input_per_m || 0) + (outTok / 1e6) * (price.output_per_m || 0);
     }
@@ -712,10 +754,27 @@ async function runUnchunked(opts = {}) {
       output_tokens_est: outTok,
       structured_output: parseStructuredOutput(text, personaId),
       full_prompt: { system, user },
+      at: new Date().toISOString(),
+      run_id: runId,
+      attribution: {
+        provider: callOpts.provider,
+        model: actualModel,
+        model_id: callOpts.provider + '/' + actualModel,
+        effort: callOpts.effort || 'standard',
+        policy_version: modelPolicy.VERSION,
+        prompt_hash: modelPolicy.promptHash(personaId),
+        validator_version: outputQuality.VERSION,
+      },
+      quality: quality,
       effort_log_entry: {
         persona: personaId,
         effort: callOpts.effort || 'standard',
-        model: callOpts.model,
+        provider: callOpts.provider,
+        model: actualModel,
+        model_id: callOpts.provider + '/' + actualModel,
+        input_tokens: inTok,
+        output_tokens: outTok,
+        run_id: runId,
         scoped_mode: null,
       },
     };

package/dist/lib/outcome.js

@@ -118,7 +118,9 @@ function inferAllOutcomes(opts) {
           value: result.inferred,
           confidence: result.confidence,
           reason: result.reason,
-          at: new Date().toISOString()
+          at: new Date().toISOString(),
+          run_id: entry.run_id || null,
+          attribution: entry.attribution || null
         };
         session.update({ project: pid, patch: { outcome: outcomePatch } });
         inferred++;
@@ -143,6 +145,7 @@ function confirmOutcome(opts) {
 
   var state = session.show({ project: project });
   if (!state) throw new Error('No session found');
+  var output = state.persona_outputs && state.persona_outputs[persona];
 
   var outcomePatch = {
     inferred: { ...(state.outcome && state.outcome.inferred ? state.outcome.inferred : {}) },
@@ -150,7 +153,9 @@ function confirmOutcome(opts) {
   };
   outcomePatch.confirmed[persona] = {
     value: outcome,
-    at: new Date().toISOString()
+    at: new Date().toISOString(),
+    run_id: output && output.run_id || null,
+    attribution: output && output.attribution || null
   };
   delete outcomePatch.inferred[persona];
 

package/dist/lib/output-quality.js

@@ -0,0 +1,95 @@
+'use strict';
+
+/**
+ * Format-aware output validation shared by normal runs and calibration.
+ * Hard failures may trigger a bounded retry; warnings only affect quality score.
+ */
+
+var VERSION = 1;
+
+var PERSONA_FORBIDDEN = {
+  arjun: [/delight pass/i, /ARR impact/i],
+  meera: [/color contrast/i, /typography scale/i, /WCAG/i],
+  priya: [/delight moment/i, /north-star metric/i],
+  zara: [/--color-primary/i, /contrast ratio/i, /fix the token/i],
+};
+
+function issue(code, message, hard) {
+  return { code: code, message: message, hard: !!hard };
+}
+
+function validateOutput(text, opts) {
+  opts = opts || {};
+  text = typeof text === 'string' ? text.trim() : '';
+  var format = String(opts.outputFormat || opts.format || 'generic').toLowerCase();
+  var persona = String(opts.persona || '').toLowerCase();
+  var issues = [];
+
+  if (!text) issues.push(issue('empty', 'The model returned no text.', true));
+  if (text && text.length < 40) issues.push(issue('too_short', 'The answer is too short to evaluate.', true));
+
+  if (format === 'persona_lite' || format === 'lite') {
+    if (!/##\s*[A-Za-z]+(?:\s*[—-]\s*Lite)?/i.test(text)) {
+      issues.push(issue('missing_header', 'Missing persona output header.', false));
+    }
+    if (!/Top\s*2|fix|verdict|no delight needed/i.test(text)) {
+      issues.push(issue('missing_action', 'Missing an actionable finding or verdict.', true));
+    }
+  } else if (format === 'ux_audit') {
+    if (!/usab|access|hierarch|visual|UX/i.test(text)) {
+      issues.push(issue('missing_audit', 'UX audit has no UX or visual assessment.', true));
+    }
+    if (!/fix|recommend|change|keep|revise|ship|block/i.test(text)) {
+      issues.push(issue('missing_action', 'UX audit has no actionable conclusion.', true));
+    }
+  } else if (format === 'premise_assessment' || format === 'premise_check') {
+    if (!/premise|problem|assumption|framing|right problem/i.test(text)) {
+      issues.push(issue('missing_premise', 'Premise assessment does not examine the framing.', true));
+    }
+    if (!/proceed|change|reject|accept|revise|evidence/i.test(text)) {
+      issues.push(issue('missing_decision', 'Premise assessment has no decision or evidence request.', true));
+    }
+  } else if (format === 'synthesis') {
+    if (!/\b(SHIP|REVISE|BLOCK)\b/i.test(text)) {
+      issues.push(issue('missing_verdict', 'Synthesis has no SHIP, REVISE, or BLOCK verdict.', true));
+    }
+    if (!/top\s*3|action|next step|fix/i.test(text)) {
+      issues.push(issue('missing_actions', 'Synthesis has no next actions.', false));
+    }
+  }
+
+  var forbidden = PERSONA_FORBIDDEN[persona] || [];
+  for (var i = 0; i < forbidden.length; i++) {
+    if (forbidden[i].test(text)) {
+      issues.push(issue('forbidden_scope', 'The persona crossed into a forbidden scope.', true));
+    }
+  }
+
+  var hardFailures = issues.filter(function(item) { return item.hard; });
+  var warnings = issues.filter(function(item) { return !item.hard; });
+  var score = Math.max(0, 1 - hardFailures.length * 0.35 - warnings.length * 0.1);
+  return {
+    version: VERSION,
+    format: format,
+    pass: hardFailures.length === 0,
+    score: Number(score.toFixed(2)),
+    issues: issues,
+    hard_failures: hardFailures.length,
+    warnings: warnings.length,
+  };
+}
+
+function classifyError(error) {
+  var message = String(error && error.message ? error.message : error || '');
+  if (/429|rate.?limit|too many requests|quota/i.test(message)) return 'rate_limit';
+  if (/timeout|timed out|ECONNRESET|ENOTFOUND|network|socket/i.test(message)) return 'transport';
+  if (/401|403|unauthori|forbidden|api.?key/i.test(message)) return 'auth';
+  return 'provider';
+}
+
+module.exports = {
+  VERSION: VERSION,
+  PERSONA_FORBIDDEN: PERSONA_FORBIDDEN,
+  validateOutput: validateOutput,
+  classifyError: classifyError,
+};

package/dist/lib/reference-pack.js

@@ -37,6 +37,7 @@ var REFERENCE_MAP = {
     { file: 'ux-guidelines.csv', column: 'Category', limit: 3 },
     { file: 'ui-reasoning.csv', column: 'UI Category', limit: 3 },
     { file: 'charts.csv', column: 'Data Type', limit: 3 },
+    { file: 'ui-libraries.csv', column: 'Best For Tags', limit: 3 },
   ],
   zara: [
     { file: 'colors.csv', column: 'Product Type', limit: 3 },
@@ -44,6 +45,8 @@ var REFERENCE_MAP = {
     { file: 'styles.csv', column: 'Best For Tags', limit: 3 },
     { file: 'landing.csv', column: 'Keywords', limit: 3 },
     { file: 'icons.csv', column: 'Keywords', limit: 3 },
+    { file: 'motion.csv', column: 'Category', limit: 3 },
+    { file: 'ui-libraries.csv', column: 'Job', limit: 3 },
   ],
   meera: [
     { file: 'products.csv', column: 'Product Type', limit: 3 },
@@ -55,14 +58,17 @@ var REFERENCE_MAP = {
     { file: 'ui-reasoning.csv', column: 'UI Category', limit: 3 },
     { file: 'app-interface.csv', column: 'Keywords', limit: 3 },
     { file: 'icons.csv', column: 'Keywords', limit: 3 },
+    { file: 'ui-libraries.csv', column: 'Job', limit: 3 },
   ],
   anuj: [
     { file: 'ux-guidelines.csv', column: 'Category', limit: 3 },
     { file: 'app-interface.csv', column: 'Keywords', limit: 3 },
     { file: 'stacks/shadcn.csv', column: 'Category', limit: 3 },
+    { file: 'ui-libraries.csv', column: 'Job', limit: 3 },
   ],
   priya: [
     { file: 'react-performance.csv', column: 'Category', limit: 3 },
+    { file: 'ui-libraries.csv', column: 'Job', limit: 3 },
   ],
   raj: [
     { file: 'products.csv', column: 'Product Type', limit: 3 },
@@ -101,7 +107,9 @@ function getReferenceSpec(id, state) {
   if (!Array.isArray(specs)) specs = [specs];
   if (id === 'priya') {
     var stack = detectStack(state && state.vault_path);
-    if (stack) return [{ file: 'stacks/' + stack + '.csv', column: 'Category', limit: 3 }];
+    if (stack) {
+      return [{ file: 'stacks/' + stack + '.csv', column: 'Category', limit: 3 }].concat(specs);
+    }
   }
   return specs;
 }

package/dist/lib/session.js

@@ -49,6 +49,7 @@ function defaultState(projectId) {
     },
     information_hierarchy: { declared_by: 'undeclared', ranking: [] },
     routing_decision: { problem_type: '', experts: [], reason: '' },
+    active_run: null,
     persona_outputs: {},
     full_prompts: {},
     structured_outputs: {},
@@ -64,6 +65,13 @@ function defaultState(projectId) {
     },
     vault_path: '',
     last_collect_at: '',
+    installed_ui_libraries: {
+      installed: [],
+      missing_defaults: [],
+      full_kits: [],
+      mixed_kits: false,
+      folders: [],
+    },
     deliberation: {
       round: 0,
       max_rounds: 3,
@@ -214,11 +222,22 @@ function ensurePersonaOutput({ project, persona, text } = {}) {
   const outputs = { ...(state.persona_outputs || {}) };
   let created = false;
   if (!outputs[persona]) {
+    if (state.active_run && !text) {
+      return { projectId, state, created: false, stale: true };
+    }
+    const now = new Date().toISOString();
     outputs[persona] = {
       text: text || '(slash — designer marked this note; full text was in chat)',
-      at: new Date().toISOString(),
+      at: now,
       accepted: null,
       source: 'slash',
+      run_id: state.active_run?.id || `slash-${Date.now()}`,
+      attribution: {
+        provider: 'host',
+        model: 'unknown',
+        model_id: 'host/unknown',
+        effort: 'unknown',
+      },
     };
     created = true;
     state = update({ project: projectId, patch: { persona_outputs: outputs } });
@@ -233,7 +252,11 @@ function markAccepted({ project, persona, accepted = true } = {}) {
   if (!state || !state.persona_outputs || !state.persona_outputs[persona]) {
     return { updated: false, reason: `No output recorded for persona "${persona}" in this session yet.` };
   }
-  state.persona_outputs[persona].accepted = accepted;
+  const output = state.persona_outputs[persona];
+  if (state.active_run && output.run_id !== state.active_run.id) {
+    return { updated: false, reason: `The "${persona}" output is from an older run. Run the persona again before rating it.` };
+  }
+  output.accepted = accepted;
   const merged = update({ project: projectId, patch: { persona_outputs: state.persona_outputs } });
   return { updated: true, state: merged };
 }
@@ -246,8 +269,10 @@ function logHostTurn({ project, path: turnPath, persona, inferred_in, verdicts =
   const existing = show({ project: projectId }) || defaultState(projectId);
   const metrics = { ...(existing.metrics || {}) };
   const turns = Array.isArray(metrics.host_turns) ? metrics.host_turns.slice() : [];
+  const now = new Date().toISOString();
+  const runId = `host-${Date.now()}-${crypto.randomBytes(3).toString('hex')}`;
   turns.push({
-    at: new Date().toISOString(),
+    at: now,
     path: turnPath || 'mcp',
     persona: persona || '',
     inferred_in: Number(inferred_in) || 0,
@@ -259,7 +284,26 @@ function logHostTurn({ project, path: turnPath, persona, inferred_in, verdicts =
   const cliIn = metrics.input_tokens_est || 0;
   const v = metrics.verdicts_this_run || (metrics.experts_run && metrics.experts_run.length ? 1 : 0) || (metrics.host_turns.length ? 1 : 0);
   metrics.tokens_per_verdict = v && (host + cliIn) ? Math.round((host + cliIn) / v) : null;
-  return update({ project: projectId, patch: { metrics } });
+  const patch = { metrics };
+  if (persona && PERSONA_IDS.indexOf(persona) !== -1) {
+    patch.active_run = { id: runId, mode: 'host', at: now };
+    patch.persona_outputs = {
+      [persona]: {
+        text: '(host chat — full response remains in the IDE conversation)',
+        at: now,
+        accepted: null,
+        source: turnPath || 'mcp',
+        run_id: runId,
+        attribution: {
+          provider: 'host',
+          model: 'unknown',
+          model_id: 'host/unknown',
+          effort: 'unknown',
+        },
+      },
+    };
+  }
+  return update({ project: projectId, patch });
 }
 
 module.exports = {

package/dist/lib/system-prompt.js

@@ -32,8 +32,11 @@ function buildPrompt(opts) {
   lines.push('');
   lines.push('**CRITIQUE** — Review an existing screen. Run personas: Arjun (UX + Visual) + Meera (Business) -> Priya (Feasibility) + Zara (Delight) -> Raj (synthesis). Output: composite score, SHIP/REVISE/BLOCK verdict, top 3 fixes.');
   lines.push('');
+  lines.push('**DIRECTION** — Mood board (tagged URLs) or UI image board. For a UI board, Zara scouts 3-5 real shipped screens (never invent URLs, never generate AI comps). Arjun, Noor, Priya, Meera jury. She re-scouts if they skip (max 3 rounds).');
+  lines.push('');
   lines.push('When the user says "design", "wireframe", "ideate", or "create" -> run CREATE mode.');
   lines.push('When the user says "review", "critique", "audit", or "fix" -> run CRITIQUE mode.');
+  lines.push('When the user says "mood board", "UI board", "image board", or "visual direction" -> run DIRECTION mode.');
   lines.push('');
 
   lines.push('## Premise challenge (critical)');

package/dist/lib/ui-libraries.js

@@ -0,0 +1,232 @@
+'use strict';
+
+/**
+ * Detect installed motion / UX / visual-design libraries from package.json
+ * and copy-paste kit folders. Personas read Tech/Installed-UI-Libraries.md
+ * and session.installed_ui_libraries instead of guessing the stack.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const retrieve = require('./retrieve');
+
+const DEFAULT_BY_JOB = {
+  primitives: 'Shadcn UI',
+  motion: 'Motion',
+  icons: 'Lucide',
+};
+
+const FOLDER_CANDIDATES = [
+  'components/ui',
+  'src/components/ui',
+  'app/components/ui',
+  'components/magicui',
+  'src/components/magicui',
+  'components/aceternity',
+  'src/components/aceternity',
+];
+
+function catalogRows() {
+  try {
+    return retrieve.loadCsv('ui-libraries.csv').rows || [];
+  } catch {
+    return [];
+  }
+}
+
+function splitAliases(field) {
+  return String(field || '')
+    .split(';')
+    .map((s) => s.trim())
+    .filter(Boolean);
+}
+
+function npmMatches(depName, npmField) {
+  return splitAliases(npmField).some((alias) => {
+    if (alias.endsWith('/*')) {
+      const prefix = alias.slice(0, -1);
+      const pkg = alias.slice(0, -2);
+      return depName === pkg || depName.startsWith(prefix);
+    }
+    return depName === alias;
+  });
+}
+
+function readPackageDeps(cwd) {
+  const pkgPath = path.join(cwd, 'package.json');
+  if (!fs.existsSync(pkgPath)) return { deps: [], pkgPath: null };
+  try {
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+    const names = Object.keys({
+      ...(pkg.dependencies || {}),
+      ...(pkg.devDependencies || {}),
+    });
+    return { deps: names, pkgPath };
+  } catch {
+    return { deps: [], pkgPath };
+  }
+}
+
+function folderExists(cwd, rel) {
+  try {
+    return fs.statSync(path.join(cwd, rel)).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+function detectFolders(cwd) {
+  const found = [];
+  for (const rel of FOLDER_CANDIDATES) {
+    if (folderExists(cwd, rel)) found.push(rel);
+  }
+  return found;
+}
+
+function folderHitsRow(foundFolders, detectionFolders) {
+  const needles = splitAliases(detectionFolders).filter(Boolean);
+  if (!needles.length) return false;
+  return foundFolders.some((rel) =>
+    needles.some((n) => rel === n || rel.endsWith('/' + n) || rel.indexOf(n) !== -1));
+}
+
+/**
+ * @param {{ cwd: string }} opts
+ * @returns {{ installed: object[], missing_defaults: object[], folders: string[], full_kits: string[], mixed_kits: boolean }}
+ */
+function detectInstalledUiLibraries({ cwd } = {}) {
+  const root = path.resolve(cwd || process.cwd());
+  const { deps } = readPackageDeps(root);
+  const folders = detectFolders(root);
+  const rows = catalogRows();
+  const installed = [];
+  const seen = new Set();
+
+  for (const row of rows) {
+    const byNpm = deps.some((d) => npmMatches(d, row['Npm Names']));
+    const byFolder = folderHitsRow(folders, row['Detection Folders']);
+    if (!byNpm && !byFolder) continue;
+    const name = row.Library;
+    if (seen.has(name)) continue;
+    seen.add(name);
+    installed.push({
+      library: name,
+      job: row.Job,
+      persona: row.Persona,
+      import_example: row['Import Example'],
+      docs: row['Docs URL'],
+      do_not_use_for: row['Do Not Use For'],
+      bundle_hint: row['Bundle Hint'],
+      how: byNpm ? (byFolder ? 'package+folder' : 'package.json') : 'folder',
+    });
+  }
+
+  const jobsPresent = new Set(installed.map((i) => i.job));
+  const missing_defaults = [];
+  Object.keys(DEFAULT_BY_JOB).forEach((job) => {
+    if (jobsPresent.has(job)) return;
+    // full-kit covers primitives
+    if (job === 'primitives' && jobsPresent.has('full-kit')) return;
+    const libName = DEFAULT_BY_JOB[job];
+    const row = rows.find((r) => r.Library === libName);
+    missing_defaults.push({
+      job,
+      library: libName,
+      install: row ? row.Install : '',
+      docs: row ? row['Docs URL'] : '',
+    });
+  });
+
+  const full_kits = installed.filter((i) => i.job === 'full-kit').map((i) => i.library);
+  const hasShadcn = installed.some((i) => i.library === 'Shadcn UI' || i.library === 'Radix UI');
+  const mixed_kits = full_kits.length > 1 || (full_kits.length > 0 && hasShadcn);
+
+  return { installed, missing_defaults, folders, full_kits, mixed_kits };
+}
+
+function buildNoteMarkdown(detection) {
+  const date = new Date().toISOString().split('T')[0];
+  const installed = detection.installed || [];
+  const missing = detection.missing_defaults || [];
+  const lines = [
+    '---',
+    'title: Installed-UI-Libraries',
+    'tags: [tech, ui-libraries]',
+    'source: package.json',
+    'category: tech',
+    `collected_at: "${date}"`,
+    'enriched: true',
+    '---',
+    '',
+    '## Purpose',
+    'Libraries already in this repo that design personas must prefer. One library per job. Do not add a second full UI kit. Do not put marketing FX (Magic UI, Aceternity, 21st.dev, Lottie, Spline) on daily working dashboards.',
+    '',
+    '## Installed',
+  ];
+  if (!installed.length) {
+    lines.push('- _(none of the catalogued packages detected)_');
+  } else {
+    for (const i of installed) {
+      lines.push(`- **${i.library}** (${i.job}) via ${i.how} — \`${i.import_example}\``);
+    }
+  }
+  lines.push('', '## Missing defaults (optional — do not install unless the brief needs them)');
+  if (!missing.length) {
+    lines.push('- All default jobs covered.');
+  } else {
+    for (const m of missing) {
+      lines.push(`- **${m.job}:** ${m.library} — \`${m.install}\``);
+    }
+  }
+  lines.push('', '## Kit rule');
+  if (detection.mixed_kits) {
+    lines.push('- **BLOCK mix:** more than one full kit (or a full kit plus Shadcn) is present. Priya: do not add more. Use the incumbent kit.');
+  } else if (detection.full_kits && detection.full_kits.length) {
+    lines.push(`- Incumbent full kit: **${detection.full_kits.join(', ')}**. Prescribe this kit's components; do not start a Shadcn tree.`);
+  } else {
+    lines.push('- No full kit detected. Shadcn + Radix is the greenfield default for Tailwind apps.');
+  }
+  lines.push('', '## Folders found');
+  if (!(detection.folders || []).length) {
+    lines.push('- _(none)_');
+  } else {
+    for (const f of detection.folders) lines.push(`- \`${f}\``);
+  }
+  lines.push('');
+  return lines.join('\n');
+}
+
+function writeInstalledUiLibrariesNote({ vaultPath, detection, dryRun }) {
+  const md = buildNoteMarkdown(detection);
+  const rel = path.join('Tech', 'Installed-UI-Libraries.md');
+  if (dryRun || !vaultPath) {
+    return { vaultRel: rel, written: false, markdown: md };
+  }
+  const destDir = path.join(vaultPath, 'Tech');
+  fs.mkdirSync(destDir, { recursive: true });
+  const dest = path.join(destDir, 'Installed-UI-Libraries.md');
+  fs.writeFileSync(dest, md);
+  return { vaultRel: rel, written: true, markdown: md, dest };
+}
+
+function sessionPayload(detection) {
+  return {
+    installed: (detection.installed || []).map((i) => ({
+      library: i.library,
+      job: i.job,
+      how: i.how,
+    })),
+    missing_defaults: detection.missing_defaults || [],
+    full_kits: detection.full_kits || [],
+    mixed_kits: !!detection.mixed_kits,
+    folders: detection.folders || [],
+  };
+}
+
+module.exports = {
+  detectInstalledUiLibraries,
+  writeInstalledUiLibrariesNote,
+  buildNoteMarkdown,
+  sessionPayload,
+  DEFAULT_BY_JOB,
+};