CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What this is

Marketing site for Meu Posto App (a cashback/loyalty platform for gas stations), built with Jekyll 3.9 and served via GitHub Pages at meuposto.app (see CNAME). All content is in Brazilian Portuguese. Ruby is pinned to 3.4.1 (.tool-versions).

Commands

bundle install                 # install gems
bundle exec jekyll serve       # local dev server (regenerates on change)
bundle exec jekyll build       # one-off build into _site/

Docker alternative (exposes port 4000):

docker-compose up -d
docker-compose exec app bash
bundle && jekyll serve

There is no test suite, linter, or JS build step — content is authored directly as HTML/Markdown/SCSS.

Architecture — two kinds of pages

The most important thing to understand: pages here fall into two distinct patterns, and most do not use Jekyll layouts.

Standalone landing pages (e.g. sobre/, historia/, app/, and most top-level campaign folders like clube-vip-premiado/, equipe-premiada/, black-novembro/). Each is a directory with its own index.html that contains a complete <!DOCTYPE html> document — its own <head>, inline analytics, and often its own CSS. They carry Jekyll front matter (title, description, keywords, socialImg) for SEO but render their full markup themselves, ignoring _layouts/. When editing one of these, change the page’s own HTML/CSS; the shared includes and layouts do not apply.
Layout-driven pages — the blog and a few others. Blog posts live in _posts/*.markdown with layout: post front matter (title, date, image, categories, index_resume) and are written in Markdown (kramdown). blog/index.html, contato/index.html, and juridico/contrato/index.html use layout: default. These flow through _layouts/default.html → _includes/.

index.html at the repo root is a symlink to revendedor/index.html (the site homepage).

Page directory map

Almost every top-level directory is a standalone full-HTML page (pattern 1 above). The exceptions noted are layout-driven (pattern 2).

Core / product pages

Directory	Page
`revendedor/`	Homepage (“Sistema de fidelização”) — root `index.html` symlinks here
`sobre/`	Sobre o Meu Posto App
`historia/`	História (`historia_original/` is the prior version)
`app/`	App download / features landing
`integracoes/`	Integrações
`meu-posto-xpert/`	Meu Posto XPert (distribuidores)
`central-pro/`	Central PRO
`casos-de-sucesso/`	Cases de sucesso
`midia/`	Na Mídia
`materiais/`	Materiais / ebooks (data from `_data/ebooks.yml`)
`calculadora/`	Calculadora de Cashback (also `_calculadora/` working copy)
`fale-com-um-consultor/`	Lead / consultant contact
`infografico-texto-blog/`	Infográfico landing

Promotional campaigns (mostly promo regulations — many are seasonal/recurring)

Directory	Campaign
`clube-vip-premiado/`, `clube-vip-premiado-2025/`	Clube VIP Premiado (`_clube-vip-premiado_old/` is a backup)
`equipe-premiada/`, `equipe-premiada-2/`	Equipe Premiada / Club VIP Equipe de Pista
`agosto-com-cashback/`, `campanhadesaojoao/`	É São João
`campanha-carnaval/`, `ferias-premiadas/`	Férias Premiadas
`black-novembro/`	Black Novembro
`setembro-mes-do-cliente/`	Mês do Consumidor
`final-de-ano-premiado/`	Final de Ano Premiado
`promocional-expopostos/`	Expopostos

Forms, legal & blog

Directory	Purpose
`blog/`	Blog index — `layout: default`, lists `_posts/`
`contato/`, `form-contato/`	Contact forms (`contato/` uses `layout: default`); submission via root `contact.php`
`politica-de-privacidade/`, `termos-de-uso/`	Legal pages
`juridico/contrato/`	Contract page — `layout: default`

Other: a1b2c3/ and a1b2c3.html/ are “Em manutenção” placeholders.

Shared building blocks (only affect layout-driven pages)

_layouts/: default.html, default_new.html, post.html. default.html pulls in head + header + a stack of marketing/tracking includes and jQuery.
_includes/: head.html (SEO tags, Google Analytics, Facebook Pixel), header.html, footer.html, plus third-party tracking snippets (drip.html, rdscript.html, leadboose.html, adOpt.html, google-analytics.html).
_data/ebooks.yml: data file for ebook/materials listings.
_sass/minima/ + _sass/minima.scss: SCSS for the minima-themed blog (compiled compressed per _config.yml). Note that standalone landing pages instead reference hand-written stylesheets under assets/css/ and assets/revendedor/.

Styling and design system

docs/design-system.md is the visual source of truth (open docs/design-system.html for swatches/specimens). Honor it when building or editing pages: brand purple #660099 (with #5d2684 / #4e2771 variants), warm accent #9a4d1c reserved for emotional taglines only, Montserrat as the single font family, and a 4px-multiple spacing scale. CSS custom-property tokens (--color-primary, --sp-*, etc.) are documented there.

Conventions

Pagination is configured in _config.yml for the blog (paginate, pagination: block) — posts are sorted by date descending.
Many *_old, _original, and underscore-prefixed sibling files/dirs (e.g. _clube-vip-premiado_old, index_image.html, Gemfile.lock_old) are retained backups — leave them alone unless explicitly working on them. New campaign pages are typically created by copying an existing landing-page directory.
contact.php handles form submission server-side (not part of the Jekyll build).

Calculadora de Cashback (`calculadora/`)

A standalone HTML/CSS/JS tool — no Jekyll involved. Serve it statically from the repo root so ../assets/ resolves:

ruby -run -e httpd . -p 8000   # → http://localhost:8000/calculadora/
node calculadora/test_calculadora.js   # run the calc tests (Node, manual asserts)

calculadora.js is the calculation engine; CALCULADORA DE CASHBACK.md is the formula spec (source of truth); test_calculadora.js cross-checks the engine against the spec. When changing the formula, update the spec and extend test_calculadora.js in the same change.
The page exists at /calculadora/ but is not yet linked from any site navigation/footer.

Team conventions & workflow

Linear → PR: open a Linear issue before the PR; branch named vf/...; assign to Vini; move the issue status when it enters review.
PR body carries no Claude signature — do not put “Generated with Claude Code” in PR descriptions. Commits may keep a Co-Authored-By trailer.
PR titles in English, formatted [MP-XXX] <imperative description> (e.g. [MP-200] Remove dead Smart Link (Firebase Dynamic Links) and add QR/Token guidance copy). The Linear issue itself may stay in Portuguese.
Code comments in English, always. Prefer WHY over WHAT — explain intent/rationale, not what the line obviously does. Keep short section-divider comments only where they genuinely aid readability.
User-facing copy: avoid em dashes (—) in running text; use commas, parentheses or periods. Marketing tone is commercial and concrete, not speculative — anchor claims, and keep the headline conservative with upside (e.g. tax benefit) shown as a separate “extra”.
README/CLAUDE.md describe the present (“what it is + how to run”). Roadmap/future ideas go to a Linear card (at most a link here), not into the docs.
Tests ship with the feature: every feature PR reviews existing tests and adds new ones in the same PR.
Always work from the repo root, never from ~ (there’s a stray .git in the home dir that breaks tooling).
Do not commit scratch/handoff files (e.g. CALCULADORA_HANDOFF.md, kept in .git/info/exclude).