---
name: documentacao
description: Crie, revise e mantenha a documentação do projeto Dental System. Use quando Codex precisar atualizar README, guias de instalação, scripts de execução, documentação de API, onboarding, troubleshooting, exemplos de uso, rotas FastAPI, variáveis de ambiente, Docker, Poetry, frontend estático, cadastro/login ou qualquer documentação técnica dentro deste repositório.
---

# Documentacao

## Objetivo

Manter a documentação do Dental System clara, executável e sincronizada com o código. Priorizar instruções que uma pessoa consiga seguir do zero sem conhecer o projeto.

## Fluxo

1. Ler primeiro os arquivos relevantes:
   - `README.md`
   - `.env.example`
   - `pyproject.toml`
   - `docker-compose.yml`
   - `scripts/start.sh` e `scripts/stop.sh`, quando existirem
   - `app/main.py` e roteadores em `app/routers/`, quando documentar API
   - `frontend/src/api.js`, quando documentar integração frontend/backend

2. Conferir comandos antes de documentar como verdade. Preferir validar com comandos leves:
   - `bash -n scripts/start.sh scripts/stop.sh`
   - `poetry check`
   - `python -m compileall app`
   - `pytest`, informando quando não houver testes

3. Atualizar documentação com foco em execução real:
   - pré-requisitos
   - instalação
   - configuração do `.env`
   - como iniciar e parar
   - URLs úteis
   - cadastro/login
   - troubleshooting dos erros mais prováveis

4. Escrever em português brasileiro, com comandos copiáveis e caminhos reais do projeto.

5. Evitar prometer funcionalidades que o código não implementa. Quando algo estiver incompleto, sinalizar como limitação ou próximo passo.

## Padrões

- Preferir seções curtas e diretas.
- Usar `127.0.0.1` nos exemplos locais.
- Documentar SQLite como caminho local simples e PostgreSQL como opção Docker.
- Manter exemplos de API usando `/api/v1`.
- Informar que o frontend é servido pelo FastAPI em `/`.
- Quando citar scripts, usar:

```bash
./scripts/start.sh
./scripts/stop.sh
```

## Referências

Leia `references/dental-system.md` quando precisar de detalhes sobre arquitetura, comandos, variáveis e checklist de documentação deste projeto.