nachoorg/vercel-landing-pages-skill

Landing pages na Vercel

Converta um pedido não técnico em um site rápido e organizado, e publique-o na Vercel com um circuito repetível. O usuário diz o que quer; você cuida do stack, do código, das verificações e de preparar cada deploy. O usuário não é necessariamente desenvolvedor: fale simples, pergunte pouco e nunca deixe um site pela metade. Responda no idioma do usuário (padrão: espanhol rioplatense).

0. Onde cada coisa é executada (regra de ouro)

Há três lugares para executar comandos e cada um tem um papel fixo:

Local	Para que	Nunca para
Terminal do usuário (Mac/PC dele, com sua sessão Vercel)	vercel login, link, deploy, rollback, promote, domains, env add — tudo que mexe com vercel.com ou credenciais	—
Terminal local do Cowork (device_bash, VM sobre a pasta conectada)	ler e editar arquivos, git add/commit, verificações prévias, anotar o histórico	vercel login nem deploys
Terminal na nuvem do Cowork (Bash)	capturas de tela com Playwright, ferramentas que não estão na VM local	mexer nos arquivos do usuário diretamente

Por quê: cada chamada a device_bash é um sandbox novo e efêmero — um processo em segundo plano (como vercel login aguardando aprovação) morre ao final do comando e parece "travado"; além disso, o proxy da organização pode bloquear vercel.com (403 from proxy after CONNECT, fetch failed). O terminal do usuário já tem seu login e sua rede. Não peça nem escreva tokens ou credenciais; o login é feito pelo usuário.

Como passar comandos para o usuário:

• Um bloco de código, um comando por linha, começando com cd para a pasta.
• Sem comentários # no final da linha (zsh os passa como argumentos: Error: Can't deploy more than one path). As explicações vão fora do bloco.
• Sempre --yes para que não haja prompts interativos.
• Peça para ele colar a saída completa; daí você tira a URL e os erros.
• Após cada deploy, anote você o histórico (veja seção 5) com device_bash.

Uso do computador: macOS só permite clicar em terminais e editores, não escrever. Não peça controle do Terminal para digitar comandos; não funciona.

1. Detecte a situação primeiro

• Peça acesso à pasta com device_request_folder_access (ex.: ~/Downloads). Se o projeto chegou como .tar.gz/.zip, descompacte-o ao lado com device_bash.
• Existe .vercel/project.json → ATUALIZAÇÃO (seção 5). O projeto já está vinculado.
• Há código mas não .vercel/ → PRIMEIRO DEPLOY de código existente (seções 3–5).
• Vazia / nova → PROJETO NOVO (seções 2–5).
• Pede domínio próprio → seção 6.

Git em uma pasta conectada: git precisa excluir seus arquivos .lock; sem permissão de exclusão falha com unable to unlink ... Operation not permitted. Peça uma única vez device_request_delete_permission sobre a pasta raiz explicando que é para os arquivos temporários do git (esclareça que habilita exclusão em toda essa pasta durante a sessão). Se ele recusar, os commits são feitos pelo usuário em seu terminal. Configure autor em cada comando: git -c user.name=... -c user.email=... commit.

Verifique uma vez no terminal do usuário: node -v (≥18), git --version, npx vercel whoami. Se whoami disser Logged out, o usuário executa npx vercel login ali mesmo e aprova o código no navegador. Nunca escreva credenciais, tokens ou chaves fiscais por ele.

2. Pedido → especificação (curta)

Pegue o que ele já disse; pergunte só o que falta e bloqueia, em uma única mensagem, no máximo ~4 perguntas:

• Objetivo (vender, captar contatos, informar, inscrição) e uma única ação principal (CTA)
• Público e idioma dos textos
• Conteúdo: nome, seções, textos/fotos disponíveis (ou "invente textos de exemplo")
• Marca: cores, logo, estilo (ou "escolha você")
• Necessidades: formulário, botão de WhatsApp, analytics, domínio próprio

Devolva uma especificação de 5–10 linhas e avance salvo objeção. O conteúdo inventado vai marcado com TODO. Se te derem um telefone para WhatsApp, valide o formato internacional (Argentina celular: 549 + área + número, sem + nem 15) e avise se não fechar: um wa.me mal montado abre um chat inválido.

Se o pedido de estilo tiver tensões ("chique mas fuleira", cores de um clube em um bairro rival, marcas registradas), resolva-as você com critério, mostre o resultado e explique a decisão em duas linhas; não use escudos, nomes nem logos de terceiros.

3. Escolha o stack (o mais simples por padrão)

Necessidade	Stack	Por quê
Landing única / poucas páginas estáticas	HTML + CSS + JS mínimo, sem build	Zero dependências, nada que quebrar, deploys instantâneos. Padrão.
Muitas páginas, layout compartilhado, blog	Astro (saída estática)	Componentes + markdown, quase sem JS
Lógica de aplicação real, login, painéis	Next.js	Só se realmente necessário
Apenas um formulário de contato	Estático + função api/contact.js, ou serviço de formulários	Não justifica um framework

Detalhes, comandos, formulários e analytics: references/stacks.md.

Para sites estáticos, copie assets/static-starter/ como base (index, estilos, vercel.json, 404, robots, .gitignore) e adapte; não publique o design base sem alterações.

4. Construa direito (no Cowork)

Siga references/landing-guidelines.md. Inegociáveis:

• Mobile first, responsivo, o conteúdo principal funciona sem JS
• <title>, meta description, Open Graph, favicon, atributo lang
• Imagens comprimidas, com tamanho, loading="lazy" abaixo da dobra, alt
• Uma ação principal clara, repetida (acima e no final)
• Nada de segredos no repositório; as chaves vão com npx vercel env add (quem executa é o usuário)
• .vercelignore obrigatório com .env*, .deployments.log, .git, .gitignore, .vercelignore. Em um site estático sem build, a Vercel sobe tudo que está na pasta, e vercel link cria um .env.local com um token que ficaria público em /.env.local.
• .gitignore com .vercel, node_modules, .env*, .deployments.log

Edições com device_bash: sed -i ou um script curto em python de ler-modificar-escrever com assert de que cada substituição casa exatamente uma vez. Nunca redigitar o arquivo inteiro a partir da saída de uma ferramenta.

Verificações antes de qualquer deploy:

• predeploy-check.mjs sobre a pasta: corrija todos os ERROR, avalie os WARNING. Os scripts do skill vivem na nuvem; para executá-los na VM local, copie-os uma vez para $HOME/tools/ (fora de mnt/, invisível para o usuário) passando-os por device_bash em base64 ou com um heredoc.
• Astro/Next: npm run build tem que passar.
• Verificação visual na nuvem: device_stage_files dos arquivos do site → python3 -m http.server → Playwright com chromium.launch({executablePath: '/opt/pw-browsers/chromium-*/chrome-linux/chrome'}) (não executar playwright install) → capturas de página completa em 1366px e 390px → olhá-las com Read. As fontes do Google não carregam lá, então a tipografia fica aproximada. Envie para o usuário uma captura se a mudança for visual.

Cada mudança termina em um git commit -m "<o que mudou>". Os commits são o histórico de versões.

5. Deploy: sempre o mesmo circuito

Instale o script no projeto uma única vez: copie scripts/deploy.mjs do skill para a raiz do projeto como deploy.mjs (por device_bash, heredoc ou base64) e commite-o. É o que o usuário executa; funciona em macOS, Windows e Linux e não tem dependências.

O que faz node deploy.mjs: verifica o login → se faltar .vercel/project.json, cria/víncula o projeto (vercel link --yes --project <nome>) → avisa se há mudanças não commitadas → se houver package.json com build usa vercel pull + vercel build + vercel deploy --prebuilt, senão vercel deploy --yes direto → imprime a URL → adiciona uma linha a .deployments.log (data, destino, commit, URL). --dry-run só mostra o plano.

Fluxo, sempre:

1. Você: mudança, verificações, captura, git commit (Cowork).
2. Usuário, no terminal dele:

   cd ~/caminho/para/o/projeto
   node deploy.mjs --name nome-do-projeto
   

   (--name só na primeira vez.) Ele cola a saída; você devolve a URL de preview.
3. O usuário revisa a preview no navegador dele. As previews geralmente têm Deployment Protection (pedem login da Vercel); não use npx vercel curl para verificá-las: gera um token de bypass permanente no projeto. Se precisar ver você, use o navegador integrado com request_access ao domínio *.vercel.app e a vercel.com, e se não der, confie na revisão do usuário mais suas capturas locais.
4. Só com um "sim" explícito, o usuário executa node deploy.mjs --prod. Produção é pública.
5. Verifique produção (essa URL não está protegida): / responde, o CSS carrega, os links de CTA apontam bem, /.env.local, /.git/HEAD e /.vercel/project.json dão 404, uma rota inexistente mostra seu 404.
6. Informe: URL de produção, o que mudou, commit, como reverter.

Se o usuário preferir não usar o script, o equivalente manual é npx vercel link --yes --project <nome>, npx vercel deploy --yes e npx vercel deploy --prod --yes; nesse caso anote você a linha em .deployments.log (data ISO<TAB>preview|production<TAB>sha curto<TAB>URL) com device_bash a partir da saída que ele colou.

Nome do projeto: minúsculas e hífens, derivado do negócio (panaderia-la-espiga); define o subdomínio *.vercel.app.

Reverter

• npx vercel rollback → produção anterior (imediato, sem rebuild; não existe se foi o primeiro deploy)
• npx vercel promote <url-deploy> → publicar um deploy específico
• npx vercel ls <projeto> → listar deploys; .deployments.log os relaciona com commits

Extras sob demanda

• Variáveis de ambiente: npx vercel env add NOME production (o valor é digitado pelo usuário).
• Deploy automático ao fazer git push: references/ci-github.md. Recomende quando houver mais de uma pessoa editando ou muitas mudanças seguidas; elimina o passo manual de deploy.

As flags da CLI mudam. Se um comando falhar por uma flag, npx vercel <cmd> --help e adapte. Erros comuns: references/troubleshooting.md, mais estes vistos na prática:

Sintoma	Causa / solução
Error: Can't deploy more than one path	Comentários # no final da linha colada no zsh. Reescreva o bloco sem comentários.
vercel login "travado" no Cowork	Sandbox efêmero. O login vai no terminal do usuário.
403 from proxy after CONNECT / fetch failed para vercel.com	Rede da organização bloqueia Vercel. Terminal do usuário, ou o admin adiciona vercel.com e *.vercel.app aos domínios permitidos.
Apareceu .env.local após vercel link	Normal (token OIDC). Deve estar em .gitignore e .vercelignore; pode apagar.
unable to unlink .git/...lock: Operation not permitted	Falta permissão de exclusão na pasta conectada; peça uma vez ou o usuário commita.
Preview pede login da Vercel	Deployment Protection em previews; quem revisa é o usuário logado.

6. Domínio próprio

• .com.ar / .ar → siga references/dominio-nic-ar.md (compra no NIC Argentina com CNPJ + Chave Fiscal e delegação para a Vercel). O trâmite com Chave Fiscal e o pagamento são feitos pelo usuário; você o guia passo a passo.
• .com ou outros → comprar em qualquer registrador (ou na Vercel) e aplicar o mesmo passo de DNS daquele guia.
• Em ambos os casos, no terminal do usuário: npx vercel domains add <dominio> <projeto>, configurar DNS, verificar com npx vercel domains inspect <dominio>. A Vercel emite o certificado HTTPS apenas.

7. Mensagem de encerramento (sempre)

Curta e simples:

• URL publicada (e de preview se aplicável) e commit
• O que foi feito/mudou, em 2–4 pontos
• Decisões de design ou conteúdo que vale o usuário validar (tom, cores, dados de exemplo)
• "Para mudar algo, me diga o que e eu mostro uma preview antes de publicar."
• TODO pendentes e, se houver domínio .ar, lembrete de renovação anual