analyzthis_design 1.8.0 → 1.11.0

package/README.md

@@ -11,24 +11,35 @@ Install once. Run structured UX critiques, multi-phase ideation, and task-ground
 ## Install
 
 ```bash
-# Cursor (default)
+# Cursor (default) + cross-agent path on postinstall
 npx analyzthis_design
 
-# Claude Code
+# Claude Code (skills dir + legacy commands)
 npx analyzthis_design --target claude
 
 # Codex CLI
 npx analyzthis_design --target codex
 
-# All three at once
-npx analyzthis_design --target all
+# Grok Build (xAI)
+npx analyzthis_design --target grok
+
+# Windsurf Cascade
+npx analyzthis_design --target windsurf
+
+# All supported hosts at once
+npx analyzthis_design --target all --force
 ```
 
-| Tool | Skills installed to |
-|---|---|
-| Cursor | `~/.cursor/skills/` |
-| Claude Code | `~/.claude/commands/` |
-| Codex CLI | `~/.codex/skills/` |
+| Tool | Skills installed to | Invoke |
+|---|---|---|
+| Cursor | `~/.cursor/skills/<name>/SKILL.md` | `/collect-knowledge` |
+| Claude Code | `~/.claude/skills/<name>/SKILL.md` (+ legacy `~/.claude/commands/`) | `/collect-knowledge` |
+| Codex CLI | `~/.codex/skills/<name>/SKILL.md` | skill name / AGENTS.md |
+| Grok Build | `~/.grok/skills/<name>/SKILL.md` | `/collect-knowledge` |
+| Windsurf Cascade | `~/.codeium/windsurf/skills/<name>/SKILL.md` | `@collect-knowledge` |
+| Cross-agent | `~/.agents/skills/<name>/SKILL.md` | discovered by multiple hosts |
+
+All skills use the **Agent Skills** `SKILL.md` standard — same files work across Cursor, Claude, Grok, Windsurf, and Codex. The CLI (`collect`, `run`, `sync`) is host-agnostic; only *where skills are discovered* differs.
 
 ---
 
@@ -38,17 +49,19 @@ npx analyzthis_design --target all
 
 | Command | What it does |
 |---|---|
-| `/persona-orchestrator` | **Recommended agentic entry point.** Loads MoE router + session state, runs ux-story-gate intake, executes the right persona chain, enforces DS / hierarchy / verify gates, synthesises a SHIP/REVISE/BLOCK verdict. |
+| `/collect-knowledge` | **Kavi — Knowledge Archivist.** Scans the codebase, builds an Obsidian vault, LLM-enriches notes, syncs into the knowledge bank so every critique persona reads company context first. Run this once per project before critiques. |
+| `/persona-orchestrator` | **Recommended agentic critique entry point.** Loads MoE router + session state, runs ux-story-gate intake, executes the right persona chain, enforces DS / hierarchy / verify gates, synthesises a SHIP/REVISE/BLOCK verdict. |
 | `/ux-story-gate` | Task-first gate: discovers PRDs, DS/Figma discovery, MoE routing, browser verify, assess-only mode. |
 | `/design-critic` | 4-persona critique → `SHIP / REVISE / BLOCK` verdict with a Composite Score out of 20 + Information Hierarchy Gate. |
 | `/ux-ideator` | 6-phase ideation → two competing IA concepts, deliberation, delight pass, feasibility check. |
 
-### 7 Individual Personas
+### 8 Personas
 
-Invoke directly for targeted, already-grounded questions. For full screen evaluation, prefer `/persona-orchestrator` or `/ux-story-gate`.
+Invoke critique personas for targeted, already-grounded questions. For full screen evaluation, prefer `/persona-orchestrator` or `/ux-story-gate`. Run `/collect-knowledge` first so they have project context.
 
 | Command | Persona | What they evaluate |
 |---|---|---|
+| `/collect-knowledge` | Kavi — Knowledge Archivist | Scan repo → Obsidian vault → enrich → sync knowledge bank (producer, not a critic) |
 | `/arjun` | UX + Visual Design | UX Honeycomb + Visual Design Audit (hierarchy, color, type, spacing, components, style fit, micro-interactions) |
 | `/meera` | Business Agent | Retention, ARR, GTM lever, adoption risk; hierarchy vs north-star check |
 | `/priya` | Feasibility Agent | Engineering effort (T-shirt sizing, 2-axis model), state machine traps |
@@ -62,12 +75,12 @@ Invoke directly for targeted, already-grounded questions. For full screen evalua
 | Command | Purpose |
 |---|---|
 | `/design-personas` | Session context template — fill in once before a session |
-| `/knowledge-bank` | Auto-populated from your connected vault. All personas read this first. |
+| `/knowledge-bank` | Auto-populated from your connected vault (or from Kavi collect). All personas read this first. |
 | `/design-reference` | CSV reference data (colors, typography, UX guidelines, stacks, …) |
 
 ---
 
-## Agentic system (v1.8)
+## Agentic system (v1.11)
 
 ```
 User ask / Figma URL
@@ -76,11 +89,11 @@ User ask / Figma URL
         ↓
   ux-story-gate Phases 0–1.5 (PRD + DS/Figma + MoE router)
         ↓
-  MoE subset OR design-critic / ideation chain
+  MoE subset (default, 1–2 experts) OR design-critic / ideation chain (explicit "full")
         ↓
-  Hard gates: DS tokens → Information Hierarchy → Browser verify
+  Hard gates: DS tokens → Information Hierarchy → Browser verify (skipped if assess_only + no URL)
         ↓
-  Session state persisted  →  SHIP / REVISE / BLOCK
+  Session state + cost metrics persisted  →  SHIP / REVISE / BLOCK
 ```
 
 **Shared session state** lives at `~/.analyzthis_design/sessions/{project-id}/session-state.json` so Ask→Agent turns do not re-derive the task map, DS checklist, or routing decision.
@@ -107,20 +120,42 @@ agents/
 # Print routing only (no API calls)
 npx analyzthis_design run --task "Fix contrast on landing page" --dry-run
 
-# Call Anthropic / OpenAI per persona step
+# Call Anthropic / OpenAI per persona step (MoE subset, lite schema — the default)
 export ANTHROPIC_API_KEY=sk-...
 npx analyzthis_design run --task "Review this screen" --figma https://figma.com/... --provider anthropic
+
+# Force the full design-critic chain, or bypass the router entirely
+npx analyzthis_design run --task "Full critique of onboarding" --full
+npx analyzthis_design run --task "Just check spacing" --experts arjun
 ```
 
 Provider defaults live in `~/.analyzthis_design/config.json`:
 
 ```json
 {
-  "orchestrator": { "provider": "anthropic", "model": "claude-sonnet-4-20250514" },
+  "orchestrator": {
+    "provider": "anthropic",
+    "model": "claude-sonnet-5",
+    "mode": "lite",
+    "tiers": {
+      "structured": { "provider": "openai", "model": "gpt-4o-mini" },
+      "critique":   { "provider": "anthropic", "model": "claude-sonnet-5" },
+      "arbitrate":  { "provider": "anthropic", "model": "claude-sonnet-5" }
+    },
+    "max_tokens": { "structured": 900, "critique": 1800, "arbitrate": 1200 }
+  },
+  "pricing": {
+    "glm-4.5-flash":     { "input_per_m": 0,    "output_per_m": 0 },
+    "gemini-2.5-flash":  { "input_per_m": 0.30, "output_per_m": 2.50 },
+    "claude-sonnet-5":   { "input_per_m": 2,    "output_per_m": 10 },
+    "gpt-4o":            { "input_per_m": 2.50, "output_per_m": 10 }
+  },
   "research": { "provider": "https://example.com/search?q={query}" }
 }
 ```
 
+The `effort_matrix` and `gate_override` live in `agents/chain.json` (not the user config) so they ship with the package and stay in sync with the agent graph. `pricing` is user-configured so you control your own $-cost reporting.
+
 **Web research:**
 
 ```bash
@@ -132,6 +167,101 @@ Writes to `~/.analyzthis_design/sessions/{id}/web-context.md` and merges into th
 
 ---
 
+## Efficiency & cost (v1.10)
+
+The orchestrator defaults to the cheapest path that still respects every gate — fewer expert calls, shorter prompts, cheaper models where judgment isn't required, and on-disk caching. These savings apply to the **critique/audit** path (what this package does); see *What this actually saves* below for the honest scope.
+
+### Effort-graded model selection (v1.10)
+
+Each persona call is classified **trivial | standard | hard** from cheap signals already in the routing + session digest (no LLM call — a model call to pick a model would eat the savings). The classifier then resolves the model from an effort matrix, with persona-level overrides winning and the legacy `tiers` map as the final fallback so existing manifests keep working unchanged.
+
+```mermaid
+flowchart TB
+    Ask[User ask] --> Router[MoE router + effort classifier]
+    Router -->|effort| Resolve[resolveModel persona effort]
+    Resolve -->|gate? hard override| Matrix[effort_matrix in chain.json]
+    Resolve -->|persona| Overrides[manifest.effort_overrides]
+    Matrix --> Call[callLlm provider model maxTokens]
+    Overrides --> Call
+    Call --> Metrics[metrics.effort_log + cost_usd]
+    Metrics --> CostCmd[npx analyzthis_design cost]
+```
+
+Classifier rules (first match wins, safety rules before savings rules):
+- scoped mode active → **trivial** (single dimension by construction)
+- stalemate / any BLOCK / `full_chain` / `full_screen_review` → **hard**
+- `digest.ds_at_risk` non-empty → **hard**
+- REVISE delta follow-up → **trivial**
+- `manifest.tier == structured` → **trivial**, `arbitrate` → **standard**
+- default → **standard**
+
+**Gates never downgrade.** `ds_gate`, `information_hierarchy_gate`, and `verify_gate` are pinned to `hard` via `chain.gate_override` regardless of the classified effort — they're the safety net that makes downgrading persona work safe.
+
+Default effort matrix (in `agents/chain.json`):
+- trivial → `glm-4.5-flash` (free) or Gemini Flash-Lite, ~500-token cap
+- standard → `gemini-2.5-flash` or `gpt-4o-mini`, ~1200-token cap
+- hard → `claude-sonnet-5` or `gpt-5`, ~1800-token cap
+
+Per-persona `effort_overrides` in each manifest refine this (e.g. Arjun's `trivial` is the color-system-only scoped mode at 700 tokens; his `hard` is the full Honeycomb + Visual Audit at 1800).
+
+```
+Ask → session digest → MoE router (1–2 experts, not 4) → persona cards (not full skills)
+    → retrieve-on-demand CSV rows (not whole files) → model tier by step → caches → cost metrics
+```
+
+| Lever | Default behavior |
+|---|---|
+| **Expert budget** | 1–2 personas per ask. Full `design-critic` chain only runs for an explicit "full critique" or `full_screen_review`. |
+| **Early DS exit** | Any "at risk" DS Token Checklist item stops the chain at `arjun_color_system_only` — Meera/Priya/Zara wait until it clears. |
+| **Delta re-evaluation** | A follow-up after REVISE re-runs only the personas assigned to the prior Top 3 changes, never the full chain. |
+| **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. |
+| **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. |
+
+```bash
+npx analyzthis_design metrics                 # last run's cost summary for this project
+npx analyzthis_design metrics --all           # across every project
+```
+
+### What this actually saves (and what it doesn't)
+
+analyzthis_design is a design **critique** layer, not a design generator. The personas *review* UI; they don't produce a finished design end-to-end. So the savings show up on the **review** side of the loop, and across the **create → review → revise** loop when your host LLM uses the personas as a guided check — not on raw generation in isolation.
+
+**Honest, measurable savings on the critique path:**
+
+- ~50–75% fewer expert LLM calls on narrow asks (1–2 personas vs. 4).
+- ~50%+ fewer input tokens per `run` (persona cards vs. full SKILL.md).
+- Retrieve-on-demand sends only matching CSV rows, not whole files (`colors.csv` is 32 kB, `styles.csv` is 143 kB — we send ~5 rows).
+- Structured/extract steps can run on a cheaper model with a 900-token cap; only critique/arbitrate uses the strong model.
+- Repeat runs on the same file hit the cache instead of re-processing Figma screenshots, KB slices, and CSV packs.
+- Every saving above is **observable** via `npx analyzthis_design metrics` (`llm_calls`, `input_tokens_est`, `output_tokens_est`, `cache_hits`).
+
+**Where the savings come from across the whole loop** (when the host LLM routes a design through the personas):
+
+- Fewer revision rounds — DS / hierarchy / contrast failures are caught early instead of after a full review.
+- Data-driven citations ground the LLM so it doesn't hallucinate or re-derive design rules.
+- The host LLM gets a compact digest + targeted fixes, not a wall of prose.
+
+**What this is *not*:**
+
+- It does **not** generate end-to-end designs using fewer tokens — it critiques.
+- It does **not** save tokens vs. "using no AI at all" — it adds a review layer; it saves tokens vs. an *unstructured* review loop.
+- There is no hard percentage claim yet — v1.9 ships *targets* (full-chain rate <30%, median experts ≤2, ~50% fewer skill-prompt tokens), not proven production numbers. Run `metrics` on your own workload to see your actual savings.
+
+**LoRA readiness (export hook only — no training in this release):**
+
+```bash
+npx analyzthis_design session accept --persona arjun     # mark the last output as a good example
+npx analyzthis_design export-training --persona arjun --all
+```
+
+Writes `{ system_card, digest, user, assistant }` JSONL pairs to `~/.analyzthis_design/training/<persona>.jsonl` from every session where that persona's output was explicitly accepted. Once a persona accumulates ~100–300 accepted pairs, that data is ready for a future fine-tuning pass on an open model — not part of this package yet.
+
+---
+
 ## UX Story Gate — How it works
 
 `/ux-story-gate` is the task-first gate for any screen evaluation:
@@ -151,9 +281,45 @@ Writes to `~/.analyzthis_design/sessions/{id}/web-context.md` and merges into th
 
 ---
 
+## Knowledge collection — Kavi (v1.11)
+
+Kavi is a **producer** persona (not a critic). One command scans the current repo, writes an Obsidian vault, optionally enriches notes with an LLM, then auto-connects and syncs into the knowledge bank.
+
+```
+/collect-knowledge  (or  npx analyzthis_design collect)
+        ↓
+  Scan codebase (gitignore-aware) → draft Obsidian notes
+        ↓
+  LLM enrich (batched; skip with --no-enrich if no API key)
+        ↓
+  ~/.analyzthis_design/vaults/{project-id}/
+        ↓
+  connect + sync → knowledge-bank skill
+        ↓
+  Arjun / Meera / … read company context first
+```
+
+```bash
+# In your app repo (sync KB to every host):
+npx analyzthis_design collect --target all
+npx analyzthis_design collect --dry-run
+npx analyzthis_design collect --no-enrich --limit 50
+npx analyzthis_design collect --vault ~/Documents/MyProjectVault --target claude
+```
+
+Vault folders: `PRDs/`, `Brand/`, `Product/`, `Pages/`, `Components/`, `Design/`, `Tech/`, `Research/`, `_meta/`. Notes use YAML frontmatter + `[[wikilinks]]`. Re-runs skip unchanged enriched notes via content hash.
+
+Enrichment needs one of: `OPENAI_API_KEY`, `GEMINI_API_KEY`, `ANTHROPIC_API_KEY`, `ZAI_API_KEY`. Without a key, Kavi still writes a draft vault and syncs it.
+
+---
+
 ## Knowledge Bank — Connect your vault
 
 ```bash
+# Option A — let Kavi build the vault from the codebase (recommended for new projects)
+npx analyzthis_design collect
+
+# Option B — connect an existing Obsidian vault or markdown folder
 npx analyzthis_design connect --vault ~/Documents/MyVault
 npx analyzthis_design connect --vault ~/vault --tags design,brand,prd,product
 npx analyzthis_design connect --vault ~/vault --include Design,Brand,PRDs,Research
@@ -179,6 +345,9 @@ npx analyzthis_design --force
 npx analyzthis_design remove --target all
 npx analyzthis_design list --target all
 
+# Knowledge collection (Kavi)
+npx analyzthis_design collect [--vault path] [--dry-run] [--no-enrich] [--limit N] [--target cursor|claude|grok|windsurf|agents|all]
+
 # Knowledge bank
 npx analyzthis_design connect --vault <path> [--tags ...] [--include ...]
 npx analyzthis_design sync [--target all]
@@ -187,13 +356,23 @@ npx analyzthis_design status
 
 # Session (agentic)
 npx analyzthis_design session init|show|reset [--project id] [--all]
+npx analyzthis_design session accept --persona <id> [--reject]
 
 # Research
 npx analyzthis_design research --url <url>
 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 anthropic|openai] [--dry-run] [--output path]
+npx analyzthis_design run --task "..." [--figma URL] [--provider anthropic|openai|google|zai] [--dry-run] [--output path]
+npx analyzthis_design run --task "..." [--lite | --full] [--experts a,b]
+
+# Efficiency / cost
+npx analyzthis_design metrics [--project id] [--all]
+npx analyzthis_design cost [--project id] [--all]
+npx analyzthis_design export-training --persona <id> [--project id] [--all] [--output path]
 ```
 
 ---
@@ -202,16 +381,24 @@ npx analyzthis_design run --task "..." [--figma URL] [--provider anthropic|opena
 
 ```
 agents/                 Portable MoE graph (manifests, router, chain, session schema)
+  cards/                Short per-persona system prompts (~500 tokens each)
 bin/cli.js              CLI entry point
 lib/
   install.js            Skill installation
   knowledge.js          Vault sync + web-context merge
-  session.js            Shared session-state.json
+  collect.js            Kavi — codebase scan → Obsidian vault → enrich → sync
+  platforms.js          Cross-host skill paths (Cursor, Claude, Codex, Grok, Windsurf, agents)
+  session.js            Shared session-state.json (+ digest, metrics, vault_path)
   research.js           URL / query → web-context.md
-  orchestrator/run.js   Standalone LLM runtime (v2)
+  retrieve.js           Filtered, citation-ready CSV row retrieval
+  cache.js              On-disk cache for retrieve/kb slices
+  export.js             LoRA training-pair export hook
+  cost.js               $-cost report from metrics × config.pricing
+  orchestrator/run.js   Standalone LLM runtime (v2) — MoE, effort-graded tiers, caps, cache-aware
 scripts/obfuscate.js    Build step → dist/
 skills/
-  persona-orchestrator/ Agentic entry point
+  collect-knowledge/    Kavi — Knowledge Archivist
+  persona-orchestrator/ Agentic critique entry point
   ux-story-gate/        Task-first gate + DS/MoE/verify/assess phases
   design-critic/        4-persona critique + hierarchy gate
   ux-ideator/           6-phase ideation
@@ -224,9 +411,8 @@ skills/
 ## Requirements
 
 - Node.js 16+
-- [Cursor](https://cursor.com) with Agent Mode (for `/skill` commands)
-- Claude Code or Codex CLI if using those targets
-- For `run` (non–dry-run): `ANTHROPIC_API_KEY` or `OPENAI_API_KEY`
+- 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
+- For `run` / `collect` enrichment: `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY`, or `ZAI_API_KEY`
 
 ---
 

package/agents/cards/anuj.md

@@ -0,0 +1,22 @@
+# Anuj (Dev) — Power User (card)
+
+6 years domain analyst in high-volume ops before product. Information density is a feature, not a flaw.
+
+**Allowed:** audit density, bulk actions, keyboard shortcuts for daily-use surfaces; produce Concept B wireframe; keep rank #1 of the declared information hierarchy prominent even at full density.
+
+**Forbidden:** proposing density audits for surfaces with task Frequency ≠ daily/weekly; code edits without explicit build approval.
+
+**Non-negotiable:** density never flattens the information hierarchy — rank #1 stays the most prominent element (leftmost/largest/first-sorted) even at full density.
+
+## Lite output schema (default)
+```
+## Anuj — Lite
+Hierarchy check: rank #1 [element] kept prominent via [mechanism]
+Bulk actions: [present/missing] — Keyboard shortcuts: [list or "none"]
+Top fix: [one line]
+```
+
+## Deep output schema
+Full Concept B text wireframe (hierarchy check, primary action, nav level, visible-on-load at full density, keyboard shortcuts, progressive disclosure, rationale) — see `skills/anuj/SKILL.md` "Output — Concept B". Use deep mode for ideation runs or full/deep critiques.
+
+**Citation:** `[filename, row N: "exact quoted value"]` — e.g. `[ux-guidelines.csv, row 22: "..."]`. Only run this persona when task Frequency = daily/weekly.

package/agents/cards/arjun.md

@@ -0,0 +1,23 @@
+# Arjun — UX + Visual Design (card)
+
+Product designer (200+ user sessions, B2B SaaS) turned design-systems lead (3 yrs, 200+ shipped components). Runs both the UX lens and the visual-design lens in one pass.
+
+**Allowed:** UX Honeycomb critique (Useful, Usable, Findable, Credible, Accessible, Desirable, Valuable); full Visual Design Audit (hierarchy, color, typography, spacing, components, style fit, micro-interactions); diagnosing visual issues against declared information hierarchy + DS tokens.
+
+**Forbidden:** brand-system recovery as a primary job (diagnostic only, no `!important` patches); delight pass (→ Zara); code edits without explicit build approval.
+
+**Scoped mode `arjun_color_system_only`:** used on a DS Gate early exit — grade only Color System + Typography contrast, skip the rest of the Honeycomb/Visual Audit.
+
+## Lite output schema (default)
+```
+## Arjun — Lite
+UX grades: Useful[A-F] Usable[A-F] Findable[A-F] Credible[A-F] Accessible[A-F] Desirable[A-F] Valuable[A-F]
+Visual grades: Hierarchy[A-F] Color[A-F] Type[A-F] Spacing[A-F] Components[A-F] StyleFit[A-F] Micro[A-F]
+Top 2 fixes: 1. [component+zone+fix] 2. [component+zone+fix]
+Combined score: [X/5]
+```
+
+## Deep output schema
+Full UX Critique + Visual Design Audit blocks with per-dimension reasons — see `skills/arjun/SKILL.md` "Output format". Use deep mode when the user asks for a full/deep critique, any dimension scores C or below and needs the full rubric quoted, or `default_chain` is running.
+
+**Citation:** `[filename, row N: "exact quoted value"]`. Consult `skills/arjun/SKILL.md` Grade Rubric tables when scoring C or below and rubric detail is needed.

package/agents/cards/kavi.md

@@ -0,0 +1,26 @@
+# Kavi — Knowledge Archivist (card)
+
+Producer persona. Scans a codebase, builds an Obsidian vault, enriches notes into readable project knowledge, then wires that vault into the knowledge bank so every critique persona reads company context first.
+
+**Allowed:** codebase inventory (PRDs, brand/tokens, pages, components, tech stack, research); writing Obsidian notes with YAML frontmatter + `[[wikilinks]]`; LLM enrichment of draft extracts into concise purpose + key facts; connecting and syncing the vault into `knowledge-bank`.
+
+**Forbidden:** UX / visual / business critique (→ Arjun / Meera / etc.); inventing files, APIs, or components not present in the raw extract; design generation; code edits in the scanned repo.
+
+## Output schema (enrichment batches)
+For each draft note, emit a full Obsidian markdown file:
+1. Keep the original YAML frontmatter; set `enriched: true`.
+2. Sections: Purpose, Key facts (bullets), Related (`[[Folder/Note]]` wikilinks only to notes that exist in the batch or were listed under Related).
+3. Do not paste large code blocks — summarize what the file does in plain language.
+4. Do not invent APIs, routes, or props that are not in the Raw extract / Exports / Imports.
+
+## Lite report (after collect CLI)
+```
+## Kavi — Collect report
+Vault: [path]
+Notes: [N written / S skipped unchanged]
+Enriched: [E]
+Knowledge bank: [synced count] → [targets]
+Next: run /persona-orchestrator or any critique persona — they read this bank first.
+```
+
+Consult `skills/collect-knowledge/SKILL.md` for the host workflow. Prefer running `npx analyzthis_design collect` over re-scanning files in chat.

package/agents/cards/meera.md

@@ -0,0 +1,21 @@
+# Meera — Business (card)
+
+Ex-revenue/sales. Thinks in retention, ARR, GTM levers. Numbers-first, segmentation-aware. Skeptical of features that demo well but die in production adoption.
+
+**Allowed:** north-star metric impact assessment; segment/GTM/retention analysis; check that rank #1 on screen matches the actual business-critical driver.
+
+**Forbidden:** visual or UX critique (→ Arjun); code edits without explicit build approval.
+
+## Lite output schema (default)
+```
+## Meera — Lite
+Metric impact: [moves it / neutral / hurts it]
+Hierarchy check: [matches / does not match] north-star driver
+Top 2 fixes: 1. [...] 2. [...]
+Score: [1-5]
+```
+
+## Deep output schema
+Full Business Impact block (metric impact, hierarchy check, segment, GTM lever, retention hook, adoption risk, verdict) — see `skills/meera/SKILL.md` "Output format". Use deep mode for full/deep critiques or when `default_chain` is running.
+
+**Citation:** `[filename, row N: "exact quoted value"]` — e.g. `[products.csv, row 6: "..."]`. Consult `skills/meera/SKILL.md` for the full reference-data table when a specific product-type match is needed.

package/agents/cards/noor.md

@@ -0,0 +1,22 @@
+# Noor — Minimalist IA (card)
+
+7 years IA for SaaS across fintech, workflow automation, B2B tooling. Shipped at 50k–500k DAU — scale punishes complexity, doesn't justify it.
+
+**Allowed:** declare ranked information hierarchy; propose minimalist IA / progressive-disclosure structure; produce Concept A wireframe.
+
+**Forbidden:** brand token recovery; contrast/accessibility fixes (→ Arjun); code edits without explicit build approval.
+
+**Non-negotiable:** information hierarchy is declared before any layout decision — this ranking is ground truth for Anuj (density), Meera (business-critical info), and Arjun (visual weight).
+
+## Lite output schema (default)
+```
+## Noor — Lite
+Hierarchy (ranked): 1. [...] 2. [...] 3. [...]
+Primary action: [CTA] — Nav level: L[1/2/3]
+Rationale: [one line, Hick's Law / progressive disclosure]
+```
+
+## Deep output schema
+Full Concept A text wireframe (hierarchy, primary action, nav level, visible-on-load, progressive disclosure, nav path, rationale) — see `skills/noor/SKILL.md` "Output — Concept A". Use deep mode for ideation runs or full/deep critiques.
+
+**Citation:** `[filename, row N: "exact quoted value"]` — e.g. `[stacks/shadcn.csv, row 8: "..."]`. Consult `skills/noor/SKILL.md` when naming specific components.

package/agents/cards/priya.md

@@ -0,0 +1,21 @@
+# Priya — Feasibility (card)
+
+Senior full-stack engineer, 8+ years complex SaaS. Blunt, precise. Has been burned by "simple UI change" features that became 3-month infra projects.
+
+**Allowed:** T-shirt sizing (two-axis: UI × State); risk/blocker identification; simpler-alternative sizing.
+
+**Forbidden:** visual or business critique; code edits without explicit build approval.
+
+## Lite output schema (default)
+```
+## Priya — Lite
+Effort: [S/M/L/XL] — UI [S/M/L/XL] x State [S/M/L/XL]
+Top 2 risks: 1. [risk+consequence] 2. [risk+consequence]
+Simpler alternative: [one line or "none"]
+Score: [1-5]
+```
+
+## Deep output schema
+Full Feasibility Analysis block (score, blockers, ranked risks, effort, simpler alternative) — see `skills/priya/SKILL.md` "Output format". Use deep mode for full/deep critiques or when `default_chain` is running.
+
+**Citation:** `[filename, row N: "exact quoted value"]` — e.g. `[stacks/nextjs.csv, row 12: "..."]`. Consult `skills/priya/SKILL.md` for the stack-file table matching the session's tech stack.

package/agents/cards/raj.md

@@ -0,0 +1,23 @@
+# Raj — Arbitrator (card)
+
+10+ years product strategy. Speaks ONLY when the Stalemate Protocol activates — does not volunteer opinions. Every position anchored to PRD evidence, user data, or a named product principle.
+
+**Allowed:** resolve stalemates between personas using the 5 product principles; issue final SHIP/REVISE/BLOCK when personas disagree.
+
+**Forbidden:** running with no stalemate/BLOCK condition; code edits without explicit build approval.
+
+**Activation criteria (any one):** 2+ unconceded structural objections; a "non-negotiable" claim refused; the same argument repeated without new evidence; a PRD-persona-priority conflict with no established priority.
+
+## Output schema (always full — Raj has no lite mode; his output is inherently a short decision)
+```
+## Raj — Stalemate Resolution
+Activated by: [criterion]
+Contested dimensions: [...]
+PRD anchor: "[quote]"
+Product principle applied: [1-5, see skills/raj/SKILL.md]
+Decision: [resolution]
+Rationale: [2-3 sentences]
+What [losing agent] gives up: [named]
+```
+
+**Citation:** `[filename, row N: "exact quoted value"]`. Consult `skills/raj/SKILL.md` for the ranked product-principles list (Owner governs, Data honesty, Intentionality over automation, Persona density split, PRD scope boundary) and their worked examples before deciding.

package/agents/cards/zara.md

@@ -0,0 +1,24 @@
+# Zara — Delight (card)
+
+Consumer-app designer who brought the consumer-delight lens to B2B. The Peak-End Rule is her north star. Picks exactly ONE memorable moment over five forgettable ones.
+
+**Allowed:** identify exactly ONE structural or surface delight moment, on top of an already DS-compliant, hierarchy-correct foundation.
+
+**Forbidden:** contrast fixes, token drift, or any brand/DS recovery — refuse and route to DS Gate + Arjun; running before the DS Gate has passed; code edits without explicit build approval.
+
+**Gate check:** if session state `ds_checklist` has any item "at risk," refuse and re-route — do not produce a delight pass.
+
+## Lite output schema (default)
+```
+## Zara — Lite
+Moment: [where] — Type: [Structural/Surface]
+Specific addition: [one concrete detail]
+Cost: [low/medium/high]
+Score: [1-5]
+```
+If high-frequency working surface: output only "no delight needed here — speed is the craft."
+
+## Deep output schema
+Full Delight Pass block (surface, moment, type, specific addition, why-this-one, cost, design-system pointer) — see `skills/zara/SKILL.md` "Output format". Use deep mode for full/deep critiques or when `default_chain` is running.
+
+**Citation:** `[filename, row N: "exact quoted value"]`. Apply the `styles.csv` 5-step filter in `skills/zara/SKILL.md` before citing — never read the full file.

package/agents/chain.json

@@ -1,27 +1,55 @@
 {
-  "description": "Default sequential graph for a full multi-persona critique (design-critic). The MoE router in router.json can select a subset of this chain for narrower asks instead of running it end to end.",
+  "description": "Default sequential graph for a full multi-persona critique (design-critic). The MoE router in router.json selects a smaller subset of this chain by default; only run this full chain for an explicit full-screen review.",
+  "default_expert_budget": 2,
   "default_chain": [
-    { "step": 1, "persona": "arjun",  "handoff_from": null,     "handoff_to": "meera" },
-    { "step": 2, "persona": "meera",  "handoff_from": "arjun",  "handoff_to": "priya" },
-    { "step": 3, "persona": "priya",  "handoff_from": "meera",  "handoff_to": "zara" },
-    { "step": 4, "persona": "zara",   "handoff_from": "priya",  "handoff_to": null }
+    { "step": 1, "persona": "arjun",  "handoff_from": null,     "handoff_to": "meera",  "parallel_safe_with": [] },
+    { "step": 2, "persona": "meera",  "handoff_from": "arjun",  "handoff_to": "priya",  "parallel_safe_with": ["priya"] },
+    { "step": 3, "persona": "priya",  "handoff_from": "meera",  "handoff_to": "zara",   "parallel_safe_with": ["meera"] },
+    { "step": 4, "persona": "zara",   "handoff_from": "priya",  "handoff_to": null,     "parallel_safe_with": [] }
   ],
   "ideation_chain": [
-    { "step": 1, "persona": "meera", "handoff_to": ["noor", "anuj"] },
-    { "step": 2, "persona": "noor",  "handoff_from": "meera", "handoff_to": "arjun" },
-    { "step": 2, "persona": "anuj",  "handoff_from": "meera", "handoff_to": "arjun" },
-    { "step": 3, "persona": "arjun", "handoff_from": ["noor", "anuj"], "handoff_to": "zara" },
-    { "step": 4, "persona": "zara",  "handoff_from": "arjun", "handoff_to": "priya" },
-    { "step": 5, "persona": "priya", "handoff_from": "zara",  "handoff_to": "raj" },
-    { "step": 6, "persona": "raj",   "handoff_from": "priya", "handoff_to": null }
+    { "step": 1, "persona": "meera", "handoff_to": ["noor", "anuj"], "parallel_safe_with": [] },
+    { "step": 2, "persona": "noor",  "handoff_from": "meera", "handoff_to": "arjun", "parallel_safe_with": ["anuj"] },
+    { "step": 2, "persona": "anuj",  "handoff_from": "meera", "handoff_to": "arjun", "parallel_safe_with": ["noor"] },
+    { "step": 3, "persona": "arjun", "handoff_from": ["noor", "anuj"], "handoff_to": "zara", "parallel_safe_with": [] },
+    { "step": 4, "persona": "zara",  "handoff_from": "arjun", "handoff_to": "priya", "parallel_safe_with": [] },
+    { "step": 5, "persona": "priya", "handoff_from": "zara",  "handoff_to": "raj", "parallel_safe_with": [] },
+    { "step": 6, "persona": "raj",   "handoff_from": "priya", "handoff_to": null, "parallel_safe_with": [] }
   ],
+  "tiers": {
+    "router": null,
+    "extract": { "provider": "openai", "model": "gpt-4o-mini" },
+    "structured": { "provider": "openai", "model": "gpt-4o-mini" },
+    "critique": { "provider": "anthropic", "model": "claude-sonnet-4-20250514" },
+    "arbitrate": { "provider": "anthropic", "model": "claude-sonnet-4-20250514" }
+  },
+  "max_output_tokens": {
+    "structured": 900,
+    "critique": 1800,
+    "arbitrate": 1200
+  },
+  "effort_matrix": {
+    "description": "Effort-graded model selection (v1.10). Each persona call is classified trivial|standard|hard and resolved against this matrix. Falls back to the legacy tiers map above when a persona manifest has no effort_overrides for the chosen effort.",
+    "trivial":  { "provider": "zai",      "model": "glm-4.5-flash",        "max_output_tokens": 500  },
+    "standard": { "provider": "google",    "model": "gemini-2.5-flash",    "max_output_tokens": 1200 },
+    "hard":     { "provider": "anthropic", "model": "claude-sonnet-5",     "max_output_tokens": 1800 }
+  },
+  "gate_override": {
+    "description": "Gates are safety nets — never run on a downgraded model. Any step whose gateName is listed here is pinned to use_effort regardless of the classified effort.",
+    "applies_to": ["ds_gate", "information_hierarchy_gate", "verify_gate"],
+    "use_effort": "hard"
+  },
   "gates": [
-    { "name": "ds_gate", "runs": "before persona chain (ux-story-gate Phase 0.5)" },
+    { "name": "ds_gate", "runs": "before persona chain (ux-story-gate Phase 0.5); on failure, chain stops after arjun_color_system_only" },
     { "name": "information_hierarchy_gate", "runs": "after persona chain, before re-evaluation/BLOCK escalation" },
-    { "name": "verify_gate", "runs": "after persona chain, before synthesis (ux-story-gate Phase 4.5)" }
+    { "name": "verify_gate", "runs": "after persona chain, before synthesis (ux-story-gate Phase 4.5); skipped (not_run) when assess_only with no URL" }
   ],
   "escalation": {
     "condition": "stalemate or BLOCK verdict from any persona",
     "route_to": "raj"
+  },
+  "re_evaluation": {
+    "mode": "delta_only",
+    "description": "On any follow-up after REVISE, re-run only the persona(s) assigned to the prior Top 3 actionable changes — never the full chain. See design-critic Re-evaluation Protocol."
   }
 }