@ericrisco/rsc 3.3.1 → 3.5.0

package/README.md

@@ -239,7 +239,7 @@ project. rsc handles four things by default:
 | | What happens | Turn it off |
 | --- | --- | --- |
 | **You choose how the project works** | The install asks once: straight on `main`, or branches and pull requests? With branches, a commit on `main` is refused and the agent asks before each change: this branch, a new one, or unlock `main`? It never opens a branch on its own. | «unlock main», or `rsc main unlock` |
-| **One workspace per agent** | If another session works in the same folder, new work goes to `.worktrees/<branch>/`, inside the project and never committed. A `post-merge` hook retires it once the branch lands. | `rsc isolation off` |
+| **One workspace per agent** | If another session works in the same folder, new work goes to `.worktrees/<branch>/` at the root you work in (never inside a project folder) and is never committed. A `post-merge` hook retires it once the branch lands. | `rsc isolation off` |
 | **The agent picks the method** | FTD for simple changes, SDD for complex ones. The agent decides and says why. | Ask for the other lane |
 | **Knowledge reaches everyone** | `01-TOOLS/`, `02-DOCS/wiki/` and `02-DOCS/attachments/` travel through one exchange branch, `rsc/knowledge`, and reach `main` inside your normal pull requests. | `rsc knowledge-sync off` |
 
@@ -564,11 +564,11 @@ whether, what and which platform.
 
 ### 🌀 Motion & interface craft
 
-[ui-engineering](skills/ui-engineering/) · [variant-explorer](skills/variant-explorer/) · [scroll-film](skills/scroll-film/)
+[variant-explorer](skills/variant-explorer/) · [scroll-film](skills/scroll-film/)
 
 ### 🎨 Design & content craft
 
-[design](skills/design/) · [presentations](skills/presentations/) · [course-storytelling](skills/course-storytelling/) · [course-builder](skills/course-builder/) · [technical-writing](skills/technical-writing/) · [translation-l10n](skills/translation-l10n/)
+[design](skills/design/) · [ux](skills/ux/) · [presentations](skills/presentations/) · [course-storytelling](skills/course-storytelling/) · [course-builder](skills/course-builder/) · [technical-writing](skills/technical-writing/) · [translation-l10n](skills/translation-l10n/)
 
 ### 🧠 Knowledge & meta
 

package/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "3.3.1",
+  "version": "3.5.0",
   "counts": {
     "skills": 269,
     "agents": 34,
@@ -1311,7 +1311,7 @@
     },
     {
       "id": "design",
-      "description": "Use when designing, redesigning, restyling or reviewing a web page or app screen (landing, product site, portfolio, dashboard, docs) or when a UI looks generic or AI-made. Deals a researched direction, takes the idea from the subject, uses real pictures, proves it in a browser. NOT the words (landing-copy), NOT component state (ui-engineering).",
+      "description": "Use when designing, redesigning, restyling or reviewing a web page or app screen (landing, product site, portfolio, dashboard, docs) or when a UI looks generic or AI-made. Deals a researched direction, takes the idea from the subject, uses real pictures, proves it in a browser. NOT the words (landing-copy), NOT flows or usability (ux).",
       "tags": [
         "design",
         "ui",
@@ -1323,7 +1323,7 @@
       ],
       "recommends": [
         "landing-copy",
-        "ui-engineering",
+        "ux",
         "accessibility",
         "brand-identity",
         "nextjs"
@@ -5108,25 +5108,6 @@
       ],
       "profiles": []
     },
-    {
-      "id": "ui-engineering",
-      "description": "Use when the question is how interface should be BUILT — component boundaries, state that belongs in the URL vs the component, loading/empty/error states, forms, optimistic updates, build vs adopt. NOT the visual system (`design`), NOT framework mechanics (`react`/`nextjs`).",
-      "tags": [
-        "interface",
-        "frontend",
-        "architecture",
-        "components",
-        "state",
-        "craft"
-      ],
-      "recommends": [
-        "design"
-      ],
-      "profiles": [
-        "core",
-        "full"
-      ]
-    },
     {
       "id": "unit-economics",
       "description": "Use when computing or improving the per-customer economics of a business — CAC, LTV, CAC payback period and contribution margin — judging whether the ratios are healthy against current norms, and naming the one lever that fixes the worst number. Covers a blended CAC that hides a bleeding channel, and a model that shows profit while each customer loses money. NOT the multi-year P&L or scenario projection (that is `financial-model`).",
@@ -5242,6 +5223,46 @@
       ],
       "profiles": []
     },
+    {
+      "id": "ux",
+      "description": "Use when an app or SaaS must be easy to use: designing complete user flows, screens and every state, navigation, forms, onboarding, tables, dashboards, search or AI features, or auditing usability and accessibility. Anyone finishes the job without a manual; experts go fast. NOT the visual direction (design), NOT the words (landing-copy).",
+      "tags": [
+        "ux",
+        "usability",
+        "user-flows",
+        "flows",
+        "screens",
+        "states",
+        "empty-state",
+        "signup",
+        "modal",
+        "saas",
+        "app",
+        "product-design",
+        "navigation",
+        "forms",
+        "onboarding",
+        "dashboard",
+        "productivity",
+        "accessibility",
+        "wcag",
+        "interaction-design",
+        "usabilidad",
+        "flujos",
+        "pantallas"
+      ],
+      "recommends": [
+        "design",
+        "accessibility",
+        "landing-copy",
+        "react"
+      ],
+      "profiles": [
+        "minimal",
+        "core",
+        "full"
+      ]
+    },
     {
       "id": "variant-explorer",
       "description": "Use when someone wants OPTIONS rather than an answer — 'show me a few versions', picking between approaches by seeing them. Genuinely different candidates, cheap to throw away, trade-off named. NOT the critique that judges one (`design`), NOT the spec (`specify`).",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ericrisco/rsc",
-  "version": "3.3.1",
+  "version": "3.5.0",
   "description": "A guided harness builder that turns your goal into a minimal, verified AI-agent setup using strict best practices.",
   "type": "module",
   "bin": {

package/scripts/lib/default-skill-floor.js

@@ -18,7 +18,11 @@
 // `design` joined in 3.3.0 (spec design-from-scratch): it was `full`-only, so most projects designed
 // with no design skill at all. Only its description is paid for on other turns; the engine it ships
 // (scripts and data) is never loaded into context.
-export const DEFAULT_SKILL_FLOOR = Object.freeze(['orient', 'suggest', 'unslop', 'ftd', 'connect-tool', 'design']);
+//
+// `ux` joined in 3.4.0: `design` decides how a screen looks, `ux` decides whether people can use it —
+// the whole flow, every state, the browser walk. It replaced `ui-engineering`, which was core-only.
+// Only its description is paid for on other turns; the upstream references load on demand.
+export const DEFAULT_SKILL_FLOOR = Object.freeze(['orient', 'suggest', 'unslop', 'ftd', 'connect-tool', 'design', 'ux']);
 
 export function withDefaultSkillFloor(skillIds = []) {
   return [...new Set([...DEFAULT_SKILL_FLOOR, ...skillIds])];

package/scripts/lib/domains.js

@@ -24,8 +24,8 @@ export const DOMAINS = [
   { title: 'Ship & operate — platforms', ids: ['vercel', 'netlify', 'cloudflare', 'railway', 'render', 'fly-io', 'coolify', 'hetzner', 'digitalocean', 'aws-essentials', 'gcp-essentials'] },
   { title: 'Ship & operate — devops', ids: ['docker', 'github-actions', 'git-workflow', 'domains-dns', 'monitoring', 'email-deliverability', 'scaling', 'deployment', 'deprecation'] },
   { title: 'Ship & operate — quality & security', ids: ['code-review', 'security-scan', 'secure-coding', 'testing-py', 'testing-web', 'testing-go', 'e2e-testing', 'accessibility', 'performance', 'error-handling', 'observability'] },
-  { title: 'Motion & interface craft', ids: ['ui-engineering', 'variant-explorer', 'scroll-film'] },
-  { title: 'Design & content craft', ids: ['design', 'presentations', 'course-storytelling', 'course-builder', 'technical-writing', 'translation-l10n'] },
+  { title: 'Motion & interface craft', ids: ['variant-explorer', 'scroll-film'] },
+  { title: 'Design & content craft', ids: ['design', 'ux', 'presentations', 'course-storytelling', 'course-builder', 'technical-writing', 'translation-l10n'] },
   { title: 'Knowledge & meta', ids: ['knowledge-ops', 'codebase-onboarding', 'research-ops', 'decision-records', 'continuous-learning', 'skill-scout', 'context-budget', 'roast-me', 'fable-operator'] },
 ];
 

package/scripts/lib/retired-skills.js

@@ -11,9 +11,13 @@
 //
 // `design-loop`, `design-dna` and `motion-craft` folded into the rebuilt `design` in 3.3.0 (spec
 // design-from-scratch): its engine deals the direction, measures the render and owns the motion layer.
+//
+// `ui-engineering` folded into `ux` in 3.4.0: the screen states and form behaviour it owned are
+// `ux`'s state matrix now, and where component state lives is `react`'s.
 export const RETIRED_SKILLS = Object.freeze({
   eli5: 'orient', 'show-me': 'orient', bro: 'unslop',
   'design-loop': 'design', 'design-dna': 'design', 'motion-craft': 'design',
+  'ui-engineering': 'ux',
 });
 
 const retiredTo = (id) => (Object.hasOwn(RETIRED_SKILLS, id) ? RETIRED_SKILLS[id] : id);

package/scripts/rsc.js

@@ -927,7 +927,7 @@ async function main() {
             : 'rsc main lock: branches and pull requests for this project — the default branch is closed for the agent, and it asks before each code change where it goes. Commit .rsc.json so the team gets the same decision.')
           : (sub === OFF
             ? 'rsc isolation off: sessions may share this folder without a worktree. Commit .rsc.json so the team gets the same decision.'
-            : 'rsc isolation on: with another session active in this folder, new work goes to .worktrees/<branch>/. Commit .rsc.json so the team gets the same decision.'));
+            : 'rsc isolation on: with another session active in this folder, new work goes to .worktrees/<branch>/ at the root, never inside a project folder. Commit .rsc.json so the team gets the same decision.'));
         return;
       }
       if (sub === 'status') {

package/skills/design/SKILL.md

@@ -1,8 +1,8 @@
 ---
 name: design
-description: "Use when designing, redesigning, restyling or reviewing a web page or app screen (landing, product site, portfolio, dashboard, docs) or when a UI looks generic or AI-made. Deals a researched direction, takes the idea from the subject, uses real pictures, proves it in a browser. NOT the words (landing-copy), NOT component state (ui-engineering)."
+description: "Use when designing, redesigning, restyling or reviewing a web page or app screen (landing, product site, portfolio, dashboard, docs) or when a UI looks generic or AI-made. Deals a researched direction, takes the idea from the subject, uses real pictures, proves it in a browser. NOT the words (landing-copy), NOT flows or usability (ux)."
 tags: [design, ui, ux, landing, dashboard, frontend, taste]
-recommends: [landing-copy, ui-engineering, accessibility, brand-identity, nextjs]
+recommends: [landing-copy, ux, accessibility, brand-identity, nextjs]
 profiles: [minimal, core, full]
 origin: risco
 ---
@@ -91,7 +91,8 @@ launch. Do not claim a check you did not run.
 ## Hand-offs
 
 - The words on a conversion page → `../landing-copy/SKILL.md`.
-- Component boundaries, state, loading and error behaviour → `../ui-engineering/SKILL.md`.
+- Flows, screen states, navigation, forms and usability → `../ux/SKILL.md`.
+- Component code and where state lives → `../react/SKILL.md`.
 - WCAG conformance work → `../accessibility/SKILL.md`.
 - A full brand system (logo, print colours, usage rules) → `../brand-identity/SKILL.md`.
 - The App Router build → `../nextjs/SKILL.md`.

package/skills/design/evals/cases.yaml

@@ -19,8 +19,8 @@ should_not_trigger:
     route_to: "landing-copy"
     why: "The words on a conversion page belong to landing-copy; design builds the page around them."
   - prompt: "Where should the filter state live, in the URL or in the component, and how do we handle loading and errors?"
-    route_to: "ui-engineering"
-    why: "How interface is built (state, boundaries, async states) is ui-engineering, not visual design."
+    route_to: "react"
+    why: "How interface is built (state, boundaries, async states) is react's (and the states it shows are ux's), not visual design."
   - prompt: "Make our web app pass WCAG 2.2 AA: fix the axe violations and keyboard traps."
     route_to: "accessibility"
     why: "Conformance remediation is the accessibility skill's job."

package/skills/ftd/SKILL.md

@@ -73,7 +73,7 @@ says which on every turn) — never a branch opened on your own:
   is no exception: an unrelated change does not go into it without asking. A new branch is named by
   intent and closes with a pull request. Unlocking is `rsc main unlock`; never without that answer.
 - **Docs, wiki or config only** → no question, no branch.
-- **Another session working in this same folder** → a worktree in `.worktrees/<branch>/`, never a
+- **Another session working in this same folder** → a worktree in `.worktrees/<branch>/` at the root you work in (never inside a project folder), never a
   branch switch under the other session. Not a question: rsc tells you when that is the case.
 
 A worktree only when another session is there: alone, setting one up costs more than it protects.

package/skills/react/SKILL.md

@@ -10,7 +10,8 @@ origin: risco
 
 **Hand-off — picking dependencies.** Which library to reach for (UI primitives, command menus,
 toasts, OTP inputs, charts, virtualization, drag and drop, state, styling, theming) is
-`../ui-engineering/SKILL.md`'s — build vs adopt is decided there, before hand-rolling a component. The look of a page
+this skill's call: reuse what the project already depends on, then prefer a maintained, accessible library
+over hand-rolling a component. How the screen should behave for people is `../ux/SKILL.md`'s. The look of a page
 or screen, and its motion layer, is `../design/SKILL.md`'s.
 
 

package/skills/ux/SKILL.md

@@ -0,0 +1,149 @@
+---
+name: ux
+description: "Use when an app or SaaS must be easy to use: designing complete user flows, screens and every state, navigation, forms, onboarding, tables, dashboards, search or AI features, or auditing usability and accessibility. Anyone finishes the job without a manual; experts go fast. NOT the visual direction (design), NOT the words (landing-copy)."
+tags: [ux, usability, user-flows, flows, screens, states, empty-state, signup, modal, saas, app, product-design, navigation, forms, onboarding, dashboard, productivity, accessibility, wcag, interaction-design, usabilidad, flujos, pantallas]
+recommends: [design, accessibility, landing-copy, react]
+profiles: [minimal, core, full]
+origin: risco
+---
+
+# ux
+
+The bar: someone who has never seen the product finishes the main job **without asking anyone**,
+someone who uses it every day finishes it **fast**, and nobody loses work when something fails. A
+screen that looks good and misses that bar is not done.
+
+- **The flow comes before the screen.** Map the whole journey, from arrival to the job done and back
+  again, before drawing anything.
+- **Every screen answers five questions:** where am I, what is this, what can I do, what just
+  happened, where do I go next.
+- **Every state is designed,** not only the full one: empty, loading, error, offline, no permission,
+  too much data.
+- **You prove it by using it,** in a real browser, with the keyboard, at phone width. Reading the
+  code is not a check.
+
+The depth ships in `upstream/`, two MIT skills copied unmodified (`THIRD_PARTY.md`). This file is the
+method; load only the reference the task touches (table in **Files**).
+
+## 0. Name the job
+
+Write four lines before anything else: **who** (first-time, occasional, daily expert, admin),
+**the job** in their words, **done when** (what they can see), and **the risk** (money, data, legal,
+irreversible). Assume motivated but distracted people with average domain knowledge and imperfect
+memory.
+
+Ask one question only when the answer changes the design: the main task is unclear, the action is
+risky or irreversible, novices and experts need different things, the platform is unknown, or the
+request asks for a hidden or manipulative pattern. The ready-made questions, each with its default,
+are in `upstream/ux-usability-foundations/references/decision-prompts.md`. Everything else is
+decided by the defaults in `upstream/ux-usability-foundations/GUIDE.md`.
+
+## 1. Map the whole flow
+
+Use [references/flows.md](references/flows.md): the flow map, the lifecycle (sign-up, empty
+account, first value, the daily loop, limits, permissions, failures, offline, leaving and coming
+back), the second role (whoever is invited, not only the admin who set it up), and the step count of
+the core loop. Output a table with one row per step and screen. Missing lifecycle rows are the usual
+reason an app "feels broken".
+
+## 2. Design each screen
+
+1. **One job and one primary action.** The primary action is named with a verb and an object
+   ("Send invoice"), it is the strongest element, and the destructive action is never the primary
+   one.
+2. **Pick the pattern from the job:** list, detail, form, wizard, settings, dashboard, search, or an
+   overlay. Decision trees (modal, side panel or page; which notification type) are in
+   `upstream/ux-designer/GUIDE.md`. Navigation and IA in `05-information-architecture.md`.
+3. **Fill the state matrix** in `references/flows.md` for every screen: default, loading, empty
+   (new account and filtered to zero), partial, error, offline, no permission, overflow, pending.
+4. **Prevent, then recover:** constraints and safe defaults first, inline validation, input kept
+   across every failure, undo for anything reversible, confirmation only for the irreversible.
+   Forms in `07-forms-and-inputs.md`.
+5. **Speed for experts:** keyboard shortcuts, command search, bulk actions, saved views, remembered
+   filters, sensible defaults. They never replace the visible route for everyone else.
+6. **Accessible from the start:** native elements first, keyboard reaches everything, visible focus,
+   labels, colour never the only signal, targets of at least 24×24 CSS px. WCAG 2.2 AA in
+   `03-accessibility.md`.
+
+The rules with their numbers (contrast, type, timing, targets, toasts) are in
+`upstream/ux-designer/GUIDE.md` › *Core rules* and *Reference values*. Use them; do not invent
+others.
+
+## 3. How it looks
+
+The visual direction (type, palette, composition, pictures) is `../design/SKILL.md`'s, and it runs its
+engine on the screens this skill has specified. What stays here is the hierarchy that serves the job:
+one dominant element per screen, three levels of emphasis, one spacing scale, colour that means state,
+density chosen by the job (monitoring dense, onboarding calm). The tells of generated interfaces are
+listed in `upstream/ux-designer/GUIDE.md` › *Generated-UI defaults to avoid*, and visual detail in
+`04-visual-design.md`.
+
+## 4. Prove it by using it
+
+Walk the main job from a cold start in a real browser (the Chrome DevTools tools, when present): a new
+account, then one with data. Then the extremes: keyboard only, 320px wide, 200% zoom, a long
+translated string, empty data, a lot of data, a slow network, a failed request. Run axe or Lighthouse
+when the browser is there. Write down every hesitation and fix the hesitations before polishing
+anything. A check that could not run is reported as not run.
+
+## Review mode
+
+When the task is to audit an existing interface: steps 0 and 4 first, then report findings ranked
+by impact on the job, in the format of `upstream/ux-designer/GUIDE.md` › *Reviewing or auditing a
+UI* (Blocker / Major / Minor, where, fix, reference). Inspection order and the full checklists:
+`upstream/ux-usability-foundations/GUIDE.md` › *Workflow for critiquing* and
+`references/checklists.md`. Split quick wins from structural changes. If nothing serious turns up,
+say so in one line.
+
+## Report
+
+Say briefly: the person and the job; the flow map; the screens with their primary action and the
+states covered; what was walked in the browser and what was not; the findings or decisions with
+their reference; what still needs real data or real users to confirm.
+
+## Hand-offs
+
+- Visual direction, type, palette, pictures, landing pages → `../design/SKILL.md`.
+- The words on a marketing or conversion page → `../landing-copy/SKILL.md`.
+- A formal WCAG conformance programme or audit → `../accessibility/SKILL.md`.
+- Component code, state and data fetching → `../react/SKILL.md` or `../nextjs/SKILL.md`.
+- Measuring a flow with real users at scale → `../analytics/SKILL.md`, `../ab-testing/SKILL.md`.
+
+## Files
+
+| Load when the task involves… | File |
+| --- | --- |
+| The whole journey, lifecycle, roles, state matrix | [references/flows.md](references/flows.md) |
+| Workflows, core rules, numbers, decision trees, generated-UI tells | `upstream/ux-designer/GUIDE.md` |
+| Principles, defaults, questions to ask, critique order | `upstream/ux-usability-foundations/GUIDE.md` |
+| Questions with their recommended default | `upstream/ux-usability-foundations/references/decision-prompts.md` |
+| Principles as cards, full checklists, anti-patterns | `upstream/ux-usability-foundations/references/` › `principle-cards.md`, `checklists.md`, `anti-patterns.md` |
+| Nielsen's heuristics, Gestalt | `upstream/ux-designer/references/01-core-principles.md` |
+| Fitts, Hick, Jakob, Tesler, peak-end | `…/02-laws-of-ux.md` |
+| WCAG 2.2, ARIA, EAA | `…/03-accessibility.md` |
+| Type, colour, spacing, hierarchy, dark mode | `…/04-visual-design.md` |
+| Navigation, sitemaps, card sorting | `…/05-information-architecture.md` |
+| Modals, tooltips, drag and drop, motion timing | `…/06-interaction-design.md` |
+| Forms, validation, input types, errors | `…/07-forms-and-inputs.md` |
+| Touch, gestures, responsive, mobile navigation | `…/08-mobile-ux.md` |
+| Microcopy, error messages, tone | `…/09-ux-writing.md` |
+| Interviews, usability tests, surveys, metrics | `…/10-user-research.md` |
+| Tokens, component APIs, design system docs | `…/11-design-systems.md` |
+| Presence, cursors, avatars | `…/12a-presence-awareness.md` |
+| Conflicts, sync, offline, sharing, history | `…/12b-conflict-resolution-sync.md` |
+| Canvas zoom, pan, selection; layers, snapping, performance | `…/13a-canvas-navigation.md`, `…/13b-canvas-objects-performance.md` |
+| Chat, copilots, agents, generative UI | `…/14-ai-ux-patterns.md` |
+| Dark patterns, consent, DSA and GDPR interface rules | `…/15-ethical-design.md` |
+| First run, activation, empty states, checklists | `…/16-onboarding.md` |
+| Notifications, push, toasts, preferences | `…/17-notifications.md` |
+| Charts and dashboards | `…/18-data-visualization.md` |
+| Search, autocomplete, filters, zero results | `…/19-search-ux.md` |
+| Trust, delight, recovering from errors | `…/20-emotional-design.md` |
+| Tables, sorting, pagination, bulk actions | `…/21-data-tables.md` |
+| Loading, skeletons, optimistic updates, Core Web Vitals | `…/22-performance-ux.md` |
+| Localisation, RTL, `Intl`, plurals | `…/23-internationalization.md` |
+| Voice and multimodal input | `…/24-voice-and-multimodal.md` |
+| Barcodes and QR: scanning, scanner workflows, display | `…/25a-barcode-camera-scanning.md`, `…/25b-barcode-scanner-workflows.md`, `…/25c-barcode-display.md` |
+| Which upstream versions ship here, with file hashes | `upstream/UPSTREAM.json` |
+
+`…/` is `upstream/ux-designer/references/`.

package/skills/ux/THIRD_PARTY.md

@@ -0,0 +1,32 @@
+# Third-party work in this skill
+
+Both sources are copied unmodified. The exact commit of each, and the sha256 of every file shipped,
+are in `upstream/UPSTREAM.json`; `tests/ux-upstream.test.js` fails if a shipped file drifts from it.
+
+## ux-designer
+
+- **Source:** https://github.com/szilu/ux-designer-skill
+- **Licence:** MIT, Copyright (c) 2026 Szilárd Hajba. Full text: `upstream/ux-designer/LICENSE`.
+- **What is here:** `upstream/ux-designer/references/` (29 files), copied unmodified.
+  `upstream/ux-designer/GUIDE.md` is the upstream `SKILL.md` with its YAML front matter removed so it
+  is not discovered as a second skill; the text is unchanged.
+
+## ux-usability-foundations
+
+- **Source:** https://github.com/hueyexe/frontend-agent-skills (`ux-usability-foundations`)
+- **Licence:** MIT, Copyright (c) 2026 hueyexe. Full text: `upstream/ux-usability-foundations/LICENSE`
+  (the repository licence).
+- **What is here:** `upstream/ux-usability-foundations/references/` (4 files), copied unmodified.
+  `upstream/ux-usability-foundations/GUIDE.md` is the upstream `SKILL.md` with its YAML front matter
+  removed; the text is unchanged.
+
+## Written for rsc
+
+`SKILL.md` and `references/flows.md` are original to rsc. They route into the upstream material and
+add what neither source covers in depth: mapping a whole application's flows, its lifecycle, its
+roles and the state matrix per screen.
+
+## Updating
+
+Copy a reviewed checkout over `upstream/<name>/`, strip the front matter from its `SKILL.md` into
+`GUIDE.md`, and regenerate the hashes and commit in `UPSTREAM.json`. Never an automatic download.

package/skills/ux/evals/cases.yaml

@@ -0,0 +1,40 @@
+skill: ux
+
+should_trigger:
+  - prompt: "Diseña todos los flujos de la app: desde que alguien se registra hasta que envía su primera factura."
+    why: "A whole application journey, the thing this skill maps before any screen."
+  - prompt: "New users sign up, see an empty dashboard and leave. What should they see instead?"
+    why: "The empty account and first value, rows of the lifecycle this skill owns."
+  - prompt: "Revisa la usabilidad de nuestro panel antes de la demo: que cualquiera entienda cómo usarlo."
+    why: "A usability audit by use, reported by severity, in Spanish."
+  - prompt: "Should editing a customer open a modal, a side panel or a full page?"
+    why: "A pattern decision driven by the job, from the decision trees this skill routes to."
+  - prompt: "The signup form wipes everything when the email is already taken. How should it behave?"
+    why: "Error prevention and recovery in a form."
+  - prompt: "Our power users complain the app is slow to work with. How do we make it more productive?"
+    why: "Expert speed: shortcuts, command search, bulk actions, saved views."
+  - prompt: "What states does this list screen need besides the loaded one?"
+    why: "The state matrix, the checklist that replaced ui-engineering's five states."
+
+should_not_trigger:
+  - prompt: "Give our landing page a distinctive look: type, palette, hero picture."
+    route_to: "design"
+    why: "Visual direction for a page; design runs its engine for that."
+  - prompt: "Write the headline and the call to action for the pricing page."
+    route_to: "landing-copy"
+    why: "The words on a conversion page."
+  - prompt: "My useEffect fires twice in development. Why?"
+    route_to: "react"
+    why: "Framework mechanics, not how the interface should behave for people."
+  - prompt: "Prepare our WCAG 2.2 conformance report for the public tender."
+    route_to: "accessibility"
+    why: "A formal conformance programme, not designing a flow."
+  - prompt: "Convert this PDF contract into plain text."
+    route_to: "none"
+    why: "No interface or flow involved."
+
+capability:
+  - prompt: "We are building a SaaS for clinics to book appointments. Map the complete flows for the receptionist and the invited doctor, with the states of each screen."
+    why: "Forces the flow map, the second role and the state matrix, before any visual work."
+  - prompt: "Audit this app by using it: a new account creating a client and sending an invoice. Report by severity with fixes and references."
+    why: "Forces the browser walk and the finding format instead of a code-only review."

package/skills/ux/references/flows.md

@@ -0,0 +1,124 @@
+# Flows — the whole application, before any screen
+
+Most apps that "feel broken" have good screens and missing steps: nobody designed the empty account,
+the invited member, the failed payment or the way back after a week away. Map the journey first;
+the screens fall out of it.
+
+## 1. The flow map
+
+One table per job. One row per step. Every row names its screen and the states that screen can be
+in when the person arrives.
+
+```
+Person:    Office manager · weekly · average domain knowledge
+Job:       Send this month's invoice to a client
+Done when: The client has it and the manager can see "Sent" on the invoice
+Risk:      Money and a client relationship — sending is not reversible
+```
+
+| # | Step (the person's words) | Screen | Primary action | States on arrival | Way back / out |
+| --- | --- | --- | --- | --- | --- |
+| 1 | Find the client | Clients list | Open client | empty, filtered to zero, many | — |
+| 2 | Start the invoice | Client detail | New invoice | no invoices yet, has drafts | Back to list, filters kept |
+| 3 | Fill the lines | Invoice form | Review invoice | draft restored, validation error | Save as draft |
+| 4 | Check before sending | Review | Send invoice | missing client email, over plan limit | Edit |
+| 5 | Know it worked | Invoice detail | — (status visible) | sending, sent, bounced | Back to client |
+
+Rules for the map:
+
+- **Steps in the person's words,** not the system's ("Find the client", not "Query CRM entity").
+- **Every row has a way back.** A step with no way back is a defect, unless it is the irreversible
+  action and it said so first.
+- **Count the core loop.** Clicks and decisions from "I want to do this" to "done". Each one earns its
+  place: can it be defaulted, inferred, remembered or skipped? The daily job gets the fewest steps.
+- **No step depends on memory.** If step 4 needs something seen in step 1, step 4 shows it.
+
+## 2. The lifecycle — rows people forget
+
+Walk every one. A row with no answer is a gap in the design, not an edge case.
+
+| Moment | What the person must see |
+| --- | --- |
+| Arrives with no account | What the product does for them, then a sign-up asking for the least it can. |
+| Account just created, nothing exists | An empty state that names the first useful action and shows what it produces. Import or a sample, when that is faster than starting blank. |
+| First value | Proof it worked, and the next most useful step. Not a celebration that blocks the screen. |
+| Daily use | The shortest route to the core job: recent items, saved views, shortcuts, remembered filters. |
+| Near or at a plan limit | A warning before the limit; at it, what is blocked, why, and the one action that unblocks it. Never a silent failure. |
+| No permission | Who can do it and a way to ask them. Actions that this role can never use are hidden, not disabled. |
+| Network lost | Work stays on screen, offline is visible, changes sync when back and say so. |
+| Request fails | What failed, what is safe, input intact, retry in one click. |
+| Long operation | Progress, what is happening, whether they can leave and come back. |
+| Payment fails | What happens to their data and when, and the one action that fixes it. |
+| Coming back after weeks | Things where they left them; what changed while away, if anything did. |
+| Leaving | Export first, then delete; what is removed, what stays, and for how long it can be undone. |
+
+## 3. The second role
+
+Whoever set the account up is rarely whoever uses it most. Map the flow again for each role that
+exists:
+
+- **The invited member:** arrives from an email, has no context, did not choose the product. Their
+  first screen is the thing they were invited to, not the generic dashboard.
+- **The admin:** billing, members, roles, security, audit. Rare tasks, high stakes: clarity over
+  speed, consequences written out.
+- **The viewer or guest:** sees only what they can act on. No dead buttons.
+- **Support acting as the user,** when the product allows it: clearly marked, never invisible.
+
+## 4. Flows every SaaS needs
+
+Check each exists and is mapped; most products ship without two or three of them.
+
+| Flow | The part that is usually missing |
+| --- | --- |
+| Sign-up and sign-in | Password managers and paste working; magic link or SSO path; the expired-link screen. |
+| Onboarding to first value | Skippable, resumable, disappears once done. See `../upstream/ux-designer/references/16-onboarding.md`. |
+| Invite and join | The invited person's first screen; resending; an expired invitation. |
+| Create, edit, delete the core object | Drafts, autosave or an unsaved-changes guard, undo after delete. |
+| Find (search, filter, sort) | Zero results that suggest a way out; filters kept when coming back from detail. |
+| Bulk work | How many items, what will change, undo or a summary of what failed. |
+| Import and export | Preview and mapping before import; a report of what was skipped and why. |
+| Notifications | Severity matches reality; per-channel preferences. See `../upstream/ux-designer/references/17-notifications.md`. |
+| Settings | Grouped by subject; changes say when they take effect; dangerous ones apart, at the end. |
+| Plan, billing, limits | Current plan and usage visible; upgrade from the point of need; downgrade explains what is lost. |
+| Account and data deletion | Export offered first; the consequence spelled out; a grace period when the product can keep one. |
+
+## 5. The state matrix
+
+Fill it for every screen in the map. "N/A" is allowed; blank is not.
+
+| Screen | Default | Loading | Empty (new) | Empty (filtered) | Partial | Error | Offline | No permission | Overflow | Pending item |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| Clients list | | | | | | | | | | |
+
+What each state needs:
+
+- **Loading:** skeleton in the layout of what is coming, after about 300ms so fast loads do not
+  flash; progress and cancel past ten seconds.
+- **Empty (new):** why it is empty, the action that fills it, and what it will look like.
+- **Empty (filtered):** the active filters, and a way to clear them. Never the "new account" message.
+- **Partial:** what loaded, what did not, retry for the part that failed.
+- **Error:** what happened in plain words, what is safe, retry; the request id when support needs it.
+- **Offline:** cached data marked as possibly stale; what can still be done.
+- **No permission:** who can grant it, a way to ask.
+- **Overflow:** long names truncated with the full text reachable, many items paginated or
+  virtualised with a count, huge numbers formatted.
+- **Pending item:** the row or card marked as working, the rest of the screen usable.
+
+## 6. Expert speed
+
+The person who uses the product every day is the one who decides whether it is "productive". For
+each daily job, decide:
+
+- the keyboard shortcut and where it is shown (menus, a `?` overlay);
+- whether a command search (Cmd/Ctrl+K) reaches it;
+- which bulk action replaces doing it item by item;
+- which view or filter should be saved or remembered;
+- which field can default from the last time.
+
+None of these replaces the visible route; they sit on top of it.
+
+## 7. Walking the map
+
+Before calling the flow done, walk it in a browser twice: once as the new person on an empty
+account, once as the daily user with real-sized data. Keyboard only for one of the walks, phone width
+for the other. Every pause, every "where is…", every re-typed value is a row to fix in the map.