docs/ — Documentação do MOJ

Índice da documentação da versão API-first do MOJ. Para ler em HTML (com TOC e navegação), rode bash docs/build-html.sh e abra docs/html/index.html.

Mantenha em dia (doc atrasada = bug): toda mudança de comportamento ou contrato atualiza a doc no mesmo commit — rotas/campos em API.md e em ../web/api/openapi.json (os dois em sincronia); arquitetura/fluxo em OVERVIEW.md/FLOW.md; regras de trabalho nos CLAUDE.md.

• OVERVIEW.md — comece aqui. Visão geral: arquitetura, estrutura do repositório, camada de API, frontend e tudo o que existe (treino, criação de contest, ambiente de contest, juiz/daemons).
• FLOW.md — fluxo de comunicação: como uma submissão viaja do browser ao placar — spool, daemon judged, a fila/claim pull (sched-lib.sh), os juízes puxando por heartbeat e o placar.
• API.md — referência das rotas /api/v1/... (entrada/saída, auth, papéis). Versão de máquina: ../web/api/openapi.json (servida em /api/ na web).
• PACOTE.md — fonte única do formato do pacote de problema: o que é cada arquivo (enunciado, tests/, sols/, scripts/, conf), os metadados (.moj-meta.json e .moj-id), o que são orgs (acesso) e coleções (agrupamento), e o ciclo validar → calibrar → publicar. O roteiro prático de montar um pacote fica no README.md do mojtools.
• SCOREBOARD.md — formato do TXT de placar e como adicionar um modo (updatescore-<modo>.sh + score-<modo>.js).
• DEPLOY.md — nginx + fcgiwrap + units systemd (daemon judged, bot) + juízes pull e o subdomínio de contest.
• ADMIN.md — manual do administrador: instalação do zero num servidor limpo (podman/bare-metal), segredos e o bootstrap do treino + primeira conta .admin.
• PLAN.md — plano original aprovado da reescrita (arquitetura, contratos, modos de placar, fases). Referência histórica da migração.

A especificação de design original (telas/contratos) foi a base histórica para web/ e os handlers de server/; hoje o contrato vivo é docs/API.md + web/api/openapi.json.

Manuais de usuário

Voltados ao usuário final, em português simples e sem travessão:

• MANUAL-TREINO.md: o aluno no Treino Livre (cadastro por Telegram, busca, enviar solução, perfil, estatísticas).
• MANUAL-CONTEST.md: o competidor num contest (entrar, enviar, placar, clarifications, impressão, backup).
• MANUAL-LINGUAGENS.md: como enviar em cada linguagem e como funciona a entrada/saída. Virou página do site (/treino/ajuda/, o link "Ajuda" do menu): a tabela de linguagens é gerada da lista real e a página é bilíngue. Este .md é só o ponteiro.
• MANUAL-STAFF.md: a equipe de sala (.staff e .cstaff): fila de impressão, balões, etiquetas, revelação por sede.
• MANUAL-JUIZ.md: os juízes (.judge e .cjudge): fila de avaliação, votos, conflitos, painel do chefe.

Compilar em HTML

bash docs/build-html.sh     # -> docs/html/*.html + index.html  (usa pandoc)