docs: reorganize and simplify

- Add docs/README.md as index
- Consolidate ops in docs/operations.md; mark legacy runbooks as archive
- Create docs/desktop/ and docs/admin/ structure and move relevant docs
- Update root README to link docs index
- Keep historical and planning notes under docs/archive/

docs/desktop-handshake-troubleshooting.md

@@ -1,71 +0,0 @@
-# Desktop (Tauri) — Handshake, Sessão de Máquina e Antivírus
-
-Este documento consolida as orientações e diagnósticos sobre o fluxo do agente desktop, handshake na web e possíveis interferências de antivírus.
-
-## Sintomas observados
-- Ao clicar em “Registrar máquina”, o antivírus aciona (ex.: ATC.SuspiciousBehavior) e o processo é interrompido.
-- Após o registro, ao abrir a UI web: cabeçalho mostra “Cliente / Sem e‑mail definido” e o Portal não permite abrir chamados.
-- No passado, mesmo quando o app “entrava direto”, o Portal não refletia o colaborador/gestor vinculado (sem assignedUser); receio de repetir o problema.
-
-## Causas prováveis
-1) O antivírus interrompe o processo durante o handshake
-   - O app salva token/config, inicia heartbeat e abre `GET /machines/handshake?token=...&redirect=...` para gravar cookies de sessão.
-   - Se o processo cai neste momento, os cookies não são gravados e a UI fica sem sessão “machine”.
-
-2) Endpoint de contexto sem ler a sessão adequadamente
-   - O Portal preenche o colaborador/gestor via `GET /api/machines/session`.
-   - Em alguns ambientes, é mais estável rodar esse endpoint no runtime `nodejs` para ler `cookies()` do Next sem inconsistências.
-
-## O que já foi aplicado no projeto
-- Middleware permite `GET /machines/handshake` sem exigir login (rota pública).
-- Frontend preenche `machineContext` chamando `GET /api/machines/session` (assignedUserId/email/nome/persona) e usa esse ID ao abrir chamados.
-- UI oculta “Sair” quando a sessão é de máquina (portal e shell interno).
-- DevTools habilitado no desktop (F12, Ctrl+Shift+I ou botão direito com Ctrl/Shift).
-- Desktop salva dados em `C:\\Raven\\data\\machine-agent.json` (ou equivalente ao lado do executável), com fallback para AppData se a pasta do app não permitir escrita.
-
-## Validação rápida (após “Registrar máquina”)
-1) No executável, com DevTools:
-   ```js
-   fetch('/api/machines/session').then(r => r.status).then(console.log)
-   // Esperado: 200
-   fetch('/api/machines/session').then(r => r.json()).then(console.log)
-   // Deve conter: persona (collaborator|manager), assignedUserEmail/nome/Id
-   ```
-2) Na UI (Portal/Topo):
-   - Mostrar nome/e‑mail do colaborador/gestor (não “Cliente / Sem e‑mail definido”).
-   - Sem botão “Sair” (sessão de máquina).
-3) No Portal, o formulário “Abrir chamado” deve habilitar normalmente (usa `machineContext.assignedUserId`).
-
-Se `GET /api/machines/session` retornar 403:
-- Verificar se o antivírus barrou o processo na hora do handshake.
-- Adicionar exceção para `C:\\Raven\\appsdesktop.exe` e `C:\\Raven\\data\\`.
-- Opcional: forçar `export const runtime = 'nodejs'` no endpoint de sessão para leitura consistente de cookies (Next `cookies()`).
-
-## Fluxo atual do desktop
-- Antes de registrar: tela de onboarding (sem “Abrir sistema”).
-- Após registrar: salva token/config, inicia heartbeat e mostra as abas com “Abrir sistema” e “Reprovisionar”.
-- Auto‐abrir: o app já tenta abrir o sistema quando detecta token; pode ser reforçado chamando `openSystem()` ao fim do `register()`.
-
-## Melhorias opcionais
-- Auto‑abrir imediatamente após `register()` (reforça o comportamento atual e reduz a janela para interferência do AV).
-- Diagnóstico no desktop: exibir caminho completo do arquivo de dados e botão “Abrir pasta de dados”.
-- Forçar `nodejs` no `GET /api/machines/session` para estabilidade total na leitura de cookies.
-
-## Notas sobre antivírus
-- Apps Tauri não assinados com certificado de code signing do Windows são frequentemente marcados como “desconhecidos”.
-- A assinatura Minisign (updater) não substitui o code signing do executável.
-- Recomendações:
-  - Adicionar exceções para o executável e a pasta de dados.
-  - Avaliar aquisição de um certificado de code signing (EV/OV) para distribuição ampla sem alertas.
-
-## Checklist quando “não mudou nada” após registro
-- Confirmar `GET /api/machines/session` (status 200 + JSON contendo assignedUser). Caso 403, tratar AV/endpoint runtime.
-- Verificar cookies no navegador (DevTools → Application → Cookies): presença da sessão e `machine_ctx`.
-- Validar que o Portal mostra o colaborador/gestor e permite abrir chamado.
-- Conferir arquivo de dados:
-  - Preferencial: `C:\\Raven\\data\\machine-agent.json`.
-  - Fallback: AppData local do usuário (buscar por `machine-agent.json`).
-
----
-
-Última atualização: automatização do handshake no middleware, ocultação de “Sair” em sessão de máquina, dados persistidos junto ao executável e DevTools habilitado.