feat: integrate desktop runtime and root workspace updates

docs/app/backend-commands.md

@@ -0,0 +1,116 @@
+# Comandos backend do app desktop
+
+O backend Tauri exposto ao frontend vive principalmente em `tauri-app/src-tauri/src/lib.rs`.
+
+Esta pagina documenta os comandos que o frontend usa para runtime, modelos e diagnostico.
+
+## Runtime manager
+
+### `bootstrap_runtime_command`
+
+Carrega a configuracao persistida, reconstrui o snapshot do runtime e pode iniciar o runtime local automaticamente quando a politica e `on_app_launch` e o modo e `local`.
+
+### `get_runtime_snapshot_command`
+
+Retorna o `RuntimeSnapshot` atual com:
+
+- `status`
+- `ready`
+- `process_running`
+- `resolved_url`
+- `binary_path`
+- `last_error`
+- `config`
+
+### `save_runtime_config_command_handler`
+
+Persiste `RuntimeConfig` e atualiza o estado backend usado pelo runtime manager.
+
+Importante:
+
+- se o processo local estiver rodando e a mudanca exigir restart, o backend pode recusar a alteracao com erro `restart_required`
+
+### `start_runtime_command`
+
+Inicia o runtime local usando a configuracao atualmente salva no backend Tauri.
+
+### `stop_runtime_command`
+
+Para o runtime local e atualiza o snapshot.
+
+## GPU e modelos
+
+### `query_gpu`
+
+Usa `nvidia-smi` para detectar GPU NVIDIA e sugerir `recommended_layers`.
+
+### `scan_models(dir)`
+
+Escaneia um diretorio em busca de arquivos `.gguf`.
+
+### `pick_models_dir`
+
+Abre seletor nativo de pasta e devolve o diretorio escolhido junto com os modelos encontrados.
+
+### `pick_model_files`
+
+Abre seletor nativo de arquivos para escolher um ou mais `.gguf`.
+
+### `import_model(src_path, dest_dir)`
+
+Copia um arquivo `.gguf` para um diretorio de modelos.
+
+## Configuracao e paths
+
+### `save_config`
+
+Compatibilidade legada para salvar `RuntimeConfig` em arquivo.
+
+### `load_config`
+
+Leitura da configuracao persistida.
+
+### `find_server_binary`
+
+Resolve o caminho do binario `localllm` para diagnostico e start local.
+
+### `get_app_data_dir`
+
+Retorna o diretorio de dados do app.
+
+## Comandos legados de compatibilidade
+
+O backend ainda expoe:
+
+- `start_server`
+- `stop_server`
+- `server_status`
+
+Esses comandos existem como shims de compatibilidade. O fluxo principal do frontend atual deve preferir o runtime manager unificado (`bootstrap_runtime_command`, `get_runtime_snapshot_command`, `save_runtime_config_command_handler`, `start_runtime_command`, `stop_runtime_command`).
+
+## Tipos principais
+
+### `RuntimeConfig`
+
+Campos relevantes:
+
+- `connection_mode`
+- `start_policy`
+- `server_url`
+- `api_key`
+- `model_path`
+- `models_dir`
+- `addr`
+- `gpu_layers`
+- `ctx_size`
+- `extra_model_paths`
+
+### `RuntimeSnapshot`
+
+Representa o estado serializado usado pelo frontend para desenhar o runtime card, drawer e logica de start/stop.
+
+## Observacoes importantes
+
+- o backend Tauri e a source of truth da configuracao persistida do runtime do app
+- o frontend usa `useRuntimeManager()` para consumir essa superficie de comandos
+- readiness do runtime local depende de `GET /health`, nao apenas de socket aberto