# Guia de uso do app desktop

Este guia cobre o fluxo de uso do app Tauri no estado atual do projeto.

## 1. Abrir o app

Em desenvolvimento:

```bash
cd tauri-app
npm install
npm run tauri dev
```

## 2. Entender os modos de conexao

O Runtime Manager suporta dois modos.

### Local API

Use quando o app deve subir e controlar o backend local.

Voce configura:

- pasta de modelos
- modelo selecionado
- endereco de bind (`addr`)
- numero de GPU layers
- contexto (`ctx_size`)
- politica de auto-start

### Remote API

Use quando a API ja esta rodando em outro lugar.

Voce configura:

- `server_url`
- `api_key` opcional

Nesse modo o app nao tenta iniciar/parar o backend local.

## 3. Configurar o runtime local

Na sidebar, abra `Manage` ou o icone de configuracao.

Fluxo recomendado:

1. deixe `Connection mode` em `Local API`
2. escolha a pasta de modelos com `Browse`, ou adicione arquivos individuais com `Add files`
3. selecione o modelo desejado
4. ajuste `Listen address`, `GPU layers` e `Context size` se necessario
5. use `Save settings` ou `Save and start local API`

Observacoes:

- o app tenta descobrir o binario do backend automaticamente
- se uma revarredura da pasta vier vazia, o app preserva o `model_path` salvo em vez de limpar a selecao imediatamente
- o start local so fica disponivel quando existe binario e modelo selecionado

## 4. Configurar API remota

1. abra o Runtime Manager
2. mude para `Remote API`
3. preencha `Remote server URL`
4. opcionalmente, preencha `API key`
5. salve a configuracao

Depois disso, o app passa a usar essa URL para `GET /v1/models` e `POST /v1/chat/completions`.

## 5. Selecionar modelos no app

Quando a API estiver acessivel:

- o seletor de modelo na sidebar sera preenchido por `GET /v1/models`
- o app tenta manter a selecao atual quando possivel
- se o modelo sumir da API, o app troca para o primeiro disponivel

## 6. Conversar no chat

O fluxo principal fica em `ChatView`.

Recursos de uso:

- streaming on/off
- memory on/off
- historico persistente por conversa
- edicao e reenvio de mensagens do usuario
- edicao de resposta do assistente
- copia de conteudo/markdown/codigo

## 7. Thinking e tokens

Quando a resposta inclui blocos `<think>...</think>`:

- o app separa esse conteudo como `Thinking`
- o painel de thinking pode ser expandido/recolhido
- a resposta final aparece separadamente do thinking

Metricas visiveis:

- tokens enviados (`Sent`)
- tokens gerados (`Generated`)
- total por mensagem e por chat
- `tok/s` quando informado pela API

## 8. Troubleshooting rapido

### "Configure a local or remote API before sending messages"

O app esta sem endpoint valido. Abra o Runtime Manager e configure modo local ou remoto.

### Nenhum modelo aparece

- confirme que a API esta acessivel
- use o botao de refresh da sidebar
- no modo local, confirme que o modelo salvo foi iniciado corretamente

### O start local esta desabilitado

Verifique:

- se o binario do backend foi encontrado
- se um modelo esta salvo/selecionado
- se voce nao esta em modo remoto

### O runtime sobe mas nunca fica pronto

O app usa readiness por `GET /health`. Se a API local nao passar nesse check dentro do timeout, o runtime manager marca erro.

## 9. Persistencia e cuidado com dados

- chats e mensagens ficam no armazenamento local do app/frontend
- o app nao implementa sincronizacao remota de conversas
- apagar dados do navegador/webview pode remover o historico local