# Trilha

> Framework web para Go no estilo Next.js: uma pasta em app/ é uma rota, o HTML é escrito em Go e nada fora da biblioteca padrão é importado.

Este é o índice da documentação em texto puro. Cada item abaixo é uma página; a documentação inteira, concatenada, está em /trilha/pt/llms-full.txt.

## Aprender

- [Início rápido](/trilha/pt/aprender): Do zero a uma página no navegador em cinco minutos, e o que aconteceu em cada passo.
- [Páginas e rotas](/trilha/pt/aprender/paginas-e-rotas): Como pastas viram URLs, incluindo segmentos dinâmicos, catch-all e grupos.
- [Layouts aninhados](/trilha/pt/aprender/layouts): Um layout por pasta, do mais interno ao mais externo, e como o título viaja entre eles.
- [HTML com o pacote h](/trilha/pt/aprender/html-com-h): Elementos como funções, escape por padrão, condicionais, listas e quando usar templates.
- [Formulários](/trilha/pt/aprender/formularios): POST no mesmo page.go, proteção CSRF automática e o padrão redirecionar-depois-de-gravar.
- [Rotas de API](/trilha/pt/aprender/api): route.go com uma função por método HTTP, JSON de entrada e saída e erros com status.
- [Dados e cache](/trilha/pt/aprender/dados): De onde vem o dado, por quanto tempo vale guardar a resposta e o que a derruba — com cache.Do, tags e cache.Once.
- [Middleware](/trilha/pt/aprender/middleware): Interceptar uma subárvore de rotas, passar valores para as páginas e proteger áreas.
- [Segurança](/trilha/pt/aprender/seguranca): O que o Trilha protege por padrão, como ajustar, e o que continua sendo responsabilidade sua.
- [Saúde e observabilidade](/trilha/pt/aprender/observabilidade): Sondas de vida e prontidão, métricas no formato Prometheus e correlação de log, com o cuidado de não transformar monitoração em vazamento.
- [Autenticação com Entra ID, Keycloak, Cognito e Clerk](/trilha/pt/aprender/autenticacao): Login OpenID Connect com PKCE, sessão assinada, papéis e logout federado, sem dependência externa e sem senha no seu banco.
- [Interface com ui](/trilha/pt/aprender/interface-com-ui): O kit de componentes padrão do Trilha, compatível com temas do shadcn/ui, e como ele fica seu para customizar.
- [Interatividade](/trilha/pt/aprender/interatividade): Trocar um pedaço da página e enviar formulário sem recarregar, com o mesmo handler que serve a página inteira.
- [IA e agentes](/trilha/pt/aprender/ia-e-agentes): Chame um modelo, dê ferramentas a um agente, transfira a conversa entre agentes, use e exponha MCP, e transmita a resposta em streaming.
- [Exemplos](/trilha/pt/aprender/exemplos): Apps completos em examples/, do básico ao complexo, e o que cada um ensina.
- [Testes](/trilha/pt/aprender/testes): Um cliente de teste no próprio framework: um pedido, uma sessão inteira, CSRF que já passa.
- [Desenvolvimento e produção](/trilha/pt/aprender/dev-e-producao): O que trilha dev faz por baixo, como publicar um binário e como configurar por variáveis de ambiente.
- [Problemas comuns](/trilha/pt/aprender/problemas-comuns): Erros que aparecem nos primeiros minutos e o que cada um significa.

## Referência

- [Visão geral](/trilha/pt/referencia): Os pacotes do Trilha e o que cada um faz.
- [Convenções de arquivo](/trilha/pt/referencia/convencoes): Tabela completa do que cada arquivo e nome de pasta em app/ significa.
- [Ctx](/trilha/pt/referencia/ctx): Tudo que uma função de rota pode fazer com o contexto da requisição.
- [Pacote h](/trilha/pt/referencia/h): Referência do DSL de HTML: nós, elementos, atributos e fluxo de controle.
- [Pacote tmpl](/trilha/pt/referencia/tmpl): Usar html/template dentro do pipeline de páginas e layouts.
- [Erros](/trilha/pt/referencia/erros): Os valores de erro que o Trilha entende e como cada um vira resposta.
- [Validação](/trilha/pt/referencia/validacao): A tag validate, as regras por tipo, as suas próprias regras e as mensagens que o Bind devolve.
- [App e Config](/trilha/pt/referencia/app): O que o arquivo gerado monta e o que você pode ajustar em setup.go.
- [Segurança](/trilha/pt/referencia/seguranca): Configuração completa de cabeçalhos, proxies, limite de taxa, cookies assinados e eventos.
- [Observabilidade](/trilha/pt/referencia/observabilidade): Config.Observability, endpoints de saúde, registro de métricas, variáveis de ambiente e o contrato de cada resposta.
- [auth](/trilha/pt/referencia/auth): Provider, Options, Auth, User e Store — a API do pacote auth, com os padrões e o que cada campo muda.
- [cache](/trilha/pt/referencia/cache): Options, Key, Cache, Do, Get e Once — a API do pacote cache, com os padrões e o que cada campo muda.
- [ui](/trilha/pt/referencia/ui): Componentes do kit, variantes, assets e o contrato de tema.
- [ai](/trilha/pt/referencia/ai): Cliente OpenAI-compatível, ferramentas, agentes, handoffs e composição.
- [mcp](/trilha/pt/referencia/mcp): Cliente e servidor do Model Context Protocol (stdio e Streamable HTTP).
- [CLI](/trilha/pt/referencia/cli): Os comandos de trilha e suas opções.
- [Desempenho e comparação](/trilha/pt/referencia/desempenho): Quanto o Trilha custa sobre a biblioteca padrão, como medir você mesmo, e como ele se posiciona frente a outras abordagens.

## Receitas

- [Receitas](/trilha/pt/receitas): As partes que todo app precisa e nenhum framework decide por você — banco, sessão, upload, paginação, e-mail, tarefa agendada, Docker — com código que compila.
- [Banco de dados](/trilha/pt/receitas/banco-de-dados): Um pool para o processo, consultas que carregam o contexto da requisição, uma transação que desfaz sozinha e migrações aplicadas em ordem.
- [Sessões](/trilha/pt/receitas/sessoes): Login com cookie assinado, o usuário atual num middleware, uma mensagem flash que sobrevive a um redirecionamento — e nada guardado no servidor.
- [Uploads](/trilha/pt/receitas/uploads): Receber um arquivo com teto, conferir o que ele é de verdade, guardar fora da árvore servida e devolver sem deixar rodar.
- [Paginação](/trilha/pt/receitas/paginacao): Paginar por offset enquanto a lista é curta, por cursor quando não é mais, uma linha a mais em vez de um COUNT, e links que um robô consegue seguir.
- [E-mail](/trilha/pt/receitas/email): Uma interface que os handlers chamam, SMTP atrás dela em produção, o log em dev, um corpo vindo de template e cabeçalhos que se recusam a ser injetados.
- [Tarefas agendadas](/trilha/pt/receitas/tarefas-agendadas): Um ticker que sobe com o app e para com ele, um tique por vez, um pânico que não derruba o processo — e a linha em que o cron passa a ser a resposta certa.
- [Docker](/trilha/pt/receitas/docker): Um binário estático numa imagem distroless, os assets já dentro dele, as variáveis que ele precisa e uma sonda de saúde que o orquestrador consegue usar.
- [Checklist de produção](/trilha/pt/receitas/checklist-de-producao): O que conferir antes de publicar, em ordem: o que o trilha audit acha por você, o que ele não enxerga e as duas coisas a preparar para o dia em que der errado.
- [Migração](/trilha/pt/receitas/migracao): De net/http puro para Trilha uma rota por vez, sem reescrita — e o que olhar quando você anda entre versões menores.