# Agentes de IA

Como agentes de IA e ferramentas LLM devem ler esta documentação (llms.txt, llms-full.txt e páginas em Markdown) e como pedir ajuda a uma IA sem vazar chaves.

Source: https://fivedash.fivex.gg/docs/pt/developers/ai-agents

Esta documentação foi escrita para pessoas e para agentes de IA. Toda página existe também em Markdown puro, e há um índice e um arquivo com tudo junto, no formato `llms.txt`. Assim você pode entregar a documentação certa para o ChatGPT, o Claude, o Cursor ou qualquer agente, e pedir ajuda para montar a sua cidade sem a IA inventar exports ou opções que não existem.

[Vídeo: como fazer em menos de 20 segundos](https://fivedash.fivex.gg/docs/videos/docs-agents-pt.mp4)

## Antes de começar

* Uma IA ou agente que consiga ler links ou arquivos que você cola.
* O que você quer fazer, em uma frase (ex.: "trocar os webhooks do Discord dos meus scripts pelos logs do FiveDash").
* Nunca cole chaves, tokens ou links secretos na conversa. Veja a seção **Segurança** abaixo.

## Os formatos para IA

| Endereço                              | O que tem                                               | Quando usar                                                                |
| ------------------------------------- | ------------------------------------------------------- | -------------------------------------------------------------------------- |
| `/docs/llms.txt`                      | O índice: a lista de páginas da documentação, com links | Para o agente descobrir o que existe e escolher o que ler                  |
| `/docs/<idioma>/llms-full.txt`        | Todas as páginas de um idioma num arquivo só            | Para dar o contexto inteiro de uma vez (ferramentas com bastante contexto) |
| `/docs/<idioma>/<slug>.md`            | Uma página em Markdown                                  | Para dar só o assunto da tarefa                                            |
| Botão **Copiar página como Markdown** | A página aberta, em Markdown, na área de transferência  | Para colar direto no chat                                                  |

`<idioma>` é `pt` (português) ou `en` (inglês). O `<slug>` é o caminho da página, o mesmo do link normal. Exemplos:

```text
/docs/llms.txt
/docs/pt/llms-full.txt
/docs/en/llms-full.txt
/docs/pt/developers/logs-api.md
/docs/en/developers/fivem-resource.md
/docs/pt/getting-started/install-resource.md
```

Cada página faz sentido sozinha: os pré-requisitos principais são repetidos em cada uma, então um agente que lê só um `.md` tem o que precisa.

### Qual escolher

| Tarefa                                          | Dê para a IA                                                           |
| ----------------------------------------------- | ---------------------------------------------------------------------- |
| Instalar e conectar o recurso                   | `getting-started/install-resource.md` e `developers/fivem-resource.md` |
| Integrar um script com os logs                  | `developers/exports-and-events.md` (e o script)                        |
| Trocar webhooks do Discord                      | `logs/migrate-from-webhooks.md` e `developers/logs-api.md`             |
| Mandar prints para a CDN                        | `developers/cdn-api.md`                                                |
| Entender a whitelist ou a loja na sua framework | `developers/frameworks.md`                                             |
| Dúvida geral ou várias áreas                    | `llms-full.txt` do seu idioma                                          |
| Não sabe por onde começar                       | `llms.txt` e peça para o agente escolher                               |

## Como pedir para uma IA ajudar a montar a cidade

A IA trabalha nos arquivos da cidade (scripts, `server.cfg`, `config.lua`). O que acontece no painel do FiveDash (gerar a chave, criar logs, criar chaves da CDN, conectar pagamentos) é você quem faz, com a sua conta.

| A IA pode fazer                                                         | Você faz no painel                                                                   |
| ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| Ajustar a ordem do `server.cfg` (`ensure fivedash` depois da framework) | Gerar a chave do servidor (**Conexão com o jogo → Conectar servidor → Gerar chave**) |
| Escrever as chamadas `exports.fivedash:log(...)` nos scripts            | Criar cada log e escolher a **Chave** dele                                           |
| Trocar o link do Discord pelo link do log, sem mexer no resto           | Copiar o link de cada log                                                            |
| Escrever o envio para a CDN (`screenshot-basic`, NUI, servidor)         | Criar a chave de envio e escolher a pasta                                            |
| Explicar um aviso do console `[FiveDash]`                               | Ver o cartão **Conexão com o jogo** e os avisos                                      |

### Dicas para o pedido

1. **Diga a sua base:** framework (QBCore, Qbox, ESX, ox_core, Creative, vRP), o driver do banco (`oxmysql`…) e o inventário.
2. **Dê a página certa:** cole o `.md` da tarefa ou o link dele, e peça para a IA seguir só o que está escrito.
3. **Use valores de exemplo:** no lugar da chave, escreva `fdk_xxxxxxxx`; no lugar do link do log, `https://<endereço-dos-logs>/api/logs/<channelId>/<token>`. Você cola os valores reais depois, direto no arquivo.
4. **Peça só as alterações:** "me mostre em qual arquivo e onde entra cada trecho". Revise antes de colar.
5. **Teste no console:** depois de mudar, `restart` do script, `fivedash logs teste <chave>` e `fivedash` para ver o estado.

### Exemplos de pedido

Integrar um script com os logs:

```text
Leia https://fivedash.fivex.gg/docs/pt/developers/exports-and-events.md
e siga só o que está nela.

Minha cidade usa QBCore com oxmysql. O recurso fivedash já está instalado.
Quero mandar para o log com a chave "roubo-lojinha" sempre que alguém roubar
uma loja neste script (colei abaixo). Use player = source, coloque o valor
roubado em fields e crie a função fivedashLog no topo do arquivo.
Me mostre só as alterações.

<cole o server.lua do script aqui>
```

Trocar webhooks do Discord:

```text
Leia https://fivedash.fivex.gg/docs/pt/developers/logs-api.md.
Neste config.lua há webhooks do Discord (discord.com/api/webhooks/...).
Troque cada um por um marcador LOG_URL_<NOME> para eu colar os links do
FiveDash depois. Não mude mais nada.
```

Revisar a instalação:

```text
Leia https://fivedash.fivex.gg/docs/pt/developers/fivem-resource.md.
Este é o meu server.cfg (sem as chaves) e o que o console mostrou no boot.
Diga se a ordem dos ensure está certa e o que significa cada aviso [FiveDash].
```

> No painel, cada log tem o botão **Copiar prompt para IA** em **Como mandar**. Ele copia um pedido pronto, com a chave daquele log, todas as opções do export e as regras de segurança. É só colar na IA junto com o script.

## Segurança

> Nunca cole chaves, tokens ou links secretos num chat de IA, num ticket ou num print. O que vai para uma conversa pode ficar guardado fora do seu controle.

| Segredo                                      | Como reconhecer                                                          | Se vazar                                                           |
| -------------------------------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------ |
| Chave do servidor                            | Começa com `fdk_` (no `fivedash/config.lua` ou na convar `fivedash_key`) | **Servidor → Visão geral → Conexão com o jogo → Gerar nova chave** |
| Link de um log                               | `…/api/logs/<channelId>/<token>`: o token é a senha                      | No log, **Editar log → Gerar novo link**                           |
| Chave de envio da CDN                        | Começa com `fdm_`                                                        | **CDN → Configurações → Chaves de envio → Revogar**                |
| Token do bot do Discord, chaves de pagamento | Nos módulos **Discord** e **Loja**                                       | Troque no provedor e no painel                                     |

Boas práticas:

* Troque os valores reais por exemplos antes de colar qualquer arquivo: `fdk_xxxxxxxx`, `fdm_xxxxxxxx`, `<token>`.
* Peça para a IA ler a chave de uma convar ou de um arquivo de configuração, nunca escrever a chave no código.
* Não suba `config.lua`, `server.cfg` com chaves ou arquivos `.env` para o GitHub.
* Se colou uma chave por engano, gere outra na hora. A antiga para de funcionar.

## Para agentes de IA

Se você é um agente lendo esta página, siga estas regras ao ajudar um dono de cidade:

1. Use só o que está nesta documentação. Ela foi escrita a partir do código do FiveDash.
2. O recurso `fivedash` expõe um único export, `exports.fivedash:log(chave, dados)`, só no servidor, e o evento local `fivedash:log`. Não invente outros exports, eventos de rede ou callbacks.
3. A chave do servidor, os logs e as chaves da CDN são criados no painel pela pessoa. Peça para ela fazer isso e use marcadores no lugar dos valores.
4. Nunca peça para a pessoa colar uma chave (`fdk_`, `fdm_`) ou um link de log completo na conversa. Se ela colar, avise que precisa gerar outra.
5. Para a lista completa de páginas, leia `/docs/llms.txt`. Para uma página, leia `/docs/<idioma>/<slug>.md`.
6. Quando algo depender da framework, confira a aba dela em [Frameworks](https://fivedash.fivex.gg/docs/pt/developers/frameworks).

## Perguntas frequentes

**Qual idioma dar para a IA?**
O da sua conversa. As páginas em `pt` e `en` têm o mesmo conteúdo e a mesma estrutura.

**O llms-full.txt é grande demais para a minha IA.**
Use o `llms.txt` para achar as páginas da tarefa e dê só esses `.md`.

**A IA pode configurar o painel por mim?**
Não por esta documentação: ela ajuda nos arquivos da cidade. As ações no painel são feitas por você.

## Próximos passos

[Recurso FiveM](https://fivedash.fivex.gg/docs/pt/developers/fivem-resource)O que dar para a IA instalar e conectar a cidade.
[Exports, eventos e comandos](https://fivedash.fivex.gg/docs/pt/developers/exports-and-events)A referência que a IA usa nos scripts.
[Assistente do painel](https://fivedash.fivex.gg/docs/pt/dashboard/assistant)O assistente que já vem no FiveDash.
[Migrar dos webhooks](https://fivedash.fivex.gg/docs/pt/logs/migrate-from-webhooks)Uma tarefa ótima para fazer com IA.