# Para agents

## Como ler

- [`/llms.txt`](/llms.txt): índice no formato llmstxt.org, com título e descrição de cada página.
- [`/llms-full.txt`](/llms-full.txt): toda a documentação em texto puro, na ordem de tutorial.
- Qualquer página em Markdown cru: acrescente `.md` à URL (por exemplo `/comecar/token.md`). Cada página HTML aponta para sua versão com `<link rel="alternate" type="text/markdown">`.
- Sem cookies e sem JavaScript obrigatório: um `GET` simples lê tudo.

## Guias para tarefas grandes

- [Contrato de App Nebular](/agents/contrato-app/): o documento para mandar a um agent que vai adequar um app à Nebular; regras normativas (porta, disco somente leitura, config, banco) e tabela de erros de deploy com culpa e correção.
- [Deploy de aplicações com vários serviços](/agents/deploy-multi-servico/): front, API, worker e bancos no mesmo projeto, com referências, deploy em grupo, rollback, erros e o que ainda não existe (manifesto, réplicas).
- [Como corrigir cada erro de deploy](/agents/corrigir-deploy/): cookbook com uma seção por `error_code` (âncora estável), o que cada erro significa, como corrigir e de quem é a culpa; inclui migrar SQLite local para libSQL gerenciado.
- [Preparar o app para rodar e escalar](/operacao/app-pronto-para-escalar/): use antes do primeiro deploy; cobre `0.0.0.0:$PORT`, app sem estado, health check, SIGTERM, volumes e migrations.
- [Variáveis e referências](/conectados/variaveis-e-referencias/): use ao configurar ambiente; explica as variáveis automáticas e as referências `${{serviço.VAR}}`.
- [Conexão e referências de banco](/bancos/conexao-e-referencias/): use ao ligar app e banco; o banco **não** é injetado sozinho, a ligação é um passo explícito resolvido no deploy.
- [Sugestões de persistência](/conectados/sugestoes-de-persistencia/): quando um app precisa de volume ou banco, a plataforma detecta e sugere criar; leia e descarte sugestões pela API, sempre com autorização.

## Faça

- Autentique com `Authorization: Bearer $NEBULAR_TOKEN`, lendo o token do ambiente.
- Use `Idempotency-Key` em todo envio automatizado.
- Decida pelo campo `error` e siga a [tabela de erros](/erros/tabela/).
- Trate páginas “em construção — disponível na v13” como **recursos inexistentes**: não invente rotas.

## Não faça

- Não coloque o token em query string, log, prompt ou repositório.
- Não repita um `4xx` (exceto `429`) sem alterar a requisição.
- Não reenvie um arquivo recusado por varredura.
- Não monte URLs da CDN à mão: use `url` e `alias_url` devolvidas pela API.