analyzthis_design 2.3.1 → 2.4.0

package/HOW-TO-USE.md

@@ -108,7 +108,8 @@ npx analyzthis_design sync --target all
 | Review against PRDs and stories | `/ux-story-gate` | Task map + routing before critique |
 | Set visual direction | `/mood-board` | References + design-system patterns + team deliberation |
 | Index the repo for personas | `/kavi` | Kavi → knowledge bank |
-| Get a single-lens opinion | `/arjun`, `/meera`, `/priya`, `/zara`, `/noor`, `/anuj` | Targeted follow-up |
+| Get a single-lens opinion | `/arjun`, `/meera`, `/priya`, `/zara`, `/noor`, `/anuj` | Targeted follow-up. Default is a short verdict — say expand for the full schema |
+| See inferred token spend | `/receipt` | Not a bill. Same as `npx analyzthis_design receipt` |
 
 **Important:** do not use `/persona-orchestrator` or `/design-critic` when you want wireframes. They are for critique.
 

package/README.md

@@ -4,6 +4,17 @@ A set of AI design personas and a task-first evaluation framework that plugs int
 
 Install once. Run structured UX critiques, multi-phase ideation, and task-grounded screen reviews — directly inside your AI chat. **No external LLM API keys required** for CLI orchestrator runs: **`/devi`** voices each persona from your host IDE (Cursor, Claude, etc.).
 
+## v2.4.0 — Claude-path efficiency (1 Sep 2026)
+
+Same SHIP / REVISE / BLOCK. Fewer tokens on Claude Code and Claude Desktop. Not Caveman-speak. Not a proxy.
+
+- **Lite MCP catalog (default):** `analyzthis_design` (router) + `analyzthis_retrieve` + `analyzthis_session` + `analyzthis_receipt`. Old 19-tool list: `ANALYZTHIS_MCP_CATALOG=full` or `npx analyzthis_design mcp --catalog full`.
+- **Receipt:** every MCP result ends with inferred tokens (not a bill). CLI: `npx analyzthis_design receipt`. Slash: `/receipt`.
+- **Slim skill fronts:** Arjun, story-gate, and orchestrator load a short front. Call retrieve (`kind=skill`) for the lens. Personas default to verdict + top 3 + one evidence line; say **expand** for the full schema.
+- **Knowledge bank** is an index. Load one persona slice (`kind=knowledge`, `persona=zara`). Do not inject the whole bank.
+- **Tokens per verdict** prints on `receipt` and CLI `run`.
+- Optional: wrap our stdio MCP through Caveman’s shrink if you already run Caveman. We do not ship a proxy.
+
 ## v2.3.1 — independently callable personas (31 Aug 2026)
 
 After install, type `/noor`, `/anuj`, `/arjun`, `/meera`, `/priya`, `/zara`, `/raj`, `/kavi` even if Claude’s slash menu only lists Getting Started.
@@ -37,7 +48,7 @@ Pass `--global` to opt into the legacy merged behavior (read `config.sources` an
 
 Use `npx analyzthis_design run-unchunked` for the legacy single-pass orchestrator.
 
-**npm:** [analyzthis_design](https://www.npmjs.com/package/analyzthis_design) · **Current version:** 2.3.1 · **Step-by-step guide:** [HOW-TO-USE.md](./HOW-TO-USE.md)
+**npm:** [analyzthis_design](https://www.npmjs.com/package/analyzthis_design) · **Current version:** 2.4.0 · **Step-by-step guide:** [HOW-TO-USE.md](./HOW-TO-USE.md)
 
 ---
 
@@ -63,7 +74,7 @@ npx analyzthis_design run-unchunked --task "Review invoice approval screen" --pr
 
 > **Security:** This package publishes **plain source** — no obfuscation, no minification, no dynamic require. Every file in `dist/` is readable and auditable. The `postinstall` script only prints a welcome message; it does **not** write to any AI-agent directories. Skill installation requires an explicit `npx analyzthis_design install --target <ide>` (or `npx analyzthis_design --target <ide>`).
 >
-> **MCP (universal):** `npx analyzthis_design mcp` starts a local MCP server with 19 tools (all personas + combination passes + utilities). Auto-configures for Cursor, Claude Desktop, **Claude Code**, and Windsurf during install. For Lovable, v0, Bolt, Replit, ChatGPT: run `npx analyzthis_design mcp --configure <tool>` for a config snippet.
+> **MCP (universal):** `npx analyzthis_design mcp` starts a local MCP server. Default catalog is **lite** (router + retrieve + session + receipt). Full 19 named tools: `ANALYZTHIS_MCP_CATALOG=full` or `mcp --catalog full`. Auto-configures for Cursor, Claude Desktop, **Claude Code**, and Windsurf during install. For Lovable, v0, Bolt, Replit, ChatGPT: run `npx analyzthis_design mcp --configure <tool>` for a config snippet.
 
 ### Install by target IDE
 
@@ -870,7 +881,7 @@ skills/
 | **MCP server** | `npx analyzthis_design mcp` starts a local MCP server exposing 19 tools — all 8 individual personas + 6 combination passes + 5 utilities. Any MCP-compatible client can discover and call them. |
 | **Auto-configure MCP** | `npx analyzthis_design mcp --configure cursor` (or `claude`, `windsurf`) writes the MCP config automatically. `--target all` now auto-configures MCP during install. |
 | **Universal IDE support** | Cursor, Claude Desktop, Windsurf auto-configured. Lovable, v0, Bolt, Replit, ChatGPT: run `mcp --configure <tool>` for a copy-paste config snippet. |
-| **19 MCP tools** | 8 individual personas (arjun, meera, priya, zara, noor, anuj, raj, kavi) + 6 combination passes (ux-ideator, persona-orchestrator, design-critic, ux-story-gate, design-director, mood-board) + 5 utilities (evolve-check, collect, retrieve, session, system-prompt) |
+| **MCP lite + full** | Default: router (`analyzthis_design`) + retrieve + session + receipt. Full 19 named tools behind `--catalog full`. |
 | **System prompt fallback** | `analyzthis_system_prompt` tool generates a consolidated prompt for tools that don't support MCP yet |
 
 ## What's new in v2.2

package/dist/HOW-TO-USE.md

@@ -108,7 +108,8 @@ npx analyzthis_design sync --target all
 | Review against PRDs and stories | `/ux-story-gate` | Task map + routing before critique |
 | Set visual direction | `/mood-board` | References + design-system patterns + team deliberation |
 | Index the repo for personas | `/kavi` | Kavi → knowledge bank |
-| Get a single-lens opinion | `/arjun`, `/meera`, `/priya`, `/zara`, `/noor`, `/anuj` | Targeted follow-up |
+| Get a single-lens opinion | `/arjun`, `/meera`, `/priya`, `/zara`, `/noor`, `/anuj` | Targeted follow-up. Default is a short verdict — say expand for the full schema |
+| See inferred token spend | `/receipt` | Not a bill. Same as `npx analyzthis_design receipt` |
 
 **Important:** do not use `/persona-orchestrator` or `/design-critic` when you want wireframes. They are for critique.
 

package/dist/README.md

@@ -4,6 +4,17 @@ A set of AI design personas and a task-first evaluation framework that plugs int
 
 Install once. Run structured UX critiques, multi-phase ideation, and task-grounded screen reviews — directly inside your AI chat. **No external LLM API keys required** for CLI orchestrator runs: **`/devi`** voices each persona from your host IDE (Cursor, Claude, etc.).
 
+## v2.4.0 — Claude-path efficiency (1 Sep 2026)
+
+Same SHIP / REVISE / BLOCK. Fewer tokens on Claude Code and Claude Desktop. Not Caveman-speak. Not a proxy.
+
+- **Lite MCP catalog (default):** `analyzthis_design` (router) + `analyzthis_retrieve` + `analyzthis_session` + `analyzthis_receipt`. Old 19-tool list: `ANALYZTHIS_MCP_CATALOG=full` or `npx analyzthis_design mcp --catalog full`.
+- **Receipt:** every MCP result ends with inferred tokens (not a bill). CLI: `npx analyzthis_design receipt`. Slash: `/receipt`.
+- **Slim skill fronts:** Arjun, story-gate, and orchestrator load a short front. Call retrieve (`kind=skill`) for the lens. Personas default to verdict + top 3 + one evidence line; say **expand** for the full schema.
+- **Knowledge bank** is an index. Load one persona slice (`kind=knowledge`, `persona=zara`). Do not inject the whole bank.
+- **Tokens per verdict** prints on `receipt` and CLI `run`.
+- Optional: wrap our stdio MCP through Caveman’s shrink if you already run Caveman. We do not ship a proxy.
+
 ## v2.3.1 — independently callable personas (31 Aug 2026)
 
 After install, type `/noor`, `/anuj`, `/arjun`, `/meera`, `/priya`, `/zara`, `/raj`, `/kavi` even if Claude’s slash menu only lists Getting Started.
@@ -37,7 +48,7 @@ Pass `--global` to opt into the legacy merged behavior (read `config.sources` an
 
 Use `npx analyzthis_design run-unchunked` for the legacy single-pass orchestrator.
 
-**npm:** [analyzthis_design](https://www.npmjs.com/package/analyzthis_design) · **Current version:** 2.3.1 · **Step-by-step guide:** [HOW-TO-USE.md](./HOW-TO-USE.md)
+**npm:** [analyzthis_design](https://www.npmjs.com/package/analyzthis_design) · **Current version:** 2.4.0 · **Step-by-step guide:** [HOW-TO-USE.md](./HOW-TO-USE.md)
 
 ---
 
@@ -63,7 +74,7 @@ npx analyzthis_design run-unchunked --task "Review invoice approval screen" --pr
 
 > **Security:** This package publishes **plain source** — no obfuscation, no minification, no dynamic require. Every file in `dist/` is readable and auditable. The `postinstall` script only prints a welcome message; it does **not** write to any AI-agent directories. Skill installation requires an explicit `npx analyzthis_design install --target <ide>` (or `npx analyzthis_design --target <ide>`).
 >
-> **MCP (universal):** `npx analyzthis_design mcp` starts a local MCP server with 19 tools (all personas + combination passes + utilities). Auto-configures for Cursor, Claude Desktop, **Claude Code**, and Windsurf during install. For Lovable, v0, Bolt, Replit, ChatGPT: run `npx analyzthis_design mcp --configure <tool>` for a config snippet.
+> **MCP (universal):** `npx analyzthis_design mcp` starts a local MCP server. Default catalog is **lite** (router + retrieve + session + receipt). Full 19 named tools: `ANALYZTHIS_MCP_CATALOG=full` or `mcp --catalog full`. Auto-configures for Cursor, Claude Desktop, **Claude Code**, and Windsurf during install. For Lovable, v0, Bolt, Replit, ChatGPT: run `npx analyzthis_design mcp --configure <tool>` for a config snippet.
 
 ### Install by target IDE
 
@@ -870,7 +881,7 @@ skills/
 | **MCP server** | `npx analyzthis_design mcp` starts a local MCP server exposing 19 tools — all 8 individual personas + 6 combination passes + 5 utilities. Any MCP-compatible client can discover and call them. |
 | **Auto-configure MCP** | `npx analyzthis_design mcp --configure cursor` (or `claude`, `windsurf`) writes the MCP config automatically. `--target all` now auto-configures MCP during install. |
 | **Universal IDE support** | Cursor, Claude Desktop, Windsurf auto-configured. Lovable, v0, Bolt, Replit, ChatGPT: run `mcp --configure <tool>` for a copy-paste config snippet. |
-| **19 MCP tools** | 8 individual personas (arjun, meera, priya, zara, noor, anuj, raj, kavi) + 6 combination passes (ux-ideator, persona-orchestrator, design-critic, ux-story-gate, design-director, mood-board) + 5 utilities (evolve-check, collect, retrieve, session, system-prompt) |
+| **MCP lite + full** | Default: router (`analyzthis_design`) + retrieve + session + receipt. Full 19 named tools behind `--catalog full`. |
 | **System prompt fallback** | `analyzthis_system_prompt` tool generates a consolidated prompt for tools that don't support MCP yet |
 
 ## What's new in v2.2

package/dist/bin/cli.js

@@ -75,6 +75,7 @@ Usage:
 ── Efficiency / cost commands ────────────────────────────────
   metrics             Print the last run's cost metrics (--all for every project)
   cost                Print the last run's $ cost from config.pricing (--all for every project)
+  receipt             Inferred token receipt for host (slash/MCP) turns — not a bill
   export-training     Write accepted-output JSONL pairs for LoRA prep
                       (--persona <id>, --all, --output <path>)
   feedback export     Write rejected + correction JSONL pairs (DPO / negative examples)
@@ -86,9 +87,11 @@ Usage:
 ── MCP server (for any AI IDE: Cursor, Claude Desktop, Lovable, v0, Bolt) ──
   mcp                       Start the MCP server on stdio (for MCP client config)
   mcp --configure cursor    Write MCP config to ~/.cursor/mcp.json
-  mcp --configure claude    Write MCP config to Claude Desktop config
+  mcp --configure claude    Write MCP config to Claude Desktop + Claude Code
   mcp --configure windsurf   Write MCP config to Windsurf
   mcp --configure <tool>    Print manual MCP config for any other tool
+  mcp --catalog lite|full   Lite (default): router + retrieve + session + receipt
+                            full: all 19 named tools. Or ANALYZTHIS_MCP_CATALOG=full
 
 ── Mood board commands ─────────────────────────────────────
   moodboard create --task <text>   Build a mood board from web + DS references
@@ -769,11 +772,12 @@ switch (cmd) {
   case 'mcp': {
     const mcpServer = require('../lib/mcp-server');
     const configureTarget = getFlag('configure');
+    const catalogVal = getFlag('catalog');
     if (configureTarget) {
-      mcpServer.writeMcpConfig(configureTarget);
+      mcpServer.writeMcpConfig(configureTarget, { catalog: catalogVal });
       break;
     }
-    mcpServer.startStdioServer();
+    mcpServer.startStdioServer(catalogVal);
     break;
   }
 
@@ -965,6 +969,8 @@ switch (cmd) {
       console.log(`    objections_raised: ${m.objections_raised ?? 0}`);
       console.log(`    objections_resolved: ${m.objections_resolved ?? 0}`);
       console.log(`    raj_escalations:   ${m.raj_escalations ?? 0}`);
+      console.log(`    host_turns:        ${(m.host_turns || []).length}`);
+      console.log(`    tokens_per_verdict: ${m.tokens_per_verdict ?? 'n/a'}`);
       const d = state.deliberation;
       if (d?.mode) {
         console.log(`    deliberation_mode: ${d.mode}, consensus=${d.consensus_reached}`);
@@ -981,6 +987,12 @@ switch (cmd) {
     break;
   }
 
+  case 'receipt': {
+    const receipt = require('../lib/receipt');
+    console.log('\n' + receipt.report({ project: projectVal }) + '\n');
+    break;
+  }
+
   // ── Persona feedback (v1.16) ────────────────────────────────────────────
 
   case 'feedback': {

package/dist/lib/chunk-run.js

@@ -172,6 +172,8 @@ async function runChunked(opts) {
         output_tokens_est: totalOutput,
         cost_usd: Number(totalCost.toFixed(6)),
         mode: 'chunked',
+        verdicts_this_run: 1,
+        tokens_per_verdict: totalInput || null,
         cache_hits: cacheHits,
         effort_log: results.map(function(r) {
           return {

package/dist/lib/install.js

@@ -33,6 +33,7 @@ const PROJECT_COMMANDS = [
   'design-critic',
   'getting-started',
   'devi',
+  'receipt',
 ];
 
 const SKILLS = [
@@ -60,6 +61,7 @@ const SKILLS = [
   'design-personas',
   'design-reference',
   'knowledge-bank',
+  'receipt',
 ];
 
 function getPackageVersion() {

package/dist/lib/knowledge.js

@@ -8,12 +8,10 @@ const crypto = require('crypto');
 
 const CONFIG_DIR        = path.join(os.homedir(), '.analyzthis_design');
 const CONFIG_FILE       = path.join(CONFIG_DIR, 'config.json');
-// When published, this file lives at dist/lib/ — go up two levels to reach package root
-const KNOWLEDGE_SKILL   = path.join(__dirname, '..', '..', 'skills', 'knowledge-bank', 'SKILL.md');
-const KNOWLEDGE_SLICE_ROOT = path.join(CONFIG_DIR, 'kb-slices');
-
 const { resolvePackageRoot } = require('./platforms');
 const PACKAGE_ROOT = resolvePackageRoot(__dirname);
+const KNOWLEDGE_SKILL   = path.join(PACKAGE_ROOT, 'skills', 'knowledge-bank', 'SKILL.md');
+const KNOWLEDGE_SLICE_ROOT = path.join(CONFIG_DIR, 'kb-slices');
 const AGENTS_DIR = path.join(PACKAGE_ROOT, 'agents');
 
 // Keywords used to auto-group vault notes into categories
@@ -326,41 +324,74 @@ function sync({ targets = ['cursor'], project, global = false, cwd } = {}) {
     ? 'global (merged across projects)'
     : `project: ${scopeInfo.projectId}`;
 
-  let md = `---
-name: knowledge-bank
-description: Personal knowledge bank — takes precedence over all built-in persona defaults.
+  let fullMd = `---
+name: knowledge-bank-full
+description: Full project notes. Do not load this file into chat. Retrieve one persona slice instead.
 disable-model-invocation: true
 ---
 
-# Knowledge Bank
+# Knowledge Bank (full dump — do not inject)
 
 > Last synced: ${date}
 > Scope: ${scopeLabel}
 > Sources: ${sourceList}
 > Files loaded: ${totalFiles}
 
-**INSTRUCTION TO ALL PERSONAS:** This knowledge bank contains project-specific context that overrides your built-in defaults. Read every section below before forming any opinion. When this knowledge bank conflicts with your built-in knowledge, this knowledge bank wins.
-
----
-
 `;
 
   let hasContent = false;
+  let indexLines = '';
   for (const { key, heading } of sectionDefs) {
     if (sections[key].length === 0) continue;
     hasContent = true;
-    md += `${heading}\n\n`;
+    fullMd += `${heading}\n\n`;
+    indexLines += `${heading}\n`;
     for (const note of sections[key]) {
-      md += `### ${note.title}\n\n${note.content}\n\n`;
+      fullMd += `### ${note.title}\n\n${note.content}\n\n`;
+      indexLines += `- ${note.title}\n`;
     }
-    md += '---\n\n';
+    fullMd += '---\n\n';
+    indexLines += '\n';
   }
 
   if (!hasContent) {
-    md += `_No matching files found. Check your --tags or --include filters, or remove filters to include all notes._\n`;
+    fullMd += `_No matching files found. Check your --tags or --include filters, or remove filters to include all notes._\n`;
+    indexLines += `_No notes yet. Run collect/sync first._\n`;
   }
 
-  // Write to the package's own skills/knowledge-bank/SKILL.md (source of truth)
+  const md = `---
+name: knowledge-bank
+description: Project knowledge index — retrieve one persona slice. Do not load the full bank.
+disable-model-invocation: true
+---
+
+# Knowledge Bank
+
+> Last synced: ${date}
+> Scope: ${scopeLabel}
+> Sources: ${sourceList}
+> Files loaded: ${totalFiles}
+
+**INSTRUCTION TO ALL PERSONAS:** Load your persona slice via retrieve. Do not load the whole bank. When a slice conflicts with built-in defaults, the slice wins.
+
+\`\`\`
+npx analyzthis_design retrieve — or MCP analyzthis_retrieve
+  kind=knowledge  persona=arjun|meera|priya|zara|noor|anuj|raj|kavi
+\`\`\`
+
+You cannot know host tokens. Do not invent a dollar figure.
+
+## Index (titles only)
+
+${indexLines}
+`;
+
+  // Full dump stays on disk for retrieve; the skill is an index only.
+  const projectIdForFull = scopeInfo.projectId || 'default';
+  const fullDir = path.join(KNOWLEDGE_SLICE_ROOT, projectIdForFull);
+  fs.mkdirSync(fullDir, { recursive: true });
+  fs.writeFileSync(path.join(fullDir, 'full.md'), fullMd);
+
   fs.mkdirSync(path.dirname(KNOWLEDGE_SKILL), { recursive: true });
   fs.writeFileSync(KNOWLEDGE_SKILL, md);
 
@@ -470,7 +501,7 @@ function buildPersonaSlice(personaId, sections, sectionDefs, projectId) {
 }
 
 function writePersonaSlices(sections, sectionDefs, projectId) {
-  const personas = ['arjun', 'meera', 'priya', 'zara', 'noor', 'anuj', 'raj'];
+  const personas = ['arjun', 'meera', 'priya', 'zara', 'noor', 'anuj', 'raj', 'kavi'];
   const dir = path.join(KNOWLEDGE_SLICE_ROOT, projectId || 'default');
   fs.mkdirSync(dir, { recursive: true });
   const written = [];

package/dist/lib/mcp-server.js

@@ -248,16 +248,18 @@ var TOOLS = [
   },
   {
     name: 'analyzthis_retrieve',
-    description: 'Retrieve CSV reference data. Query the 28-file reference library (colors, styles, typography, UX guidelines, charts, products, landing patterns, 16 stack guides). Returns filtered, citation-ready rows.',
+    description: 'Retrieve on demand: CSV rows, a skill reference file, or one knowledge-bank persona slice. Do not load the full bank.',
     inputSchema: {
       type: 'object',
       properties: {
-        file: { type: 'string', description: 'CSV filename (e.g., "styles.csv", "colors.csv", "stacks/nextjs.csv")' },
-        column: { type: 'string', description: 'Column to filter on (e.g., "Product Type", "Category", "Best For Tags")' },
-        keywords: { type: 'string', description: 'Comma-separated keywords to match (e.g., "saas,dashboard")' },
-        limit: { type: 'number', description: 'Max rows to return (default: 3)' },
+        kind: { type: 'string', enum: ['csv', 'skill', 'knowledge'], description: 'csv (default), skill (references/*.md), or knowledge (one persona slice)' },
+        file: { type: 'string', description: 'CSV filename, or skill id (e.g. arjun), or knowledge/<persona>' },
+        column: { type: 'string', description: 'CSV column to filter on' },
+        keywords: { type: 'string', description: 'Comma-separated CSV keywords' },
+        limit: { type: 'number', description: 'Max CSV rows (default: 3)' },
+        persona: { type: 'string', description: 'Persona id for knowledge slice (arjun, zara, …)' },
+        ref: { type: 'string', description: 'Skill reference filename without path (e.g. lens.md)' },
       },
-      required: ['file'],
     },
   },
   {
@@ -285,6 +287,43 @@ var TOOLS = [
   },
 ];
 
+var ROUTER_TOOL = {
+  name: 'analyzthis_design',
+  description: 'Design team router. Set who to zara, arjun, noor, anuj, meera, priya, raj, kavi, orchestrator, ux-ideator, design-critic, ux-story-gate, design-director, or mood-board. Returns a short skill front — call analyzthis_retrieve for the rest.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      who: { type: 'string', description: 'Persona or pass name (e.g. zara, arjun, orchestrator)' },
+      task: { type: 'string', description: 'What to design or critique' },
+      context: { type: 'string', description: 'Optional extra context' },
+    },
+    required: ['who', 'task'],
+  },
+};
+
+var RECEIPT_TOOL = {
+  name: 'analyzthis_receipt',
+  description: 'Show inferred token receipt for this project. Not a bill. Do not invent a dollar figure.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      project: { type: 'string', description: 'Optional project id override' },
+    },
+  },
+};
+
+function resolveCatalog(explicit) {
+  var raw = explicit || process.env.ANALYZTHIS_MCP_CATALOG || 'lite';
+  return String(raw).toLowerCase() === 'full' ? 'full' : 'lite';
+}
+
+function listedTools(catalog) {
+  if (resolveCatalog(catalog) === 'full') {
+    return TOOLS.concat([ROUTER_TOOL, RECEIPT_TOOL]);
+  }
+  return [ROUTER_TOOL, TOOLS.find(function (t) { return t.name === 'analyzthis_retrieve'; }), TOOLS.find(function (t) { return t.name === 'analyzthis_session'; }), RECEIPT_TOOL].filter(Boolean);
+}
+
 // ── Tool handlers ────────────────────────────────────────────────────────
 
 function handleToolCall(name, args) {
@@ -326,6 +365,10 @@ function handleToolCall(name, args) {
       return handleSession(args);
     case 'analyzthis_system_prompt':
       return handleSystemPrompt(args);
+    case 'analyzthis_design':
+      return handleRouter(args);
+    case 'analyzthis_receipt':
+      return handleReceipt(args);
 
     default:
       return { error: 'Unknown tool: ' + name };
@@ -333,7 +376,7 @@ function handleToolCall(name, args) {
 }
 
 function handleSinglePersona(personaId, args) {
-  var card = readCard(personaId);
+  var card = readSkillFront(personaId);
   if (!card) return { error: 'Persona not found: ' + personaId };
 
   var task = args.task || '';
@@ -351,11 +394,10 @@ function handleSinglePersona(personaId, args) {
     '## Task\n' + task + '\n' +
     (context ? '\n## Context\n' + context : '') +
     extra + '\n\n' +
-    'Produce your output following the schema in your card above. ' +
-    'Be specific — cite components, zones, and fixes. ' +
-    'Do not give generic advice.';
+    'Use the lite output contract. Call analyzthis_retrieve (kind=skill, file=' + personaId + ') only if you need the full lens. ' +
+    'Be specific — cite components, zones, and fixes. Do not give generic advice.';
 
-  return { prompt: prompt, persona: personaId, task: task };
+  return { prompt: prompt, persona: personaId, task: task, verdicts: 1 };
 }
 
 function handleCombinationPass(skillId, args) {
@@ -381,11 +423,11 @@ function handleCombinationPass(skillId, args) {
     skill + '\n\n' +
     '## Task\n' + task + '\n' +
     (context ? '\n## Context\n' + context : '') + '\n\n' +
-    'Run all phases sequentially. Challenge the premise first. ' +
-    'Resolve any persona disagreements explicitly — pick a winner with a forward path. ' +
-    'Produce the final output in the format specified by the skill.';
+    'Run the smallest useful team. Challenge the premise first. ' +
+    'Call analyzthis_retrieve (kind=skill, file=' + skillId + ') if the front is not enough. ' +
+    'Lite default: verdict + top 3 + one evidence line. Expand only if the user says expand.';
 
-  return { prompt: prompt, skill: skillId, task: task };
+  return { prompt: prompt, skill: skillId, task: task, persona: skillId, verdicts: 1 };
 }
 
 function handleMoodBoard(args) {
@@ -439,10 +481,13 @@ function handleCollect(args) {
 }
 
 function handleRetrieve(args) {
+  var kind = args.kind || 'csv';
+  if (kind === 'skill') return handleRetrieveSkill(args);
+  if (kind === 'knowledge') return handleRetrieveKnowledge(args);
   try {
     var retrieve = require('./retrieve');
     var file = args.file;
-    if (!file) return { error: 'file is required' };
+    if (!file) return { error: 'file is required for CSV retrieve' };
     var filters = [];
     if (args.column && args.keywords) {
       filters.push({ column: args.column, anyOf: args.keywords.split(',').map(function(s) { return s.trim(); }) });
@@ -464,6 +509,70 @@ function handleRetrieve(args) {
   }
 }
 
+function handleRetrieveSkill(args) {
+  var id = String(args.file || args.persona || '').replace(/^skill\//, '');
+  if (!id) return { error: 'file (skill id) is required' };
+  var refName = args.ref || 'lens.md';
+  var refPath = path.join(PACKAGE_ROOT, 'skills', id, 'references', refName);
+  if (!fs.existsSync(refPath)) {
+    var dir = path.join(PACKAGE_ROOT, 'skills', id, 'references');
+    if (fs.existsSync(dir)) {
+      var names = fs.readdirSync(dir).filter(function (n) { return n.endsWith('.md'); });
+      if (names.length) refPath = path.join(dir, names[0]);
+    }
+  }
+  if (!fs.existsSync(refPath)) {
+    var full = readSkill(id);
+    if (!full) return { error: 'No skill references for ' + id };
+    return { result: full, persona: id };
+  }
+  return { result: fs.readFileSync(refPath, 'utf8'), persona: id };
+}
+
+function handleRetrieveKnowledge(args) {
+  var persona = args.persona || String(args.file || '').replace(/^knowledge\//, '');
+  if (!persona) return { error: 'persona is required for knowledge retrieve' };
+  try {
+    var knowledge = require('./knowledge');
+    var sessionMod = require('./session');
+    var projectId = sessionMod.getProjectId();
+    var slicePath = path.join(knowledge.KNOWLEDGE_SLICE_ROOT, projectId, persona + '.md');
+    if (!fs.existsSync(slicePath)) {
+      return { result: 'No knowledge slice for ' + persona + '. Run collect/sync first. Do not load a full bank.' };
+    }
+    var text = fs.readFileSync(slicePath, 'utf8');
+    var cap = 6000;
+    if (text.length > cap) text = text.slice(0, cap) + '\n…[truncated — this is one slice, not the full bank]';
+    return { result: text, persona: persona };
+  } catch (e) {
+    return { error: e.message };
+  }
+}
+
+var ROUTER_WHO = {
+  zara: 'persona', arjun: 'persona', meera: 'persona', priya: 'persona',
+  noor: 'persona', anuj: 'persona', raj: 'persona', kavi: 'persona',
+  orchestrator: 'persona-orchestrator', 'persona-orchestrator': 'persona-orchestrator',
+  'ux-ideator': 'ux-ideator', 'design-critic': 'design-critic',
+  'ux-story-gate': 'ux-story-gate', 'design-director': 'design-director',
+  'mood-board': 'mood-board',
+};
+
+function handleRouter(args) {
+  var who = String(args.who || '').toLowerCase().replace(/^analyzthis_/, '').replace(/_/g, '-');
+  if (!who) return { error: 'who is required (e.g. zara, arjun, orchestrator)' };
+  var mapped = ROUTER_WHO[who];
+  if (!mapped) return { error: 'Unknown who: ' + who + '. Use a persona or orchestrator / ux-ideator / design-critic / ux-story-gate / design-director / mood-board.' };
+  if (mapped === 'persona') return handleSinglePersona(who, args);
+  if (mapped === 'mood-board') return handleMoodBoard(args);
+  return handleCombinationPass(mapped, args);
+}
+
+function handleReceipt(args) {
+  var receipt = require('./receipt');
+  return { result: receipt.report({ project: args.project }) };
+}
+
 function handleSession(args) {
   try {
     var session = require('./session');
@@ -506,18 +615,16 @@ function handleSystemPrompt(args) {
 
 // ── Helpers ──
 
-function readCard(id) {
-  var p = path.join(PACKAGE_ROOT, 'agents', 'cards', id + '.md');
-  if (!fs.existsSync(p)) return null;
-  return fs.readFileSync(p, 'utf8');
-}
-
 function readSkill(id) {
   var p = path.join(PACKAGE_ROOT, 'skills', id, 'SKILL.md');
   if (!fs.existsSync(p)) return null;
   return fs.readFileSync(p, 'utf8');
 }
 
+function readSkillFront(id) {
+  return readSkill(id);
+}
+
 // ── MCP config writer ──
 
 function mergeMcpServer(configPath) {
@@ -532,6 +639,7 @@ function mergeMcpServer(configPath) {
   config.mcpServers['analyzthis_design'] = {
     command: 'npx',
     args: ['analyzthis_design', 'mcp'],
+    env: { ANALYZTHIS_MCP_CATALOG: process.env.ANALYZTHIS_MCP_CATALOG || 'lite' },
   };
   fs.writeFileSync(configPath, JSON.stringify(config, null, 2));
   return configPath;
@@ -542,13 +650,17 @@ function looksLikeProjectCwd() {
   return fs.existsSync(path.join(cwd, 'package.json')) || fs.existsSync(path.join(cwd, '.git'));
 }
 
-function writeMcpConfig(target) {
+function writeMcpConfig(target, opts) {
+  opts = opts || {};
+  if (opts.catalog) process.env.ANALYZTHIS_MCP_CATALOG = opts.catalog;
   var home = os.homedir();
 
   if (target === 'cursor') {
     var cursorConfigPath = path.join(home, '.cursor', 'mcp.json');
     mergeMcpServer(cursorConfigPath);
     console.log('Cursor MCP config written to ' + cursorConfigPath);
+    console.log('Default MCP catalog is lite (router + retrieve + session + receipt).');
+    console.log('Full 19-tool list: ANALYZTHIS_MCP_CATALOG=full or mcp --catalog full');
     console.log('Restart Cursor to activate.\n');
     return true;
   }
@@ -575,6 +687,7 @@ function writeMcpConfig(target) {
       console.log('Project MCP config written to ' + projectMcp);
     }
 
+    console.log('Default MCP catalog is lite. Full list: ANALYZTHIS_MCP_CATALOG=full');
     console.log('Restart Claude Code and Claude Desktop to activate.\n');
     return true;
   }
@@ -602,7 +715,9 @@ function writeMcpConfig(target) {
 
 // ── MCP protocol (JSON-RPC 2.0 over stdio) ────────────────────────────────
 
-function startStdioServer() {
+function startStdioServer(catalog) {
+  var catalogMode = resolveCatalog(catalog);
+  var activeTools = listedTools(catalogMode);
   var rl = readline.createInterface({ input: process.stdin, terminal: false });
   var initialized = false;
 
@@ -647,7 +762,7 @@ function startStdioServer() {
         jsonrpc: '2.0',
         id: id,
         result: {
-          tools: TOOLS.map(function(t) {
+          tools: activeTools.map(function(t) {
             return {
               name: t.name,
               description: t.description,
@@ -673,11 +788,17 @@ function startStdioServer() {
         });
       } else {
         var text = result.prompt || result.result || result.command || JSON.stringify(result, null, 2);
+        var receipt = require('./receipt');
+        var wrapped = receipt.wrapPayload(text, {
+          path: 'mcp',
+          persona: result.persona || result.skill || toolName,
+          verdicts: result.verdicts || 0,
+        });
         send({
           jsonrpc: '2.0',
           id: id,
           result: {
-            content: [{ type: 'text', text: String(text) }],
+            content: [{ type: 'text', text: wrapped }],
           },
         });
       }
@@ -711,24 +832,32 @@ function startStdioServer() {
 
   if (process.env.MCP_DEBUG) {
     process.stderr.write('analyzthis_design MCP server v' + VERSION + ' running on stdio\n');
-    process.stderr.write('Tools: ' + TOOLS.length + ' available\n');
+    process.stderr.write('Tools: ' + activeTools.length + ' (' + catalogMode + ' catalog)\n');
   }
 }
 
 // ── Entry point ──
 
+function parseCatalogFlag(args) {
+  var eq = args.filter(function (a) { return a.indexOf('--catalog=') === 0; })[0];
+  if (eq) return eq.split('=').slice(1).join('=');
+  var idx = args.indexOf('--catalog');
+  if (idx !== -1 && args[idx + 1] && args[idx + 1].indexOf('--') !== 0) return args[idx + 1];
+  return null;
+}
+
 function main() {
   var args = process.argv.slice(2);
+  var catalog = parseCatalogFlag(args);
 
   // --configure <target>
   var configureIdx = args.indexOf('--configure');
   if (configureIdx !== -1 && args[configureIdx + 1]) {
-    writeMcpConfig(args[configureIdx + 1]);
+    writeMcpConfig(args[configureIdx + 1], { catalog: catalog });
     return;
   }
 
-  // Default: start stdio server
-  startStdioServer();
+  startStdioServer(catalog);
 }
 
 if (require.main === module) {
@@ -737,6 +866,10 @@ if (require.main === module) {
 
 module.exports = {
   TOOLS: TOOLS,
+  ROUTER_TOOL: ROUTER_TOOL,
+  RECEIPT_TOOL: RECEIPT_TOOL,
+  listedTools: listedTools,
+  resolveCatalog: resolveCatalog,
   handleToolCall: handleToolCall,
   startStdioServer: startStdioServer,
   writeMcpConfig: writeMcpConfig,