Add Cursor rules for project context, PR workflow and code style

.cursor/rules/deliverables-markdown-files.mdc

@@ -0,0 +1,30 @@
+---
+description: Planos, tarefas, Github e descrições de PR como ficheiros MD organizados
+alwaysApply: true
+---
+
+# Entregáveis em Markdown (ficheiros no repositório)
+
+Quando o pedido for **plano**, **descrição de tarefa**, **história ou issue para Jira**, ou **texto de pull request**, **não** limite a resposta ao chat: **crie ficheiros `.md` no projeto**, bem estruturados e reutilizáveis.
+
+## Onde guardar
+
+Use a pasta **`docs/plan`**, com subpastas por tipo (crie-as se não existirem):
+
+| Tipo | Pasta sugerida | Exemplo de nome |
+|------|------------------|-----------------|
+| Plano / roadmap de execução | `docs/plans/` | `YYYY-MM-DD-nome-curto-do-plano.md` |
+| Tarefa / descrição de trabalho | `docs/tasks/` | `YYYY-MM-DD-nome-da-tarefa.md` |
+| Pull request | `docs/pr/` | `pr-nome-do-ramo-ou-tema.md` ou `YYYY-MM-DD-pr-tema.md` |
+
+Se já existir convenção no repositório (prefixos `atividade-`, `docs/github-*`, etc.), **alinhe com ela** em vez de duplicar padrões conflituosos.
+
+## Conteúdo
+
+- **Cabeçalho**: título H1, data (ISO), contexto ou link de ticket quando houver.
+- **Secções claras**: objetivo, âmbito, passos / critérios de aceite, riscos, follow-up — conforme o tipo de documento.
+- **Linguagem**: a mesma do pedido do utilizador (ex.: português), salvo indicação contrária.
+
+## Resposta no chat
+
+Depois de criar ou atualizar os ficheiros, resuma no chat **o caminho dos ficheiros** e o essencial (uma ou duas frases), para o utilizador saber onde editar ou copiar para o GitHub.

.cursor/rules/extract-function-on-reuse.mdc

@@ -0,0 +1,24 @@
+---
+description: Extrair função só quando houver reuso em pelo menos dois trechos
+alwaysApply: true
+---
+
+# Funções apenas com reuso
+
+- **Não** crie funções (nem métodos privados auxiliares) só para “organizar” um único fluxo ou dar nome a um bloco usado **uma vez**.
+- **Crie** uma função quando a mesma lógica for necessária em **dois ou mais** trechos de código (reuso real).
+
+## O que fazer em vez disso
+
+- Deixe o fluxo linear no escopo onde é usado uma vez.
+- Use variáveis com nomes claros e blocos curtos em vez de micro-funções de uso único.
+
+## Exceções raras
+
+- **Framework / contrato**: funções ou métodos que o Django, Celery, etc. exigem como ponto de entrada (view, `action`, task, signal handler) — mesmo com um único registo, a função é o mecanismo obrigatório.
+- **Testes**: fixtures/helpers partilhados por vários testes, conforme o ficheiro.
+- **Código gerado** ou boilerplate obrigatório do projeto.
+
+## Parâmetros
+
+- Não adicionar * nas função a não ser que seja solicitado.

.cursor/rules/no-comments.mdc

@@ -0,0 +1,12 @@
+---
+description: Código sem comentários — nomes e estrutura devem bastar
+alwaysApply: true
+---
+
+# Sem comentários no código
+
+- Não adicione comentários de linha (`#`, `//`, `/* */`, `<!-- -->`, etc.) nem docstrings em código novo ou alterado.
+- Não use comentários para “desligar” linhas ou marcar TODO/FIXME no código; use issues ou tarefas.
+- Prefira nomes claros, funções pequenas e extração de métodos em vez de explicar com comentário.
+
+**Exceções (se o projeto já exigir):** cabeçalhos de licença em arquivos novos, ou comentários gerados por ferramentas que não devem ser editados manualmente.

.cursor/rules/pr-commit.mdc

@@ -0,0 +1,57 @@
+---
+description: Insumo obrigatório em docs/pr e mensagem de commit por tarefa com código
+alwaysApply: true
+---
+
+# Insumo de PR e mensagem de commit (obrigatório)
+
+Em **todo pedido que produza ou altere código** no repositório (implementação, correção, refactor, testes novos), ao **concluir** o trabalho é **obrigatório** criar ou atualizar um ficheiro Markdown de insumo em `docs/pr/`. Não basta descrever só no chat.
+
+Pedidos **apenas informativos** (explicação, revisão sem alterações, perguntas) **não** exigem este ficheiro.
+
+## Onde guardar
+
+- Pasta: **`docs/pr/`** (criar se não existir).
+- Nome: **`YYYY-MM-DD-<tema-curto>.md`** ou **`pr-<nome-do-ramo-ou-tema>.md`**.
+- Um ficheiro por tarefa/sessão de trabalho; se o mesmo ficheiro for reutilizado no mesmo dia/tema, **atualizar** o existente em vez de duplicar.
+
+## Estrutura obrigatória do ficheiro
+
+O insumo deve conter **duas partes**, nesta ordem:
+
+### 1. Mensagem de commit
+
+Secção **`## Mensagem de commit`** com texto **pronto a colar** no `git commit`:
+
+- Primeira linha: resumo imperativo, ≤72 caracteres, em português ou inglês conforme o padrão recente do repositório.
+- Corpo opcional (linhas seguintes): o *porquê* da mudança, não só o *o quê*.
+- Não incluir ficheiros secretos, `.env` ou artefactos locais no âmbito do commit.
+
+### 2. Corpo do PR (template do projeto)
+
+Reproduzir as secções do template oficial:
+
+`.github/PULL_REQUEST_TEMPLATE/pull_request_template.md`
+
+Preencher cada secção com conteúdo concreto da tarefa atual:
+
+| Secção no insumo | Conteúdo esperado |
+|------------------|-------------------|
+| **O que esse PR faz?** | Problema resolvido ou feature entregue. |
+| **Onde a revisão poderia começar?** | Caminho(s) de ficheiro(s) para o revisor abrir primeiro. |
+| **Como este poderia ser testado manualmente?** | Passos numerados reproduzíveis. |
+| **Algum cenário de contexto que queira dar?** | Contexto editorial/técnico, decisões, limitações. |
+| **Screenshots** | Quando aplicável; senão indicar *N/A*. |
+| **Quais são tickets relevantes?** | Issue/Jira ou *N/A*. |
+| **Referências** | RCT, ADR, links externos usados. |
+
+## Comportamento do agente
+
+1. Criar ou atualizar o ficheiro em `docs/pr/` **antes** de encerrar a tarefa (junto com o código, não depois).
+2. No chat, indicar o **caminho do ficheiro** e repetir apenas a **mensagem de commit** (uma ou duas frases).
+3. Ao abrir o PR no GitHub, copiar do insumo as secções do template para a descrição do PR; a mensagem de commit vem da secção **Mensagem de commit**.
+4. Só fazer `git commit` quando o utilizador pedir explicitamente; mesmo sem commit, o insumo em `docs/pr/` é obrigatório.
+
+## Alinhamento
+
+Complementa a regra `deliverables-markdown-files.mdc` (planos, tarefas, PR). Para PRs, este ficheiro de insumo é o entregável **obrigatório** por tarefa com código.

.cursor/rules/project-objectives.mdc

@@ -0,0 +1,48 @@
+---
+description: Objetivos, escopo e princípios do SciELO RCT (MarkAPI)
+alwaysApply: true
+---
+
+# SciELO Research Communication Tools (SciELO RCT)
+
+Plataforma para produção, avaliação e rastreio de objetos de comunicação de pesquisas (manuscritos, preprints, artigos, dados de pesquisa, livros, capítulos). Repositório: `scieloorg/markapi`. O XML SPS é o registro único e rastreável de cada objeto e de cada evento do ciclo editorial.
+
+## Objetivo geral
+
+Cobrir o ciclo completo — da submissão à disseminação — com marcação assistida por IA, avaliação informada, validação, geração de múltiplos formatos e rastreio de eventos no XML, integrando-se de forma agnóstica a sistemas editoriais via API REST (sem obrigar periódicos a trocar OJS, ScholarOne, etc.).
+
+## Objetivos específicos
+
+- Suportar os seis tipos de objeto: manuscrito, preprint, artigo, dado de pesquisa, livro, capítulo.
+- Pipeline DOCX/LaTeX (e ODT como alternativa) → XML SPS com marcação assistida por LLM; revisão humana sempre possível antes de finalizar.
+- Avaliação informada: checklists (CONSORT, PRISMA, STROBE, ARRIVE) e critérios FAIR; resultados registrados no XML com avaliador e timestamp.
+- Rastreio no XML: submissão, parecer, decisão, marcação, validação, publicação — cada evento com timestamp, agente e metadados.
+- Formatos de saída a partir do XML SPS: pacote `.zip` SPS, PDF por idioma, HTML, XML Crossref/PubMed/PMC/Web of Science, JSON DOAJ; correções no XML propagam aos derivados.
+- API REST (JWT) para sistemas externos postarem eventos e operarem documentos; Wagtail embutido para quem não tem sistema editorial.
+- Bases de referência (ORCID, ROR, Fundref, ISSN, licenças, DeCS/MeSH, etc.) para autocomplete, normalização e validação.
+- Integrações SciELO: metadados via scielo.org; publicação via Upload/scms-upload → OPAC 5, com eventos de publicação de volta ao XML.
+- Implantação: desktop, intranet ou internet (Docker Compose / Kubernetes).
+
+## Dentro do escopo
+
+Conversão e marcação; validação e PDF/HTML via packtools; LLM local (llama-cpp) ou remoto (configurável); registro de eventos e avaliação no XML; interface Wagtail; fluxo de revisão por pares nativo opcional; distribuição Docker/K8s.
+
+## Fora do escopo
+
+Substituir à força sistemas de revisão por pares já adotados; custear APIs de LLM de terceiros; desenvolver modelo de IA próprio; gestão de assinaturas ou acesso ao conteúdo publicado.
+
+## Princípios de implementação
+
+- IA auxilia marcação (destaque: referências bibliográficas); humano revisa e corrige; persistir resultados para auditoria e reuso.
+- Integração aditiva: periódicos mantêm seus fluxos; a plataforma é backbone editorial via API.
+- Conformidade SPS: validar com packtools (versão fixada no projeto).
+- Privacidade: preferir LLM on-premise; API externa é responsabilidade da instituição.
+- Stack principal: Python 3, Django 5, Wagtail 6, DRF, Celery + Redis, PostgreSQL, lxml/python-docx + packtools, apps `xml_manager`, `reference`, `model_ai`, `docx_layouts`, `tracker`.
+
+## Critérios de sucesso (referência)
+
+Redução ≥50% no tempo de marcação; ≥90% validação packtools sem erros; ≥85% precisão LLM em referências (amostragem); PDF sem defeitos críticos em revisão amostral; satisfação ≥4/5.
+
+## Especificação completa
+
+Documento de referência: `scielo_rct_v3_updated.docx` (SciELO RCT v4.0). Para detalhes de arquitetura, perfis, cronograma e glossário, consultar o RCT ou pedir `@` do ficheiro em `docs/spec/` quando existir cópia versionada no repositório.

.cursor/rules/python-black-isort.mdc

@@ -0,0 +1,25 @@
+---
+description: Python formatado com Black e imports com isort (pyproject.toml)
+globs: "**/*.py"
+alwaysApply: false
+---
+
+# Black + isort em todo código Python
+
+O projeto define `[tool.black]` e `[tool.isort]` com `profile = "black"` e `line-length = 88` em `pyproject.toml`. Siga isso ao escrever ou alterar `.py`.
+
+## Ao terminar edições em arquivos Python
+
+Rode os dois a partir da raiz do repositório, **nesta ordem** (imports primeiro, formatação depois):
+
+1. `isort <caminhos-dos-arquivos.py>`
+2. `black <caminhos-dos-arquivos.py>`
+
+Isso evita que o Black refaça linhas e o isort precise rodar de novo.
+
+Se o ambiente não tiver os binários no PATH, use os do projeto (`make`/pipx conforme `Makefile`) ou `python -m black` / `python -m isort`.
+
+## Estilo
+
+- Linha máxima **88** caracteres (Black).
+- Imports agrupados de acordo com isort **profile black**, sem conflitar com o Black.