wizz-method 2.21.0 → 2.23.0

package/src/skills-lib/wizz-premium-landing-ui-researcher/references/audit-protocol.md

@@ -4,51 +4,24 @@ The Source-First Protocol takes care of the **beginning** (curating mature sourc
 
 Apply 3 passes in order. Each catches a different class of problem: using the first two is redundant only 60% of the time; in the other 40%, one catches what the other missed.
 
-### Pass 1: Taste Skill (early, before full implementation)
+### Pass 1: Taste (early, before full implementation)
 
 **When to apply:** right after Phase 5 of the Source-First Protocol, when you have a mockup/wireframe of the sections or a first version of the hero implemented. Ideally there's still time to swap a component without high cost.
 
-**Source:** `https://github.com/Leonxlnx/taste-skill.git`
+**Run:** invoke `skill:wizz-taste-skill` in audit mode. Its checklist is the list for this pass: [design-audit](../../wizz-taste-skill/references/design-audit.md) and [anti-slop-tells](../../wizz-taste-skill/references/anti-slop-tells.md), including the landing-page tells of section 9.H. This protocol keeps only when to run it, the angle and the output, so the list has one owner and cannot drift.
 
 **Angle:** an anti-AI-generic detector. Key question: *"Could this layout belong to any generic SaaS, or does it have an authorial signature?"*
 
-**What to look for and flag as a problem:**
-
-- A hero with "big headline + subtitle + 2 side-by-side CTAs" with no identity of its own
-- Features in a 3-col grid with cute decorative icons (the "✨ Fast 🚀 Reliable 🔥 Secure" style)
-- Saturated color gradients with no purpose (purple-to-pink, blue-to-cyan, the default Tailwind look)
-- AI copy: "revolutionize your workflow", "supercharge your business", "10x your results"
-- A perfectly symmetrical layout with no editorial tension
-- Excessive rounded corners (`rounded-3xl` on everything)
-- Card stacks with the default Tailwind `shadow-xl`
-- Decorative emoji anywhere other than status microcopy
-- Generic testimonial cards with a round avatar + name + title + quoted sentence
-- Pricing cards with a centered, gradient "Most Popular" badge
-
-**Pass output:** a list of up to 5 spots where the landing page looks templated, with a **replacement** suggestion for each one (a component from an authorized source, an editorial decision, or removal). Present it to the user before proceeding.
+**Pass output:** a list of up to 5 spots where the landing page looks templated, with a **replacement** suggestion for each one (a component from an authorized source, an editorial decision, or removal). Present it to the user before proceeding. A replacement that needs a new component reopens the need in `design-state.yaml` instead of starting a fresh search.
 
 ### Pass 2: Impeccable (late, with real tokens and content)
 
 **When to apply:** after the implementation is assembled with brand tokens, real typography, real images/mockups. Catches problems that only appear once the component is alive, not in a wireframe.
 
-**Source:** `https://github.com/pbakaus/impeccable.git`
+**Run:** invoke `skill:wizz-impeccable` with `critique` (or `polish` when fixing). Its ruleset is the list for this pass: [design-rules](../../wizz-impeccable/references/design-rules.md), including the "Landing fine-tuning" block. Same split as Pass 1: the list lives in the skill, the timing and output live here.
 
 **Angle:** classic design chops. Key question: *"Does this look like it was made by a senior designer with 10+ years of editorial background?"*
 
-**What to look for and flag as a problem:**
-
-- **Spacing**: inconsistent padding/margin between sections (24px here, 28px there, 32px elsewhere). Define and follow a scale (4/8/12/16/24/32/48/64/96/128)
-- **Hierarchy**: headings competing with each other for weight/size. H1, H2, H3 should have clear contrast
-- **Leading**: `line-height` too tight in body text (<1.5) or too loose in headlines (>1.15)
-- **Tracking**: wrong letter-spacing on small uppercase text (mono labels need more tracking, ~0.18em)
-- **Optical alignment**: icons with a different visual weight than adjacent text, mono numbers not monospaced vertically
-- **Vertical rhythm**: scrolling with no breathing room (section after section with no air) or with unexplainable huge gaps
-- **Color hierarchy**: 5+ shades of gray for text with no justification, accent color used on things that aren't actionable
-- **Image cropping**: thumbnails with inconsistent aspect ratio between cards
-- **Typographic contrast**: heavy headings + heavy body text too (missing a light/regular weight to create contrast)
-- **Edge cases**: what happens when the project name has 4 words vs. 1? And when the description has 2 lines vs. 4?
-- **Focus states**: does the tab order deliver an editorial sequence, or does it jump around chaotically between sections?
-
 **Pass output:** a list of up to 7 fine-tuning adjustments with specific **before/after** (e.g., "Hero subhead: change leading 1.1 → 1.3" / "Cards grid: align the mono numbering baseline with the card headline baseline").
 
 ### Pass 3: Cross-check with references
@@ -82,7 +55,7 @@ agent-browser eval "<js>"       # 4. measure tokens (computed styles, etc.)
 **Diagnosis:**
 
 - If the difference is **taste/direction** (conscious brand choices) → ok, keep it
-- If the difference is **execution** (the reference has polish yours is missing) → go back to Source-First and find the missing component
+- If the difference is **execution** (the reference has polish yours is missing) → reopen the need in `design-state.yaml` (status `open`, with the discoveries already rejected carried forward) and mine it again; with no state file, go back to Source-First and find the missing component
 - If the difference is **motion fluidity** → review timing, easing, scale, and animation composition (the Design Motion Principles were probably not applied)
 - If the difference is **visual density** (the reference is more spaced out and breathes more) → cut elements, don't add
 
@@ -106,8 +79,8 @@ Not a matter of taste, it's technical quality. Check:
 
 | Pass | When | Adjustment cost | Frequency |
 |---|---|---|---|
-| 1. Taste Skill | Wireframe / hero first | Low (component can still be swapped) | Always |
-| 2. Impeccable | Implementation with real tokens | Medium (fine CSS) | Always |
+| 1. Taste (`wizz-taste-skill`) | Wireframe / hero first | Low (component can still be swapped) | Always |
+| 2. Impeccable (`wizz-impeccable`) | Implementation with real tokens | Medium (fine CSS) | Always |
 | 3. Cross-check | Final visual | Variable | Always |
 | 4. Accessibility + Perf | Before delivering | Medium-high (may require refactor) | Always |
 

package/src/skills-lib/wizz-premium-landing-ui-researcher/references/component-sources.md

@@ -1,3 +1,5 @@
+> To pick a source, query [design-sources.yaml](design-sources.yaml) with `scripts/design_sources.py list --need <tag>`; this page is the policy and nuance behind those rows, read when a source needs it.
+
 ## Source Access Strategy
 
 Prioritize free, open source, public, registry-based sources or sources provided by the user.
@@ -101,6 +103,18 @@ As of 2026-10-15 the shadcn index marks `@styleui` as **degraded** (sampled item
 - Priority source for: SaaS dashboards, data viz, metrics/stats sections on the landing page, premium animated charts (complements/replaces raw Recharts)
 - The Bklit Studio (playground) is proprietary; the components themselves are MIT
 
+### ReUI
+
+- Site: https://reui.io/ · GitHub: https://github.com/keenthemes/reui (MIT, free)
+- shadcn components and blocks (forms, tables, dialogs, pricing, dashboards). Confirm the registry namespace in the live index before `npx shadcn add`.
+- Use for: app sections and dashboard blocks when the project already runs on shadcn.
+
+### Thinking Orbs
+
+- GitHub: https://github.com/Jakubantalik/thinking-orbs (MIT) · `npm i thinking-orbs`
+- 9 animated canvas orbs, one per AI state (working, searching, solving, listening, connecting...).
+- Use only when the product has an agent or AI chat UI and needs a state indicator better than a spinner. Install, never vendor.
+
 ### Skiper UI
 
 Skiper UI **must not be cloned**.
@@ -183,6 +197,17 @@ Use for: vibe coding references, prompt ideas, component inspiration, UI pattern
 
 > **Important rule:** Vibe Code Components can appear under `Reference Sources` and `Visual Inspiration Sources`, but must not be treated as primary implementation sources like React Bits, Cult UI, Watermelon, or StyleUI.
 
+### Tokens, design systems and the final audit
+
+A model asked to "make it look good" averages everything it has seen. Give it a closed target before the first screen:
+
+- **Open Props** (https://open-props.style/, MIT): ready-made CSS tokens for colour, spacing, radius, easing. Hand the token list over so the model stops inventing a new grey per screen.
+- **DesignSystems.one** (https://designsystems.one/): gallery of real company design systems (Material, Fluent, Carbon, Atlassian, Polaris). Pick one as the base, swap in the brand colours, give it to the model at project start.
+- **Design System Checklist** (https://www.designsystemchecklist.com/): the audit before publishing. Ask the model for the list of failing items, choose 3 and fix them one at a time. Never "fix everything": it rewrites the project and breaks what works.
+- **VibePrompt** (https://vibeprompts.dev/): UI Prompt Library with 286 layout prompts by section (auth, pricing, hero, bento, stats, FAQ, dashboard). Use one prompt as the brief for one section and swap in the project tokens; never paste a whole page of them.
+- **GetLayers** (https://www.getlayers.com/): section templates with a "copy prompt" button and an MCP. Read the licence of each item; take the structure, rebuild the code.
+- **Curated** (https://curated.design/): catalogue of real, live websites for direction. Visual only.
+
 ## Visual Inspiration Sources
 
 These are visual sources for the skill to use when it needs visual direction, inspiration, style, animation, composition, and UX. They must not be treated as a guaranteed source of code.

package/src/skills-lib/wizz-premium-landing-ui-researcher/references/design-sources.yaml

@@ -0,0 +1,325 @@
+# Design sources, as data. Read by scripts/design_sources.py (list by need tag,
+# cache freshness, refresh) so the miner does not load the whole prose catalogue
+# to pick one source. The prose in component-sources.md stays as the reference
+# for policy and nuance (Clone Policy, Paid Source Policy, visual inspiration
+# rules); this file is the one to query.
+#
+# Fields:
+#   kind     code | registry | engine | visual | taste | extractor
+#            (code/registry = evidence bar of code; visual = pattern only, rebuilt)
+#   license  what was read, with the date of the reading in `checked`; null = none
+#   access   free | free+paid | paid | login
+#   need_tags  what the source answers; matched by `design_sources.py list --need`
+#   registry   shadcn namespace and item URL template, when it has one
+#   cache      folder name under ~/.claude/design-sources/, when there is a local clone
+#   study_only true when the code must never be copied (no license)
+version: 1
+cache_root: "~/.claude/design-sources"
+max_cache_age_days: 30
+registry_index: "https://ui.shadcn.com/r/registries.json"
+
+sources:
+  - id: react-bits
+    kind: registry
+    url: "https://github.com/DavidHDev/react-bits.git"
+    registry: { namespace: "@react-bits" }
+    license: "MIT + Commons Clause"
+    checked: 2026-09-06
+    access: free+paid
+    cache: react-bits
+    need_tags: [text-animation, background, scroll, hover, card, micro-interaction, loader, hero, particles, cursor]
+    note: "React Bits Pro is never a mandatory dependency."
+
+  - id: cult-ui
+    kind: registry
+    url: "https://github.com/nolly-studio/cult-ui"
+    docs: "https://www.cult-ui.com/docs"
+    registry: { namespace: "@cult-ui" }
+    license: null
+    checked: null
+    access: free+paid
+    cache: cult-ui
+    need_tags: [marketing-section, hero, button, card, landing-section]
+    note: "Read the license of the item; public/open resources only unless paid access is confirmed."
+
+  - id: ali-imam
+    kind: visual
+    url: "https://github.com/aliimam-in/aliimam.git"
+    license: null
+    checked: 2026-10-15
+    access: free
+    cache: aliimam
+    study_only: true
+    need_tags: [shader, liquid, ripple, border-glow, bento, typewriter, canvas, experimental]
+    note: "No license: study the technique, never copy the code."
+
+  - id: watermelon
+    kind: registry
+    url: "https://github.com/WatermelonCorp/watermellon-registry.git"
+    registry: { namespace: "@watermelon", template: "https://registry.watermelon.sh/r/{name}.json" }
+    license: null
+    checked: null
+    access: free
+    cache: watermelon
+    need_tags: [dashboard, saas, card, app-section, data-viz, product-ui]
+
+  - id: styleui
+    kind: registry
+    url: "https://github.com/heyfabrika/styleui.git"
+    registry: { namespace: "@styleui" }
+    license: null
+    checked: 2026-10-15
+    access: free
+    cache: styleui
+    need_tags: [layout, template, landing-section, base-page]
+    note: "Marked degraded in the shadcn index on 2026-10-15: check health before relying on it."
+
+  - id: componentry
+    kind: registry
+    url: "https://componentry.dev/"
+    registry: { namespace: "@componentry", template: "https://componentry.fun/r/{name}.json" }
+    license: null
+    checked: null
+    access: free
+    need_tags: [text-animation, background, hover, micro-interaction, animated-component]
+
+  - id: bklit-ui
+    kind: registry
+    url: "https://github.com/bklit/bklit-ui"
+    registry: { namespace: "@bklit" }
+    license: MIT
+    checked: null
+    access: free
+    need_tags: [chart, data-viz, dashboard, metrics]
+    note: "Install from the registry, do not clone."
+
+  - id: skiper-ui
+    kind: registry
+    url: null
+    registry: { namespace: "@skiper-ui" }
+    license: null
+    checked: null
+    access: free+paid
+    need_tags: [distinctive-effect, premium-section, advanced-animation]
+    note: "Must not be cloned: npx shadcn add @skiper-ui/<item>. Premium only with confirmed access."
+
+  - id: shadcn-ui
+    kind: registry
+    url: "https://ui.shadcn.com/"
+    license: MIT
+    checked: null
+    access: free
+    need_tags: [base, form, dialog, navigation, carousel, layout]
+
+  - id: embla
+    kind: code
+    url: "https://www.embla-carousel.com/"
+    license: MIT
+    checked: null
+    access: free
+    need_tags: [carousel]
+
+  - id: animmaster
+    kind: code
+    url: "https://animmasterlib.dev/"
+    license: "commercial"
+    checked: null
+    access: paid
+    need_tags: [animated-component]
+    note: "Only with authorized access; what the user already bought counts as local material."
+
+  - id: gsap
+    kind: engine
+    url: "https://github.com/greensock/GSAP.git"
+    license: "free since v3.13, all plugins"
+    checked: null
+    access: free
+    need_tags: [scroll-storytelling, scroll, timeline, text-reveal, svg-morph]
+
+  - id: animejs
+    kind: engine
+    url: "https://github.com/juliangarnier/anime.git"
+    license: MIT
+    checked: null
+    access: free
+    need_tags: [micro-interaction, stagger, svg, counter]
+
+  - id: design-motion-principles
+    kind: taste
+    url: "https://github.com/kylezantos/design-motion-principles.git"
+    license: null
+    checked: null
+    access: free
+    need_tags: [motion-principles, easing, timing]
+
+  - id: vibe-code-components
+    kind: visual
+    url: "https://vibecodecomponents.com/"
+    license: null
+    checked: null
+    access: free
+    need_tags: [visual-direction, section-idea]
+
+  - id: landing-love
+    kind: visual
+    url: "https://www.landing.love/"
+    license: null
+    checked: null
+    access: free
+    need_tags: [visual-direction, scroll, hero, landing-section]
+
+  - id: recent
+    kind: visual
+    url: "https://recent.design/"
+    license: null
+    checked: 2026-10-15
+    access: free
+    need_tags: [visual-direction, typography, editorial, art-direction]
+
+  - id: design-spells
+    kind: visual
+    url: "https://www.designspells.com/"
+    license: null
+    checked: null
+    access: free
+    need_tags: [micro-interaction, delight, hover]
+
+  - id: spline
+    kind: visual
+    url: "https://spline.design/"
+    license: null
+    checked: null
+    access: free+paid
+    need_tags: [3d, hero]
+
+  - id: unicorn-studio
+    kind: visual
+    url: "https://www.unicorn.studio/"
+    license: null
+    checked: null
+    access: free+paid
+    need_tags: [webgl, background, shader, particles]
+
+  - id: refero
+    kind: visual
+    url: "https://refero.design/"
+    license: null
+    checked: 2026-10-15
+    access: login
+    need_tags: [ux-flow, dashboard, pricing, onboarding]
+    note: "Refero MCP is paid."
+
+  - id: refero-styles
+    kind: taste
+    url: "https://styles.refero.design/"
+    license: null
+    checked: null
+    access: free
+    need_tags: [design-md, typography, palette, spacing]
+
+  - id: awesome-design-md
+    kind: taste
+    url: "https://github.com/VoltAgent/awesome-design-md"
+    license: MIT
+    checked: 2026-10-15
+    access: free
+    need_tags: [design-md, typography, palette, spacing]
+
+  - id: mobbin
+    kind: visual
+    url: "https://mobbin.com/"
+    license: null
+    checked: 2026-10-15
+    access: login
+    need_tags: [ux-flow, onboarding, pricing, dashboard, mobile]
+    note: "Mobbin MCP is paid."
+
+  - id: screensdesign
+    kind: visual
+    url: "https://screensdesign.com/"
+    license: null
+    checked: 2026-10-15
+    access: login
+    need_tags: [mobile, onboarding, paywall, subscription]
+
+  - id: dembrandt
+    kind: extractor
+    url: "https://github.com/dembrandt/dembrandt"
+    license: MIT
+    checked: 2026-10-15
+    access: free
+    need_tags: [typography, palette, spacing, design-md]
+    note: "npx -y dembrandt@0.39.2 <url> --design-md: measures a site the user named."
+
+  - id: thinking-orbs
+    kind: code
+    url: "https://github.com/Jakubantalik/thinking-orbs"
+    license: MIT
+    checked: 2026-10-25
+    access: free
+    need_tags: [loader, ai-state, canvas, micro-interaction]
+    note: "npm thinking-orbs: 9 animated canvas orbs, one per AI state (working, searching, solving, listening...). Only for products with an agent or AI chat UI."
+
+  - id: reui
+    kind: registry
+    url: "https://github.com/keenthemes/reui"
+    docs: "https://reui.io/"
+    license: MIT
+    checked: 2026-10-25
+    access: free
+    need_tags: [form, button, dialog, data-viz, pricing, app-section, dashboard, template]
+    note: "shadcn components and blocks (485+ blocks on the site). Confirm the registry namespace in the live index before installing."
+
+  - id: open-props
+    kind: taste
+    url: "https://open-props.style/"
+    license: MIT
+    checked: 2026-10-25
+    access: free
+    need_tags: [design-md, palette, spacing, typography, easing]
+    note: "Ready-made CSS tokens. Hand the token list to the model before the first screen so it stops inventing a new grey per page."
+
+  - id: designsystems-one
+    kind: taste
+    url: "https://designsystems.one/"
+    license: null
+    checked: 2026-10-25
+    access: free
+    need_tags: [design-md, typography, palette, spacing, visual-direction]
+    note: "Gallery of real company design systems (Material, Fluent, Carbon, Atlassian, Polaris...). Pick one as a base, swap the brand colours, give it to the model at project start."
+
+  - id: design-system-checklist
+    kind: taste
+    url: "https://www.designsystemchecklist.com/"
+    license: null
+    checked: 2026-10-25
+    access: free
+    need_tags: [design-md, audit]
+    note: "Final audit before publishing: ask the model for the failing items, fix 3 at a time, never all at once."
+
+  - id: getlayers
+    kind: visual
+    url: "https://www.getlayers.com/"
+    license: null
+    checked: 2026-10-25
+    access: free+paid
+    need_tags: [hero, landing-section, 3d, section-idea]
+    note: "Section templates with a 'copy prompt' button and an MCP. Read the licence of each item; rebuild, never paste."
+
+  - id: curated-design
+    kind: visual
+    url: "https://curated.design/"
+    license: null
+    checked: 2026-10-25
+    access: free
+    need_tags: [visual-direction, landing-section, art-direction]
+    note: "Catalogue of real, live websites for direction."
+
+  - id: vibeprompts
+    kind: taste
+    url: "https://vibeprompts.dev/"
+    license: null
+    checked: 2026-10-25
+    access: free
+    need_tags: [section-idea, landing-section, pricing, form, hero, dashboard, onboarding, navigation]
+    note: "UI Prompt Library: 286 layout prompts by section (auth, pricing, hero, bento, stats, FAQ, dashboard...) that return Tailwind markup. Use the prompt as the brief for one section; adapt it to the project tokens."

package/src/skills-lib/wizz-premium-landing-ui-researcher/references/mandatory-process.md

@@ -8,7 +8,7 @@ Always follow this process. **Steps 6, 7, and 8 are SOURCE CHECKPOINTS and must
 4. Define the visual direction.
 5. Decide whether it needs a landing page, dashboard, 3D/WebGL, or a combination.
 6. **CHECKPOINT: Inventory of the user's sources.** List and inspect (ls + minimal reading of READMEs/package.json) the current project and the models at the paths provided by the user; reuse the memory summary from the handoff. Identify which components/effects the user already has that can be reused before any external source.
-7. **CHECKPOINT: Source-First Protocol (mandatory).** Run [source-first-protocol](source-first-protocol.md): search public sources, open demos and code/registry, check revision, license, and dependencies. Log evidence and failures in the research artifact; show 1-3 real candidates per component.
+7. **CHECKPOINT: Source-First Protocol (mandatory).** Run [source-first-protocol](source-first-protocol.md): search public sources, open demos and code/registry, check revision, license, and dependencies. Log evidence and failures in the research artifact; judge each verified candidate with [mining-rubric](mining-rubric.md) and show the selected one per need, with at most two runners-up and their verdicts.
 8. **CHECKPOINT: Choose sources.** Recommend the appropriate combination. With direction and implementation already authorized, proceed; only ask if a material decision is missing.
 9. Recommend components and animations (already curated in the previous checkpoints).
 10. Write copy and structure.

package/src/skills-lib/wizz-premium-landing-ui-researcher/references/mining-rubric.md

@@ -0,0 +1,123 @@
+# Mining rubric: entry conditions, score, verdict, stop and adaptation
+
+Shared by `wizz-premium-landing-ui-researcher` and `wizz-ui-component-curator`. Read it before judging the first candidate of a need. It turns "this looks good" into a verdict that the next session, the implementer and QA can read back from `design-state.yaml`.
+
+The discipline is ported from the offer miner (`wizz-lowticket-minerador`): conditions checked before any score, a 0-10 score with a cut at 6, an enumerated verdict, a stop rule per need, observation kept apart from inference, and a fixed read order that rebuilds instead of copying.
+
+Order of work for each candidate, always the same:
+
+1. **Evidence gate** ([web-access-and-evidence](web-access-and-evidence.md)). Missing any of the five fields = `evidence: unverified`. Unverified is not scored and never selected; it can be verified later.
+2. **Dedup.** Its `pattern_key` is already `selected` in the project → `status: rejected`, `dup_of: <that discovery>`. Not scored.
+3. **Entry conditions.** One unmet = `verdict: DESCARTAR` with the code in `disqualifiers`. Not scored.
+4. **Score** the five criteria, sum, read the verdict from the band.
+5. **Select or keep searching**, by the selection and stop rules below.
+6. **Adapt** the selected one with the five-step protocol.
+
+## Entry conditions
+
+Each one is a condition of use, not a ban: the line says what makes the candidate eligible. A candidate that does not meet a condition is recorded with the code and the reason, so the next round does not open it again.
+
+| Code | The candidate is eligible when | Unmet means |
+|---|---|---|
+| `licenca` | a code source (`kind: code` or `registry`) has a license that allows use in this project | no license or an incompatible one. Reclassify it as `kind: visual` and it is scored as a pattern to rebuild, never as code to copy |
+| `acesso_pago` | paid access is already authorized by the user | access or cost not confirmed (the user decides, it is a faixa C item) |
+| `dependencia` | its dependencies fit the stack and the bundle budget of `design-state.stack` | it pulls a dependency outside the stack or above the budget, and the user has not approved going over |
+| `reduced_motion` | it honours `prefers-reduced-motion`, or the adaptation plan writes that path | it ignores reduced motion and nobody wrote the alternative |
+| `contraste` | its contrast passes AA once the project's tokens are applied | the effect itself breaks AA (text over moving image with no scrim, glow under body text) |
+| `nivel` | the motion is allowed at the site level ([site-levels](site-levels.md)) | the level lists that motion as one to avoid |
+| `proibido` | it does not land on a capability in the `proibidos` block | it does. A reference the user chose already moved its item out of `proibidos` (derivation rule 4.4 of `wizz-design-needs`), so it is eligible |
+
+## Score
+
+Five criteria, summed to 0-10. Score only what was observed in this session; a criterion that rests on an inference is scored from what was seen and the inference is written in `inferred`.
+
+| Criterion | Range | Top of the range | Bottom of the range |
+|---|---|---|---|
+| `aderencia` | 0-3 | answers the need's `question` and fits the style DNA and brief signals as is | adjacent to the need, does not answer it |
+| `execucao` | 0-2 | polished in the live demo: timing, states, resize, mobile | broken or janky. Inspected static only: at most 1 |
+| `custo_adaptacao` | 0-2, inverted | token-level adaptation (colour, type, spacing) | most of it has to be rewritten |
+| `custo_performance` | 0-2, inverted | no new dependency, no layout thrash | heavy runtime (WebGL, video, large library) for what it adds |
+| `originalidade` | 0-1 | not the default look of the stack or the catalogue | reads as template |
+
+Middle values: `aderencia` 2 = answers the question with visible restyling, 1 = answers part of it; `execucao` 1 = works with rough edges; `custo_adaptacao` 1 = markup or API changes; `custo_performance` 1 = a new dependency inside the budget, or a measurable runtime cost.
+
+## Verdict
+
+| Verdict | Score | Use |
+|---|---|---|
+| `ASSINATURA` | 9-10 | the piece that defines the surface. At most one selected per surface |
+| `FORTE` | 7-8 | enters |
+| `UTILITARIO` | 6 | enters only when the need has nothing better |
+| `DESCARTAR` | 0-5, or an unmet entry condition | does not enter; the reason stays recorded |
+
+The cut is 6. A need's `floor` can raise it for that need, never lower it: a 7 on a need with `floor: 8` stays `FORTE` and is not selected for that need.
+
+The signature cap is what stops a page from becoming a collage of impressive effects. When a second candidate on the same surface scores 9 or 10, it is recorded as `FORTE` with `reason: "teto de assinatura"`.
+
+## Selection
+
+Per need, one discovery is selected: the highest-scoring verified, eligible candidate at or above the need's floor.
+
+- **Faixa A, silent:** the first leads the second by 2 points or more and the need is not `signature: true`. Select and move on.
+- **Faixa B, announced:** a tie within 1 point, or the signature piece of a surface. Select, then say which one won, the runner-up and why. The swap costs one edit to the state file.
+- `UTILITARIO` is selected only when no `FORTE` or `ASSINATURA` is eligible for that need.
+- Everything else on the need stays `proposed` or goes to `rejected` with a `reason`.
+
+## Stop conditions
+
+The miner stops on the first one that applies. Each stop writes the need's status and reason to the state file.
+
+| Scope | Stops when | Need status |
+|---|---|---|
+| Need, early | an eligible candidate scores 9 or more | `selected` |
+| Need, budget | the sources opened reach `budget.fontes` | `selected` if anything eligible, else `unmet` |
+| Need, diminishing returns | 2 sources in a row with nothing eligible at or above the floor | `unmet`, with what was tried. A result, not a failure |
+| Dedup | the need's question is already answered by a selected discovery on another surface | `dropped`, `reason: "resolvido por <need-id>"` |
+| Surface | the selected behaviour discoveries reach the level's behaviour ceiling (derivation rule 3 of `wizz-design-needs`) | the rest `deferred` |
+| Global | every need is `selected`, `unmet`, `dropped` or `deferred` | mining is over. This is "I have enough information" |
+
+Count the spend on the need itself (`spent.fontes`, `spent.secas`) so a reopened need starts from what was already paid.
+
+## Observation and inference
+
+Every discovery keeps two lists. `observed`: what was actually seen in this session (a duration in the code, an import, the demo jank at 375 px). `inferred`: the reading of it ("probably uses GSAP ScrollTrigger"). A score rests on `observed`. An inference written as an observation is the failure mode this split exists to catch.
+
+## Adaptation protocol
+
+Fixed read order, the design twin of the offer miner's "Demanda → Hook → Promessa…":
+
+**Pattern → Why it works → Invariant → Variable → Reimplementation**
+
+- **Pattern** (`padrao`): what happens mechanically, in one sentence, with no brand name.
+- **Why it works** (`por_que`): the perceptual or conversion reason. If it cannot be written, the discovery was not understood: it goes back to evaluation and is not selected.
+- **Invariant** (`invariante`): what cannot change without breaking the effect.
+- **Variable** (`variavel`): what is free (easing, duration, direction, colour, density).
+- **Reimplementation** (`reimplementacao`): the plan in the project's tokens and vocabulary.
+
+Closing rule, in the same spirit as the offer miner's: **a visual reference gives structure and principle, never CSS.** A code source with a license can be copied with attribution; a visual source is rebuilt.
+
+## Machine-readable block
+
+The eval (`evals/design-mining/`) and the state checker (`wizz-design-needs/scripts/design_state.py`) read the numbers from this block. Change a band here and both follow; nothing else holds a copy.
+
+```yaml
+# mining-rubric:v1
+cut: 6
+criteria:
+  aderencia: [0, 3]
+  execucao: [0, 2]
+  custo_adaptacao: [0, 2]
+  custo_performance: [0, 2]
+  originalidade: [0, 1]
+verdicts:
+  - { id: ASSINATURA, min: 9, max: 10 }
+  - { id: FORTE, min: 7, max: 8 }
+  - { id: UTILITARIO, min: 6, max: 6 }
+  - { id: DESCARTAR, min: 0, max: 5 }
+disqualifiers: [licenca, acesso_pago, dependencia, reduced_motion, contraste, nivel, proibido]
+signature_per_surface: 1
+signature_cap_reason: "teto de assinatura"
+faixa_a_lead: 2
+early_stop_score: 9
+dry_sources_to_unmet: 2
+```

package/src/skills-lib/wizz-premium-landing-ui-researcher/references/source-first-protocol.md

@@ -12,7 +12,7 @@ Log the real paths of the resources found. If there are no local models, proceed
 
 ## Phase 2: Search and inspect public sources
 
-Choose sources based on the effect needed, using [component-sources](component-sources.md) and [source-links](source-links.md):
+Choose sources by querying the catalogue as data instead of reading the whole prose: `uv run --no-cache scripts/design_sources.py list --need <tag>` (run from this skill's folder; tags such as `hover`, `scroll`, `card`, `dashboard`, `chart`, `shader`, `typography`) returns the matching sources from [design-sources.yaml](design-sources.yaml) with kind, access, license and `study_only`. Without `uv`, read the YAML directly. [component-sources](component-sources.md) keeps the policy and nuance (clone, paid, visual inspiration) and [source-links](source-links.md) the links; open them when a source needs that detail. The quick map, for orientation:
 
 | Need | Initial sources |
 |---|---|
@@ -50,7 +50,7 @@ Most sources are shadcn registries. Read them live instead of cloning:
 2. **Read the item.** Replace `{name}` in the URL template and fetch the JSON: it carries the files, dependencies and registry dependencies, which is the evidence the gate asks for. When the shadcn MCP is configured (`npx shadcn@latest mcp init`), it does the same lookup for you.
 3. **Repos outside the index** (and offline work) use the local cache.
 
-An existing design cache (for example `~/.claude/design-sources/`) can be inspected. Don't treat it as up to date just because it exists:
+An existing design cache (for example `~/.claude/design-sources/`) can be inspected. Don't treat it as up to date just because it exists. One command answers it: `uv run --no-cache scripts/design_sources.py freshness` gives each cached clone's revision, last sync and `stale` past 30 days (`--remote` also compares with origin). A stale cache is still a source for a pattern, never for an API. `design_sources.py refresh` fast-forwards only the clones with no local changes and reports the rest; run it when the user agrees to update. The rules below still hold:
 
 - Check origin, branch, revision, and local changes before updating.
 - Check the remote revision when there's network access; the folder's modification date is not proof of being up to date.
@@ -70,10 +70,16 @@ Log in the existing design artifact (or create `design-research.md` in the proje
 
 Also include searches with no results and unavailable sources. Never fill in component names, paths, license, or test results by assumption. A row missing any of the five fields in [web-access-and-evidence](web-access-and-evidence.md) is UNVERIFIED and cannot be the recommendation.
 
-Show 1-3 compatible candidates per component, with a recommendation and adaptation cost. If the user has already authorized the implementation and defined the direction, choose the best option within that scope and proceed. Only ask when a material decision about direction, paid access, or scope change is missing.
+Judge every verified candidate with [mining-rubric](mining-rubric.md): dedup, entry conditions, the 0-10 score with the cut at 6, the verdict, and the selection rule. With a `design-state.yaml`, each candidate is written as a discovery with its need id, scores, verdict and status; the table above is the human-readable view of the same rows.
+
+Show the selected candidate per need and at most two runners-up, each with its verdict and score. If the user has already authorized the implementation and defined the direction, the selection rule decides and you proceed. Only ask when a material decision about direction, paid access, or scope change is missing.
 
 ## Phase 5: Adapt and verify
 
-Adapt tokens, typography, spacing, content, and motion to the project. Verify responsiveness, keyboard navigation, focus, contrast, reduced-motion, and rendering cost as appropriate for the component. Link the result back to the logged sources.
+Write the adaptation in the five-step order of [mining-rubric](mining-rubric.md) (pattern, why it works, invariant, variable, reimplementation) before touching code. Then adapt tokens, typography, spacing, content, and motion to the project. Verify responsiveness, keyboard navigation, focus, contrast, reduced-motion, and rendering cost as appropriate for the component. Link the result back to the logged sources.
 
 Building from scratch is acceptable for trivial primitives or when the documented research finds no compatible option and the implementation is authorized. Explain the reason. Don't claim something doesn't exist in any catalog; only report the sources actually researched.
+
+## Phase 6: Stop
+
+Mining stops by rule, not by patience. Per need: an eligible candidate at 9 or more, the source budget spent, or 2 sources in a row with nothing eligible (`unmet`, with what was tried). Per surface: the level's behaviour ceiling. Globally: every need in a terminal status. The table and the status each stop writes are in [mining-rubric](mining-rubric.md). Report which stop closed each need.

package/src/skills-lib/wizz-premium-landing-ui-researcher/references/web-access-and-evidence.md

@@ -36,6 +36,6 @@ Every candidate needs all five, collected in this session:
 | Dependencies | Read from the actual imports or registry JSON | Guessed from the component's name |
 | Source read | The code file was opened and its imports checked | The demo alone |
 
-A candidate missing any field is **UNVERIFIED**. UNVERIFIED items go in a separate section of the report, with what is missing and why. They are never recommended and never placed in the top 1-3, and the implementation plan never depends on them. If every candidate for a need is UNVERIFIED, the need is reported as `unmet`, not filled.
+A candidate missing any field is **UNVERIFIED**. UNVERIFIED items go in a separate section of the report, with what is missing and why. They are never recommended and never scored or selected by the [mining-rubric](mining-rubric.md), and the implementation plan never depends on them. If every candidate for a need is UNVERIFIED, the need is reported as `unmet`, not filled.
 
 Before closing, check the delivery against this gate once: every recommended item has its five fields in the research log (`design-research.md` or the project's design artifact), and the access line from Step 0 is in the report.