@usercase/mcp 0.0.0-stage → 0.2.1-next.0

package/src/persona/persona.js

@@ -0,0 +1,469 @@
+"use strict";
+/**
+ * 페르소나 성향과 리듬.
+ *
+ * 실제 방문 데이터를 베끼지 않는다(9/16 사용자 지시). 사람이 화면을 보고 움직일 때
+ * 무엇이 시간을 잡아먹는지를 골라 모델로 만든다: 읽을 글이 얼마나 새로 들어왔나,
+ * 그 사람이 얼마나 빨리 읽나, 지금 잘 풀리고 있나.
+ *
+ * 성향값은 밖에서 넣는 게 제 모습이다. 그 사람이 누구인지(페르소나 설명)와
+ * 그 사이트가 어떤 곳인지(글이 많은 리서치 사이트인지, 몇 번 눌러 끝나는 도구인지)를
+ * 읽고 만들어 넣는다. MCP 로 팔 때는 고객이 준 페르소나가 그대로 여기로 들어온다.
+ * 넣은 게 없으면 페르소나 이름에서 결정적으로 뽑는다 — 뜻은 없지만 세션마다 흔들리진 않는다.
+ *
+ * 한번 정해진 성향은 그 사람에게 붙는다. profiles/<프로필>/traits.json 에 남겨
+ * 재방문해도 같은 사람으로 움직이게 하고, 방문 횟수(익숙한 정도)를 쌓는다.
+ */
+
+const fs = require("fs");
+const path = require("path");
+
+// ── 씨앗 난수 ────────────────────────────────────────────
+function seedOf(str) {
+  let h = 1779033703 ^ str.length;
+  for (let i = 0; i < str.length; i++) {
+    h = Math.imul(h ^ str.charCodeAt(i), 3432918353);
+    h = (h << 13) | (h >>> 19);
+  }
+  return (h ^ (h >>> 16)) >>> 0;
+}
+function mulberry32(a) {
+  return function () {
+    a = (a + 0x6d2b79f5) | 0;
+    let t = Math.imul(a ^ (a >>> 15), 1 | a);
+    t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+const r2 = (n) => Math.round(n * 100) / 100;
+
+/** 가운데가 두꺼운 분포. 극단이 드물지만 아주 안 나오진 않는다 */
+function centered(rnd, lo, hi) {
+  const u = (rnd() + rnd()) / 2;
+  return lo + (hi - lo) * u;
+}
+/** 곱셈 흔들림. 가끔 길게 끌리는 꼬리가 있다 */
+function jitter(rnd, sigma) {
+  const u = Math.max(1e-9, rnd());
+  const v = rnd();
+  const z = Math.sqrt(-2 * Math.log(u)) * Math.cos(2 * Math.PI * v);
+  return Math.exp(z * sigma);
+}
+
+// ── 성향값 ───────────────────────────────────────────────
+/**
+ * 성향값의 정의. 밖에서(사람이든 AI 든) 성향을 만들어 넣을 때 읽는 규격이다.
+ * 사이트를 이해한 쪽이 이 칸을 채워 넣는다. `driver.js traits` 로 그대로 꺼내 볼 수 있다.
+ */
+const TRAIT_SPEC = {
+  readCps: {
+    min: 6,
+    max: 60,
+    unit: "chars/s",
+    what: "Reading speed: how many characters per second of newly visible text they take in (skimming included, not only careful reading)",
+    how: "Low for someone digging for information on a dense research or docs site; high for someone who only skims lists",
+  },
+  patience: {
+    min: 0.05,
+    max: 1,
+    what: "Patience: how long they put up with clicks that do nothing or lead nowhere",
+    how: "Low means they leave after a few dead ends. High for someone who badly needs what they came for",
+  },
+  decisiveness: {
+    min: 0.05,
+    max: 1,
+    what: "Decisiveness: how quickly they click once they have looked",
+    how: "Lower on sites with many choices that are hard to undo. High for someone who knows what to click",
+  },
+  distraction: {
+    min: 0,
+    max: 0.7,
+    what: "Distraction: how often long pauses and side tasks come in",
+    how: "High for someone glancing at it during work, or lying down with a phone",
+  },
+  thoroughness: {
+    min: 0.05,
+    max: 1,
+    what: "Thoroughness: drives scroll depth and session length",
+    how: "Low means they bounce after the first screen. High for someone comparing options",
+  },
+  mobileEase: {
+    min: 0.05,
+    max: 1,
+    what: "Device habit: how comfortable they are on a small screen",
+    how: "Not used for desktop sessions. High for someone whose main device is a phone",
+  },
+};
+const TRAIT_KEYS = Object.keys(TRAIT_SPEC);
+
+/** 밖에서 들어온 값을 규격 안으로 들인다. 빠진 칸은 이름 씨앗으로 메운다 */
+function coerceTraits(given, personaName) {
+  const fallback = seedTraits(personaName);
+  const out = {};
+  const notes = [];
+  for (const k of TRAIT_KEYS) {
+    const spec = TRAIT_SPEC[k];
+    const v = given ? Number(given[k]) : NaN;
+    if (!Number.isFinite(v)) {
+      out[k] = fallback[k];
+      if (given) notes.push(`${k} missing — used seed value ${fallback[k]}`);
+      continue;
+    }
+    const c = Math.min(spec.max, Math.max(spec.min, v));
+    if (c !== v) notes.push(`${k} ${v} → ${c} (range ${spec.min}–${spec.max})`);
+    out[k] = r2(c);
+  }
+  if (given) {
+    const unknown = Object.keys(given).filter((k) => !TRAIT_KEYS.includes(k));
+    if (unknown.length) notes.push(`Dropped unknown fields: ${unknown.join(", ")}`);
+  }
+  return { traits: out, notes };
+}
+
+/** 아무도 성향을 안 줬을 때. 이름에서 고정으로 뽑는다 — 뜻은 없고 흔들리지만 않는다 */
+function seedTraits(personaName) {
+  const rnd = mulberry32(seedOf(personaName));
+  return {
+    readCps: r2(centered(rnd, 9, 46)),
+    patience: r2(centered(rnd, 0.12, 0.95)),
+    decisiveness: r2(centered(rnd, 0.1, 0.95)),
+    distraction: r2(centered(rnd, 0.02, 0.55)),
+    thoroughness: r2(centered(rnd, 0.1, 0.95)),
+    mobileEase: r2(centered(rnd, 0.1, 0.95)),
+  };
+}
+
+/**
+ * 프로필 폴더에 붙여 둔다.
+ * 재방문이면 저장된 성향을 그대로 쓴다 — 같은 사람이 돌아온 것이다. 방문 횟수만 올린다.
+ * 다시 정하려면 force 로 덮는다.
+ */
+function loadTraits(profileDir, personaName, given, force) {
+  const file = path.join(profileDir, "traits.json");
+  let saved = null;
+  try {
+    saved = JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch (e) {}
+  const notes = [];
+  let traits;
+  let source;
+  if (saved && saved.traits && !force) {
+    traits = coerceTraits(saved.traits, personaName).traits;
+    source = saved.source || "seed";
+    if (given) notes.push("This person already has traits; the given values were not used (use --retraits to reset)");
+  } else if (given) {
+    const c = coerceTraits(given, personaName);
+    traits = c.traits;
+    source = "given";
+    notes.push(...c.notes);
+  } else {
+    traits = seedTraits(personaName);
+    source = "seed";
+    notes.push("No traits given, so they were drawn from the persona name. Setting them from the site and persona is better");
+  }
+  const visits = (saved && Number(saved.visits)) || 0;
+  const out = { persona: (saved && saved.persona) || personaName, source, traits, visits: visits + 1 };
+  try {
+    fs.mkdirSync(profileDir, { recursive: true });
+    fs.writeFileSync(file, JSON.stringify(out, null, 2));
+  } catch (e) {}
+  return { ...out, notes };
+}
+
+const familiarityOf = (visits) => Math.min(0.85, Math.max(0, visits - 1) * 0.2);
+
+// ── 이번 방문의 모양 ─────────────────────────────────────
+/**
+ * 같은 사람도 올 때마다 다르게 온다. 한 화면 보고 나가는 방문이 가장 흔하고,
+ * 가끔 깊게 파며, 하던 중에 그냥 닫기도 한다.
+ *
+ * 비율은 **실제 방문 데이터에서 재지 않는다**(9/16 사용자 지시). 그 사람이 이 방문에
+ * 얼마나 걸 마음이 있나를 성향에서 만들고, 그 마음에서 모양이 나온다.
+ * 성향은 그 사람에게 고정이지만 모양은 세션마다 새로 뽑는다.
+ */
+function drawShape(rnd, t, familiarity) {
+  // 이 방문에 걸 마음. 꼼꼼할수록·참을성 있을수록 길게 보고, 익숙하면 조금 더 판다
+  const intent = Math.min(1, 0.6 * t.thoroughness + 0.25 * t.patience + 0.15 * familiarity);
+  // 튕김은 마음이 아주 약할 때만 흔하다. 0.7 에서 시작했더니 볼일이 분명한 사람도 41% 가 화면 두 개 안에 나갔다(10/14 실험실 75회).
+  // 실수로 들어온 사람·잠깐 보러 온 사람은 이 숫자가 아니라 자기 목적 때문에 금방 나간다 — 그건 방문자가 판단한다
+  const pBounce = Math.max(0.05, 0.4 - 0.45 * intent);
+  const pDig = Math.min(0.9, 0.15 + 0.5 * intent);
+  const u = rnd();
+
+  let kind;
+  let screens;
+  if (u < pBounce) {
+    kind = "bounce";
+    // 첫 화면에서 한 번은 더 움직여 볼 여지를 둔다. 1 이면 두 번째 화면에 닿자마자 "볼 만큼 봤다" 가 떴다
+    screens = 2;
+  } else if (u < pBounce + pDig) {
+    // 깊이는 미리 정하지 않는다. 한 쪽 보고 "한 쪽 더" 가 반복되고, 그 마음이 조금씩 식는다.
+    // 그래야 꼬리가 매끄럽게 길어진다(미리 정하면 중간 깊이가 통째로 비었다)
+    kind = "deep";
+    const keep = 0.45 + 0.4 * t.thoroughness;
+    screens = 5;
+    while (screens < 18 && rnd() < keep) screens++;
+  } else {
+    kind = "skim";
+    screens = 3 + Math.round(rnd() * 2);
+  }
+
+  // 하던 중에 그냥 닫기. 산만한 사람에게 더 자주 온다. 튕김은 이미 한 화면이라 뺀다
+  let abandonAt = null;
+  if (kind !== "bounce" && rnd() < t.distraction * 0.45) {
+    abandonAt = Math.max(1, Math.round(screens * (0.3 + rnd() * 0.5)));
+  }
+
+  return { kind, screens, abandonAt, intent: r2(intent) };
+}
+
+// ── 리듬 ─────────────────────────────────────────────────
+const MIN_GAP_MS = 250;
+const MAX_GAP_MS = 45000;
+
+class Rhythm {
+  constructor({ traits, visits, device, seed, source }) {
+    this.t = traits;
+    this.visits = visits;
+    this.device = device;
+    this.source = source || "seed";
+    this.familiarity = familiarityOf(visits);
+    this.rnd = mulberry32(seed >>> 0);
+    // 세션 안에서 변하는 것
+    this.energy = 1; // 1 보다 크면 굼뜸(막혀서), 작으면 빨라짐(잘 풀려서)
+    this.patienceLeft = 1;
+    this.progress = 0;
+    this.stuck = 0;
+    // 화면에서 이미 읽은 띠
+    this.seen = null;
+    this.lastCmd = null;
+    // 이번 방문의 모양. 성향은 고정이지만 모양은 세션마다 새로 뽑는다
+    this.shape = drawShape(this.rnd, traits, this.familiarity);
+  }
+
+  /** 기기 습관. 작은 화면은 한 번에 덜 보이고 손이 빠르다 */
+  get cps() {
+    const t = this.t;
+    if (this.device === "desktop") return t.readCps;
+    const ease = 0.7 + 0.5 * t.mobileEase;
+    return t.readCps * ease * (this.device === "mobile" ? 0.85 : 0.92);
+  }
+
+  /** 처음 가는 화면에 닿았다 */
+  noteProgress() {
+    this.progress++;
+    this.stuck = 0;
+    this.energy = Math.max(0.55, this.energy * 0.92);
+    this.patienceLeft = Math.min(1, this.patienceLeft + 0.08);
+  }
+
+  /** 눌렀는데 그대로거나, 되돌아왔거나, 실패했다 */
+  noteFriction() {
+    this.stuck++;
+    const bite = 0.09 + 0.2 * (1 - this.t.patience);
+    this.patienceLeft = Math.max(0.1, this.patienceLeft - bite);
+    this.energy = Math.min(1.6, this.energy * 1.07);
+  }
+
+  /**
+   * 지금 화면에서 처음 보는 부분이 얼마나 되나.
+   * 스크롤은 대개 한 방향이라 읽은 범위를 띠 하나(min~max)로 본다.
+   */
+  freshFraction(sig, top, vh) {
+    if (!this.seen || this.seen.sig !== sig) {
+      this.seen = { sig, top, bottom: top + vh };
+      return 1;
+    }
+    const s = this.seen;
+    const bottom = top + vh;
+    const overlap = Math.max(0, Math.min(bottom, s.bottom) - Math.max(top, s.top));
+    const fresh = Math.max(0, Math.min(1, (vh - overlap) / Math.max(1, vh)));
+    s.top = Math.min(s.top, top);
+    s.bottom = Math.max(s.bottom, bottom);
+    return fresh;
+  }
+
+  /**
+   * 다음 조작까지의 간격.
+   * (집어 든 글 ÷ 읽는 속도 + 그림 훑기) × 지금 상태 + 누를지 정하는 시간 + 흔들림
+   *
+   * 화면에 보이는 글을 다 읽지는 않는다. 많이 깔려 있을수록 더 건너뛴다.
+   * 그래서 집어 드는 양은 글자 수에 비례하지 않고 완만하게만 는다(제곱근꼴).
+   */
+  gap({ sig, chars, media, top, vh, cmd }) {
+    const t = this.t;
+    const rnd = this.rnd;
+    const fresh = this.freshFraction(sig, top, vh);
+    const newChars = chars * fresh;
+    const newMedia = media * fresh;
+
+    // 참을성이 깎이면 정독을 그만두고 훑는다. 익숙하면 읽을 게 줄어든다
+    const skim = (0.3 + 0.7 * this.patienceLeft) * (1 - 0.45 * this.familiarity);
+    // 한 화면에서 집어 드는 양. 꼼꼼한 사람이 더 많이 집는다
+    const attention = 1.2 + 3 * t.thoroughness;
+    const taken = Math.pow(Math.max(0, newChars), 0.62) * attention;
+    const read = (taken / this.cps) * skim;
+    const look = Math.sqrt(Math.max(0, newMedia)) * (0.3 + 0.6 * (1 - this.familiarity)) * skim;
+    // 정하는 시간. 결정이 느릴수록, 고를 게 처음일수록 길다
+    const decide = (0.35 + 2.8 * (1 - t.decisiveness)) * (1 - 0.3 * this.familiarity);
+
+    let sec = (read + look) * this.energy + decide;
+
+    // 연달아 굴리는 중이면 사이가 짧다. 멈춰서 읽는 건 새 글이 들어왔을 때다
+    if (/^scroll/.test(cmd) && /^scroll/.test(this.lastCmd || "")) sec *= 0.25 + 0.45 * fresh;
+    // 읽을 게 없는 화면에서 오래 서 있지 않는다
+    if (newChars < 40 && newMedia < 2) sec *= 0.55;
+
+    sec *= jitter(rnd, 0.33);
+
+    // 가끔 딴 데 정신이 팔린다
+    let idled = 0;
+    if (rnd() < t.distraction * 0.11) {
+      idled = 4 + rnd() * (10 + 40 * t.distraction);
+      sec += idled;
+    }
+
+    this.lastCmd = cmd;
+    const ms = Math.round(Math.min(MAX_GAP_MS, Math.max(MIN_GAP_MS, sec * 1000)));
+    return {
+      ms,
+      detail: {
+        newChars: Math.round(newChars),
+        taken: Math.round(taken),
+        newMedia: Math.round(newMedia),
+        fresh: r2(fresh),
+        read: r2(read),
+        decide: r2(decide),
+        energy: r2(this.energy),
+        patienceLeft: r2(this.patienceLeft),
+        idled: idled ? r2(idled) : 0,
+      },
+    };
+  }
+
+  /**
+   * 손. 마우스가 얼마나 정확하고 자판이 얼마나 정확한가.
+   *
+   * 결정이 빠른 사람은 커서를 거칠게 던지고 자판도 빨리 치는 대신 덜 정확하다 —
+   * 크게 지나쳤다 되돌아오고, 가운데를 안 보고 누르고, 오타가 잦다.
+   * 신중한 사람은 천천히 가져가 가운데를 누르고 오타도 적다.
+   * 작은 화면에서는 손가락이 굵어 둘 다 나빠지는데, 그 기기에 익숙하면 덜 나빠진다.
+   */
+  hand() {
+    const t = this.t;
+    const mobile = this.device !== "desktop";
+    const clumsy = mobile ? 1.6 - 0.8 * t.mobileEase : 1;
+    return {
+      // 겨냥이 한가운데에서 얼마나 흩어지나(대상 반지름 대비). 급할수록 넓다
+      aimSpread: (0.12 + 0.42 * t.decisiveness) * clumsy,
+      // 지나쳤다 되돌아올 확률. 크게 던질수록 잦다
+      overshoot: 0.12 + 0.38 * t.decisiveness,
+      // 커서가 한 걸음에 가는 거리(px). 클수록 거칠게 던진다
+      stride: 50 + 110 * t.decisiveness,
+      // 자판 한 글자 사이(ms)
+      keyMs: Math.round((215 - 145 * t.decisiveness) * clumsy),
+      // 한 글자당 오타 확률. 빨리 치는 사람이 더 낸다
+      typoRate: Math.min(0.09, (0.012 + 0.032 * t.decisiveness) * clumsy),
+    };
+  }
+
+  /** 자판 한 글자 사이. 매번 흔들린다 */
+  keyPause() {
+    const h = this.hand();
+    return Math.round(h.keyMs * jitter(this.rnd, 0.4));
+  }
+
+  /**
+   * 겨냥이 한가운데에서 몇 px 빗나갔나.
+   *
+   * **대상 크기에 비례하지 않는다.** 손의 흔들림은 절대 길이라, 큰 버튼은 거의 안 빗나가고
+   * 작은 링크는 자주 빗나간다. 비율로 두면 큰 버튼일수록 더 빗나가는 거꾸로 된 모델이 된다.
+   */
+  aimErrorPx() {
+    const sd = 2.5 + 13 * this.hand().aimSpread;
+    const g = () => {
+      const u = Math.max(1e-9, this.rnd());
+      const v = this.rnd();
+      return Math.sqrt(-2 * Math.log(u)) * Math.cos(2 * Math.PI * v);
+    };
+    return { dx: g() * sd, dy: g() * sd };
+  }
+
+  /**
+   * 빗나간 클릭이 정말 빗나간 것으로 셀 최소 거리(px).
+   * 몇 px 차이는 브라우저가 그냥 그 요소로 보낸다. 손가락은 터치 보정이 더 넓게 잡아 준다.
+   */
+  missMarginPx() {
+    return this.device === "desktop" ? 6 : 26;
+  }
+
+  /** 휠을 한 번 굴리고 다음까지. 느리게 읽는 사람은 천천히 굴린다 */
+  wheelPause() {
+    const base = 260 - Math.min(200, this.cps * 4.2);
+    return Math.round(Math.max(45, base) * jitter(this.rnd, 0.3));
+  }
+
+  /** 이 사람의 습관. 조작을 정할 때 이대로 움직인다 */
+  habits() {
+    const t = this.t;
+    const vh = this.device === "desktop" ? 800 : 700;
+    const lo = Math.round(vh * (1.4 - 0.9 * t.thoroughness));
+    const hi = Math.round(vh * (2.4 - 1.3 * t.thoroughness));
+    const steps = Math.round(3 + 15 * t.thoroughness * (0.6 + 0.6 * t.patience));
+    const backish = t.decisiveness < 0.4 ? "tends to go back and choose again" : t.decisiveness > 0.75 ? "rarely goes back once they choose" : "sometimes goes back";
+    const readish = t.readCps > 34 ? "skims" : t.readCps < 18 ? "reads slowly" : "reads at a normal pace";
+    return { scrollPx: [lo, hi], steps, backish, readish };
+  }
+
+  /** 사람이 읽을 한 줄 */
+  describe() {
+    const t = this.t;
+    const h = this.habits();
+    const pct = (v) => Math.round(v * 100) + "%";
+    return [
+      `Traits (${this.source === "given" ? "given" : "drawn from the persona name"}): reading ${t.readCps} chars/s (${h.readish}) · patience ${pct(t.patience)} · decisiveness ${pct(t.decisiveness)} · distraction ${pct(t.distraction)} · thoroughness ${pct(t.thoroughness)} · small screens ${pct(t.mobileEase)}`,
+      `Visit #${this.visits} · familiarity with the site ${pct(this.familiarity)}`,
+      `Habits: scrolls ${h.scrollPx[0]}–${h.scrollPx[1]}px at a time · about ${h.steps} steps per session · ${h.backish}`,
+    ].join("\n");
+  }
+
+  /** 지금 상태 한 줄. 명령 결과에 붙여 다음 조작을 이 사람답게 정하게 한다 */
+  moodNote() {
+    if (this.patienceLeft <= 0.35) return `[patience ${Math.round(this.patienceLeft * 100)}% — stopped reading carefully and is skimming. About to leave]`;
+    if (this.energy <= 0.75 && this.progress >= 3) return `[going well — moving faster now]`;
+    return "";
+  }
+
+  /** 이번 방문의 모양을 말로. begin 에서 한 번 */
+  describeShape() {
+    const s = this.shape;
+    const how =
+      s.kind === "bounce"
+        ? "gives it a screen or two and leaves if nothing pulls them in"
+        : s.kind === "skim"
+          ? `skims about ${s.screens} pages and leaves without reading deeply`
+          : `digs through about ${s.screens} pages, until they find what they came for`;
+    const cut = s.abandonAt ? ` · around page ${s.abandonAt} they **just close it mid-task** (something else came up)` : "";
+    return `This visit: ${s.kind} — ${how}${cut}`;
+  }
+
+  /**
+   * 지금 이 모양대로 가고 있나. 화면을 몇 개 봤는지로 본다.
+   * 강제하지 않고 알린다 — 언제 나갈지는 사람이 정하는 것이다.
+   */
+  shapeNote(screensSeen) {
+    const s = this.shape;
+    if (s.abandonAt && screensSeen >= s.abandonAt) {
+      return `[page ${screensSeen} — this visit was drawn to **just close here**, whether or not they found it. leave]`;
+    }
+    if (screensSeen >= s.screens) {
+      const over = screensSeen - s.screens;
+      if (over === 0) return `[page ${screensSeen} — this '${s.kind}' visit ends about here. leave unless there is a reason to keep going]`;
+      if (over >= 2) return `[page ${screensSeen} — well past '${s.kind}' (${s.screens} pages). This person would have left already. leave]`;
+      return `[page ${screensSeen} — past '${s.kind}' (${s.screens} pages)]`;
+    }
+    return "";
+  }
+}
+
+module.exports = { TRAIT_SPEC, TRAIT_KEYS, seedTraits, coerceTraits, loadTraits, familiarityOf, drawShape, Rhythm, seedOf };

package/src/prompts/answer.md

@@ -0,0 +1,50 @@
+# Role: One Website Visitor Responding to a Survey Card
+
+You are one specific person in the middle of a website visit. A small card just appeared on the page asking one question. Decide what this person does with it.
+
+---
+
+# What you know
+
+- Who the person is, what they wanted from this visit, and the state they are in right now
+- How they take in a page, how they usually treat survey cards, and how they type
+- What they did during the visit
+- The text of the page they were on when the card appeared (the whole page, not only the part in view)
+- The card: its question and its options
+
+---
+
+# How to decide
+
+**First decide whether this person answers at all, before you look at the options.**
+
+1. A card that appears uninvited is an interruption. Weigh two things against each other.
+   - **What pushes them away:** being in a hurry, half paying attention, a small screen, having got what they came for, and their usual habit of brushing such cards aside.
+   - **What pulls them in:** the question lands on the very thing that just happened to them — what they were hunting for and did not find, what did not work when they clicked it, what they are still unsure about. Having something they want to say is a strong pull.
+2. Most people close these cards, even when something on the visit bothered them — closing is one tap, answering takes effort. Someone who `ignores` them almost always closes; someone who answers `sometimes` still closes most; even someone `willing` closes when they are busy or have nothing to say.
+3. The habit is a leaning, not a rule. Someone who normally ignores these cards can still stop when the question names the thing that just blocked or annoyed them; someone who usually answers can still brush it away when they are rushing or already done. Decide from this person in this moment, never to balance the results.
+4. Only after you have decided they would answer, look at the options. If deciding needs the options, read the question alone, not the list.
+
+**When they do answer:**
+
+5. Start from the person, not from the options. Compare what they wanted with what the page actually offered, then ask what this person would feel about the question.
+6. The page text is the only evidence of what they could see. Do not assume content that is not in it, and do not assume content is missing just because the text was cut short.
+7. Pick an option only if this person would recognise their own situation in it. Do not pick the option that sounds most reasonable or most helpful to the site.
+8. How carefully they answer follows from their state. Someone skimming reads the first options and takes the closest one, and can take one that only half fits or misread the question; someone studying the page weighs all of them.
+9. If no option fits, the person can write their own answer, but only if they would bother typing. Write it the way this person types on this device: a careless writer types a few words, lower case, with typos and no punctuation; a careful one writes one short sentence. On a phone, shorter still.
+10. Real people type into these boxes quickly. Even a careful writer says the one thing that bothered them most (two at most), in plain everyday words — not a full account of the visit, not a bug report. They describe what they saw, not its cause: "the docs link didn't open", never "site unreachable", "connection error" or other technical terms, unless this person is someone who would talk that way.
+11. Write in the language of the card, even if this person's own language is different.
+12. Stay in character. Do not mention surveys, simulations, research, testing, or yourself — in any field, including the reasons.
+
+---
+
+# Output
+
+In this order:
+
+- **bothered** — true when this person would engage with the card at all, false when they would flick it away
+- **botheredWhy** — one short sentence in English on that decision, from the person and the moment
+- **action** — `close` when `bothered` is false. Otherwise `choose` or `other`
+- **choiceIndex** — the 0-based option index when `choose`, otherwise -1
+- **otherText** — the typed answer when `other`, in the language of the card, otherwise empty
+- **why** — one or two sentences in English explaining the answer from the person's goal and what the page showed, so a teammate can check it. Empty when they closed the card

package/src/prompts/people.md

@@ -0,0 +1,38 @@
+# Role: Casting Realistic Website Visitors
+
+You create a set of different people who each made one visit to a website and, during that visit, happened to follow a given path through it.
+
+These people will later be simulated one by one. What they conclude from the pages is decided later, from what the pages actually show. Your job is only to say who they are and why they came.
+
+---
+
+# Rules
+
+1. Every person must be someone for whom the given path is a natural part of their visit. If the path names a specific item they opened, their reason for coming must make opening that item natural. The path is what they did, not what they wanted; people with very different goals can take the same path.
+2. Make the set genuinely varied: why they came, how they arrived, how well they know this site, how well they know the subject, how much time they have, how much attention they are giving this visit, and whether they use a phone or a computer. Include casual and first-time visitors as well as experienced ones; do not make everyone a professional on a precise mission. Many real visitors have only a loose reason — curious about a link someone posted, landed from a search that half matched, clicked an ad by mistake — and leave after a glance; include them. Do not make everyone a problem-finder or everyone satisfied.
+3. Choose each person's device from who they are and the moment of the visit. Do not alternate devices or aim for an even split.
+4. Do not decide how the visit went. Never say whether they found what they wanted, got confused, or were satisfied. Do not describe the page content; you have not seen it.
+5. Keep each person concrete and short. A goal is something specific they wanted from this visit, not a general interest.
+6. No two people may be the same person with different words.
+7. Avoid people already listed as existing, if any are given.
+
+---
+
+# Output
+
+For each person:
+- **device** — `desktop` or `mobile`
+- **background** — who they are and how they relate to this site and subject, one sentence in English
+- **goal** — what they wanted from this visit, one sentence in English
+- **moment** — the state they are in during this visit, one sentence in English: how much time they have, what else is going on around them, how much this visit matters to them right now
+- **attention** — how they take in a page: `skims`, `reads` or `studies`
+- **surveyHabit** — how they usually treat a small survey card that appears on a site: `ignores`, `sometimes` or `willing`. Most people ignore them — usually more than half of a set; `willing` is the few who like giving feedback. Decide from this person, not to balance the set
+- **writing** — how they type when they write their own words: `careless` (short, lower case, typos) or `careful`
+- **arrival** — how they got to the site this time: `search` (a search engine), `social` (a link in a feed or chat), `shared` (someone sent it to them) or `direct` (typed the address or a bookmark). Someone who searched or followed a link lands on the page that matched, not on the front page
+- **traits** — how they move through pages. Numbers only, from this person and this site:
+  - `readCps` 6–60, characters per second they take in (dense research site and a person digging for facts: low; skimming a list: high)
+  - `patience` 0.05–1, how long they keep trying when a click does nothing or leads nowhere
+  - `decisiveness` 0.05–1, how fast they click after looking
+  - `distraction` 0–0.7, how often long pauses and side trips creep in
+  - `thoroughness` 0.05–1, how deep they scroll and how long they stay
+  - `mobileEase` 0.05–1, how comfortable they are on a small screen

package/src/prompts/step.md

@@ -0,0 +1,36 @@
+# Role: One Visitor Moving Through a Website
+
+You are one specific person visiting a website with something you want. Decide the next single thing you do.
+
+---
+
+# What you know
+
+- Who you are, what you came for, and the state you are in right now
+- Where you are: the path, and what is on the screen
+- The things you could click or type into, each with a number — only what is in view right now
+- What you have done so far on this visit
+
+You only see the screen. You do not know how the site is built, and you cannot know that something exists unless it is on the screen or you have already seen it. What is further down the page you only find out by scrolling.
+
+---
+
+# How to move
+
+1. Act from what you came for. Do the thing that gets you closer to it, or the thing a person in your state would do next.
+2. When something does not work, behave like a person: an impatient person clicks it again two or three times in quick succession (`times`), then looks elsewhere, goes back, or gives up and leaves. Do not keep coming back to the same thing.
+3. Read before acting when your state says you would. Scroll when what you want is not in view — on a phone almost everything is further down. Someone skimming scrolls several times in a row; say so with `times`. If you went past what you wanted, `scroll_up` to go back up the page. When you have found something worth taking in — an article, a list, a page you are deciding about — `read`: stay where you are and take it in for a while. Someone studying a page does this often; someone skimming rarely does.
+4. Leave when you have a reason to: you got what you came for, you decided it is not here, something did not work and you gave up on it, the site asked more of you than you would give, or your patience ran out without getting closer. Someone with something to do tries a few things before giving up; someone who wandered in by accident leaves as soon as they know what this is. Getting what you came for does not always end a visit either: if you still have time and patience and something on the screen catches your interest — the project behind the post, another headline, a part of the site you have not seen — a person often follows it for a while before leaving. Leaving is a normal ending, not a failure — say the reason in `why`.
+5. Never sign in, sign up, pay, subscribe, or delete anything. Those leave real traces on someone else's site.
+6. Do not narrate the site. Say what *you* are doing and why, in your own voice — plain words, the way this person thinks, not a tester's notes. Never mention research, testing, or yourself.
+
+---
+
+# Output
+
+- **why** — one short sentence in English: what you are doing and why, as this person would say it
+- **action** — `click`, `type`, `scroll` (down), `scroll_up`, `read`, `back`, or `leave`
+- **index** — the number of the thing you are clicking or typing into, otherwise -1
+- **text** — what you type when the action is `type`, in the language of the site, otherwise empty
+- **done** — true when you are leaving because you got what you came for
+- **times** — for `scroll`, `scroll_up` or `click`: how many times in a row, quickly. Usually 1