# Recursos para desenvolvedores e agentes — carioca.build

Tudo o que carioca.build publica em formato legível por máquina, num só sítio. Esta mesma
página existe em HTML e em markdown na mesma URL — peça com `Accept: text/markdown`.

Este domínio é o site institucional da carioca.build. **Não há API pública, não há produto
self-serve e não há credenciais a emitir**: o que está publicado aqui é conteúdo, não uma
plataforma para integrar. Para falar connosco, ver [Contato](#contato).

## Índice de recursos

| Recurso                                             | URL                             | Formato                      |
| --------------------------------------------------- | ------------------------------- | ---------------------------- |
| Página inicial                                      | `/`                             | HTML ou markdown (negociado) |
| Página inicial em markdown                          | `/index.md`                     | `text/markdown`              |
| Resumo da empresa para agentes                      | `/llms.txt`                     | `text/plain`                 |
| Instruções para agentes (quando usar / como chamar) | `/agents.md`                    | `text/markdown`              |
| Esta página                                         | `/docs/`                        | HTML ou markdown (negociado) |
| Sitemap                                             | `/sitemap.xml`                  | XML                          |
| Regras de rastreio                                  | `/robots.txt`                   | `text/plain`                 |
| Contato de segurança                                | `/.well-known/security.txt`     | RFC 9116                     |
| Política de privacidade (LGPD)                      | `/politica-de-privacidade.html` | HTML                         |

## Negociação de conteúdo em markdown

carioca.build segue o [acceptmarkdown.com](https://acceptmarkdown.com): o mesmo URL serve HTML
a browsers e markdown a agentes, conforme o cabeçalho `Accept`.

```bash
curl -sSI -H 'Accept: text/markdown' https://carioca.build/
# content-type: text/markdown; charset=utf-8
# vary: negotiate,accept,Accept

curl -sS https://carioca.build/                     # continua a devolver HTML
curl -sSI -H 'Accept: application/pdf' https://carioca.build/   # 406 Not Acceptable
```

Os q-values são respeitados: `Accept: text/html;q=0.5, text/markdown` devolve markdown, e
`Accept: text/markdown;q=0.1, text/html` devolve HTML.

## Caminhos inexistentes

Um caminho que não existe devolve **404** — nunca 200 com o shell da aplicação. O corpo do 404
é markdown curto com o mapa do site, para um agente conseguir recuperar sem uma segunda
pesquisa:

```bash
curl -sS -o /dev/null -w '%{http_code}\n' https://carioca.build/caminho-que-nao-existe
# 404
```

## Contato

Trabalho, orçamento ou dúvida técnica: <dev@carioca.build> ou WhatsApp +55 21 97277-6040. O
formulário da [página inicial](/#contato) chega ao mesmo sítio.

Vulnerabilidades: seguir [`/.well-known/security.txt`](/.well-known/security.txt).