raven-mcp 1.2.0 → 1.3.1

package/README.md

@@ -2,15 +2,18 @@
 
 **Odin's ravens brought back knowledge of the world — Raven brings back design intelligence.**
 
-A design knowledge MCP server that Claude can query when generating UI. Five layers: principles, patterns, content design systems, business strategy, and design tokens.
+A design knowledge MCP server that Claude can query when generating UI. Eight layers: principles, patterns, content design systems, research methods, service design, brand/visual, business strategy, and design tokens.
 
 ## What it does
 
 Raven gives Claude access to a comprehensive design knowledge base:
 
-- **Principles** — Nielsen's 10 Heuristics, all 21 Laws of UX, Gestalt principles, WCAG accessibility, typography rules, color theory, mobile UX, D4D framework, and UX writing principles
-- **Patterns** — Proven UI patterns for signup flows, pricing pages, navigation, forms, landing pages, dashboards, modals, empty/error/loading states, CTAs, social proof, mobile conversion — plus content patterns for error messages, empty-state copy, notifications, and form validation
+- **Principles** — Nielsen's 10 Heuristics, all 21 Laws of UX, Gestalt principles, WCAG accessibility, typography rules, color theory, mobile UX, D4D framework, UX writing, service design, and brand
+- **Patterns** — Proven UI patterns for signup flows, pricing pages, navigation, forms, landing pages, dashboards, modals, empty/error/loading states, CTAs, social proof, mobile conversion — plus content patterns (error messages, empty-state copy, notifications, form validation) and service patterns (service blueprinting, human handoff, signup-as-service, omnichannel continuity, moments of truth)
 - **Content systems** — Voice & tone guides from real brands: Mailchimp, GOV.UK, Shopify Polaris, Atlassian, and Intuit
+- **Research** — Qualitative, quantitative, and usability methods with do/don't protocols and checklists. Metrics frameworks: HEART, AARRR/Pirate, North Star Metric, conversion funnel, RICE, OKRs.
+- **Service design** — Service blueprinting (with HTML blueprint generation — current vs. ideal state), human-handoff patterns, signup-as-service, omnichannel continuity, moments of truth / recovery, and the GOV.UK Service Standard
+- **Brand & visual** — Logo usage (clear space, min sizes, variants, placement, restraint), gradient usage (hierarchy, palette, contrast, trend vs signature), imagery (consistency, representation, purpose), visual hierarchy, brand-as-system, and current (2026) visual-design trends
 - **Business** — Monetization models, retention strategies, onboarding optimization, growth mechanics, and product metrics frameworks
 - **Tokens** — Design system tokens for Stripe, Linear, and more
 
@@ -64,8 +67,24 @@ cd raven-mcp && npm install && npm run build
 | `get_content_system` | Get a brand's voice attributes, tone shifts, vocabulary, grammar, and content patterns |
 | `get_content_principles` | Get UX-writing principles — clarity, active voice, error anatomy, inclusive language |
 | `get_content_pattern` | Get copy recipes for error messages, empty-state copy, notifications, form validation |
+| `get_research_method` | Get qualitative, quantitative, or usability research methods with protocols and checklists |
+| `get_metrics_framework` | Get a product-metrics framework — HEART, AARRR, North Star, conversion funnel, RICE, OKRs |
+| `get_service_pattern` | Get a service design pattern — blueprinting, human handoff, signup-as-service, omnichannel, moments of truth |
+| `get_service_standard` | Get the GOV.UK Service Standard — 14 points for evaluating service quality |
+| `generate_service_blueprint` | Render a service blueprint as HTML — current state, or current vs. ideal side-by-side |
+| `get_brand_principles` | Get brand/visual principles — logo, gradient, imagery, hierarchy, brand-as-system |
+| `get_brand_trends` | Get current (2026) brand and visual-design trends with usage guidance |
 | `raven_reflect` | Summarize your local Raven usage log to find patterns + gaps |
 
+## Release updates
+
+Raven ships new principles, patterns, and brand systems regularly. For one email per minor/major release (patches stay quiet):
+
+- **Web:** [ravenmcp.ai/#updates](https://ravenmcp.ai/#updates) — 10 seconds, one email field.
+- **In-product:** ask Claude *"register me for Raven updates at you@work.com"* — Claude calls `raven_register` and you're in.
+
+No marketing, unsubscribe anytime. Powered by Resend.
+
 ## Learning loop
 
 Raven keeps a small **local-only** log of how you use it so you (and Claude) can spot which patterns you build most often and which gaps show up again and again.
@@ -92,12 +111,23 @@ All knowledge lives in `src/data/` as static JSON files:
 
 ```
 src/data/
-  principles/   # Nielsen, Laws of UX, Gestalt, accessibility, typography, color, mobile, D4D
-  patterns/     # signup, pricing, nav, forms, landing, dashboard, modals, empty/error/loading, CTA, social proof, mobile
-  business/     # monetization, retention, onboarding, growth, metrics
-  tokens/       # registry.json + systems/ (stripe, linear, vercel, …)
-  content/      # voice & tone: Mailchimp, GOV.UK, Shopify Polaris, Atlassian, Intuit
-    systems/    # registry.json + brand-voice JSONs
-    principles/ # UX-writing principles (clarity, active voice, error anatomy, …)
-    patterns/   # copy recipes for errors, empty states, notifications, form validation
+  principles/      # Nielsen, Laws of UX, Gestalt, accessibility, typography, color, mobile, D4D
+  patterns/        # signup, pricing, nav, forms, landing, dashboard, modals, empty/error/loading, CTA, social proof, mobile
+  business/        # monetization, retention, onboarding, growth, metrics
+  tokens/          # registry.json + systems/ (stripe, linear, vercel, …)
+  content/         # voice & tone: Mailchimp, GOV.UK, Shopify Polaris, Atlassian, Intuit
+    systems/       # registry.json + brand-voice JSONs
+    principles/    # UX-writing principles (clarity, active voice, error anatomy, …)
+    patterns/      # copy recipes for errors, empty states, notifications, form validation
+  research/        # study protocols + metrics frameworks
+    principles/    # research fundamentals (method match, bias, sample size, ethics, triangulation, …)
+    methods/       # qualitative, quantitative, usability
+    frameworks/    # HEART, AARRR, North Star, conversion funnel, RICE, OKRs
+  service-design/  # service-level principles + patterns + frameworks
+    principles/    # Stickdorn, Shostack, peak-end, moments of truth, handoff
+    patterns/      # service blueprinting, human handoff, signup-as-service, omnichannel, moments of truth
+    frameworks/    # GOV.UK Service Standard (14 points)
+  brand/           # brand & visual design
+    principles/    # logo, gradient, imagery, hierarchy, brand-as-system
+    trends/        # 2026-current.json
 ```

package/dist/index.js

@@ -18,6 +18,17 @@ var CONTENT_DIR = join(DATA_DIR, "content");
 var CONTENT_SYSTEMS_DIR = join(CONTENT_DIR, "systems");
 var CONTENT_PRINCIPLES_DIR = join(CONTENT_DIR, "principles");
 var CONTENT_PATTERNS_DIR = join(CONTENT_DIR, "patterns");
+var RESEARCH_DIR = join(DATA_DIR, "research");
+var RESEARCH_PRINCIPLES_DIR = join(RESEARCH_DIR, "principles");
+var RESEARCH_METHODS_DIR = join(RESEARCH_DIR, "methods");
+var RESEARCH_FRAMEWORKS_DIR = join(RESEARCH_DIR, "frameworks");
+var SERVICE_DIR = join(DATA_DIR, "service-design");
+var SERVICE_PRINCIPLES_DIR = join(SERVICE_DIR, "principles");
+var SERVICE_PATTERNS_DIR = join(SERVICE_DIR, "patterns");
+var SERVICE_FRAMEWORKS_DIR = join(SERVICE_DIR, "frameworks");
+var BRAND_DIR = join(DATA_DIR, "brand");
+var BRAND_PRINCIPLES_DIR = join(BRAND_DIR, "principles");
+var BRAND_TRENDS_DIR = join(BRAND_DIR, "trends");
 // ── Data loading ────────────────────────────────────────────────────
 function loadJsonDir(dir) {
     if (!existsSync(dir))
@@ -50,6 +61,13 @@ function loadAllData() {
     // accessed via list_content_systems / get_content_system.
     allPrinciples = allPrinciples.concat(loadJsonDir(CONTENT_PRINCIPLES_DIR));
     allPatterns = allPatterns.concat(loadJsonDir(CONTENT_PATTERNS_DIR));
+    // Research / service-design / brand layers — principles follow the same
+    // schema and merge into allPrinciples. Service-design also contributes
+    // patterns. Research methods, research metrics frameworks, service
+    // frameworks, and brand trends use domain-specific shapes and are
+    // accessed through dedicated tools.
+    allPrinciples = allPrinciples.concat(loadJsonDir(RESEARCH_PRINCIPLES_DIR), loadJsonDir(SERVICE_PRINCIPLES_DIR), loadJsonDir(BRAND_PRINCIPLES_DIR));
+    allPatterns = allPatterns.concat(loadJsonDir(SERVICE_PATTERNS_DIR));
 }
 loadAllData();
 // ── Token helpers (from reference) ──────────────────────────────────
@@ -89,6 +107,10 @@ function getAvailableContentSystemIds() {
         .filter(f => f.endsWith(".json") && f !== "registry.json")
         .map(f => f.replace(".json", ""));
 }
+function loadResearchMethods() { return loadJsonDir(RESEARCH_METHODS_DIR); }
+function loadMetricsFrameworks() { return loadJsonDir(RESEARCH_FRAMEWORKS_DIR); }
+function loadServiceFrameworks() { return loadJsonDir(SERVICE_FRAMEWORKS_DIR); }
+function loadBrandTrends() { return loadJsonDir(BRAND_TRENDS_DIR); }
 function flattenTokens(obj, prefix) {
     var results = [];
     var parentType = obj["$type"];
@@ -444,6 +466,194 @@ function formatPrinciple(p, format) {
     }
     return p;
 }
+function escapeHtml(s) {
+    if (!s)
+        return "";
+    return s
+        .replace(/&/g, "&")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;")
+        .replace(/'/g, "&#39;");
+}
+function renderBlueprintSection(bp) {
+    var stepCount = bp.steps.length;
+    var twoActor = !!(bp.actors && bp.actors.b);
+    var labelA = (bp.actors && bp.actors.a && bp.actors.a.label) || "User";
+    var labelB = twoActor ? bp.actors.b.label : "";
+    var cols = bp.steps.map(function (s) {
+        return '<div class="step-header">' + escapeHtml(s.label) + '</div>';
+    }).join("");
+    function rowFromCells(title, accent, cells) {
+        return ('<div class="row">' +
+            '<div class="row-label ' + accent + '">' + title + '</div>' +
+            '<div class="row-cells" style="grid-template-columns: repeat(' + stepCount + ', minmax(0, 1fr));">' + cells + '</div>' +
+            '</div>');
+    }
+    function row(title, accent, field) {
+        var cells = bp.steps.map(function (s) {
+            var content = s[field];
+            return content
+                ? '<div class="cell">' + escapeHtml(content) + '</div>'
+                : '<div class="cell cell-empty"></div>';
+        }).join("");
+        return rowFromCells(title, accent, cells);
+    }
+    function actorBRow(title, accent, field) {
+        var cells = bp.steps.map(function (s) {
+            var content = s.actor_b ? s.actor_b[field] : undefined;
+            return content
+                ? '<div class="cell">' + escapeHtml(content) + '</div>'
+                : '<div class="cell cell-empty"></div>';
+        }).join("");
+        return rowFromCells(title, accent, cells);
+    }
+    // Pain/delight row is merged — one cell per step
+    var pdCells = bp.steps.map(function (s) {
+        if (s.pain_point)
+            return '<div class="cell pain"><span class="tag tag-pain">Pain</span>' + escapeHtml(s.pain_point) + '</div>';
+        if (s.delight)
+            return '<div class="cell delight"><span class="tag tag-delight">Moment</span>' + escapeHtml(s.delight) + '</div>';
+        return '<div class="cell cell-empty"></div>';
+    }).join("");
+    var body;
+    if (twoActor) {
+        // Simple person silhouette avatars — Actor A plain, Actor B with a
+        // subtle collar/V to distinguish. Both tint to their lane color.
+        // Distinct role icons: User = a person silhouette; Expert = a
+        // briefcase (universal shorthand for professional work, reads
+        // across law / medicine / finance / real estate / advising).
+        var avatarA = '<span class="lane-avatar-wrap">' +
+            '<svg class="lane-avatar" viewBox="0 0 24 24" fill="currentColor" aria-hidden="true">' +
+            '<circle cx="12" cy="9" r="4"/>' +
+            '<path d="M4 21c0-4 3.6-6.5 8-6.5s8 2.5 8 6.5v1H4z"/>' +
+            '</svg>' +
+            '</span>';
+        var avatarB = '<span class="lane-avatar-wrap">' +
+            '<svg class="lane-avatar" viewBox="0 0 24 24" fill="currentColor" aria-hidden="true">' +
+            '<path d="M9 5h6a1 1 0 0 1 1 1v2h-8V6a1 1 0 0 1 1-1zm-5 5h16a1 1 0 0 1 1 1v7a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2v-7a1 1 0 0 1 1-1zm8 3a1 1 0 0 0-1 1v1h2v-1a1 1 0 0 0-1-1z"/>' +
+            '</svg>' +
+            '</span>';
+        // Two-actor / HI-loop layout:
+        // Actor A (above line of interaction), Actor B (below), then line of visibility, backstage, support.
+        body =
+            '<div class="swim-lane lane-a">' +
+                '<div class="lane-label lane-label-a">' + avatarA + '<span>' + escapeHtml(labelA) + '</span></div>' +
+                row("Physical evidence", "row-evidence", "evidence") +
+                row("Actions", "row-user", "user_action") +
+                row("Frontstage (sees)", "row-frontstage", "frontstage") +
+                '</div>' +
+                '<div class="line-of-interaction">Line of interaction</div>' +
+                '<div class="swim-lane lane-b">' +
+                '<div class="lane-label lane-label-b">' + avatarB + '<span>' + escapeHtml(labelB) + '</span></div>' +
+                actorBRow("Physical evidence", "row-evidence", "evidence") +
+                actorBRow("Actions", "row-user", "action") +
+                actorBRow("Frontstage (sees)", "row-frontstage", "frontstage") +
+                '</div>' +
+                '<div class="line-of-visibility">Line of visibility</div>' +
+                row("Backstage", "row-backstage", "backstage") +
+                row("Support processes", "row-support", "support") +
+                rowFromCells("Pain / moments", "row-pain", pdCells);
+    }
+    else {
+        body =
+            row("Physical evidence", "row-evidence", "evidence") +
+                row("User actions", "row-user", "user_action") +
+                row("Frontstage", "row-frontstage", "frontstage") +
+                '<div class="line-of-visibility">Line of visibility</div>' +
+                row("Backstage", "row-backstage", "backstage") +
+                row("Support processes", "row-support", "support") +
+                rowFromCells("Pain / moments", "row-pain", pdCells);
+    }
+    return ('<section class="blueprint' + (twoActor ? ' two-actor' : '') + '">' +
+        (bp.state_label ? '<h2 class="state-label">' + escapeHtml(bp.state_label) + '</h2>' : '') +
+        '<div class="steps-header" style="grid-template-columns: 180px repeat(' + stepCount + ', minmax(0, 1fr));">' +
+        '<div class="row-label empty-label">Step</div>' +
+        cols +
+        '</div>' +
+        body +
+        '</section>');
+}
+function generateServiceBlueprintHtml(current, ideal) {
+    var subtitle = current.subtitle ? '<p class="subtitle">' + escapeHtml(current.subtitle) + '</p>' : '';
+    var currentBlueprint = renderBlueprintSection({
+        ...current,
+        state_label: current.state_label || (ideal ? "Current state" : undefined)
+    });
+    var idealBlueprint = ideal
+        ? renderBlueprintSection({
+            ...ideal,
+            service_name: current.service_name,
+            state_label: ideal.state_label || "Ideal state"
+        })
+        : "";
+    var css = ':root {' +
+        '--bg-base:#1a1a22;--bg-surface:#212129;--bg-raised:#2a2a33;--bg-alt:#16161e;' +
+        '--border:rgba(255,255,255,0.08);--border-strong:rgba(255,255,255,0.12);' +
+        '--text-primary:#F0F0F2;--text-secondary:#9498A0;--text-tertiary:#5C5F68;' +
+        '--accent-blue:#00BFFF;--accent-green:#00E676;--accent-orange:#FFAB40;--accent-pink:#FF4081;--accent-purple:#B388FF;' +
+        '--font-body:"Inter",-apple-system,BlinkMacSystemFont,"Segoe UI",sans-serif;' +
+        '}' +
+        '*{margin:0;padding:0;box-sizing:border-box}' +
+        'body{font-family:var(--font-body);background:var(--bg-base);color:var(--text-primary);padding:48px 24px;line-height:1.5;font-size:14px;-webkit-font-smoothing:antialiased}' +
+        '.container{max-width:1600px;margin:0 auto}' +
+        'header{margin-bottom:48px;padding-bottom:24px;border-bottom:1px solid var(--border)}' +
+        'header .eyebrow{font-size:11px;letter-spacing:0.12em;text-transform:uppercase;color:var(--accent-blue);font-weight:700;margin-bottom:8px}' +
+        'header h1{font-size:32px;font-weight:800;letter-spacing:-0.02em;margin-bottom:8px}' +
+        'header .subtitle{color:var(--text-secondary);font-size:16px;max-width:720px}' +
+        '.blueprint{margin-bottom:64px}' +
+        '.state-label{font-size:18px;font-weight:700;color:var(--text-primary);margin-bottom:16px;padding-bottom:8px;border-bottom:1px solid var(--border)}' +
+        '.steps-header{display:grid;gap:8px;margin-bottom:12px}' +
+        '.step-header{background:var(--bg-raised);padding:12px 14px;font-weight:700;font-size:13px;border-radius:10px;border:1px solid var(--border);text-align:center}' +
+        '.row{display:grid;grid-template-columns:180px 1fr;gap:8px;margin-bottom:8px;align-items:stretch}' +
+        '.row-label{padding:12px 14px;font-size:11px;font-weight:700;letter-spacing:0.08em;text-transform:uppercase;border-radius:10px;display:flex;align-items:center;min-height:72px}' +
+        '.row-evidence{background:rgba(179,136,255,0.08);color:var(--accent-purple);border:1px solid rgba(179,136,255,0.18)}' +
+        '.row-user{background:rgba(0,191,255,0.08);color:var(--accent-blue);border:1px solid rgba(0,191,255,0.18)}' +
+        '.row-frontstage{background:rgba(0,230,118,0.08);color:var(--accent-green);border:1px solid rgba(0,230,118,0.18)}' +
+        '.row-backstage{background:rgba(255,171,64,0.08);color:var(--accent-orange);border:1px solid rgba(255,171,64,0.18)}' +
+        '.row-support{background:rgba(255,64,129,0.06);color:var(--accent-pink);border:1px solid rgba(255,64,129,0.14)}' +
+        '.row-pain{background:rgba(255,255,255,0.04);color:var(--text-secondary);border:1px solid var(--border)}' +
+        '.swim-lane{padding:18px 18px 14px;position:relative;border-radius:14px;margin-bottom:4px}' +
+        '.lane-a{background:rgba(0,191,255,0.04);border:1px solid rgba(0,191,255,0.15);border-left:4px solid var(--accent-blue)}' +
+        '.lane-b{background:rgba(255,171,64,0.04);border:1px solid rgba(255,171,64,0.15);border-left:4px solid var(--accent-orange)}' +
+        '.lane-label{font-size:11px;font-weight:700;letter-spacing:0.14em;text-transform:uppercase;color:var(--text-tertiary);margin-bottom:14px;display:inline-flex;align-items:center;gap:10px;padding:6px 16px 6px 6px;border-radius:9999px;background:rgba(255,255,255,0.05);border:1px solid var(--border)}' +
+        '.lane-avatar-wrap{width:28px;height:28px;border-radius:9999px;display:inline-flex;align-items:center;justify-content:center;flex-shrink:0}' +
+        '.lane-avatar{width:20px;height:20px}' +
+        '.lane-label-a .lane-avatar-wrap{background:var(--accent-blue)}' +
+        '.lane-label-b .lane-avatar-wrap{background:var(--accent-orange)}' +
+        '.lane-label-a .lane-avatar{color:var(--bg-base)}' +
+        '.lane-label-b .lane-avatar{color:var(--bg-base)}' +
+        '.lane-label-a{color:var(--accent-blue);background:rgba(0,191,255,0.12);border-color:rgba(0,191,255,0.28)}' +
+        '.lane-label-b{color:var(--accent-orange);background:rgba(255,171,64,0.12);border-color:rgba(255,171,64,0.28)}' +
+        '.line-of-interaction{text-align:center;font-size:11px;font-weight:700;letter-spacing:0.14em;text-transform:uppercase;color:var(--text-primary);padding:14px 0;border-top:2px solid var(--border-strong);border-bottom:2px solid var(--border-strong);margin:10px 0;background:linear-gradient(90deg,rgba(0,191,255,0.10),rgba(255,171,64,0.10))}' +
+        '.empty-label{background:transparent;border:1px dashed var(--border);color:var(--text-tertiary)}' +
+        '.row-cells{display:grid;gap:8px}' +
+        '.cell{background:var(--bg-surface);border:1px solid var(--border);border-radius:10px;padding:12px 14px;font-size:13px;color:var(--text-primary);min-height:72px;display:flex;flex-direction:column;gap:6px}' +
+        '.cell.pain{background:rgba(255,64,129,0.08);border-color:rgba(255,64,129,0.22)}' +
+        '.cell.delight{background:rgba(0,230,118,0.08);border-color:rgba(0,230,118,0.22)}' +
+        '.cell.cell-empty{background:transparent;border:none;padding:0;min-height:72px}' +
+        '.tag{display:inline-block;font-size:10px;font-weight:700;letter-spacing:0.06em;text-transform:uppercase;padding:2px 8px;border-radius:9999px;width:fit-content}' +
+        '.tag-pain{background:rgba(255,64,129,0.18);color:var(--accent-pink)}' +
+        '.tag-delight{background:rgba(0,230,118,0.18);color:var(--accent-green)}' +
+        '.line-of-visibility{text-align:center;font-size:11px;font-weight:700;letter-spacing:0.14em;text-transform:uppercase;color:var(--text-tertiary);padding:14px 0;border-top:2px dashed var(--border-strong);border-bottom:2px dashed var(--border-strong);margin:14px 0}' +
+        'footer{margin-top:48px;padding-top:24px;border-top:1px solid var(--border);color:var(--text-tertiary);font-size:12px;text-align:center}';
+    var html = '<!DOCTYPE html><html lang="en"><head><meta charset="UTF-8"><meta name="viewport" content="width=device-width,initial-scale=1.0">' +
+        '<title>Service blueprint &mdash; ' + escapeHtml(current.service_name) + '</title>' +
+        '<link rel="preconnect" href="https://fonts.googleapis.com"><link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>' +
+        '<link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700;800&display=swap" rel="stylesheet">' +
+        '<style>' + css + '</style>' +
+        '</head><body><div class="container">' +
+        '<header>' +
+        '<div class="eyebrow">Service blueprint</div>' +
+        '<h1>' + escapeHtml(current.service_name) + '</h1>' +
+        subtitle +
+        '</header>' +
+        currentBlueprint +
+        idealBlueprint +
+        '<footer>Generated by Raven &middot; frontstage / line of visibility / backstage &middot; Shostack-Stickdorn</footer>' +
+        '</div></body></html>';
+    return html;
+}
 // ── Update check ────────────────────────────────────────────────────
 // On startup, fetch the latest published version from npm and compare against
 // our own. Minor/major bumps get surfaced via stderr + injected into the first
@@ -597,6 +807,32 @@ function extractInsight(toolName, input, output) {
             case "get_content_pattern":
                 insight = { type: input?.type };
                 break;
+            case "get_research_method":
+                insight = { category: input?.category, search: !!input?.search };
+                break;
+            case "get_metrics_framework":
+                insight = { id: input?.id, search: !!input?.search };
+                break;
+            case "get_service_pattern":
+                insight = { type: input?.type };
+                break;
+            case "get_service_standard":
+                insight = { action: "service-standard" };
+                break;
+            case "generate_service_blueprint":
+                insight = {
+                    has_ideal: Array.isArray(input?.ideal),
+                    current_steps: Array.isArray(input?.current) ? input.current.length : 0,
+                    ideal_steps: Array.isArray(input?.ideal) ? input.ideal.length : 0,
+                    two_actor: !!(input?.actors && input.actors.b)
+                };
+                break;
+            case "get_brand_principles":
+                insight = { topic: safeStr(input?.topic, 32), format: input?.format };
+                break;
+            case "get_brand_trends":
+                insight = { action: "trends" };
+                break;
             case "generate_design_system":
                 insight = { style: input?.style, has_brand_color: !!input?.brand_color, format: input?.format };
                 break;
@@ -2271,6 +2507,147 @@ server.tool("get_content_pattern", "Get content design patterns — copy recipes
             }]
     };
 });
+// ── Research / service-design / brand tools ───────────────────────
+server.tool("get_research_method", "Get research method details — qualitative (interviews, contextual inquiry, diary, field, intercept), quantitative (surveys, analytics, A/B tests, benchmarking, clickstream), or usability (moderated, unmoderated, 5-second, card sort, tree test, heuristic eval). Returns specific protocols, do/don't guidance, evidence, and a checklist. Use when the user is designing a study or asking how to measure something.", {
+    category: z.enum(["qualitative", "quantitative", "usability", "all"]).optional().describe("Which family of methods. Default: all."),
+    search: z.string().optional().describe("Search within methods by name or description.")
+}, async ({ category, search }) => {
+    var methods = loadResearchMethods();
+    var result = methods;
+    if (category && category !== "all") {
+        result = methods.filter((m) => m.id && m.id.startsWith(category));
+    }
+    if (search) {
+        var q = search.toLowerCase();
+        result = result.filter((m) => (m.name && m.name.toLowerCase().includes(q)) ||
+            (m.summary && m.summary.toLowerCase().includes(q)) ||
+            (m.patterns && m.patterns.some((p) => (p.name && p.name.toLowerCase().includes(q)) ||
+                (p.description && p.description.toLowerCase().includes(q)))));
+    }
+    return {
+        content: [{
+                type: "text",
+                text: JSON.stringify({ count: result.length, methods: result }, null, 2)
+            }]
+    };
+});
+server.tool("get_metrics_framework", "Get a product-metrics framework — HEART (Google), AARRR/Pirate (Dave McClure), North Star Metric, Conversion Funnel, RICE Scoring, or OKRs. Returns structure, when-to-use, pitfalls, and examples. Use when the user asks 'how should we measure success?' or 'what metrics should we track?'", {
+    id: z.string().optional().describe("Framework id (heart, aarrr, north-star-metric, conversion-funnel, rice-scoring, okrs). Omit to list all."),
+    search: z.string().optional().describe("Search for a framework by name or summary.")
+}, async ({ id, search }) => {
+    var frameworks = loadMetricsFrameworks();
+    var flat = [];
+    for (var file of frameworks) {
+        if (Array.isArray(file?.frameworks))
+            flat = flat.concat(file.frameworks.map((f) => ({ ...f, source_file: file.id })));
+    }
+    if (id) {
+        var match = flat.find(f => f.id === id);
+        if (!match) {
+            return { content: [{ type: "text", text: "Framework '" + id + "' not found. Available: " + flat.map(f => f.id).join(", ") }] };
+        }
+        return { content: [{ type: "text", text: JSON.stringify(match, null, 2) }] };
+    }
+    if (search) {
+        var q = search.toLowerCase();
+        flat = flat.filter(f => (f.name && f.name.toLowerCase().includes(q)) || (f.summary && f.summary.toLowerCase().includes(q)));
+    }
+    return { content: [{ type: "text", text: JSON.stringify({ count: flat.length, frameworks: flat }, null, 2) }] };
+});
+server.tool("get_service_pattern", "Get a service design pattern — service blueprinting, human handoff, signup-as-service, omnichannel continuity, or moments of truth / recovery. Returns patterns, do/don't guidance, evidence, and a checklist. Use when the user is designing a service flow, escalation, cross-channel experience, or moment of truth.", {
+    type: z.enum(["service-blueprinting", "human-handoff", "signup-as-service", "omnichannel-continuity", "moments-of-truth"]).describe("Service design pattern type")
+}, async ({ type }) => {
+    var pattern = allPatterns.find(p => p.id === type && p.category === "service-design");
+    if (!pattern) {
+        return {
+            content: [{
+                    type: "text",
+                    text: "Service pattern '" + type + "' not found. Available: service-blueprinting, human-handoff, signup-as-service, omnichannel-continuity, moments-of-truth."
+                }]
+        };
+    }
+    return { content: [{ type: "text", text: JSON.stringify(pattern, null, 2) }] };
+});
+server.tool("get_service_standard", "Get the GOV.UK Service Standard — 14 points the UK government uses to assess whether a public service is ready to launch. Widely applicable as a rigorous service-quality checklist beyond government. Use when the user asks how to evaluate a whole service.", {}, async () => {
+    var frameworks = loadServiceFrameworks();
+    var govuk = frameworks.find((f) => f.id === "gov-uk-service-standard");
+    if (!govuk) {
+        return { content: [{ type: "text", text: "GOV.UK service standard not found." }] };
+    }
+    return { content: [{ type: "text", text: JSON.stringify(govuk, null, 2) }] };
+});
+server.tool("generate_service_blueprint", "Render a service blueprint as a self-contained HTML page. Supports two modes: (1) classic Shostack single-actor blueprint — user action, frontstage, backstage, support, evidence, pain/delight; (2) two-actor HI-loop blueprint — when `actors` is supplied, renders two swim lanes with a line of interaction between them (e.g. customer ↔ lawyer, patient ↔ doctor, buyer ↔ agent). Each actor gets their own actions, frontstage (what they see), and evidence. Optionally accepts an ideal-state to render side-by-side with the current state.", {
+    service_name: z.string().describe("Name of the service (e.g. 'Free trial signup', 'Client intake', 'Restaurant reservation')"),
+    subtitle: z.string().optional().describe("Short description or context line under the title"),
+    actors: z.object({
+        a: z.object({ label: z.string() }).optional().describe("Actor A label (default: 'User'). Use when you want to name the first side (e.g. 'Customer', 'Patient')."),
+        b: z.object({ label: z.string() }).describe("Actor B label (e.g. 'Lawyer', 'Doctor', 'Agent'). Presence of this field switches to two-actor layout.")
+    }).optional().describe("Omit for classic single-actor Shostack blueprint. Provide to render a two-swim-lane HI-loop blueprint with a line of interaction between the two sides."),
+    current: z.array(z.object({
+        label: z.string().describe("Step label (e.g. 'Discover', 'Sign up', 'First use')"),
+        user_action: z.string().optional().describe("In single-actor: what the user does. In two-actor: what actor A does."),
+        frontstage: z.string().optional().describe("In single-actor: what the user SEES (UI, agent greeting). In two-actor: what actor A sees."),
+        backstage: z.string().optional().describe("What neither actor sees directly — shared systems, internal processes, back-office work"),
+        support: z.string().optional().describe("Supporting processes, systems, third-party dependencies"),
+        evidence: z.string().optional().describe("In single-actor: artifact user receives. In two-actor: artifact actor A has."),
+        pain_point: z.string().optional().describe("Known pain point at this step (shown as red callout)"),
+        delight: z.string().optional().describe("Designed moment of delight at this step (shown as green callout)"),
+        actor_b: z.object({
+            action: z.string().optional().describe("What actor B does in this step"),
+            frontstage: z.string().optional().describe("What actor B sees — their own UI, tools, views"),
+            evidence: z.string().optional().describe("Artifact actor B has — case file, notes, record")
+        }).optional().describe("Only used when `actors.b` is provided. Captures the other side of the interaction.")
+    })).describe("The current-state blueprint as an array of steps"),
+    ideal: z.array(z.object({
+        label: z.string(),
+        user_action: z.string().optional(),
+        frontstage: z.string().optional(),
+        backstage: z.string().optional(),
+        support: z.string().optional(),
+        evidence: z.string().optional(),
+        pain_point: z.string().optional(),
+        delight: z.string().optional(),
+        actor_b: z.object({
+            action: z.string().optional(),
+            frontstage: z.string().optional(),
+            evidence: z.string().optional()
+        }).optional()
+    })).optional().describe("Optional ideal-state blueprint — if provided, output shows current AND ideal side-by-side")
+}, async ({ service_name, subtitle, actors, current, ideal }) => {
+    var html = generateServiceBlueprintHtml({ service_name, subtitle, steps: current, actors: actors }, ideal ? { service_name, steps: ideal, actors: actors } : null);
+    return { content: [{ type: "text", text: html }] };
+});
+server.tool("get_brand_principles", "Get brand and visual-design principles — logo usage (clear space, min sizes, variants, placement, restraint), gradient usage (hierarchy, palette, contrast, trend vs signature), imagery (consistency, representation, purpose), visual hierarchy, and brand-as-system thinking. Use when the user asks about branding, logos, gradients, imagery, visual consistency, or how to treat a brand across surfaces.", {
+    topic: z.string().optional().describe("Filter by topic: 'logo', 'gradient', 'imagery', 'hierarchy', 'system', or a freeform search term. Omit to return all brand principles."),
+    format: z.enum(["full", "checklist", "brief"]).optional().describe("Output format. Default: full.")
+}, async ({ topic, format }) => {
+    var fmt = format || "full";
+    var brand = allPrinciples.filter(p => p.category === "brand");
+    var results = brand;
+    if (topic) {
+        var q = topic.toLowerCase();
+        results = brand.filter(p => {
+            var idMatch = p.id.toLowerCase().includes(q);
+            var nameMatch = p.name.toLowerCase().includes(q);
+            var appliesMatch = p.applies_to ? matchesTags(p.applies_to, topic) : false;
+            var textMatch = textSearch(p.name + " " + p.summary + " " + p.description, topic);
+            return idMatch || nameMatch || appliesMatch || textMatch;
+        });
+        if (results.length === 0)
+            results = brand;
+    }
+    var formatted = results.map(p => formatPrinciple(p, fmt));
+    return {
+        content: [{
+                type: "text",
+                text: JSON.stringify({ topic: topic || "all brand principles", count: formatted.length, principles: formatted }, null, 2)
+            }]
+    };
+});
+server.tool("get_brand_trends", "Get current brand and visual-design trends — what's working in 2026 and where each trend fits or fails. Includes bento grids, monospace type, neon-on-dark-glass, generative patterns, brutalism rebound, AI-generated imagery, lowercase/mixed case. Each trend is time-stamped — treat as a calibration signal, not a prescription.", {}, async () => {
+    var trends = loadBrandTrends();
+    return { content: [{ type: "text", text: JSON.stringify({ count: trends.length, trends: trends }, null, 2) }] };
+});
 // ── Reflection ─────────────────────────────────────────────────────
 // Summarize the local usage log so the user (or Claude acting on their
 // behalf) can see what Raven is being asked to do, and what it's often