analyzthis_design 2.0.0 → 2.0.1

package/HOW-TO-USE.md

@@ -0,0 +1,436 @@
+# How to Use Analyzthis Design — Step-by-Step Guide
+
+A practical guide for Cursor, Claude Code, Codex CLI, Grok Build, Windsurf Cascade, and any Agent Skills–compatible IDE.
+
+> **Updated for v2.0.0:** `npx analyzthis_design run` now uses **chunked execution** by default (frontier planner → free/cheap chunk models → synthesis). Each chunk retrieves from 3-5 CSV reference files + vault slices, pooled into a single ranker call. Legacy single-pass is available as `npx analyzthis_design run-unchunked`.
+
+---
+
+## 1. What this package gives you
+
+**8 design personas** as slash commands inside your IDE:
+
+- **Arjun** — UX + Visual Design audit (Honeycomb + hierarchy)
+- **Meera** — Business / retention / GTM lens
+- **Priya** — Feasibility / engineering effort
+- **Zara** — Delight moments
+- **Noor** — Minimalist IA / progressive disclosure
+- **Anuj** — Dense power-user IA
+- **Raj** — Product strategy / stalemate arbitrator
+- **Kavi** — Knowledge archivist
+
+Plus composite skills: `/ux-ideator`, `/design-director`, `/persona-orchestrator`, `/design-critic`, `/ux-story-gate`, `/mood-board`.
+
+---
+
+## 2. One-time install (per machine)
+
+Pick your IDE and run **one** command in any terminal:
+
+```bash
+# Cursor (default)
+npx analyzthis_design --target cursor
+
+# Claude Code
+npx analyzthis_design --target claude
+
+# Codex CLI
+npx analyzthis_design --target codex
+
+# Grok Build
+npx analyzthis_design --target grok
+
+# Windsurf Cascade
+npx analyzthis_design --target windsurf
+
+# Install to every supported IDE at once
+npx analyzthis_design --target all
+```
+
+This copies the skills into the IDE's agent-skills directory:
+
+| IDE | Where skills live | Invoke prefix |
+|---|---|---|
+| **Cursor** | `~/.cursor/skills/<skill>/SKILL.md` | `/` |
+| **Claude Code** | `~/.claude/skills/<skill>/SKILL.md` | `/` |
+| **Codex CLI** | `~/.codex/skills/<skill>/SKILL.md` | reference in `AGENTS.md` |
+| **Grok Build** | `~/.grok/skills/<skill>/SKILL.md` | `/` |
+| **Windsurf Cascade** | `~/.codeium/windsurf/skills/<skill>/SKILL.md` | `@` |
+| **Cross-agent** | `~/.agents/skills/<skill>/SKILL.md` | `/` |
+
+To see what is installed:
+
+```bash
+npx analyzthis_design list --target cursor
+```
+
+To reinstall after updating the package:
+
+```bash
+npx analyzthis_design --target all --force
+```
+
+---
+
+## 3. Project setup (do this once per repo)
+
+Open your project in the IDE, then in the chat/terminal:
+
+```bash
+npx analyzthis_design collect
+```
+
+This runs **Kavi**:
+
+1. Scans your repo (PRDs, brand/tokens, pages, components, tech, research).
+2. Writes an Obsidian-compatible vault under `~/.analyzthis_design/vaults/{projectId}/`.
+3. Optionally enriches notes with an LLM.
+4. Syncs a **knowledge bank** into your IDE so every persona reads your context first.
+
+If you already have an Obsidian vault or markdown folder:
+
+```bash
+npx analyzthis_design connect --vault ~/Documents/MyVault
+npx analyzthis_design sync --target all
+```
+
+---
+
+## 4. How to pick the right slash command
+
+| I want to… | Run this | Why |
+|---|---|---|
+| Wireframe a new screen or flow | `/ux-ideator` or `/noor` | Full text wireframes, two competing IA concepts |
+| Quick minimalist wireframe | `/noor` | Concept A — progressive disclosure, one primary action |
+| Dense power-user wireframe | `/anuj` | Concept B — bulk actions, keyboard shortcuts, full density |
+| Design + spec + optional build | `/design-director` | Senior-designer handoff path |
+| Critique an existing design | `/persona-orchestrator` or `/design-critic` | Scored review → SHIP / REVISE / BLOCK |
+| 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 |
+
+**Important:** do not use `/persona-orchestrator` or `/design-critic` when you want wireframes. They are for critique.
+
+---
+
+## 5. Common workflows
+
+### 5.1 Wireframe a new screen
+
+**Cursor / Claude / Grok:**
+
+```
+/ux-ideator Design a settings page for a B2B SaaS dashboard.
+Primary user: ops manager, daily use. Stack: Next.js + shadcn.
+Produce full text wireframes for both Concept A and Concept B.
+```
+
+**Windsurf:** replace `/` with `@`:
+
+```
+@ux-ideator Design a settings page for a B2B SaaS dashboard.
+```
+
+**Codex:** reference the skill in `AGENTS.md` or invoke by name from `~/.codex/skills/`.
+
+What happens:
+
+1. `ux-story-gate` builds a task map.
+2. MoE router selects the ideation chain.
+3. Meera → Noor + Anuj → Arjun → Zara → Priya run in groups.
+4. Personas deliberate with low satisfaction.
+5. You get two text wireframes plus a synthesis.
+
+---
+
+### 5.2 Critique an existing screen
+
+```
+/persona-orchestrator Critique this login page for UX friction and hierarchy.
+Assess only — do not implement changes.
+```
+
+What happens:
+
+1. `ux-story-gate` discovers PRDs and user stories.
+2. MoE router picks a subset of the critique chain (default: Arjun + Meera).
+3. For a full 4-persona review:
+
+   ```
+   /design-critic Full review of the invoice screen.
+   Run all personas in --full mode.
+   ```
+
+4. Personas raise objections, ask questions, and converge.
+5. Output: composite score, verdict (SHIP / REVISE / BLOCK), Top 3 fixes.
+
+---
+
+### 5.3 Design + spec + build
+
+```
+/design-director Design a notifications settings page for our B2B app.
+Use our shadcn components and tokens from the knowledge bank.
+Produce a DesignSpec and implement after spec gates pass.
+```
+
+What happens:
+
+1. Ideation → two concepts.
+2. DesignSpec is produced and validated.
+3. Spec gates (design system, hierarchy) must pass.
+4. If `mode: build_approved`, implementation begins.
+
+---
+
+### 5.4 Set visual direction with a mood board
+
+```bash
+npx analyzthis_design moodboard create --task "B2B fintech dashboard, trustworthy, high-contrast" --auto
+npx analyzthis_design moodboard critique --board <boardId>
+```
+
+Or in chat:
+
+```
+/mood-board Build a mood board for a B2B fintech dashboard.
+Trustworthy, high-contrast, data-dense. Include 3 web references.
+```
+
+What happens:
+
+1. Web references and search stubs are collected.
+2. Each reference is tagged (style, mood, surface).
+3. Design-system patterns are pulled from `skills/design-reference/*.csv`.
+4. Arjun, Meera, Priya, Zara, Noor deliberate using the UX Honeycomb matrix.
+5. A `board.json` is written to `./moodboard/` for you to inspect.
+
+You can add your own references and rerun:
+
+```bash
+npx analyzthis_design moodboard add --board <boardId> \
+  --url https://dribbble.com/shots/example \
+  --title "Alt hero" --tags "landing,trust"
+```
+
+---
+
+### 5.5 Run the standalone CLI orchestrator
+
+**v2.0 default — chunked execution (no API keys required):**
+
+```bash
+# Frontier planner + free/cheap chunk models
+npx analyzthis_design run --task "Review my invoice screen"
+
+# Prefer free models only (Ollama, Groq/Gemini/OpenRouter free endpoints)
+npx analyzthis_design run --task "Review my invoice screen" --budget free
+
+# Use your paid keys for cheap, capable models
+npx analyzthis_design run --task "Review my invoice screen" --budget cheap --provider together
+
+# Sequential is default; explicit parallel
+npx analyzthis_design run --task "..." --parallel --max-chunks 6
+```
+
+**Legacy single-pass orchestrator (host mode, no API keys):**
+
+```bash
+# Start a run — it pauses and waits for the host LLM /devi
+npx analyzthis_design run-unchunked --task "Review my invoice screen" --full
+npx analyzthis_design devi status
+npx analyzthis_design run-unchunked --continue --task "Review my invoice screen" --full
+
+# Quick single-expert run
+npx analyzthis_design run-unchunked --task "Just check spacing" --experts arjun
+```
+
+In host mode, the CLI writes pending prompts to:
+
+```
+~/.analyzthis_design/runs/{projectId}/{runId}/pending/
+```
+
+and reads responses from:
+
+```
+~/.analyzthis_design/runs/{projectId}/{runId}/responses/
+```
+
+---
+
+## 6. IDE-specific notes
+
+### Cursor
+
+- Invoke skills with `/`, e.g. `/ux-ideator`, `/persona-orchestrator`, `/mood-board`.
+- Skills live in `~/.cursor/skills/`.
+- Use `/devi` when the CLI orchestrator is waiting for a host response.
+- If a skill is missing, run `npx analyzthis_design --target cursor --force`.
+
+### Claude Code
+
+- Invoke skills with `/`, e.g. `/ux-ideator`.
+- Skills live in `~/.claude/skills/`. Legacy commands also work from `~/.claude/commands/`.
+- Use `/devi` for host LLM responses.
+
+### Codex CLI
+
+- Codex does not use `/` prefixes. Reference skill names in your project's `AGENTS.md` or invoke by name.
+- Skills live in `~/.codex/skills/`.
+- Example `AGENTS.md` line: `Skills: analyzthis_design/ux-ideator, analyzthis_design/persona-orchestrator`.
+
+### Grok Build
+
+- Invoke skills with `/`, e.g. `/ux-ideator`, `/persona-orchestrator`.
+- Skills live in `~/.grok/skills/`.
+
+### Windsurf Cascade
+
+- Invoke skills with `@`, e.g. `@ux-ideator`, `@persona-orchestrator`, `@mood-board`.
+- Skills live in `~/.codeium/windsurf/skills/`.
+
+---
+
+## 7. Persona-specific follow-ups
+
+After a run, you can ask a single persona to go deeper:
+
+```
+/arjun Double-check the hierarchy on the wireframe from the last /ux-ideator run.
+/meera Is the onboarding flow likely to improve activation rate?
+/priya How much effort is the modal-vs-wizard choice?
+/zara Add one delight moment to the empty state.
+/noor Simplify the navigation to ≤3 levels.
+/anuj Add bulk actions and keyboard shortcuts for daily users.
+```
+
+Each persona reads the session state, so you do not need to repeat the task.
+
+---
+
+## 8. After the run — accept, reject, evolve
+
+### Mark an output accepted
+
+```bash
+npx analyzthis_design session accept --persona arjun
+```
+
+### Reject with correction
+
+```bash
+npx analyzthis_design session accept --persona arjun --reject \
+  --comment "Invented tokens not in our DS" \
+  --correction "Use --color-primary and spacing-4 from tokens.css" \
+  --rating 2 --tags invented_tokens,missed_ds
+```
+
+### Make the team learn
+
+```bash
+npx analyzthis_design evolve --extract --dry-run   # preview
+npx analyzthis_design evolve --extract             # write patch proposals
+npx analyzthis_design evolve --apply <patchId>      # apply after review
+```
+
+### Confirm whether the advice actually shipped
+
+```bash
+npx analyzthis_design outcome --confirm --persona arjun --result shipped
+# or: revised, blocked_correctly, missed
+```
+
+---
+
+## 9. Configuration
+
+Create `~/.analyzthis_design/config.json`:
+
+```json
+{
+  "orchestrator": {
+    "provider": "host",
+    "mode": "lite"
+  },
+  "collect": {
+    "web_urls": ["https://your-company.com/brand-guidelines"],
+    "web_queries": ["your product design inspiration"],
+    "web_limit": 10
+  },
+  "moodboard": {
+    "urls": ["https://dribbble.com/shots/example"],
+    "queries": ["fintech dashboard design"],
+    "limit": 12,
+    "workspace_dir": "./moodboard"
+  }
+}
+```
+
+No API keys are required for host mode. To use cloud providers, set one of:
+
+- `ANTHROPIC_API_KEY`
+- `OPENAI_API_KEY`
+- `GEMINI_API_KEY` or `GOOGLE_API_KEY`
+- `ZAI_API_KEY` or `ZHIPU_API_KEY`
+- `GROQ_API_KEY` (free tier available)
+- `TOGETHER_API_KEY`
+- `OPENROUTER_API_KEY` (free models available)
+- `DEEPSEEK_API_KEY`
+- Local **Ollama** auto-detected at `localhost:11434` (no key needed)
+
+---
+
+## 10. Troubleshooting
+
+| Problem | Fix |
+|---|---|
+| Skill not found in IDE | Reinstall: `npx analyzthis_design --target <ide> --force` |
+| Personas re-ask for context | Run `npx analyzthis_design session show` — if a session exists, do not re-derive the task map |
+| No web references fetched | Add `collect.web_urls` / `research.urls` to config, or paste URLs directly |
+| Run pauses with "Host LLM pending" | Invoke `/devi` in Cursor/Claude, or run `npx analyzthis_design devi respond --run <dir> --step <id> --file response.md` |
+| Want a cheaper run | Use `--lite` (default) instead of `--full` |
+| Want deeper critique | Use `--full` for the full design-critic chain |
+| Personas give generic advice | Add PRDs/brand/research notes and re-run `npx analyzthis_design collect` |
+| CSV data seems stale | Run `npx analyzthis_design validate` to check integrity against `schema.json` |
+
+---
+
+## 11. Quick reference
+
+```bash
+# Help
+npx analyzthis_design welcome
+
+# Knowledge
+npx analyzthis_design collect
+npx analyzthis_design sync --target all
+npx analyzthis_design session init
+npx analyzthis_design session show
+
+# Run (v2.0 chunked by default)
+npx analyzthis_design run --task "Review this screen" --dry-run
+npx analyzthis_design run --task "Review this screen" --budget free
+npx analyzthis_design run --continue --task "Review this screen"
+
+# Run (legacy single-pass)
+npx analyzthis_design run-unchunked --task "Review this screen" --full
+
+# Validate CSV reference data
+npx analyzthis_design validate
+
+# Mood board
+npx analyzthis_design moodboard create --task "..." --auto
+npx analyzthis_design moodboard critique --board <id>
+npx analyzthis_design moodboard add --board <id> --url <url> --tags a,b
+
+# Evolve
+npx analyzthis_design evolve --extract --dry-run
+npx analyzthis_design evolve --apply <patchId>
+npx analyzthis_design outcome --confirm --persona arjun --result shipped
+```
+
+---
+
+Docs: https://github.com/joshirishi/analyzthis_design

package/README.md

@@ -15,7 +15,7 @@ Install once. Run structured UX critiques, multi-phase ideation, and task-ground
 
 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.0.0 · **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.0.1 · **Step-by-step guide:** [HOW-TO-USE.md](./HOW-TO-USE.md)
 
 ---
 
@@ -379,6 +379,9 @@ Ask → session digest → MoE router (1–2 experts, not 4) → persona cards (
 | **Persona cards** | `agents/cards/<persona>.md` (~500 tokens) are the default system prompt; the full `skills/<persona>/SKILL.md` is only opened for a C-or-below rubric lookup or an explicit deep/full request. |
 | **Lite output schema** | Grades + Top 2 fixes + score, by default. Deep/full schema is opt-in. |
 | **Retrieve-on-demand** | `npx analyzthis_design retrieve --file colors.csv --column "Product Type" --keywords saas` returns only matching rows, pre-formatted for citation — never the whole CSV. |
+| **Multi-file reference packs** | Each persona retrieves from 3-5 CSV files (not 1), pooled into a single ranker call. Arjun gets styles + ux-guidelines + ui-reasoning + charts; Zara gets colors + typography + styles + landing + icons. Same LLM cost as single-file, 3-5x coverage. |
+| **Best For Tags** | `styles.csv` and `typography.csv` have a `Best For Tags` column (semicolon-delimited product-type tokens) for reliable keyword filtering. Previously `Best For` was free-text and 31/84 styles were unfilterable. |
+| **CSV schema + validation** | `skills/design-reference/schema.json` defines all 28 CSV files' headers, filter columns, and cross-file joins. `npm run validate` checks integrity before publish. |
 | **Model tiers** | `structured` steps can run on a cheaper model (e.g. `gpt-4o-mini`); `critique`/`arbitrate` steps use a stronger model. Configurable per tier in `~/.analyzthis_design/config.json`. |
 | **Caching** | `lib/cache.js` caches retrieve results (invalidated automatically when the source CSV changes) and knowledge-bank slices (invalidated on `sync` / `session reset`). |
 | **Cost metrics** | Every `run` records `metrics` (llm_calls, experts_run, estimated tokens, cache_hits) into session state. |
@@ -458,12 +461,12 @@ evolve --extract → proposes:
   - reference-data rows (new product-type patterns)
   - router patches (task_type → best-performing expert)
         ↓
-evolve --apply <patchId> (human review) → skill/CSV/router updated
-        ↓
+  evolve --apply <patchId> (human review) → skill/CSV/router updated
+         ↓
 Next run retrieves:
   - per-persona knowledge slices (priority + fallback)
   - past lessons for similar tasks
-  - query-expanded + ranked reference rows
+  - query-expanded + ranked reference rows from 3-5 CSV files per persona
 ```
 
 ### Retrieval stack
@@ -709,12 +712,14 @@ npx analyzthis_design research --query <text>
 # Reference data (retrieve-on-demand)
 npx analyzthis_design retrieve --file <csv> --column <col> --keywords a,b [--limit N]
 
-# Standalone orchestrator
-npx analyzthis_design run --task "..." [--figma URL] [--provider host|anthropic|openai|google|zai] [--dry-run] [--output path]
-npx analyzthis_design run --task "..." [--lite | --full] [--experts a,b]
-npx analyzthis_design run --task "..." [--deliberate | --no-deliberate] [--max-rounds N] [--satisfaction 0.4]
+# Standalone orchestrator (v2.0 chunked by default)
+npx analyzthis_design run --task "..." [--budget free|cheap|auto] [--sequential|--parallel] [--max-chunks N] [--dry-run]
+npx analyzthis_design run-unchunked --task "..." [--lite|--full] [--experts a,b] [--dry-run] [--deliberate|--no-deliberate]
 npx analyzthis_design run --continue --task "..."   # resume host-mode run after /devi
 
+# CSV validation
+npx analyzthis_design validate    # validate all 28 CSV files against schema.json
+
 # Self-evolving team (v1.21)
 npx analyzthis_design evolve --extract [--window N] [--dry-run]
 npx analyzthis_design evolve --apply <patchId> [--dry-run]
@@ -764,6 +769,7 @@ lib/
   chunk-synthesis.js    Merge chunk outputs into final verdict
   chunk-telemetry.js    Per-chunk model quality tracking
   chunk-run.js          Top-level chunked execution coordinator
+  reference-pack.js     Shared multi-file CSV + vault retrieval (buildReferencePack)
   moodboard.js          Mood-board engine: collect web/DS references, tag, deliberate
   dedup.js              Cross-persona redundancy detection
   lessons.js            Self-evolving lessons store (extract/retrieve/inject)
@@ -785,6 +791,7 @@ scripts/
   quality-check.js      Validate persona outputs vs skill + deliberation protocol
   demo-fictional-deliberation.js  Dry-run walkthrough for FlowPay scenario
 scripts/obfuscate.js    Build step → dist/
+scripts/validate-csvs.js  CSV integrity validation against schema.json
 skills/
   devi/                 Host LLM runtime — voices personas from pending prompts
   kavi/                 Kavi — Knowledge Archivist (/kavi)
@@ -804,7 +811,7 @@ skills/
 
 - Node.js 16+
 - Any Agent Skills–compatible host: [Cursor](https://cursor.com), [Claude Code](https://code.claude.com), Codex CLI, [Grok Build](https://x.ai), or Windsurf Cascade
-- **CLI `run`:** works without API keys via **`/devi`** host mode (default). Optional keys for automated API runs: `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY`, `ZAI_API_KEY`
+- **CLI `run`:** works without API keys via **`/devi`** host mode (default). Optional keys for automated API runs: `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY`, `ZAI_API_KEY`, `GROQ_API_KEY`, `TOGETHER_API_KEY`, `OPENROUTER_API_KEY`, `DEEPSEEK_API_KEY`. Local Ollama auto-detected at `localhost:11434`.
 - **Kavi `collect` enrichment:** optional — same keys as above; without keys, draft vault + sync still run
 
 ---
@@ -818,6 +825,10 @@ skills/
 | **Chunk telemetry** | Tracks per-model success rate so router improves over time |
 | **Legacy mode preserved** | `npx analyzthis_design run-unchunked` for the original single-pass orchestrator |
 | **Planner never cheap** | Planner always uses frontier/host; chunk models are cost-optimized |
+| **Multi-file reference retrieval** | Each persona retrieves from 3-5 CSV files (not 1) via a shared ranker — same LLM cost, 3-5x coverage |
+| **All 16 stacks detected** | `detectStack()` covers all 16 stack CSVs (flutter, swiftui, laravel, threejs, etc.) — was 8 |
+| **CSV schema + validation** | `npm run validate` checks all 28 CSV files against `schema.json` before publish |
+| **Best For Tags** | styles.csv + typography.csv have normalized tag columns for reliable keyword filtering |
 
 ## What's new in v1.22
 

package/dist/HOW-TO-USE.md

@@ -2,7 +2,7 @@
 
 A practical guide for Cursor, Claude Code, Codex CLI, Grok Build, Windsurf Cascade, and any Agent Skills–compatible IDE.
 
-> **Updated for v2.0.0:** `npx analyzthis_design run` now uses **chunked execution** by default (frontier planner → free/cheap chunk models → synthesis). Legacy single-pass is available as `npx analyzthis_design run-unchunked`.
+> **Updated for v2.0.0:** `npx analyzthis_design run` now uses **chunked execution** by default (frontier planner → free/cheap chunk models → synthesis). Each chunk retrieves from 3-5 CSV reference files + vault slices, pooled into a single ranker call. Legacy single-pass is available as `npx analyzthis_design run-unchunked`.
 
 ---
 
@@ -374,6 +374,11 @@ No API keys are required for host mode. To use cloud providers, set one of:
 - `OPENAI_API_KEY`
 - `GEMINI_API_KEY` or `GOOGLE_API_KEY`
 - `ZAI_API_KEY` or `ZHIPU_API_KEY`
+- `GROQ_API_KEY` (free tier available)
+- `TOGETHER_API_KEY`
+- `OPENROUTER_API_KEY` (free models available)
+- `DEEPSEEK_API_KEY`
+- Local **Ollama** auto-detected at `localhost:11434` (no key needed)
 
 ---
 
@@ -388,6 +393,7 @@ No API keys are required for host mode. To use cloud providers, set one of:
 | Want a cheaper run | Use `--lite` (default) instead of `--full` |
 | Want deeper critique | Use `--full` for the full design-critic chain |
 | Personas give generic advice | Add PRDs/brand/research notes and re-run `npx analyzthis_design collect` |
+| CSV data seems stale | Run `npx analyzthis_design validate` to check integrity against `schema.json` |
 
 ---
 
@@ -403,11 +409,17 @@ npx analyzthis_design sync --target all
 npx analyzthis_design session init
 npx analyzthis_design session show
 
-# Run
+# Run (v2.0 chunked by default)
 npx analyzthis_design run --task "Review this screen" --dry-run
-npx analyzthis_design run --task "Review this screen" --full
+npx analyzthis_design run --task "Review this screen" --budget free
 npx analyzthis_design run --continue --task "Review this screen"
 
+# Run (legacy single-pass)
+npx analyzthis_design run-unchunked --task "Review this screen" --full
+
+# Validate CSV reference data
+npx analyzthis_design validate
+
 # Mood board
 npx analyzthis_design moodboard create --task "..." --auto
 npx analyzthis_design moodboard critique --board <id>

package/dist/README.md

@@ -15,7 +15,7 @@ Install once. Run structured UX critiques, multi-phase ideation, and task-ground
 
 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.0.0 · **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.0.1 · **Step-by-step guide:** [HOW-TO-USE.md](./HOW-TO-USE.md)
 
 ---
 
@@ -379,6 +379,9 @@ Ask → session digest → MoE router (1–2 experts, not 4) → persona cards (
 | **Persona cards** | `agents/cards/<persona>.md` (~500 tokens) are the default system prompt; the full `skills/<persona>/SKILL.md` is only opened for a C-or-below rubric lookup or an explicit deep/full request. |
 | **Lite output schema** | Grades + Top 2 fixes + score, by default. Deep/full schema is opt-in. |
 | **Retrieve-on-demand** | `npx analyzthis_design retrieve --file colors.csv --column "Product Type" --keywords saas` returns only matching rows, pre-formatted for citation — never the whole CSV. |
+| **Multi-file reference packs** | Each persona retrieves from 3-5 CSV files (not 1), pooled into a single ranker call. Arjun gets styles + ux-guidelines + ui-reasoning + charts; Zara gets colors + typography + styles + landing + icons. Same LLM cost as single-file, 3-5x coverage. |
+| **Best For Tags** | `styles.csv` and `typography.csv` have a `Best For Tags` column (semicolon-delimited product-type tokens) for reliable keyword filtering. Previously `Best For` was free-text and 31/84 styles were unfilterable. |
+| **CSV schema + validation** | `skills/design-reference/schema.json` defines all 28 CSV files' headers, filter columns, and cross-file joins. `npm run validate` checks integrity before publish. |
 | **Model tiers** | `structured` steps can run on a cheaper model (e.g. `gpt-4o-mini`); `critique`/`arbitrate` steps use a stronger model. Configurable per tier in `~/.analyzthis_design/config.json`. |
 | **Caching** | `lib/cache.js` caches retrieve results (invalidated automatically when the source CSV changes) and knowledge-bank slices (invalidated on `sync` / `session reset`). |
 | **Cost metrics** | Every `run` records `metrics` (llm_calls, experts_run, estimated tokens, cache_hits) into session state. |
@@ -458,12 +461,12 @@ evolve --extract → proposes:
   - reference-data rows (new product-type patterns)
   - router patches (task_type → best-performing expert)
         ↓
-evolve --apply <patchId> (human review) → skill/CSV/router updated
-        ↓
+  evolve --apply <patchId> (human review) → skill/CSV/router updated
+         ↓
 Next run retrieves:
   - per-persona knowledge slices (priority + fallback)
   - past lessons for similar tasks
-  - query-expanded + ranked reference rows
+  - query-expanded + ranked reference rows from 3-5 CSV files per persona
 ```
 
 ### Retrieval stack
@@ -709,12 +712,14 @@ npx analyzthis_design research --query <text>
 # Reference data (retrieve-on-demand)
 npx analyzthis_design retrieve --file <csv> --column <col> --keywords a,b [--limit N]
 
-# Standalone orchestrator
-npx analyzthis_design run --task "..." [--figma URL] [--provider host|anthropic|openai|google|zai] [--dry-run] [--output path]
-npx analyzthis_design run --task "..." [--lite | --full] [--experts a,b]
-npx analyzthis_design run --task "..." [--deliberate | --no-deliberate] [--max-rounds N] [--satisfaction 0.4]
+# Standalone orchestrator (v2.0 chunked by default)
+npx analyzthis_design run --task "..." [--budget free|cheap|auto] [--sequential|--parallel] [--max-chunks N] [--dry-run]
+npx analyzthis_design run-unchunked --task "..." [--lite|--full] [--experts a,b] [--dry-run] [--deliberate|--no-deliberate]
 npx analyzthis_design run --continue --task "..."   # resume host-mode run after /devi
 
+# CSV validation
+npx analyzthis_design validate    # validate all 28 CSV files against schema.json
+
 # Self-evolving team (v1.21)
 npx analyzthis_design evolve --extract [--window N] [--dry-run]
 npx analyzthis_design evolve --apply <patchId> [--dry-run]
@@ -764,6 +769,7 @@ lib/
   chunk-synthesis.js    Merge chunk outputs into final verdict
   chunk-telemetry.js    Per-chunk model quality tracking
   chunk-run.js          Top-level chunked execution coordinator
+  reference-pack.js     Shared multi-file CSV + vault retrieval (buildReferencePack)
   moodboard.js          Mood-board engine: collect web/DS references, tag, deliberate
   dedup.js              Cross-persona redundancy detection
   lessons.js            Self-evolving lessons store (extract/retrieve/inject)
@@ -785,6 +791,7 @@ scripts/
   quality-check.js      Validate persona outputs vs skill + deliberation protocol
   demo-fictional-deliberation.js  Dry-run walkthrough for FlowPay scenario
 scripts/obfuscate.js    Build step → dist/
+scripts/validate-csvs.js  CSV integrity validation against schema.json
 skills/
   devi/                 Host LLM runtime — voices personas from pending prompts
   kavi/                 Kavi — Knowledge Archivist (/kavi)
@@ -804,7 +811,7 @@ skills/
 
 - Node.js 16+
 - Any Agent Skills–compatible host: [Cursor](https://cursor.com), [Claude Code](https://code.claude.com), Codex CLI, [Grok Build](https://x.ai), or Windsurf Cascade
-- **CLI `run`:** works without API keys via **`/devi`** host mode (default). Optional keys for automated API runs: `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY`, `ZAI_API_KEY`
+- **CLI `run`:** works without API keys via **`/devi`** host mode (default). Optional keys for automated API runs: `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY`, `ZAI_API_KEY`, `GROQ_API_KEY`, `TOGETHER_API_KEY`, `OPENROUTER_API_KEY`, `DEEPSEEK_API_KEY`. Local Ollama auto-detected at `localhost:11434`.
 - **Kavi `collect` enrichment:** optional — same keys as above; without keys, draft vault + sync still run
 
 ---
@@ -818,6 +825,10 @@ skills/
 | **Chunk telemetry** | Tracks per-model success rate so router improves over time |
 | **Legacy mode preserved** | `npx analyzthis_design run-unchunked` for the original single-pass orchestrator |
 | **Planner never cheap** | Planner always uses frontier/host; chunk models are cost-optimized |
+| **Multi-file reference retrieval** | Each persona retrieves from 3-5 CSV files (not 1) via a shared ranker — same LLM cost, 3-5x coverage |
+| **All 16 stacks detected** | `detectStack()` covers all 16 stack CSVs (flutter, swiftui, laravel, threejs, etc.) — was 8 |
+| **CSV schema + validation** | `npm run validate` checks all 28 CSV files against `schema.json` before publish |
+| **Best For Tags** | styles.csv + typography.csv have normalized tag columns for reliable keyword filtering |
 
 ## What's new in v1.22