super-ux 0.4.0 → 0.7.0

package/CHANGELOG.md

@@ -4,6 +4,53 @@ All notable changes to this project are documented in this file. The format
 follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versions
 follow [SemVer](https://semver.org/spec/v2.0.0.html).
 
+## [0.7.0] - 2026-07-20
+
+### Added
+
+- **Best-practices catalog** (`skills/references/best-practices.md`) — a
+  living, tag-indexed catalog (48 entries seeded from "48 Laws of
+  Subscription App Success", Botsi 2025): each practice has an ID (BP-NNN),
+  own-words summary, mechanism, applicability, and tags (stage / mechanism /
+  domain / effect) so agents can select what fits the product. Growable per
+  in-file rules.
+- Integration: `ux-scenarios` consults the catalog when drafting (practices
+  applied only when they serve a traced job); `ux-foundation` uses it for
+  journey opportunities; `ux-audit` gains an optional practices pass
+  (suggestion findings `[BP-NNN]`, never blockers); `/ux` menu gains a
+  "Best-practices review" action.
+
+## [0.6.0] - 2026-07-20
+
+### Added
+
+- **ux-foundation skill** — the WHY layer: personas, Jobs to Be Done (with
+  forces and success metrics), customer journey maps (stage / action /
+  touchpoint / emotion / pain / opportunity), user stories (INVEST,
+  Given/When/Then acceptance criteria). New file contract
+  `docs/ux/foundation.md`, template, `/ux-foundation` command, Cursor rule.
+- **ux-contract v2** — scenarios gain a `Traces:` field (story/job/journey
+  stage) and traceability rules: every must/should story covered, every
+  scenario serves a story or job; orphans are findings.
+- **Full-context audits** — `ux-audit` loads traced acceptance criteria as
+  checks and judges whether the implementation serves the job, not just
+  renders elements; new `coverage` scope audits the chain itself; fix plans
+  prioritized by Frequency × Severity × Solvability.
+- **`/ux` action menu** — single entry point now reports status across all
+  three layers and offers the applicable actions (init/update foundation,
+  build scenarios, validate chain, audit, coverage audit, plan fixes) with
+  one recommended default.
+
+## [0.5.0] - 2026-07-19
+
+### Changed
+
+- Installer menu is now a real multi-select: arrow keys / j k to move, space
+  or number to toggle, `a` selects all three targets at once, enter installs
+  the whole selection in one run (own questions asked up front, the external
+  skills-CLI picker runs last). Non-TTY stdin gets a text fallback
+  (`1,3` / `all` / `q`). Zero dependencies (stdlib raw-mode).
+
 ## [0.4.0] - 2026-07-19
 
 ### Added

package/README.md

@@ -1,5 +1,9 @@
 # super-ux
 
+[![npm](https://img.shields.io/npm/v/super-ux)](https://www.npmjs.com/package/super-ux)
+[![CI](https://github.com/ssheleg/super-ux/actions/workflows/validate.yml/badge.svg)](https://github.com/ssheleg/super-ux/actions/workflows/validate.yml)
+[![license](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
 Scenario-driven UI development for AI agents (Claude Code + Cursor).
 
 AI agents generate poor interfaces because they build UI without a model of
@@ -13,25 +17,29 @@ the codebase.
 
 ```mermaid
 flowchart LR
-    A[Feature idea] --> B[Draft scenarios]
-    B --> C{Validate vs existing base:\nconflicts, overlaps, gaps}
-    C -->|approved| D[Design & build UI]
+    W[Personas + JTBD\n+ journeys + stories] --> B[Derive scenarios\nwith Traces]
+    A[Feature idea] --> V{Which job? Which stage?\nValidate vs base}
+    W --> V
+    V -->|approved| D[Design & build UI]
     D --> E[Update scenarios\nin the same change]
-    E --> F[/ux-audit: batched check\nof code vs every scenario/]
-    F --> G[Audit report + findings]
-    G --> H[Plan fixes] --> D
+    E --> F[/ux-audit: code vs scenarios\nwith story acceptance criteria/]
+    B --> F
+    F --> G[Report + findings]
+    G --> H[Prioritized fix plan\nFreq × Severity × Solvability] --> D
 ```
 
 ## What's inside
 
 | Piece | Purpose |
 |---|---|
-| skill `ux-scenarios` | Maintain `docs/ux/scenarios.md`: init (greenfield interview or existing-code inventory sweep), update on every change, validate for conflicts and coverage |
-| skill `ux-audit` | Batched audit loop: trace every scenario through the code, verdicts PASS/PARTIAL/FAIL/BLOCKED with `file:line` evidence, report into `docs/ux/audits/` |
-| `/ux` | **The one command**: sets everything up if missing (rule, `docs/ux/`, initial base), otherwise status report + one suggested next action. Idempotent |
-| `/ux-init` `/ux-update` `/ux-audit` `/ux-rule` | Direct controls over the skills; `/ux-rule` installs the hard rule into the project's CLAUDE.md |
-| `cursor/rules/*.mdc` | The same methodology for Cursor (always-on hard rule + two agent-requested rules) |
-| `templates/` | Skeletons for the scenario base, the audit report, and the CLAUDE.md rule snippet |
+| skill `ux-foundation` | The WHY layer (`docs/ux/foundation.md`): personas, Jobs to Be Done with forces, customer journey maps, user stories with Given/When/Then acceptance criteria |
+| skill `ux-scenarios` | Maintain `docs/ux/scenarios.md`: scenarios derived from stories/journeys with `Traces:`, updated on every change, validated for conflicts, coverage, and traceability |
+| skill `ux-audit` | Batched audit loop with full context: code vs every scenario + its story's acceptance criteria; verdicts PASS/PARTIAL/FAIL/BLOCKED with `file:line` evidence; `coverage` scope audits the chain itself |
+| `/ux` | **The one command**: sets up whatever is missing, then status across all layers + a menu of applicable actions with one recommended default. Idempotent |
+| `/ux-foundation` `/ux-init` `/ux-update` `/ux-audit` `/ux-rule` | Direct controls; `/ux-rule` installs the hard rule into the project's CLAUDE.md |
+| `cursor/rules/*.mdc` | The same methodology for Cursor (always-on hard rule + three agent-requested rules) |
+| `templates/` | Skeletons for the foundation, scenario base, audit report, and the CLAUDE.md rule snippet |
+| [best-practices.md](plugins/super-ux/skills/references/best-practices.md) | Living, tag-indexed catalog of proven UX/growth practices (seeded with 48 subscription-app laws); agents filter by stage/domain tags and apply what serves a traced job |
 
 The format all of them share is locked in
 [scenario-format.md](plugins/super-ux/skills/references/scenario-format.md):
@@ -80,9 +88,10 @@ methods below.
 npx super-ux
 ```
 
-Menu: skills for any of 70+ agents (delegates to the `skills` CLI picker —
-choose agents and global/project there), Cursor rules into a project, or the
-Claude Code plugin user-globally.
+Multi-select menu (space to toggle, `a` = everything at once, enter to
+install): skills for any of 70+ agents (delegates to the `skills` CLI picker
+— choose agents and global/project there), Cursor rules into a project, and
+the Claude Code plugin user-globally — any combination in one run.
 
 ### Cursor
 
@@ -98,16 +107,20 @@ rules after a new release.
 
 ## Typical cycle
 
-1. `/ux` — first run sets everything up and builds the base (greenfield:
-   interview first, UI later; existing code: inventory sweep, scenarios for
-   everything found, gaps flagged in both directions).
+1. `/ux` — first run sets everything up: foundation first (greenfield:
+   interview about personas, jobs, journeys; existing code:
+   reverse-engineer them), then scenarios derived from the stories with
+   full traceability.
 2. Work normally; every user-facing change updates the base in the same
    change (the always-on rule catches it; `/ux-update` for manual control).
-3. `/ux` any time — status + the one next action; `/ux-audit` — batched
-   verification of code vs scenarios; report lands in
-   `docs/ux/audits/YYYY-MM-DD.md`, statuses update in the base.
-4. Turn FAIL/PARTIAL findings into a plan with your planning workflow; build;
-   repeat.
+   New feature ideas are validated against the chain first: which job,
+   which journey stage, which story.
+3. `/ux` any time — status across layers + action menu; `/ux-audit` —
+   batched verification of code vs scenarios (with acceptance criteria);
+   `/ux-audit coverage` — chain gaps. Reports land in
+   `docs/ux/audits/YYYY-MM-DD.md`.
+4. Findings become a prioritized fix plan (Frequency × Severity ×
+   Solvability) via your planning workflow; build; repeat.
 
 ## Development
 
@@ -119,11 +132,15 @@ is semver; bump `marketplace.json` + `plugin.json` + `CHANGELOG.md` together
 ## По-русски (коротко)
 
 Проблема: агенты генерируют плохие интерфейсы, потому что строят UI без
-модели поведения пользователя. super-ux делает базу UX-сценариев
-(`docs/ux/scenarios.md`) источником правды: сценарии пишутся и валидируются
-**до** интерфейса, обновляются тем же изменением, что и поведение, и служат
-чек-листом для регулярных аудитов кода (`/ux-audit`) с вердиктами
-PASS/PARTIAL/FAIL/BLOCKED и доказательствами `file:line`. Установка: в
+модели поведения пользователя. super-ux строит цепочку: **персоны → JTBD →
+карта пути → user stories → UX-сценарии → аудиты → планы фиксов**.
+Foundation (`docs/ux/foundation.md`) отвечает на «зачем», сценарии
+(`docs/ux/scenarios.md`) — источник правды поведения, трассируются к
+stories. Всё пишется и валидируется **до** интерфейса, обновляется тем же
+изменением, что и поведение. Аудиты (`/ux-audit`) проверяют код против
+сценариев вместе с acceptance criteria, вердикты PASS/PARTIAL/FAIL/BLOCKED
+с доказательствами `file:line`; `/ux-audit coverage` ищет дыры в самой
+цепочке. Установка: в
 Claude Code — `/plugin marketplace add ssheleg/super-ux`, в Cursor —
 `npx super-ux --cursor <проект>`. Дальше одна команда — `/ux`: сама ставит
 правило и базу, а при повторных запусках показывает статус и следующий шаг.

package/bin/super-ux.js

@@ -2,9 +2,11 @@
 /*
  * super-ux installer CLI.
  *
- * No arguments: interactive menu (skills for any agent via the `skills` CLI
- * picker, Cursor rules into a project, Claude Code plugin user-globally).
- * Flags keep the non-interactive paths: --cursor [dir] [--force].
+ * No arguments: interactive multi-select menu (arrow keys + space, `a` for
+ * all) covering: skills for any agent via the `skills` CLI picker, Cursor
+ * rules into a project, Claude Code plugin user-globally. Non-TTY stdin gets
+ * a text fallback ("1,3" / "all"). Flags keep the non-interactive paths:
+ * --cursor [dir] [--force].
  */
 'use strict';
 
@@ -16,15 +18,21 @@ const { spawnSync } = require('child_process');
 const ROOT = path.resolve(__dirname, '..');
 const REPO = 'ssheleg/super-ux';
 
+const MENU_ITEMS = [
+  { key: 'skills', label: 'Skills for any AI agent (Claude Code, Codex, Cursor, 70+ — opens agent picker)' },
+  { key: 'cursor', label: 'Cursor rules (always-on hard rule + docs/ux skeleton) into a project' },
+  { key: 'claude', label: 'Claude Code plugin (skills + /ux commands, user-global)' },
+];
+
 function usage() {
   console.log(`super-ux installer
 
 Usage:
-  npx super-ux                                  interactive menu
+  npx super-ux                                  interactive menu (multi-select)
   npx super-ux --cursor [project-dir] [--force] Cursor rules, non-interactive
   npx super-ux --help
 
-Menu options (also available directly):
+Menu items (select any combination, 'a' = all):
   1. Skills for any AI agent (Claude Code, Codex, Cursor, 70+) — delegates to
      'npx skills add ${REPO}' with its agent/global/project picker.
   2. Cursor rules: cursor/rules/*.mdc -> <project>/.cursor/rules/ plus the
@@ -85,12 +93,13 @@ function run(cmd, args) {
 }
 
 function installSkillsCli() {
-  console.log(`Delegating to the skills CLI (agent/global/project picker)...`);
+  console.log(`\n--- Skills for any agent: delegating to the skills CLI picker ---`);
   const status = run('npx', ['--yes', 'skills', 'add', REPO]);
-  if (status !== 'ok') fail(`'npx skills add ${REPO}' ${status}`);
+  if (status !== 'ok') console.error(`warning: 'npx skills add ${REPO}' ${status}`);
 }
 
 function installClaudePlugin() {
+  console.log(`\n--- Claude Code plugin ---`);
   const probe = spawnSync('claude', ['--version'], { stdio: 'ignore' });
   if (probe.error && probe.error.code === 'ENOENT') {
     console.log(`claude CLI not found. Run inside Claude Code instead:
@@ -104,14 +113,13 @@ function installClaudePlugin() {
   if (run('claude', ['plugin', 'install', 'super-ux@super-ux']) === 'ok') {
     console.log('Claude Code plugin installed (scope: user). Restart sessions to pick it up; then run /ux in any project.');
   } else {
-    fail('claude plugin install failed — see output above');
+    console.error('warning: claude plugin install failed — see output above');
   }
 }
 
 function makePrompter() {
   // A persistent 'line' listener with a buffer: with piped stdin, lines that
-  // arrive between two questions are kept instead of being lost (which is
-  // what plain sequential rl.question() does).
+  // arrive between two questions are kept instead of being lost.
   const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
   const buffered = [];
   let pending = null;
@@ -148,30 +156,131 @@ function makePrompter() {
   };
 }
 
+function parseSelection(input, count) {
+  const value = input.trim().toLowerCase();
+  if (value === '' || value === 'q' || value === 'quit') return [];
+  if (value === 'a' || value === 'all' || value === '*') {
+    return Array.from({ length: count }, (_, i) => i);
+  }
+  const picked = new Set();
+  for (const part of value.split(/[\s,]+/)) {
+    if (part === '') continue;
+    const n = Number(part);
+    if (!Number.isInteger(n) || n < 1 || n > count) return null;
+    picked.add(n - 1);
+  }
+  return [...picked].sort();
+}
+
+function selectInteractive(items) {
+  // Raw-mode checkbox list: up/down or j/k move, space or 1..9 toggle,
+  // a = toggle all, enter = confirm, q/esc/ctrl+c = quit.
+  return new Promise((resolve) => {
+    const selected = new Set();
+    let cursor = 0;
+    let rendered = false;
+
+    const line = (i) =>
+      `${i === cursor ? '❯' : ' '} ${selected.has(i) ? '◉' : '◯'} ${i + 1}) ${items[i].label}`;
+
+    const render = () => {
+      if (rendered) process.stdout.write(`\x1b[${items.length + 1}A`);
+      for (let i = 0; i < items.length; i += 1) {
+        process.stdout.write(`\x1b[2K${line(i)}\n`);
+      }
+      process.stdout.write(
+        '\x1b[2K  ↑/↓ move · space/number toggle · a all · enter confirm · q quit\n'
+      );
+      rendered = true;
+    };
+
+    const finish = (result) => {
+      process.stdin.setRawMode(false);
+      process.stdin.pause();
+      process.stdin.removeListener('keypress', onKeypress);
+      resolve(result);
+    };
+
+    const onKeypress = (str, key) => {
+      const name = key && key.name;
+      if ((key && key.ctrl && name === 'c') || name === 'escape' || str === 'q') {
+        finish([]);
+        return;
+      }
+      if (name === 'up' || str === 'k') cursor = (cursor - 1 + items.length) % items.length;
+      else if (name === 'down' || str === 'j') cursor = (cursor + 1) % items.length;
+      else if (name === 'space') {
+        if (selected.has(cursor)) selected.delete(cursor);
+        else selected.add(cursor);
+      } else if (str === 'a') {
+        if (selected.size === items.length) selected.clear();
+        else for (let i = 0; i < items.length; i += 1) selected.add(i);
+      } else if (str && /^[1-9]$/.test(str) && Number(str) <= items.length) {
+        const idx = Number(str) - 1;
+        if (selected.has(idx)) selected.delete(idx);
+        else selected.add(idx);
+        cursor = idx;
+      } else if (name === 'return') {
+        finish([...selected].sort());
+        return;
+      }
+      render();
+    };
+
+    readline.emitKeypressEvents(process.stdin);
+    process.stdin.setRawMode(true);
+    process.stdin.resume();
+    process.stdin.on('keypress', onKeypress);
+    render();
+  });
+}
+
+async function selectFallback(items, prompter) {
+  for (let i = 0; i < items.length; i += 1) {
+    console.log(`  ${i + 1}) ${items[i].label}`);
+  }
+  const answer = await prompter.ask(`Select [e.g. 1,3 | all | q]: `);
+  const picked = parseSelection(answer, items.length);
+  if (picked === null) fail(`invalid selection '${answer.trim()}'`);
+  return picked;
+}
+
 async function menu() {
-  const prompter = makePrompter();
-  console.log(`super-ux — scenario-driven UI development. What do you want to install?
-
-  1) Skills for any AI agent (Claude Code, Codex, Cursor, 70+ — interactive picker)
-  2) Cursor rules (always-on hard rule + docs/ux skeleton) into a project
-  3) Claude Code plugin (skills + /ux commands, user-global)
-  q) Quit
-`);
-  const choice = (await prompter.ask('Choice [1/2/3/q]: ')).trim().toLowerCase();
-  if (choice === '1') {
-    prompter.close();
-    installSkillsCli();
-  } else if (choice === '2') {
-    const dir = (await prompter.ask('Project directory [.]: ')).trim() || '.';
-    prompter.close();
-    installCursor(path.resolve(dir), false);
-  } else if (choice === '3') {
-    prompter.close();
-    installClaudePlugin();
+  console.log('super-ux — scenario-driven UI development. Select what to install:\n');
+  const interactive = Boolean(process.stdin.isTTY && process.stdout.isTTY);
+
+  // ONE prompter for the whole flow: with piped stdin, all pending lines are
+  // buffered by its persistent listener; a second prompter would lose them.
+  let prompter = null;
+  let picked;
+  if (interactive) {
+    picked = await selectInteractive(MENU_ITEMS);
   } else {
-    prompter.close();
-    if (choice !== 'q' && choice !== '') fail(`unknown choice '${choice}'`);
+    prompter = makePrompter();
+    picked = await selectFallback(MENU_ITEMS, prompter);
+  }
+
+  if (picked.length === 0) {
+    if (prompter) prompter.close();
+    console.log('Nothing selected.');
+    return;
+  }
+
+  const keys = picked.map((i) => MENU_ITEMS[i].key);
+
+  // Gather all our own questions BEFORE running anything, so they don't
+  // interleave with the external skills-CLI picker.
+  let cursorDir = null;
+  if (keys.includes('cursor')) {
+    if (!prompter) prompter = makePrompter();
+    const dir = (await prompter.ask('Cursor rules — project directory [.]: ')).trim() || '.';
+    cursorDir = path.resolve(dir);
   }
+  if (prompter) prompter.close();
+
+  if (keys.includes('cursor')) installCursor(cursorDir, false);
+  if (keys.includes('claude')) installClaudePlugin();
+  if (keys.includes('skills')) installSkillsCli();
 }
 
 function main() {

package/cursor/rules/super-ux.mdc

@@ -5,13 +5,16 @@ alwaysApply: true
 
 # UX scenarios — hard rule (super-ux)
 
-- `docs/ux/scenarios.md` is the source of truth for all user-facing behavior.
+- `docs/ux/scenarios.md` is the source of truth for all user-facing behavior;
+  `docs/ux/foundation.md` (personas, JTBD, journeys, user stories) is the WHY
+  layer scenarios trace to.
 - Any change that touches user-facing behavior MUST update
   `docs/ux/scenarios.md` in the same change (add/adjust scenarios, statuses,
   coverage). New user-facing behavior with no scenario is a blocker, not a
   warning.
-- Any new feature or project STARTS with scenarios: draft them, validate
-  against existing scenarios (conflicts, overlaps, gaps), get them approved —
-  only then design and build UI.
-- Scenario maintenance workflows: see the `ux-scenarios` rule. Codebase
-  audits against the base: see the `ux-audit` rule.
+- Any new feature or project STARTS with the chain: which job does it serve,
+  which journey stage, which story — then scenarios, validated against the
+  existing base (conflicts, overlaps, gaps), approved — only then design and
+  build UI. An idea serving no job is challenged, not silently accepted.
+- Workflows: `ux-foundation` rule (WHY layer), `ux-scenarios` rule
+  (scenario base), `ux-audit` rule (evidence-backed audits).

package/cursor/rules/ux-foundation.mdc

@@ -0,0 +1,47 @@
+---
+description: "Maintain docs/ux/foundation.md (personas, Jobs to Be Done, customer journeys, user stories): apply when defining who the users are and why they use the product, during product discovery, or when scenarios need a WHY layer to trace to"
+alwaysApply: false
+---
+
+# ux-foundation — The WHY Layer
+
+`docs/ux/foundation.md` holds the chain scenarios trace to: **Personas
+(P-NN) → Jobs to Be Done (JTBD-NN) → Customer journeys (JRN-NN) → User
+stories (ST-NNN)**. IDs sequential, never reused; dropped entries kept, not
+deleted.
+
+## Formats (ux-contract v2)
+
+- **Persona `P-NN`:** 1–3 sentences, grounded in data/observation,
+  recognizable by a real user.
+- **JTBD `JTBD-NN`:** `When <situation>, I want to <motivation>, so I can
+  <outcome>` + personas + type (functional|emotional|social) + forces
+  (push/pull/anxiety/habit) + success metric (user outcome, never a
+  feature).
+- **Journey `JRN-NN`** (persona × job): stage table — `# | Stage | User
+  action | Touchpoint | Emotion (1-5) | Pain | Opportunity`; end-to-end
+  (before/during/after product); opportunity priority = Frequency ×
+  Severity × Solvability.
+- **Story `ST-NNN`:** `As <persona>, I want <capability>, so that
+  <benefit>` + Traces (JTBD, JRN/stage) + Given/When/Then acceptance
+  criteria + priority (must|should|could) + status
+  (proposed|validated|delivered|dropped). Quality bar: INVEST.
+
+## Workflows
+
+- **Init (interview):** greenfield — ask one question at a time: who uses
+  it; what situation triggers the job; what outcome = success; walk the
+  path end-to-end; derive stories from pains and outcomes.
+- **Init (reverse):** existing product — reverse-engineer jobs/personas
+  from the UI and scenarios; tag entries observed vs inferred; flag
+  features serving no job and jobs with no support.
+- **Update:** locate by ID, update, mark dropped (never delete), then
+  cascade: list scenarios tracing to changed IDs and update them in the
+  same change.
+- **Validate:** integrity (IDs, references), quality (no features in JTBD,
+  INVEST, observable criteria), coverage (persona→job→journey→story chain
+  complete; must/should stories have scenarios).
+
+Evidence beats opinion: mark unvalidated guesses as assumptions
+(desirability/viability/feasibility/usability) and test risky ones before
+building on them.

package/cursor/rules/ux-scenarios.mdc

@@ -14,7 +14,12 @@ Title, then header comment, then: **Index** table
 (`| ID | Title | Feature | Persona | Status | Last audit |`), **Personas**
 (1–3 sentences each), **Scenarios** grouped by feature.
 
-Scenario entry fields (exact names): `Persona`, `Feature`, `Entry point`,
+When `docs/ux/foundation.md` exists, scenarios derive from it: draft per
+user story / journey stage, fill `Traces:` (e.g. `ST-001 (JTBD-01,
+JRN-01/#2)`), enforce traceability — every must/should story covered by ≥1
+scenario, every scenario serves ≥1 story or job.
+
+Scenario entry fields (exact names): `Persona`, `Feature`, `Traces`, `Entry point`,
 `Preconditions`, `Steps` (numbered, one user action each), `Expected result`
 (observable), `UI elements` (every button/field/link/dialog/toast involved —
 this is what audits check), `States covered` (loading|empty|error|success),

package/package.json

@@ -1,13 +1,33 @@
 {
   "name": "super-ux",
-  "version": "0.4.0",
+  "version": "0.7.0",
   "description": "Scenario-driven UI development for AI agents (Claude Code + Cursor): scenario base, scenario-first hard rule, evidence-backed UX audits. This package is the installer CLI.",
-  "bin": { "super-ux": "bin/super-ux.js" },
-  "files": ["bin", "cursor", "templates", "README.md", "LICENSE", "CHANGELOG.md"],
+  "bin": {
+    "super-ux": "bin/super-ux.js"
+  },
+  "files": [
+    "bin",
+    "cursor",
+    "templates",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
   "repository": "github:ssheleg/super-ux",
   "homepage": "https://github.com/ssheleg/super-ux",
   "license": "MIT",
   "author": "ssheleg",
-  "engines": { "node": ">=16" },
-  "keywords": ["ux", "scenarios", "audit", "ui", "user-flows", "scenario-driven", "claude-code", "cursor"]
+  "engines": {
+    "node": ">=16"
+  },
+  "keywords": [
+    "ux",
+    "scenarios",
+    "audit",
+    "ui",
+    "user-flows",
+    "scenario-driven",
+    "claude-code",
+    "cursor"
+  ]
 }

package/templates/foundation.md

@@ -0,0 +1,39 @@
+# UX Foundation
+
+<!-- Managed with super-ux (ux-contract v2). The WHY layer: personas, jobs
+to be done, customer journeys, user stories. Update when the understanding
+of users changes; scenarios in scenarios.md trace to the IDs defined here. -->
+
+## Personas
+
+<!-- ### P-01: <name>
+1-3 sentences: who they are, what they know, what they want. Grounded in
+data/observation, recognizable by a real user. -->
+
+## Jobs to Be Done
+
+<!-- ### JTBD-01: <short job name>
+- **Statement:** When <situation>, I want to <motivation>, so I can <expected outcome>.
+- **Personas:** P-01
+- **Type:** functional | emotional | social
+- **Forces:** push: <...>; pull: <...>; anxiety: <...>; habit: <...>
+- **Success metric:** <observable user outcome, not a feature>
+-->
+
+## Customer journeys
+
+<!-- ### JRN-01: <persona> — <job> (JTBD-01)
+| # | Stage | User action | Touchpoint | Emotion (1-5) | Pain | Opportunity |
+|---|-------|------------|------------|---------------|------|-------------|
+-->
+
+## User stories
+
+<!-- ### ST-001: <short name>
+- **Story:** As <persona>, I want <capability>, so that <benefit>.
+- **Traces:** JTBD-01, JRN-01/#2
+- **Acceptance criteria:**
+  - Given <precondition>, when <action>, then <observable result>.
+- **Priority:** must | should | could
+- **Status:** proposed
+-->