@ranimontagna/agent-toolkit 0.1.18 → 0.1.20

package/skills/frontend/design/revenue-centric-design/references/positioning-icp-and-gtm.md

@@ -0,0 +1,64 @@
+# Positioning, ICP & Go-to-Market
+
+> Curated, distilled wisdom from @richardrx ("Richard — Design for startups"), translated from Portuguese. Each entry is a reusable principle linked to its source post.
+
+## Size the market with TAM → SAM → SOM (and know which one matters)
+**Principle.** Your real market is far smaller than the population — TAM is a theoretical ceiling (Brazil's 213M becomes ~101M credit-card holders for a paid app). Investors often ignore a TAM under ~R$1B, but the number that matters is the **SOM** — what you can actually capture.
+**Apply when.** Sizing a market, writing a deck, or judging whether a niche is big enough.
+**The move.** TAM = total addressable ceiling; **SAM** = the realistic slice your model reaches (~40% in his example); **SOM** = the 1–5% you truly win in ~36 months — and SOM isn't a guessed %, it comes from real CAC, activation, support capacity and LTV. You can't change your TAM; you change how much of your SAM you convert and retain.
+**Evidence.** RepareCar: ~76k mechanic shops (honest TAM) → SAM ~47k → ~3% ≈ 1,414 shops ≈ R$1.6M ARR; current pace (~10 shops/day) ≈ 7% of SAM in 12 months.
+**Visual.** TAM/SAM/SOM concentric-circle diagram with definitions — `../assets/2070140923380420796__1.jpg`
+**Source.** [@richardrx · 2026-06-25](https://x.com/richardrx/status/2070140923380420796)
+
+## Frame the referral prize as a gift to the friend, not a commission to the referrer
+**Principle.** Member-get-member (MGM) referral programs win on framing and timing, not just on a two-sided reward. Money makes the exchange feel transactional; an in-product benefit feels like a genuine gift.
+**Apply when.** Designing or fixing a referral program and defaulting to "refer a friend, get $20."
+**The move.** Apply the framing effect: surface the prize on the receiver's side ("João gave you 500MB"). Ask for the referral at the peak of value (right after a concrete win, or when the user hits a limit). Avoid cash; give a reward that deepens use of your own product. Embed it as continuous in-product operation, not a one-off campaign. Caveat: referral amplifies a product people already love; it can't fix one nobody recommends for free.
+**Evidence.** Dropbox grew 3900% in 15 months (100k → 4M users), peaking near 3M invites in a single month; ~1/3 of users already arrived via word-of-mouth before the program.
+**Voice.** "A referral amplifies a product people already love — it doesn't fix a product nobody recommends for free."
+**Source.** [@richardrx · 2026-06-02](https://x.com/richardrx/status/2061766945582559509)
+
+## Pick a deliberately under-served niche as your ICP
+**Principle.** A clear ICP (ideal customer profile) is not "everyone who could use my product." It's a deliberately chosen, under-served niche — and a sharp niche beats no niche, because you can't out-fight the entrenched generalist giant.
+**Apply when.** Early traction; tempted to "embrace the world" out of fear of a small TAM.
+**The move.** Validate four ICP filters: (1) feels the pain with real weight — pain is proportional to what's lost when unsolved (a lost lead costs a face-aesthetics clinic R$3,000 vs. R$60 for a barber); (2) big enough TAM to sustain operations; (3) money to pay your required ticket so unit economics close; (4) founder-fit, giving native language, a fast validation network, and instinct that money can't buy. With a clear ICP, failure has a diagnosis ("I got the messaging wrong"); without one, you can't tell if product, copy, channel, price, or audience failed — and every test burns runway.
+**Voice.** "A generalist ERP is hard to sell; an ERP for cabinetmaking is a different conversation."
+**Source.** [@richardrx · 2026-05-19](https://x.com/richardrx/status/2056789797646029232)
+
+## Don't claim PLG without the four structural conditions
+**Principle.** Product-led growth (PLG) is a consequence of structural conditions, not a product decision you declare. Most B2B SaaS that pitches PLG is really sales-led wearing a PLG label.
+**Apply when.** Writing a pitch deck or strategy and calling the motion "self-service" / PLG.
+**The move.** Require all four conditions: (1) TTV < 10 minutes — if it needs a consultant demo, API support, or paid implementation, it's not PLG (tell: full trial, zero activation); (2) ticket below ~R$1,000 — higher means a buying committee; (3) native virality or collaboration (Notion, Figma, Slack pull users in; a CRM/AI tool needs SDRs, demos, follow-up); (4) a huge addressable market with a real bottom-up TAM. If you fail these, run sales-led honestly.
+**Evidence.** Brazil has ~20,000 companies with 100+ employees, and only ~a dozen B2B SaaS where PLG makes real economic sense.
+**Voice.** "Founders love PLG because it seems to delete the part they don't master — selling."
+**Source.** [@richardrx · 2026-05-04](https://x.com/richardrx/status/2051262752547536941)
+
+## Charge your first ten users from day one
+**Principle.** The first ten users define the product's entire curve, and payment is the cheapest test of real pain — curiosity is free, an open wallet demands a concrete problem.
+**Apply when.** Validating a new product and tempted to give early access away to "build a base."
+**The move.** Source the first ten from closed communities, personal reach, or pure guerrilla. Charge even while in prototype. When someone says they can't pay, ask directly: "What does the system need to do for you to pay right now?" Treat the payment friction as part of the test. Collect dense feedback; only start visual design after ~20 paying users. For B2C apps the method shifts (e.g., pre-sale of a solution-in-progress) but the principle holds.
+**Evidence.** RepareCar's first 25 auto shops tested the product in prototype; the team visited each and charged at the end, designing visuals only after 20 paying shops.
+**Voice.** "Curiosity is free; an open wallet demands a concrete problem."
+**Source.** [@richardrx · 2026-04-26](https://x.com/richardrx/status/2048359526487716333)
+
+## Reverse-engineer the funnel math before celebrating an MRR target
+**Principle.** Building the product is the easy part; distribution is the game. A revenue target is really a traffic-and-retention problem, and churn quietly resets the whole funnel every month.
+**Apply when.** Someone asks "is it hard to hit X MRR?" or you're sizing acquisition for a target customer count.
+**The move.** Work backwards: to net 2,500 customers at 5% LP conversion you need 50,000 visitors; from ads at 3% creative CTR, ~1.6M impressions (5% and 3% are top-decile — most land at 1–2% LP and under 1% CTR, so you test dozens). Then add the leaky bucket: at 20% monthly churn, average customer life is 5 months, so you replace 500 customers every month forever just to stand still (≈10,000 visitors / 333,000 impressions). The problem lives at the intersection of dev, design, and marketing — none alone owns it.
+**Evidence.** 20% monthly churn → 5-month average lifetime; at low ticket many operate at 40–50% churn, so "the bucket never fills."
+**Voice.** "Building the product is the easy part; distribution is the game."
+**Source.** [@richardrx · 2026-04-20](https://x.com/richardrx/status/2046222319912132977)
+
+## Concentrate channels with the Bullseye framework, not scattershot testing
+**Principle.** Testing ten channels at once means you never know what drove results and you blame the channel when the business stalls. Distribution needs prioritized focus — and a perfect channel still fails if the receiving structure leaks.
+**Apply when.** You're spreading content and traffic across many channels with no clear read on what works.
+**The move.** Use the Bullseye framework (from the book *Traction*): three rings of priority. Inner ring = at most three highest-potential channels with total focus; middle ring = up to six channels you probe with small experiments; outer ring = everything plausible long-term, no active focus now. Choose between channels with an ICE Score (Impact, Confidence, Ease, each 0–10, divide by 3, prioritize). Crucial gap the book skips: scaling distribution onto a broken reception structure (LP, onboarding, first product steps) yields no growth — distribution and retention are simultaneous, not sequential.
+**Visual.** Bullseye as nested circles — What's Possible → What's Probable → What's Working — beside a "Marketing Framework for Startups" triangle (Prioritization, Testing, Quick Iteration). — `../assets/2036035304868434115__1.jpg`
+**Source.** [@richardrx · 2026-03-23](https://x.com/richardrx/status/2036035304868434115)
+
+## Diagnose the bottleneck: no entries is distribution, leaving without paying is design
+**Principle.** Design can't save a "ghost product." Design optimizes and raises the LTV of something that already has traffic; it can't manufacture demand.
+**Apply when.** A builder ships an app, gets near-zero users, and hopes a redesign will rescue it.
+**The move.** Split the diagnosis cleanly: if nobody enters your product, it's a distribution problem; if they enter, don't pay, and leave, it's design. Read *Traction* even if you can afford an agency or a marketing team — the lever isn't just cost-per-channel but each channel's awareness level, which drives different conversion and retention behavior depending on where and how the user arrived.
+**Voice.** "If nobody enters your product, it's distribution. If they enter, don't pay, and leave, that's design."
+**Source.** [@richardrx · 2026-02-28](https://x.com/richardrx/status/2027721170569564521)

package/skills/frontend/design/revenue-centric-design/references/pricing-and-monetization.md

@@ -0,0 +1,87 @@
+# Pricing & Monetization Psychology
+
+> Curated, distilled wisdom from @richardrx ("Richard — Design for startups"), translated from Portuguese. Each entry is a reusable principle linked to its source post.
+
+## The freemium trap, in numbers: higher conversion, far lower cash
+**Principle.** A free plan lifts signup conversion but can crush the economics — the higher top-of-funnel number hides a worse business.
+**Apply when.** You're tempted by freemium's better conversion rate.
+**The move.** Run the funnel (same R$80k/mo traffic, plans from R$199). **With freemium:** ~8% → 800 signups → 80% activate → 5% pay = 32 payers (R$6,368 MRR), saturating ~160 payers under 20% churn, while 768 free users burn AI tokens (~$0.08 each) — real CAC ≈ R$2,540/payer, payback ~13 months. **Without:** ~3% → 300 payers = R$59,700 MRR (~10×), CAC ~R$275, payback ~6 weeks, LTV:CAC 5:1 that reinvests its own profit. Freemium only pays off if free brings *organic/viral* users you didn't pay for.
+**Voice.** "One scenario reinvests its own profit; the other funds losses until the money runs out."
+**Source.** [@richardrx · 2026-07-01](https://x.com/richardrx/status/2072312844784152628)
+
+## Whether freemium works is decided by the cost to serve a free user
+**Principle.** Freemium isn't good or bad in the abstract — the *cost of free* decides, and it hinges on (1) how much it costs to serve non-payers and (2) how long/expensive activation is.
+**Apply when.** Considering a free plan, especially as a bootstrapped (non-bigtech) founder.
+**The move.** If serving a free user costs almost nothing and TTV is short, free becomes an acquisition channel (Slack — first message in minutes; it's the short TTV, not the cash, that sustains it). If the product runs on AI (dollar-priced tokens) or activation is long, a free account is an expensive bet that a small fraction funds — which needs deep pockets (the exception, not the average founder). On a friendly average, only ~3–4% of freemium converts. Otherwise: charge — well, and early.
+**Voice.** "For an AI product, your free user was never free."
+**Source.** [@richardrx · 2026-06-30](https://x.com/richardrx/status/2071962778072469560)
+
+## Price is the cheapest money — stop anchoring it to the cheapest competitor
+**Principle.** Pricing is a SaaS's biggest lever, yet ~90% of products are underpriced — the founder, who knows every limitation, anchors on the cheapest competitor instead of on value delivered. The buyer only sees the problem solved.
+**Apply when.** Setting or revisiting price; fearing a "no."
+**The move.** Raise toward value. A 30% price increase doesn't yield 30% MRR (some churn), but what remains is nearly pure cash — no acquisition in between — while growing a channel 30% costs money, time, and has a ceiling. Low price costs you later: less budget to reach your ICP, a CAC-obsession trap (the real metric is the CAC↔LTV *gap*, which price widens on both sides), and higher churn (cheap attracts uncommitted buyers). Design link: the number must be sustained by perceived value — your page and first use justify or destroy it.
+**Voice.** "Charging more without seeming to be worth more is just raising the price of rejection."
+**Source.** [@richardrx · 2026-06-29](https://x.com/richardrx/status/2071634185228329219)
+
+## Make the middle plan the one you actually want to sell
+**Principle.** Each plan has a behavioral job, not just a price; the plan you most want to sell should sit in the middle, flanked by a decoy below and an anchor above.
+**Apply when.** Building or auditing a SaaS pricing page, especially if you copied competitors without assigning each tier a role.
+**The move.** Use the decoy effect: place your target (e.g. Pro) in the middle; make the tier below it clearly inferior on one important attribute (user cap, no critical integration, no priority support) so Pro looks obvious. Keep exactly three plans — four+ triggers the paradox of choice and users stall. Add a top tier (Enterprise) purely to anchor price perception. Ask: "What is my decoy today?" If you can't name one, it likely doesn't exist.
+**Evidence.** Ariely's MIT test of The Economist's tiers: with the print-only decoy, 16%/84% chose online/combo; removing it flipped choices to 68%/32%, cutting combo revenue by more than half. Estimated +30–43% subscription revenue.
+**Visual.** Economist subscription page; the decoy's removal shifts combo-plan share from 84% down to 32% — `../assets/2059951433827426437__1.jpg`
+**Voice.** "Option B was never built to be sold — it was built to make C look obvious. It's the bait."
+**Source.** [@richardrx · 2026-05-28](https://x.com/richardrx/status/2059951433827426437)
+
+## Ask for the card in trial — but optimize for the right ICP, not raw conversion
+**Principle.** Requiring a credit card multiplies trial-to-paid conversion but shrinks signups; the goal is the model that attracts and retains the right ICP, not the one with the highest headline conversion.
+**Apply when.** Choosing trial-with-card vs trial-without-card (or freemium), or designing recurring billing for a Brazilian market.
+**The move.** Weigh the funnel both ways. Trial-with-card converts harder but starves you of volume; trial-without-card floods the funnel with low-intent users. Run the full math, not just the conversion rate. In Brazil, also account for PIX recorrente, whose dynamics differ from monthly card billing.
+**Evidence.** ChartMogul 2026 (US, 200 products): trial-with-card converts ~31.4% vs 8.9% without — 3x+. Worked funnel: 1,000 visitors → 30 trials → 9.4 paying (with card) vs 85 trials → 7.5 paying (without). Author observes PIX-recorrente cohorts churn more than card cohorts.
+**Voice.** "Don't ask which model converts more — ask which model attracts and retains the right ICP."
+**Source.** [@richardrx · 2026-05-15](https://x.com/richardrx/status/2055247161349054950)
+
+## Frame the upgrade as a loss at the moment of value, not a feature you're selling
+**Principle.** Low upgrade rates are usually a framing-and-timing problem, not a price problem; remind users what they've already invested and what they stand to lose.
+**Apply when.** A happy, active free user never upgrades, or your upgrade rate sits below 5%.
+**The move.** Three framings beat generic limit/discount/feature-gate prompts. (1) Sunk cost: surface the assets they've built — "You created 47 custom reports. On the free plan you lose access to 40." (2) Loss aversion: framing loss outconverts framing gain — "You'll lose access to 8 months of history" beats "Get unlimited history." (3) Limited-access gate timed to an imminent, known result — "Your report is ready. To export as PDF, activate Pro." The timing/context of the gate matters more than the gate itself.
+**Voice.** "If your upgrade rate is below 5%, the problem probably isn't price — it's how and when you're asking."
+**Source.** [@richardrx · 2026-04-21](https://x.com/richardrx/status/2046544442216054981)
+
+## Engineer the comparison frame with a decoy and a high anchor — and drop Free from the top
+**Principle.** Conversion shifts when you change the frame of comparison, not the product; equal-looking options cause delay, and showing Free first anchors everyone to zero so everything else feels expensive.
+**Apply when.** You run the default Free / Pro / Enterprise (sob consulta) ladder and Pro isn't converting.
+**The move.** Insert a decoy: a Starter just below Pro with irritating limitations (e.g. R$79 vs Pro R$99) so users compare Starter↔Pro and Pro wins for R$20 more. Remove Free from the visible top so the first number isn't zero — anchoring means the first price seen sets the reference; lead with a higher/previous/Enterprise price so Pro at R$99 reads as cheap.
+**Evidence.** The Economist sold 3x more print+digital after adding a same-price print-only decoy nobody bought. Author cites documented tests lifting conversion 10–20% via reframing alone.
+**Voice.** "You're competing against your own free plan. And losing."
+**Source.** [@richardrx · 2026-04-14](https://x.com/richardrx/status/2044014136770580743)
+
+## Tie the trial's end to value consumed, not the calendar
+**Principle.** Blocking access on a fixed day count (7/14/28) is a lazy rule; the billing trigger should fire on value consumption, after the user's first real win.
+**Apply when.** You copied a competitor's 14-day trial and paid conversion is failing, or you're setting trial length from scratch.
+**The move.** Never paywall before a clear micro-win or solving the core problem — doing so kills conversion and breeds bad word of mouth. Set length using four variables: (1) Product complexity — enterprise needs time for compliance/security review, not just the user. (2) Time to Value — Spotify delivers in seconds, a CRM needs days of data. (3) Usage frequency — rarely-used products may need long trials, or none at all (a once-a-year tax tool shouldn't have a trial). (4) Card entry — no card means a shorter trial to create urgency; with card, watch silent next-month churn. Note: sunk cost only bites if the user built a real asset — a bad onboarding produces frustration, not switching cost.
+**Voice.** "Locking access purely on the calendar is a lazy rule that can cost you dearly — you're burning CAC without knowing where value lands."
+**Source.** [@richardrx · 2026-03-16](https://x.com/richardrx/status/2033502548301091057)
+
+## Order pricing rows by the serial-position effect: killer feature first, differentiator last
+**Principle.** Users don't read pricing lists linearly; attention and memory cluster on the first and last items, so feature order is itself a conversion lever.
+**Apply when.** Laying out the feature rows inside a pricing card or comparison table.
+**The move.** Exploit the serial-position effect (primacy + recency). Top: value anchor — never "24/7 support"; lead with the core/killer feature that solves the ICP's main pain and justifies ~80% of the ticket and the ROI. Middle: utilitarian features (exports, integrations, storage limits) the user won't memorize but will scan to compare against the next plan. Bottom (nearest the CTA): the differentiator, bonus, or loss-aversion hook — a lifetime guarantee or dedicated support. The middle of the list is "a cognitive black hole."
+**Visual.** Pricing card emphasizing the bold first row (core feature) and bold last row (super bonus), with greyed utilitarian middle rows — `../assets/2029623167900061970__1.jpg`
+**Voice.** "Pricing success depends not just on what you deliver, but on the order the brain is led to process the value."
+**Source.** [@richardrx · 2026-03-05](https://x.com/richardrx/status/2029623167900061970)
+
+## Build a single value axis, then tune the decoy's distance to your target plan
+**Principle.** A plan ladder must read as one clear progression of value; mixing quantitative and qualitative axes muddles it, and where you place the decoy's price decides which plan looks like the deal.
+**Apply when.** Naming and pricing tiers, or the "value staircase" between your plans isn't obvious to users.
+**The move.** Pick one progression — quantitative (rising credits/users) or qualitative (24/7 human support, special features) — rather than blending both. Borrow Starbucks-style naming (Tall/Grande/Venti) so every tier sounds good and lifts the brand. Then position the decoy: place it near the most expensive plan and the expensive plan looks cheap; place it near the cheapest and the decoy itself becomes the most attractive option.
+**Visual.** Decorative 3D price-tag illustration — no data.
+**Source.** [@richardrx · 2026-02-02](https://x.com/richardrx/status/2018357024543715480)
+
+## Engineer the pricing page with Good-Better-Best and control the comparison
+**Principle.** Lost LTV is rarely about price — it's analysis paralysis from a missing choice architecture. The brain is lazy and judges by relative comparison (priming + anchoring), so if you don't design the anchor, users compare you to "nothing" or to the cheapest competitor.
+**Apply when.** Designing or fixing a pricing page; conversions die at the final step despite strong CAC spend.
+**The move.** Use a Good-Better-Best (GBB) structure: **Good** = a stripped entry plan that anchors a low price but is limited enough to make users feel pain and look up (never make it free — then everything above looks expensive). **Better** = your standard plan, the target for ~80% of buyers; price it closer to Good than to Best so users think "paying only ~20% more I get double?" **Best** = the value anchor that exists mainly to make Better look cheap (bicycle analogy: without the carbon-fiber Best, the carbon-wheel Better looks expensive). Golden rule: keep comparisons on one axis — don't pit "10,000 tokens" against "Priority Support"; prefer linear, ideally asymmetric, growth. Cap at 2–5 plans (6 = anxiety, paradox of choice). Then control which attributes you compare — your own "Brazil vs Paraguay" table — choosing indicators that favor your value thesis. Highlight Better with color/size/badges. "Stop making the user do the math — do the math for them."
+**Evidence.** Cites Briesch et al. (1997) and Mazumdar et al. (2005) on reference-price models, and Chernev (2015) on choice overload.
+**Visual.** Two mirrored BR-vs-PY indicator tables prove framing: swapping which metrics are shown flips which country "wins" — `../assets/2018693884449009956__1.jpg`, `../assets/2018693884449009956__2.jpg`. Four-tier mockup highlights a "Most Popular" target beside a high anchor (Hick's law / few options) — `../assets/2018693884449009956__4.jpg`
+**Voice.** "Your pricing page is killing your LTV — and I can prove it."
+**Source.** [@richardrx · 2026-02-03](https://x.com/richardrx/status/2018693884449009956)

package/skills/frontend/design/revenue-centric-design/references/product-strategy-and-features.md

@@ -0,0 +1,58 @@
+# Product Strategy & Feature Discipline
+
+> Curated, distilled wisdom from @richardrx ("Richard — Design for startups"), translated from Portuguese. Each entry is a reusable principle linked to its source post.
+
+## Run every feature through a two-layer "Swiss Knife filter" before building
+**Principle.** A feature you ship stays forever and charges rent forever, so the right question isn't "is this good?" but "does it deserve the permanent cost it imposes on the product?"
+**Apply when.** A roadmap item feels appealing but nobody applied a filter before committing to build.
+**The move.** Layer 1 — does it deserve to exist? Pass all four: (1) cognitive load (more surface = more to learn + Hick's law decision time); (2) ICP specificity (a CRM for facial-aesthetics clinics charges 5x a generic one); (3) operational cost (maintain/support/document, not build); (4) reinforces the core claim. Layer 2 — build now? Two axes: easily rejectable (clear "no"?) and easily implementable (cost to the validating version, not the dream version). Build the no-brainers first; fail any of the four, kill it guilt-free. To rank survivors, score (New Users + New Revenue + Impact Level) / Effort.
+**Visual.** Prioritization scoring table: (New Users + New Revenue + Impact Level) / Effort = Score — `../assets/2059236567533650119__1.jpg`
+**Voice.** "Every feature that gets in, stays. And it charges rent forever."
+**Source.** [@richardrx · 2026-05-26](https://x.com/richardrx/status/2059236567533650119)
+
+## Feature adoption is a design problem, not a communication problem
+**Principle.** Shipping a feature doesn't make it discovered; users move through their habitual path and never see what they aren't looking for.
+**Apply when.** Three weeks post-launch only ~9% of active users opened the feature and ~4% used it twice, despite changelog, email, and "new" badges.
+**The move.** Stop treating adoption as announcement. The killers are inattentional blindness (users don't see what they aren't seeking) plus status-quo bias (re-learning cost outweighs perceived benefit even when the new way is better). Instead: directional empty states that surface the feature where it'd be used; triggered onboarding fired by the behavior that signals need (CRM user hits the sales page → introduce the objection-busting AI); and a feature adoption rate metric measuring habit/appropriate frequency, not clicks. Anything below an adoption threshold goes back into review.
+**Voice.** "Launching a feature is easy; getting it used is a whole other thing."
+**Source.** [@richardrx · 2026-05-20](https://x.com/richardrx/status/2057162392048476345)
+
+## Compute your Swiss Knife Index to expose feature creep
+**Principle.** A product's worth is measured by features actually used, not features shipped; a bloated product is expensive to sustain and hard to sell, not rich.
+**Apply when.** The roadmap has become a user wishlist and every new feature feels like progress (especially with AI making building cheap).
+**The move.** Swiss Knife Index (SKI) = (features used by >40% of active users in a 30-day window) ÷ (total features). Below 0.3, you own a clumsy Swiss army knife. Fix it with: quarterly audits on real usage data (not team opinion); hide, don't delete (push rarely-used features into advanced settings — reachable for the 3%, gone for the 97%); and a gate on every new feature — "which existing feature do I kill to make cognitive room?" Litmus test: which feature would you show first with 30 seconds to sell? The rest stays invisible until needed. See the academic grounding (2034248739557159293) and the curve (2033880553607364684).
+**Visual.** SKI curve — perceived utility rises then declines past the optimal point as complexity keeps climbing — `../assets/2057124008445796659__1.jpg`
+**Voice.** "Which feature would I show first if I had 30 seconds to sell the product?"
+**Source.** [@richardrx · 2026-05-20](https://x.com/richardrx/status/2057124008445796659)
+
+## Design the attention hierarchy to direct behavior, not just organize info
+**Principle.** A product that organizes delivers access; a product that directs delivers activation — and the visual hierarchy decides which the user gets.
+**Apply when.** "My interface looks good, but people don't use the main features" — and the key feature is buried behind three clicks the user will never make.
+**The move.** Recognize that attention hierarchy is the structure deciding what users see first, find with effort, or never discover. Built without intent, the product sabotages itself: users use what's most salient, which is rarely what retains. Plan the hierarchy to influence behavior — make the value-driving, retention-driving feature the most prominent thing — instead of merely arranging information neatly.
+**Visual.** A typographic demo (huge headline "YOU WILL READ THIS FIRST") proving the eye follows visual weight, not reading order — `../assets/2039399756452057159__1.jpg`
+**Voice.** "A well-designed attention hierarchy makes the user use what retains; a bad one makes them use what's most salient."
+**Source.** [@richardrx · 2026-04-01](https://x.com/richardrx/status/2039399756452057159)
+
+## Ground feature discipline in the academic feature-fatigue research
+**Principle.** Past a cognitive-load threshold, the subjective evaluation of a product doesn't stay neutral — it declines into frustration, confusion, and task abandonment, directly hitting CAC and LTV.
+**Apply when.** You need the evidence behind cutting features, and want to separate pre-purchase appeal from post-purchase utility.
+**The move.** Apply the SKI as a decision criterion grounded in feature fatigue. More features help pre-purchase comparison via distinction bias but hurt the decision via analysis paralysis (more options = longer decisions and more no-decisions; no decision, no conversion). Each extra feature steepens the learning curve — measurable B2B productivity loss — and when value comes slowly, users silently churn before the trial ends, blaming themselves, not the product. This complements the index (2057124008445796659) and the curve (2033880553607364684).
+**Evidence.** Thompson, Hamilton & Rust (2005), "Feature Fatigue," JMR 42(4); distinction bias (Hsee & Zhang 2004); analysis paralysis (Iyengar & Lepper 2000).
+**Voice.** "A product that grows without criteria doesn't get rich — it gets expensive to sustain and hard to sell."
+**Source.** [@richardrx · 2026-03-18](https://x.com/richardrx/status/2034248739557159293)
+
+## Past the optimal feature count, a technically bigger product becomes functionally worse
+**Principle.** The relationship between feature count and perceived utility is non-linear: there's an optimal point, after which each added feature reduces perceived utility while raising sustaining cost and the learning curve.
+**Apply when.** You hear "my interface looks good, but people don't use the main features" — a sign you've passed the optimal point.
+**The move.** Read the SKI curve: utility climbs to a peak (~10 features in the example) then falls as complexity keeps rising. The fix isn't more visibility — it's reducing the product's cognitive load so the rest becomes visible again. Criterion: any feature used by under 10% of the active base must justify its existence or leave. There's no universal ideal count — only the ideal for your ICP, context, and device.
+**Visual.** SKI graph: green perceived-utility curve peaks at the optimal point (10.3 features, 97), red complexity curve rises monotonically and overtakes utility in the "decline zone" — `../assets/2033880553607364684__1.jpg`
+**Voice.** "A bloated product isn't a rich product — it's a product actively destroying the conversion and retention you paid dearly to win."
+**Source.** [@richardrx · 2026-03-17](https://x.com/richardrx/status/2033880553607364684)
+
+## Focus on your core; trying to be "all-in-one" dilutes your value proposition
+**Principle.** Chasing a bigger TAM by going generic destroys retention of your heavy users without converting new ones — the same roadmap mistake in cars and in software.
+**Apply when.** The product is tempted to "embrace the world" and become a do-everything tool, abandoning the specific ICP that made it loved.
+**The move.** Remember who your ICP actually is and build for them, even at the expense of broad appeal. In software, when UI/UX tries to cover everything, the value proposition dilutes: you wreck heavy-user retention and fail to convert newcomers because you've gone generic. Focus relentlessly on the core.
+**Evidence.** Porsche chased China's TAM with generic EVs, abandoning its ICP (visceral flat-six machines); ~€3.9B in losses to reverse the roadmap — operating profit fell from €4,000M (2022) to €40M (9M 2025), margin 18% → 0.2%. [Porsche figures from the quoted post; treat as illustrative.]
+**Voice.** "Focus on your damn core."
+**Source.** [@richardrx · 2026-03-11](https://x.com/richardrx/status/2031722047080960265)

package/skills/frontend/design/revenue-centric-design/references/revenue-centric-design.md

@@ -0,0 +1,105 @@
+# Revenue-Centric Design — Philosophy & Process
+
+> Curated, distilled wisdom from @richardrx ("Richard — Design for startups"), translated from Portuguese. Each entry is a reusable principle linked to its source post.
+
+## The 9 principles of Revenue Centric Design (RCD)
+**Principle.** Intentional design serves the user AND the business at once — value and revenue, not one or the other. Richard's canonical framework, named Revenue Centric Design (RCD), built after Dieter Rams' 10 laws (form/function) and Amber Case's Calm Technology (attention/context) — "neither taught me to think about revenue."
+**Apply when.** Designing any digital product meant to convert, retain, and expand; you need a north-star checklist for decisions.
+**The move.** Apply all nine:
+1. **Neutrality is omission** — an interface that doesn't direct hurts conversion.
+2. **Who talks to everyone convinces no one** — no ICP means generic value, which retains worse.
+3. **Value first, ask later** — proof must arrive before the user questions their choice.
+4. **Your promise is the size of your proof** — the market believes what you demonstrate, not what you claim.
+5. **Same competes on price, different on category** — contrast in mechanism, narrative, or experience; no contrast, no margin.
+6. **Default is the decision you made for the user** — most never change settings; the initial state defines mass behavior.
+7. **Retention is built, not requested** — show what the user accumulated; perceived loss retains more than promised benefit.
+8. **Expansion is born of usage** — upsell that interrupts breeds resistance; upgrade at the moment of the limit converts frictionlessly.
+9. **Price is a filter** — pricing defines who enters, who stays, who expands; wrong price attracts the wrong ICP.
+**Voice.** "Rams taught me form and function. Amber Case taught me attention and context. Neither taught me to think about revenue."
+**Source.** [@richardrx · 2026-05-05](https://x.com/richardrx/status/2051672248348479691)
+
+## Design's leverage isn't constant — it changes with the product stage
+**Principle.** Design's payoff is near-zero at MVP and grows to decisive at scale; when a product is dying, design is the *last* place to look for the culprit. Knowing your stage tells you whether design moves the cash or is just vanity.
+**Apply when.** Deciding where design effort should go at your current stage.
+**The move.** Match the discipline to the stage: **MVP** — shorten the path to value and say no to "obvious" features; **Survival** — fix onboarding/activation (the first week beats the whole roadmap and buys runway); **Traction** — conversion (sharp LP + tuned onboarding as channels saturate); **PMF** — depth (design the second "aha," upgrade path, expansion, so retention stabilizes higher); **Scale** — design becomes a system (a design system so 3–4 teams ship without you). Shorten → Activate → Convert → Expand → Systematize.
+**Voice.** "Polishing the UI of a product nobody wants is the most beautiful mistake there is. It dies pretty."
+**Source.** [@richardrx · 2026-06-15](https://x.com/richardrx/status/2066476811177877962)
+
+## Design owns the flow, not the final coat of paint
+**Principle.** What decides whether a user converts or churns — information order, when you ask for the card, what appears at moments of doubt, when value is first felt — is set and coded long before a "finished" product reaches design.
+**Apply when.** Design is scoped as "make it pretty before launch"; product/eng/requirements own the flow (common in big orgs or eng-led teams).
+**The move.** Pull design upstream to own the flow. To win the argument, show it: Richard built the same app twice (requirements-led vs UX-led) and the side-by-side won him project leadership.
+**Voice.** "If I got a buck every time I heard 'design comes in when the product's almost ready,' I'd buy a GT3 RS."
+**Source.** [@richardrx · 2026-06-09](https://x.com/richardrx/status/2064327349894553855)
+
+## Find the leaks before you rebuild the bucket
+**Principle.** Products rarely die from one dramatic error; they bleed out as micro-disappointments accumulate across the journey until the user quits without quite knowing why. Patch the leaks instead of redesigning from scratch — a fraction of the effort for most of the gain.
+**Apply when.** Conversion or retention is dropping and the team's reflex is a full redesign (the addictive blank-page urge).
+**The move.** Run a heuristic analysis: walk the product area by area from landing to activation, mark each point OK or not-OK, screenshot every failure and grade severity across four levels — from aesthetic (ugly but harmless) up to critical (user stalls, conversion dies). The output is a map of holes; find where it's dripping and seal it.
+**Visual.** Journey graph — cumulative score sliding downward, green dots = wins, small red dots = micro-disappointments stacking up — `../assets/2062621019978760424__1.jpg`
+**Voice.** "Redesign from zero says more about the desire of whoever's drawing than the pain of whoever's using."
+**Source.** [@richardrx · 2026-06-04](https://x.com/richardrx/status/2062621019978760424)
+
+## Refactor to solve a real problem, not to repaint the wall
+**Principle.** Designers loop forever ("it's great → could be better → better → repeat"), refactoring UI like code. True refactoring waits for user feedback and changes what fixes a problem; repainting because the old color got boring is vanity that burns a week on pixel-perfect nobody asked for.
+**Apply when.** You feel the itch to redo a screen mid-project; separate "this resolves a known pain" from "this just looks nicer."
+**The move.** Gate the change: does it attack a real, validated pain? Richard's example passed because it tackled an old industry pain — customers not trusting the repair shop's quote. Until usage proves it, "you're just selling the visual."
+**Visual.** RepareCar quote builder — parts pre-loaded with photo, code, and cost; live financial summary (labor + parts = total); client approves by phone — `../assets/2062554393447141438__1.jpg`
+**Source.** [@richardrx · 2026-06-04](https://x.com/richardrx/status/2062554393447141438)
+
+## Mine the tactical layer — it's the most under-explored
+**Principle.** Product design has three leverage drivers — Tactical → Organizational → Strategic. Strategic has the most asymmetric upside, but because everyone outsourced aesthetics to the same AI-generated UI kit, the tactical layer (aesthetics + function) became the most under-explored opportunity in the stack: lowest leverage in theory, highest return in practice, simply because nobody looks.
+**Apply when.** Your SaaS UI looks like every competitor's; you assume polish is "too obvious" to bother with.
+**The move.** Invest the basic care most skip — distinctive aesthetics drive differentiation and branding even for a commodity (e.g., Resend dressing its ICP). Cost lives here too: square Johnnie Walker bottles cut breakage and shipping; the smaller iPhone box fit more units per container — both straight to margin.
+**Evidence.** Ferrari's first EV (Luce, Jony Ive–led) drew the worst brand reception in recent company history — ~8% stock drop, billions in market value erased in 48 hours; mockers compared it to a Honda Accord and a luxury toaster. The revolt was almost entirely visual.
+**Source.** [@richardrx · 2026-05-28](https://x.com/richardrx/status/2059997257156399233)
+
+## Leave the over-used parts alone; improve around them
+**Principle.** Heavily-used parts of a working product form a "cognitive map" — users memorized where everything is and which gesture does what — that is part of the product even if you never designed it intentionally. Redesigning it aggressively makes them pay a re-learning cost and signals you think you know better than they do.
+**Apply when.** You're tempted to overhaul a working, well-adopted product.
+**The move.** Ask: "Which part is so used that touching it would feel hostile?" Freeze that part; improve around it. The bias at work is status-quo bias — people keep the current state when the change's gain seems small versus the effort to re-learn.
+**Evidence.** Snapchat's Feb 2018 redesign (separating friends from brand/creator content) triggered a 1.2M-signature Change.org reversal petition; Kylie Jenner's "does anyone else not open Snapchat anymore?" preceded a sharp stock drop.
+**Voice.** "While we see every redesign as an upgrade, the user can see it as a threat."
+**Source.** [@richardrx · 2026-05-12](https://x.com/richardrx/status/2054180098392178796)
+
+## Don't hire a designer to make software "pretty"
+**Principle.** Aesthetics is subjective, doesn't scale, and won't save a product from high churn. The interface's job is to steer user behavior toward a KPI; aesthetics is sometimes a by-product of that. Hiring design for looks is technical founders' biggest financial mistake.
+**Apply when.** You're scoping design as cosmetics rather than as a growth lever for conversion, retention, and expansion.
+**The move.** Aim design at three outcomes: (1) **Conversion via lower cognitive load** — Hick's Law: each extra on-screen option raises decision time and abandonment; remove friction (Ability in the Fogg model) so the target task is the path of least resistance. (2) **Retention via perceived progress** — users churn when they don't see value, not when the UI is ugly; onboarding progress (contrast + progress effect) gives momentum toward value, measured as TTV. (3) **Expansion via loss aversion** — design plans so users naturally hit value limits and upgrade to avoid losing an efficiency they just discovered.
+**Visual.** Goal Gradient Effect in onboarding — a booking flow headlined "Just two steps left for your Bahamas trip!" with a single primary CTA, showing progress proximity to push completion — `../assets/2029226965580804593__1.jpg`
+**Source.** [@richardrx · 2026-03-04](https://x.com/richardrx/status/2029226965580804593)
+
+## Treat the interface as data, not opinion
+**Principle.** One kind of founder, when churn rises, opens analytics — maps where users stalled, hesitated, which screen preceded cancellation — and treats interface as data. The other debates color palettes in product meetings. One is building a company, the other a portfolio.
+**Apply when.** Deciding how your team reasons about design changes and what conversations product meetings should start from.
+**The move.** Start from LTV, CAC, and activation rate; judge delivery on next quarter's MRR. Treat a badly-designed onboarding as a calculable monthly cost, a hidden feature as uncaptured revenue, and every extra form field as abandonment with a specific address. Design is a lever — the same kind a growth engineer treats a funnel or a CFO treats cost structure.
+**Source.** [@richardrx · 2026-03-30](https://x.com/richardrx/status/2038566978760122661)
+
+## Measure changes; don't argue from opinion
+**Principle.** "Change the color, swap the CTA, kill the pop-up" — and nobody tests anything. Faith in gut beats faith in data science. Product design is experimentation and analysis, not guesswork: if you don't test, how will you improve, and if you don't improve, you don't grow.
+**Apply when.** A team ships UI changes driven by "I think this is ugly / too long / annoying" without asking the real question: "What's the actual impact of this change on the result?"
+**The move.** Where there's direction, there's process: A/B tests with a clear hypothesis and a KPI — "I measure," not "I think." It takes courage to back the doubt and culture to trust the data over ego.
+**Evidence.** A pricing-page experiment generated 68% more AOV (average order value) — "and it wasn't even the coolest experiment we ran."
+**Visual.** Before/After of a pricing block — same product, redesigned tiers, "+68% AOV" badge on the winning variant — `../assets/2026605258152038780__1.jpg`
+**Source.** [@richardrx · 2026-02-25](https://x.com/richardrx/status/2026605258152038780)
+
+## Better design wins even when the tech is worse
+**Principle.** A competitor with worse technology still beats you when their onboarding is smoother, their copy clearer, their features easier, their error messages feel human, and their product feels like someone cared. That sum is "better design" — and it's why they're winning and you're not.
+**Apply when.** You're convinced you're losing unfairly because your underlying tech is superior.
+**The move.** Stop treating design as decoration and audit the felt experience end to end — onboarding friction, copy clarity, error-message tone, the sense that a human cared. Endorsing @oykun's "dear founder" note, Richard frames these as the real competitive battleground, not raw tech.
+**Voice.** "Dear founder, yes, you're right — their tech is worse. But their design is better. That's why they're winning. And you are not."
+**Source.** [@richardrx · 2026-03-24](https://x.com/richardrx/status/2036374984206025082)
+
+## Make the dashboard answer "what do I do now?"
+**Principle.** A dashboard is your software's front door, not NASA mission control. Cram it with colorful charts, five-decimal counters, and endless tables and the user takes a cognitive-overload beating, feels dumb, and churns. A good dashboard answers one question — "What do I do now to get more value?" — and that drives LTV.
+**Apply when.** Building or auditing any data-heavy screen (dashboards, reports, analytics views).
+**The move.** Apply the rule set: (1) **Define your "who"** — list users' top 3 pains, your top 3 value deliveries, and combine them. (2) **Noise is a cognitive tax** — every pixel that doesn't communicate (thick borders, heavy shadows, colored fills) competes for attention; less ink = more signal. (3) **Insights > raw data** — bad: "sales Jan–Dec"; good: "Revenue up 15% vs last month, likely cause: Twitter," with an expandable card (and a free 15-day upsell to act on it). (4) **The "so what?" test** (from Scott Belsky's *Making Ideas Happen*) — for each component, if a number is red, is the fix button right beside it? (5) **Round everything** — drop decimals, currency symbols, cents the ICP doesn't need; "R$10,234.56" → "10k"; white space cuts anxiety. (6) **Group by business context**, not chart type — sales in one block, support in another; the eye scans Z-within-F, so use Gestalt proximity/similarity to shorten the scan. (7) **Size + position = hierarchy** — "if everything is important, nothing is"; the user's North Star metric gets the largest font on screen. (8) **Design for humans** — celebrate when a goal is hit, redirect with good humor when something breaks; reinforce positive behavior to build habit and retention.
+**Visual.** "Raw data → Actionable" LEGO value ladder (collection → preparation → visualization → analysis → storytelling, rising from −value to +value) — `../assets/2022255404743381289__3.jpg`. Bad example: an aesthetic-looking dashboard overloaded with color that fails to direct attention — `../assets/2022255404743381289__4.jpg`. Hierarchy fix: a tiny "13" lost bottom-right (✗) vs a large "13" placed top-left in the F-pattern (✓) — `../assets/2022255404743381289__5.jpg`
+**Voice.** "Your dashboard is a graveyard of data, and that's going to kill your LTV."
+**Source.** [@richardrx · 2026-02-13](https://x.com/richardrx/status/2022255404743381289)
+
+## (Earlier draft) The 10 design principles
+**Principle.** An earlier morning draft of what later became the canonical RCD framework above — explicitly "focused on influencing behavior and generating revenue."
+**Apply when.** Cross-referencing the evolution of RCD; the polished 9-principle list above supersedes it.
+**The move.** Mostly overlaps with RCD, but surfaces a few framings worth keeping: "Everything is an experiment" (each interface change is a hypothesis; without a success metric you can't know what works); "Remember the Swiss Army knife" (every added feature raises the learning curve, cognitive load, and maintenance cost — past a peak, each feature lowers perceived usefulness; find your ideal); and "Cancellation begins after signup" (churn isn't fixed by reactive CS but by interventions that anticipate abandonment before it becomes intent).
+**Source.** [@richardrx · 2026-04-06](https://x.com/richardrx/status/2041117825436106979)

package/skills/frontend/design/ui-ux-pro-max/NOTICE.md

@@ -3,7 +3,7 @@
 This skill was copied from Next Level Builder's UI/UX Pro Max Skill repository.
 
 - Source: https://github.com/nextlevelbuilder/ui-ux-pro-max-skill/tree/main/.claude/skills/ui-ux-pro-max
-- Source commit: b7e3af80f6e331f6fb456667b82b12cade7c9d35
+- Source commit: 8a81ed60272d21d4b8808f7308d49a0b1b000555
 - License: MIT
 - Copyright: Copyright (c) 2024 Next Level Builder
 

package/skills/frontend/design/ui-ux-pro-max/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ui-ux-pro-max
-description: Use when designing, implementing, reviewing, or improving UI/UX for web or mobile products, including layout, style, color, typography, accessibility, interaction states, responsive behavior, dashboards, landing pages, SaaS, e-commerce, portfolios, and app interfaces.
+description: "UI/UX design intelligence for web and mobile. Includes 50+ styles, 161 color palettes, 57 font pairings, 161 product types, 99 UX guidelines, and 25 chart types across 10 stacks (React, Next.js, Vue, Svelte, SwiftUI, React Native, Flutter, Tailwind, shadcn/ui, and HTML/CSS). Actions: plan, build, create, design, implement, review, fix, improve, optimize, enhance, refactor, and check UI/UX code. Projects: website, landing page, dashboard, admin panel, e-commerce, SaaS, portfolio, blog, and mobile app. Elements: button, modal, navbar, sidebar, card, table, form, and chart. Styles: glassmorphism, claymorphism, minimalism, brutalism, neumorphism, bento grid, dark mode, responsive, skeuomorphism, and flat design. Topics: color systems, accessibility, animation, layout, typography, font pairing, spacing, interaction states, shadow, and gradient. Integrations: shadcn/ui MCP for component search and examples."
 ---
 
 # UI/UX Pro Max - Design Intelligence
@@ -330,6 +330,8 @@ sudo apt update && sudo apt install python3
 winget install Python.Python.3.12
 ```
 
+> **Note:** On Windows, use `python` instead of `python3` to run scripts (e.g., `python scripts/search.py` instead of `python3 scripts/search.py`).
+
 ---
 
 ## How to Use This Skill
@@ -360,7 +362,7 @@ Extract key information from user request:
 - **Product type**: Entertainment (social, video, music, gaming), Tool (scanner, editor, converter), Productivity (task manager, notes, calendar), or hybrid
 - **Target audience**: C-end consumer users; consider age group, usage context (commute, leisure, work)
 - **Style keywords**: playful, vibrant, minimal, dark mode, content-first, immersive, etc.
-- **Stack**: Detect the project stack first, then use the matching stack search when available
+- **Stack**: Match the project's framework. The engine ships guidance for many stacks (see [Available Stacks](#available-stacks) below) — pass the matching `--stack` (e.g. `nextjs`, `react`, `shadcn`, `vue`, `svelte`, `astro`, `swiftui`, `flutter`, `react-native`).
 
 ### Step 2: Generate Design System (REQUIRED)
 
@@ -440,12 +442,14 @@ python3 scripts/search.py "<keyword>" --domain <domain> [-n <max_results>]
 | App interface a11y | `web` | `--domain web "accessibilityLabel touch safe-areas"` |
 | AI prompt / CSS keywords | `prompt` | `--domain prompt "minimalism"` |
 
-### Step 4: Stack Guidelines
+### Step 4: Stack Guidelines (match your framework)
 
-Get implementation-specific best practices for the detected stack:
+Get implementation-specific best practices for the stack you're building in.
+Pass the `--stack` that matches the project's framework:
 
 ```bash
-python3 scripts/search.py "<keyword>" --stack react
+python3 scripts/search.py "<keyword>" --stack <your-stack>
+# e.g. --stack nextjs | react | shadcn | vue | svelte | astro | swiftui | flutter | react-native
 ```
 
 ---
@@ -470,18 +474,26 @@ python3 scripts/search.py "<keyword>" --stack react
 
 ### Available Stacks
 
+Run `ls <skill>/data/stacks/` to see the live set. Shipped stacks:
+
 | Stack | Focus |
 |-------|-------|
-| `react` | Components, state, rendering, accessibility |
-| `nextjs` | App Router, server/client boundaries, routing |
-| `vue` | Components and composition patterns |
-| `svelte` | Components and reactivity patterns |
-| `astro` | Content and island architecture |
-| `swiftui` | iOS-native UI structure |
-| `react-native` | Components, navigation, lists |
-| `flutter` | Widgets, theming, navigation |
-| `html-tailwind` | Utility-first HTML/CSS |
-| `shadcn` | Radix/shadcn UI composition |
+| `react` | Components, hooks, render performance |
+| `nextjs` | App Router, RSC, Server Actions, rendering |
+| `vue` | Components, Composition API, reactivity |
+| `nuxtjs` | Nuxt app patterns, SSR data fetching |
+| `nuxt-ui` | Nuxt UI component patterns |
+| `svelte` | Components, stores, transitions |
+| `astro` | Islands, content, partial hydration |
+| `shadcn` | shadcn/ui primitives, composition |
+| `html-tailwind` | Tailwind utility patterns |
+| `angular` | Components, signals, services |
+| `laravel` | Blade / server-rendered UI patterns |
+| `swiftui` | Views, state, navigation (iOS/macOS) |
+| `flutter` | Widgets, state, navigation |
+| `jetpack-compose` | Composables, state, navigation (Android) |
+| `react-native` | Components, Navigation, Lists |
+| `threejs` | 3D scenes, materials, performance |
 
 ---
 
@@ -493,7 +505,7 @@ python3 scripts/search.py "<keyword>" --stack react
 - Product type: Tool (AI search engine)
 - Target audience: C-end users looking for fast, intelligent search
 - Style keywords: modern, minimal, content-first, dark mode
-- Stack: detected from the target project
+- Stack: Next.js (a homepage is a web surface; use a web `--stack`)
 
 ### Step 2: Generate Design System (REQUIRED)
 
@@ -516,7 +528,7 @@ python3 scripts/search.py "search loading animation" --domain ux
 ### Step 4: Stack Guidelines
 
 ```bash
-python3 scripts/search.py "list performance navigation" --stack react
+python3 scripts/search.py "list performance navigation" --stack nextjs
 ```
 
 **Then:** Synthesize design system + detailed searches and implement the design.
@@ -544,7 +556,7 @@ python3 scripts/search.py "fintech crypto" --design-system -f markdown
 - Use **multi-dimensional keywords** — combine product + industry + tone + density: `"entertainment social vibrant content-dense"` not just `"app"`
 - Try different keywords for the same need: `"playful neon"` → `"vibrant dark"` → `"content-first minimal"`
 - Use `--design-system` first for full recommendations, then `--domain` to deep-dive any dimension you're unsure about
-- Add the matching `--stack` option for implementation-specific guidance
+- Add the `--stack` that matches the project's framework for implementation-specific guidance
 
 ### Common Sticking Points
 

package/skills/frontend/react/react-patterns/NOTICE.md

@@ -3,7 +3,7 @@
 This skill is copied from Affaan Mustafa's public `affaan-m/ECC` repository.
 
 - Source: https://github.com/affaan-m/ECC/tree/main/skills/react-patterns
-- Imported from commit: `0f84c0e2796703fbda87d577b2636351418c7442`
+- Imported from commit: `2bc924faf2f8e893bfe0af86b1931283693c30ae`
 - Upstream skill name: `react-patterns`
 - License: MIT
 - Copyright: Copyright (c) 2026 Affaan Mustafa

package/skills/frontend/react/react-patterns/SKILL.md

@@ -1,7 +1,8 @@
 ---
 name: react-patterns
 description: React 18/19 patterns including hooks discipline, server/client component boundaries, Suspense + error boundaries, form actions, data fetching, state management decision trees, and accessibility-first composition. Use when writing or reviewing React components.
-origin: ECC
+metadata:
+  origin: ECC
 ---
 
 # React Patterns

package/skills/frontend/react/react-performance/NOTICE.md

@@ -3,7 +3,7 @@
 This skill is copied from Affaan Mustafa's public `affaan-m/ECC` repository.
 
 - Source: https://github.com/affaan-m/ECC/tree/main/skills/react-performance
-- Imported from commit: `0f84c0e2796703fbda87d577b2636351418c7442`
+- Imported from commit: `2bc924faf2f8e893bfe0af86b1931283693c30ae`
 - Upstream skill name: `react-performance`
 - License: MIT
 - Copyright: Copyright (c) 2026 Affaan Mustafa

package/skills/frontend/react/react-performance/SKILL.md

@@ -1,7 +1,8 @@
 ---
 name: react-performance
 description: React and Next.js performance optimization patterns adapted from Vercel Engineering's React Best Practices (https://github.com/vercel-labs/agent-skills). Organizes 70+ rules across 8 priority categories — waterfalls, bundle size, server-side, client fetching, re-render, rendering, JS micro-perf, advanced. Use when writing, reviewing, or refactoring React/Next.js code for performance.
-origin: ECC
+metadata:
+  origin: ECC
 ---
 
 # React Performance

package/skills/frontend/react/react-testing/NOTICE.md

@@ -3,7 +3,7 @@
 This skill is copied from Affaan Mustafa's public `affaan-m/ECC` repository.
 
 - Source: https://github.com/affaan-m/ECC/tree/main/skills/react-testing
-- Imported from commit: `0f84c0e2796703fbda87d577b2636351418c7442`
+- Imported from commit: `2bc924faf2f8e893bfe0af86b1931283693c30ae`
 - Upstream skill name: `react-testing`
 - License: MIT
 - Copyright: Copyright (c) 2026 Affaan Mustafa

package/skills/frontend/react/react-testing/SKILL.md

@@ -1,7 +1,8 @@
 ---
 name: react-testing
 description: React component testing with React Testing Library, Vitest/Jest, MSW for network mocking, accessibility assertions with axe, and the decision boundary between component tests and Playwright/Cypress end-to-end runs. Use when writing or fixing tests for React components, hooks, or pages.
-origin: ECC
+metadata:
+  origin: ECC
 ---
 
 # React Testing

package/skills/general/code-reviewer/AGENTS.md

@@ -11,7 +11,7 @@
 2. [XSS Prevention](#xss-prevention)
 
 ### Performance — **HIGH**
-3. [Avoid N+1 Query Problem](#avoid-n-1-query-problem)
+3. [Avoid N+1 Query Problem](#avoid-n1-query-problem)
 
 ### Correctness — **HIGH**
 4. [Proper Error Handling](#proper-error-handling)

package/skills/general/code-reviewer/NOTICE.md

@@ -3,7 +3,7 @@
 This skill was copied from Shubhamsaboo's awesome-llm-apps repository.
 
 - Source: https://github.com/Shubhamsaboo/awesome-llm-apps/tree/main/awesome_agent_skills/code-reviewer
-- Source commit: 72718ec759ecc82ead7666fd47922928b61c2b4d
+- Source commit: ca3a3d37438643fd47b1dac095c2ce9cca92ef72
 - Repository license: Apache-2.0
 - Upstream skill metadata also declares: MIT