@ranimontagna/agent-toolkit 0.1.19 → 0.1.21

package/README.md

@@ -210,6 +210,10 @@ skills/
         debugging.md
         testing.md
     design/
+      revenue-centric-design/
+        SKILL.md
+        assets/
+        references/
       ui-ux-pro-max/
         SKILL.md
         data/
@@ -356,6 +360,7 @@ Follow these steps...
 | `devops` | `docker-patterns` | Adapted from Affaan Mustafa's [`ECC`](https://github.com/affaan-m/ECC/tree/main/.kiro/skills/docker-patterns) and [`sickn33/antigravity-awesome-skills`](https://github.com/sickn33/antigravity-awesome-skills/tree/main/skills/docker-expert), both under the MIT license |
 | `frontend` | `accessibility` | Copied from Affaan Mustafa's [`ECC`](https://github.com/affaan-m/ECC/tree/main/skills/accessibility) under the MIT license |
 | `frontend` | `astro-developer` | Copied from the official [`withastro/astro`](https://github.com/withastro/astro/tree/main/.agents/skills/astro-developer) repository under the MIT license |
+| `frontend` | `revenue-centric-design` | Copied from Helio Costa's [`revenue-centric-design`](https://github.com/heliocosta-dev/revenue-centric-design) under source-available custom terms requiring attribution and excluding gambling/betting/casino use |
 | `frontend` | `ui-ux-pro-max` | Copied from Next Level Builder's [`ui-ux-pro-max-skill`](https://github.com/nextlevelbuilder/ui-ux-pro-max-skill/tree/main/.claude/skills/ui-ux-pro-max) under the MIT license |
 | `frontend` | `gsap-core` | Copied from GreenSock's [`gsap-skills`](https://github.com/greensock/gsap-skills/tree/main/skills/gsap-core) under the MIT license |
 | `frontend` | `gsap-frameworks` | Copied from GreenSock's [`gsap-skills`](https://github.com/greensock/gsap-skills/tree/main/skills/gsap-frameworks) under the MIT license |
@@ -661,8 +666,8 @@ Release a new npm version by updating `package.json`, pushing the change to
 `main`, then pushing a matching tag:
 
 ```bash
-git tag v0.1.19
-git push origin v0.1.19
+git tag v0.1.21
+git push origin v0.1.21
 ```
 
 For normal releases, prefer the scripted flow. It bumps `package.json`, updates

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ranimontagna/agent-toolkit",
-  "version": "0.1.19",
+  "version": "0.1.21",
   "description": "Personal AI agent toolkit installer for Claude Code, Codex CLI, OpenCode, Gemini CLI, Antigravity and graph-aware workflows.",
   "type": "module",
   "packageManager": "pnpm@11.8.0",

package/skills/frontend/design/design-to-code/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: design-to-code
+description: "Convert design artifacts into React + TypeScript + Tailwind code that follows the target repository's design system and conventions. Inputs auto-detected: local HTML mockups (Claude Design / Open Design output), artifact URLs, or screenshots. Use when asked to 'transformar design em código', 'implementar mockup', 'implementar design', 'design to code', turn a Claude Design / Open Design artifact into components, or convert an HTML mockup to React. Requires the target repo to use React, TypeScript, and Tailwind. Output: components + assembled page, wired to the repo's routing/state/data-fetching patterns when detectable, with structural visual verification."
+---
+
+# Design to Code
+
+Convert a design artifact into production React + TypeScript + Tailwind code that looks like it was written by the target repo's own team.
+
+## Golden rule
+
+**Design = intent, repo = law.**
+
+The design tells you *what* to build — structure, hierarchy, content, interaction. The target repository tells you *how* — tokens, components, naming, wiring. When they conflict, the repo wins.
+
+Consequences:
+
+- Never use arbitrary Tailwind values (`bg-[#3B82F6]`, `p-[18px]`). Map every design value to the nearest repo token. The only escape is a documented exception with written justification (see `mapping.md`).
+- Never invent a token, variant, or pattern the repo lacks. If the design needs one, propose it as an **explicit extension** and get approval at the Phase 3 gate.
+- Reuse existing components before creating new ones. New components only when no equivalent exists.
+
+## Preconditions
+
+The target repo MUST have React + TypeScript + Tailwind.
+
+- **No Tailwind** → abort. Tell the user exactly what is missing and that this skill only targets react+ts+tailwind repos.
+- **No design system** (no custom tokens, no reusable components) → degrade gracefully: use the default Tailwind scale, mark every component NEW, and warn the user that nothing could be reused.
+- **Monorepo** → ask which app/package is the target before Phase 1.
+
+## Pipeline
+
+Five phases, strictly gated. On entering a phase, read its reference file (same directory as this SKILL.md). Do not read phase files ahead of time — progressive disclosure keeps context lean.
+
+| Phase | Reference | Output artifact | Gate to proceed |
+|---|---|---|---|
+| 1. Discovery | `discovery.md` | `repo-map.md` | Artifact written |
+| 2. Input analysis | `input-analysis.md` | `design-spec.md` | Artifact written |
+| 3. Mapping | `mapping.md` | `mapping-table.md` | **USER APPROVAL** |
+| 4. Generation | `generation.md` | Code in target repo | Static checks pass |
+| 5. Verification | `verification.md` | Verification report | Checklist passes or 3 rounds |
+
+Phase N may not start until phase N−1's gate is satisfied. Phases 1 and 2 are independent of each other in content but run in this order so component candidates in Phase 2 can be named in the repo's style.
+
+**Create a todo per phase when the pipeline starts.** Mark each in_progress/completed as you go.
+
+## Artifacts
+
+Write intermediate artifacts to the session scratchpad directory:
+
+- `repo-map.md` — what the repo offers (tokens, components, conventions, wiring patterns)
+- `design-spec.md` — what the design asks for (component tree, observed tokens, content, states)
+- `mapping-table.md` — the crossing of the two (REUSE / EXTEND / NEW decisions, token mapping, exceptions)
+- `screen-backlog.md` — multi-screen runs only (see below)
+
+Later phases **read artifacts instead of re-analyzing**. If a session is resumed mid-pipeline, read the existing artifacts and continue from the first missing one.
+
+**Persistence across sessions:** for work likely to span sessions (multi-screen designs, large repos), write the artifacts to `.design-to-code/` at the target repo root instead of the scratchpad, and add that directory to the repo's `.gitignore` if not already ignored. A new session then resumes by reading `.design-to-code/` — repo-map and mapping decisions survive, only staleness needs re-checking (did tokens/components change since the artifact was written? `git log` on the token/component paths answers it).
+
+## Multi-screen designs
+
+A design with more than ~2 screens does not fit one pipeline pass. Structure it:
+
+1. Phase 2 produces one `design-spec.md` **per screen** (or per tight screen group), plus `screen-backlog.md`:
+
+```markdown
+# Screen backlog — <design>
+| # | Screen | Depends on | Status | Commit |
+|---|---|---|---|---|
+| 1 | Chrome (sidebar+topbar) | — | done | abc123 |
+| 2 | Home | 1 | done | def456 |
+| 3 | Search | 1 | in progress | |
+| 4 | Detail + booking modal | 1 | pending | |
+```
+
+2. Order the backlog: shared chrome/layout first, then screens leaf-to-complex. Phases 3–5 run **per batch** (1–2 screens), each batch ending in a commit and a backlog status update.
+3. Phase 1 runs once; Phase 3's mapping-table grows incrementally — new screens append rows, and components created by earlier batches become REUSE candidates for later ones.
+4. The consolidation pass (see `verification.md`) runs once at the end, across everything the run created.
+
+## The Phase 3 gate (hard stop)
+
+`mapping-table.md` is presented to the user before any code is generated:
+
+- EXTEND decisions modify existing components — the user must see the API diff and approve.
+- Token mappings change the design's raw values — the user must see what diverges and why.
+
+Wait for explicit approval. Apply any requested changes to the table, then enter Phase 4. Never skip this gate, even when every decision is REUSE.
+
+**Autonomous runs:** when the user has explicitly pre-authorized unattended execution (batch run, "não precisa me perguntar", scheduled/loop mode), self-approve the gate — but record in `mapping-table.md` that it was auto-approved and why, keep every EXTEND strictly additive, and surface the full table in the final report so the user reviews it after the fact.
+
+## Input priority
+
+When multiple design inputs exist for the same design:
+
+1. **Local HTML file** — structural source of truth
+2. **Artifact URL** — fetch, then treat as HTML
+3. **Screenshot** — vision extraction; when HTML also exists, the screenshot only validates appearance
+
+Multiple candidate designs (e.g., two HTML files, unclear which) → ask the user. Never guess.

package/skills/frontend/design/design-to-code/discovery.md

@@ -0,0 +1,82 @@
+# Phase 1 — Discovery
+
+## Purpose
+
+Inventory the target repository so every later decision (naming, reuse, tokens, wiring) is grounded in what actually exists. This phase reads the repo; it changes nothing.
+
+## Inputs
+
+- Target repository working directory (ask which app/package first if monorepo).
+
+## Procedure
+
+1. **Stack detection**
+   - Tailwind version: `tailwind.config.{js,ts,cjs,mjs}` → v3-style config; CSS with `@theme` / `@import "tailwindcss"` → v4. Record where tokens live.
+   - shadcn: `components.json` present → record its aliases and `ui/` path.
+   - Routing: `app/` or `pages/` dir (Next.js), `react-router` / `@tanstack/react-router` in package.json. Record the idiom (file-based vs route objects) and one example route file.
+   - State: grep imports for `zustand`, `@reduxjs/toolkit`, `jotai`, `valtio`; note context-based patterns in `providers/` or `context/`.
+   - Data-fetching: `@tanstack/react-query`, `swr`, or plain `fetch` wrappers (`lib/api`, `services/`). Record one example usage.
+
+2. **Token inventory**
+   - From the Tailwind config (v3) or `@theme` block / CSS vars (v4): colors, spacing overrides, font families, radii, shadows.
+   - Record every custom token as `name → value`. Note whether colors are semantic (`primary`, `destructive`) or palette-step (`brand-500`).
+   - No custom tokens at all → note "default Tailwind scale only" (triggers the degraded mode from SKILL.md).
+
+3. **Component inventory**
+   - Scan `components/`, `src/components/`, `ui/`, and the shadcn path if present.
+   - Per component record: name, file path, props signature, variants (cva variants, union-typed props). **Read signatures and variant definitions only — not full implementations.**
+   - Large codebases: inventory `ui/` primitives fully; feature-level components by name + one-line role only.
+
+4. **Convention detection**
+   - File naming (PascalCase.tsx vs kebab-case.tsx), folder-per-feature vs flat, export style (default vs named, barrel `index.ts` or not), test file pattern (`*.test.tsx` location), class-merge helper (`cn`, `clsx`, `twMerge`).
+
+5. **Verify build commands**
+   - Actually run the repo's typecheck and build once, now. If `pnpm exec`/`npx` wrappers misbehave (hook/proxy environments can break them), fall back to `./node_modules/.bin/<tool>` and record whichever form worked — Phases 4–5 depend on these commands.
+
+## Output: `repo-map.md`
+
+Write to the session scratchpad, in this shape:
+
+```markdown
+# Repo Map — <repo name>
+
+## Stack
+- Tailwind: v4 (tokens in src/styles/globals.css @theme)
+- shadcn: yes (components.json → @/components/ui)
+- Routing: Next.js app router | react-router v7 | none detected
+- State: zustand (src/stores/) | none detected
+- Data-fetching: react-query (src/hooks/queries/) | none detected
+
+## Tokens
+| Kind | Token | Value |
+|---|---|---|
+| color | primary | #4f46e5 |
+| radius | radius-lg | 12px |
+
+## Components
+| Name | File | Props | Variants |
+|---|---|---|---|
+| Button | components/ui/button.tsx | variant, size, asChild | solid/ghost/outline; sm/md/lg |
+
+## Conventions
+- Naming: kebab-case files, named exports, no barrels
+- Class merge: cn() from lib/utils
+- Tests: colocated *.test.tsx
+
+## Verified commands
+- Typecheck: ./node_modules/.bin/tsc -b
+- Build: ./node_modules/.bin/vite build
+- Dev/preview: ./node_modules/.bin/vite preview --port 4180
+
+## Wiring patterns
+- Route example: app/dashboard/page.tsx
+- Query example: useQuery in src/hooks/queries/use-orders.ts
+```
+
+Mark absent things explicitly as "none detected" — Phase 4 uses that to decide mock-only wiring.
+
+## Failure modes
+
+- **No Tailwind** → stop, abort per SKILL.md preconditions.
+- **Monorepo, target ambiguous** → ask the user which app; do not inventory everything.
+- **Hundreds of components** → primitives fully, feature components as name + role. Never dump full implementations into the map.

package/skills/frontend/design/design-to-code/generation.md

@@ -0,0 +1,60 @@
+# Phase 4 — Generation
+
+## Purpose
+
+Produce the code exactly as `mapping-table.md` (approved at the gate) prescribes, written in the target repo's own style.
+
+## Inputs
+
+- `mapping-table.md` (approved) — the only source of component decisions and token choices
+- `design-spec.md` — structure, content, states
+- `repo-map.md` — conventions and wiring patterns
+
+## Procedure
+
+1. **Order of work**
+   1. **Extensions first** — smallest diffs, and they unblock reuse everywhere else. Apply each approved API diff additively; never alter existing variant behavior.
+   2. **NEW components, leaf-first** — primitives before composites, so composites import real code.
+   3. **Page / composition** — assemble per the design-spec component tree, preserving section order and heading hierarchy.
+   4. **Wiring last** — see step 3.
+
+2. **Style rules (every file)**
+   - Strict TS: typed props (interface or type per repo habit), no `any`, no `@ts-ignore`.
+   - Follow `repo-map.md` conventions exactly: file naming, export style, folder placement, class-merge helper (`cn`/`clsx`).
+   - Tailwind classes only from the approved token mapping. Class order: layout → spacing → typography → color → states.
+   - No inline `style=` attributes.
+   - Repeated visual units (cards, rows, tiers) render from a typed data array, never copy-pasted JSX.
+
+3. **Wiring**
+   - `repo-map.md` shows a routing pattern → create the route in that idiom (app-router page, route object, etc.).
+   - Shows a data-fetching pattern → wire it in the repo's idiom (e.g., a `useQuery` hook) backed by the mock data, so swapping to a real endpoint is a one-line change.
+   - Shows a state pattern and the design needs shared state → follow it. Local UI state stays `useState`.
+   - Pattern "none detected" → typed mock data only: put it in the repo's `mocks/` dir if one exists, else colocate a `*.mock.ts` next to the page. Mock content comes from the design-spec Content inventory — real texts and numbers, not lorem ipsum.
+
+4. **Filling design gaps with restraint**
+   When the design doesn't specify something you must build anyway (responsive collapse it never drew, empty/error/loading states, a screen edge case):
+   - Default to restraint: no invented badges/pills/decorative micro-UI, no cards nested inside cards, preserve the design's negative space and rhythm.
+   - Reuse the design's own motifs (from the design-spec) instead of importing generic patterns.
+   - Every invented piece goes in the Phase 5 report under "accepted differences" — gap-filling is fine, silent invention is not.
+
+5. **Accessibility baseline (mandatory)**
+   - Semantic landmarks: `nav`, `main`, `header`, `footer`, `aside`.
+   - Heading hierarchy exactly as extracted in the design-spec.
+   - `alt` on images, labels on form controls, `button` vs `a` used by behavior (action vs navigation).
+   - Interactive elements keyboard-reachable with visible focus (repo's focus ring token if one exists).
+
+6. **Per-file self-check (before moving to the next file)**
+   - Does it compile in your head — every import exists per `repo-map.md`?
+   - Every class traceable to the approved mapping? Zero arbitrary values outside the Exceptions table?
+   - Props typed, mock data typed?
+   - Only use component APIs the repo actually has (per the `repo-map.md` props column). Don't assume shadcn idioms (`asChild`, `forwardRef` wrappers, slot props) on hand-rolled components that look similar.
+
+## Output
+
+Code in the target repo. No artifact file — Phase 5 verifies directly.
+
+## Failure modes
+
+- **Extension was rejected at the gate** → NEW component that wraps the existing one instead of modifying it.
+- **Ambiguous wiring** (two routers present, two fetch idioms) → ask the user; don't pick silently.
+- **Design-spec node impossible with approved mapping** (e.g., needs a variant the user removed at the gate) → go back to the gate with a revised proposal; don't improvise.

package/skills/frontend/design/design-to-code/input-analysis.md

@@ -0,0 +1,83 @@
+# Phase 2 — Input analysis
+
+## Purpose
+
+Turn the design artifact into a structured spec: what sections exist, how they're laid out, what values they use, what content they carry. The spec is the contract Phase 4 implements and Phase 5 verifies against.
+
+## Inputs
+
+- Design artifact(s): local HTML, artifact URL, and/or screenshot.
+- `repo-map.md` (for naming component candidates in the repo's style).
+
+## Procedure
+
+1. **Detect inputs**
+   - Use what the user pointed at. If nothing explicit, look for obvious candidates: `*.html` mockups in cwd, `temp/`, `designs/`, or recently mentioned files/URLs.
+   - Multiple candidate designs and it's unclear which → **ask the user, never guess**.
+   - Priority when the same design exists in several forms: **design source folder > local HTML > URL (fetch it, then treat as HTML) > screenshot**. HTML + screenshot together → HTML is the structural truth; use the screenshot only to validate rendered appearance.
+   - **Design source folders** (Claude Design / Open Design exports) are the richest input. Recognize them by: a folder with `.jsx`/`.tsx` source files, one or more small `*.html` shells, large `*Standalone.html` bundles, and often a `HANDOFF*.md`/`README` doc. Handle each part by role:
+     - `.jsx/.tsx` sources → structural truth: real component boundaries, props, state, interactions. Read these instead of parsing rendered HTML.
+     - Handoff/README docs → often carry tokens, TypeScript types, mock data, and behavior notes **verbatim** — lift them directly into the spec instead of re-deriving. But its stack prescriptions (e.g. "don't use Tailwind") do NOT override the target repo: design = intent, repo = law.
+     - `*Standalone.html` bundles (hundreds of KB to MB, inline React/Babel) → **never read as text** (they destroy context). Use them only as the render reference: screenshot with a headless browser for Phase 5 comparison. They need a generous render budget (e.g. `--virtual-time-budget=15000`) because they compile in-browser.
+
+2. **Extract structure** (HTML: read markup + styles; screenshot: vision)
+   - Section hierarchy top to bottom (nav, hero, content regions, footer...).
+   - Layout system per section: grid vs flex, column counts, alignment, sidebar widths, breakpoints if declared.
+   - Heading hierarchy (h1/h2/h3) — Phase 4 must preserve it.
+
+3. **Extract observed tokens**
+   - Colors (hex/rgb) with role: background, surface, text, accent, success/danger.
+   - Typography: families, the distinct size/weight steps actually used — and the **scale relationships** (how much bigger is the h1 than the sub? than body?), which survive token mapping even when exact px don't.
+   - Spacing rhythm: the distinct paddings/gaps in use (e.g., 18/22/28px) — record raw values; mapping to repo scale happens in Phase 3, not here. Also record **cadence relationships**: headline↔subheadline distance vs section gaps vs card gaps — relative rhythm is what Phase 5 checks.
+   - Radii, shadows, borders.
+   - Repeated visual motifs (a texture, a chip style, a decorative pattern) — name them once; they anchor cross-screen consistency later.
+
+4. **Extract states and interactions**
+   - Hover/active/disabled styles present in CSS; focus styles; anything animated.
+   - Screenshots can't show hover — note "states not observable" so Phase 4 falls back to repo component defaults.
+
+5. **Extract content**
+   - Real texts, numbers, table rows, labels — **verbatim**, including CTA microcopy, section headings, and small labels. These become **typed mock data** in Phase 4 — never lorem ipsum, never paraphrased copy, when the design has real content.
+
+6. **Decompose into candidate components**
+   - One responsibility per node. Repeated visual units (cards, rows, tiers) → one component + data array.
+   - Name candidates in the repo's naming style (from `repo-map.md`).
+
+## Output: `design-spec.md`
+
+Write to the session scratchpad, in this shape:
+
+```markdown
+# Design Spec — <artifact name>
+
+## Overview
+Analytics dashboard: fixed sidebar, header, stats row, revenue table, chart panel.
+
+## Component tree
+- DashboardPage
+  - Sidebar — logo, nav list (5 items, active state), user footer
+  - Header — search input, avatar
+  - StatCard ×4 — label, value, delta (up/down)
+  - RevenueTable — 5 rows, status badge per row
+  - ChartPanel — bar chart placeholder
+
+## Observed tokens
+| Kind | Value | Role / where |
+|---|---|---|
+| color | #4f6ef7 | accent: active nav, primary button |
+| spacing | 22px | card padding |
+
+## States & interactions
+- Nav item hover: background lightens
+- Table row hover: surface tint
+
+## Content inventory
+- Stat cards: "Revenue $48,2k +12%", ...
+- Table rows: (Acme Corp, $1,200, Paid), ...
+```
+
+## Failure modes
+
+- **Illegible / low-res screenshot** → request a better export or the HTML. Do not invent details vision can't confirm.
+- **URL unreachable** → ask for an HTML export instead.
+- **Design spans multiple screens/pages** → one `design-spec.md` per screen plus `screen-backlog.md`, per the Multi-screen designs section of SKILL.md. Confirm scope/order with the user unless running autonomously (then: chrome first, leaf-to-complex).

package/skills/frontend/design/design-to-code/mapping.md

@@ -0,0 +1,73 @@
+# Phase 3 — Mapping
+
+## Purpose
+
+Cross `design-spec.md` against `repo-map.md`: decide for every component candidate whether to reuse, extend, or create, and map every observed design value to a repo token. Ends in a **hard user-approval gate**.
+
+## Inputs
+
+- `design-spec.md` (what the design asks for)
+- `repo-map.md` (what the repo offers)
+
+## Procedure
+
+1. **Component decisions** — for each candidate in the component tree:
+   - **REUSE** — a repo component has the same role and a compatible API. Record which props/variants will be used.
+   - **EXTEND** — a repo component has the role but lacks a variant/prop the design needs (e.g., Button has sm/md but design needs an xl hero button). Write an **explicit API diff**:
+     ```
+     Button (components/ui/button.tsx)
+       size: "sm" | "md" | "lg"          → size: "sm" | "md" | "lg" | "xl"
+     ```
+     Extensions must be additive — never change existing variant behavior.
+   - **NEW** — no equivalent exists. Decide its path per repo conventions (`repo-map.md` → Conventions).
+
+2. **Color mapping** — for each observed color, pick the nearest repo token:
+   - Compare hue first, then lightness. A same-hue token two lightness steps away beats a closer-lightness token in a different hue.
+   - Ties → prefer semantic tokens (`primary`, `destructive`) over palette steps (`blue-500`).
+   - Record the mapping and a one-word distance note (exact / close / far).
+
+3. **Spacing / typography / radii mapping** — nearest scale step. Round consistently within a section (don't map 18px→4 and 22px→6 in the same card; pick one direction so rhythm survives).
+
+4. **Exceptions** — arbitrary values (`h-[57px]`) are forbidden. The only escape: an Exceptions table row with written justification (e.g., brand asset with fixed aspect ratio). Target: empty table.
+
+## Output: `mapping-table.md`
+
+Write to the session scratchpad, three tables:
+
+```markdown
+# Mapping — <design> → <repo>
+
+## Components
+| Candidate | Decision | Target / new path | Notes |
+|---|---|---|---|
+| StatCard | NEW | components/dashboard/stat-card.tsx | no equivalent |
+| Button (hero) | EXTEND | components/ui/button.tsx | size: +"xl" — diff below |
+| Badge | REUSE | components/ui/badge.tsx | variant="success" |
+
+### EXTEND diffs
+Button: size "sm"|"md"|"lg" → "sm"|"md"|"lg"|"xl"
+
+## Tokens
+| Design value | Repo token | Distance |
+|---|---|---|
+| #4f6ef7 | primary (#4f46e5) | close |
+| 22px card padding | p-5 (20px) | close |
+
+## Exceptions
+| Value | Justification |
+|---|---|
+| (none) | |
+```
+
+## Gate (hard stop — from SKILL.md)
+
+Present all three tables to the user. Wait for explicit approval.
+
+- EXTEND rows modify existing code — user must see each API diff.
+- Token rows change the design's raw values — user must see what diverges.
+- Apply requested changes to the table **before** entering Phase 4. Never skip the gate, even when everything is REUSE.
+
+## Failure modes
+
+- **No token remotely close** (design is neon green, repo palette is earth tones) → design-system conflict. Don't silently pick either side. Ask the user: (a) map to nearest anyway, (b) propose a new token as an extension, (c) keep the raw value as a justified exception.
+- **Two repo components could serve the same role** → pick the one used more often in the repo; note the alternative in the table.

package/skills/frontend/design/design-to-code/verification.md

@@ -0,0 +1,68 @@
+# Phase 5 — Verification
+
+## Purpose
+
+Prove the generated code matches the design **structurally** — not pixel-for-pixel, since Phase 3 intentionally remapped raw values to repo tokens.
+
+## Inputs
+
+- Generated code (Phase 4)
+- Original design artifact (HTML/screenshot/URL)
+- `design-spec.md`, `mapping-table.md`
+
+## Procedure
+
+1. **Static verification (must pass before the visual loop)**
+   - Discover the target repo's scripts from its `package.json`: typecheck (`tsc --noEmit` or a `typecheck` script), lint, build.
+   - Run all three. Fix failures before any screenshot — a broken build makes visual comparison meaningless.
+   - If `pnpm exec`/`npx` misbehaves (hangs, OOMs, "missing script" for a binary that exists — shell hooks/proxies can break these wrappers), bypass with the direct binary: `./node_modules/.bin/<tool>`. Record the working commands in `repo-map.md` so later phases reuse them.
+   - **Arbitrary-value gate (mechanical):** grep the generated/modified files for arbitrary Tailwind values — `grep -nE '\[(#|[0-9]+px)' <new files>` catches `bg-[#...]`, `p-[18px]`, `h-[57px]`. Every hit must correspond to a row in the mapping-table's Exceptions table. A hit with no exception row is a Phase 4 bug: fix the code or (rarely) go back to the gate to justify it. Decorative parametric styles passed via `style=` (per-datum gradients) are exempt only if the Exceptions table names them.
+
+2. **Visual loop**
+   1. Start the repo's dev server (its `dev` script) in the background; wait for it to report ready.
+   2. Screenshot the new page/components. Tooling, in detection order:
+      - Playwright already in the repo → use it
+      - `npx playwright screenshot` available → use that
+      - Headless Chrome/Chromium (`chromium --headless --screenshot`) → fallback
+   3. Compare against the original design artifact side by side.
+   4. **Responsive matrix:** when the design-spec declares breakpoints or responsive behavior (sidebar collapse, grid → single column), screenshot at three widths — mobile 390, tablet 768, desktop 1440 — and run the fidelity checklist per viewport. Desktop-only designs skip this, but say so in the report rather than silently checking one width.
+
+3. **Interactive states (don't skip — static screenshots miss them)**
+   Route screenshots never capture modals, hover states, dropdowns, or multi-step flows. For every spec'd state that needs interaction to reach:
+   - **Preferred:** drive the real flow — a throwaway Playwright script (repo's Playwright or `./node_modules/.bin/playwright`), or headless Chrome via DevTools Protocol, that clicks through and screenshots each state (e.g., open the booking modal, advance each step; log in through the app's own mock auth to reach protected screens). Real-flow driving beats state injection: it also proves the transitions work.
+   - **Fallback — state injection:** temporarily flip the state's source to render it directly (store default, seeded route param, initial-step prop), screenshot, then revert before committing. Same technique as auth-state parity.
+   - **Neither possible:** the state goes in the report under **"Spec'd states NOT visually verified"** with the reason. This list is mandatory in the final report — an empty list is a claim, so make it explicitly ("all interactive states exercised"), not by omission.
+   - **Match app state to the design's depicted state before comparing** (auth logged in/out, active tab, filters, seeded data). A state mismatch reads as dozens of false layout diffs.
+   - `file://` screenshot pitfalls: spaces/unicode in filenames break the URL — copy the file to a space-free scratch path instead of fighting encoding. A suspiciously small screenshot (~15–20 KB dark page) is Chrome's error page (`ERR_FILE_NOT_FOUND`), not your render — check the path before debugging the code.
+   - **SPA prototypes with state-based routing** (route in `useState`/localStorage, no URL routing) can't deep-link to inner views. To screenshot an inner view, patch a *copy* of the prototype's initial-route expression (`sed` on the copy — never the original). If the bundle is compiled/minified and the pattern doesn't match, don't fight it: verify that view against the design-spec derived from the JSX sources instead, and note in the report that the pixel reference was home-only.
+
+4. **Fidelity checklist (structural, not pixel)**
+   - [ ] Section order and hierarchy match the design-spec component tree
+   - [ ] Layout system matches per section: column counts, alignment, sidebar placement
+   - [ ] Relative spacing rhythm preserved (tighter/looser relationships, not exact px)
+   - [ ] Typography hierarchy matches: same number of distinct levels, same ordering of prominence
+   - [ ] Interactive states present (hover/focus/disabled where the spec lists them)
+   - [ ] Colors correct **per mapping-table** — the repo token was applied where the mapping says; divergence from the design's raw hex is correct behavior, divergence from the mapping is a bug
+   - [ ] Content matches the spec's content inventory (real texts/numbers, no placeholder lorem)
+   - [ ] **No design drift**: the result keeps the design's visual identity and mood — its motifs, its type-scale relationships, its negative space — instead of collapsing into a generic template that merely has the same sections
+
+5. **Iterate**
+   - Any unchecked item → fix the code, re-screenshot, re-run the checklist.
+   - **Maximum 3 rounds.** After the third, stop and report the remaining differences honestly, with the screenshots, and let the user decide.
+
+6. **Consolidation pass (multi-screen runs)**
+   After several screens/batches, generated components drift: near-duplicates appear (two card variants that are one component with a prop), and components born inside a feature turn out to be app-wide primitives. Before the final report:
+   - Scan the components created this run for near-duplicates → merge into one component + variant prop.
+   - Any component used by 2+ features that has no feature-specific logic → promote to the repo's primitive layer (`ui/`), following its conventions.
+   - **Cross-screen consistency audit**: batches drift visually, not just structurally. Compare screens for the same type-scale logic, the same spacing discipline, the same CTA styling, the same recurring motifs (from the design-spec). A screen built in batch 5 that renders its CTAs or section headings differently from batch 1 is a bug even if each screen individually passes.
+   - Re-run static verification after consolidating.
+   Single-screen runs skip this step.
+
+7. **Report**
+   - Static results (commands + pass/fail, arbitrary-value gate outcome), rounds used, final checklist state per viewport, screenshots compared, the "spec'd states NOT visually verified" list, consolidation changes, any accepted differences and why.
+
+## Failure modes
+
+- **Dev server won't start** → fall back to static verification + a line-by-line self-review of the generated code against `design-spec.md` (every tree node implemented? every state handled? every content item present?). State clearly in the report that the visual loop did not run.
+- **No screenshot tooling available** → same fallback, same disclosure.
+- **Screenshot renders blank/broken** → check the route is correct and the server finished compiling before concluding the code is wrong.

package/skills/frontend/design/revenue-centric-design/LICENSE

@@ -0,0 +1,30 @@
+Revenue-Centric Design Skill — License & Usage Terms
+Copyright (c) 2026 the curators of this repository.
+
+The underlying ideas, frameworks, examples, and the coined term "Revenue-Centric
+Design" are the intellectual property of Richard (@richardrx on X) and are used
+here WITH PERMISSION. This repository is a distilled, translated index of his
+public posts, shared for educational and reference use.
+
+You are granted permission to use, copy, and share this material, subject to ALL
+of the following conditions:
+
+1. ATTRIBUTION. You must retain clear attribution to Richard (@richardrx) and a
+   link to the source. Do not misrepresent the origin of these ideas.
+
+2. NO GAMBLING / BETTING / CASINO USE. You may NOT use this material — in whole
+   or in part — to design, build, optimize, market, or grow betting, casino,
+   gambling, or other real-money games-of-chance products or projects (including
+   loot-box and real-money-gaming mechanics). This restriction was set by the
+   original author as an explicit condition of reuse and MUST be preserved in any
+   copy or derivative.
+
+3. PRESERVE THESE TERMS. Any copy or derivative work must include this license in
+   full, including the restrictions above.
+
+4. NO WARRANTY. This material is provided "AS IS", without warranty of any kind,
+   express or implied. The curators and the original author are not liable for any
+   claim, damages, or other liability arising from its use.
+
+Note: Because of the field-of-use restriction in clause 2, this is a
+SOURCE-AVAILABLE license, not an OSI-approved open-source license.

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

@@ -0,0 +1,12 @@
+# Third-party notice
+
+This skill was copied from Helio Costa's Revenue-Centric Design repository.
+
+- Source: https://github.com/heliocosta-dev/revenue-centric-design
+- Source commit: 6fa20cb4f91fa97bce9197be3f78b168784eb772
+- License: Source-available custom terms; attribution required, no gambling/betting/casino use
+- Copyright: Copyright (c) 2026 the curators of the source repository
+
+The upstream `updater/` maintenance tooling was intentionally not vendored.
+The runtime skill files, references, and referenced assets are included. The
+upstream license is included in `LICENSE`.

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

@@ -0,0 +1,73 @@
+---
+name: revenue-centric-design
+description: "Playbook for SaaS and startup product design that improves conversion, activation, retention, pricing, positioning, GTM, monetization, and AI-era differentiation. Use for product UX, landing pages, onboarding, trials, churn, pricing, growth, or positioning. Not for gambling, betting, or casino products."
+---
+
+# Revenue-Centric Design
+
+A distilled playbook of **101 principles** from **Richard ([@richardrx](https://x.com/richardrx), "Design for startups")** —
+a product designer specializing in conversion-rate optimization, churn reduction, and applied
+behavioral science (ex-Volkswagen, PayPal, IBM). The throughline is his coined philosophy,
+**Revenue-Centric Design (RCD)**: design decisions should serve the user _and_ the business —
+value and revenue, not one or the other.
+
+Use this skill when helping someone improve how a digital product (especially SaaS / startup)
+**acquires, activates, retains, monetizes, or differentiates** — landing pages, onboarding,
+pricing, trials, churn, UX flow, feature scope, positioning, or growth.
+
+## Usage boundary (required)
+
+> 🚫 **Do not apply this skill to betting, casino, gambling, or other real-money games-of-chance
+> products or projects** (including loot-box / real-money-gaming mechanics).
+
+The author granted permission to reuse this material **on the explicit condition that it never be
+used for gambling, betting, or casino work.** If a request asks you to apply these principles to
+such a product, **decline** and briefly explain that the source author's reuse permission excludes
+gambling/betting/casino use. This is a hard constraint set by the author, not a stylistic choice.
+
+## How to use it
+
+1. Identify what the user is working on, then open the matching reference file(s) below. Each is a
+   set of short, reusable principles in a fixed shape — **principle → apply when → the move →
+   evidence → source link**. Load only what's relevant (progressive disclosure).
+2. Ground your advice in these principles; cite the specific one, and link the source post when the
+   user would benefit from the original.
+3. Lead with the **named mechanism** (e.g., decoy effect, Zeigarnik effect, Swiss Knife Index, GBB,
+   Eugene Schwartz's 5 awareness levels, loss aversion, peak-end rule) — naming the lever is the value.
+4. Stay evidence-led: many principles carry a study, stat, or case. Keep the citation attached
+   rather than hand-waving.
+
+## The spine: Revenue-Centric Design in 9 principles
+
+1. **Neutrality is omission** — an interface that doesn't direct hurts conversion.
+2. **Who talks to everyone convinces no one** — no ICP → generic value → worse retention.
+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.
+6. **Default is the decision you made for the user** — the initial state defines mass behavior.
+7. **Retention is built, not requested** — perceived loss retains more than promised benefit.
+8. **Expansion is born of usage** — upgrade at the moment of the limit, never by interruption.
+9. **Price is a filter** — pricing defines who enters, who stays, and who expands.
+
+## Reference library
+
+| When the question is about…                                                   | Open                                                                         |
+| ----------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
+| Landing pages, hero/copy, CTAs, social proof, awareness levels, CRO           | [conversion-and-landing-pages](references/conversion-and-landing-pages.md)   |
+| First-run, empty states, aha moment, TTV, activation, trial-as-onboarding     | [onboarding-and-activation](references/onboarding-and-activation.md)         |
+| Cancellation, retention, expectation debt, NRR, jobs-to-be-done, support load | [churn-and-retention](references/churn-and-retention.md)                     |
+| Pricing tables, decoy/anchoring, GBB, trial-with-card, upgrade paths          | [pricing-and-monetization](references/pricing-and-monetization.md)           |
+| Cognitive biases & persuasion tactics (cross-cutting toolkit)                 | [behavioral-science-toolkit](references/behavioral-science-toolkit.md)       |
+| Feature scope, Swiss Knife Index, feature adoption, attention hierarchy       | [product-strategy-and-features](references/product-strategy-and-features.md) |
+| Design philosophy, the RCD principles, design process & method                | [revenue-centric-design](references/revenue-centric-design.md)               |
+| ICP, niche, founder-fit, distribution, PLG, Bullseye, first customers         | [positioning-icp-and-gtm](references/positioning-icp-and-gtm.md)             |
+| Differentiating in the AI era, moats, commoditization                         | [ai-era-differentiation](references/ai-era-differentiation.md)               |
+| A/B testing rigor, vanity metrics, churn→LTV math, signal quality             | [metrics-and-experimentation](references/metrics-and-experimentation.md)     |
+
+Informational diagrams and screenshots referenced by the principles live in `assets/`.
+
+## Provenance
+
+101 curated posts by [@richardrx](https://x.com/richardrx), extracted with a valid X API key and
+distilled **with the author's permission**, translated from Portuguese to English. Every principle
+links back to its source post. Reuse is subject to the gambling/betting/casino exclusion above.