diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..a9a665f
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,88 @@
+# Contribuindo para o gitlab-lint Frontend
+
+Obrigado por querer contribuir com este projeto! Este guia curto descreve como preparar um contribution de forma clara e rápida.
+
+## Antes de começar
+
+- Procure por issues abertas que possam estar relacionadas à sua ideia para evitar duplicação.
+- Para mudanças maiores, abra uma issue descrevendo o problema e a solução proposta antes de implementar.
+
+## Fluxo sugerido
+
+1. Faça fork do repositório para sua conta GitHub.
+2. Clone seu fork:
+
+```powershell
+git clone https://github.com/<seu-usuario>/gitlab-lint-react.git
+cd gitlab-lint-react
+```
+
+3. Crie uma branch com nome descritivo:
+
+```powershell
+git checkout -b feature/minha-melhora
+```
+
+4. Faça mudanças pequenas e commits frequentes. Use mensagens de commit claras.
+5. Execute os testes e garanta que o código esteja formatado antes de abrir o PR.
+6. Suba sua branch e abra um Pull Request contra a `master` (ou outra branch indicada pelos mantenedores):
+
+```powershell
+git push origin feature/minha-melhora
+# então abra o PR no GitHub
+```
+
+## Estilo de código
+
+- O projeto usa Prettier via Husky (pre-commit) para formatar mudanças staged automaticamente.
+- Configure seu editor para usar Prettier (por exemplo: extensão Prettier no VSCode).
+- Siga os padrões existentes do código (React 17, hooks e Material-UI v4).
+
+## Testes
+
+- Se você implementar lógica significativa, adicione testes unitários (React Testing Library / Jest quando aplicável).
+- Para rodar testes localmente:
+
+```powershell
+npm test
+# ou
+# yarn test
+```
+
+## Mensagens de commit
+
+Use mensagens claras. Exemplos:
+
+```
+feat: adiciona nova funcionalidade X
+fix: corrige bug em Y
+docs: atualiza documentação
+refactor: refatora componente sem alterar comportamento
+```
+
+Adotar Conventional Commits é recomendado, mas não obrigatório para contribuições pequenas.
+
+## Checklist para Pull Request
+
+- [ ] O PR explica o que foi feito e por quê.
+- [ ] Testes foram adicionados/atualizados quando necessário.
+- [ ] Código está formatado (Prettier) e sem segredos/acessos embutidos.
+- [ ] Build local passa (`npm run build`).
+
+## Segurança
+
+- Não inclua senhas, keys ou tokens em commits.
+- Para relatar problemas de segurança, contate os mantenedores em privado ou abra uma issue descrevendo o problema.
+
+## Feedback e revisão
+
+- Responda às observações feitas pelos revisores e atualize seu PR quando solicitado.
+- Prefira PRs menores e focados — facilitam revisão e aprovação.
+
+## Agradecimento
+
+Obrigado por contribuir! Mesmo pequenas correções de documentação são bem-vindas.
+
+---
+
+Este guia é um ponto de partida e pode ser atualizado pelos mantenedores conforme necessário.
diff --git a/README.md b/README.md
index 99406e7..6f1306c 100644
--- a/README.md
+++ b/README.md
@@ -1,23 +1,118 @@
-# gitlab-lint Frontend
+# gitlab-lint — Frontend
 
 ![gitlab-lint Frontend](gitlab-lint-frontend.png)
 
-## Dependencies
+Interface web para visualizar os resultados coletados pelo projeto `gitlab-lint` (API/collector). Esta aplicação é uma SPA em React que consome uma API (configurada via variável de ambiente).
 
-- nodejs
-- yarn
-- [gitlab-lint API and collector][gitlab-lint]
+## Sumário
 
-### Installing dependencies
+- Requisitos
+- Como rodar localmente
+- Variáveis de ambiente
+- Docker
+- Desenvolvimento e testes
+- Contribuindo
+- Licença
 
-```bash
-make setup
+## Requisitos
+
+- Node.js (LTS recomendado)
+- yarn ou npm
+- backend `gitlab-lint` (API que fornece os dados)
+
+### Dependências principais
+
+- React 17
+- Material-UI v4
+- Recharts
+- axios, lodash
+
+## Rodando localmente
+
+O projeto fornece Makefile com atalhos, mas você também pode usar os scripts do `package.json` diretamente.
+
+Usando Make (recomendado quando disponível):
+
+```powershell
+make setup   # instala dependências (npm/yarn conforme Makefile)
+make run     # inicia a aplicação em modo de desenvolvimento
+```
+
+Usando npm / yarn diretamente:
+
+```powershell
+# instalar
+npm install
+# ou
+yarn install
+
+# iniciar em modo desenvolvimento
+npm start
+# ou
+yarn start
+
+# rodar testes
+npm test
+# ou
+yarn test
+
+# build de produção
+npm run build
+# ou
+yarn build
 ```
 
-## Run it
+## Variáveis de ambiente
+
+Esta aplicação usa a variável de ambiente REACT_APP_API_URL para apontar para a URL da API do `gitlab-lint`. Você pode exportá-la antes de iniciar a aplicação:
 
-```bash
-make run
+```powershell
+# Windows PowerShell
+$env:REACT_APP_API_URL = 'https://seu-backend.example.com'
+npm start
 ```
 
+No código, a configuração é lida em `src/conf.js`:
+
+```javascript
+const conf = { gitlabLintApiUrl: process.env.REACT_APP_API_URL }
+export default conf
+```
+
+## Docker
+
+O repositório inclui `Dockerfile` e `docker-compose.yml` para executar a aplicação em container. Exemplo rápido:
+
+```powershell
+# build e subir via docker-compose
+docker compose up --build -d
+```
+
+Verifique o `docker-compose.yml` para o nome do serviço e portas expostas.
+
+## Desenvolvimento e qualidade
+
+- O projeto já possui integração com `prettier` e `pretty-quick` via `husky` para formatar staged changes no pre-commit.
+- Recomenda-se adicionar ESLint e um workflow de CI para rodar lint/test/build em PRs.
+- Sugestões futuras: adicionar testes com React Testing Library, code-splitting nas rotas e análise de bundle.
+
+## Contribuindo
+
+1. Fork o projeto
+2. Crie uma branch com um nome descritivo: `feature/minha-melhora`
+3. Implemente sua mudança e adicione testes quando aplicável
+4. Faça commit e push
+5. Abra um Pull Request explicando o que mudou e por quê
+
+Por favor siga as convenções de lint/format definidas no projeto.
+
+## Problemas comuns
+
+- Erro ao iniciar devido à falta de `REACT_APP_API_URL`: assegure-se de definir a variável de ambiente apontando para o backend.
+- Se o `make` falhar no Windows, rode os comandos npm/yarn diretamente conforme seção acima.
+
+## Licença
+
+BSD 3-Clause — ver o arquivo `LICENSE` neste repositório.
+
 [gitlab-lint]: https://github.com/globocom/gitlab-lint