analyzthis_design 2.0.0 → 2.1.0

package/dist/lib/reference-pack.js

@@ -0,0 +1,221 @@
+'use strict';
+
+/**
+ * Reference pack builder (v2.0).
+ *
+ * Extracted from lib/orchestrator/run.js so both the chunked path
+ * (chunk-executor) and the legacy unchunked path can share the same
+ * CSV + vault retrieval pipeline.
+ *
+ * Builds a ranked, citation-ready reference pack for one persona:
+ *   1. Query expansion (LLM, cached) → broadened keywords
+ *   2. CSV retrieve (file I/O, cached by mtime) → filtered rows
+ *   3. Knowledge-bank slice read (cached) → per-persona vault notes
+ *   4. LLM ranker → top-5 citations
+ *
+ * Falls back to static keywords + unranked rows on any error.
+ *
+ * CommonJS, 'use strict', var.
+ */
+
+var fs = require('fs');
+var path = require('path');
+var retrieve = require('./retrieve');
+var knowledge = require('./knowledge');
+var queryExpander = require('./query-expander');
+var ranker = require('./ranker');
+
+var PRODUCT_KEYWORDS = [
+  'saas', 'b2b', 'b2c', 'dashboard', 'analytics', 'e-commerce', 'ecommerce',
+  'fintech', 'healthcare', 'crm', 'marketplace', 'admin', 'enterprise',
+  'consumer', 'mobile', 'productivity', 'social', 'education', 'finance',
+];
+
+var REFERENCE_MAP = {
+  arjun: [
+    { file: 'styles.csv', column: 'Best For Tags', limit: 3 },
+    { 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 },
+  ],
+  zara: [
+    { file: 'colors.csv', column: 'Product Type', limit: 3 },
+    { file: 'typography.csv', column: 'Best For Tags', limit: 3 },
+    { file: 'styles.csv', column: 'Best For Tags', limit: 3 },
+    { file: 'landing.csv', column: 'Keywords', limit: 3 },
+    { file: 'icons.csv', column: 'Keywords', limit: 3 },
+  ],
+  meera: [
+    { file: 'products.csv', column: 'Product Type', limit: 3 },
+    { file: 'ui-reasoning.csv', column: 'UI Category', limit: 3 },
+    { file: 'landing.csv', column: 'Keywords', limit: 3 },
+  ],
+  noor: [
+    { file: 'ux-guidelines.csv', column: 'Category', limit: 3 },
+    { file: 'ui-reasoning.csv', column: 'UI Category', limit: 3 },
+    { file: 'app-interface.csv', column: 'Keywords', limit: 3 },
+    { file: 'icons.csv', column: 'Keywords', 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 },
+  ],
+  priya: [
+    { file: 'react-performance.csv', column: 'Category', limit: 3 },
+  ],
+  raj: [
+    { file: 'products.csv', column: 'Product Type', limit: 3 },
+    { file: 'landing.csv', column: 'Keywords', limit: 3 },
+  ],
+};
+
+function extractKeywords(text) {
+  var lower = (text || '').toLowerCase();
+  return PRODUCT_KEYWORDS.filter(function(k) { return lower.indexOf(k) !== -1; });
+}
+
+function detectStack(vaultPath) {
+  if (!vaultPath || !fs.existsSync(path.join(vaultPath, 'Tech'))) return null;
+  var techNotes = fs.readdirSync(path.join(vaultPath, 'Tech')).map(function(f) { return f.toLowerCase(); });
+  // Check all 16 stacks. Order matters for disambiguation:
+  // nuxt-ui must be checked before nuxtjs (nuxt-ui notes may contain "nuxt")
+  // shadcn must be checked before react (shadcn notes may contain "react")
+  // react-native must be checked before react
+  // jetpack-compose must be checked before other android
+  var stacks = [
+    'nuxt-ui', 'nuxtjs', 'nextjs', 'shadcn', 'react-native', 'react',
+    'vue', 'angular', 'svelte', 'astro', 'html-tailwind',
+    'flutter', 'swiftui', 'jetpack-compose', 'laravel', 'threejs',
+  ];
+  for (var i = 0; i < stacks.length; i++) {
+    // Match if any tech note filename contains the stack name
+    if (techNotes.some(function(n) { return n.indexOf(stacks[i]) !== -1; })) return stacks[i];
+  }
+  return null;
+}
+
+function getReferenceSpec(id, state) {
+  var specs = REFERENCE_MAP[id];
+  if (!specs) return null;
+  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 }];
+  }
+  return specs;
+}
+
+/**
+ * Build a ranked reference pack for one persona.
+ *
+ * @param {string} id — persona id
+ * @param {string} task — task text
+ * @param {object} state — session state
+ * @param {function} [callLlmFn] — LLM caller (defaults to orchestrator.callLlm)
+ * @returns {Promise<{cacheHit: boolean, citations: string[]} | null>}
+ */
+async function buildReferencePack(id, task, state, callLlmFn) {
+  var specs = getReferenceSpec(id, state);
+  if (!specs || !specs.length) return null;
+
+  var keywords = extractKeywords(task);
+
+  if (!callLlmFn) {
+    try { callLlmFn = require('./orchestrator/run').callLlm; }
+    catch (e) { callLlmFn = null; }
+  }
+
+  if (callLlmFn) {
+    try {
+      var expanded = await queryExpander.expandQuery({
+        task: task, personaId: id,
+        callLlmFn: callLlmFn,
+        provider: 'host', model: 'devi',
+      });
+      if (expanded && expanded.terms && expanded.terms.length) {
+        keywords = expanded.terms;
+      }
+    } catch (e) { /* fall back to static keywords */ }
+  }
+
+  if (!keywords.length) return null;
+
+  // Pool rows from all specs (multi-file retrieval with shared ranker).
+  var pool = [];
+  var anyCacheHit = false;
+
+  for (var s = 0; s < specs.length; s++) {
+    var spec = specs[s];
+    try {
+      var result = retrieve.retrieve({
+        file: spec.file,
+        filters: [{ column: spec.column, anyOf: keywords }],
+        limit: 10,
+      });
+      if (result.cacheHit) anyCacheHit = true;
+      if (!result.rows.length) continue;
+
+      for (var i = 0; i < result.rows.length; i++) {
+        var row = result.rows[i];
+        pool.push({
+          type: 'reference',
+          source: spec.file,
+          row: row.__no,
+          content: row[spec.column] || '',
+        });
+      }
+    } catch (e) { /* file missing or unreadable — skip */ }
+  }
+
+  // Add knowledge-bank slice notes to the pool.
+  try {
+    var kbNotes = knowledge.getPersonaSliceForPrompt(state, id);
+    for (var j = 0; j < Math.min(kbNotes.length, 5); j++) {
+      pool.push({
+        type: 'knowledge',
+        source: kbNotes[j].title,
+        row: 0,
+        content: kbNotes[j].content.slice(0, 200),
+      });
+    }
+  } catch (e) { /* knowledge slices unavailable */ }
+
+  if (!pool.length) return null;
+
+  // Single ranker call across the merged pool (same cost as before, better coverage).
+  if (callLlmFn) {
+    try {
+      var ranked = await ranker.rankCandidates({
+        personaId: id,
+        task: task,
+        candidates: pool,
+        callLlmFn: callLlmFn,
+        provider: 'host', model: 'devi',
+      });
+      return {
+        cacheHit: anyCacheHit,
+        citations: ranked.ranked.slice(0, 5).map(function(c) {
+          return '[' + c.source + (c.row ? ', row ' + c.row : '') + ': "' + c.content + '"]';
+        }),
+      };
+    } catch (e) { /* fall back to unranked */ }
+  }
+
+  // Fallback: first 5 from pool, unranked.
+  return {
+    cacheHit: anyCacheHit,
+    citations: pool.slice(0, 5).map(function(c) {
+      return '[' + c.source + (c.row ? ', row ' + c.row : '') + ': "' + c.content + '"]';
+    }),
+  };
+}
+
+module.exports = {
+  buildReferencePack: buildReferencePack,
+  getReferenceSpec: getReferenceSpec,
+  extractKeywords: extractKeywords,
+  detectStack: detectStack,
+  REFERENCE_MAP: REFERENCE_MAP,
+  PRODUCT_KEYWORDS: PRODUCT_KEYWORDS,
+};

package/dist/lib/research.js

@@ -1,2 +1,144 @@
 #!/usr/bin/env node
-'use strict';const fs=require('fs'),path=require('path'),os=require('os'),https=require('https'),http=require('http'),{getProjectId,sessionDir}=require('./session'),CONFIG_FILE=path['join'](os['homedir'](),'.analyzthis_design','config.json');function loadConfig(){if(!fs['existsSync'](CONFIG_FILE))return{};try{return JSON['parse'](fs['readFileSync'](CONFIG_FILE,'utf8'));}catch{return{};}}function htmlToText(a){return a['replace'](/<script[\s\S]*?<\/script>/gi,'')['replace'](/<style[\s\S]*?<\/style>/gi,'')['replace'](/<[^>]+>/g,'\x20')['replace'](/&nbsp;/g,'\x20')['replace'](/&amp;/g,'&')['replace'](/&lt;/g,'<')['replace'](/&gt;/g,'>')['replace'](/&quot;/g,'\x22')['replace'](/\s+/g,'\x20')['trim']();}function fetchUrl(a,b=0x5){return new Promise((c,d)=>{const e=a['startsWith']('https')?https:http,f=e['get'](a,{'headers':{'User-Agent':'analyzthis_design/1.8'},'timeout':0x3a98},g=>{if([0x12d,0x12e,0x133,0x134]['includes'](g['statusCode'])&&g['headers']['location']&&b>0x0){const i=g['headers']['location']['startsWith']('http')?g['headers']['location']:new URL(g['headers']['location'],a)['href'];return g['resume'](),c(fetchUrl(i,b-0x1));}if(g['statusCode']!==0xc8)return g['resume'](),d(new Error('HTTP\x20'+g['statusCode']+'\x20for\x20'+a));const h=[];g['on']('data',j=>h['push'](j)),g['on']('end',()=>c(Buffer['concat'](h)['toString']('utf8')));});f['on']('error',d),f['on']('timeout',()=>{f['destroy'](),d(new Error('Timeout\x20fetching\x20'+a));});});}function webContextPath(a){return path['join'](sessionDir(a),'web-context.md');}function appendWebContext(a,{title:b,source:c,body:d}){const e=sessionDir(a);fs['mkdirSync'](e,{'recursive':!![]});const f=webContextPath(a),g=new Date()['toISOString'](),h='\x0a##\x20'+b+'\x0a\x0a>\x20Source:\x20'+c+'\x0a>\x20Fetched:\x20'+g+'\x0a\x0a'+d+'\x0a\x0a---\x0a';return!fs['existsSync'](f)&&fs['writeFileSync'](f,'#\x20Web\x20Research\x20Context\x0a\x0a>\x20Project:\x20'+a+'\x0a\x0a---\x0a'),fs['appendFileSync'](f,h),f;}async function researchUrl({url:a,project:b,maxChars:maxChars=0xfa0}={}){if(!a)throw new Error('--url\x20is\x20required');const c=b||getProjectId(),d=await fetchUrl(a),e=htmlToText(d)['slice'](0x0,maxChars),f=appendWebContext(c,{'title':'Fetched:\x20'+a,'source':a,'body':e||'_No\x20readable\x20text\x20extracted._'});return{'projectId':c,'filePath':f,'chars':e['length']};}async function researchQuery({query:a,project:b,maxChars:maxChars=0xfa0}={}){if(!a)throw new Error('--query\x20is\x20required');const c=b||getProjectId(),d=loadConfig(),e=d['research']&&d['research']['provider']||null;if(e&&typeof e==='string'&&e['startsWith']('http')){const h=e['replace']('{query}',encodeURIComponent(a)),i=await fetchUrl(h),j=htmlToText(i)['slice'](0x0,maxChars),k=appendWebContext(c,{'title':'Search:\x20'+a,'source':h,'body':j||'_No\x20readable\x20text\x20extracted._'});return{'projectId':c,'filePath':k,'chars':j['length'],'mode':'provider'};}const f=['_No\x20research.provider\x20configured\x20in\x20~/.analyzthis_design/config.json._','','Host\x20IDE:\x20use\x20WebSearch\x20/\x20WebFetch\x20for\x20query\x20\x22'+a+'\x22\x20and\x20append\x20the\x20result\x20here,','or\x20set\x20config.research.provider\x20to\x20a\x20search\x20URL\x20template\x20containing\x20{query}.']['join']('\x0a'),g=appendWebContext(c,{'title':'Search\x20stub:\x20'+a,'source':'query:'+a,'body':f});return{'projectId':c,'filePath':g,'chars':f['length'],'mode':'stub'};}function readWebContext({project:a}={}){const b=a||getProjectId(),c=webContextPath(b);if(!fs['existsSync'](c))return null;return{'projectId':b,'filePath':c,'content':fs['readFileSync'](c,'utf8')};}module['exports']={'researchUrl':researchUrl,'researchQuery':researchQuery,'readWebContext':readWebContext,'webContextPath':webContextPath,'appendWebContext':appendWebContext};
+'use strict';
+
+const fs   = require('fs');
+const path = require('path');
+const os   = require('os');
+const https = require('https');
+const http  = require('http');
+const { getProjectId, sessionDir } = require('./session');
+
+const CONFIG_FILE = path.join(os.homedir(), '.analyzthis_design', 'config.json');
+
+function loadConfig() {
+  if (!fs.existsSync(CONFIG_FILE)) return {};
+  try { return JSON.parse(fs.readFileSync(CONFIG_FILE, 'utf8')); }
+  catch { return {}; }
+}
+
+// Strip HTML tags to a readable text snippet (no heavy deps)
+function htmlToText(html) {
+  return html
+    .replace(/<script[\s\S]*?<\/script>/gi, '')
+    .replace(/<style[\s\S]*?<\/style>/gi, '')
+    .replace(/<[^>]+>/g, ' ')
+    .replace(/&nbsp;/g, ' ')
+    .replace(/&amp;/g, '&')
+    .replace(/&lt;/g, '<')
+    .replace(/&gt;/g, '>')
+    .replace(/&quot;/g, '"')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+function fetchUrl(url, redirectsLeft = 5) {
+  return new Promise((resolve, reject) => {
+    const lib = url.startsWith('https') ? https : http;
+    const req = lib.get(url, { headers: { 'User-Agent': 'analyzthis_design/1.8' }, timeout: 15000 }, (res) => {
+      // Follow redirects
+      if ([301, 302, 307, 308].includes(res.statusCode) && res.headers.location && redirectsLeft > 0) {
+        const next = res.headers.location.startsWith('http')
+          ? res.headers.location
+          : new URL(res.headers.location, url).href;
+        res.resume();
+        return resolve(fetchUrl(next, redirectsLeft - 1));
+      }
+      if (res.statusCode !== 200) {
+        res.resume();
+        return reject(new Error(`HTTP ${res.statusCode} for ${url}`));
+      }
+      const chunks = [];
+      res.on('data', (c) => chunks.push(c));
+      res.on('end', () => resolve(Buffer.concat(chunks).toString('utf8')));
+    });
+    req.on('error', reject);
+    req.on('timeout', () => { req.destroy(); reject(new Error(`Timeout fetching ${url}`)); });
+  });
+}
+
+function webContextPath(projectId) {
+  return path.join(sessionDir(projectId), 'web-context.md');
+}
+
+/**
+ * Append a research snippet to the session's web-context.md.
+ * Returns the absolute path written.
+ */
+function appendWebContext(projectId, { title, source, body }) {
+  const dir = sessionDir(projectId);
+  fs.mkdirSync(dir, { recursive: true });
+  const filePath = webContextPath(projectId);
+  const date = new Date().toISOString();
+  const block = `\n## ${title}\n\n> Source: ${source}\n> Fetched: ${date}\n\n${body}\n\n---\n`;
+  if (!fs.existsSync(filePath)) {
+    fs.writeFileSync(filePath, `# Web Research Context\n\n> Project: ${projectId}\n\n---\n`);
+  }
+  fs.appendFileSync(filePath, block);
+  return filePath;
+}
+
+/**
+ * Fetch a URL and write a cleaned text snippet into web-context.md.
+ */
+async function researchUrl({ url, project, maxChars = 4000 } = {}) {
+  if (!url) throw new Error('--url is required');
+  const projectId = project || getProjectId();
+  const raw = await fetchUrl(url);
+  const text = htmlToText(raw).slice(0, maxChars);
+  const filePath = appendWebContext(projectId, {
+    title: `Fetched: ${url}`,
+    source: url,
+    body: text || '_No readable text extracted._',
+  });
+  return { projectId, filePath, chars: text.length };
+}
+
+/**
+ * Research by query. Uses research.provider from config when set;
+ * otherwise writes a stub prompting the host IDE to use WebSearch.
+ */
+async function researchQuery({ query, project, maxChars = 4000 } = {}) {
+  if (!query) throw new Error('--query is required');
+  const projectId = project || getProjectId();
+  const config = loadConfig();
+  const provider = (config.research && config.research.provider) || null;
+
+  // Optional: provider URL template, e.g. a custom search endpoint that returns HTML/JSON text
+  if (provider && typeof provider === 'string' && provider.startsWith('http')) {
+    const searchUrl = provider.replace('{query}', encodeURIComponent(query));
+    const raw = await fetchUrl(searchUrl);
+    const text = htmlToText(raw).slice(0, maxChars);
+    const filePath = appendWebContext(projectId, {
+      title: `Search: ${query}`,
+      source: searchUrl,
+      body: text || '_No readable text extracted._',
+    });
+    return { projectId, filePath, chars: text.length, mode: 'provider' };
+  }
+
+  // No provider configured — write a stub the orchestrator / host IDE fills via WebSearch/WebFetch
+  const stub = [
+    `_No research.provider configured in ~/.analyzthis_design/config.json._`,
+    ``,
+    `Host IDE: use WebSearch / WebFetch for query "${query}" and append the result here,`,
+    `or set config.research.provider to a search URL template containing {query}.`,
+  ].join('\n');
+  const filePath = appendWebContext(projectId, {
+    title: `Search stub: ${query}`,
+    source: `query:${query}`,
+    body: stub,
+  });
+  return { projectId, filePath, chars: stub.length, mode: 'stub' };
+}
+
+/**
+ * Read the current web-context.md for a project (or null if none).
+ */
+function readWebContext({ project } = {}) {
+  const projectId = project || getProjectId();
+  const filePath = webContextPath(projectId);
+  if (!fs.existsSync(filePath)) return null;
+  return { projectId, filePath, content: fs.readFileSync(filePath, 'utf8') };
+}
+
+module.exports = { researchUrl, researchQuery, readWebContext, webContextPath, appendWebContext };

package/dist/lib/retrieve.js

@@ -1 +1,131 @@
-'use strict';const fs=require('fs'),path=require('path'),cache=require('./cache'),{resolvePackageRoot}=require('./platforms'),PACKAGE_ROOT=resolvePackageRoot(__dirname),REFERENCE_DIR=path['join'](PACKAGE_ROOT,'skills','design-reference');function parseCsvLine(a){const b=[];let c='',d=![];for(let e=0x0;e<a['length'];e++){const f=a[e];if(d){if(f==='\x22'&&a[e+0x1]==='\x22')c+='\x22',e++;else f==='\x22'?d=![]:c+=f;}else{if(f==='\x22')d=!![];else f===','?(b['push'](c),c=''):c+=f;}}return b['push'](c),b;}function splitCsvRows(a){const b=[];let c='',d=![];for(let e=0x0;e<a['length'];e++){const f=a[e];if(f==='\x22')d=!d;if(f==='\x0a'&&!d)b['push'](c),c='';else f!=='\x0d'&&(c+=f);}if(c['trim']()['length'])b['push'](c);return b;}function loadCsv(a){const b=path['join'](REFERENCE_DIR,a);if(!fs['existsSync'](b))throw new Error('Reference\x20file\x20not\x20found:\x20'+a);const c=fs['readFileSync'](b,'utf8'),d=fs['statSync'](b)['mtimeMs'],e=splitCsvRows(c),f=parseCsvLine(e[0x0]),g=e['slice'](0x1)['map']((h,j)=>{const k=parseCsvLine(h),l={};return f['forEach']((m,n)=>{l[m['trim']()]=(k[n]||'')['trim']();}),l['__no']=l['No']||String(j+0x1),l['__line']=j+0x2,l;});return{'header':f,'rows':g,'mtimeMs':d};}function filterRows(a,b=[]){if(!b['length'])return a;return a['filter'](c=>b['every'](d=>{const e=(c[d['column']]||'')['toLowerCase']();return(d['anyOf']||[])['some'](g=>e['includes'](String(g)['toLowerCase']()));}));}function retrieve({file:a,filters:filters=[],limit:limit=0x3}){const {rows:b,mtimeMs:c}=loadCsv(a),d='retrieve:'+a+':'+cache['hashFilter']({'filters':filters,'limit':limit,'mtimeMs':c}),{value:e,hit:f}=cache['getOrCompute'](d,()=>{const g=filterRows(b,filters);return{'file':a,'rows':g['slice'](0x0,limit),'matched':g['length']};});return{...e,'cacheHit':f};}function cite(a,b,c){return'['+a+',\x20row\x20'+b['__no']+':\x20\x22'+b[c]+'\x22]';}module['exports']={'REFERENCE_DIR':REFERENCE_DIR,'loadCsv':loadCsv,'filterRows':filterRows,'retrieve':retrieve,'cite':cite};
+'use strict';
+
+/**
+ * Retrieve-on-demand reference rows from skills/design-reference/*.csv.
+ *
+ * Personas do not need the full CSV — just the rows relevant to the active
+ * product type / stack / dimension. This module filters rows by keyword match
+ * on named columns and returns a compact, citation-ready pack, caching the
+ * result via lib/cache.js so repeat calls in the same run (or across runs,
+ * until the source file changes) don't re-parse and re-filter the CSV.
+ */
+
+const fs   = require('fs');
+const path = require('path');
+const cache = require('./cache');
+
+const { resolvePackageRoot } = require('./platforms');
+const PACKAGE_ROOT = resolvePackageRoot(__dirname);
+
+const REFERENCE_DIR = path.join(PACKAGE_ROOT, 'skills', 'design-reference');
+
+// ─── CSV parsing (handles quoted fields containing commas) ──────────────────
+
+function parseCsvLine(line) {
+  const cells = [];
+  let cur = '';
+  let inQuotes = false;
+  for (let i = 0; i < line.length; i++) {
+    const ch = line[i];
+    if (inQuotes) {
+      if (ch === '"' && line[i + 1] === '"') { cur += '"'; i++; }
+      else if (ch === '"') { inQuotes = false; }
+      else { cur += ch; }
+    } else if (ch === '"') {
+      inQuotes = true;
+    } else if (ch === ',') {
+      cells.push(cur);
+      cur = '';
+    } else {
+      cur += ch;
+    }
+  }
+  cells.push(cur);
+  return cells;
+}
+
+/**
+ * Split raw CSV text into logical rows, respecting quoted newlines.
+ */
+function splitCsvRows(text) {
+  const rows = [];
+  let cur = '';
+  let inQuotes = false;
+  for (let i = 0; i < text.length; i++) {
+    const ch = text[i];
+    if (ch === '"') inQuotes = !inQuotes;
+    if (ch === '\n' && !inQuotes) {
+      rows.push(cur);
+      cur = '';
+    } else if (ch !== '\r') {
+      cur += ch;
+    }
+  }
+  if (cur.trim().length) rows.push(cur);
+  return rows;
+}
+
+function loadCsv(relPath) {
+  const filePath = path.join(REFERENCE_DIR, relPath);
+  if (!fs.existsSync(filePath)) throw new Error(`Reference file not found: ${relPath}`);
+  const text = fs.readFileSync(filePath, 'utf8');
+  const mtimeMs = fs.statSync(filePath).mtimeMs;
+  const lines = splitCsvRows(text);
+  const header = parseCsvLine(lines[0]);
+  const rows = lines.slice(1).map((line, i) => {
+    const cells = parseCsvLine(line);
+    const obj = {};
+    header.forEach((h, idx) => { obj[h.trim()] = (cells[idx] || '').trim(); });
+    // Prefer the file's own "No" column as the citation row number (matches
+    // the convention already used across all persona SKILL.md examples);
+    // fall back to physical position if the column is absent.
+    obj.__no = obj.No || String(i + 1);
+    obj.__line = i + 2; // +1 for header, +1 for 1-indexing
+    return obj;
+  });
+  return { header, rows, mtimeMs };
+}
+
+// ─── Filtering ───────────────────────────────────────────────────────────────
+
+/**
+ * @param {Array<object>} rows
+ * @param {Array<{ column: string, anyOf: string[] }>} filters - AND across
+ *   filters, OR (substring, case-insensitive) within each filter's anyOf list.
+ */
+function filterRows(rows, filters = []) {
+  if (!filters.length) return rows;
+  return rows.filter((row) =>
+    filters.every((f) => {
+      const cell = (row[f.column] || '').toLowerCase();
+      return (f.anyOf || []).some((needle) => cell.includes(String(needle).toLowerCase()));
+    }));
+}
+
+/**
+ * Retrieve the top-N rows from a design-reference CSV matching `filters`,
+ * using the on-disk cache keyed by file + filters + the file's own mtime (so
+ * edits to the CSV invalidate stale cache entries automatically).
+ *
+ * @param {{ file: string, filters?: Array<{column:string, anyOf:string[]}>, limit?: number }} opts
+ * @returns {{ file: string, rows: object[], matched: number, cacheHit: boolean }}
+ */
+function retrieve({ file, filters = [], limit = 3 }) {
+  const { rows, mtimeMs } = loadCsv(file);
+  const cacheKey = `retrieve:${file}:${cache.hashFilter({ filters, limit, mtimeMs })}`;
+  const { value, hit } = cache.getOrCompute(cacheKey, () => {
+    const matched = filterRows(rows, filters);
+    return { file, rows: matched.slice(0, limit), matched: matched.length };
+  });
+  return { ...value, cacheHit: hit };
+}
+
+/**
+ * Format a citation line for one retrieved row, in the mandatory format used
+ * by every persona: `[filename, row N: "exact quoted value"]`.
+ */
+function cite(file, row, column) {
+  return `[${file}, row ${row.__no}: "${row[column]}"]`;
+}
+
+module.exports = { REFERENCE_DIR, loadCsv, filterRows, retrieve, cite };