Brief — Pedido de nova atividade de laboratório

Cole este brief junto com o pedido e preencha só o que muda (tema e tarefas). Ele define o padrão fixo do curso; o assistente entrega a aula pronta e validada.

Contexto e stack

• Plataforma: ESP32 · Ambiente: PlatformIO (VS Code) · Framework: Arduino.
• Simulador: Wokwi (sem placa física). Broker/telemetria: stack Docker (Mosquitto + Node-RED + MQTT Explorer).
• Documentação: Docusaurus em MDX. Entrega/correção: Git + GitHub Actions, por commit.
• Organização: ELT85B-N21-2026-2. Repos por aula: labNN-template, labNN-grupo-a/b/c…, e labNN-grupo-n = repositório de notas/correção daquela aula (mesmo padrão para projeto-*).
• Tipo de aula: a maioria é embarcada (ESP32/Wokwi), mas há aulas somente de ferramentas (ex.: Lab 00 — git/GitHub/gh/Markdown). Nessas, não há PlatformIO/Wokwi/firmware; o "produto" é outro artefato (ex.: README.md). Diga no pedido qual é o caso.

Formato do documento (MDX Docusaurus)

• Front matter completo (id, title, sidebar_label, sidebar_position, slug, keywords).
• Avisos como admonitions (:::info/tip/warning/danger/note); <Tabs>/<TabItem> quando útil; diagramas em mermaid (requer @docusaurus/theme-mermaid).
• import CommitPoint from '@site/src/components/CommitPoint'; no topo.
• Code blocks com title="...". Seções típicas: Objetivos, Material, Setup, Partes (experimentos com saída esperada), Projeto integrador, Desafios D1–D4, Gabarito (em <details> atrás de :::danger Spoiler), Checklist.
• Regra MDX (crítica): todo código com <, >, {, }, & fica em blocos/backticks; nunca use esses caracteres nas strings task="..." dos CommitPoint (ex.: escreva "citacao e regra horizontal", não "citacao (>) e (---)"). Para mostrar um bloco de código dentro de outro, use quatro crases no bloco externo.
• Nota :::info explicando quando o código fica em setup() (demonstração única) vs loop() (comportamento contínuo). Só em aulas embarcadas — omitir quando não houver firmware.

Abertura da aula (padrão fixo)

• Ambiente de desenvolvimento: não repita comandos de instalação inline. Use os componentes reutilizáveis (fonte única de verdade):
  • import {LabSetup, LabLogout} from '@site/src/components/InstructionsSite';
  • <LabSetup /> no topo → admonition "Antes de começar" (procedimento numerado: instalar → configurar → verificar + verificação rápida git --version && gh auth status && code -v).
  • <LabLogout /> no fim → admonition "Ao terminar" (logout, importante em máquina de laboratório compartilhada).
  • Distinguir uma vez por máquina (config) vs a cada aula (verificação).
• Âncoras estáveis no /lab/intro (evita link podre ao reescrever títulos): {#setup}, {#git-config}, {#verify}, {#logout}.
• Clone + entrega: <LabTeamMembers labName="labNN" /> (cria/clona o repo do grupo) e <LabSubmit labName="labNN" /> (envio do link no Moodle). Esses componentes são globais no site (não precisam de import no MDX).

Wokwi (apenas aulas com circuito)

• Incluir diagram.json (circuito) e wokwi.toml (.pio/build/<env>/firmware.bin e .elf). Fluxo: Build → "Wokwi: Start Simulator". Recompilar antes de simular.
• WiFi no Wokwi: SSID Wokwi-GUEST, senha vazia; broker público (broker.hivemq.com:1883). Broker local no Wokwi exige o IoT Gateway (Wokwi Club). ESP32 físico → broker local direto (IP da máquina, não localhost).
• (Opcional) Verificação de saída serial no CI: cenário test/*.test.yaml (wait-serial) + WOKWI_CLI_TOKEN.
• Aula sem circuito: pular esta seção inteira. O labNN-template traz então só os arquivos do artefato-alvo (ex.: README.md inicial, .gitignore, .vscode/extensions.json, evidencias/.gitkeep).

Pontos de commit (componente CommitPoint)

• Marcar cada tarefa avaliada: <CommitPoint task="descrição" pontos={N} />. Numeração automática T1…Tn na ordem do documento.
• Props: type, files (multi: files="a.cpp b.ini"), prefix, push, n, id (âncora), allowEmpty (deploy/release, sem mudar arquivos), run (comando extra, ex.: alias de deploy).
• Convenção: 1 tarefa = 1 commit cuja mensagem começa com Tn:. Vale o commit Tn: mais recente; refazer > desfazer; nunca push --force no repo de grupo.
• Passos de runtime (subir stack, testar MQTT, deploy, comandos git/gh) → salvar evidência em evidencias/*.txt (checável) ou allowEmpty.
• Alinhamento MDX × mensagem de commit: o Tn gerado pela ordem dos CommitPoint deve casar com o Tn: escrito nos blocos de comando. Conferir após inserir/remover tarefas.

Pontuação (padrão)

• Somar 100 pts (o autograder normaliza p/ 0–10). Ex.: experimentos ~5 cada, projeto 15–25, desafios ~5 cada. Ajustar conforme o nº de tarefas.
• Split usual: Base T1…Tk = 80 pts · Desafios = 20 pts (declarar na nota :::info Pontuação do fim).

Correção automática

• grade.py (no labNN-grupo-n): TAREFAS = token, nome, pontos, checks. Tipos de check: contem, nao_contem, arquivo, compila (pio run, só aulas embarcadas), release (gh api), jobe (executa no sandbox). Correção por commit (git worktree); gera GRADE.md + nota.csv.
• Aulas de Markdown/ferramentas: usar checks de texto sobre o artefato (ex.: no README.md — H1/H2, ênfase, listas, links, imagem, bloco de código, tabela, citação, régua, âncoras). Regex tolerantes (ex.: itálico com * ou _) para não punir formatação válida.
• Repo labNN-grupo-n autoconfigurável: deduz a aula pelo nome, descobre os grupos, corrige em paralelo (reutilizável grade-one.yml + grade-all.yml), lê grupos read-only (org secret STUDENTS_TOKEN), grava boletins em notas/. À prova de adulteração.
• gen_grade.py: gera o scaffold do grade.py a partir dos CommitPoint do MDX (-o grade.py) e tem modo --check (compara MDX × grade.py, aponta divergências — para CI). O grade.py deve conter assert sum(pontos) == 100.
• Lógica pura no Jobe (sem Moodle): mocks Arduino.h/WiFi.h/PubSubClient.h + harness + jobe_test.py (--local/--jobe) para avaliar comportamento (ver brief do Jobe). Firmware real → pio run + Wokwi.

Fluxo ao criar a aula

1. Escrever a aula em MDX com CommitPoint em cada tarefa (validar: gen_grade.py aula.mdx --tarefas-only deve listar T1…Tn com os pontos certos e somar 100).
2. Varrer MDX: nenhum </{ solto fora de código (só JSX de CommitPoint/Tabs/details/LabSetup/LabLogout/LabTeamMembers/LabSubmit); nenhum <>{}& em task="...".
3. Conferir alinhamento Tn (ordem dos CommitPoint) × Tn: das mensagens de commit nos blocos.
4. Se a aula não for embarcada: confirmar que não sobrou resíduo de platformio/wokwi/esp32/firmware/pio run no texto.
5. gen_grade.py aula.mdx -o autograde/grade.py → completar os checks.
6. (Opcional) cenário Wokwi / check jobe no CI.

Modelo de pedido (preencher)

• Tema / número (labNN): …
• Tipo: embarcada (ESP32/Wokwi) · somente ferramentas (sem circuito) …
• Objetivos de aprendizagem: …
• Periféricos/circuito no Wokwi: (LEDs, botões, sensores, I²C/SPI, MQTT…) — ou "sem circuito" …
• Artefato-alvo do template: (firmware src/main.cpp · README.md · outro) …
• Tarefas avaliadas (viram CommitPoint T1…Tn) e pontos de cada: …
• Checagens por tarefa (contem/compila/jobe/saída serial/release/Markdown): …
• Desafios/gabarito? (sim/não) · Usa Docker/Node-RED? (sim/não)

Regras de qualidade do entregável

• Precisão técnica para ESP32 (ex.: int/word = 4 bytes, double = 8 bytes; difere do Uno) — verificar quando o tamanho importa.
• Buscar detalhes de ferramentas que mudam (versões de extensões/plugins, Wokwi, gh, CodeRunner/Jobe) antes de afirmar.
• Código com saída esperada ("preveja antes de rodar"); gabarito testável.
• Validar o que der: extração dos CommitPoint (soma = 100, sem char proibido em task), alinhamento Tn × mensagem, compilação de exemplos, parsing de configs, e — em aulas de Markdown — os checks contra um artefato de exemplo.

# Brief — Pedido de nova atividade de laboratório

Cole este brief junto com o pedido e preencha só o que muda (tema e tarefas). Ele
define o padrão fixo do curso; o assistente entrega a aula pronta e validada.

## Contexto e stack

- **Plataforma:** ESP32 · **Ambiente:** PlatformIO (VS Code) · **Framework:** Arduino.
- **Simulador:** **Wokwi** (sem placa física). **Broker/telemetria:** stack Docker (Mosquitto + Node-RED + MQTT Explorer).
- **Documentação:** Docusaurus em **MDX**. **Entrega/correção:** Git + GitHub Actions, por commit.
- **Organização:** `ELT85B-N21-2026-2`. Repos por aula: `labNN-template`, `labNN-grupo-a/b/c…`, e `labNN-grupo-n` = **repositório de notas/correção** daquela aula (mesmo padrão para `projeto-*`).
- **Tipo de aula:** a maioria é **embarcada** (ESP32/Wokwi), mas há aulas **somente de ferramentas** (ex.: Lab 00 — git/GitHub/gh/Markdown). Nessas, **não** há PlatformIO/Wokwi/firmware; o "produto" é outro artefato (ex.: `README.md`). Diga no pedido qual é o caso.

## Formato do documento (MDX Docusaurus)

- Front matter completo (`id`, `title`, `sidebar_label`, `sidebar_position`, `slug`, `keywords`).
- Avisos como **admonitions** (`:::info/tip/warning/danger/note`); `<Tabs>`/`<TabItem>` quando útil; diagramas em `mermaid` (requer `@docusaurus/theme-mermaid`).
- `import CommitPoint from '@site/src/components/CommitPoint';` no topo.
- Code blocks com `title="..."`. Seções típicas: Objetivos, Material, Setup, Partes (experimentos com saída esperada), Projeto integrador, Desafios D1–D4, Gabarito (em `<details>` atrás de `:::danger Spoiler`), Checklist.
- **Regra MDX (crítica):** todo código com `<`, `>`, `{`, `}`, `&` fica em blocos/backticks; **nunca** use esses caracteres nas strings `task="..."` dos CommitPoint (ex.: escreva "citacao e regra horizontal", não "citacao (>) e (---)"). Para _mostrar_ um bloco de código dentro de outro, use **quatro crases** no bloco externo.
- Nota `:::info` explicando quando o código fica em `setup()` (demonstração única) vs `loop()` (comportamento contínuo). **Só em aulas embarcadas** — omitir quando não houver firmware.

## Abertura da aula (padrão fixo)

- **Ambiente de desenvolvimento:** não repita comandos de instalação inline. Use os componentes reutilizáveis (fonte única de verdade):
  - `import {LabSetup, LabLogout} from '@site/src/components/InstructionsSite';`
  - `<LabSetup />` no **topo** → admonition **"Antes de começar"** (procedimento numerado: instalar → configurar → verificar + verificação rápida `git --version && gh auth status && code -v`).
  - `<LabLogout />` no **fim** → admonition **"Ao terminar"** (logout, importante em máquina de laboratório compartilhada).
  - Distinguir **uma vez por máquina** (config) vs **a cada aula** (verificação).
- **Âncoras estáveis** no `/lab/intro` (evita link podre ao reescrever títulos): `{#setup}`, `{#git-config}`, `{#verify}`, `{#logout}`.
- **Clone + entrega:** `<LabTeamMembers labName="labNN" />` (cria/clona o repo do grupo) e `<LabSubmit labName="labNN" />` (envio do link no Moodle). Esses componentes são globais no site (não precisam de `import` no MDX).

## Wokwi (apenas aulas com circuito)

- Incluir `diagram.json` (circuito) e `wokwi.toml` (`.pio/build/<env>/firmware.bin` e `.elf`). Fluxo: Build → "Wokwi: Start Simulator". Recompilar antes de simular.
- WiFi no Wokwi: SSID `Wokwi-GUEST`, senha vazia; broker **público** (`broker.hivemq.com:1883`). Broker **local** no Wokwi exige o **IoT Gateway** (Wokwi Club). ESP32 físico → broker local direto (IP da máquina, não `localhost`).
- (Opcional) Verificação de saída serial no CI: cenário `test/*.test.yaml` (`wait-serial`) + `WOKWI_CLI_TOKEN`.
- **Aula sem circuito:** pular esta seção inteira. O `labNN-template` traz então só os arquivos do artefato-alvo (ex.: `README.md` inicial, `.gitignore`, `.vscode/extensions.json`, `evidencias/.gitkeep`).

## Pontos de commit (componente CommitPoint)

- Marcar cada tarefa avaliada: `<CommitPoint task="descrição" pontos={N} />`. Numeração **automática** T1…Tn na ordem do documento.
- Props: `type`, `files` (multi: `files="a.cpp b.ini"`), `prefix`, `push`, `n`, `id` (âncora), `allowEmpty` (deploy/release, sem mudar arquivos), `run` (comando extra, ex.: alias de deploy).
- Convenção: **1 tarefa = 1 commit** cuja mensagem começa com `Tn:`. Vale o commit `Tn:` mais recente; refazer > desfazer; nunca `push --force` no repo de grupo.
- Passos de runtime (subir stack, testar MQTT, deploy, comandos git/gh) → salvar **evidência** em `evidencias/*.txt` (checável) ou `allowEmpty`.
- **Alinhamento MDX × mensagem de commit:** o `Tn` gerado pela ordem dos `CommitPoint` **deve** casar com o `Tn:` escrito nos blocos de comando. Conferir após inserir/remover tarefas.

## Pontuação (padrão)

- Somar **100 pts** (o autograder normaliza p/ 0–10). Ex.: experimentos ~5 cada, projeto 15–25, desafios ~5 cada. Ajustar conforme o nº de tarefas.
- Split usual: **Base T1…Tk = 80 pts · Desafios = 20 pts** (declarar na nota `:::info Pontuação` do fim).

## Correção automática

- **`grade.py`** (no `labNN-grupo-n`): `TAREFAS` = `token`, `nome`, `pontos`, `checks`. Tipos de check: `contem`, `nao_contem`, `arquivo`, `compila` (`pio run`, só aulas embarcadas), `release` (gh api), `jobe` (executa no sandbox). Correção **por commit** (`git worktree`); gera `GRADE.md` + `nota.csv`.
- **Aulas de Markdown/ferramentas:** usar checks de texto sobre o artefato (ex.: no `README.md` — H1/H2, ênfase, listas, links, imagem, bloco de código, tabela, citação, régua, âncoras). Regex **tolerantes** (ex.: itálico com `*` ou `_`) para não punir formatação válida.
- Repo `labNN-grupo-n` autoconfigurável: deduz a aula pelo nome, descobre os grupos, corrige em paralelo (reutilizável `grade-one.yml` + `grade-all.yml`), lê grupos **read-only** (org secret `STUDENTS_TOKEN`), grava boletins em `notas/`. À prova de adulteração.
- **`gen_grade.py`**: gera o scaffold do `grade.py` a partir dos CommitPoint do MDX (`-o grade.py`) e tem modo **`--check`** (compara MDX × `grade.py`, aponta divergências — para CI). O `grade.py` deve conter `assert sum(pontos) == 100`.
- **Lógica pura no Jobe (sem Moodle):** mocks `Arduino.h`/`WiFi.h`/`PubSubClient.h` + harness + `jobe_test.py` (`--local`/`--jobe`) para avaliar comportamento (ver brief do Jobe). Firmware real → `pio run` + Wokwi.

## Fluxo ao criar a aula

1. Escrever a aula em MDX com `CommitPoint` em cada tarefa (validar: `gen_grade.py aula.mdx --tarefas-only` deve listar T1…Tn com os pontos certos e **somar 100**).
2. Varrer MDX: nenhum `<`/`{` solto fora de código (só JSX de `CommitPoint`/`Tabs`/`details`/`LabSetup`/`LabLogout`/`LabTeamMembers`/`LabSubmit`); nenhum `<>{}&` em `task="..."`.
3. Conferir alinhamento `Tn` (ordem dos CommitPoint) × `Tn:` das mensagens de commit nos blocos.
4. Se a aula **não** for embarcada: confirmar que não sobrou resíduo de `platformio`/`wokwi`/`esp32`/`firmware`/`pio run` no texto.
5. `gen_grade.py aula.mdx -o autograde/grade.py` → completar os `checks`.
6. (Opcional) cenário Wokwi / check `jobe` no CI.

## Modelo de pedido (preencher)

- **Tema / número (`labNN`):** …
- **Tipo:** embarcada (ESP32/Wokwi) · somente ferramentas (sem circuito) …
- **Objetivos de aprendizagem:** …
- **Periféricos/circuito no Wokwi:** (LEDs, botões, sensores, I²C/SPI, MQTT…) — _ou_ "sem circuito" …
- **Artefato-alvo do template:** (firmware `src/main.cpp` · `README.md` · outro) …
- **Tarefas avaliadas** (viram `CommitPoint` T1…Tn) e **pontos** de cada: …
- **Checagens por tarefa** (`contem`/`compila`/`jobe`/saída serial/`release`/Markdown): …
- **Desafios/gabarito?** (sim/não) · **Usa Docker/Node-RED?** (sim/não)

## Regras de qualidade do entregável

- Precisão técnica **para ESP32** (ex.: `int`/`word` = 4 bytes, `double` = 8 bytes; difere do Uno) — verificar quando o tamanho importa.
- Buscar detalhes de ferramentas que mudam (versões de extensões/plugins, Wokwi, `gh`, CodeRunner/Jobe) antes de afirmar.
- Código com saída esperada ("preveja antes de rodar"); gabarito testável.
- Validar o que der: extração dos CommitPoint (soma = 100, sem char proibido em `task`), alinhamento Tn × mensagem, compilação de exemplos, parsing de configs, e — em aulas de Markdown — os checks contra um artefato de exemplo.