@caoscompanybr/merlin 3.5.0

package/.merlin-core/skills/general/load-testing/scripts/compare_baseline.py

@@ -0,0 +1,172 @@
+#!/usr/bin/env python3
+"""Compare Locust run CSV against a baseline JSON.
+
+Exit codes:
+    0 -- no regression (all endpoints within tolerance, or ignored by noise floor)
+    1 -- regression detected (at least one endpoint exceeded 20% over baseline)
+    2 -- baseline absent/placeholder (baseline file written, soft-fail)
+
+Policy:
+    regression delta = (current_p95 - baseline_p95) / baseline_p95
+    Ignore endpoints where baseline_p95_ms < NOISE_FLOOR_MS (default 50)
+    FAIL if any eligible endpoint has delta > REGRESSION_THRESHOLD (default 0.20)
+"""
+from __future__ import annotations
+
+import argparse
+import csv
+import datetime
+import json
+import pathlib
+import sys
+
+
+NOISE_FLOOR_MS = 50.0
+REGRESSION_THRESHOLD = 0.20
+
+
+def read_stats_csv(path: pathlib.Path) -> dict[str, dict[str, float]]:
+    """Return per-endpoint metrics keyed by request name."""
+    out: dict[str, dict[str, float]] = {}
+    with path.open("r", newline="", encoding="utf-8") as f:
+        reader = csv.DictReader(f)
+        for row in reader:
+            name = row.get("Name") or ""
+            if name in ("", "Aggregated"):
+                continue
+
+            def _num(key: str) -> float:
+                raw = row.get(key)
+                try:
+                    return float(raw) if raw not in (None, "", "N/A") else 0.0
+                except ValueError:
+                    return 0.0
+
+            req_count = _num("Request Count")
+            fail_count = _num("Failure Count")
+            out[name] = {
+                "p50_ms": _num("50%"),
+                "p95_ms": _num("95%"),
+                "p99_ms": _num("99%"),
+                "rps": _num("Requests/s"),
+                "fail_ratio": (fail_count / req_count) if req_count > 0 else 0.0,
+            }
+    return out
+
+
+def is_placeholder_baseline(data: dict) -> bool:
+    endpoints = data.get("endpoints") or {}
+    return not isinstance(endpoints, dict) or len(endpoints) == 0
+
+
+def write_baseline(
+    path: pathlib.Path,
+    stats: dict[str, dict[str, float]],
+    runtime_s: int | None = None,
+) -> None:
+    payload = {
+        "schema_version": 1,
+        "target": "dashboard",
+        "captured_at": datetime.datetime.now(datetime.timezone.utc).isoformat().replace("+00:00", "Z"),
+        "locust_version": None,
+        "config": {"users": None, "spawn_rate": None, "runtime_s": runtime_s},
+        "endpoints": {
+            name: {
+                "p50_ms": round(m["p50_ms"]),
+                "p95_ms": round(m["p95_ms"]),
+                "p99_ms": round(m["p99_ms"]),
+                "rps": round(m["rps"], 2),
+                "fail_ratio": round(m["fail_ratio"], 6),
+            }
+            for name, m in stats.items()
+        },
+    }
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(payload, indent=2), encoding="utf-8")
+
+
+def compare(
+    current: dict[str, dict[str, float]],
+    baseline: dict[str, dict[str, float]],
+) -> tuple[bool, list[str]]:
+    regressions: list[str] = []
+    lines: list[str] = []
+    lines.append("| Endpoint | Baseline p95 | Current p95 | Delta | Verdict |")
+    lines.append("| --- | --- | --- | --- | --- |")
+    for name, base_m in baseline.items():
+        base_p95 = float(base_m.get("p95_ms") or 0)
+        cur = current.get(name)
+        if cur is None:
+            lines.append(f"| {name} | {base_p95:.0f} | -- | -- | SKIP (missing) |")
+            continue
+        cur_p95 = cur["p95_ms"]
+        if base_p95 < NOISE_FLOOR_MS:
+            lines.append(f"| {name} | {base_p95:.0f} | {cur_p95:.0f} | -- | SKIP (<{NOISE_FLOOR_MS:.0f}ms noise floor) |")
+            continue
+        delta = (cur_p95 - base_p95) / base_p95 if base_p95 > 0 else 0
+        verdict = "PASS"
+        if delta > REGRESSION_THRESHOLD:
+            verdict = "FAIL"
+            regressions.append(f"{name}: {base_p95:.0f}ms → {cur_p95:.0f}ms ({delta:+.1%})")
+        lines.append(f"| {name} | {base_p95:.0f} | {cur_p95:.0f} | {delta:+.1%} | {verdict} |")
+    ok = not regressions
+    return ok, lines
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Compare a Locust run against a baseline.")
+    parser.add_argument("--stats", required=True, help="Path to run_stats.csv (Locust --csv output)")
+    parser.add_argument(
+        "--baseline",
+        default=str(pathlib.Path("tests") / "benchmarks" / "baseline.dashboard.json"),
+        help="Path to baseline JSON",
+    )
+    parser.add_argument("--accept", action="store_true", help="Overwrite baseline with current run")
+    args = parser.parse_args()
+
+    stats_path = pathlib.Path(args.stats)
+    baseline_path = pathlib.Path(args.baseline)
+
+    if not stats_path.exists():
+        print(f"ERROR: stats file not found: {stats_path}", file=sys.stderr)
+        return 2
+
+    current = read_stats_csv(stats_path)
+
+    if args.accept:
+        write_baseline(baseline_path, current)
+        print(f"Baseline written to {baseline_path}")
+        print(f"Endpoints captured: {len(current)}")
+        return 0
+
+    if not baseline_path.exists():
+        print(f"No baseline at {baseline_path} — writing initial baseline from this run.")
+        write_baseline(baseline_path, current)
+        return 2
+
+    try:
+        baseline_data = json.loads(baseline_path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as exc:
+        print(f"ERROR: baseline JSON invalid: {exc}", file=sys.stderr)
+        return 2
+
+    if is_placeholder_baseline(baseline_data):
+        print("Placeholder baseline detected (endpoints: {}). Writing initial baseline from this run.")
+        write_baseline(baseline_path, current)
+        return 2
+
+    baseline = baseline_data.get("endpoints", {})
+    ok, report_lines = compare(current, baseline)
+    for line in report_lines:
+        print(line)
+
+    if ok:
+        print("regression_ok=true; no endpoints regressed beyond threshold")
+        return 0
+    else:
+        print(f"regression_ok=false; {len(report_lines)} line(s) report regressions")
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/.merlin-core/skills/general/load-testing/scripts/run_local.py

@@ -0,0 +1,245 @@
+#!/usr/bin/env python3
+"""Local runner for the load-testing skill.
+
+Spawns the Dashboard backend (if --host is localhost), runs Locust headless
+against it, writes CSV/HTML/summary artefacts under .ai/load-tests/<timestamp>/,
+then invokes compare_baseline.py to check for regressions. The latest run's
+summary is also written to .ai/load-tests/LATEST.json for the Layer 2 PR gate.
+
+Exit codes:
+    0 -- success (thresholds met, no regression)
+    1 -- threshold breach (from threshold_hook via Locust exit code)
+    2 -- regression detected by compare_baseline.py
+    3 -- infrastructure error (backend didn't start, etc.)
+"""
+from __future__ import annotations
+
+import argparse
+import datetime
+import json
+import os
+import pathlib
+import shutil
+import signal
+import socket
+import subprocess
+import sys
+import time
+
+
+REPO_ROOT = pathlib.Path(__file__).resolve().parents[5]
+SKILL_ROOT = REPO_ROOT / ".merlin-core" / "skills" / "general" / "load-testing"
+TEMPLATES_DIR = SKILL_ROOT / "templates"
+LOCUSTFILE = TEMPLATES_DIR / "locustfile_dashboard.py"
+COMPARE_SCRIPT = SKILL_ROOT / "scripts" / "compare_baseline.py"
+DEFAULT_BASELINE = REPO_ROOT / "tests" / "benchmarks" / "baseline.dashboard.json"
+OUT_ROOT = REPO_ROOT / ".ai" / "load-tests"
+
+
+def wait_for_port(port: int, host: str = "localhost", timeout: int = 30) -> bool:
+    start = time.time()
+    while time.time() - start < timeout:
+        try:
+            with socket.create_connection((host, port), timeout=1):
+                return True
+        except (ConnectionRefusedError, OSError):
+            time.sleep(0.5)
+    return False
+
+
+def spawn_backend(port: int) -> subprocess.Popen:
+    backend_dir = REPO_ROOT / "dashboard" / "backend"
+    entrypoint = backend_dir / "dist" / "index.js"
+    if not entrypoint.exists():
+        raise FileNotFoundError(
+            f"Dashboard backend build missing at {entrypoint}. "
+            "Run `npm --prefix dashboard/backend run build` first."
+        )
+    env = os.environ.copy()
+    env["PORT"] = str(port)
+    env["NODE_ENV"] = "test"
+    return subprocess.Popen(
+        ["node", str(entrypoint)],
+        cwd=str(backend_dir),
+        env=env,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.STDOUT,
+        preexec_fn=os.setsid if hasattr(os, "setsid") else None,
+    )
+
+
+def stop_process(proc: subprocess.Popen | None) -> None:
+    if proc is None or proc.poll() is not None:
+        return
+    try:
+        if hasattr(os, "killpg"):
+            os.killpg(os.getpgid(proc.pid), signal.SIGTERM)
+        else:
+            proc.terminate()
+        proc.wait(timeout=5)
+    except (ProcessLookupError, subprocess.TimeoutExpired):
+        if hasattr(os, "killpg"):
+            os.killpg(os.getpgid(proc.pid), signal.SIGKILL)
+        else:
+            proc.kill()
+
+
+def find_locust_executable() -> str:
+    which = shutil.which("locust")
+    if which:
+        return which
+    venv_bin = (
+        SKILL_ROOT / ".venv" / ("Scripts" if os.name == "nt" else "bin") / ("locust.exe" if os.name == "nt" else "locust")
+    )
+    if venv_bin.exists():
+        return str(venv_bin)
+    raise FileNotFoundError(
+        "Could not find `locust` on PATH or in the skill venv. "
+        f"Run `pip install -r {SKILL_ROOT / 'requirements.txt'}` first."
+    )
+
+
+def run_locust(
+    host: str,
+    users: int,
+    spawn_rate: int,
+    runtime: str,
+    outdir: pathlib.Path,
+) -> int:
+    outdir.mkdir(parents=True, exist_ok=True)
+    csv_prefix = outdir / "run"
+    html_path = outdir / "report.html"
+    env = os.environ.copy()
+    existing_path = env.get("PYTHONPATH", "")
+    env["PYTHONPATH"] = (
+        f"{TEMPLATES_DIR}{os.pathsep}{existing_path}" if existing_path else str(TEMPLATES_DIR)
+    )
+    cmd = [
+        find_locust_executable(),
+        "-f",
+        str(LOCUSTFILE),
+        "--headless",
+        "-u",
+        str(users),
+        "-r",
+        str(spawn_rate),
+        "-t",
+        runtime,
+        "--host",
+        host,
+        "--csv",
+        str(csv_prefix),
+        "--html",
+        str(html_path),
+    ]
+    print(f"Running: {' '.join(cmd)}")
+    result = subprocess.run(cmd, env=env)
+    return result.returncode
+
+
+def write_latest(outdir: pathlib.Path, locust_exit: int, regression_exit: int, compare_summary: str) -> dict:
+    stats_csv = outdir / "run_stats.csv"
+    totals = {"p50_ms": None, "p95_ms": None, "p99_ms": None, "rps": None, "fail_ratio": None}
+    if stats_csv.exists():
+        import csv
+
+        with stats_csv.open("r", newline="", encoding="utf-8") as f:
+            reader = csv.DictReader(f)
+            for row in reader:
+                if row.get("Name") == "Aggregated":
+                    def _num(key: str) -> float | None:
+                        raw = row.get(key)
+                        try:
+                            return float(raw) if raw not in (None, "", "N/A") else None
+                        except ValueError:
+                            return None
+
+                    totals = {
+                        "p50_ms": _num("50%"),
+                        "p95_ms": _num("95%"),
+                        "p99_ms": _num("99%"),
+                        "rps": _num("Requests/s"),
+                        "fail_ratio": _num("Failure Count") / _num("Request Count")
+                        if _num("Request Count") and _num("Request Count") > 0
+                        else 0.0,
+                    }
+                    break
+
+    summary = {
+        "schema_version": 1,
+        "timestamp": datetime.datetime.now(datetime.timezone.utc).isoformat().replace("+00:00", "Z"),
+        "target": "dashboard",
+        "config": {},
+        "totals": totals,
+        "threshold_ok": locust_exit == 0,
+        "regression_ok": regression_exit == 0,
+        "summary": compare_summary or ("thresholds met" if locust_exit == 0 else "threshold breach"),
+    }
+    OUT_ROOT.mkdir(parents=True, exist_ok=True)
+    latest = OUT_ROOT / "LATEST.json"
+    latest.write_text(json.dumps(summary, indent=2), encoding="utf-8")
+    return summary
+
+
+def run_compare(stats_csv: pathlib.Path) -> tuple[int, str]:
+    if not COMPARE_SCRIPT.exists() or not stats_csv.exists():
+        return 0, ""
+    cmd = [sys.executable, str(COMPARE_SCRIPT), "--stats", str(stats_csv), "--baseline", str(DEFAULT_BASELINE)]
+    result = subprocess.run(cmd, capture_output=True, text=True)
+    sys.stdout.write(result.stdout)
+    sys.stderr.write(result.stderr)
+    return result.returncode, result.stdout.strip().splitlines()[-1] if result.stdout else ""
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Run the load-testing skill locally.")
+    parser.add_argument("--target", choices=["dashboard"], default="dashboard")
+    parser.add_argument("--users", type=int, default=100)
+    parser.add_argument("--spawn-rate", type=int, default=10)
+    parser.add_argument("--runtime", default="3m")
+    parser.add_argument("--host", default="http://localhost:3939")
+    parser.add_argument("--skip-baseline", action="store_true")
+    args = parser.parse_args()
+
+    backend_proc: subprocess.Popen | None = None
+    timestamp = datetime.datetime.now(datetime.timezone.utc).strftime("%Y%m%dT%H%M%SZ")
+    outdir = OUT_ROOT / timestamp
+
+    try:
+        if "localhost" in args.host or "127.0.0.1" in args.host:
+            port = 3939
+            print(f"Spawning dashboard backend on port {port}...")
+            try:
+                backend_proc = spawn_backend(port)
+            except FileNotFoundError as exc:
+                print(f"ERROR: {exc}", file=sys.stderr)
+                return 3
+            if not wait_for_port(port, timeout=30):
+                print(f"ERROR: backend did not become ready on port {port}", file=sys.stderr)
+                return 3
+            print("Backend ready.")
+
+        locust_exit = run_locust(args.host, args.users, args.spawn_rate, args.runtime, outdir)
+
+        regression_exit = 0
+        compare_summary = ""
+        if not args.skip_baseline:
+            regression_exit, compare_summary = run_compare(outdir / "run_stats.csv")
+
+        write_latest(outdir, locust_exit, regression_exit, compare_summary)
+
+        if locust_exit != 0:
+            return 1  # threshold breach
+        if regression_exit == 1:
+            return 2  # regression
+        return 0
+
+    except KeyboardInterrupt:
+        print("\nInterrupted.", file=sys.stderr)
+        return 3
+    finally:
+        stop_process(backend_proc)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/.merlin-core/skills/general/load-testing/templates/load_shape_stepped.py

@@ -0,0 +1,35 @@
+"""Reusable stepped LoadTestShape.
+
+Import this class from a locustfile or subclass it to customize the stages.
+
+    from load_shape_stepped import SteppedLoad
+
+    class MyShape(SteppedLoad):
+        stages = [
+            {"duration": 30,  "users": 20, "spawn_rate": 4},
+            ...
+        ]
+
+The stages are cumulative-time windows (not deltas). At each tick Locust
+asks which stage applies; the first stage whose duration is still in the
+future wins. Returning None ends the test.
+"""
+from locust import LoadTestShape
+
+
+class SteppedLoad(LoadTestShape):
+    """Safe graduated ramp. Override `stages` per target."""
+
+    stages = [
+        {"duration": 30, "users": 10, "spawn_rate": 2},
+        {"duration": 90, "users": 50, "spawn_rate": 5},
+        {"duration": 180, "users": 100, "spawn_rate": 10},
+        {"duration": 300, "users": 200, "spawn_rate": 10},
+    ]
+
+    def tick(self):
+        t = self.get_run_time()
+        for s in self.stages:
+            if t < s["duration"]:
+                return s["users"], s["spawn_rate"]
+        return None

package/.merlin-core/skills/general/load-testing/templates/locustfile_dashboard.py

@@ -0,0 +1,47 @@
+"""Locustfile: Gestao Merlin Dashboard API (port 3939, no auth).
+
+v0.1 is GET-only. POSTs like /api/projects/scan trigger filesystem walks
+and are out of scope until a seeded throwaway DB fixture exists.
+
+Runner note: `threshold_hook` must be importable as a top-level module.
+The `run_local.py` wrapper sets PYTHONPATH to this templates/ directory
+before invoking Locust. Direct `locust -f ...` runs need the same:
+    PYTHONPATH=.merlin-core/skills/general/load-testing/templates \\
+        locust -f templates/locustfile_dashboard.py ...
+"""
+from locust import HttpUser, between, task
+
+import threshold_hook  # noqa: F401 -- installs @events.quitting listener
+
+
+class DashboardUser(HttpUser):
+    wait_time = between(1, 3)
+    host = "http://localhost:3939"
+
+    @task(5)
+    def health(self):
+        self.client.get("/api/health", name="GET /api/health")
+
+    @task(10)
+    def list_projects(self):
+        self.client.get("/api/projects", name="GET /api/projects")
+
+    @task(3)
+    def project_stats(self):
+        self.client.get("/api/projects/stats", name="GET /api/projects/stats")
+
+    @task(4)
+    def timeline(self):
+        self.client.get("/api/timeline?limit=50", name="GET /api/timeline")
+
+    @task(2)
+    def tags(self):
+        self.client.get("/api/projects/tags", name="GET /api/projects/tags")
+
+    @task(2)
+    def jobs(self):
+        self.client.get("/api/jobs", name="GET /api/jobs")
+
+    @task(2)
+    def settings(self):
+        self.client.get("/api/settings", name="GET /api/settings")

package/.merlin-core/skills/general/load-testing/templates/threshold_hook.py

@@ -0,0 +1,36 @@
+"""Threshold gate for Locust headless runs.
+
+Usage in a locustfile:
+    import threshold_hook  # noqa: F401
+
+The import alone installs an @events.quitting listener that checks the
+total-suite p95 latency and error rate against env-var budgets. If either
+budget is exceeded, Locust exits with a non-zero process code.
+
+Env vars:
+    LOCUST_P95_MAX_MS      -- p95 ceiling in ms (default 1500)
+    LOCUST_ERROR_RATE_MAX  -- error-rate ceiling 0..1 (default 0.01)
+"""
+import os
+
+from locust import events
+
+P95_MAX_MS = int(os.getenv("LOCUST_P95_MAX_MS", "1500"))
+ERROR_RATE_MAX = float(os.getenv("LOCUST_ERROR_RATE_MAX", "0.01"))
+
+
+@events.quitting.add_listener
+def _assert_thresholds(environment, **_):
+    stats = environment.runner.stats.total
+    failed = False
+    if stats.fail_ratio > ERROR_RATE_MAX:
+        print(
+            f"THRESHOLD FAIL: error_rate={stats.fail_ratio:.3%} > {ERROR_RATE_MAX:.3%}"
+        )
+        failed = True
+    p95 = stats.get_response_time_percentile(0.95) or 0
+    if p95 > P95_MAX_MS:
+        print(f"THRESHOLD FAIL: p95={p95}ms > {P95_MAX_MS}ms")
+        failed = True
+    if failed:
+        environment.process_exit_code = 1

package/.merlin-core/skills/general/mage-beauty/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: mage-beauty
+description: "Beauty-first design operations for web UI and Remotion video — 20 design verbs (critique, polish, bolder, distill, animate, cinematic, rebrand, …) plus 9 thematic references covering typography, color, spatial, motion, interaction, responsive, microcopy, anti-patterns, and Remotion bridge. Use when the user invokes /beauty or asks to make a UI/video more beautiful, polish, critique, audit, harden, or transform a design."
+license: "MIT (Eugenio / Merlin Framework — original work)"
+metadata:
+  author: merlin-framework
+  version: "1.0.0"
+  auto_activate: [beauty, mage-beauty, polish-design, critique-design, redesign-aesthetic, beautiful]
+  file_triggers: [*.tsx, *.jsx, *.css, *.scss, **/components/**/*.ts, **/renderer/**/*.tsx]
+  tool_reminders:
+    - "Always read references/anti-patterns.md before declaring any design done"
+    - "Never use generic AI-tells — Inter for everything, purple-blue gradients, card-in-card, gray-on-color"
+    - "For Remotion targets — references/motion-design.md and references/remotion-bridge.md override web defaults"
+---
+
+## Charter
+
+Beauty is a discipline, not a feeling. This skill turns beauty into 20 verbs you can run on web UIs and Remotion video. Every verb is opinionated, traces to a thematic reference, and refuses generic AI-tells. The keyword "beauty" anchors the whole surface — say it and the skill activates. Web parity with video is non-negotiable: a stunning landing page and a stunning 1080×1920 reel ship through the same vocabulary.
+
+## When to invoke
+
+Invoke `/beauty <verb> [target]` for any design operation. Target detection: paths under `**/renderer/**` or `**/components/cinematic/**` are Remotion; everything else is web. Without a verb argument, `/beauty` returns the verb menu. The user can also describe the goal in natural language ("make this hero bolder", "polish this scene") and an `auto_activate` keyword will route here.
+
+## Verb catalog
+
+20 verbs. For each, read `references/verb-<name>.md` before acting.
+
+- both: critique, audit, polish, shape, bolder, quieter, distill, animate, colorize, typeset, layout, delight, clarify, adapt, optimize, overdrive, rebrand
+- web only: harden, onboard
+- Remotion-first: cinematic
+
+`/beauty` with no verb prints this list.
+
+## Reference catalog
+
+9 thematic references, on demand:
+
+- `typography.md` — type, pairing, scale
+- `color-and-contrast.md` — OKLCH, WCAG
+- `spatial-design.md` — grids, negative space
+- `motion-design.md` — easing, stagger
+- `interaction-design.md` — forms, focus (web only)
+- `responsive-and-multi-format.md` — breakpoints + video formats
+- `voice-and-microcopy.md` — labels, captions
+- `anti-patterns.md` — 15 deal-breakers
+- `remotion-bridge.md` — web → Remotion
+
+## Activation flow
+
+1. Detect target type — web (default) vs Remotion (path-based).
+2. Read the verb file: `references/verb-<name>.md`.
+3. Read the thematic references the verb cites.
+4. For Remotion targets, also read `remotion-bridge.md`.
+5. Run the anti-patterns check from `anti-patterns.md` before declaring done.
+6. Deliver — every fix uses exact values (hex, px, ms, font name, preset name).
+
+## Web targets
+
+Web targets: any `.tsx`/`.jsx`/`.css`/`.html`/`.svelte`/`.vue` outside `renderer/`. Default reference set: typography, color-and-contrast, spatial-design, motion-design, interaction-design, responsive-and-multi-format, voice-and-microcopy, anti-patterns. Skip remotion-bridge. Pre-delivery checklist: WCAG AA contrast, visible focus rings, reduced-motion fallback, 44 px minimum touch targets, no layout shift on hover.
+
+## Remotion targets
+
+Remotion targets: paths under `**/renderer/**` or `**/components/cinematic/**`. Read `remotion-bridge.md` first — it maps web principles onto the 9 component buckets (animation, cinematic, dataviz, education, layout, media, music, scene, text). Skip interaction-design (non-interactive medium). Always run motion-design through the pre-checks: video is overwhelmingly a motion problem, not a layout problem.
+
+## Integration with sibling skills
+
+Sits on Merlin's design family — never duplicates catalogs:
+
+- `frontend-design` — aesthetic philosophy + benchmarks
+- `design-palette` — 96-palette industry catalog
+- `design-typography` — 57-pairing catalog
+- `design-ux-patterns` — 30 landing patterns + 119 UX rules
+- `design-inspiration` — brief generator (used by `verb-shape`)
+- `tailwind-design-system` — Tailwind v4 OKLCH + CVA
+- `design-system` — semantic-token enforcement
+
+## Anti-patterns
+
+5 deal-breakers (full list in `references/anti-patterns.md`):
+
+1. Inter, Geist, or system font for everything — kills typographic identity
+2. Purple-to-blue gradient hero — universally read as AI-generic
+3. Card nested inside card — visual noise, no information gain
+4. Gray text on colored background — fails WCAG AA most of the time
+5. Bounce or elastic easing on UI — feels dated since 2018
+
+## License
+
+MIT — original work by Eugenio (Merlin Framework). Structurally inspired by but contains zero text from upstream Apache-2.0 / MIT design skills. Independent rewrite from public-domain design principles. See `.merlin-core/thoughts/shared/learnings/2026-05-05-design-skill-fusion-rationale.md` for the attribution policy.