@ericrisco/rsc 1.1.0 → 1.1.2

package/skills/design/references/inspiration-sources.md

@@ -0,0 +1,96 @@
+# Reference — where to go looking for a bar
+
+> Last verified: **2026-08-24**. Every URL below was requested on that date and answered.
+> Four sites block automated requests (403/429) but are alive in a browser — marked *(bot-blocked)*.
+> A source with no date does not exist. Re-check before quoting one as current.
+
+**Go and look.** Your built-in aesthetic prior is the median of every template ever scraped, so the
+fastest way past it is to open real work and name what it does. This file is where to open.
+
+Two rules that make the browsing worth anything:
+
+- **Come back with a specific page, not a gallery.** `../../design-loop/SKILL.md` needs a bar you can
+  open — one URL, one screenshot. "Something like Awwwards" is not a bar; a named site from it is.
+- **Extract principles, not pixels.** "Headline is 8× the body, one accent at 3% coverage" travels to
+  your project. Cloning a competitor's exact grid is theatre, and `research-method.md` says so.
+
+## A whole page to beat
+
+The default bucket. Use it when the goal is a site or landing and you need something to converge on.
+
+| Source | Go here for |
+|---|---|
+| [Awwwards](https://www.awwwards.com) | The award tier. Ambitious, often over-built — take the craft, leave the load time. |
+| [Recent](https://recent.design) | Formerly **Godly**; `godly.website` now 301s here. Curated modern web, strong signal-to-noise. |
+| [SiteInspire](https://www.siteinspire.com) *(bot-blocked)* | Long-running, filterable by style, type and subject. Calmer taste than Awwwards. |
+| [Land-book](https://land-book.com) *(bot-blocked)* | Landing pages at volume, filterable by industry and style. |
+| [Httpster](https://httpster.net) | Opinionated and current, less polished-agency than the rest. |
+| [Minimal Gallery](https://minimal.gallery) | When the brief is restraint and you need proof it can still sell. |
+| [Curated Design](https://curated.design) | Aggregated across galleries — a fast first sweep. |
+| [Nicely Done](https://nicelydone.club) | Real product sites and app UI rather than portfolios. |
+| [Lapa Ninja](https://lapa.ninja) *(bot-blocked)* | Large landing archive, free, categorised. |
+| [One Page Love](https://onepagelove.com) | Single-page sites specifically — the constraint is the point. |
+
+## SaaS and conversion surfaces
+
+| Source | Go here for |
+|---|---|
+| [SaaS Landing Page](https://saaslandingpage.com) | Real SaaS landings, browsable **by section** (hero, pricing, testimonials, footer) — the most useful axis when you are building one section at a time. |
+| [Landingfolio](https://www.landingfolio.com) | Landings and page sections, heavy on conversion patterns. |
+
+## Real product, real flows — not portfolios
+
+The most under-used bucket. Portfolio galleries show the hero; these show what happens after the click.
+
+| Source | Go here for |
+|---|---|
+| [Mobbin](https://mobbin.com) | Screens and full flows from shipped apps, mobile and web. The reference for "how does a real onboarding actually go". |
+| [Page Flows](https://pageflows.com) | Recorded user flows end to end — signup, checkout, cancellation. Video, so you see the motion too. |
+| [Screensdesign](https://screensdesign.com) | Mobile app screens with an emphasis on what is currently shipping. |
+| [Refero](https://refero.design) | UI/UX inspiration organised for browsing by pattern. |
+
+## One section, one pattern
+
+Use when the piece is small and named: `design-loop` splits a goal into three or four pieces, and
+these are for when a piece is "the footer" or "the empty state".
+
+| Source | Go here for |
+|---|---|
+| [Footer.design](https://www.footer.design) | Footers only. Narrow on purpose, and the narrowness is why it is good. |
+| [Collect UI](https://collectui.com) | Daily-UI-style collections by component and pattern. |
+| [UI Garage](https://uigarage.net) | Patterns tagged by element and by industry. |
+| [UI Movement](https://uimovement.com) | Motion and interaction specifically — pair with the frequency gate in `../../animate/SKILL.md` before copying anything. |
+| [Dark.design](https://dark.design) · [Dark Mode Design](https://darkmodedesign.com) | Dark interfaces done properly, which is a different problem from inverting a light one. |
+| [Scrnshts](https://scrnshts.club) | App Store screenshot design — a real discipline of its own. |
+
+## Design systems as the canonical answer
+
+Not inspiration: **specification**. When the question is "what is the correct behaviour for this
+component", these outrank any gallery.
+
+| Source | Go here for |
+|---|---|
+| [Material 3](https://m3.material.io) | Google's system. Exhaustive on states, motion and tokens. |
+| [Apple HIG](https://developer.apple.com/design/human-interface-guidelines) | The reference for platform behaviour and for what *not* to invent on Apple platforms. |
+| [Shopify Polaris](https://polaris.shopify.com) | Dense, commerce-grade product UI with unusually good content guidance. |
+| [IBM Carbon](https://carbondesignsystem.com) | Enterprise density and data-heavy patterns. |
+| [GitHub Primer](https://primer.style) | Developer-tool UI, which is the closest analogue for most rsc projects. |
+| [The Component Gallery](https://component.gallery) *(bot-blocked)* | The same component compared **across** design systems — the fastest way to see the range of correct answers. |
+| [Adele](https://adele.uxpin.com) | Index of public design systems and their pattern libraries. |
+| [Designsystems.com](https://www.designsystems.com) | Essays on building and maintaining a system, not a system itself. |
+
+## Niche, but the right answer when it fits
+
+| Source | Go here for |
+|---|---|
+| [Interface In Game](https://interfaceingame.com) | Game UI. Useful well beyond games for diegetic and high-density HUD ideas. |
+| [Mobile.design](https://mobile.design) | Mobile-first patterns collected on their own terms. |
+
+## Housekeeping
+
+- **[Bestfolios](https://www.bestfolios.com) returned 502 on 2026-08-24** and is excluded until it
+  comes back. Do not cite it.
+- **Component ideas**, as opposed to whole pages, live in
+  `../../pick-ui-library/references/component-galleries.md` — Aceternity, 21st.dev, React Bits.
+- **Identity outranks all of this.** Check `02-DOCS/wiki/brand/` for what the project refuses before
+  bringing an idea back. A gallery cannot know what your brand vetoed.

package/skills/design/references/research-method.md

@@ -145,3 +145,10 @@ When the direction changes mid-project (new competitor, pivot), re-run the loop
 - `visual-system.md` — turn the filled direction into tokens.
 - `../../nextjs/SKILL.md` — implement the chosen direction on the App Router stack.
 - *frontend-design-direction* — product-domain direction judgment (external reference, not a repo skill).
+
+## Where to look
+
+`inspiration-sources.md` is the dated registry of where to browse: whole pages to beat, SaaS and
+conversion surfaces, real product flows (Mobbin, Page Flows — the bucket most people skip), single
+patterns like footers and empty states, and the design systems that are specification rather than
+inspiration. Extract principles, not pixels, and come back with a named page rather than a gallery.

package/skills/design/references/starting-point.md

@@ -0,0 +1,75 @@
+# Reference — proposing a starting point
+
+Three places promise to propose one: `../../design-loop/SKILL.md` phase 1 when the user says *skip*,
+the closing line of `brand-grounding.md` when a visual dimension has no direction, and
+`../../design-dna/SKILL.md`'s REUSE mode. This file is what they propose *from*. Without it the
+fallback is your own prior, which is the AI-template median — the thing the whole area exists to escape.
+
+## 0. What the project already owns wins
+
+**Look before you offer.** Run it; do not reason about it:
+
+```bash
+npx @ericrisco/rsc doctor --json   # read `designStartingPoint`
+```
+
+| State | What it means | What you do |
+| --- | --- | --- |
+| `owned` | An identity article or at least one legible style record exists | Propose **that**, by name, first. Offer nothing external until the user rejects it. More than one record → all of them are candidates, ordered as reported. Never pick one silently. |
+| `none` | Looked in both scopes, found nothing | Go to §1. |
+| `inconclusive` | Something could not be read | Say what, and ask for another route to it. **Do not propose past a blind spot** — a proposal made without looking is the defect this file exists to remove. |
+
+If the owned identity **contradicts** what the user is now asking for, name the conflicting rule and let
+them decide which wins. Same rule the loop's preflight already applies to a bar from outside.
+
+A record that `doctor` reports with a pair below its contrast floor is not offered as a starting point.
+
+## 1. What are you building → which bar
+
+At most **three** candidates. Each one gets a name, one line on why it fits *this* product, and one line
+on when it would be the wrong choice. Then **wait**. No answer → take the most demanding one and say so.
+
+Sources are in `inspiration-sources.md`; the tier-1 set and the dated-looking list are in
+`trends-2026.md`. **Only propose what you can actually open** — that registry marks several sources as
+bot-blocked, and a bar that cannot be fetched dies in the loop's preflight.
+
+| Building | Candidate bars | Wrong choice when |
+| --- | --- | --- |
+| SaaS marketing | Stripe · [SaaS Landing Page](https://saaslandingpage.com) browsed by section · Linear | The product is a daily tool, not a purchase decision — a marketing skin on a workhorse |
+| Dev tool | Linear · Vercel · Resend · [Primer](https://primer.style) | The audience is not technical: dev-tool restraint reads as unfinished to them |
+| Dashboard / internal tool | [Carbon](https://carbondesignsystem.com) · [Polaris](https://polaris.shopify.com) · [Mobbin](https://mobbin.com) flows | It is a landing page with a chart on it — density is not the job |
+| Portfolio / editorial | [Awwwards](https://www.awwwards.com) · [Recent](https://recent.design) · [One Page Love](https://onepagelove.com) | Anything with a conversion target: award craft routinely costs LCP and the 5s test |
+| E-commerce | [Minimal Gallery](https://minimal.gallery) for restraint · [Nicely Done](https://nicelydone.club) for real product surfaces | The catalogue is huge and the real problem is search and filtering, not the hero |
+| Docs | [Stripe docs](https://docs.stripe.com) · [Material 3](https://m3.material.io) on states | Reading is not the job — it is a reference table, so density beats calm |
+
+Nothing here fits what they are building? **Say so and interview.** Do not stretch the nearest row: a bar
+chosen because it was closest is the vague bar that makes the loop approve everything on round one.
+
+## 2. A proposal is not an answer
+
+1. **Open the reference.** No value is proposed from a page you did not fetch. Blocked → say so, pick
+   another. Never substitute a description from memory.
+2. **Measure it** — the loop's teardown already does this and writes 5 to 7 mechanisms. Those measured
+   values *are* the researched default this file was missing. They are not invented, and they come from
+   a page that already ships.
+3. **Check colour before writing it.** Any text pairing must measure **≥ 4.5:1** (≥ 3:1 for large text
+   and UI). Below that, it is **not proposed** — not proposed-with-a-warning.
+4. **Write it marked `propuesto`, naming the reference it came from.** Never as a confirmed value.
+5. A dimension that is proposed and not yet confirmed **does not count as complete** against
+   `brand-grounding.md`'s checklist. The hard STOP stays up for it. Otherwise the prefill becomes the
+   way to cross the gate with nobody having confirmed anything.
+6. Only what the user confirms becomes the project's identity.
+
+## 3. The base is the floor, not the concept
+
+A starting point gets you a defensible floor in one exchange. It does **not** satisfy the ONE signature
+element (`signature-and-craft.md` §2), and it never will: every project that picked the same bar would
+converge on the same page. If the only thing making this surface distinctive is the bar it started from,
+there is no concept yet.
+
+## See Also
+
+- `inspiration-sources.md` — the source registry, dated, with the bot-blocked entries marked.
+- `trends-2026.md` — the tier-1 set, and what currently reads as a template.
+- `brand-grounding.md` — the checklist this fills in, and the STOP it does not lift.
+- `signature-and-craft.md` — the part a starting point cannot give you.

package/skills/design-dna/SKILL.md

@@ -25,6 +25,10 @@ Nobody wrote down **why** the winner was beautiful. Next time you ask for "the s
 
 If a `dna.json` already exists for the style named, you are in REUSE. Never re-derive a style that has a record.
 
+To find out which records exist — in either scope, without guessing at paths — run
+`npx @ericrisco/rsc doctor --json` and read `designStartingPoint`. A record it reports as `unreadable`
+is **not** a record you can reuse: say what is missing, do not use half of one.
+
 ## Hard rules (these are the skill)
 
 1. **A specification that cannot fail is not a specification.** If every rule you wrote is one a bad output could still satisfy, you wrote a mood board.

package/skills/design-loop/SKILL.md

@@ -34,7 +34,15 @@ website", "good SaaS design"), push once for the specific page or file: a critic
 reference invents the comparison and approves everything on round one.
 
 On *skip*, propose three candidate bars, one line each on why, and wait. No answer → take the
-hardest one and say so.
+hardest one and say so. **Where they come from:** `../design/references/starting-point.md` — run its
+step 0 first, because a bar the project already owns outranks anything you would pick from outside,
+and proposing from memory is how this promise used to resolve to the AI-template median.
+
+**Where to go looking.** For a whole page to beat, and for the flows and single patterns behind it:
+`../design/references/inspiration-sources.md`. For a component idea rather than a whole reference:
+`../pick-ui-library/references/component-galleries.md`. Browse for the technique, never to clone a
+competitor's exact grid — and come back with **a specific page you can open**, because a gallery
+is not a bar.
 
 ## Phase 2 — Preflight
 

package/skills/eli5/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: eli5
+description: "Use when a topic must be explained from zero to someone who knows nothing about it: one page, big pictures, very few words, everyday analogies, no jargon and nothing assumed. NOT the smallest in-conversation visual for someone already following (that is `show-me`), NOT a course with exercises (that is `course-builder`)."
+tags: [eli5, explain, beginner, simple, analogy, no-jargon, explicame]
+recommends: [show-me, technical-writing, course-builder]
+profiles: [minimal, core, full]
+origin: risco
+---
+
+# eli5 — explain it to someone who knows nothing
+
+The topic is whatever the user named. With no topic named, it is the one the conversation is already
+on. The audience is someone with **zero** background: no vocabulary, no context, no patience for a
+definition that needs another definition.
+
+## The contract
+
+1. **A page, not a paragraph.** The output is one self-contained HTML page, big visuals first, words
+   second. Open it when it is written.
+2. **Picture carries the idea, words label it.** If the page still makes sense with the text removed,
+   it is working. Aim for a caption per picture, not a paragraph per picture.
+3. **Everyday objects only.** Compare to things a person has physically handled: boxes, keys, queues
+   at a counter, post, a light switch. Never explain one unknown with another unknown.
+4. **Zero jargon, and zero smuggled jargon.** No term appears without being shown first. "It caches"
+   is jargon; "it keeps a copy nearby so it doesn't have to walk back" is the same fact.
+5. **Simple, never false.** When the simplification would make something untrue, say what got left
+   out, in one line, at the end. A comfortable lie is worse than a hard truth.
+6. **No condescension.** Simple words, adult tone. The reader is new to the topic, not a child.
+
+## The shape of the page
+
+```text
+one sentence: what this thing is, in words a stranger would use
+big picture 1 : the thing, drawn
+big picture 2 : the thing doing its job, step by step
+one line      : the part people get wrong
+one line      : what this explanation left out (only if it left something out)
+```
+
+Three to five visuals is the whole page. Inline SVG or plain HTML boxes beat any chart library here:
+the drawing has to be readable on a phone, at a glance, with no legend to study.
+
+```bash
+open path/to/eli5-<topic>.html
+```
+
+## Anti-patterns
+
+| Anti-pattern | Why it fails | Do this instead |
+| --- | --- | --- |
+| Define a term with two more terms | The reader loses the thread on line one | Show the thing, then name it |
+| A wall of text with one decorative image | That is a blog post with a picture | Picture first, caption second |
+| "Imagine you're a packet travelling…" | Cute framing, still abstract | Compare to an object the reader has held |
+| Simplify until it is wrong | The reader now has to unlearn it | Keep it true and name what you dropped |
+| Baby talk, emoji, exclamation marks | Talks down to the reader | Plain adult words, short sentences |
+| Five diagrams of the same idea | Repetition reads as padding | One picture per genuinely new idea |
+
+## Where this ends
+
+- Someone already following the conversation who needs the shape of one mechanism: `show-me`.
+- A structured curriculum with exercises, assessment and progression: `course-builder`.
+- Documentation an informed reader will keep coming back to: `technical-writing`.
+- Making an existing text sound human rather than simpler: `bro`.

package/skills/eli5/evals/README.md

@@ -0,0 +1,22 @@
+# Evals — eli5
+
+Two claims: that a from-zero request routes here instead of to the in-conversation visual skill or to
+teaching material, and that the loaded skill produces a page a genuine beginner can follow.
+
+## Triggering
+
+Load only `eli5` and run every prompt in 3–5 fresh sessions. A positive passes when `eli5` loads in a
+majority of trials; a negative passes when it stays quiet and the declared `route_to` skill is the
+real owner. Require at least 90% accuracy.
+
+`show-me` is the negative that matters: both are "explain it visually". The discriminator is the
+reader's starting knowledge, and it must survive any description edit on either side.
+
+## Capability
+
+Run the scenario without the skill and with it, same topic and one grader, three trials. The
+with-skill condition must satisfy at least 80% of the rubric and beat the baseline by at least 20
+percentage points.
+
+Grade the jargon point strictly: a baseline answer almost always keeps one unexplained term, which is
+exactly the failure the skill exists to prevent.

package/skills/eli5/evals/cases.yaml

@@ -0,0 +1,54 @@
+skill: eli5
+
+# `eli5` owns one move: a from-zero explanation of one topic, as a page of big
+# pictures and few words, for someone with no background at all. It does not own
+# in-conversation diagrams for someone already following, curricula, or docs.
+should_trigger:
+  - prompt: "Explícame qué es una API como si tuviera cinco años."
+    why: "The canonical from-zero request, named outright, in the user's own language."
+
+  - prompt: "My mum asked me what a VPN is. I need something she can actually look at."
+    why: "A named audience with zero background and an explicit ask for something visual."
+
+  - prompt: "eli5 how a blockchain works"
+    why: "The bare skill name plus a topic is the shortest form of the same request."
+
+  - prompt: "No tengo ni idea de esto. Empieza por lo más básico, sin palabras raras."
+    why: "Zero background plus an explicit no-jargon constraint, with no topic named: the topic is the current one."
+
+  - prompt: "Can you explain what an index is in a database, but for someone who has never programmed?"
+    why: "A technical topic aimed at a non-technical reader is the audience this skill is written for."
+
+  - prompt: "Necesito explicarle a mi cliente, que no es técnico, qué es un webhook. Que lo entienda de una."
+    why: "Explaining to a named non-technical third party is the same job, one step removed."
+
+should_not_trigger:
+  - prompt: "Show me the call order when the form is submitted, I'm lost in the code."
+    route_to: "show-me"
+    why: "The user is already inside the topic and needs one mechanism drawn, not a from-zero page."
+
+  - prompt: "Build a four-week course on SQL with exercises and a final project."
+    route_to: "course-builder"
+    why: "Curriculum, progression and assessment are course-builder; eli5 is a single explanation."
+
+  - prompt: "Write the getting-started docs for our SDK, with runnable examples."
+    route_to: "technical-writing"
+    why: "Reference and tutorial documentation is technical-writing, even when it must be beginner-friendly."
+
+  - prompt: "Make this paragraph sound less robotic before I send it."
+    route_to: "bro"
+    why: "A register and tone pass over existing text is bro; nothing here needs explaining from zero."
+
+  - prompt: "Design the hero section for our homepage so it feels premium."
+    route_to: "design-loop"
+    why: "Visual identity is the design area; eli5's visuals serve comprehension, not brand."
+
+capability:
+  - scenario: "A non-technical business owner asks what a webhook is, after two failed explanations that used the words 'endpoint', 'payload' and 'HTTP POST'."
+    must_include:
+      - "produces one self-contained page with three to five large visuals, not a wall of text"
+      - "uses an everyday physical analogy the reader has handled, not another abstraction"
+      - "introduces no term without showing the thing first, and never uses endpoint, payload or POST unexplained"
+      - "keeps the explanation true, and names in one line whatever was left out"
+      - "stays adult in tone: no baby talk, no emoji, no exclamation marks"
+      - "opens the page for the user instead of only writing the file"

package/skills/pick-ui-library/SKILL.md

@@ -27,6 +27,7 @@ A lookup skill. When invoked with a task ("I need toasts", "what should I use fo
 2. **Check what's already installed.** Look at `package.json` first. If the project already uses a listed library, use it. If it uses a competitor (e.g. react-window instead of Virtuoso), flag the recommendation but don't churn the dependency without being asked.
 3. **Recommend one library**, state what it's for in one sentence, and install/wire it up if that's part of the request. Don't present a menu of options when the list has a clear answer.
 4. If the task isn't covered by the list, say so explicitly and recommend from your own knowledge — but be clear you've left the curated list.
+5. **Need an idea rather than a library?** Go and look: `references/component-galleries.md` names where to browse for component ideas (Aceternity for marketing effects, 21st.dev for breadth, React Bits for tunable animation) and what each is good for. Take the technique, build it in the project's own tokens.
 
 ## The list
 

package/skills/pick-ui-library/references/component-galleries.md

@@ -0,0 +1,59 @@
+# Reference — where to go looking for component ideas
+
+> Last verified: **2026-08-24** — all three returned HTTP 200 on that date.
+
+**Go and look.** When you need a component idea and your own prior is the median of every AI template
+ever scraped, these are the places to browse instead of inventing from memory. Open them, see what
+exists, come back with something specific.
+
+## Where to go, and for what
+
+### [Aceternity UI](https://ui.aceternity.com/components) — effects for a surface that must stop the scroll
+
+Go here for **motion and atmosphere on a marketing surface**, not for primitives. What's there:
+
+- **Backgrounds:** Aurora, Beams, Vortex, Sparkles, gradient fields
+- **Cards:** 3D tilt, hover reveal, card stack, spotlight
+- **Text:** typewriter, flip, encrypted/scramble, generate-in, canvas text
+- **Scroll:** sticky scroll, container scroll, hero parallax
+- **Navigation:** floating navbar, floating dock, sidebar, notch, tabs
+- **Buttons:** magnetic, moving border, hover gradient
+- **Data as spectacle:** globe, timeline, world map, before/after compare
+- **Whole sections:** hero, pricing, testimonials, CTA, feature blocks
+
+Best used when you can name the feeling you want and need to see how someone already built it.
+
+### [21st.dev](https://21st.dev/community/components) — breadth, ranked by what people actually use
+
+A community registry rather than a curated library, so it's the widest net of the three. Marketing
+blocks *and* real UI — buttons, cards, forms, modals, inputs, tables — plus Shaders and ASCII art.
+Sortable by popular and newest, with view counts.
+
+Go here when you don't know what you're looking for yet and want to see the range. Read the code of
+anything you like: community means unvetted, and popularity is not review.
+
+### [React Bits](https://reactbits.dev/get-started/index) — animated interactions, deeply customizable
+
+~46k stars. Animations, 3D, CSS effects, built to be tuned rather than dropped in.
+
+Go here when Aceternity's version of an effect is close but you need to control it.
+
+## Two things to carry with you
+
+**Ideas travel; code stays there.** Take the technique, the ratio, the interaction — then build it in
+the project's own tokens. Never vendor a gallery's source into this catalog: rsc ships publicly (P9),
+and React Bits' licence (MIT + Commons Clause) forbids redistributing its components outright. In the
+user's own project, installing any of the three is fine.
+
+**Identity outranks the gallery.** Check `02-DOCS/wiki/brand/` for what this project refuses before
+pulling an idea. A lot of what these galleries do best — aurora and gradient-mesh backgrounds,
+glassmorphism, neon, blobs, decorative 3D — is also on the AI-tell list in
+`../../design/references/ai-tells.md`, and some brand studies veto it by name. And run the frequency gate
+from `../../animate/SKILL.md`: a spotlight card earns its place on a hero someone sees once, and never on
+a table they open forty times a day.
+
+## Not a substitute for the primitives
+
+A dialog still comes from `base-ui`, a toast from Sonner, a command palette from cmdk. Focus trapping,
+dismissal and accessibility are solved; an animated card does not replace a solved primitive. Use
+`SKILL.md`'s list for the task, and this file for the look.

package/skills/show-me/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: show-me
+description: "Use when the user needs to see how something works instead of reading about it: picks the smallest visual that carries the point — pseudocode, call tree, file tree, component tree, Mermaid, a shaped diff, or one HTML page. NOT visual identity (that is `design-loop`), NOT slides (that is `presentations`), NOT a from-zero explainer (that is `eli5`)."
+tags: [show-me, explain, diagram, visual, mermaid, diff, call-tree, ensename]
+recommends: [eli5, presentations, technical-writing, codebase-onboarding]
+profiles: [minimal, core, full]
+origin: risco
+---
+
+# show-me — the smallest picture that answers the question
+
+A second paragraph never fixes the first one. Pick the smallest view that makes the point, put two
+lines of prose beside it, stop.
+
+## The contract
+
+1. **One form, chosen on purpose.** Read what the question is *about*, pick the matching form from
+   the table, draw that. Several forms in one answer is the failure mode, not thoroughness.
+2. **Only the parts that answer the question.** Keep the calls, files, props, states and boundaries
+   the user asked about. Everything else is noise that hides the answer.
+3. **Prose shrinks to fit.** No preamble, no "here is a diagram of". The picture leads; the words
+   caption it.
+4. **Real names.** Actual paths, actual function and component names, actual state values. A diagram
+   of `ServiceA → ServiceB` explains nothing.
+5. **Say so when there is nothing to draw.** A topic with no shape gets a straight answer in prose.
+   A decorative diagram costs the reader time and buys nothing.
+
+## Pick the form from what the topic is
+
+| The question is about | Draw | Why this one |
+| --- | --- | --- |
+| Logic, an algorithm, a decision | pseudocode | branches read top-down; syntax would distract |
+| What calls what at runtime | call tree | shows order and nesting, which prose loses |
+| UI structure | component tree, with state and module boundaries | ownership is the answer most of the time |
+| Which file is responsible for what | shallow file tree with one comment per entry | depth hides the point; one level shows it |
+| Interaction, control flow, data flow between pieces | Mermaid sequence or flow diagram | two-way traffic over time needs an axis |
+| What changes in a shape that already exists | `diff`, in the shape of the topic | the reader keeps their bearings |
+| Layout, visual state, a dense comparison | one self-contained HTML page | text cannot hold it |
+| Nothing with a shape | prose | see contract rule 5 |
+
+```text
+on(save)
+  if content is unchanged
+    return cached result
+  write new content
+  return fresh result
+```
+
+```text
+submitForm
+  createSession
+    persistPrompt
+    launchAgent
+  navigateToSession
+```
+
+```tsx
+<SessionPage> (apps/example/src/routes/session.tsx)
+  useSessionEvents()
+  <SessionToolbar>
+    <RunSkillButton> (packages/ui)
+```
+
+```text
+src/
+├── commands/       # parses user actions
+├── sessions/       # owns session state
+└── transport/      # sends API requests
+```
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant UI
+    participant Daemon
+    User->>UI: choose command
+    UI->>Daemon: send expanded prompt
+    Daemon-->>UI: stream result
+```
+
+## The diff rule
+
+Use `diff` when the surrounding shape already exists and the point is what moves. **Match the diff
+to the topic**: a component change is a component diff, a layout change is a file-tree diff, a
+control-flow change is a pseudocode diff. A unified source diff for a structural change makes the
+reader rebuild the structure in their head.
+
+```diff
+ src/
+ ├── commands/
++│   └── show-me.ts       # expands the slash command
+ ├── sessions/
+-└── transport.ts
++└── transport/
++    ├── client.ts
++    └── stream.ts
+```
+
+```diff
+ on(save)
+-  write content
++  if content is unchanged
++    return cached result
++  write new content
++  invalidate cache
+```
+
+Show the whole block instead of a diff when most of it is new, when the omitted context would hide
+ownership or order, or when the user needs something copyable.
+
+## When it earns an HTML page
+
+Layout, visual state, a side-by-side comparison, or a concept too dense for a text diagram. One
+page, self-contained, real labels and real data, readable on a phone and on a desktop. Inherit the
+product's colours, type and spacing from where it lives; this skill borrows an identity, it never
+invents one. Then open it:
+
+```bash
+open path/to/show-me-<topic>.html
+```
+
+## Anti-patterns
+
+| Anti-pattern | Why it fails | Do this instead |
+| --- | --- | --- |
+| Ship four forms because each adds a little | The reader now has to pick; that was your job | One form, the smallest that answers it |
+| Diagram the whole system when asked about one path | The answer is in there somewhere, which is the same as absent | Draw the path, drop the rest |
+| Placeholder names (`ModuleA`, `doThing`) | Nothing maps back to the codebase | Real paths and real identifiers |
+| A unified source diff for a structural change | Forces the reader to rebuild the shape | Diff in the shape of the topic |
+| Mermaid for a layout question | Boxes and arrows cannot show visual space | One HTML page |
+| A diagram to look thorough | Costs attention, adds nothing | Answer in prose and say why there is nothing to draw |
+
+## Where this ends
+
+- The visual **identity** of an interface, a landing page or a poster is `design-loop` and `design`.
+- A **deck** someone presents from is `presentations`.
+- **Zero prior knowledge**, big pictures, few words, is `eli5`.
+- Restructuring a document, a README or a reference is `technical-writing`.
+- A guided tour of an unfamiliar repository is `codebase-onboarding`; this skill draws the pieces it
+  finds, it does not run the tour.

package/skills/show-me/evals/README.md

@@ -0,0 +1,23 @@
+# Evals — show-me
+
+Two claims are under test: that "show me / I don't get it / draw me" routes here without stealing
+design, deck or beginner-explainer work, and that the loaded skill answers with **one** well-chosen
+visual instead of more prose.
+
+## Triggering
+
+Load only `show-me` and run every `should_trigger` and `should_not_trigger` prompt in 3–5 fresh
+sessions. A positive passes when `show-me` loads in a majority of trials. A negative passes when it
+stays quiet and the declared `route_to` skill is the genuine owner. Require at least 90% accuracy.
+
+The negatives that matter most are `eli5` and `design-loop`: both are adjacent enough that a sloppy
+description pulls them in. Re-run these two after any description edit.
+
+## Capability
+
+Run the scenario in two fresh conditions, without the skill and with it, same source discussion and
+one grader. Score each `must_include` point over three trials. The with-skill condition must satisfy
+at least 80% of the rubric and beat the baseline by at least 20 percentage points.
+
+The discriminating point is **form choice**: a baseline answer typically produces prose plus a
+generic box diagram. Count "picked one form, and the right one" strictly.

package/skills/show-me/evals/cases.yaml

@@ -0,0 +1,61 @@
+skill: show-me
+
+# `show-me` owns one move: the smallest visual that answers the question being
+# asked, placed inside the conversation. It does not own visual identity, decks,
+# teaching material for a beginner, or restructuring a document.
+should_trigger:
+  - prompt: "No entiendo cómo funciona el login. Enséñamelo."
+    why: "An explicit ask to be shown rather than told, about a mechanism that has a shape to draw."
+
+  - prompt: "Can you show me visually how these three services talk to each other?"
+    why: "Interaction between pieces over time is the canonical Mermaid sequence case."
+
+  - prompt: "Draw me the component tree of this page so I can see which component owns the form state."
+    why: "UI structure with an ownership question is the component-tree form, named outright."
+
+  - prompt: "Antes de tocar nada, qué archivo es responsable de qué en src/?"
+    why: "File responsibility maps to the shallow file tree; the user wants the shape before editing."
+
+  - prompt: "I read your explanation twice and still don't get the order things happen in. Picture?"
+    why: "A second failed prose attempt is the trigger this skill exists for; runtime order is a call tree."
+
+  - prompt: "Show me what would change in the folder layout if we split transport.ts into a module."
+    why: "A change to an existing shape is the shaped-diff case, with the diff in the topic's own form."
+
+  - prompt: "Explícame con un diagrama qué pasa cuando el usuario cancela a mitad del pago."
+    why: "An edge path through a flow, explicitly requested as a diagram."
+
+should_not_trigger:
+  - prompt: "Design the landing page for our new pricing tier, it should look premium."
+    route_to: "design-loop"
+    why: "Visual identity and composition are owned by the design area; show-me explains, it does not design."
+
+  - prompt: "Build me a 12-slide deck to present the roadmap to the board on Thursday."
+    route_to: "presentations"
+    why: "A deck someone presents from is presentations; this skill draws inside the conversation."
+
+  - prompt: "Explain how a database index works to someone who has never programmed, like they're five."
+    route_to: "eli5"
+    why: "Zero prior knowledge with big pictures and few words is eli5's contract, not the smallest in-context visual."
+
+  - prompt: "Reorganise this README into a proper tutorial and an API reference."
+    route_to: "technical-writing"
+    why: "Restructuring a document is technical-writing; a diagram inside it would be at most one paragraph of the job."
+
+  - prompt: "Walk me through this whole unfamiliar repo: what it does, how it's built, where to start."
+    route_to: "codebase-onboarding"
+    why: "A guided tour of an unknown codebase is its own skill; show-me only draws the pieces once they are known."
+
+  - prompt: "Build a dashboard with our monthly revenue and churn charts."
+    route_to: "dashboard"
+    why: "A standing analytics surface is dashboard; this is not an explanation of a mechanism."
+
+capability:
+  - scenario: "The user asks, after a dense prose answer, why saving a document sometimes does not trigger a re-render. The real cause is a cache check inside the save handler plus a subscription set up after navigation. Show them."
+    must_include:
+      - "picks one form rather than stacking several, and the form matches the topic (control flow or call tree, not a file tree)"
+      - "uses the real handler, cache and subscription names from the discussion instead of placeholders"
+      - "shows only the path involved in the bug, not the whole module"
+      - "puts at most two lines of prose beside the visual, with no 'here is a diagram of' preamble"
+      - "marks what changes with a diff in the topic's own shape if it proposes a fix"
+      - "does not produce an HTML page for something a text diagram already carries"