wizz-method 2.21.0 → 2.22.0

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

@@ -0,0 +1,252 @@
+# 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."

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.

package/src/skills-lib/wizz-premium-landing-ui-researcher/scripts/design_sources.py

@@ -0,0 +1,221 @@
+# /// script
+# requires-python = ">=3.10"
+# dependencies = ["ruamel.yaml>=0.18"]
+# ///
+"""Query the design-source catalogue and keep the local cache honest.
+
+Prints ONLY JSON to stdout. Reads ../references/design-sources.yaml.
+
+Subcommands:
+  list        Sources that answer a need tag (--need, repeatable), optionally
+              filtered by --kind. Paid sources are listed with their access so
+              the miner can apply the paid-source condition; study_only sources
+              say so.
+  freshness   For every source with a `cache` folder: revision, last commit,
+              last sync with the remote (FETCH_HEAD, else the clone date), age
+              of that sync in days, local changes, and `stale` when the age
+              passes max_cache_age_days. --remote also compares HEAD with
+              origin (network). Exit 0 always; the JSON carries the verdict.
+  refresh     Fast-forward the cached clones that have no local changes
+              (`git fetch` + `git merge --ff-only`). A clone with local changes
+              is skipped and reported, never reset. --id limits it to one source.
+
+Run with `uv run --no-cache scripts/design_sources.py <subcommand>`: uv
+provisions ruamel.yaml from the header above.
+"""
+
+import argparse
+import datetime as dt
+import json
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+HERE = Path(__file__).resolve().parent
+CATALOGUE = HERE.parent / "references" / "design-sources.yaml"
+
+
+def emit(payload, code=0):
+    print(json.dumps(payload, ensure_ascii=False, indent=2, default=str))
+    sys.exit(code)
+
+
+def load_catalogue(path):
+    from ruamel.yaml import YAML
+
+    yaml = YAML(typ="safe")
+    with open(path, encoding="utf-8") as handle:
+        data = yaml.load(handle)
+    if not isinstance(data, dict) or not isinstance(data.get("sources"), list):
+        raise ValueError(f"{path}: expected a mapping with a `sources` list")
+    return data
+
+
+def cmd_list(data, needs, kind):
+    wanted = {tag.lower() for tag in needs}
+    rows = []
+    for source in data["sources"]:
+        tags = {str(tag).lower() for tag in source.get("need_tags") or []}
+        if wanted and not wanted & tags:
+            continue
+        if kind and source.get("kind") != kind:
+            continue
+        rows.append(
+            {
+                "id": source["id"],
+                "kind": source.get("kind"),
+                "access": source.get("access"),
+                "license": source.get("license"),
+                "study_only": bool(source.get("study_only")),
+                "matches": sorted(wanted & tags) if wanted else [],
+                "url": source.get("url"),
+                "registry": source.get("registry"),
+                "note": source.get("note"),
+            }
+        )
+    rows.sort(key=lambda row: (-len(row["matches"]), row["access"] != "free", row["id"]))
+    return {"need": sorted(wanted), "count": len(rows), "sources": rows}
+
+
+def git(repo, *args):
+    result = subprocess.run(
+        ["git", "-C", str(repo), *args], capture_output=True, text=True, timeout=120
+    )
+    if result.returncode != 0:
+        raise RuntimeError(result.stderr.strip() or f"git {' '.join(args)} failed")
+    return result.stdout.strip()
+
+
+def cache_root(data, override):
+    root = override or data.get("cache_root") or "~/.claude/design-sources"
+    return Path(os.path.expanduser(root))
+
+
+def last_sync(repo):
+    """When the clone last talked to its remote.
+
+    FETCH_HEAD is rewritten by every fetch. A clone that was never fetched has
+    no FETCH_HEAD, so the last HEAD reflog entry (the clone itself, or the last
+    pull) is used. The .git folder's mtime is not: `git status` touches it.
+    """
+    git_dir = repo / ".git"
+    marker = git_dir / "FETCH_HEAD"
+    if marker.exists():
+        return dt.date.fromtimestamp(marker.stat().st_mtime)
+    reflog = git_dir / "logs" / "HEAD"
+    if reflog.exists():
+        lines = [line for line in reflog.read_text(encoding="utf-8").splitlines() if line.strip()]
+        if lines:
+            identity = lines[-1].split("\t", 1)[0].split()
+            return dt.date.fromtimestamp(int(identity[-2]))
+    return None
+
+
+def remote_status(repo, revision):
+    try:
+        line = git(repo, "ls-remote", "origin", "HEAD")
+    except RuntimeError as error:
+        return {"remote": f"unreachable: {error}"}
+    remote = line.split()[0] if line else ""
+    return {"remote": "current" if remote.startswith(revision) else "behind", "remote_revision": remote[:8]}
+
+
+def inspect_cache(repo, max_age, today, check_remote):
+    if not (repo / ".git").exists():
+        return {"present": repo.is_dir(), "error": None if not repo.is_dir() else "not a git clone"}
+    try:
+        revision = git(repo, "rev-parse", "--short", "HEAD")
+        committed = git(repo, "log", "-1", "--format=%cs")
+        dirty = bool(git(repo, "status", "--porcelain"))
+    except RuntimeError as error:
+        return {"present": True, "error": str(error)}
+    synced = last_sync(repo)
+    if synced is None:
+        return {"present": True, "revision": revision, "last_commit": committed, "error": "no fetch or reflog record"}
+    age = (today - synced).days
+    row = {
+        "present": True,
+        "revision": revision,
+        "last_commit": committed,
+        "last_sync": synced.isoformat(),
+        "age_days": age,
+        "local_changes": dirty,
+        "stale": age > max_age,
+    }
+    if check_remote:
+        row.update(remote_status(repo, revision))
+    return row
+
+
+def cmd_freshness(data, root, today, check_remote=False):
+    max_age = int(data.get("max_cache_age_days") or 30)
+    rows = []
+    for source in data["sources"]:
+        if not source.get("cache"):
+            continue
+        row = {"id": source["id"], "path": str(root / source["cache"])}
+        row.update(inspect_cache(root / source["cache"], max_age, today, check_remote))
+        rows.append(row)
+    stale = [row["id"] for row in rows if row.get("stale")]
+    return {"max_age_days": max_age, "today": today.isoformat(), "stale": stale, "caches": rows}
+
+
+def cmd_refresh(data, root, only_id):
+    rows = []
+    for source in data["sources"]:
+        if not source.get("cache") or (only_id and source["id"] != only_id):
+            continue
+        repo = root / source["cache"]
+        row = {"id": source["id"], "path": str(repo)}
+        if not repo.is_dir():
+            row["result"] = "absent"
+        else:
+            try:
+                if git(repo, "status", "--porcelain"):
+                    row["result"] = "skipped: local changes"
+                else:
+                    before = git(repo, "rev-parse", "--short", "HEAD")
+                    git(repo, "fetch", "--quiet")
+                    git(repo, "merge", "--ff-only", "--quiet", "@{u}")
+                    after = git(repo, "rev-parse", "--short", "HEAD")
+                    row["result"] = "updated" if after != before else "already current"
+                    row["revision"] = after
+            except RuntimeError as error:
+                row["result"] = f"error: {error}"
+        rows.append(row)
+    return {"caches": rows}
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(prog="design_sources.py")
+    parser.add_argument("--catalogue", default=str(CATALOGUE))
+    parser.add_argument("--cache-root", default=None)
+    sub = parser.add_subparsers(dest="command", required=True)
+    listing = sub.add_parser("list")
+    listing.add_argument("--need", action="append", default=[])
+    listing.add_argument("--kind", default=None)
+    fresh = sub.add_parser("freshness")
+    fresh.add_argument("--today", default=None, help="YYYY-MM-DD, for tests")
+    fresh.add_argument("--remote", action="store_true", help="compare HEAD with origin (network)")
+    refresh = sub.add_parser("refresh")
+    refresh.add_argument("--id", default=None)
+    try:
+        args = parser.parse_args(argv)
+    except SystemExit as error:
+        emit({"error": "invalid arguments"}, int(error.code or 2))
+    try:
+        data = load_catalogue(args.catalogue)
+    except (OSError, ValueError, ImportError) as error:
+        emit({"error": str(error)}, 1)
+    root = cache_root(data, args.cache_root)
+    if args.command == "list":
+        emit(cmd_list(data, args.need, args.kind))
+    if args.command == "freshness":
+        today = dt.date.fromisoformat(args.today) if args.today else dt.date.today()
+        emit(cmd_freshness(data, root, today, args.remote))
+    emit(cmd_refresh(data, root, args.id))
+
+
+if __name__ == "__main__":
+    main()