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.

Docs em pt · en · es: os de usuário da lista DOCS_I18N (docs/i18n.sh) têm tradução em en/ e es/, que muda no mesmo commit do PT: bash docs/i18n.sh diff <DOC>, aplicar, bash docs/i18n.sh stamp <DOC>. O server/test/smoke-docs-i18n.sh reprova tradução atrasada. Regras e estilo em I18N.md, seção "Documentação".

• 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.
• VIRTUAL.md — participação virtual: refazer um contest encerrado contra o placar oficial (portão, regra de desistência, feed, motor do placar)
• SCOREBOARD.md — formato do TXT de placar e como adicionar um modo
• I18N.md — idiomas da interface (pt · en · es): T(pt, en, es), data-en/data-es, LOCALE do contest, o que o servidor traduz (papel, relatório, DM, Central) e o glossário do espanhol; seção "Documentação": os docs de usuário em en/es e como mantê-los (updatescore-<modo>.sh + score-<modo>.js).
• DEPLOY.md — nginx + fcgiwrap + units systemd (daemon judged, bot) + juízes pull e o subdomínio de contest.
• PULL-REQUESTS.md — como revisar, decidir e aplicar pull requests nos repos do MOJ (revisão adversária, decisão PR a PR, worktree, testes nos dois jq, merge e comentários) e o checklist de quem contribui.
• 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 contextual de ajuda): a tabela de linguagens é gerada da lista real e a página é trilíngue (pt/en/es). 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-ANIMEITOR.md: quem opera o telão (.animeitor): chaves de streaming, fotos e músicas dos times, foto/música padrão, cerimônia. O técnico é o WEBCAST.md.
• 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)