wizz-method 1.4.0 → 1.5.0

package/src/skills-lib/decision-maker/references/output-format.md

@@ -0,0 +1,161 @@
+# Output format — the five deliverables
+
+Load this file when the brief is complete (spatial logic locked) or when the user runs `/output`. Contains the exact copy-paste templates for the five output sections: Copywriter prompt, 3D/Illustration prompt, Design prompt, Developer prompt, and the GitHub + Vercel launch guide, plus the closing message.
+
+## Output format
+
+When the brief is complete (or when the user runs `/output`), produce exactly five sections in this order. Each prompt in a code block, copy-paste ready.
+
+If any decisions, references, or logics are missing, tell the user what's missing and walk them back through that section.
+
+---
+
+### Section 1 — Prompt for Copywriter AI
+
+```
+You are a senior brand copywriter. Write the copy for a website with this brief:
+
+BRIEF:
+- Feeling: [decision 1]
+- Audience: [audience]
+- Anti-audience: [anti-audience]
+- Hero object: [decision 3]
+- Job: [decision 4]
+- Three-second memory: [decision 6]
+
+TONE: Match the feeling. The visitor should not read — they should feel. One sentence per screen. No filler. No hedging. Banned words: modern, clean, minimal, premium, professional, elegant.
+
+OUTPUT:
+1. Hero headline (max 4 words)
+2. Hero subheadline (max 12 words)
+3. Section headlines for: [list cut-survivor sections from decision 5]
+4. Microcopy for primary CTA (max 2 words)
+5. Footer line (one sentence)
+
+Return as JSON.
+```
+
+### Section 2 — Prompt for 3D / Illustration AI
+
+```
+Generate a hero visual for a website with this direction:
+
+HERO OBJECT: [decision 3]
+FEELING: [decision 1]
+COLOR LOGIC: [color logic]
+SPATIAL LOGIC: [spatial logic]
+
+STYLE NOTES:
+- The object should be oversized, slightly tilted, centered.
+- Background: dominant color floods the entire frame.
+- Lighting: cinematic, soft rim light, slight depth of field.
+- Resolution: 4K, transparent background.
+- No humans, no environments, no context — just the object in atmosphere.
+
+REFERENCE AESTHETIC: [pull 2–3 visual feeling references from bucket 1]
+
+Tool suggestion: Midjourney for the hero, GPT Image / Recraft for variants, Remove.bg for cleanup, Squoosh for WebP compression under 2MB.
+```
+
+### Section 3 — Prompt for Design AI (Figma / layout spec)
+
+```
+Design a landing page layout with this spec:
+
+VISUAL DECISIONS:
+- Feeling: [decision 1]
+- Hero object: [decision 3]
+- Job: [decision 4]
+
+STYLE LOGICS:
+- Color: [color logic]
+- Type: [type logic]
+- Spatial: [spatial logic]
+
+SECTIONS (in order, top to bottom):
+[list cut-survivor sections from decision 5]
+
+LAYOUT RULES:
+- Hero: hero object dead center, oversized, slightly tilted. Copy pushed to one edge. Nav at top edge. Awards/badges at bottom corner.
+- Every section follows the spatial logic above.
+- Mobile-first responsive. Stack all grids to single column under 768px.
+
+DELIVERABLE: A Figma frame or layout spec showing the hero + 2–3 below-fold sections.
+```
+
+### Section 4 — Prompt for Developer AI (Claude Code / Cursor)
+
+```
+Build a premium animated landing page with this spec:
+
+ASSETS:
+- /assets/images/hero.webp (hero object — see 3D output)
+- /assets/copy.json (see copywriter output)
+
+STYLE TOKENS (CSS custom properties):
+- Color logic: [color logic — translate to --color-primary, --color-accent, --color-bg]
+- Type logic: [type logic — translate to --font-display, --font-body with size scale]
+- Spatial logic: [spatial logic — translate to layout grid rules]
+
+FEATURES TO BUILD:
+- Hero: GSAP spring entrance for the hero object. Cursor-reactive — hero object subtly follows mouse position. Staggered word reveal on headline (60ms).
+- [If product has variants:] Smooth state-change between variants — background color, accent color, and hero object all transition together.
+- Magnetic CTA: button slightly follows cursor within 40px on hover.
+- Smooth scroll indicator at bottom of hero.
+- Scroll-triggered fade+slide-up animations on sections (120ms stagger).
+- Mobile-first responsive. Respect prefers-reduced-motion.
+
+TECH STACK:
+- Plain HTML/CSS/JS or Next.js (your choice).
+- GSAP for animations.
+- Lighthouse targets: Performance 90+, AA contrast, no layout shift, font preloaded, images lazy-loaded WebP.
+
+OUTPUT: index.html, style.css, animations.js (or component files if Next.js).
+```
+
+### Section 5 — Launch with GitHub + Vercel
+
+```
+LAUNCH GUIDE
+
+1. INITIALIZE GIT
+   Open the project folder in Terminal.
+   - git init
+   - git add .
+   - git commit -m "Initial commit"
+
+2. CREATE GITHUB REPO
+   - Go to github.com → New repository.
+   - Name it [project-slug]. Private.
+   - Skip README / .gitignore (you already have files).
+   - On the next page, copy the two commands under "push an existing repository from the command line."
+   - Paste them in Terminal. Your code is now on GitHub.
+
+3. DEPLOY TO VERCEL
+   - Go to vercel.com, sign in with GitHub.
+   - Click "Add New" → "Project".
+   - Select your repo.
+   - Vercel auto-detects the framework (use "Other" for plain HTML).
+   - Leave defaults. Click "Deploy".
+   - 30–60 seconds later you have a live URL: [project].vercel.app.
+
+4. CUSTOM DOMAIN (optional)
+   - In Vercel → Settings → Domains.
+   - Add your domain. Vercel shows DNS records.
+   - Go to your registrar (Namecheap, GoDaddy, Cloudflare) and paste them.
+   - 5–30 minutes for DNS to propagate. Live on your domain.
+
+5. PUSH UPDATES
+   - Any time you make changes: git add . && git commit -m "update" && git push
+   - Vercel auto-deploys every push.
+
+THE SITE IS LIVE.
+```
+
+After outputting all five sections, close with:
+> That's everything. Five outputs, ready to use.
+>
+> Hand sections 1–4 to the matching AI tools (Claude, Midjourney, Figma plugin, Cursor or Claude Code). Then run the launch guide.
+>
+> If you want to redo any part of the brief, type `/redo [section]` — for example `/redo decision 3` or `/redo color logic`.
+

package/src/skills-lib/decision-maker/references/references-and-extraction.md

@@ -0,0 +1,129 @@
+# Reference buckets + extraction logics — full script
+
+Load this file once the six decisions are locked (after the Decision 6 summary message). Contains the exact scripted flow for the three reference buckets (feeling/structure/detail) and the three extraction logics (color/type/spatial), including push-back copy and worked examples.
+
+## References
+
+Three buckets, one at a time. Always auto-advance after each.
+
+### Bucket 1 — Feeling references
+
+> **Bucket 1 of 3 — Feeling references.**
+>
+> These are almost never websites. Film stills, photography, fashion editorial, fine art, architecture, packaging — the visual world that matches your *feeling* (Decision 1: [their feeling]).
+>
+> Examples for "intoxicated by the fruit": Wong Kar-wai film stills (saturated color flooding the frame), Carl Kleiner's hyperreal fruit photography (oversized, surreal, studio-lit), Vogue Italia editorials shot under colored gels, hyperreal CGI on Instagram like @omar.aqil.
+>
+> Where to look: **Are.na** (best moodboard tool on the internet), **ShotDeck** (film stills library), **Cinema Palettes** on Instagram, magazine archives — Apartamento, Cabana, Toilet Paper, The Gentlewoman.
+>
+> Give me 3–5 specific references. For each one, tell me in one sentence what *specifically* is working. Not "I like it" — something like *"the headline takes 70% of the screen, everything else is tiny — extreme hierarchy."*
+>
+> What's in your feeling bucket?
+
+If they answer "I like it" or vague reactions, push:
+> "I like it" is decoration, not a reference. What's the *decision* the image is making? What rule could you steal from it? Try again.
+
+Once they have 3–5 with annotations:
+> Locked. Feeling bucket loaded.
+>
+> **Bucket 2 of 3 — Structural references.** Now websites — but for *layout logic*, not style. How they handle hierarchy, negative space, hero treatment.
+>
+> Example from the soda project: Diesel.com and Off-White product pages for oversized hero with one object holding 80% of the screen. Aesop for spatial restraint — each section treated like a museum vitrine. A few Awwwards Site of the Day winners for the smooth product-variant switching pattern.
+>
+> Where to look: **Awwwards** (specifically the Site of the Day *archive* — the homepage shows what's trending, the archive shows what's lasting), **Godly.website**, **Lapa.ninja**, **Land-book**, **Httpster**. Skip Behance and Dribbble trending feeds — generic factory.
+>
+> Give me 3–5 sites with one sentence each on what structural logic you're stealing.
+
+### Bucket 2 — Structural references
+
+Same pushback rule as Bucket 1 if they're vague.
+
+Once locked:
+> Locked. Structure bucket loaded.
+>
+> **Bucket 3 of 3 — Detail references.** The texture layer — button states, hover effects, scroll behavior, type pairings, cursor changes, transitions, micro-interactions. The stuff that makes a site feel *alive*.
+>
+> Example from the soda project: Stripe's pricing page for the fluid color-shift between states (we used the same pattern for flavor-switching). Apple product reveals for the slow, weighted hero entrance. Cofolios designer portfolios for cursor-reactive 3D objects.
+>
+> Where to look: **Cofolios**, **Read.cv** (personal sites of working designers — usually sharper than agency work), screen-recorded Reels from motion designers, "UI details" accounts on Twitter that post one micro-interaction at a time.
+>
+> Give me 3–5 references with one sentence each on what detail you're stealing.
+
+### Bucket 3 — Detail references
+
+Once locked:
+> Locked. All three buckets done.
+>
+> **Next: extraction.** We turn 15-ish references into 3 style logics — color, type, spatial. This is the part that becomes the actual prompt for downstream AI.
+
+Then proceed to extraction.
+
+---
+
+## Extraction (the three logics)
+
+### Color logic
+
+> **Logic 1 of 3 — Color logic.**
+>
+> Imagine the 5–7 strongest references laid side by side. Don't look for what's beautiful — look for what's *common*. The relationship, not the specific colors.
+>
+> Weak: "Green and red, with some accents."
+> Sharp: "One saturated color floods the entire screen — background, particles, ambient glow. Paired with one cinematic accent: the natural color of the fruit. When the flavor changes, the whole color world changes with it."
+>
+> Other examples: "Three neutrals and zero color." "High-contrast black and white, one image carries all the warmth." "Off-white background, single saturated color on CTAs only."
+>
+> What's your color *relationship*?
+
+If they give hex codes or specific color names:
+> That's a palette, not a logic. The logic is the *rule* — which color is dominant, which is accent, when does each appear? Try again as a sentence about the relationship.
+
+Once locked:
+> Locked. Color logic: [their answer].
+>
+> **Logic 2 of 3 — Typography logic.** The contrast, not the fonts.
+>
+> Weak: "A bold display font with a clean sans-serif for body."
+> Sharp: "One script display used at extreme scale for emotional copy. One tiny sans-serif for everything functional. Nothing in between."
+>
+> Other examples: "One sans-serif used at four sizes, no other family." "Editorial serif paired with a system mono — serif for ideas, mono for facts." "Display type so large it crops at the edges of the screen."
+>
+> What's your typographic *contrast*?
+
+### Typography logic
+
+Once locked:
+> Locked. Type logic: [their answer].
+>
+> **Logic 3 of 3 — Spatial logic.** How the screen is organized.
+>
+> Weak: "The product is the focal point with supporting elements around it."
+> Sharp: "The can is dead center, oversized, slightly tilted. Everything else orbits it — fruit suspended around it, copy pushed to the edges, UI in the corners. The center is sacred. The edges are utilitarian."
+>
+> Other examples: "Dense grid, packed information, zero white space." "Asymmetric — content lives on the left half, right is image or empty." "Stacked center, every section is one column, no sidebars ever."
+>
+> What's your spatial *point of view*?
+
+### Spatial logic
+
+Once locked, show the full brief and auto-advance to output:
+> Locked. Spatial logic: [their answer].
+>
+> **That's the full brief.** Here's everything you've decided:
+>
+> *Feeling: [decision 1]*
+> *Audience: [audience]. Not for: [anti-audience]*
+> *Hero object: [decision 3]*
+> *Job: [decision 4]*
+> *Cut: [decision 5]*
+> *Three-second memory: [decision 6]*
+> *Color logic: [color]*
+> *Type logic: [type]*
+> *Spatial logic: [spatial]*
+>
+> Nine sentences. That's the prompt.
+>
+> Compiling your four AI prompts + launch guide now…
+
+Then immediately output all five sections from **Output format** below.
+

package/src/skills-lib/decision-maker/references/six-decisions.md

@@ -0,0 +1,122 @@
+# Six decisions — full script
+
+Load this file when the opening message has been sent and the user has answered with their project. Contains the exact scripted flow for Decisions 1-6: questions, push-back copy for weak answers, worked examples, and the lock/preview/next-question pattern for each decision.
+
+## The six decisions
+
+### Decision 1 — The feeling
+
+Ask:
+> What does the visitor need to feel in the first three seconds?
+>
+> Heads up — banned words: modern, clean, minimal, professional, sleek, premium, beautiful, elegant. They describe every site, so they produce every site.
+>
+> Push for something specific and a little uncomfortable. Like *"intoxicated by the fruit"* (a soda brand we worked on) or *"watched by something invisible"* (a security SaaS) or *"slowed down on purpose"* (a luxury watch site).
+>
+> What's the feeling?
+
+If they answer with a banned word or generic abstraction, push back:
+> "[Their word]" describes every site in this category. Push harder. Try uncomfortable, sensory, narrow. What does this product actually *do* to the person who uses it? Translate that into a feeling.
+
+Once they give a sharp answer:
+> Locked. Decision 1: [their answer].
+>
+> Next up: audience. Two halves — who it's for, and just as important, who it's *not* for.
+>
+> Who's this site for? Picture one real human, not a demographic. Example: not "health-conscious millennials" — but "the person who picks a drink the way they'd pick a fragrance." Or for a B2B SaaS: not "mid-market CFOs" — but "the finance lead who's tired of explaining the same spreadsheet every Monday."
+>
+> Who's your one person?
+
+### Decision 2 — Audience and anti-audience
+
+Step 1 — the audience. If they give a generic demographic, push back:
+> That fits ten million people. You can't design for a demographic — only for a person. Picture one human. What do they do for work? What do they buy? What do they reject? Try again.
+
+Once the audience is locked, ask the anti-audience:
+> Got it. Now the harder half — who is this site *not* for?
+>
+> Example from the soda project: "Not for anyone who reads the back of the can before they buy it." That one sentence killed half the site — no nutrition facts above the fold, no ingredient comparisons, no badges.
+>
+> Who's your anti-audience?
+
+Once both are locked:
+> Locked. Decision 2: For [audience]. Not for [anti-audience].
+>
+> Next: the hero object. The one thing your site shows on the first screen.
+>
+> If your site could show only one thing on the hero, what is it? Most founders say "the product" — that's usually wrong. Example: for our soda site the hero wasn't the can, it was the *fruit* flying around it. For a fintech we worked on, it wasn't the dashboard — it was a single number that captured what changed for the user.
+>
+> What's your one thing?
+
+### Decision 3 — The hero object
+
+If they list multiple things, push:
+> One thing. If you can't pick one, the visitor won't know where to look — and a visitor who doesn't know where to look leaves. Pick the one thing that, if everything else disappeared, would still tell the story.
+
+Once locked:
+> Locked. Decision 3: [their answer].
+>
+> Next: the one-sentence job. What this site *does* in one verb.
+>
+> Not "convert and inform" — that's two jobs done badly. One verb. Examples: *seduce* (a perfume site), *convince* (a B2B sales tool), *intimidate* (a security firm targeting enterprise), *disarm* (a tax product for anxious users), *invite* (a community-led startup).
+>
+> What's your verb?
+
+### Decision 4 — The one-sentence job
+
+If they give a compound answer:
+> That's two jobs and both will be done badly. Pick one verb. The whole site will be measured against it — pacing, weight, copy density, motion. One.
+
+Once locked:
+> Locked. Decision 4: [verb].
+>
+> Next: the cut. This one needs you to look at competitors.
+>
+> Pull up three competitor sites right now. List every section they have — hero, features, testimonials, logo wall, pricing, FAQ, blog teasers, footer columns, the whole catalog.
+>
+> Then tell me: which 60–80% of those sections are you cutting?
+>
+> Example from the soda project: we cut lifestyle photography, ice/condensation graphics, ingredient charts, "find us in stores" maps, social walls, and an 8-column footer. What survived: hero, flavor selector, ingredients (below fold), taste, sustainability, reviews, contact. Seven sections, every one louder because the noise around it was gone.
+>
+> Go look at your three competitors. What are you cutting? (Take your time — come back when you have the list.)
+
+### Decision 5 — The cut
+
+If they answer without actually looking at competitors, send them back:
+> Go look first. The cut has to be grounded in real competitor analysis, not guesses. Pull up three competitor sites, list their sections, then come back.
+
+Once they've done it and given a real list:
+> Locked. Decision 5: We're cutting [list].
+>
+> Last decision. The three-second test.
+>
+> Imagine someone lands on your site, scrolls nothing, and closes the tab after three seconds. What would they remember? Be specific — an object, a word, a feeling. Something they could describe to a friend in one sentence.
+>
+> Weak answer: "It looked nice. Green and red. A soda brand."
+> Sharp answer: "A floating green can with cherries flying around it. The word PURE in giant letters. It felt like a movie, not an ad."
+>
+> What's your three-second memory?
+
+### Decision 6 — The three-second test
+
+If they say "looked nice" or "professional" or "modern," push hard:
+> That's a failure state. "Looked nice" is what generic looks like. The three-second answer has to be a specific image, a specific phrase, a specific feeling. If your three-second memory is "looked nice," you built a brochure. What would they actually remember? Be specific.
+
+Once locked, do the decision-layer summary:
+> Locked. Decision 6: [their answer].
+>
+> That's the decision layer. Here's your brief so far:
+>
+> 1. **Feeling:** [decision 1]
+> 2. **Audience:** [audience]. **Not for:** [anti-audience]
+> 3. **Hero object:** [decision 3]
+> 4. **Job:** [decision 4]
+> 5. **Cut:** [decision 5]
+> 6. **Three-second memory:** [decision 6]
+>
+> Six sentences. That's the foundation.
+>
+> **Next: references.** We're building three reference buckets — feeling, structure, detail — to prove your decisions can take a visual form. Ready? I'll walk you through one bucket at a time.
+
+Then immediately proceed to references.
+

package/src/skills-lib/decision-maker/references/wizz-method-handoff.md

@@ -0,0 +1,22 @@
+# Wizz Method handoff
+
+Load this file when a `_wizz/` folder exists in the project or when an agent like `wizz-designer` invoked this skill. Explains how to dispatch the four brief sections to executor agents (wizz-copy, wizz-designer, wizz-agent-dev / wizz-quick-dev) instead of just emitting copy-paste prompts.
+
+## Wizz Method handoff (when running inside the method)
+
+If this skill is running inside a Wizz Method project (a `_wizz/` folder exists, or an agent like `wizz-designer` invoked you), don't stop at copy-paste prompts. The four prompts map directly onto the executor agents — offer to dispatch them instead of (or in addition to) emitting the blocks:
+
+| Brief section | Hand off to | Via |
+|---|---|---|
+| Section 1 — Copywriter | `wizz-copy` | the `Skill` tool, passing the copy prompt as the brief |
+| Section 2 — 3D / Illustration | `wizz-designer` | routes onward to `motion-3d-director` |
+| Section 3 — Design (layout spec) | `wizz-designer` | routes onward to `ui-ux-pro-max` / `premium-landing-ui-researcher` |
+| Section 4 — Developer | `wizz-agent-dev` (`wizz-quick-dev` for small builds) | builds from the dev prompt + assets |
+
+Recommended close inside the method:
+> Brief locked. Want me to dispatch it? I can send the copy to **wizz-copy**, the visual direction to **wizz-designer**, and the build to **wizz-agent-dev** — or **wizz-quick-dev** for a small build — in that order. Or run the launch guide yourself.
+>
+> For the engineering setup (folder structure, stack, patterns, dev checklist), run **`/inicio-de-projeto`** — this brief is the visual direction; that one is the technical foundation.
+
+Outside the method (standalone), keep the original behavior: emit the five copy-paste sections and the launch guide.
+

package/src/skills-lib/desktop-security/SKILL.md

@@ -15,11 +15,32 @@ description: >
 - contextIsolation: true (obrigatório)
 - sandbox: true quando possível
 - webSecurity: false nunca em produção
+- Nunca carregue conteúdo remoto numa janela com acesso a APIs privilegiadas; conteúdo remoto = sandbox + sem preload sensível
+- Mantenha o Electron atualizado (patches de Chromium/Node chegam por release do Electron)
+
+### Navegação e janelas
+- Bloqueie navegação para fora do app: handler em `will-navigate` que cancela URLs fora da allowlist
+- `setWindowOpenHandler`: negue por padrão (`{ action: "deny" }`), abra externo só o que for aprovado
+- `shell.openExternal` só com URL validada (esquema `https:` e host esperado), nunca com input cru do renderer
 
 ### IPC (comunicação renderer <> main)
-- Valide e sanitize todos os dados vindos do renderer
-- Exponha apenas as funções necessárias via contextBridge
+- Valide e sanitize todos os dados vindos do renderer (o renderer é território hostil: trate como input de usuário)
+- Exponha apenas as funções necessárias via contextBridge, cada uma com assinatura fixa
 - Nunca exponha ipcRenderer diretamente ao renderer
+- Em `ipcMain.handle`, valide tipo e tamanho dos argumentos; se houver múltiplas janelas, cheque `event.senderFrame.url` contra o esperado
+
+```ts
+// preload.ts: superfície mínima, sem repassar ipcRenderer
+contextBridge.exposeInMainWorld("api", {
+  saveNote: (text: string) => ipcRenderer.invoke("notes:save", text),
+})
+
+// main.ts: valida antes de agir
+ipcMain.handle("notes:save", (event, text) => {
+  if (typeof text !== "string" || text.length > 10_000) throw new Error("input inválido")
+  // ...
+})
+```
 
 ### Atualizações automáticas
 - Assine o pacote de atualização com certificado de código (code signing)
@@ -29,8 +50,9 @@ description: >
 ## Armazenamento local
 
 ### O que armazenar localmente
-- Tokens de sessão: keychain do OS (electron-keytar), nunca localStorage
-- Dados do usuário: criptografados com chave derivada da senha do OS
+- Tokens de sessão: `safeStorage` do Electron (usa Keychain no macOS, DPAPI no Windows, libsecret no Linux), nunca localStorage
+  - `safeStorage.encryptString(token)` antes de gravar em disco; `keytar` está arquivado, não use em projeto novo
+- Dados sensíveis do usuário: criptografados via `safeStorage` ou AES-256-GCM com chave guardada no keychain do OS
 
 ### O que nunca armazenar localmente
 - Senhas em texto plano
@@ -41,3 +63,12 @@ description: >
 - Code signing obrigatório (Windows: Authenticode, macOS: Apple Developer ID)
 - Notarização no macOS para distribuição fora da App Store
 - Auto-update com verificação de integridade antes de executar
+
+## Checklist rápido (antes de empacotar)
+- [ ] `contextIsolation: true`, `nodeIntegration: false`, `sandbox: true` onde possível?
+- [ ] Nenhuma janela privilegiada carrega URL remota?
+- [ ] `will-navigate` e `setWindowOpenHandler` restringem navegação?
+- [ ] Todo handler de `ipcMain` valida os argumentos?
+- [ ] Tokens em `safeStorage`/keychain, nada sensível em localStorage?
+- [ ] Build assinado (e notarizado no macOS)? Auto-update valida assinatura?
+- [ ] Versão do Electron atual (sem CVE aberta)?

package/src/skills-lib/find-skills/SKILL.md

@@ -159,17 +159,20 @@ Cada entrada traz `id`, `when` e o bloco `server` (command/args/env) pronto. Pre
 # Sintaxe geral (Claude Code):
 claude mcp add <id> [-e VAR=valor ...] -- <command> [args...]
 
-# Exemplos comuns:
-claude mcp add context7 -- npx -y @upstash/context7-mcp
-claude mcp add playwright -- npx -y @playwright/mcp@latest
-claude mcp add magic -e API_KEY=$MAGIC_API_KEY -- npx -y @21st-dev/magic
-claude mcp add supabase -e SUPABASE_ACCESS_TOKEN=$SUPABASE_ACCESS_TOKEN -- npx -y @supabase/mcp-server-supabase@latest
+# Exemplos comuns (SEMPRE pin de versão fixa, nunca @latest — supply chain,
+# mesma convenção do skills-registry.yaml; atualizar conscientemente quando
+# necessário):
+claude mcp add context7 -- npx -y @upstash/context7-mcp@3.2.2
+claude mcp add exa -e EXA_API_KEY=$EXA_API_KEY -- npx -y exa-mcp-server@3.2.1
+claude mcp add magic -e API_KEY=$MAGIC_API_KEY -- npx -y @21st-dev/magic@0.1.0
+claude mcp add supabase -e SUPABASE_ACCESS_TOKEN=$SUPABASE_ACCESS_TOKEN -- npx -y @supabase/mcp-server-supabase@0.8.2 --read-only
 ```
+Versões acima são as pinadas hoje em `skills-registry.yaml` — confira lá antes de copiar, pode ter mudado. Não sugira o MCP do Playwright: browser é sempre via CLI `agent-browser` neste framework, nunca Playwright.
 
 Ou edite o `.mcp.json` do projeto (merge aditivo, nunca apague servers existentes):
 
 ```json
-{ "mcpServers": { "context7": { "command": "npx", "args": ["-y", "@upstash/context7-mcp"] } } }
+{ "mcpServers": { "context7": { "command": "npx", "args": ["-y", "@upstash/context7-mcp@3.2.2"] } } }
 ```
 
 ### Passo 4: Secrets