docs: refinamento integral da documentação didática

Índices por jornada, convenções, diagramas Mermaid, correções de
arquitetura (MainShellFrame, TCP/PluginManager), tutoriais com
verificações e troubleshooting; remove redirect pitiupi/docs.

Co-authored-by: Cursor <cursoragent@cursor.com>

docs/documentation/00_convencoes.md

@@ -0,0 +1,32 @@
+# Convenções da documentação
+
+Índice geral: [docs/README.md](../README.md).
+
+## Idioma e tom
+
+- Português brasileiro, termos de Redes e Java como no código (`ConnectionManager`, `MulticastSocket`).
+- Parágrafos completos; evitar listas longas quando um texto curto explica melhor.
+
+## Blocos teoria × implementação
+
+Em capítulos de rede e arquitetura, quando um conceito for central, use mentalmente três camadas:
+
+1. **Teoria** — como o protocolo ou padrão funciona em geral (com link para [references/README.md](../references/README.md) se precisar de fonte).
+2. **No Pitiupi** — classes e fluxo reais.
+3. **Limitação** — o que o projeto **não** faz (ex.: sem criptografia, sem ICMP nativo no plugin Ping).
+
+Não descreva funcionalidade futura como se já existisse.
+
+## Código nos exemplos
+
+- Trechos de tutorial são **ilustrativos** quando indicado; o aluno completa o plugin (ver [17_tutorial_ping_aula.md](17_tutorial_ping_aula.md)).
+- APIs citadas devem existir no núcleo atual (`PluginWorkspace`, `createPlugin(ConnectionManager, PluginWorkspace)`).
+
+## Diagramas
+
+- Preferir [Mermaid](https://github.blog/2014-02-14-render-diagrams-markdown/) em arquivos `.md` (GitHub).
+- Diagramas pequenos, um fluxo por figura.
+
+## Manutenção
+
+Alterou protocolo, SPI ou boot? Atualize o capítulo numerado correspondente e, se for decisão estável, [decision-register.md](../decision-register.md). Ver [13_guia_desenvolvimento.md](13_guia_desenvolvimento.md).

docs/documentation/04_inicializacao_e_gui.md

@@ -62,7 +62,7 @@ A interface gráfica é Swing, organizada em shell (`pitiupi.presentation.shell`
 | Região | Componente |
 |--------|------------|
 | Centro | `TabWorkspacePanel` — aba **Plugins** (galeria; abre plugin sob demanda), abas de plugin **fecháveis** (×), aba **Configurações** |
-| Leste | `NetworkUsersPanel` — “Usuários nesta rede”, badges de convite, peer actions |
+| Leste | `NetworkUsersPanel` — “Usuários nesta rede”, peer actions (badges na lista: **D23**, adiados — ver [decision-register.md](../decision-register.md)) |
 | Sul | Barra de status (porta e nome local) |
 | Menu | `ShellMenuBar` — apenas **Ajuda → Sobre** (sair pelo X da janela) |
 
@@ -77,7 +77,7 @@ Ao iniciar, só as abas **Plugins** e **Configurações** ficam visíveis. Cada
 
 O **chat** usa campo de mensagem compacto (~2 linhas, quebra de linha; barra de rolagem vertical só se o texto não couber). O histórico ocupa a maior parte da altura da aba (divisor proporcional ao abrir a janela).
 
-Canal TCP privado do chat fica no mesmo `ChatPanel` (histórico separado por conversa: sala geral, peer por IP, privado com toggle). A lista lateral usa `PeerActivityInbox` (bolinha vermelha e contagem; no menu, ● na ação correspondente).
+Canal TCP privado do chat fica no mesmo `ChatPanel` (histórico separado por conversa: sala geral, peer por IP, privado com toggle). O núcleo mantém `PeerActivityInbox` para atividade por peer; indicadores visuais completos na lista lateral ainda não fazem parte da v1 (**D23**).
 
 Ao fechar a aba superior de **Compartilhar tela** (×), o núcleo chama `Plugin.onShellTabClosed()` — o plugin interrompe captura e envio (toggle desligado). Reabrir pela galeria deve mostrar compartilhamento inativo.
 
@@ -87,30 +87,66 @@ Textos da UI (destino, combo de forma de envio e linha **“Como esta mensagem v
 
 Ver [12_menus_unicast_multicast.md](12_menus_unicast_multicast.md).
 
-## Diagrama de comunicação
+## Boot (sequência)
 
+```mermaid
+sequenceDiagram
+    participant Main
+    participant Home as PitiupiHome
+    participant Login as LoginDialog
+    participant Shell as MainShellFrame
+    participant CM as ConnectionManager
+    participant PM as PluginManager
+
+    Main->>Home: ensureLayout()
+    Main->>Login: showLogin()
+    Login-->>Main: nome + porta
+    Main->>Shell: new MainShellFrame(nome, porta)
+    Shell->>CM: iniciar UDP/TCP/heartbeat
+    Shell->>PM: carregar JARs SPI
+    PM-->>Shell: createPlugin(cm, workspace)
 ```
-                         +------------------+
-                         |  MainShellFrame  |
-                         +--------+---------+
-                                  |
-             +--------------------+--------------------+
-             |                    |                    |
-             v                    v                    v
-      HeartbeatManager       SocketUDP            SocketTCP
-             |                    |                    |
-             v                    v                    v
-         Heartbeat           UDP Multicast       TCP Connections
-                                  |                    |
-                                  +---------+----------+
-                                            |
-                                            v
-                                         Plugins
-                                            |
-                                            v
-                                        Message
+
+## Camadas de comunicação
+
+```mermaid
+flowchart TB
+    subgraph ui [presentation.shell]
+        Shell[MainShellFrame]
+        Users[NetworkUsersPanel]
+    end
+    subgraph app [application + control]
+        CM[ConnectionManager]
+        HB[HeartbeatManager]
+        Disp[MessageDispatcher]
+    end
+    subgraph net [net]
+        UDP[SocketUDP]
+        TCP[SocketTCP]
+    end
+    subgraph ext [plugins]
+        PL[Plugin JARs]
+    end
+    Shell --> CM
+    Users --> CM
+    CM --> UDP
+    CM --> TCP
+    CM --> HB
+    Disp --> CM
+    PL --> Disp
+    UDP --> PL
+    TCP --> PL
 ```
 
 O UDP multicast sustenta presença e mensagens broadcast/unicast; o TCP sustenta
 canais diretos com framing de mensagens. Detalhes em [05](05_udp_multicast.md)
 e [06](06_tcp_conexoes.md).
+
+### Exemplo: um envio UDP até outro peer
+
+1. Plugin chama `MessageDispatcher` (ou `ConnectionManager`) com `TransportMode` e destino.
+2. Mensagem serializada (`Message.toByteArray()`).
+3. `SocketUDP` monta `DatagramPacket` (multicast `224.0.0.3` ou unicast ao IP do peer).
+4. Peer receptor: thread de `SocketUDP.receive()` desserializa e `PluginManager` entrega ao plugin que declarou o tipo em `getMessages()`.
+
+Ver [07_mensagens_e_serializacao.md](07_mensagens_e_serializacao.md).

docs/documentation/05_udp_multicast.md

@@ -1,5 +1,6 @@
 # Comunicação UDP
 
+**Teoria:** UDP envia datagramas sem conexão; multicast replica um pacote na LAN para todos os membros do grupo. **No Pitiupi:** presença e muitas mensagens de plugins usam o mesmo `MulticastSocket` na porta do login. **Limitação:** sem garantia de entrega nem ordem — plugins com imagens grandes devem considerar perda e MTU.
 
 A classe `SocketUDP` é responsável pela comunicação UDP da aplicação.
 
@@ -20,7 +21,7 @@ O SocketUDP suporta dois modos de envio:
 Durante sua inicialização, o `SocketUDP`:
 
 1. obtém o endereço do grupo multicast;
-2. cria um `MulticastSocket` utilizando a porta configurada na `MainWindow`;
+2. cria um `MulticastSocket` na **porta escolhida no login** (mesma porta TCP da sala);
 3. configura os buffers de envio e recepção;
 4. habilita o reuso do endereço;
 5. ingressa no grupo multicast.
@@ -83,3 +84,30 @@ do grupo multicast e fecha o `MulticastSocket`.
 
 A variável `running` é utilizada para sinalizar que o processo de recepção deve ser
 encerrado.
+
+### Interface de rede
+
+`LocalNetworkInfo.preferredNetworkInterface()` escolhe a interface para o multicast: **Ethernet antes de Wi‑Fi**; em cabo APIPA (`169.254.*`) prioriza esse endereço. Em sala **só Wi‑Fi**, a interface wireless é usada normalmente. Requisito: peers na **mesma sub-rede** e multicast permitido — ver [appendix_portas_e_multicast.md](appendix_portas_e_multicast.md).
+
+### Sequência didática (plugin → peer B)
+
+```mermaid
+sequenceDiagram
+    participant UI as Plugin_UI
+    participant Disp as MessageDispatcher
+    participant CM as ConnectionManager
+    participant UDP as SocketUDP
+    participant LAN as LAN_UDP
+    participant UDPb as SocketUDP_peerB
+    participant PM as PluginManager_peerB
+
+    UI->>Disp: enviar Message + modo + destino
+    Disp->>CM: send UDP
+    CM->>UDP: sendUnicast ou sendMulticast
+    UDP->>LAN: DatagramPacket
+    LAN->>UDPb: receive
+    UDPb->>PM: byte[] desserializado
+    PM->>UI: receiveMessage no plugin
+```
+
+**Falhas comuns:** firewall bloqueando UDP na porta do login; portas diferentes entre peers; isolamento de clientes no Wi‑Fi; WSL num lado e Windows nativo no outro.

docs/documentation/06_tcp_conexoes.md

@@ -1,7 +1,8 @@
 # Comunicação TCP
 
+**Teoria:** TCP oferece fluxo confiável e ordenado entre dois sockets; a aplicação ainda precisa definir **limites de mensagem**. **No Pitiupi:** framing `int` tamanho + bytes serializados. **Limitação:** uma conexão por endereço IP de peer no mapa gerenciado por `TcpConnectionManager`.
 
-A comunicação TCP é implementada pela classe `SocketTCP`.
+A comunicação TCP é implementada principalmente por `SocketTCP`, com o mapa de conexões em `TcpConnectionManager`.
 
 Diferentemente do UDP, o TCP estabelece conexões entre dois peers. Essas conexões 
 são mantidas enquanto forem necessárias e podem ser reutilizadas para o envio de 
@@ -9,12 +10,7 @@ múltiplas mensagens.
 
 A arquitetura utiliza uma conexão TCP persistente por endereço de peer.
 
-O SocketTCP possui um mapa de conexões:
-
-`InetAddress` -> `TcpConnection`
-
-Esse mapa permite localizar rapidamente uma conexão existente para determinado peer e 
-reutilizá-la durante novos envios.
+O `TcpConnectionManager` mantém um mapa `InetAddress` → `TcpConnection`, permitindo reutilizar a mesma conexão para vários envios ao mesmo peer.
 
 ### SocketTCP
 
@@ -85,11 +81,9 @@ SocketTCP
 Dessa forma, uma conexão bloqueada ou aguardando dados não impede que outras conexões
 continuem sendo processadas.
 
-Quando uma mensagem é recebida por uma `TcpConnection`, ela é encaminhada para todos os
-plugins registrados na `MainWindow`.
+Quando uma mensagem é recebida por uma `TcpConnection`, ela é encaminhada ao `PluginManager`, que despacha para os plugins cujo `getMessages()` inclui o tipo.
 
-O plugin responsável pela funcionalidade deve identificar o tipo da mensagem e
-realizar o processamento correspondente.
+O plugin identifica o tipo em `receiveMessage()` e processa na thread adequada (UI via `SwingUtilities.invokeLater` quando necessário).
 
 ### TcpConnection
 
@@ -190,3 +184,20 @@ v
 |
 +---- peer inativo ----> fecha conexão
 ```
+
+```mermaid
+sequenceDiagram
+    participant Sender as TcpConnection_envio
+    participant Stream as DataOutputStream
+    participant Net as TCP
+    participant Recv as TcpConnection_recepção
+
+    Sender->>Stream: writeInt(tamanho)
+    Sender->>Stream: write(bytes)
+    Stream->>Net: fluxo de bytes
+    Net->>Recv: readInt()
+    Recv->>Recv: readFully(N bytes)
+    Recv->>Recv: PluginManager.dispatch
+```
+
+Quando usar TCP no Pitiupi: chat e screencast oferecem TCP na UI; presença continua em UDP. Compare com [05_udp_multicast.md](05_udp_multicast.md) e [16_fundamentacao_redes.md](16_fundamentacao_redes.md).

docs/documentation/07_mensagens_e_serializacao.md

@@ -16,3 +16,18 @@ comportamentos necessários para cada funcionalidade.
 
 A camada de transporte não depende do conteúdo específico das mensagens. Tanto o 
 UDP quanto o TCP recebem mensagens serializadas como `byte[]`.
+
+## Despacho aos plugins
+
+1. **Registro:** cada plugin declara `List<Class<? extends Message>> getMessages()`.
+2. **Recepção UDP:** `SocketUDP` entrega bytes ao `PluginManager`, que usa `PluginObjectInputStream` com o classloader do JAR do plugin.
+3. **Recepção TCP:** `TcpConnection` lê um frame completo e o `PluginManager` tenta o mesmo despacho.
+4. **Tipos desconhecidos:** se nenhum plugin reconhece, a mensagem é ignorada (sem crash do núcleo).
+
+Mensagens de infraestrutura (`HeartbeatMessage`, `GoodbyeMessage`, etc.) são tratadas no núcleo antes ou em paralelo ao despacho de plugins — ver [08_heartbeat_e_presenca.md](08_heartbeat_e_presenca.md).
+
+## Riscos da desserialização Java
+
+Peers devem usar **mesma versão** das classes de mensagem. JARs de plugins devem vir de fonte confiável (instalação local pelo usuário). O núcleo **não** implementa sandbox de desserialização — ver [09_sistema_de_plugins.md](09_sistema_de_plugins.md).
+
+Notas: [references/notas/java_serializacao.md](../references/notas/java_serializacao.md).

docs/documentation/08_heartbeat_e_presenca.md

@@ -1,4 +1,6 @@
-# Heartbeat
+# Heartbeat e presença
+
+**Presença ≠ conexão TCP:** ver um peer na lista lateral significa que heartbeats UDP recentes foram recebidos; ainda assim o primeiro envio TCP pode abrir um novo socket.
 
 ### Heartbeat
 
@@ -60,3 +62,24 @@ Lista de peers ativos
 | 
 +----> Plugins (PeerListener)
 ```
+
+### Parâmetros práticos
+
+| Item | Valor no núcleo | Efeito na sala |
+| --- | --- | --- |
+| Grupo multicast | `224.0.0.3` | Todos na mesma porta participam |
+| Intervalo de envio | ~5 s | Lista atualiza em alguns segundos |
+| Timeout de ausência | ~15 s | Peer some após queda ou fechamento sem goodbye |
+| Goodbye | multicast ao sair | Remove peer mais rápido que só timeout |
+
+Em **Wi‑Fi de laboratório**, heartbeat usa o mesmo multicast que o chat na sala geral — mesma porta no login, mesma sub-rede, sem isolamento AP→AP. Checklist: [appendix_portas_e_multicast.md](appendix_portas_e_multicast.md).
+
+```mermaid
+flowchart LR
+    HM[HeartbeatManager] -->|HeartbeatMessage| UDP[SocketUDP multicast]
+    UDP --> LAN[LAN]
+    LAN --> UDP2[SocketUDP outro peer]
+    UDP2 --> HM2[HeartbeatManager]
+    HM2 --> PS[PresenceService]
+    PS --> UI[NetworkUsersPanel]
+```

docs/documentation/10_tutorial_plugin.md

@@ -1,14 +1,27 @@
 # Tutorial — criar um plugin
 
-Este guia complementa [09_sistema_de_plugins.md](09_sistema_de_plugins.md). Use `plugins/chat` como modelo.
+Complementa [09_sistema_de_plugins.md](09_sistema_de_plugins.md). Exercício guiado completo: [17_tutorial_ping_aula.md](17_tutorial_ping_aula.md). Use `plugins/chat` como **modelo de estrutura** (Ant, SPI, painel).
+
+Os exemplos abaixo são **parciais** — você completa métodos, UI e testes.
+
+## Verificações progressivas
+
+| Etapa | O que fazer | Sucesso | Erro comum |
+| --- | --- | --- | --- |
+| Projeto Ant | Copiar `plugins/chat` → `plugins/meuPlugin`, ajustar JAR | `ant jar` OK | Classpath sem `pitiupi.jar` |
+| Classe `Plugin` | Estender `Plugin`, metadados | Compila | `createPlugin` com assinatura antiga |
+| SPI | `META-INF/services/pitiupi.models.Plugin` | Classe listada no JAR | Arquivo fora de `src/` |
+| Mensagem | Uma classe `extends Message` | Em `getMessages()` | Tipo não registrado → ignorado na rede |
+| Instalação | JAR em `PITIUPI_HOME/plugins` + reinício | Plugin na galeria | Esqueceu reiniciar |
+| Rede | Duas instâncias, portas diferentes | Peer na lista | Portas iguais no mesmo PC ou firewall |
 
 ## 1. Novo projeto
 
-- Copie a pasta `plugins/chat` para `plugins/meuPlugin` (nome à escolha).
-- Ajuste `project.properties` / `build.xml` com o nome do JAR de saída.
-- Mantenha `javac.classpath` apontando para `../pitiupi/dist/pitiupi.jar`.
+- Copie `plugins/chat` para `plugins/meuPlugin`.
+- Ajuste `project.properties` / `build.xml` com o nome do JAR (`dist/pitiupi.meuplugin.jar`).
+- `javac.classpath` → `../../pitiupi/dist/pitiupi.jar` (ou caminho equivalente).
 
-## 2. Classe principal
+## 2. Classe principal (trecho)
 
 ```java
 public class MeuPlugin extends Plugin {
@@ -39,56 +52,72 @@ public class MeuPlugin extends Plugin {
 
     @Override
     public void receiveMessage(Message message) {
-        if (message instanceof MinhaMessage m) { /* ... */ }
+        if (message instanceof MinhaMessage m) {
+            // atualizar UI com SwingUtilities.invokeLater quando necessário
+        }
     }
-
-    // getName, getAuthor, getVersion, getIdentifier
 }
 ```
 
-## 3. Mensagem
+Implemente `getName()`, `getAuthor()`, `getVersion()`, `getIdentifier()` (identificador único na sala).
+
+## 3. Mensagem e envio
 
 ```java
 public class MinhaMessage extends Message implements Serializable {
-    // campos + serialVersionUID recomendado
+    private static final long serialVersionUID = 1L;
+    private final String texto;
+    // construtor, getters
 }
 ```
 
-Envio típico via `ConnectionManager` (multicast ou unicast UDP, ou TCP conforme o caso).
+Envio típico via `MessageDispatcher` (modo `TransportMode` + destino). Exemplo conceitual:
 
-## 4. Service Provider Interface
+```java
+// dentro do painel ou controller, com ConnectionManager injetado:
+dispatcher.send(minhaMsg, TransportMode.UNICAST_UDP, SendTarget.forPeer(ip));
+```
 
-Arquivo `src/META-INF/services/pitiupi.models.Plugin`:
+Detalhes: [07_mensagens_e_serializacao.md](07_mensagens_e_serializacao.md), [12_menus_unicast_multicast.md](12_menus_unicast_multicast.md).
+
+## 4. SPI
+
+`src/META-INF/services/pitiupi.models.Plugin`:
 
 ```
 pacote.MeuPlugin
 ```
 
-## 5. Registrar no catálogo
+Confirme com `jar tf dist/seu.jar | grep META-INF/services`.
 
-Adicione uma entrada em [`plugins.registry.json`](../../plugins.registry.json):
+## 5. Catálogo (opcional para TP)
 
-```json
-{
-  "id": "xadrez",
-  "dir": "pitiupi.xadrez",
-  "build": "ant",
-  "jar": "dist/pitiupi.xadrez.jar",
-  "menuCategory": "Jogos"
-}
-```
-
-O `id` é o que você passa para `./scripts/pitiupi.sh run --plugins xadrez`.
+Para build com `./scripts/pitiupi.sh`, adicione entrada em [`plugins.registry.json`](../../plugins.registry.json). Exercícios locais podem instalar só o JAR pela aba **Configurações**.
 
 ## 6. Build e instalação
 
 ```bash
-./scripts/pitiupi.sh build --plugins xadrez
+cd plugins/meuPlugin && ant jar
+# copiar ou Instalar JAR… na UI; reiniciar o app
 ```
 
-JARs de runtime ficam em `PITIUPI_HOME/plugins` (ver [00_quickstart.md](00_quickstart.md)).
+## 7. Dois cenários de teste
 
-## 7. Próximos passos
+**A — Mesmo computador:** duas instâncias, portas `5000` e `5001`, nomes distintos, mesma versão do JAR.
 
-- [11_plugins_referencia.md](11_plugins_referencia.md) — chat e screenCast
-- [17_tutorial_ping_aula.md](17_tutorial_ping_aula.md) — plugin didático Ping (opcional, fora do commit)
+**B — Dois PCs:** mesma porta (ex. `5000`), mesma sub-rede Wi‑Fi ou cabo, firewall UDP/TCP liberado, mesmo plugin instalado. Ver [appendix_portas_e_multicast.md](appendix_portas_e_multicast.md).
+
+## Problemas comuns
+
+| Sintoma | Causa provável | O que fazer |
+| --- | --- | --- |
+| Plugin não aparece | SPI ausente ou sem reinício | Verificar JAR, reiniciar |
+| `ClassNotFoundException` na rede | Classe de mensagem não em `getMessages()` ou JAR diferente no peer | Alinhar tipos e reinstalar nos dois |
+| Peers não se veem | Porta/sub-rede/multicast | Appendix Wi‑Fi |
+| UI não atualiza | Rede na EDT | `SwingUtilities.invokeLater` |
+| TCP falha | Peer offline ou IP errado | Conferir lista lateral e `PeerIpv4` |
+
+## Próximos passos
+
+- [17_tutorial_ping_aula.md](17_tutorial_ping_aula.md) — exercício Ping (RTT, UDP)
+- [11_plugins_referencia.md](11_plugins_referencia.md) — chat e screencast

docs/documentation/11_plugins_referencia.md

@@ -15,16 +15,36 @@ Dois módulos buildáveis no catálogo; o chat unifica o antigo mpChat (multicas
 
 ## plugins/chat
 
-- Sala geral ou um peer (lista + IP).
-- Transportes: multicast UDP, unicast UDP, TCP via `MessageDispatcher`.
-- Peer actions: abrir sala geral; conversar com peer; canal TCP privado.
-- Caminho: `plugins/chat/src/pitiupi/chat/plugin/ChatPlugin.java`.
+Fluxo resumido:
+
+1. `ChatPlugin.createPlugin` registra `ChatPanel` e peer actions (sala, peer, TCP privado).
+2. Envio: usuário escolhe destino e `TransportMode` → `MessageDispatcher` → UDP ou TCP do núcleo.
+3. Recepção: `ChatMessage` em `receiveMessage` → histórico na aba correta (sala, IP ou canal privado).
+4. TCP privado: toggle desliga o combo de transporte e usa bytes dedicados ao plugin.
+
+Código de entrada: `plugins/chat/src/pitiupi/chat/plugin/ChatPlugin.java`.
+
+```mermaid
+flowchart LR
+    UI[ChatPanel] --> Disp[MessageDispatcher]
+    Disp --> CM[ConnectionManager]
+    CM --> Net[UDP ou TCP]
+    Net --> CM2[ConnectionManager peer]
+    CM2 --> CP[ChatPlugin.receiveMessage]
+    CP --> UI2[ChatPanel peer]
+```
 
 ## plugins/screencast
 
-- Compartilhamento contínuo com destino geral (multicast recomendado) ou um peer (unicast/TCP).
-- Peer actions: compartilhar na rede; compartilhar com este peer.
-- Caminho: `plugins/screencast/src/pitiupi/screenCast/plugin/ScreenCastPlugin.java`.
+Fluxo resumido:
+
+1. Captura de tela em loop (com throttling) → `ScreenCastMessage` com imagem serializada.
+2. Destino geral: multicast; um peer: unicast/TCP conforme painel.
+3. `SessionNoticeMessage` (núcleo) marca início/fim de sessão para fechar abas de recepção.
+
+Código de entrada: `plugins/screencast/src/pitiupi/screenCast/plugin/ScreenCastPlugin.java`.
+
+**Limitação:** largura de banda e MTU — frames grandes podem sofrer perda em UDP; adequado para demonstração, não para produção.
 
 ## Exercício Ping
 

docs/documentation/12_menus_unicast_multicast.md

@@ -1,4 +1,4 @@
-# Menus e ações na lista (histórico)
+# Transporte na UI e peer actions
 
 Na v1 atual, plugins **não** registram menus na barra superior nem submenus legados por categoria.
 

docs/documentation/13_guia_desenvolvimento.md

@@ -31,6 +31,22 @@ Ou na raiz: `./scripts/pitiupi.sh build --all`.
 
 Testes manuais em rede: [15_testes_e_gate.md](15_testes_e_gate.md).
 
+## Documentação viva
+
+Ao alterar comportamento visível ou protocolo:
+
+| Mudou | Atualizar |
+| --- | --- |
+| Boot, shell, abas | `04`, `14` |
+| UDP/multicast/portas | `05`, `appendix` |
+| TCP/framing | `06` |
+| Mensagens/despacho | `07` |
+| Heartbeat/presença | `08`, `decision-register` se constante |
+| SPI / API plugin | `09`, `10` |
+| Plugin de referência | `11` |
+
+Convenções de escrita: [00_convencoes.md](00_convencoes.md).
+
 ## Convenções
 
 - Código e identificadores em inglês (pacotes `pitiupi.*`).

docs/documentation/14_arquitetura_e_manutencao.md

@@ -1,5 +1,38 @@
 # Arquitetura e manutenção
 
+## Visão em camadas
+
+```mermaid
+flowchart TB
+    subgraph presentation [presentation.shell]
+        Login[LoginDialog]
+        Shell[MainShellFrame]
+    end
+    subgraph control [control]
+        CM[ConnectionManager]
+        HB[HeartbeatManager]
+        PM[PluginManager]
+    end
+    subgraph application [application]
+        Disp[MessageDispatcher]
+        Presence[PresenceService]
+    end
+    subgraph netlayer [net]
+        UDP[SocketUDP]
+        TCP[SocketTCP]
+    end
+    Login --> Shell
+    Shell --> CM
+    CM --> UDP
+    CM --> TCP
+    CM --> HB
+    CM --> PM
+    PM --> Disp
+    HB --> Presence
+```
+
+Boot detalhado: [04_inicializacao_e_gui.md](04_inicializacao_e_gui.md).
+
 ## Onde editar
 
 | Comportamento | Pacote / classe |

docs/documentation/16_fundamentacao_redes.md

@@ -45,8 +45,20 @@ SPI e classloader por JAR — padrão de plug-in em aplicações Java.
 
 Doc: [09_sistema_de_plugins.md](09_sistema_de_plugins.md).
 
+## Quando o Pitiupi usa cada transporte
+
+| Situação | Transporte típico | Motivo |
+| --- | --- | --- |
+| Lista de usuários / heartbeat | UDP multicast | Todos os peers sem conexão prévia |
+| Sala geral (chat, ping broadcast) | UDP multicast ou cópias unicast/TCP conforme combo | Didático: aluno vê diferença na UI |
+| Mensagem para um IP | UDP unicast ou TCP | Destino explícito |
+| Fluxo contínuo (tela, TCP privado chat) | TCP | Fluxo e framing no núcleo |
+
+UDP não é “sempre mais rápido” nem TCP “resolve tudo”: perda e ordem ainda importam na aplicação; TCP adiciona handshake e estado por peer.
+
 ## Leitura complementar
 
 - [references/notas/udp_vs_tcp.md](../references/notas/udp_vs_tcp.md)
+- [references/README.md](../references/README.md) (bibliografia)
 - [references/notas/multicast_lan.md](../references/notas/multicast_lan.md)
 - [references/notas/java_spi_plugins.md](../references/notas/java_spi_plugins.md)

docs/documentation/17_tutorial_ping_aula.md

@@ -2,7 +2,7 @@
 
 Exercício para montar o plugin **mais simples** do Pitiupi: medir **RTT** (tempo de ida e volta) com mensagens `Ping` / `Pong` na rede, igual a um `ping` de laboratório — mas usando o **mesmo mecanismo de plugins** do chat e do screencast.
 
-A solução Java **não** entra no Git: só este tutorial e [`plugins/ping/README.md`](../../plugins/ping/README.md). O professor valida localmente; o aluno implementa no próprio `plugins/ping/` (gitignored).
+A solução completa **não** entra no repositório público: o aluno desenvolve em `plugins/ping/` na máquina local (fora do gate CI). Este tutorial traz escopo, trechos e verificações — você implementa o restante.
 
 Índice: [README.md](README.md) · Plugins de referência: [11_plugins_referencia.md](11_plugins_referencia.md).
 
@@ -133,6 +133,17 @@ Instalação usa o mesmo `PluginStore` da aba **Configurações** (`installFromF
 
 O chat usa a mesma ideia de abas de sessão, mas adiciona roteamento TCP privado e HTML. No Ping mantenha **só** UDP e texto em `JTextArea` — ideal para entender o fluxo antes de copiar padrões para um plugin novo.
 
+## Problemas comuns (Ping)
+
+| Sintoma | Diagnóstico |
+| --- | --- |
+| RTT não aparece | `Pong` sem `pingId` correspondente em `pendingByPingId` |
+| Peer não recebe | Tipo não listado em `getMessages()` ou UDP bloqueado |
+| `ClassCastException` | Versões diferentes do JAR entre PCs |
+| Aba não abre | Esqueceu `bindShellWorkspaceContent` ou peer action só abre UI (envio é no painel) |
+
+Mais geral: [10_tutorial_plugin.md](10_tutorial_plugin.md#problemas-comuns).
+
 ## Checklist do aluno
 
 - [ ] SPI e `getIdentifier` únicos

docs/documentation/README.md

@@ -1,28 +1,26 @@
 # Documentação técnica — Pitiupi
 
-Referência para **código Java**, **rede P2P** e **plugins**. Índice geral: [docs/README.md](../README.md).
+Índice geral: [docs/README.md](../README.md) · Convenções: [00_convencoes.md](00_convencoes.md).
 
-## Ordem sugerida
+## Por área
+
+| Área | Arquivos |
+| --- | --- |
+| **Início** | [00_quickstart](00_quickstart.md), [01_visao_disciplina_e_tp](01_visao_disciplina_e_tp.md), [02_modulos](02_modulos_do_repositorio.md), [03_build](03_build_ant_netbeans.md) |
+| **Arquitetura e GUI** | [04_inicializacao_e_gui](04_inicializacao_e_gui.md), [13_guia_desenvolvimento](13_guia_desenvolvimento.md), [14_arquitetura_e_manutencao](14_arquitetura_e_manutencao.md) |
+| **Rede** | [05_udp_multicast](05_udp_multicast.md), [06_tcp_conexoes](06_tcp_conexoes.md), [07_mensagens](07_mensagens_e_serializacao.md), [08_heartbeat](08_heartbeat_e_presenca.md), [16_fundamentacao_redes](16_fundamentacao_redes.md), [appendix_portas_e_multicast](appendix_portas_e_multicast.md) |
+| **Plugins** | [09_sistema_de_plugins](09_sistema_de_plugins.md), [10_tutorial_plugin](10_tutorial_plugin.md), [17_tutorial_ping_aula](17_tutorial_ping_aula.md), [11_plugins_referencia](11_plugins_referencia.md), [12_transporte_e_peer_actions](12_menus_unicast_multicast.md) |
+| **Qualidade** | [15_testes_e_gate](15_testes_e_gate.md), [engineering_backlog](engineering_backlog.md) |
+
+## Ordem linear (referência)
 
 | # | Arquivo | Conteúdo |
 | --- | --- | --- |
 | 0 | [00_quickstart.md](00_quickstart.md) | Build, plugins, duas instâncias |
-| 1 | [01_visao_disciplina_e_tp.md](01_visao_disciplina_e_tp.md) | Uso na disciplina e trabalho prático |
-| 2 | [02_modulos_do_repositorio.md](02_modulos_do_repositorio.md) | Núcleo e três plugins de referência |
-| 3 | [03_build_ant_netbeans.md](03_build_ant_netbeans.md) | Ant e NetBeans (núcleo + plugins) |
-| 4 | [04_inicializacao_e_gui.md](04_inicializacao_e_gui.md) | Boot, MainWindow, diagrama |
-| 5 | [05_udp_multicast.md](05_udp_multicast.md) | SocketUDP |
-| 6 | [06_tcp_conexoes.md](06_tcp_conexoes.md) | SocketTCP, TcpConnection, framing |
-| 7 | [07_mensagens_e_serializacao.md](07_mensagens_e_serializacao.md) | Classe Message |
-| 8 | [08_heartbeat_e_presenca.md](08_heartbeat_e_presenca.md) | HeartbeatManager |
-| 9 | [09_sistema_de_plugins.md](09_sistema_de_plugins.md) | Plugin, PluginManager, SPI |
-| 10 | [10_tutorial_plugin.md](10_tutorial_plugin.md) | Passo a passo novo plugin |
-| 11 | [11_plugins_referencia.md](11_plugins_referencia.md) | chat e screencast |
-| 17 | [17_tutorial_ping_aula.md](17_tutorial_ping_aula.md) | Exercício Ping (aula) |
-| 12 | [12_menus_unicast_multicast.md](12_menus_unicast_multicast.md) | MenuCategory e ações |
-| 13 | [13_guia_desenvolvimento.md](13_guia_desenvolvimento.md) | Guia de desenvolvimento |
-| 14 | [14_arquitetura_e_manutencao.md](14_arquitetura_e_manutencao.md) | Onde editar cada comportamento |
-| 15 | [15_testes_e_gate.md](15_testes_e_gate.md) | Build gate e testes manuais |
-| 16 | [16_fundamentacao_redes.md](16_fundamentacao_redes.md) | Teoria ↔ código |
-| — | [appendix_portas_e_multicast.md](appendix_portas_e_multicast.md) | Portas, multicast, WSL |
-| — | [engineering_backlog.md](engineering_backlog.md) | Débitos técnicos |
+| 1–3 | 01–03 | Disciplina, módulos, Ant |
+| 4 | [04_inicializacao_e_gui.md](04_inicializacao_e_gui.md) | Boot, `MainShellFrame`, shell Swing |
+| 5–8 | 05–08 | UDP, TCP, mensagens, presença |
+| 9–12 | 09–12 | Plugins, tutoriais, transporte na UI |
+| 13–15 | 13–15 | Dev, manutenção, testes |
+| 16–17 | 16–17 | Fundamentação redes, exercício Ping |
+| — | [appendix_portas_e_multicast.md](appendix_portas_e_multicast.md) | Portas, Wi‑Fi, WSL |