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/

README.md

@@ -42,10 +42,11 @@ Aplicação Next.js 15 com Convex e Better Auth para gestão de tickets da Rever
 
 > Se o CLI perguntar sobre configuração do projeto Convex, escolha criar um novo deployment local (opção padrão) e confirme. As credenciais são armazenadas em `.convex/` automaticamente.
 
-### Deploy em produção (Traefik + Convex self‑hosted)
+### Documentação
-- Guia completo: `docs/OPERACAO-PRODUCAO.md:1`.
+- Índice de docs: `docs/README.md`
-- Histórico de setup/decisões: `docs/SETUP-HISTORICO.md:1`.
+- Operações (produção): `docs/operations.md`
-- Stack Swarm: `stack.yml:1` (roteado por Traefik, rede `traefik_public`).
+- Guia de DEV: `docs/DEV.md`
+- Stack Swarm: `stack.yml` (roteado por Traefik, rede `traefik_public`).
 
 ### Variáveis de ambiente
 

docs/OPERACAO-PRODUCAO.md

@@ -1,4 +1,6 @@
-# Runbook de Operação — Produção (Traefik + Convex Self‑Hosted)
+# Runbook de Operação — Produção (Traefik + Convex Self‑Hosted) — Arquivo
+
+Nota: este documento foi substituído por `docs/operations.md` e permanece aqui como histórico.
 
 > Documento vivo. Guia completo para (1) preparar a VPS, (2) fazer deploy com Traefik/Swarm, (3) publicar o backend Convex self‑hosted, (4) popular seeds e (5) operar/atualizar com ou sem CI/CD. Tudo em PT‑BR.
 

docs/OPERATIONS.md

@@ -0,0 +1,144 @@
+# Operações — Sistema de Chamados (Prod)
+
+Este documento consolida as mudanças recentes, o racional por trás delas e o procedimento de operação/deploy (Web e Convex self‑hosted) do ambiente em produção.
+
+## 1) Mudanças Funcionais (Front + Server)
+
+- Empresas (admin)
+  - “Slug” renomeado para “Apelido” (mensagens e placeholders ajustados).
+
+- Fila padrão ao criar tickets
+  - Todo novo ticket entra na fila “Chamados”.
+  - Implementado no backend (fallback) e pré‑seleção na UI.
+
+- Status de tickets e interações
+  - Nomes/cores atualizados:
+    - Pendente (cinza), Em andamento (azul), Pausado (amarelo), Resolvido (verde).
+  - Transições automáticas:
+    - Iniciar (play) → status “Em andamento”.
+    - Pausar → status “Pausado”.
+  - “Encerrar” permanece manual. O dropdown foi substituído por badge + botão “Encerrar”.
+  - Diálogo de encerramento: botão “Cancelar” adicionado (além de “Limpar mensagem”/“Encerrar ticket”).
+
+- Dashboard — Últimos chamados
+  - Prioridade: sem responsável primeiro (dos mais antigos para os mais recentes), depois demais chamados.
+
+- Filtros de tickets
+  - Filtro por “Responsável” (agente/admin) adicionado.
+  - Salvar filtro como padrão por usuário (localStorage) + “Limpar padrão”.
+  - Empresas no filtro: lista completa via API admin (não só empresas presentes em tickets).
+  - Produção: filtro “Responsável” agora é feito no servidor (assigneeId); o front não envia mais parâmetros inválidos.
+
+- Editor de comentários (Tiptap)
+  - Correção: reativar edição quando um responsável é atribuído (o editor agora reflete mudanças em `disabled` via `setEditable`).
+
+## 2) Convex (Self‑Hosted) — Ajustes e Motivo
+
+- Problema observado: deploy do Convex falhava no CI por:
+  - Ausência de `convex.json` (link do projeto) no servidor.
+  - Uso incorreto de `CONVEX_DEPLOYMENT` junto a `CONVEX_SELF_HOSTED_URL` + `CONVEX_SELF_HOSTED_ADMIN_KEY` (não suportado pelo CLI ao usar self‑hosted).
+  - Divergência de schema (campo `provisioningCode` já existente nos dados, mas ausente no schema do Convex no servidor).
+
+- Medidas aplicadas:
+  - Atualização do schema do Convex no servidor: inclusão de `provisioningCode?: string` na tabela `companies` (e índice opcional `by_provisioning_code`).
+  - Criação do link de projeto (`convex.json`) no servidor via wizard do CLI (ver Passo a passo abaixo).
+  - Ajustes no workflow do GitHub Actions para self‑hosted:
+    - Adicionado passo “Acquire Convex admin key” no job de deploy do Convex.
+    - Removido `CONVEX_DEPLOYMENT` quando `CONVEX_SELF_HOSTED_URL` + `CONVEX_SELF_HOSTED_ADMIN_KEY` estão definidos.
+    - Cópia automática do `convex.json` de `/srv/apps/sistema` para o diretório de build temporário.
+  - Forçar redeploy das funções: tocar arquivos sob `convex/**` para acionar o filtro do job “Deploy Convex functions”.
+
+## 3) CI/CD — Visão Geral
+
+- Pipeline “CI/CD Web + Desktop” (GitHub Actions)
+  - Job “Detect changes” usa filtros por paths.
+  - Job “Deploy (VPS Linux)” cuida do Web (Next.js) e stack do Swarm.
+  - Job “Deploy Convex functions” roda quando há mudanças em `convex/**` ou via `workflow_dispatch`.
+    - Passos relevantes:
+      - “Acquire Convex admin key” (via container `sistema_convex_backend`).
+      - “Bring convex.json from live app if present” (usa o arquivo de link do projeto em `/srv/apps/sistema`).
+      - “convex env list” e “convex deploy” com `CONVEX_SELF_HOSTED_URL` + `CONVEX_SELF_HOSTED_ADMIN_KEY`.
+    - Importante: não usar `CONVEX_DEPLOYMENT` em conjunto com URL + ADMIN_KEY.
+
+- Como forçar o deploy do Convex
+  - Faça uma alteração mínima em `convex/**` (ex.: comentário em `convex/tickets.ts`) ou rode o workflow em “Run workflow” (workflow_dispatch).
+
+## 4) Convex — Provisionamento inicial (self‑hosted)
+
+Executar apenas 1x na VPS para criar o link do projeto (`convex.json`):
+
+```bash
+cd /srv/apps/sistema
+export CONVEX_SELF_HOSTED_URL="https://convex.esdrasrenan.com.br"
+CID=$(docker ps --format '{{.ID}} {{.Names}}' | awk '/sistema_convex_backend/{print $1; exit}')
+export CONVEX_SELF_HOSTED_ADMIN_KEY="$(docker exec -i "$CID" /bin/sh -lc './generate_admin_key.sh' | tr -d '\r' | grep -o 'convex-self-hosted|[^ ]*' | tail -n1)"
+
+npx convex dev --once --configure=new
+# Siga o wizard (self-hosted) e vincule/crie o projeto/deployment (ex.: "sistema" / "default").
+# Isso gera /srv/apps/sistema/convex.json
+```
+
+Depois disso, o job “Deploy Convex functions” funciona em modo não interativo.
+
+## 5) VPS — Acesso e Serviços
+
+- Acesso
+  - Host: `31.220.78.20`
+  - Usuário: `root`
+  - Chave SSH (repo raiz): `./codex_ed25519` (Atenção: manter permissões 600)
+    - Exemplo: `ssh -i ./codex_ed25519 root@31.220.78.20`
+  - Opcional (endurecimento): desabilitar login por senha após validar a chave.
+
+- Diretórios principais
+  - Código do app: `/srv/apps/sistema`
+  - Arquivo do projeto Convex: `/srv/apps/sistema/convex.json`
+  - Stack do Swarm: `stack.yml` (no repositório; aplicado no servidor via CI).
+
+- Serviços (Docker Swarm + Traefik)
+  - Web (Next.js): serviço `sistema_web`, exposto em `tickets.esdrasrenan.com.br`.
+  - Convex backend: serviço `sistema_convex_backend`, exposto em `convex.esdrasrenan.com.br`.
+  - Convex dashboard: `convex-admin.esdrasrenan.com.br`.
+  - Comandos úteis:
+    - `docker service ls`
+    - `docker service ps sistema_web`
+    - `docker service update --force sistema_web` (reiniciar)
+    - `docker service update --force sistema_convex_backend` (reiniciar Convex)
+
+- Convex admin key (diagnóstico)
+  - `docker exec -i $(docker ps | awk '/sistema_convex_backend/{print $1; exit}') /bin/sh -lc './generate_admin_key.sh'`
+  - Usada no CI para `convex env list` e `convex deploy`.
+
+## 6) Notas de Segurança
+
+- A chave privada `codex_ed25519` está na raiz do repo (ambiente atual). Em produção, recomenda‑se:
+  - Remover a chave do repositório ou armazená‑la em Secrets/Deploy keys do provedor.
+  - Desabilitar login por senha no SSH (apenas chave).
+  - Manter permissões: `chmod 600 ./codex_ed25519`.
+
+## 7) Testes, Build e Lint
+
+- Local
+  - `pnpm build` (Next + typecheck)
+  - `pnpm lint`
+  - `pnpm test`
+
+- CI garante build, lint e testes antes do deploy.
+
+## 8) Troubleshooting Rápido
+
+- “No CONVEX_DEPLOYMENT set” durante o deploy do Convex
+  - Certifique‑se de que `/srv/apps/sistema/convex.json` existe (rodar wizard `npx convex dev --once --configure=new`).
+  - Não usar `CONVEX_DEPLOYMENT` com `CONVEX_SELF_HOSTED_URL` + `CONVEX_SELF_HOSTED_ADMIN_KEY`.
+
+- “Schema validation failed” (campo extra `provisioningCode`)
+  - Atualize o schema do Convex no servidor para incluir `provisioningCode?: string` em `companies`.
+  - Refaça o deploy.
+
+- Filtro “Responsável” não funciona
+  - Front envia `assigneeId` e o backend Convex deve aceitar esse parâmetro (função `tickets.list`).
+  - Se necessário, forçar redeploy das funções (`convex/**`).
+
+---
+
+Última atualização: sincronizado após o deploy bem‑sucedido do Convex e do Front (20/10/2025).
+

docs/README.md

@@ -0,0 +1,25 @@
+# Documentação — Sistema de Chamados
+
+Este índice consolida a documentação viva e move conteúdos históricos para um arquivo. O objetivo é simplificar o onboarding e a operação.
+
+## Visão Geral
+- Operações (produção): `docs/operations.md`
+- Guia de desenvolvimento: `docs/DEV.md`
+- Desktop (Tauri):
+  - Build: `docs/desktop/build.md`
+  - Updater: `docs/desktop/updater.md`
+  - Handshake/troubleshooting: `docs/desktop/handshake-troubleshooting.md`
+- Tickets: `docs/ticket-snapshots.md`
+- Administração (UI): `docs/admin/admin-inventory-ui.md`
+
+## Arquivo (histórico/planejamento)
+- `docs/archive/operacao-producao.md` (substituído por `docs/operations.md`)
+- `docs/archive/deploy-runbook.md`
+- `docs/archive/setup-historico.md`
+- `docs/archive/status-2025-10-16.md`
+- `docs/archive/convex-self-hosted-env.md`
+- `docs/archive/plano-app-desktop-maquinas.md`
+- `docs/archive/historico-agente-desktop-2025-10-10.md`
+
+Se algum conteúdo arquivado voltar a ser relevante, mova-o de volta, atualizando a data e o escopo.
+

docs/admin/.gitkeep

@@ -0,0 +1 @@
+

docs/archive/.gitkeep

@@ -0,0 +1 @@
+

docs/archive/convex-self-hosted-env.md

@@ -1,4 +1,6 @@
-Convex Self‑Hosted — Configurar env e testar provisionamento
+Convex Self‑Hosted — Configurar env e testar provisionamento (Arquivo)
+
+Nota: este documento foi arquivado. O fluxo atual de deploy/ops está em `docs/operations.md`.
 
 Pré‑requisitos
 - Rodar na VPS com Docker.
@@ -52,4 +54,3 @@ TOKEN=$(node -e 'try{const j=require("fs").readFileSync("resp.json","utf8");proc
 [ -n "$TOKEN" ] && curl -sS -o /dev/null -w "%{http_code}\n" -X POST 'https://tickets.esdrasrenan.com.br/api/machines/heartbeat' \
   -H 'Content-Type: application/json' \
   -d '{"machineToken":"'"$TOKEN"'","status":"online","metrics":{"cpuPct":12,"memFreePct":61}}'
-

docs/archive/deploy-runbook.md

@@ -1,4 +1,6 @@
-# Deploy runbook (Swarm)
+# Deploy runbook (Swarm) — Arquivo
+
+Nota: este runbook foi arquivado. Utilize `docs/operations.md` para o fluxo atualizado de deploy.
 
 Este guia documenta o fluxo de deploy atual e os principais passos de diagnóstico/correção que resolveram o problema do front não atualizar mesmo com o CI verde.
 

docs/archive/plano-app-desktop-maquinas.md

@@ -1,4 +1,4 @@
-# Plano Integrado – App Desktop & Inventário por Máquina
+# Plano Integrado – App Desktop & Inventário por Máquina (Arquivo)
 
 > Documento vivo. Atualize após cada marco relevante.
 

docs/archive/setup-historico.md

@@ -1,4 +1,6 @@
-# Histórico de Setup e Decisões — Sistema de Chamados
+# Histórico de Setup e Decisões — Sistema de Chamados (Arquivo)
+
+Conteúdo mantido como registro. Para operação e deploy atuais, ver `docs/operations.md`.
 
 > Registro das etapas realizadas, problemas encontrados e decisões tomadas para colocar o projeto em produção (Traefik + Swarm + Convex self‑hosted) com CI/CD via runner self‑hosted.
 

docs/archive/status-2025-10-16.md

@@ -1,4 +1,4 @@
-# Status do Projeto — 16/10/2025
+# Status do Projeto — 16/10/2025 (Arquivo)
 
 Documento de referência sobre o estado atual do sistema (web + desktop), melhorias recentes e pontos de atenção.