desenvolvimento pre-lancamento

Commit inicial - add do repo privado para o repo NT

style: changes header's logo and colors

style: changes home page first session layout

feat: creates about us home page section

chore: creates home page section for whom

chore: creates student materails home page section

chore: creates teachers materials home page section

chore: creates teacher materials home page section

style: changes primary color

style: changes color at activities page

style: changes about page color

style: changes name to Decoda

fix: changes route to about page at footer

fix: changes background color

style: changes game page header colors

style: changes footer colors

chore: adds home page sections title

style: changes main font family to Lato

style: adds title font

fix: changes sizes to be more responsive for mobile

ajuste no build vercel

atualiza regras envio homol

Adiciona instrucoes de uso

add JupyterLite

fix solucao turtle

Add Mole Mash e Modal de Falhas

Add Progress Bar na pagina de Atividades

fix game name

chore: atualiza lockfile removendo vercel analytics

inclusão de efeito ao mudar de fase

add mecanismo de solução de fases em debug

vite config test

add BaseGame e refator do MoleMash

refatoração turtle

refatoração automato

refatoração automato

add tag

bug 1 e 2 automato

mostrar apenas games em homologação na pagina de atividades

aumentar timeout das fases finais do Turtle

fix bug scroll

add video

refactor semaforo

arrumar ordem das cores

add build docs

update vercel

update vercel

update vercel

update vercel

update vercel

add vercel jupyter

add vercel jupyter

fix deploy Vercel

fix deploy Vercel

fix deploy Vercel

add cripto

add cripto

refatoração

fix tour Mole Mash

.

remover arquivos de controle

chore: adds development tag for activity card

remover arquivos de status indevidamente versionados

atualizar cores nas atividades

add Quebra Cabeças

add Quebra Cabeças

add iniciativas

add Iniciativas

alteração de fotos pesadas

fix menu mobile

fix menu mobile

fix menu mobile

add Aspirador

update icons

update identidade visual documentação

update jupyter

add kernel python local

add kernel python local

add kernel python local

feat: add health check

feat: add primeiros passos

add letramento

mover letramento de lugar

update path games

update path games

fix: ajuste clique rapido no botão executar

remover dead code

fix: refactor: extract shared utilities for storage, phase unlock and mobile detection

stabilize context references and fix stale closure

extrair GameProgressContext do GameStateContext (SRP)

refactor(game): extrair usePhaser e useGameModals de GameBase + corrigir bugs descobertos

refactor(game): remove todos os aliases PT/EN duplicados

Remover aliases PT/EN da camada de modais

refactor + tests

security: add CodeSanitizer and integrate into GameInterpreter

- CodeSanitizer.js: 4 built-in rules (max_length, infinite_while,
  infinite_for, excessive_nesting) with pluggable extra rules
- GameInterpreter.executeCode: calls sanitizeCode() before js-interpreter,
  differentiates CodeSanitizationError (warn) from other errors (error)
- 21 unit tests for CodeSanitizer (100% coverage)
- 4 integration tests in GameInterpreter for sanitization paths

add CodeSanitizer

fix: fase 10 aspirador

fix: bug semaforo

teste

feat: add version

Ajusta a landing page para ficar mais próxima ao protótipo

ajusta raio da borda do botão de Acesse nosso Laboratório

pequenos ajustes de layout na página de iniciativas

atualiza tabela de jogos educativos com os jogos disponíveis atualmente

ajustados pequenos detalhes e informações do jogos na seção de guias pedagógicos

troca nome playground para laboratório e adiciona imagens do lab

adiciona documentação de conceitos básicos de programação

ajustado pequenos erros de digitação

adiciona tooltip com conceitos escondidos em hover na tag +N de conceitos

update docs dev

desativar tour

setup matriz MoleMash

setup matriz MoleMash

fix: link

update version

update docs

update docs

mudou o layout de quem somos

mudei as imgs dos icons e baixei o botao

centraliza titulo com imagem e ajusta sessão com gradiente vermelho-rosa

adiciona responsividade para a pagina quem somos

ajusta botão de conheça nossa história

ajustes

ajustes na home + add. teclado

update version

security

security

feat: add tapume para telas pequenas

v1.1.0

feat: decoda offline

feat: doc offline

offline

fix: ajustes para release

fix: navbar; config ordenação; versão

fix: rotas docs e jupyter para pwa

delete private files

Co-authored-by: Indra Araujo <indra.araujo.santos@gmail.com>
Co-authored-by: solange dos santos <sollangelive71@gmail.com>

docs/.dockerignore

@@ -0,0 +1,5 @@
+node_modules
+build
+.docusaurus
+.vscode
+*.log

docs/.gitignore

@@ -0,0 +1,20 @@
+# Dependencies
+/node_modules
+
+# Production
+/build
+
+# Generated files
+.docusaurus
+.cache-loader
+
+# Misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*

docs/.vscode/settings.json

@@ -0,0 +1,2 @@
+{
+}

docs/Dockerfile

@@ -0,0 +1,16 @@
+FROM node:20-alpine AS builder
+
+WORKDIR /app
+
+RUN npm install -g pnpm
+
+COPY package.json pnpm-lock.yaml ./
+RUN pnpm install
+
+COPY . .
+
+RUN pnpm run build
+
+FROM nginx:alpine
+
+COPY --from=builder /app/build /usr/share/nginx/html

docs/README.md

@@ -0,0 +1,51 @@
+# Decoda - Documentação
+
+Esta documentação é construída usando [Docusaurus](https://docusaurus.io/), um gerador moderno de sites estáticos.
+
+## 📚 Conteúdo
+
+A documentação inclui:
+
+- **Guias para Educadores** (`/edu`) - Material pedagógico, planos de aula e estratégias de ensino
+- **Guias para Desenvolvedores** (`/docs`) - Arquitetura, API e contribuição ao projeto
+
+## 🚀 Desenvolvimento Local
+
+### Pré-requisitos
+
+- Node.js 20 ou superior
+- pnpm
+
+### Instalação
+
+```bash
+pnpm install
+```
+
+### Executar em modo de desenvolvimento
+
+```bash
+pnpm start
+```
+
+Este comando inicia um servidor local e abre automaticamente o navegador. A maioria das mudanças são refletidas ao vivo sem precisar reiniciar o servidor.
+
+Acesse em: http://localhost:3000
+
+### Build
+
+```bash
+pnpm build
+```
+
+Este comando gera o conteúdo estático no diretório `build/` que pode ser servido por qualquer serviço de hospedagem estática (Nginx, Apache, etc).
+
+### Testar build localmente
+
+```bash
+pnpm serve
+```
+
+---
+
+**💡 Dica:** Para rodar toda a plataforma (app + docs) via Docker, veja o [README principal](../README.md) na raiz do repositório.

docs/docs/documentacao/_category_.json

@@ -0,0 +1,14 @@
+{
+  "position": 2,
+  "label": "Documentação",
+  "collapsible": true,
+  "collapsed": true,
+  "className": "red",
+  "link": {
+    "type": "generated-index",
+    "title": "Documentação"
+  },
+  "customProps": {
+    "description": "Entendendo como nossa documentação está organizada e como contribuir"
+  }
+}

docs/docs/documentacao/codigo-aberto.md

@@ -0,0 +1,114 @@
+---
+sidebar_position: 4
+title: "Código Aberto"
+---
+
+Esta página apresenta o contexto de licença da plataforma e as restrições de uso das dependências principais.
+
+## Licença da aplicação
+
+A aplicação está licenciada sob **GNU General Public License v3 (GPL-3.0)**.
+
+```mermaid
+graph LR
+    APP[Decoda
+GPL-3.0] --> USE[Uso livre
+para fins educacionais]
+    APP --> MOD[Modificações devem
+permanecer GPL-3.0]
+    APP --> DIST[Distribuições devem
+incluir código-fonte]
+```
+
+A GPL-3.0 garante liberdade de uso, estudo, modificação e distribuição, mas exige que trabalhos derivados mantenham a mesma licença.
+
+Referência externa: https://www.gnu.org/licenses/gpl-3.0.html
+
+## Licenças das dependências principais
+
+As dependências abaixo têm licenças compatíveis com o uso educacional não comercial, com ressalvas importantes para redistribuição.
+
+| Dependência | Versão usada | Licença | Restrição relevante |
+|---|---|---|---|
+| React | 19.x | MIT | Nenhuma |
+| React Router | 7.x | MIT | Nenhuma |
+| Blockly | 12.x | Apache 2.0 | Atribuição obrigatória |
+| Phaser | 3.90 | MIT | Nenhuma |
+| js-interpreter | 6.x | Apache 2.0 | Atribuição obrigatória |
+| CodeMirror | 6.x | MIT | Nenhuma |
+| TailwindCSS | 3.4 | MIT | Nenhuma |
+| lucide-react | 0.5x | ISC | Nenhuma |
+| Vite | 7.x | MIT | Nenhuma |
+| Docusaurus | 3.x | MIT | Nenhuma |
+
+Referências externas para verificação:
+- Blockly: https://github.com/google/blockly/blob/master/LICENSE
+- js-interpreter: https://github.com/NeilFraser/JS-Interpreter/blob/master/LICENSE
+- Apache 2.0: https://www.apache.org/licenses/LICENSE-2.0
+
+## Restrições e implicações
+
+### O que a GPL-3.0 permite
+
+- Usar a plataforma para ensino, sem restrições.
+- Modificar o código para adaptar ao contexto pedagógico.
+- Distribuir versões modificadas, desde que o código-fonte seja disponibilizado com a mesma licença.
+
+### O que a GPL-3.0 impede
+
+- Distribuir a plataforma como produto proprietário sem disponibilizar o fonte.
+- Integrar o código em sistemas fechados cujo fonte não será publicado.
+
+### Dependências com Apache 2.0 (Blockly e js-interpreter)
+
+A Apache 2.0 é compatível com GPL-3.0 quando a GPL-3.0 é a licença do trabalho resultante. Os requisitos práticos são:
+
+- Incluir cópia da licença Apache 2.0 na distribuição.
+- Manter os avisos de copyright originais.
+- Documentar mudanças feitas nos arquivos originais, se houver.
+
+## Apache 2.0 na prática: o que referenciar e onde
+
+Esta seção resume o mínimo necessário para ficar em conformidade ao redistribuir a plataforma.
+
+### O que precisa ser referenciado
+
+Para cada dependência Apache 2.0 (hoje: Blockly e js-interpreter), mantenha:
+
+1. Nome da biblioteca e URL oficial do projeto.
+2. Licença da biblioteca (Apache License 2.0) com link ou cópia integral.
+3. Aviso de copyright e arquivos NOTICE, quando existirem no projeto original.
+4. Indicação de alterações, se você modificou arquivos do projeto original.
+
+### Onde referenciar
+
+No contexto deste repositório, a recomendação prática é:
+
+1. Em código-fonte: manter `app/LICENSE` para a licença principal da aplicação (GPL-3.0).
+2. Em terceiros: criar um arquivo de avisos, como `app/THIRD_PARTY_NOTICES.md`, listando Blockly e js-interpreter com licença e links.
+3. Em distribuição: incluir no artefato final os arquivos de licença de terceiros (por exemplo, pasta `licenses/` com Apache-2.0 e notices).
+4. Em documentação: manter esta página (`documentacao/codigo-aberto`) como referência funcional para a equipe.
+
+### Checklist rápido de release
+
+```mermaid
+flowchart TD
+    A[Release iniciado] --> B[Conferir libs Apache 2.0]
+    B --> C[Atualizar THIRD_PARTY_NOTICES]
+    C --> D[Incluir LICENSE/NOTICE no artefato]
+    D --> E[Validar links e versões na doc]
+    E --> F[Publicar release]
+```
+
+- `Bibliotecas`: Blockly e js-interpreter ainda são Apache 2.0.
+- `Avisos`: `THIRD_PARTY_NOTICES` atualizado com versão e fonte.
+- `Distribuição`: contém licença Apache 2.0 e notices aplicáveis.
+- `Mudanças`: se houve patch em código Apache 2.0, alteração registrada.
+
+## Diretrizes internas
+
+- Novas dependências devem ter licença MIT, Apache 2.0, BSD ou ISC para manter compatibilidade.
+- Dependências GPL devem ser avaliadas caso a caso - podem criar obrigações adicionais de divulgação.
+- Dependências com licença proprietária ou Creative Commons NC (non-commercial) não devem ser adicionadas sem revisão explícita.
+
+Referência externa sobre compatibilidade de licenças: https://www.gnu.org/licenses/license-compatibility.html

docs/docs/documentacao/entendendo-docusaurus.md

@@ -0,0 +1,69 @@
+---
+sidebar_position: 2
+title: "Trabalhando com Docusaurus"
+---
+
+Esta seção cobre apenas o necessário para manter a documentação técnica do projeto.
+
+## Estrutura relevante
+
+```mermaid
+graph TD
+    A[docs/] --> B[**docusaurus.config.js**
+configuração geral]
+    A --> C[**sidebars.js**
+navegação]
+    A --> D[**docs/**
+doc técnica]
+    A --> E[**edu/**
+doc pedagógica]
+```
+
+- `docs/docusaurus.config.js`: configuração geral.
+- `docs/sidebars.js`: navegação.
+- `docs/docs/`: documentação técnica.
+- `docs/edu/`: documentação pedagógica.
+
+Referência externa:
+
+- Docusaurus docs: https://docusaurus.io/docs
+
+## Fluxo de edição
+
+```mermaid
+flowchart LR
+    A[Editar .md em docs/docs] --> B[Rodar servidor local]
+    B --> C[Revisar navegação e links]
+    C --> D[Rodar build]
+    D --> E[Concluir alteração]
+```
+
+## Comandos
+
+```bash
+cd docs
+pnpm install
+pnpm run start
+```
+
+Build local:
+
+```bash
+cd docs
+pnpm run build
+pnpm run serve
+```
+
+## Boas práticas editoriais
+
+- Prefira frases curtas e diretas.
+- Evite blocos de código longos quando uma explicação curta resolver.
+- Use exemplos apenas quando ajudam a esclarecer uma decisão técnica.
+- Mantenha consistência com a nomenclatura da plataforma: **atividade**.
+
+## Checklist rápido antes de concluir
+
+- O texto está coerente com o código atual?
+- Os links externos apontam para fontes confiáveis?
+- A página está com leitura natural e sem repetição?
+- O build da doc passou sem erro?

docs/docs/documentacao/git-flow.md

@@ -0,0 +1,93 @@
+---
+sidebar_position: 3
+title: "Git Flow"
+---
+
+Esta página descreve o fluxo de branches e processo de contribuição ao repositório.
+
+## Branches principais
+
+```mermaid
+gitGraph
+    commit id: "estado inicial"
+    branch develop
+    checkout develop
+    commit id: "nova funcionalidade A"
+    branch feature/exemplo
+    checkout feature/exemplo
+    commit id: "implementa mudança"
+    commit id: "ajusta detalhe"
+    checkout develop
+    merge feature/exemplo id: "merge via PR"
+    commit id: "prepara pacote"
+    checkout main
+    merge develop id: "release"
+```
+
+| Branch | Propósito |
+|---|---|
+| `main` | Código estável, reflete produção |
+| `develop` | Integração contínua, ponto de partida para features |
+| `feature/*` | Desenvolvimento de funcionalidade ou correção |
+| `fix/*` | Correção de bug |
+| `chore/*` | Tarefas de manutenção sem impacto funcional |
+
+## Fluxo de desenvolvimento
+
+```mermaid
+flowchart TD
+    A[Criar branch a partir de develop] --> B[Desenvolver e commitar localmente]
+    B --> C[Push da branch]
+    C --> D[Abrir Pull Request para develop]
+    D --> E[Code review]
+    E --> F[Merge em develop]
+    F --> G[Validação em homologação]
+    G --> H[PR de develop para main]
+    H --> I[Merge em main - release]
+```
+
+### 1. Criar branch a partir de develop
+
+```bash
+git checkout develop
+git pull
+git checkout -b feature/nome-descritivo
+```
+
+Sempre parta de `develop` atualizado.
+
+### 2. Commitar com padrão convencional
+
+Use o padrão Conventional Commits:
+
+```
+feat: adiciona atividade de lógica sequencial
+fix: corrige validação da fase 3 do aspirador
+chore: atualiza dependência do Blockly
+refactor: extrai lógica de storage para serviço dedicado
+```
+
+Referência externa: https://www.conventionalcommits.org/
+
+### 3. Abrir PR para develop
+
+- Título claro e no mesmo padrão do commit principal.
+- Descreva o que muda e por quê.
+- Inclua print ou gif se houver mudança visual.
+
+### 4. Merge em develop e validação
+
+Após aprovação, o merge vai para `develop`. A homologação é testada manualmente a partir desse estado.
+
+### 5. Release para main
+
+Quando `develop` está estável, abre-se PR de `develop` → `main`. O merge representa a release.
+
+## Regras do repositório
+
+- Não faça push direto em `main` ou `develop`.
+- PRs precisam de ao menos uma aprovação antes do merge.
+- Branches devem ser deletadas após o merge.
+- Evite acumular muitas mudanças em uma única branch - PRs menores são mais fáceis de revisar.
+
+Referência externa: https://nvie.com/posts/a-successful-git-branching-model/

docs/docs/documentacao/monorepo.md

@@ -0,0 +1,80 @@
+---
+sidebar_position: 1
+title: "Monorepo e Build"
+---
+
+O projeto usa um repositório único com builds separados por domínio técnico.
+
+## Estrutura do repositório
+
+```mermaid
+graph TD
+    A[plataforma-edu/] --> B[app/]
+    A --> C[docs/]
+    A --> D[jupyter/]
+    A --> E[docker-compose.yaml]
+    B --> BF[Dockerfile]
+    C --> CF[Dockerfile]
+    D --> DF[Dockerfile]
+    E --> P[proxy Nginx]
+```
+
+- `app/`: aplicação React com atividades.
+- `docs/`: documentação Docusaurus.
+- `jupyter/`: instância JupyterLite.
+- `docker-compose.yaml`: sobe os serviços juntos para teste local.
+
+## Como o build funciona
+
+O build é definido pelos Dockerfiles de cada pasta:
+
+- `app/Dockerfile`: build da aplicação e entrega via Nginx.
+- `docs/Dockerfile`: build do site de documentação e entrega via Nginx.
+- `jupyter/Dockerfile`: build do site JupyterLite e entrega via Nginx.
+
+Depois disso, `docker-compose.yaml` orquestra os serviços com um proxy Nginx de entrada única.
+
+Referências externas:
+
+- Dockerfile reference: https://docs.docker.com/reference/dockerfile/
+- Compose specification: https://compose-spec.io/
+- Nginx docs: https://nginx.org/en/docs/
+
+## Subida local integrada
+
+Na raiz do repositório:
+
+```bash
+docker compose up --build
+```
+
+Esse comando:
+
+1. Constrói `app`, `docs` e `jupyter` com seus Dockerfiles.
+2. Sobe os containers.
+3. Conecta tudo via proxy definido em `docker-compose.yaml`.
+
+## Quando usar Docker e quando usar modo local
+
+```mermaid
+flowchart LR
+    Q{O que você precisa?} --> A[Ambiente completo
+integrado]
+    Q --> B[Iteração rápida
+em uma frente]
+    A --> C[docker compose up --build]
+    B --> D[app: pnpm run dev]
+    B --> E[docs: pnpm run start]
+```
+
+Use Docker quando quiser reproduzir o ambiente integrado completo.
+
+Use modo local quando quiser iterar mais rápido em uma frente específica:
+
+- `app`: `pnpm run dev`
+- `docs`: `pnpm run start`
+
+## Observações importantes
+
+- A documentação técnica deve refletir sempre o fluxo acima.
+- Ajustes de deploy externo não são documentados aqui; este guia cobre desenvolvimento e validação local.

docs/docs/intro.md

@@ -0,0 +1,54 @@
+---
+sidebar_position: 1
+title: "Guia de Desenvolvimento"
+---
+
+Esta documentação técnica descreve como desenvolver a plataforma com base no código atual em `app/`.
+
+## Visão geral
+
+O repositório concentra três frentes técnicas independentes, integradas localmente via Docker:
+
+```mermaid
+graph TD
+    A[decoda] --> B["**app/** - React + Vite"]
+    A --> C["**docs/** - Docusaurus"]
+    A --> D["**jupyter/** - JupyterLite"]
+    B --> E[Atividades de **Programação**]
+    B --> F[Atividades de **Letramento**]
+```
+
+- Aplicação principal em React, com atividades interativas em `app/`.
+- Documentação em Docusaurus em `docs/`.
+- Instância JupyterLite em `jupyter/` para material de apoio.
+
+Referências externas:
+
+- React: https://react.dev/
+- Docusaurus: https://docusaurus.io/
+- JupyterLite: https://jupyterlite.readthedocs.io/
+
+## Estrutura real da aplicação
+
+Na aplicação principal, o código está organizado principalmente em:
+
+- `app/src/atividades/programacao`: atividades com Blockly, interpretador e renderização.
+- `app/src/atividades/letramento`: atividades em HTML autocontido executadas em iframe.
+- `app/src/contexts`: estado global da aplicação.
+- `app/src/interpreters`: execução segura de código.
+- `app/src/services`: persistência local e serviços auxiliares.
+- `app/src/components`: componentes reutilizáveis de interface.
+
+## Como usar esta documentação
+
+Comece por estas seções, conforme o contexto:
+
+1. `plataforma/pre-requisitos`: ambiente local em Windows, macOS e Linux.
+2. `documentacao/monorepo`: build e subida local via Docker.
+3. `plataforma/arquitetura/intro`: visão geral da arquitetura do site.
+4. `plataforma/atividades_programacao/intro`: conteúdo específico de atividades de programação.
+5. `plataforma/letramento/intro`: conteúdo específico de atividades de letramento.
+
+## Escopo desta doc
+
+Esta doc é voltada para quem já tem acesso ao código-fonte. O foco é manutenção e evolução interna do projeto.

docs/docs/plataforma/_category_.json

@@ -0,0 +1,14 @@
+{
+  "position": 3,
+  "label": "Plataforma",
+  "collapsible": true,
+  "collapsed": true,
+  "className": "red",
+  "link": {
+    "type": "generated-index",
+    "title": "Plataforma"
+  },
+  "customProps": {
+    "description": "Documentações sobre desenvolvimento da plataforma, separadas por contexto técnico."
+  }
+}

docs/docs/plataforma/arquitetura/_category_.json

@@ -0,0 +1,14 @@
+{
+  "position": 2,
+  "label": "Arquitetura",
+  "collapsible": true,
+  "collapsed": true,
+  "className": "red",
+  "link": {
+    "type": "generated-index",
+    "title": "Arquitetura"
+  },
+  "customProps": {
+    "description": "Visão geral da arquitetura da plataforma e decisões técnicas transversais."
+  }
+}

docs/docs/plataforma/arquitetura/build-offline.md

@@ -0,0 +1,162 @@
+---
+sidebar_position: 12
+title: "Build Offline (PWA)"
+---
+
+A plataforma suporta um modo de build offline que gera uma versão totalmente funcional sem acesso à internet, baseada em PWA com Workbox.
+
+## Como funciona
+
+```mermaid
+graph TD
+    CMD[pnpm build:offline] --> PRE1[build:letramento-assets\ncopia lucide.js]
+    CMD --> PRE2[build:letramento-css\ngera letramento.css]
+    PRE1 --> VITE[vite build --mode offline]
+    PRE2 --> VITE
+    VITE --> ENV[carrega .env.offline\nVITE_IS_OFFLINE=true]
+    VITE --> BUNDLE[gera bundle em dist/]
+    BUNDLE --> SW[gera dist/sw.js\nWorkbox precache]
+    SW --> VAL[pnpm test:cache\nvalida precache]
+```
+
+O `--mode offline` faz o Vite carregar o arquivo `.env.offline`, que define `VITE_IS_OFFLINE=true`. O código pode ler essa variável via `import.meta.env.VITE_IS_OFFLINE` para ajustar comportamento em runtime.
+
+O Service Worker é gerado automaticamente pelo plugin `vite-plugin-pwa` com Workbox e faz o precache de todos os assets do build.
+
+## Diferença entre build normal e build offline
+
+| Aspecto | `pnpm build` | `pnpm build:offline` |
+|---|---|---|
+| Vite mode | `production` | `offline` |
+| `.env` carregado | `.env.production` | `.env.offline` |
+| `VITE_IS_OFFLINE` | não definida | `true` |
+| Service Worker | gerado | gerado (idêntico) |
+| Precache | idêntico | idêntico |
+
+A diferença prática está nas variáveis de ambiente — o bundle em si é o mesmo. O `build:offline` é usado para distribuição sem servidor (ex.: Electron ou cópia local em escola sem internet).
+
+## O que é incluído no precache
+
+O Workbox precacha automaticamente todos os arquivos do padrão:
+
+```
+**/*.{js,css,html,svg,png,json,ico,webp}
+```
+
+Os itens validados explicitamente pelo script `pnpm test:cache` são:
+
+- `offline.html` — página de fallback quando sem conexão
+- `atividades/letramento/**` — todas as atividades de letramento
+- `letramento.css` — estilos das atividades de letramento
+- `lucide.js` — biblioteca de ícones usada no letramento
+
+A rota `/atividades/letramento/` está na deny list do `navigateFallback`, ou seja, nunca é substituída por `offline.html` mesmo sem conexão.
+
+## Arquivos de referência
+
+- `app/.env.offline` — define `VITE_IS_OFFLINE=true`
+- `app/vite.config.js` — configuração do `VitePWA` e Workbox
+- `app/public/offline.html` — página exibida ao usuário sem conexão
+- `app/scripts/test-cache.mjs` — valida o precache do SW após o build
+
+---
+
+## Executando o build offline
+
+### Pré-requisitos
+
+- Node.js 20+
+- pnpm instalado globalmente
+
+### Linux (Debian e derivadas)
+
+Clone o repositório e instale as dependências:
+
+```bash
+cd app
+pnpm install
+```
+
+Execute o build offline:
+
+```bash
+pnpm build:offline
+```
+
+Valide o Service Worker gerado:
+
+```bash
+pnpm test:cache
+```
+
+O resultado estará em `app/dist/`.
+
+Para servir localmente e testar o comportamento offline:
+
+```bash
+# instale um servidor estático se necessário
+pnpm dlx serve dist
+```
+
+Abra o navegador em `http://localhost:3000`, vá em **DevTools → Application → Service Workers** e marque **Offline** para simular ausência de conexão.
+
+### Windows
+
+No Windows, o build roda dentro do WSL2 (recomendado) ou diretamente no PowerShell/CMD.
+
+#### Opção 1 — WSL2 (recomendado)
+
+Abra o terminal do WSL2 e siga os mesmos passos da seção Linux acima.
+
+#### Opção 2 — PowerShell / CMD
+
+Certifique-se de ter Node.js e pnpm instalados no Windows (veja [Pré-requisitos](../pre-requisitos.md)).
+
+No PowerShell, dentro da pasta `app/`:
+
+```powershell
+pnpm install
+pnpm build:offline
+pnpm test:cache
+```
+
+> **Atenção:** O script `build:letramento-assets` usa `rm -f` (comando Unix). No PowerShell isso pode falhar. Use o WSL2 para evitar problemas com comandos de shell Unix embutidos nos scripts do `package.json`.
+
+---
+
+## Build para Electron
+
+O script `electron:build` já usa `build:offline` internamente:
+
+```bash
+pnpm electron:build
+```
+
+Esse comando executa `pnpm build:offline` e em seguida empacota com `electron-builder`, gerando um instalador desktop com todos os assets offline incluídos.
+
+---
+
+## O que é o Electron e por que o usamos
+
+Electron é um framework que empacota aplicações web (HTML/CSS/JS — neste caso, a aplicação em React) dentro de um runtime desktop (Chromium + Node.js), permitindo distribuir a mesma aplicação como um programa nativo para Windows, macOS e Linux.
+
+- **Porque a aplicação é React**: a interface da plataforma é escrita em React; o Electron executa essa interface num navegador embutido, o que permite reaproveitar todo o código web sem reescrever a UI para cada sistema operacional.
+- **Não é necessário Node.js na máquina do usuário**: o pacote gerado pelo `electron-builder` inclui o runtime necessário, portanto a máquina final NÃO precisa ter o Node.js ou dependências de desenvolvimento instaladas — o executável já contém tudo que é preciso para rodar offline.
+- **Evita permissões administrativas na máquina final**: ao escolher alvos como `portable` no Windows ou empacotamentos que não exigem instalação com privilégios elevados, reduzimos a necessidade de permissões administrativas em ambientes escolares onde o educador pode não ter direitos de administrador.
+
+> Observação: a fase de *build* e empacotamento pode exigir ferramentas nativas no ambiente de desenvolvimento (por exemplo, o empacotamento para Windows pode requerer dependências específicas). Porém, para execução offline nas máquinas finais, normalmente basta distribuir o executável gerado.
+
+---
+
+## Práticas recomendadas
+
+1. Sempre rode `pnpm test:cache` após o build para garantir que o precache está completo.
+2. Não distribua o build offline sem validar que `offline.html`, `letramento.css` e `lucide.js` estão no precache.
+3. Ao adicionar novas atividades de letramento, verifique se os novos arquivos seguem o padrão de glob coberto pelo Workbox.
+4. O Service Worker usa `autoUpdate` — ao servir uma versão nova, o SW se atualiza automaticamente no próximo carregamento do cliente.
+
+Referências externas:
+
+- vite-plugin-pwa: https://vite-pwa-org.netlify.app/
+- Workbox: https://developer.chrome.com/docs/workbox/
+- PWA no Chrome DevTools: https://developer.chrome.com/docs/devtools/progressive-web-apps/

docs/docs/plataforma/arquitetura/camadas-do-sistema.md

@@ -0,0 +1,65 @@
+---
+sidebar_position: 4
+title: "Camadas do Sistema"
+---
+
+Esta divisão ajuda a entender responsabilidades e reduzir acoplamento entre partes da aplicação.
+
+```mermaid
+graph TD
+    UI[**Camada de Interface**
+Páginas · Componentes · Rotas]
+    EF[**Camada de Estado e Fluxo**
+Contexts · Hooks · Event Bus]
+    EA[**Camada de Execução de Atividades**
+Programação · Letramento · Interpretador]
+    PI[**Camada de Persistência e Utilitários**
+LocalStorage · Serviços · Utils]
+
+    UI --> EF
+    EF --> EA
+    EA --> PI
+```
+
+## Camada de interface
+
+Responsável por renderização, navegação e interação com usuário.
+
+- Páginas: `app/src/pages`
+- Componentes: `app/src/components`
+- Rotas: `app/src/App.jsx`
+
+## Camada de estado e fluxo
+
+Responsável por estado compartilhado e coordenação de eventos.
+
+- Contextos: `app/src/contexts`
+- Hooks: `app/src/hooks`
+- Barramentos: `app/src/utils/gameEvents.js`, `app/src/utils/letramentoEvents.js`
+
+## Camada de execução de atividades
+
+Responsável pelo runtime das atividades.
+
+- Programação: `app/src/atividades/programacao`
+- Letramento: `app/src/atividades/letramento`
+- Interpretador: `app/src/interpreters`
+- Base de runtime: `app/src/shared/BaseGameScene.js`
+
+## Camada de persistência e utilitários
+
+Responsável por armazenamento local e funções transversais.
+
+- Serviços: `app/src/services`
+- Utilitários: `app/src/utils`
+
+## Decisões importantes
+
+- Eventos assíncronos foram desacoplados com pub-sub para reduzir dependência entre UI e runtime.
+- Estado global ficou em providers para evitar cadeias longas de props.
+- O runtime de atividades de letramento usa fronteira clara por iframe sandbox.
+
+Referências externas:
+
+- EventTarget: https://developer.mozilla.org/en-US/docs/Web/API/EventTarget
+- React Context: https://react.dev/reference/react/createContext

docs/docs/plataforma/arquitetura/estrutura-de-pastas.md

@@ -0,0 +1,67 @@
+---
+sidebar_position: 2
+title: "Estrutura de Pastas"
+---
+
+Este mapa resume as pastas mais importantes para desenvolvimento da aplicação.
+
+## Mapa principal
+
+```mermaid
+graph TD
+    SRC[app/src/] --> AT[atividades/]
+    SRC --> CO[components/]
+    SRC --> CT[contexts/]
+    SRC --> HK[hooks/]
+    SRC --> IN[interpreters/]
+    SRC --> SV[services/]
+    SRC --> SH[shared/]
+    SRC --> UT[utils/]
+    SRC --> PG[pages/]
+    AT --> PR[programacao/]
+    AT --> LT[letramento/]
+```
+
+```text
+app/src/
+  atividades/
+    programacao/
+    letramento/
+  components/
+  contexts/
+  hooks/
+  interpreters/
+  services/
+  shared/
+  utils/
+  pages/
+```
+
+## Responsabilidades por pasta
+
+- `atividades/programacao`: atividades com blocos, interpretador e renderização.
+- `atividades/letramento`: atividades HTML autocontidas.
+- `components`: componentes reutilizáveis da interface.
+- `contexts`: estado compartilhado da aplicação.
+- `hooks`: integrações e comportamento reutilizável.
+- `interpreters`: execução segura de código e APIs associadas.
+- `services`: persistência e serviços de apoio.
+- `shared`: base comum para runtime de atividades.
+- `utils`: funções utilitárias transversais.
+
+## Pastas-chave para letramento
+
+- `app/src/atividades/letramento`: definição das atividades HTML.
+- `app/src/components/letramento`: container e navegação do runtime.
+- `app/src/contexts/LetramentoStateContext.jsx`: estado de execução.
+- `app/src/services/letramentoStorage.js`: progresso no `localStorage`.
+
+## Pastas-chave para atividades de programação
+
+- `app/src/atividades/programacao/*`: implementação de cada atividade.
+- `app/src/shared/BaseGameScene.js`: ciclo de vida comum de execução.
+- `app/src/interpreters/GameInterpreter.js`: execução com `js-interpreter`.
+
+Referência externa:
+
+- js-interpreter: https://github.com/NeilFraser/JS-Interpreter

docs/docs/plataforma/arquitetura/intro.md

@@ -0,0 +1,33 @@
+---
+sidebar_position: 1
+title: "Visão Geral"
+---
+
+Esta seção apresenta a arquitetura real da aplicação em `app/`, com foco no que está em produção hoje.
+
+## Camadas principais
+
+```mermaid
+graph TD
+    A[**Interface**
+Páginas e Componentes React] --> B[Estado e Fluxo
+Contexts, Hooks, Event Bus]
+    B --> C[**Execução de Atividades**
+Interpretador, Runtime, Validação]
+    C --> D[**Infra Local**
+LocalStorage e Build com Vite]
+```
+
+A aplicação se organiza em quatro camadas práticas:
+
+1. **Interface**: páginas e componentes React.
+2. **Estado e fluxo**: contexts, hooks e barramentos de evento.
+3. **Execução de atividades**: interpretador, renderização e validação.
+4. **Infra local**: persistência no navegador e build com Vite/Docker.
+
+## Áreas funcionais
+
+- Atividades de programação em `app/src/atividades/programacao`.
+- Atividades de letramento em `app/src/atividades/letramento`.
+- Componentes compartilhados em `app/src/components`.
+- Estado compartilhado em `app/src/contexts`.

docs/docs/plataforma/arquitetura/otimizacao-bundle.md

@@ -0,0 +1,50 @@
+---
+sidebar_position: 10
+title: "Otimização de Bundle"
+---
+
+Esta página resume as decisões de build que impactam carregamento e distribuição de código.
+
+## Estratégia de chunking
+
+```mermaid
+graph TD
+    ENTRY[**Entrada da aplicação**] --> INIT[**Chunk inicial**
+interface + roteamento]
+    ENTRY --> LAZY[**Lazy loading**
+rotas e áreas pesadas]
+    INIT --> CHUNKS[Chunks dedicados]
+    CHUNKS --> B[blockly]
+    CHUNKS --> P[phaser]
+    CHUNKS --> C[codemirror]
+    CHUNKS --> V[vendor genérico]
+```
+
+## Estratégias em uso
+
+- Code splitting por grupos de dependência no build.
+- Lazy loading de rotas e áreas pesadas.
+- Separação de bibliotecas maiores em chunks dedicados.
+- Otimização de imagens no pipeline.
+
+Arquivos de referência:
+
+- `app/vite.config.js`
+- `app/src/App.jsx`
+
+## Por que isso importa
+
+Sem esse cuidado, o pacote inicial cresce rápido e piora o tempo de carregamento.
+Com separação por chunk, o usuário baixa primeiro o necessário para abrir a interface e carrega o restante sob demanda.
+
+## Práticas recomendadas para novas alterações
+
+1. Evite adicionar dependência pesada sem avaliar impacto.
+2. Prefira importação sob demanda para módulos de uso eventual.
+3. Rode build local e inspecione tamanhos antes de merge.
+
+Referências externas:
+
+- Vite build guide: https://vite.dev/guide/build
+- Rollup chunking: https://rollupjs.org/configuration-options/#output-manualchunks
+- web.dev code splitting: https://web.dev/articles/reduce-javascript-payloads-with-code-splitting

docs/docs/plataforma/arquitetura/patterns.md

@@ -0,0 +1,481 @@
+---
+sidebar_position: 11
+title: "Patterns"
+---
+
+Esta página documenta os padrões de projeto identificados no código da plataforma. Para cada pattern: o que é, onde aparece, o que resolve, diagrama de funcionamento, exemplo do código real, alternativas consideradas e tradeoffs.
+
+---
+
+## Registry
+
+### O que é
+
+Um registro centralizado que mapeia identificadores para objetos ou funções, permitindo localizar e carregar componentes sem dependência direta entre módulos.
+
+Referência externa: https://martinfowler.com/eaaCatalog/registry.html
+
+### Onde aparece no código
+
+- `app/src/config/gameRegistry.js` - registro de atividades de programação.
+- `app/src/atividades/letramento/letramentoRegistry.js` - registro de atividades de letramento.
+
+### O que resolve
+
+O sistema precisa listar, filtrar e carregar atividades sem que os módulos de interface conheçam cada atividade diretamente. O registro é o único ponto de entrada para essa informação.
+
+### Como funciona
+
+```mermaid
+graph LR
+    A[Interface / Listagem] -->|consulta| R[Registry]
+    R -->|retorna metadados| A
+    A -->|lazy import sob demanda| M[Módulo da Atividade]
+```
+
+### Exemplo do código real
+
+```javascript
+// app/src/config/gameRegistry.js
+export const games = [
+  {
+    id: 'aspirador',
+    title: 'Aspirador',
+    component: () => import('../atividades/programacao/aspirador/Aspirador.jsx'),
+    // ...
+  },
+  // ...
+];
+```
+
+### Alternativas
+
+- **Importação direta**: simples, mas cria acoplamento rígido e dificulta extensão.
+- **Backend com API de catálogo**: mais flexível para escala, mas desnecessário para a quantidade atual de atividades.
+
+### Tradeoffs
+
+| Vantagem | Limitação |
+|---|---|
+| Ponto único de extensão | Registro precisa ser atualizado manualmente ao adicionar atividade |
+| Lazy loading integrado | Sem validação em tempo de compilação da entrada |
+
+---
+
+## Observer / Pub-Sub
+
+### O que é
+
+Um mecanismo onde componentes emitem eventos sem saber quem vai consumi-los. Quem tem interesse em um evento se inscreve e reage quando ele ocorre.
+
+Referências externas:
+- Observer: https://refactoring.guru/design-patterns/observer
+- Publisher-Subscriber: https://learn.microsoft.com/en-us/azure/architecture/patterns/publisher-subscriber
+
+### Onde aparece no código
+
+- `app/src/utils/gameEvents.js` - barramento de eventos para atividades de programação.
+- `app/src/utils/letramentoEvents.js` - barramento de eventos para atividades de letramento.
+
+### O que resolve
+
+O runtime da atividade e a interface React precisam se comunicar sem acoplamento direto. O runtime emite eventos (ex.: fase concluída) e a interface reage sem estar importada no runtime.
+
+### Como funciona
+
+```mermaid
+sequenceDiagram
+    participant R as Runtime da Atividade
+    participant B as Event Bus
+    participant C as Contexto React
+
+    R->>B: emit('fase:concluida', dados)
+    B->>C: notifica todos os ouvintes
+    C->>C: atualiza estado
+```
+
+### Exemplo do código real
+
+```javascript
+// app/src/utils/gameEvents.js
+const gameEventBus = new EventTarget();
+
+export function emitGameEvent(type, detail) {
+  gameEventBus.dispatchEvent(new CustomEvent(type, { detail }));
+}
+
+export function onGameEvent(type, handler) {
+  gameEventBus.addEventListener(type, handler);
+  return () => gameEventBus.removeEventListener(type, handler);
+}
+```
+
+### Alternativas
+
+- **Callbacks diretos**: mais simples, mas cria acoplamento bidirecional.
+- **Estado compartilhado via Context**: possível, mas força re-render desnecessário para eventos transitórios.
+- **Redux / Zustand**: justificável se o estado global crescer muito.
+
+### Tradeoffs
+
+| Vantagem | Limitação |
+|---|---|
+| Desacoplamento total entre emissor e consumidor | Difícil rastrear fluxo em debug |
+| Múltiplos consumidores sem alterar o emissor | Sem tipagem estática dos eventos por padrão |
+
+---
+
+## Provider com React Context
+
+### O que é
+
+Um mecanismo do React que compartilha estado em uma árvore de componentes sem passar props manualmente por cada nível.
+
+Referência externa: https://react.dev/reference/react/createContext
+
+### Onde aparece no código
+
+- `app/src/contexts/GameStateContext.jsx` - estado da sessão de execução.
+- `app/src/contexts/GameProgressContext.jsx` - progresso de fases por atividade.
+- `app/src/contexts/LetramentoStateContext.jsx` - estado da execução de letramento.
+- `app/src/contexts/EditorContext.jsx` - estado do editor (blockly/code).
+
+### O que resolve
+
+Vários componentes em níveis diferentes da árvore precisam ler e modificar o mesmo estado (ex.: fase atual, modo do editor). Sem Context, as props precisariam ser passadas por vários níveis intermediários que não as usam.
+
+### Como funciona
+
+```mermaid
+graph TD
+    P[Provider
+no topo da árvore] --> A[Componente A]
+    P --> B[Componente B]
+    A --> C[Componente C
+consume contexto]
+    B --> D[Componente D
+consume contexto]
+```
+
+### Exemplo do código real
+
+```javascript
+// app/src/contexts/GameStateContext.jsx
+export const GAME_STATES = {
+  IDLE: 'idle',
+  RUNNING: 'running',
+  SUCCESS: 'success',
+  FAILURE: 'failure',
+};
+
+export const GameStateContext = createContext(null);
+
+export function GameStateProvider({ children }) {
+  const [gameState, setGameState] = useState(GAME_STATES.IDLE);
+  // ...
+  return (
+    <GameStateContext.Provider value={{ gameState, setGameState }}>
+      {children}
+    </GameStateContext.Provider>
+  );
+}
+```
+
+### Alternativas
+
+- **Prop drilling**: funciona para árvores rasas, mas escala mal.
+- **Zustand / Jotai**: mais leves e sem boilerplate de Provider, indicados se o número de contextos crescer muito.
+- **Redux**: overhead justificado apenas para apps com lógica de estado muito complexa.
+
+### Tradeoffs
+
+| Vantagem | Limitação |
+|---|---|
+| Nativo do React, sem dependência extra | Re-renders em todos os consumidores ao atualizar |
+| Fácil de testar com wrappers | Aninhamento excessivo de Providers |
+
+---
+
+## Factory
+
+### O que é
+
+Uma função ou classe que centraliza a criação de objetos com configuração específica, evitando que o código cliente precise conhecer os detalhes de construção.
+
+Referência externa: https://refactoring.guru/design-patterns/factory-method
+
+### Onde aparece no código
+
+- `app/src/services/createStorageService.js` - cria serviços de storage com chave e estrutura pré-definidas.
+- `app/src/hooks/usePhaser.js` - recebe `gameFactory`, uma função que constrói a configuração Phaser da atividade.
+
+### O que resolve
+
+Cada atividade precisa de um serviço de storage configurado com sua chave específica. Sem Factory, cada atividade repetiria o mesmo código de configuração.
+
+### Como funciona
+
+```mermaid
+graph LR
+    A[Atividade] -->|passa chave e schema| F[createStorageService]
+    F -->|retorna| S[Serviço configurado
+get / set / clear]
+```
+
+### Exemplo do código real
+
+```javascript
+// app/src/services/createStorageService.js
+export function createStorageService(key, defaultValue) {
+  return {
+    get: () => JSON.parse(localStorage.getItem(key)) ?? defaultValue,
+    set: (value) => localStorage.setItem(key, JSON.stringify(value)),
+    clear: () => localStorage.removeItem(key),
+  };
+}
+```
+
+### Alternativas
+
+- **Instância direta**: sem abstração, mais verboso e duplicado.
+- **Classe base com herança**: mais pesado para o que é necessário aqui.
+
+### Tradeoffs
+
+| Vantagem | Limitação |
+|---|---|
+| Elimina repetição de código de storage | Contrato não tem tipagem estática |
+| Fácil de substituir a implementação | Pouco ganho se a estrutura de cada storage for muito diferente |
+
+---
+
+## Template Method
+
+### O que é
+
+Define o esqueleto de um algoritmo na classe base e deixa que subclasses implementem as etapas variáveis, sem alterar a estrutura geral.
+
+Referência externa: https://refactoring.guru/design-patterns/template-method
+
+### Onde aparece no código
+
+- `app/src/shared/BaseGameScene.js` - define o ciclo de vida de execução de uma atividade com Phaser.
+- Cada `game.js` em `app/src/atividades/programacao/*/` sobrescreve os hooks de ciclo de vida.
+
+### O que resolve
+
+Todas as atividades de programação compartilham o mesmo ciclo de execução (iniciar, resetar, concluir, falhar), mas cada uma tem comportamento diferente em cada etapa. O Template Method evita duplicação dessa estrutura.
+
+### Como funciona
+
+```mermaid
+classDiagram
+    class BaseGameScene {
+        +run()
+        +reset()
+        +onBeforeRun()
+        +onReset()
+        +onSuccess()
+        +onFailure()
+    }
+    class AspiradorScene {
+        +onBeforeRun()
+        +onReset()
+        +onSuccess()
+    }
+    class SemaforoScene {
+        +onBeforeRun()
+        +onSuccess()
+        +onFailure()
+    }
+    BaseGameScene <|-- AspiradorScene
+    BaseGameScene <|-- SemaforoScene
+```
+
+### Exemplo do código real
+
+```javascript
+// app/src/shared/BaseGameScene.js (simplificado)
+class BaseGameScene extends Phaser.Scene {
+  run() {
+    this.onBeforeRun();
+    this.interpreter.run();
+  }
+  reset() {
+    this.onReset();
+  }
+  // Hooks sobrescritos pelas subclasses:
+  onBeforeRun() {}
+  onReset() {}
+  onSuccess() {}
+  onFailure() {}
+}
+```
+
+### Alternativas
+
+- **Composição com hooks React**: válido para comportamentos menores, mas não se aplica bem ao ciclo de vida do Phaser.
+- **Callbacks/funções injetadas**: funcional, mas perde o benefício da herança de estado da cena.
+
+### Tradeoffs
+
+| Vantagem | Limitação |
+|---|---|
+| Garante que todas as atividades seguem o mesmo ciclo | Herança pode dificultar testes isolados |
+| Reduz duplicação de orquestração | Subclasse precisa conhecer a classe base |
+
+---
+
+## Adapter
+
+### O que é
+
+Converte a interface de um sistema (ou protocolo) em outra que o sistema atual consegue consumir, sem modificar nenhum dos dois lados.
+
+Referência externa: https://refactoring.guru/design-patterns/adapter
+
+### Onde aparece no código
+
+- `app/src/components/letramento/AtividadeRuntimeFrame.jsx` - converte mensagens `postMessage` do iframe em eventos internos do `letramentoEventBus`.
+
+### O que resolve
+
+As atividades de letramento rodam em iframe isolado e se comunicam via `window.parent.postMessage`. O React não entende esse protocolo nativamente - o Adapter faz a tradução para o barramento de eventos interno.
+
+### Como funciona
+
+```mermaid
+graph LR
+    A["Atividade HTML
+(iframe)"] -->|"postMessage({ type: 'success' })"| AD["AtividadeRuntimeFrame
+(Adapter)"]
+    AD -->|"emit('atividade:success')"| B[letramentoEventBus]
+    B --> C[LetramentoStateContext]
+```
+
+### Exemplo do código real
+
+```javascript
+// app/src/components/letramento/AtividadeRuntimeFrame.jsx (simplificado)
+useEffect(() => {
+  const handler = (event) => {
+    if (event.source !== iframeRef.current?.contentWindow) return;
+    const { type, score } = event.data;
+    emitLetramentoEvent(`atividade:${type}`, { score });
+  };
+  window.addEventListener('message', handler);
+  return () => window.removeEventListener('message', handler);
+}, []);
+```
+
+Referências externas:
+- postMessage: https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage
+- iframe sandbox: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe#sandbox
+
+### Alternativas
+
+- **Comunicação direta via ref do iframe**: possível, mas viola o isolamento do sandbox.
+- **Servidor intermediário (WebSocket)**: excessivo para o escopo atual.
+
+### Tradeoffs
+
+| Vantagem | Limitação |
+|---|---|
+| Isola completamente a atividade HTML do React | Validação de origem precisa ser mantida para evitar injeção |
+| Permite qualquer tecnologia dentro do iframe | Contrato `postMessage` é implícito e pode divergir |
+
+---
+
+## State Machine
+
+### O que é
+
+Um modelo que define estados possíveis de um sistema e as transições válidas entre eles, usando enums em vez de flags booleanas soltas.
+
+Referência externa: https://refactoring.guru/design-patterns/state
+
+### Onde aparece no código
+
+- `GAME_STATES` em `app/src/contexts/GameStateContext.jsx`
+- `ATIVIDADE_STATES` em `app/src/contexts/LetramentoStateContext.jsx`
+
+### O que resolve
+
+A execução de uma atividade tem estados interdependentes: não faz sentido exibir "sucesso" se a atividade nem começou. Com enums explícitos, o estado inválido é identificável em leitura de código.
+
+### Como funciona
+
+```mermaid
+stateDiagram-v2
+    [*] --> idle
+    idle --> running : usuário executa
+    running --> success : validação passou
+    running --> failure : validação falhou
+    success --> idle : resetar
+    failure --> idle : resetar
+```
+
+### Exemplo do código real
+
+```javascript
+// app/src/contexts/GameStateContext.jsx
+export const GAME_STATES = {
+  IDLE: 'idle',
+  RUNNING: 'running',
+  SUCCESS: 'success',
+  FAILURE: 'failure',
+};
+```
+
+### Alternativas
+
+- **Flags booleanas**: `isRunning`, `isSuccess`, etc. Funciona, mas permite estados impossíveis como `isRunning = true` e `isSuccess = true` ao mesmo tempo.
+- **XState**: biblioteca dedicada a state machines com visualização e validação. Justificada para fluxos mais complexos.
+
+### Tradeoffs
+
+| Vantagem | Limitação |
+|---|---|
+| Elimina estados impossíveis | Exige disciplina para não usar flags paralelas |
+| Fácil de ler em code review | Sem enforcement de transições em tempo de execução |
+
+---
+
+## Strategy
+
+### O que é
+
+Permite trocar o algoritmo ou comportamento de um componente em tempo de execução, mantendo a interface externa estável.
+
+Referência externa: https://refactoring.guru/design-patterns/strategy
+
+### Onde aparece no código
+
+- Seleção de editor em `app/src/contexts/EditorContext.jsx` - alterna entre modo `blockly` e modo `code`.
+- Validadores por fase em `app/src/atividades/programacao/*/validation/` - cada fase pode ter regra diferente.
+
+### O que resolve
+
+O editor pode funcionar em modo visual (Blockly) ou em modo código (CodeMirror). As atividades precisam validar condições diferentes por fase. Em ambos os casos, o contexto que usa essas estratégias não precisa mudar.
+
+### Como funciona
+
+```mermaid
+graph TD
+    EC[EditorContext] -->|editorType === 'blockly'| BL[BlocklyEditor]
+    EC -->|editorType === 'code'| CM[CodeMirrorEditor]
+    AT[Atividade] -->|fase atual| VF[Validador da Fase]
+    VF -->|regras específicas| R[Resultado: sucesso/falha]
+```
+
+### Alternativas
+
+- **Condicional inline**: `if (type === 'blockly') ... else ...` - funciona para dois casos, mas escala mal.
+- **Mapa de componentes**: variação do Strategy, explícita e fácil de estender.
+
+### Tradeoffs
+
+| Vantagem | Limitação |
+|---|---|
+| Adicionar novo editor/validador não exige alterar o contexto | Contrato entre estratégia e contexto precisa ser mantido |
+| Testável de forma isolada | Pode ser over-engineering para dois casos fixos |

docs/docs/plataforma/arquitetura/sistema-persistencia.md

@@ -0,0 +1,70 @@
+---
+sidebar_position: 7
+title: "Sistema de Persistência"
+---
+
+A aplicação usa `localStorage` para manter progresso e dados de edição entre sessões.
+
+## Visão geral
+
+```mermaid
+graph TD
+    APP[Aplicação] --> PR[Atividades de **Programação**]
+    APP --> LT[Atividades de **Letramento**]
+
+    PR --> BS[**blockstorage.js**
+blocos do editor]
+    PR --> CS[**codestorage.js**
+código em texto]
+    PR --> GP[**GameProgressContext**
+progresso de fases]
+
+    LT --> LS[**letramentoStorage.js**
+progresso e status]
+    LT --> LC[**LetramentoStateContext**
+estado de execução]
+
+    BS --> LOC[(localStorage)]
+    CS --> LOC
+    GP --> LOC
+    LS --> LOC
+```
+
+## Persistência em atividades de programação
+
+Principais pontos:
+
+- Progresso de fases por atividade.
+- Workspace/código do editor.
+- Estado de execução relevante para retomada.
+
+Arquivos de referência:
+
+- `app/src/services/blockstorage.js`
+- `app/src/services/codestorage.js`
+- `app/src/services/createStorageService.js`
+- `app/src/contexts/GameProgressContext.jsx`
+
+## Persistência em atividades de letramento
+
+Principais pontos:
+
+- Status da atividade (`started`, `running`, `success`, `failure`, `completed`).
+- Tentativas e score.
+- Controle de fases concluídas por categoria.
+
+Arquivos de referência:
+
+- `app/src/services/letramentoStorage.js`
+- `app/src/contexts/LetramentoStateContext.jsx`
+
+## Diretrizes
+
+- Nunca persistir dados sensíveis.
+- Sempre versionar estruturas quando houver mudança de contrato.
+- Tratar leitura com fallback para dados ausentes ou corrompidos.
+
+Referências externas:
+
+- Web Storage API: https://developer.mozilla.org/en-US/docs/Web/API/Web_Storage_API
+- JSON.parse error handling: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/parse

docs/docs/plataforma/arquitetura/sistema-tours.md

@@ -0,0 +1,21 @@
+---
+sidebar_position: 9
+title: "Orientação de Interface"
+---
+
+Esta página foi mantida apenas para registrar uma decisão arquitetural.
+
+## Status atual
+
+O sistema antigo de orientação guiada da interface está em processo de desativação.
+Por isso, não há evolução funcional planejada para essa camada dentro do escopo atual da aplicação.
+
+## Diretriz para novas alterações
+
+- Não introduzir novas dependências específicas para tours nesta etapa.
+- Priorizar orientações contextuais simples dentro das próprias telas de atividade.
+- Concentrar investimento técnico nas atividades de programação e letramento.
+
+## Impacto na documentação
+
+As páginas de arquitetura e tecnologias foram atualizadas para refletir esse estado e evitar acoplamento com componentes em descontinuidade.

docs/docs/plataforma/arquitetura/suporte-responsivo.md

@@ -0,0 +1,81 @@
+---
+sidebar_position: 6
+title: "Suporte Responsivo"
+---
+
+Esta página descreve como a plataforma se adapta a diferentes dispositivos e tamanhos de tela.
+
+## Estratégia geral
+
+```mermaid
+graph TD
+    HOOK[**useIsMobile**
+detecta largura da tela] --> STATE[**Estado global**
+isMobile: boolean]
+    STATE --> UI[**Componentes React**
+adaptam layout]
+    STATE --> BLOCKLY[**Toolbox Blockly**
+versão mobile simplificada]
+    UI --> CSS[**TailwindCSS**
+classes responsivas]
+    BLOCKLY --> TOUCH[Interações touch-friendly]
+```
+
+A detecção de dispositivo é centralizada no hook `useIsMobile`, que expõe um booleano consumido pelos componentes que precisam adaptar comportamento ou layout.
+
+Referência externa: https://react.dev/reference/react/hooks
+
+## Hook useIsMobile
+
+O hook observa `window.innerWidth` e atualiza o estado quando o tamanho da janela muda:
+
+```javascript
+// app/src/hooks/useIsMobile.js
+import { useState, useEffect } from 'react';
+
+export function useIsMobile(breakpoint = 768) {
+  const [isMobile, setIsMobile] = useState(false);
+
+  useEffect(() => {
+    const check = () => setIsMobile(window.innerWidth < breakpoint);
+    check();
+    window.addEventListener('resize', check);
+    return () => window.removeEventListener('resize', check);
+  }, [breakpoint]);
+
+  return isMobile;
+}
+```
+
+## Breakpoints com TailwindCSS
+
+```mermaid
+graph LR
+    M["**Mobile** < 640px"] --> SM["**sm** ≥ 640px"]
+    SM --> MD["**md** ≥ 768px"]
+    MD --> LG["**lg** ≥ 1024px"]
+    LG --> XL["**xl** ≥ 1280px"]
+```
+
+A estilização usa classes utilitárias do TailwindCSS com prefixos de breakpoint (`sm:`, `md:`, `lg:`).
+O layout é pensado mobile-first: o estilo base cobre telas pequenas e os prefixos adicionam adaptações progressivas.
+
+Referência externa: https://tailwindcss.com/docs/responsive-design
+
+## Adaptação do Blockly em mobile
+
+O editor Blockly tem comportamento diferente em telas pequenas:
+
+- Toolbox simplificada com menos categorias visíveis simultaneamente.
+- Workspace com suporte a gestos touch (pan e pinch-to-zoom).
+- Controles de zoom e reset reposicionados para facilitar acesso em tela pequena.
+
+Arquivo de referência: `app/src/blockly/mobileToolbox.js`
+
+Referência externa: https://developers.google.com/blockly/guides/configure/advanced/zoom
+
+## Considerações para novas telas
+
+- Sempre teste em viewport mobile antes de publicar uma tela nova.
+- Use `useIsMobile` para bifurcar comportamentos, não apenas estilos.
+- Evite componentes com largura fixa em pixels sem fallback responsivo.

docs/docs/plataforma/arquitetura/tecnologias-principais.md

@@ -0,0 +1,73 @@
+---
+sidebar_position: 5
+title: "Tecnologias Principais"
+---
+
+Esta página lista as tecnologias centrais da aplicação e como elas entram no fluxo técnico.
+
+```mermaid
+graph LR
+    subgraph UI["Interface e Navegação"]
+        React --> ReactRouter
+        React --> Tailwind
+    end
+    subgraph PROG["Atividades de Programação"]
+        Blockly --> jsinterpreter["js-interpreter"]
+        jsinterpreter --> Phaser
+    end
+    subgraph LET["Atividades de Letramento"]
+        HTML["HTML autocontido"] --> iframe
+        iframe --> postMessage
+        postMessage --> EventBus["Event Bus interno"]
+    end
+    subgraph BUILD["Build e Empacotamento"]
+        Vite --> Rollup
+        Docker --> Nginx
+    end
+```
+
+## Interface e navegação
+
+- React para composição de interface.
+- React Router para rotas e navegação.
+- TailwindCSS para estilização utilitária.
+
+Referências externas:
+
+- React: https://react.dev/
+- React Router: https://reactrouter.com/
+- TailwindCSS: https://tailwindcss.com/docs
+
+## Atividades de programação
+
+- Blockly para construção visual de lógica.
+- js-interpreter para execução controlada do código.
+- Phaser como motor de execução em atividades que exigem canvas e animação.
+
+Referências externas:
+
+- Blockly: https://developers.google.com/blockly
+- js-interpreter: https://github.com/NeilFraser/JS-Interpreter
+- Phaser: https://docs.phaser.io/
+
+## Atividades de letramento
+
+As atividades de letramento são HTML autocontido e rodam em iframe sandbox.
+A comunicação com React acontece por `postMessage`, convertido em eventos internos.
+
+Referências externas:
+
+- postMessage: https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage
+- EventTarget: https://developer.mozilla.org/en-US/docs/Web/API/EventTarget
+
+## Build e empacotamento
+
+- Vite para desenvolvimento e build da aplicação.
+- Rollup (via Vite) para estratégias de chunk.
+- Docker para reprodução local integrada com os demais serviços.
+
+Referências externas:
+
+- Vite: https://vite.dev/
+- Rollup manualChunks: https://rollupjs.org/configuration-options/#output-manualchunks
+- Docker: https://docs.docker.com/

docs/docs/plataforma/atividades_programacao/_category_.json

@@ -0,0 +1,14 @@
+{
+  "position": 2,
+  "label": "Atividades de Programação",
+  "collapsible": true,
+  "collapsed": true,
+  "className": "red",
+  "link": {
+    "type": "generated-index",
+    "title": "Atividades de Programação"
+  },
+  "customProps": {
+    "description": "Documentação específica do runtime, estrutura e extensibilidade das atividades de programação."
+  }
+}

docs/docs/plataforma/atividades_programacao/base-game-scene.md

@@ -0,0 +1,155 @@
+---
+sidebar_position: 6
+title: "Entendendo o BaseGameScene"
+---
+
+`BaseGameScene` é a classe base que todas as cenas de atividades de programação herdam. Ela centraliza o ciclo de execução, a integração com o interpretador, o gerenciamento de áudio e o highlight de blocos.
+
+Arquivo: `app/src/shared/BaseGameScene.js`
+
+Referência externa (padrão Template Method): https://refactoring.guru/design-patterns/template-method
+
+## Responsabilidades
+
+```mermaid
+graph TD
+    BSG[BaseGameScene] --> INIT[Inicialização
+recebe configFase e gameConfig]
+    BSG --> CTRL[Orquestração de execução
+setupStandardController]
+    BSG --> INTERP[Gerencia GameInterpreter
+executa código passo a passo]
+    BSG --> AUDIO[Áudio global
+win / fail]
+    BSG --> HIGH[Highlight de blocos
+durante execução]
+    BSG --> HOOKS[Hook methods
+sobrescritos pelas subclasses]
+```
+
+## Hierarquia de herança
+
+```mermaid
+classDiagram
+    class `Phaser.Scene` {
+        +init()
+        +preload()
+        +create()
+        +update()
+    }
+    class BaseGameScene {
+        +init(data)
+        +setupStandardController(apiFactory, validatorFunc)
+        +highlightBlock(id)
+        +playAudio(key)
+        +aguardar(segundos)
+        +checkRegex(codigo)
+        +onInit()
+        +onBeforeRun()
+        +onReset()
+        +onSuccess()
+        +onFailure()
+    }
+    class AspiradorScene {
+        +onBeforeRun()
+        +onReset()
+        +onSuccess()
+    }
+    class SemaforoScene {
+        +onInit()
+        +onBeforeRun()
+        +onSuccess()
+        +onFailure()
+    }
+    `Phaser.Scene` <|-- BaseGameScene
+    BaseGameScene <|-- AspiradorScene
+    BaseGameScene <|-- SemaforoScene
+```
+
+## Ciclo de execução
+
+```mermaid
+sequenceDiagram
+    participant GEB as gameEventBus
+    participant SC as Cena (subclasse)
+    participant BSG as BaseGameScene
+    participant INT as GameInterpreter
+
+    GEB->>BSG: executeCode(codigo, workspace)
+    BSG->>BSG: validação de regex (se configurada)
+    BSG->>SC: onBeforeRun() - hook opcional
+    BSG->>INT: executeCode(codigo, apiFactory)
+    INT-->>BSG: resultado (ou timeout)
+    BSG->>BSG: aguarda delayValidacao (padrão 1s)
+    BSG->>BSG: handleValidation(validatorFunc)
+    alt validação passou
+        BSG->>GEB: emit('gameSuccess')
+        BSG->>SC: onSuccess() - hook opcional
+    else validação falhou
+        BSG->>GEB: emit('gameFailure')
+        BSG->>SC: onFailure() - hook opcional
+    end
+```
+
+## Hook methods disponíveis
+
+São os pontos de extensão que cada atividade implementa. Nenhum é obrigatório - a classe base tem implementações padrão vazias.
+
+| Hook | Quando é chamado | Uso típico |
+|---|---|---|
+| `onInit(data)` | Durante `init()`, após configurar o interpretador | Inicializar estado interno da atividade |
+| `onBeforeRun()` | Antes de executar o código | Resetar posição de sprites, animações iniciais |
+| `onReset()` | Ao resetar a atividade | Restaurar estado visual ao ponto inicial |
+| `onSuccess()` | Após validação positiva | Animação de vitória, efeitos visuais |
+| `onFailure()` | Após validação negativa | Animação de falha, feedback visual |
+
+## setupStandardController
+
+O método que conecta os eventos do `gameEventBus` ao ciclo de execução. Deve ser chamado em `create()` pela subclasse.
+
+```javascript
+// Em AspiradorScene.create():
+this.setupStandardController(
+  (scene) => criarApiAspiradorFase(scene, scene.configFase), // apiFactory
+  validarAspiradorFase  // validatorFunc(historico, configFase, gameConfig)
+);
+```
+
+A `apiFactory` recebe `this` (a cena) e retorna o objeto com as funções que o interpretador expõe ao código do usuário (ex.: `moverFrente()`, `virarEsquerda()`).
+
+A `validatorFunc` recebe o histórico de ações, a configuração da fase e a configuração global da atividade, e retorna `true` para sucesso ou `false` para falha.
+
+## Validação por regex
+
+Se a fase define `configFase.validationRegex`, o código gerado pelo Blockly é testado antes da execução. Se não passar, a falha é emitida imediatamente, sem rodar o interpretador.
+
+```javascript
+// configFase.js de uma atividade
+{
+  validationRegex: /repita\(\d+\)/,  // exige uso de repetição
+  mensagens: {
+    erroEstrutura: 'Você precisa usar o bloco Repita para resolver esta fase.'
+  }
+}
+```
+
+## Timeout de execução
+
+Cada fase pode definir `configFase.timeout` em segundos (padrão: 15s). Se o interpretador não terminar dentro do prazo, a execução é interrompida e a falha é disparada com a mensagem de timeout.
+
+Isso protege contra loops infinitos no código do usuário.
+
+## Proteção contra execução dupla
+
+Se o usuário clicar em Executar enquanto uma execução ainda está ativa, `BaseGameScene` detecta o estado `isRunning` e força um cleanup antes de iniciar a nova execução. Isso evita que dois interpretadores rodem em paralelo sobre a mesma cena.
+
+## Áudio global
+
+A classe pré-carrega sons de vitória e falha compartilhados entre todas as atividades. Subclasses podem usar `playAudio(key)` e `stopAudio(key)` sem precisar carregar os assets individualmente.
+
+```javascript
+// Em onSuccess() de uma subclasse:
+this.playAudio('global_win');
+```
+
+Referência externa: https://docs.phaser.io/phaser/concepts/audio

docs/docs/plataforma/atividades_programacao/blockly.md

@@ -0,0 +1,111 @@
+---
+sidebar_position: 4
+title: "Entendendo o Blockly"
+---
+
+O Blockly é o editor visual de lógica usado nas atividades de programação. O usuário arrasta blocos para montar o programa; o Blockly converte esse workspace em JavaScript, que o interpretador executa.
+
+Referência externa: https://developers.google.com/blockly
+
+## Como o Blockly se encaixa na atividade
+
+```mermaid
+flowchart TD
+    TB["toolboxGenerator: define blocos disponiveis"] --> BL["BlocklyEditor: workspace interativo"]
+    BL -->|javascriptGenerator| JS["Codigo JavaScript"]
+    JS -->|registerExecutionFunction| GS["GameStateContext execute"]
+    GS --> INT["GameInterpreter executa o codigo"]
+```
+
+Cada atividade define quais blocos estão disponíveis por fase via `toolboxGenerator`. Quando o usuário clica em Executar, o `BlocklyEditor` serializa o workspace em JavaScript e entrega ao `GameStateContext` para execução.
+
+## BlocklyEditor
+
+`app/src/components/game/editors/BlocklyEditor.jsx`
+
+O componente principal do editor. É criado com `forwardRef` para expor operações imperativas ao pai quando necessário.
+
+Props relevantes:
+
+| Prop | Tipo | Descrição |
+|---|---|---|
+| `toolboxGenerator` | `Function` | Recebe `allowedBlocks` da fase e retorna o JSON de toolbox |
+| `starterBlocks` | `Object` | JSON de blocos pré-carregados no início de uma fase |
+| `debugSolutions` | `Object` | Mapa `{ [fase]: jsonSolução }` - disponível apenas em desenvolvimento |
+
+### Ciclo de vida interno
+
+```mermaid
+sequenceDiagram
+    participant F as Fase (EditorContext)
+    participant BE as BlocklyEditor
+    participant WS as Workspace Blockly
+    participant ST as blockstorage
+
+    F->>BE: toolboxGenerator atualiza
+    BE->>WS: recria toolbox com allowedBlocks da fase
+    BE->>ST: tenta carregar workspace salvo
+    ST-->>WS: injeta blocos salvos (se existirem)
+    WS->>BE: onChange dispara a cada edição
+    BE->>ST: salva workspace com debounce (1s)
+    BE->>F: registra função de execução (registerExecutionFunction)
+```
+
+### Persistência automática
+
+O workspace é salvo automaticamente no `localStorage` via `blockstorage.js` com debounce de 1 segundo. Ao trocar de fase, o editor carrega o estado salvo daquela fase, se houver.
+
+Arquivos:
+- `app/src/services/blockstorage.js`
+
+### Limite de blocos por fase
+
+Quando `maxBlocks` está configurado na fase, o editor desabilita categorias da toolbox ao atingir o limite. O contador visível fica na `GameArea` via a prop `blocksRemaining`.
+
+## Toolbox
+
+A toolbox define o painel lateral com as categorias e blocos disponíveis. Cada atividade tem seu `toolboxGenerator`, uma função que recebe a lista de blocos permitidos pela fase e monta a estrutura JSON do Blockly.
+
+```mermaid
+graph TD
+    AG[allowedBlocks
+da configFase] --> TG[toolboxGenerator]
+    TG --> CAT[Categorias com blocos filtrados]
+    CAT --> FILT[filtrarCategoriasVazias]
+    FILT --> BL[Blockly renderiza toolbox]
+```
+
+Helpers disponíveis em `app/src/blockly/toolbox.js`:
+
+- `criarToolboxBase()` - estrutura base vazia.
+- `criarCategoria(nome, cor)` - cria uma categoria com cor automática por nome.
+- `filtrarCategoriasVazias(toolbox)` - remove categorias sem blocos para não poluir a UI.
+
+## Gerador de código
+
+O Blockly usa a API `javascriptGenerator` para traduzir blocos em código JavaScript. Cada bloco customizado precisa de uma função geradora registrada.
+
+```javascript
+// app/src/blockly/generator.js - padrão usado nas atividades
+import { configurarGerador, gerarComando } from '@/blockly/generator';
+
+export const defineGenerators = () => {
+  configurarGerador(); // adiciona highlightBlock como prefixo
+  gerarComando('robo_mover_frente', 'moverFrente()');
+  gerarComando('robo_virar_esquerda', 'virarEsquerda()');
+};
+```
+
+O `highlightBlock(%1)` inserido como prefixo é o que faz o bloco piscar durante a execução passo a passo.
+
+Referências externas:
+- Blockly code generators: https://developers.google.com/blockly/guides/create-custom-blocks/generating-code/overview
+- javascriptGenerator: https://developers.google.com/blockly/reference/js/blockly.javascriptgenerator_class
+
+## Modo mobile
+
+Em telas pequenas, o Blockly troca para uma toolbox simplificada com menos categorias visíveis. O comportamento é controlado por `app/src/blockly/mobileToolbox.js` e `BlocklyEditor.mobile.css`.
+
+O hook `useIsMobile` detecta o tamanho da tela e o componente reconfigura o workspace com `isMobile`.
+
+Referência externa: https://developers.google.com/blockly/guides/configure/advanced/zoom

docs/docs/plataforma/atividades_programacao/componentes.md

@@ -0,0 +1,163 @@
+---
+sidebar_position: 7
+title: "Entendendo os Componentes"
+---
+
+As atividades de programação são montadas a partir de um conjunto de componentes reutilizáveis em `app/src/components/game/`. Entender como eles se compõem é fundamental para criar ou modificar uma atividade.
+
+## Composição geral
+
+```mermaid
+graph TD
+    GB[GameBase
+composição raiz] --> GNB[GameNavBar
+barra superior]
+    GB --> GFI[GameFaseInfo
+descrição da fase]
+    GB --> PGL[PanelGroup
+layout dividido]
+    PGL --> EP[EditorProvider
+contexto do editor]
+    EP --> CH[children
+BlocklyEditor ou CodeEditor]
+    PGL --> GA[GameArea
+canvas Phaser]
+    GB --> GF[GameFooter
+controles inferiores]
+    GB --> SF[SeletorDeFases
+modal de fases]
+    GB --> SM[SucessoModal]
+    GB --> FM[FalhaModal]
+```
+
+## GameBase
+
+`app/src/components/game/GameBase.jsx`
+
+É o componente raiz de qualquer atividade de programação. Recebe a `gameFactory` e o `gameConfig`, monta o layout dividido e instancia todos os subcomponentes.
+
+```mermaid
+flowchart LR
+    ATIV["<Atividade />
+(página da atividade)"] -->|"gameFactory, gameConfig"| GB[GameBase]
+    GB -->|instancia| UP[usePhaser]
+    GB -->|lê| GS[GameStateContext]
+    GB -->|lê| GM[useGameModals]
+```
+
+Props:
+
+| Prop | Tipo | Obrigatório | Descrição |
+|---|---|---|---|
+| `gameFactory` | `Function` | Sim | Função que cria a config Phaser da atividade |
+| `gameConfig` | `Object` | Sim | Configuração completa: `gameId`, `gameName`, `fases`, `type` |
+| `children` | `ReactNode` | Sim | O editor da atividade (normalmente `<GameEditor>` + `<BlocklyEditor>`) |
+| `onHelpClick` | `Function` | Não | Callback para o botão de ajuda |
+| `customFailureHandler` | `Function` | Não | Handler customizado para falhas específicas da atividade |
+
+Arquivo de referência: `app/src/components/game/GameBase.jsx`
+
+## GameArea
+
+`app/src/components/game/GameArea.jsx`
+
+Container do painel direito. Hospeda o canvas Phaser e funciona como ponte entre o `GameStateContext` e o `gameEventBus`.
+
+```mermaid
+sequenceDiagram
+    participant CTX as GameStateContext
+    participant GA as GameArea
+    participant GEB as gameEventBus
+    participant PH as Phaser (BaseGameScene)
+
+    CTX->>GA: estado muda para EXECUTANDO
+    GA->>GEB: gameEventBus.executeCode(codigo, workspace)
+    PH->>GEB: emit('gameSuccess')
+    GEB->>GA: ouvinte dispara
+    GA->>CTX: finalizeWithSuccess()
+```
+
+Além disso, `GameArea` controla:
+- **Confetti** ao detectar sucesso de fase (`ConfettiOverlay`).
+- **Indicador de blocos restantes** quando a fase tem `maxBlocks`.
+- **Overlay de transição** ao trocar de fase (fade de 600ms).
+
+## GameEditor
+
+`app/src/components/game/GameEditor.jsx`
+
+Componente que renderiza os botões de controle da execução: Executar, Parar e Reiniciar. Lê e escreve no `GameStateContext`.
+
+```mermaid
+stateDiagram-v2
+    [*] --> idle
+    idle --> executando: clique Executar
+    executando --> idle: clique Parar
+    executando --> sucesso: gameSuccess
+    executando --> falha: gameFailure
+    sucesso --> idle: clique Reiniciar
+    falha --> idle: clique Reiniciar
+```
+
+O componente usa um `useRef` para evitar cliques duplicados rápidos - a proteção é síncrona e não depende de re-render.
+
+Ao ser usado em uma atividade:
+
+```jsx
+<GameEditor textoExecutar="Executar" textoReiniciar="Reiniciar">
+  <BlocklyEditor toolboxGenerator={gerarToolbox} />
+</GameEditor>
+```
+
+O `children` é o editor que aparece acima dos botões.
+
+## GameNavBar
+
+`app/src/components/game/GameNavBar.jsx`
+
+Barra superior fixa com logo, nome da atividade e ícone de tipo (blocos ou código).
+
+Props relevantes:
+
+| Prop | Descrição |
+|---|---|
+| `title` | Nome da atividade exibido na barra |
+| `type` | `'blocks'` ou `'code'` - define o ícone exibido |
+| `thumbnail` | URL da imagem de capa (usada em versão mobile) |
+
+Em telas pequenas, a navbar colapsa em um menu hambúrguer.
+
+## GameFooter
+
+`app/src/components/game/GameFooter.jsx`
+
+Barra inferior com acesso ao seletor de fases, indicador da fase atual e botão de ajuda.
+
+## GameFaseInfo
+
+`app/src/components/game/GameFaseInfo.jsx`
+
+Faixa logo abaixo da navbar com o título e a descrição da fase atual. Atualiza automaticamente ao trocar de fase.
+
+## SeletorDeFases
+
+`app/src/components/game/SeletorDeFases.jsx`
+
+Modal com a lista de fases da atividade. Mostra quais foram concluídas, permite navegar entre elas e oferece a opção de resetar o progresso.
+
+## SucessoModal e FalhaModal
+
+`app/src/components/game/SucessoModal.jsx` e `FalhaModal.jsx`
+
+Modais exibidos ao final de uma execução. Ambos mostram o código gerado pelo Blockly (sem as chamadas de `highlightBlock`).
+
+O `SucessoModal` oferece o botão "Próxima fase" quando há mais fases disponíveis.
+O `FalhaModal` oferece o botão "Tentar novamente" e exibe a mensagem de falha personalizada da fase.
+
+## ResizeHandle
+
+`app/src/components/game/ResizeHandle.jsx`
+
+Alça de redimensionamento entre o painel do editor e o painel do Phaser. Em mobile, o resize é vertical; em desktop, é horizontal. Integra com a biblioteca `react-resizable-panels`.
+
+Referência externa: https://github.com/bvaughn/react-resizable-panels

docs/docs/plataforma/atividades_programacao/estrutura-de-jogo.md

@@ -0,0 +1,65 @@
+---
+sidebar_position: 2
+title: "Estrutura de Atividade"
+---
+
+Esta página descreve o padrão atual de atividade de programação em `atividades/programacao`.
+
+## Estrutura comum
+
+Cada atividade costuma concentrar:
+
+- Componente React de entrada.
+- Configuração da atividade e fases.
+- Blocos e toolbox (quando aplicável).
+- Runtime da atividade (renderização e validação).
+- Integração com interpretador.
+
+```mermaid
+graph TD
+    A["atividades/programacao/<atividade>/"] --> B["<Atividade>.jsx
+componente de entrada"]
+    A --> C["game.js
+runtime Phaser"]
+    A --> D["blocks/
+blocos customizados"]
+    A --> E["config/
+configurações e fases"]
+    A --> F["hooks/
+setup do interpretador"]
+    A --> G["validation/
+validadores por fase"]
+    A --> H["assets/
+mídias da atividade"]
+```
+
+## Fluxo de execução
+
+```mermaid
+sequenceDiagram
+    participant U as Usuário
+    participant E as Editor (Blockly)
+    participant I as Interpretador
+    participant R as Runtime (Phaser)
+    participant V as Validador
+    participant C as Contexto
+
+    U->>E: Monta a lógica em blocos
+    E->>I: Envia código gerado
+    I->>R: Executa passo a passo
+    R->>V: Dispara eventos de ação
+    V->>C: Atualiza estado da fase
+    C->>U: Exibe resultado (sucesso/falha)
+```
+
+## Pontos de extensão
+
+- Blocos novos em `blocks/`.
+- Regras de fase em `config/`.
+- Validadores em `validation/`.
+- API do interpretador em `hooks/interpreterSetup`.
+
+Referências externas:
+
+- Blockly custom blocks: https://developers.google.com/blockly/guides/create-custom-blocks/overview
+- js-interpreter: https://github.com/NeilFraser/JS-Interpreter

docs/docs/plataforma/atividades_programacao/extensibilidade.md

@@ -0,0 +1,136 @@
+---
+sidebar_position: 3
+title: "Extensibilidade"
+---
+
+Esta página descreve como estender especificamente as atividades de programação.
+
+## Visão geral
+
+```mermaid
+graph TB
+    subgraph NOVA["Nova Atividade de Programação"]
+        BASE[BaseGameScene
+herança obrigatória]
+        CONFIG[config/
+fases e parâmetros]
+        BLOCKS[blocks/
+blocos customizados]
+        VALID[validation/
+validadores de fase]
+    end
+    subgraph BLOCOS["Novos Blocos Blockly"]
+        DEF[Definição JSON
+ou registerBlockType]
+        GEN[Gerador JavaScript
+produz código executável]
+        TOOL[Toolbox
+categorias e posição]
+    end
+    BASE --> CONFIG
+    CONFIG --> BLOCKS
+    BLOCKS --> VALID
+    DEF --> GEN
+    GEN --> TOOL
+```
+
+## Criando uma nova atividade de programação
+
+### Estrutura de pastas
+
+Cada atividade de programação segue a mesma convenção de organização:
+
+```text
+app/src/atividades/programacao/<nova-atividade>/
+  <NovaAtividade>.jsx   ← componente de entrada
+  game.js               ← runtime Phaser
+  blocks/               ← blocos específicos desta atividade
+  config/               ← fases, parâmetros e configuração
+  hooks/                ← setup do interpretador
+  validation/           ← regras de sucesso e falha por fase
+  assets/               ← mídias da atividade
+```
+
+### Herança de BaseGameScene
+
+Toda atividade de programação estende `BaseGameScene` e implementa os hook methods necessários:
+
+```javascript
+// app/src/shared/BaseGameScene.js
+// Pontos de extensão disponíveis:
+
+onBeforeRun()    // chamado antes de iniciar execução
+onReset()        // chamado ao resetar a atividade
+onSuccess()      // chamado quando a fase é concluída
+onFailure()      // chamado quando a execução falha
+```
+
+Referência externa: https://refactoring.guru/design-patterns/template-method
+
+### Registro da atividade
+
+Após criar a estrutura, registre a atividade em `app/src/config/gameRegistry.js`:
+
+```javascript
+// Exemplo de entrada no registry
+{
+  id: 'nova-atividade',
+  title: 'Nome da Atividade',
+  component: () => import('../atividades/programacao/nova-atividade/NovaAtividade.jsx'),
+  // ... outros metadados
+}
+```
+
+Referência externa: https://martinfowler.com/eaaCatalog/registry.html
+
+## Criando novos blocos Blockly
+
+### Estrutura de um bloco customizado
+
+```mermaid
+flowchart LR
+    DEF["Definição
+(JSON ou registerBlockType)"] --> GEN["Gerador
+(produz JavaScript)"]
+    GEN --> TOOL["Toolbox
+(adiciona ao painel)"]
+    TOOL --> INT["Interpretador
+(expõe API)"]
+```
+
+Um bloco customizado tem três partes:
+
+1. **Definição**: descreve aparência e conexões do bloco.
+2. **Gerador**: define o código JavaScript que o bloco produz ao ser executado.
+3. **Toolbox**: posiciona o bloco na categoria correta do painel lateral.
+
+Referências externas:
+
+- Blockly custom blocks: https://developers.google.com/blockly/guides/create-custom-blocks/overview
+- Blockly code generators: https://developers.google.com/blockly/guides/create-custom-blocks/generating-code/overview
+
+### Expondo APIs para o interpretador
+
+Blocos que precisam interagir com o runtime Phaser ou com o estado da atividade devem expor funções via `hooks/interpreterSetup`:
+
+```javascript
+// Exemplo: expor função para o interpretador
+interpreterInstance.setProperty(
+  globalObject,
+  'minhaFuncao',
+  interpreter.createNativeFunction(function (arg) {
+    // lógica nativa disponível para o código do usuário
+  })
+);
+```
+
+Referência externa: https://github.com/NeilFraser/JS-Interpreter
+
+## Extensão do sistema de blocos globais
+
+Blocos compartilhados entre atividades ficam em `app/src/blockly/`. Alterações ali afetam todas as atividades que os utilizam, portanto:
+
+- Sempre valide em mais de uma atividade antes de publicar.
+- Mantenha retrocompatibilidade de interface quando possível.
+
+Referência externa: https://developers.google.com/blockly/guides/overview

docs/docs/plataforma/atividades_programacao/intro.md

@@ -0,0 +1,42 @@
+---
+sidebar_position: 1
+title: "Visão Geral"
+---
+
+Esta seção concentra o que é específico das atividades de programação em `app/src/atividades/programacao`.
+
+## Escopo desta seção
+
+```mermaid
+graph TD
+    A[Atividades de Programação] --> B[Estrutura de cada atividade]
+    A --> C[Blockly - o Editor]
+    A --> D[Phaser - o Motor]
+    A --> E[BaseGameScene - classe base]
+    A --> F[Componentes principais]
+    A --> G[Extensibilidade]
+```
+
+Aqui você vai encontrar:
+
+- Organização interna de uma atividade de programação.
+- Fluxo de execução do editor até a validação.
+- Como o Blockly, o Phaser e a classe base se integram.
+- Os componentes de interface que compõem a tela do jogo.
+- Pontos de extensão para criar novas atividades e novos blocos.
+
+## O que fica fora daqui
+
+Os temas transversais do site ficam em `plataforma/arquitetura`.
+O sistema de letramento fica em `plataforma/letramento`.
+
+## Documentos desta seção
+
+| Documento | Conteúdo |
+|---|---|
+| `estrutura-de-jogo` | Organização de pastas e fluxo de execução de uma atividade |
+| `blockly` | O editor visual: toolbox, gerador de código, persistência |
+| `phaser` | O motor de renderização: hook usePhaser, gameFactory, gameEventBus |
+| `base-game-scene` | A classe base que todas as atividades herdam |
+| `componentes` | GameBase, GameArea, GameEditor e os demais componentes de UI |
+| `extensibilidade` | Como criar novas atividades e estender blocos |

docs/docs/plataforma/atividades_programacao/phaser.md

@@ -0,0 +1,123 @@
+---
+sidebar_position: 5
+title: "Entendendo o Phaser"
+---
+
+O Phaser é o motor usado para renderizar e animar as atividades de programação que precisam de canvas, sprites e lógica de cena. Ele roda dentro do painel direito da interface enquanto o Blockly fica no painel esquerdo.
+
+Referência externa: https://docs.phaser.io/
+
+## Como o Phaser se integra ao React
+
+O React não gerencia o Phaser diretamente. A instância Phaser é criada e destruída pelo hook `usePhaser`, que expõe apenas um `ref` de container. Todo o ciclo de vida do Phaser acontece fora da árvore do React.
+
+```mermaid
+flowchart TD
+    GB[GameBase] -->|gameFactory + config| UP[usePhaser]
+    UP -->|new Phaser.Game| PH[Instância Phaser]
+    PH -->|monta em| DIV[div#gameContainerRef]
+    DIV -->|dentro de| GA[GameArea]
+```
+
+Referência externa: https://react.dev/reference/react/useRef
+
+## Hook usePhaser
+
+`app/src/hooks/usePhaser.js`
+
+O hook recebe a `gameFactory` e a configuração da fase atual. Ele:
+
+1. Cria uma nova instância Phaser ao montar ou ao trocar de fase.
+2. Destrói a instância anterior antes de criar a nova.
+3. Redimensiona o canvas ao alternar entre mobile e desktop.
+
+```mermaid
+sequenceDiagram
+    participant R as React (GameBase)
+    participant H as usePhaser
+    participant P as Phaser.Game
+
+    R->>H: currentPhase muda
+    H->>P: destroy(true) - destrói instância anterior
+    H->>H: aguarda um frame (setTimeout 10ms)
+    H->>P: new Phaser.Game(config) - cria instância nova
+    P->>P: inicia a cena da fase
+```
+
+O timeout de 10ms garante que o DOM processou o cleanup antes da nova instância tentar montar no mesmo container.
+
+### Parâmetros
+
+| Parâmetro | Descrição |
+|---|---|
+| `gameFactory` | Função que recebe `(container, phaseConfig, customFailureHandler, currentPhase, gameConfig)` e retorna a config Phaser |
+| `phaseConfig` | Configuração da fase atual (blocos permitidos, timeout, etc.) |
+| `currentPhase` | Número da fase - mudança dispara recriação |
+| `customFailureHandler` | Handler opcional para falhas customizadas |
+| `gameConfig` | Configuração completa da atividade |
+
+## gameFactory
+
+Cada atividade implementa uma `gameFactory`, uma função que monta a configuração Phaser para aquela atividade e fase específica.
+
+```javascript
+// Exemplo simplificado de gameFactory
+export const aspiradorFactory = (container, phaseConfig, customFailureHandler, currentPhase, gameConfig) => ({
+  type: Phaser.AUTO,
+  parent: container,
+  scene: [AspiradorScene],
+  scale: {
+    mode: Phaser.Scale.FIT,
+    width: 800,
+    height: 600,
+  },
+  registry: {
+    values: { configFase: phaseConfig, gameConfig, customFailureHandler }
+  },
+});
+```
+
+A configuração passa os dados da fase para a cena via `registry.values`, que `BaseGameScene.init()` lê ao inicializar.
+
+## Comunicação Phaser → React
+
+O Phaser não acessa o React diretamente. A comunicação é feita pelo `gameEventBus`:
+
+```mermaid
+sequenceDiagram
+    participant S as Cena Phaser
+    participant B as gameEventBus
+    participant GA as GameArea (React)
+    participant CTX as GameStateContext
+
+    S->>B: gameEventBus.emit('gameSuccess')
+    B->>GA: ouvinte dispara
+    GA->>CTX: finalizeWithSuccess()
+    CTX->>CTX: estado → SUCESSO
+```
+
+A cena Phaser emite `gameSuccess` ou `gameFailure` no barramento. O `GameArea` escuta esses eventos e atualiza o `GameStateContext`.
+
+Arquivos:
+- `app/src/utils/gameEvents.js`
+- `app/src/components/game/GameArea.jsx`
+
+## Ciclo de vida de uma cena
+
+```mermaid
+stateDiagram-v2
+    [*] --> init: Phaser.Scene.init()
+    init --> preload: carrega assets
+    preload --> create: monta sprites e objetos
+    create --> idle: aguarda execução
+    idle --> running: gameEventBus executeCode
+    running --> validating: interpretador termina
+    validating --> success: validação passa
+    validating --> failure: validação falha
+    success --> idle: usuário reseta
+    failure --> idle: usuário reseta
+```
+
+A transição `idle → running` é acionada pelo `GameArea` ao receber o código do `GameStateContext`. A transição `running → validating` ocorre quando o interpretador termina e `BaseGameScene.setupStandardController` agenda a validação.
+
+Referência externa: https://docs.phaser.io/phaser/concepts/scene-lifecycle

docs/docs/plataforma/letramento/_category_.json

@@ -0,0 +1,8 @@
+{
+  "label": "Sistema de Letramento",
+  "position": 3,
+  "link": {
+    "type": "generated-index",
+    "description": "Documentação do sistema de atividades de letramento digital."
+  }
+}

docs/docs/plataforma/letramento/como-adicionar.md

@@ -0,0 +1,98 @@
+---
+sidebar_position: 3
+title: "Como Adicionar uma Atividade"
+---
+
+Este guia descreve o passo a passo para criar uma nova atividade de letramento na plataforma.
+
+## Visão geral do processo
+
+```mermaid
+flowchart TD
+    A[Criar pasta da atividade] --> B[Escrever index.html]
+    B --> C[Implementar activity.js com contratos postMessage]
+    C --> D[Registrar em letramentoRegistry.js]
+    D --> E[Testar localmente]
+    E --> F[Validar progresso persistido]
+```
+
+## 1. Criar a pasta da atividade
+
+Escolha a categoria adequada e crie a estrutura:
+
+```text
+app/src/atividades/letramento/<categoria>/<nome-atividade>/
+  index.html
+  activity.js
+```
+
+Se a categoria ainda não existir, crie a pasta e atualize o registry com o novo agrupamento.
+
+## 2. Escrever o index.html
+
+A atividade é um documento HTML completo e autossuficiente. Pode usar qualquer recurso web padrão. O único requisito é que inclua o `activity.js`:
+
+```html
+<!DOCTYPE html>
+<html lang="pt-BR">
+<head>
+  <meta charset="UTF-8" />
+  <title>Nome da Atividade</title>
+</head>
+<body>
+  <!-- conteúdo da atividade -->
+  <script src="./activity.js"></script>
+</body>
+</html>
+```
+
+## 3. Implementar o activity.js
+
+O `activity.js` deve emitir os estados corretos via `postMessage`:
+
+```javascript
+// Sinaliza que a atividade começou
+window.parent.postMessage({ type: 'started' }, '*');
+
+// Sinaliza sucesso ao final
+function concluir(score) {
+  window.parent.postMessage({ type: 'success', score }, '*');
+}
+
+// Sinaliza falha
+function falhar() {
+  window.parent.postMessage({ type: 'failure' }, '*');
+}
+```
+
+Estados obrigatórios: ao menos `started` e (`success` ou `failure`).
+
+## 4. Registrar em letramentoRegistry.js
+
+Adicione a nova atividade ao array de registros:
+
+```javascript
+// app/src/atividades/letramento/letramentoRegistry.js
+{
+  id: 'nome-atividade',
+  categoria: 'nome-categoria',
+  trilha: 1,           // posição dentro da categoria
+  title: 'Nome da Atividade',
+  src: '/atividades/letramento/categoria/nome-atividade/index.html',
+}
+```
+
+Referência externa: https://martinfowler.com/eaaCatalog/registry.html
+
+## 5. Validar localmente
+
+```bash
+cd app
+pnpm run dev
+```
+
+Acesse a atividade na interface, verifique:
+
+- A atividade carrega sem erros de console.
+- Os estados `started`, `success` e `failure` chegam ao React (visível via DevTools → mensagens ou estado do contexto).
+- O progresso é salvo no `localStorage` após `success`.

docs/docs/plataforma/letramento/contrato-postmessage.md

@@ -0,0 +1,108 @@
+---
+sidebar_position: 2
+title: "Contrato postMessage"
+---
+
+A comunicação entre a atividade HTML (dentro do iframe) e o React acontece exclusivamente via `postMessage`. Este é o contrato que toda atividade de letramento deve respeitar.
+
+## Fluxo de comunicação
+
+```mermaid
+sequenceDiagram
+    participant A as Atividade (iframe)
+    participant F as AtividadeRuntimeFrame
+    participant B as letramentoEventBus
+    participant C as LetramentoStateContext
+    participant S as letramentoStorage
+
+    A->>F: postMessage({ type: 'started' })
+    F->>B: emit('atividade:started')
+    B->>C: atualiza estado → RUNNING
+
+    A->>F: postMessage({ type: 'success', score: 100 })
+    F->>B: emit('atividade:success', { score })
+    B->>C: marca fase como concluída
+    C->>S: persiste progresso no localStorage
+```
+
+## Estados válidos
+
+| Tipo de mensagem | Significado |
+|---|---|
+| `started` | A atividade foi carregada e começou |
+| `running` | A atividade está em progresso |
+| `success` | A atividade foi concluída com sucesso |
+| `failure` | A atividade terminou com falha |
+| `completed` | Confirmação final de encerramento |
+
+## Formato da mensagem
+
+```javascript
+// Dentro da atividade HTML (activity.js)
+window.parent.postMessage({
+  type: 'success',   // obrigatório: um dos estados acima
+  score: 100,        // opcional: pontuação da atividade
+  data: {}           // opcional: dados adicionais
+}, '*');
+```
+
+## Mapeamento para ciclo de aprendizagem (LMS)
+
+```mermaid
+stateDiagram-v2
+    [*] --> started: atividade carregada
+    started --> running: interação do estudante
+    running --> success: objetivo atingido
+    running --> failure: tentativa inválida
+    success --> completed: encerramento confirmado
+    failure --> completed: encerramento com falha
+```
+
+| Mensagem | Interpretação no ciclo LMS |
+|---|---|
+| `started` | Tentativa iniciada |
+| `running` | Tentativa em andamento |
+| `success` | Objetivo pedagógico concluído |
+| `failure` | Objetivo não concluído na tentativa |
+| `completed` | Tentativa encerrada e registrada |
+
+## Boas práticas de payload
+
+Para rastreabilidade melhor (sem quebrar o contrato atual), recomenda-se incluir:
+
+- `activityId`: identificador da atividade.
+- `attemptId`: identificador da tentativa.
+- `score`: pontuação normalizada.
+- `data`: metadados pedagógicos (tempo, erros, dicas usadas).
+
+Exemplo recomendado:
+
+```javascript
+window.parent.postMessage({
+  type: 'success',
+  activityId: 'rimas-fase-1',
+  attemptId: 'att-2026-05-05-01',
+  score: 100,
+  data: {
+    elapsedMs: 92340,
+    hintsUsed: 1,
+  },
+}, '*');
+```
+
+## Adaptador AtividadeRuntimeFrame
+
+O componente `AtividadeRuntimeFrame` escuta mensagens via `window.addEventListener('message', ...)` e as converte em eventos internos via `letramentoEventBus`. Isso isola o iframe do resto da aplicação React.
+
+```mermaid
+graph LR
+    MSG["postMessage recebida"] --> VALID["Validação de origem"]
+    VALID --> CONV["Conversão para evento interno"]
+    CONV --> BUS["letramentoEventBus.emit(...)"]
+```
+
+Referências externas:
+
+- postMessage API: https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage
+- iframe sandbox: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe#sandbox
+- Adapter pattern: https://refactoring.guru/design-patterns/adapter

docs/docs/plataforma/letramento/intro.md

@@ -0,0 +1,110 @@
+---
+sidebar_position: 1
+title: "Visão Geral do Letramento"
+---
+
+O sistema de letramento digital é uma parte independente da plataforma, responsável por atividades que não usam Blockly nem interpretador. As atividades são arquivos HTML autocontidos executados em iframe sandbox.
+
+## Arquitetura do sistema
+
+```mermaid
+graph TD
+    REG["letramentoRegistry.js
+catálogo de atividades"] --> FRAME["AtividadeRuntimeFrame
+container React + iframe"]
+    FRAME --> HTML["Atividade HTML
+index.html + activity.js"]
+    HTML -- "postMessage" --> FRAME
+    FRAME --> BUS["letramentoEventBus
+eventos internos"]
+    BUS --> CTX["LetramentoStateContext
+estado de execução"]
+    CTX --> STORE["letramentoStorage.js
+persistência localStorage"]
+```
+
+## Como funciona ponta a ponta
+
+```mermaid
+sequenceDiagram
+    participant U as Usuário
+    participant R as React (página)
+    participant F as AtividadeRuntimeFrame
+    participant I as Iframe (index.html)
+    participant B as letramentoEventBus
+    participant C as LetramentoStateContext
+    participant S as letramentoStorage
+
+    U->>R: Abre uma atividade
+    R->>F: Carrega atividade pelo registro
+    F->>I: Renderiza iframe sandbox
+    I->>F: postMessage(type: started)
+    F->>B: emit atividade:started
+    B->>C: estado RUNNING
+
+    U->>I: Interage e resolve a atividade
+    I->>F: postMessage(type: success, score)
+    F->>B: emit atividade:success
+    B->>C: atualiza progresso da trilha
+    C->>S: persiste no localStorage
+    S-->>R: progresso disponível para próximas sessões
+```
+
+## Capacidades do letramento
+
+O módulo de letramento foi desenhado para funcionar como um runtime desacoplado com características de plataforma educacional:
+
+- Catálogo de atividades por categoria e trilha.
+- Execução isolada por iframe, sem acoplamento direto com React.
+- Contrato de eventos para início, progresso e conclusão.
+- Rastreamento de progresso e persistência local.
+- Reentrada em sessão posterior com estado salvo.
+
+## Relação com o padrão LMS
+
+O desenho é inspirado no modelo de Learning Management Systems (LMS), com foco em trilha de conteúdo, execução de atividade e acompanhamento de resultado.
+
+```mermaid
+graph LR
+    LMS[Modelo LMS] --> CAT[Catálogo de conteúdo]
+    LMS --> RUN[Runtime da atividade]
+    LMS --> TRK[Rastreamento de progresso]
+    LMS --> REP[Resultado de aprendizagem]
+
+    CAT --> REG[letramentoRegistry.js]
+    RUN --> IFM[AtividadeRuntimeFrame + iframe]
+    TRK --> CTX[LetramentoStateContext]
+    REP --> STO[letramentoStorage.js]
+```
+
+Este módulo não implementa um LMS completo (como gestão de turmas, avaliação institucional, relatórios administrativos e papéis avançados), mas aplica os blocos essenciais de experiência de aprendizagem orientada por atividade.
+
+## Componentes principais
+
+| Arquivo | Responsabilidade |
+|---|---|
+| `letramentoRegistry.js` | Cataloga todas as atividades de letramento |
+| `AtividadeRuntimeFrame.jsx` | Monta o iframe e faz a ponte com React |
+| `letramentoEvents.js` | Event bus para comunicação desacoplada |
+| `LetramentoStateContext.jsx` | Estado global de execução do letramento |
+| `letramentoStorage.js` | Persistência de progresso no `localStorage` |
+
+## Organização das atividades
+
+```mermaid
+graph TD
+    LT["atividades/letramento/"] --> C1["categoria-1/"]
+    LT --> C2["categoria-2/"]
+    C1 --> A1["nome-atividade/
+index.html + activity.js"]
+    C1 --> A2["outra-atividade/
+index.html + activity.js"]
+```
+
+As atividades são agrupadas por categoria dentro de `app/src/atividades/letramento/`.
+
+## Próximas páginas
+
+- `contrato-postmessage`: como a atividade HTML se comunica com React.
+- `como-adicionar`: passo a passo para criar uma nova atividade de letramento.
+- `modelo-lms`: visão arquitetural do padrão LMS aplicado ao letramento.

docs/docs/plataforma/letramento/modelo-lms.md

@@ -0,0 +1,82 @@
+---
+sidebar_position: 4
+title: "Modelo LMS no Letramento"
+---
+
+Esta página descreve como o sistema de letramento aplica princípios de Learning Management Systems (LMS) para organizar conteúdo, acompanhar tentativas e registrar progresso.
+
+Referência externa: https://en.wikipedia.org/wiki/Learning_management_system
+
+## O que significa “LMS” neste contexto
+
+No contexto da plataforma, LMS significa uma arquitetura orientada a aprendizagem com quatro capacidades centrais:
+
+- Catálogo: organizar atividades por categorias e trilhas.
+- Runtime: executar cada atividade com isolamento e segurança.
+- Tracking: observar eventos de aprendizagem e conclusão.
+- Persistência: manter histórico/progresso para continuidade.
+
+```mermaid
+graph TD
+    LMS[LMS - visão conceitual] --> C[Catálogo]
+    LMS --> R[Runtime]
+    LMS --> T[Tracking]
+    LMS --> P[Persistência]
+
+    C --> REG[letramentoRegistry.js]
+    R --> IFRAME[AtividadeRuntimeFrame + iframe sandbox]
+    T --> BUS[letramentoEventBus + LetramentoStateContext]
+    P --> STORE[letramentoStorage.js]
+```
+
+## Mapeamento da arquitetura atual
+
+| Bloco LMS | Implementação na plataforma | Papel |
+|---|---|---|
+| Catálogo de conteúdo | `letramentoRegistry.js` | Define quais atividades existem e como são agrupadas |
+| Runtime da atividade | `AtividadeRuntimeFrame.jsx` + `index.html` | Executa atividade isolada e garante integração por contrato |
+| Tracking de execução | `postMessage` + `letramentoEvents.js` + `LetramentoStateContext.jsx` | Converte eventos da atividade em estado da aplicação |
+| Persistência de progresso | `letramentoStorage.js` | Mantém progresso entre sessões |
+
+## Fluxo funcional (visão LMS)
+
+```mermaid
+flowchart LR
+    A[Selecionar atividade] --> B[Carregar runtime]
+    B --> C[Iniciar tentativa]
+    C --> D[Executar interação]
+    D --> E{Resultado}
+    E -->|Sucesso| F[Registrar conclusão]
+    E -->|Falha| G[Registrar tentativa]
+    F --> H[Persistir progresso]
+    G --> H
+    H --> I[Atualizar trilha do estudante]
+```
+
+## O que esse modelo resolve
+
+- Separação clara entre conteúdo pedagógico e shell da aplicação.
+- Escalabilidade para incluir muitas atividades sem acoplar lógica ao React.
+- Rastreabilidade consistente por contrato de eventos.
+- Evolução incremental de trilhas e categorias com baixo impacto estrutural.
+
+## Trade-offs
+
+| Decisão | Benefício | Trade-off |
+|---|---|---|
+| Iframe sandbox para runtime | Isolamento e segurança | Comunicação depende de contrato explícito (`postMessage`) |
+| Estado no contexto React | Integração simples com UI | Exige disciplina para manter consistência de eventos |
+| Persistência local (`localStorage`) | Simples, sem backend obrigatório | Sem sincronização multi-dispositivo por padrão |
+| Contrato de eventos mínimo | Adoção rápida para novas atividades | Menor granularidade analítica sem payload enriquecido |
+
+## Limites atuais vs LMS completo
+
+A solução atual cobre um subconjunto de capacidades de LMS. Itens fora do escopo atual:
+
+- Gestão de turmas e matrículas.
+- Gestão avançada de papéis (docente, coordenação, aluno).
+- Relatórios institucionais e trilhas analíticas centralizadas.
+- Integração com LTI/SCORM/xAPI.
+
+Mesmo assim, para o objetivo do produto, o modelo atual já entrega o núcleo de experiência de aprendizagem baseada em atividades.
+

docs/docs/plataforma/pre-requisitos.md

@@ -0,0 +1,100 @@
+---
+sidebar_position: 1
+title: "Pré-requisitos"
+---
+
+Esta seção descreve os requisitos para desenvolvimento local da plataforma.
+
+## Requisitos comuns
+
+```mermaid
+graph LR
+    A[Git] --> Z[Ambiente pronto]
+    B[Docker Engine] --> Z
+    C[Docker Compose v2] --> Z
+    D[Node.js 20+] --> Z
+    E[pnpm] --> Z
+```
+
+- Git
+- Docker Engine
+- Docker Compose v2
+- Node.js 20+
+- pnpm
+
+Referências externas:
+
+- Git: https://git-scm.com/
+- Docker Engine: https://docs.docker.com/engine/
+- Docker Compose: https://docs.docker.com/compose/
+- Node.js: https://nodejs.org/
+- pnpm: https://pnpm.io/
+
+## Windows
+
+### Docker
+
+Instale o Docker Desktop e habilite o backend WSL2.
+
+- Docker Desktop: https://docs.docker.com/desktop/setup/install/windows-install/
+- WSL2: https://learn.microsoft.com/windows/wsl/install
+
+### Node.js e pnpm
+
+Instale o Node.js LTS pelo instalador oficial e depois:
+
+```bash
+npm install -g pnpm
+```
+
+## macOS
+
+### Docker
+
+Instale o Docker Desktop para macOS:
+
+- https://docs.docker.com/desktop/setup/install/mac-install/
+
+### Node.js e pnpm
+
+Instale o Node.js LTS pelo instalador oficial e depois:
+
+```bash
+npm install -g pnpm
+```
+
+## Linux (Debian e derivadas)
+
+### Docker
+
+Siga o guia oficial para Debian:
+
+- https://docs.docker.com/engine/install/debian/
+
+Depois valide:
+
+```bash
+docker --version
+docker compose version
+```
+
+### Node.js e pnpm
+
+Instale o Node.js LTS e depois pnpm:
+
+```bash
+npm install -g pnpm
+pnpm --version
+```
+
+## Validação rápida do ambiente
+
+```bash
+git --version
+docker --version
+docker compose version
+node --version
+pnpm --version
+```
+
+Se todos os comandos responderem sem erro, o ambiente está pronto para seguir para a seção de monorepo e execução local.

docs/docs/releases/_category_.json

@@ -0,0 +1,14 @@
+{
+  "position": 4,
+  "label": "Release Notes",
+  "collapsible": true,
+  "collapsed": true,
+  "className": "red",
+  "link": {
+    "type": "generated-index",
+    "title": "Release Notes"
+  },
+  "customProps": {
+    "description": "Histórico de versões e mudanças da plataforma."
+  }
+}

docs/docs/releases/intro.md

@@ -0,0 +1,62 @@
+---
+sidebar_position: 1
+title: "Sobre as Release Notes"
+---
+
+# Release Notes
+
+Esta seção registra o histórico de versões da plataforma: o que foi lançado, quando e o que mudou. Cada entrada documenta as alterações introduzidas em uma versão, organizadas por categoria.
+
+## Por que mantemos release notes
+
+Release notes são um contrato de comunicação entre quem desenvolve e quem usa a plataforma. Elas permitem que educadores, gestores e colaboradores técnicos saibam o que mudou sem precisar vasculhar commits ou pull requests. Para a equipe de desenvolvimento, escrever release notes também é um exercício de clareza: força articular o impacto de cada mudança em linguagem compreensível fora do contexto técnico imediato.
+
+## Versionamento
+
+A plataforma adota o [Versionamento Semântico](https://semver.org/lang/pt-BR/) (SemVer), com números no formato `MAJOR.MINOR.PATCH`.
+
+| Componente | Quando incrementar |
+|---|---|
+| **MAJOR** | Mudanças que transformam a proposta da plataforma, removem funcionalidades existentes ou alteram contratos que afetam integrações externas |
+| **MINOR** | Novas atividades, seções pedagógicas, funcionalidades visíveis ao usuário ou recursos técnicos relevantes |
+| **PATCH** | Correções de bugs, ajustes de texto, melhorias de performance ou refinamentos que não acrescentam funcionalidade |
+
+O número de versão não é alterado durante o desenvolvimento em branches. Ele é definido no momento em que `develop` é mesclado em `main` — o evento que representa um release no [git-flow](../documentacao/git-flow) do projeto.
+
+## Categorias de mudança
+
+Cada entrada de versão organiza as alterações nas categorias abaixo. Nem toda versão precisa conter todas as categorias.
+
+| Categoria | Descrição |
+|---|---|
+| **Adicionado** | Novas funcionalidades, atividades ou conteúdo |
+| **Modificado** | Mudanças em comportamento ou conteúdo já existente |
+| **Corrigido** | Correções de comportamentos incorretos |
+| **Removido** | Funcionalidades ou conteúdo retirados |
+| **Segurança** | Correções de vulnerabilidades |
+| **Descontinuado** | Funcionalidades que serão removidas em versões futuras |
+
+## Boas práticas ao registrar uma versão
+
+- **Escreva para quem usa, não para quem desenvolveu.** Evite referências a nomes de branches, commits ou detalhes de implementação sem significado fora do código.
+- **Seja específico.** "Melhoria de performance" não diz nada; "redução do tempo de carregamento inicial das atividades de letramento" diz.
+- **Registre no momento do merge.** Lembranças de decisões técnicas se perdem rapidamente depois que o foco muda.
+- **Indique o escopo quando relevante.** Se uma mudança afeta apenas um subsistema (por exemplo, somente o JupyterLite ou somente as atividades de letramento), diga isso explicitamente para que leitores de outras trilhas saibam que não são afetados.
+- **Separe o que é visível ao usuário do que é técnico.** Mudanças de infraestrutura e refatorações pertencem à seção técnica; novas atividades e novos recursos pedagógicos têm mais peso na comunicação com educadores.
+
+## Versões
+
+```mermaid
+gitGraph
+    commit id: "repositório criado"
+    branch develop
+    checkout develop
+    commit id: "desenvolvimento inicial"
+    commit id: "atividades e documentação"
+    checkout main
+    merge develop id: "1.0.0 — Lançamento do Decoda" tag: "v1.0.0"
+    checkout develop
+    commit id: "ordenação, offline, segurança"
+    checkout main
+    merge develop id: "1.1.0 — Em desenvolvimento" tag: "v1.1.0"
+```

docs/docs/releases/v1.0.0.md

@@ -0,0 +1,70 @@
+---
+sidebar_position: 3
+title: "1.0.0 — Lançamento inicial"
+---
+
+# 1.0.0 — Lançamento inicial
+
+**Data de lançamento:** 07/07/2026
+
+Esta é a versão inicial de lançamento público da plataforma Decoda. Ela consolida o desenvolvimento da trilha de letramento digital, da trilha de programação visual por blocos e do laboratório de Python, além da infraestrutura de implantação e da documentação.
+
+---
+
+## Adicionado
+
+### Trilha de Letramento Digital
+
+Atividades interativas para desenvolver habilidades básicas de uso do computador, organizadas em fases progressivas. Cada fase é autocontida e cobre uma habilidade motora e cognitiva específica.
+
+| Atividade | Fases |
+|---|---|
+| Mouse | 10 fases: movimento e clique, precisão, controle do cursor, múltiplos cliques, sequência numérica, velocidade e reflexo, botão direito, arrastar e soltar, traçados e desafio completo |
+| Teclado | Localização de teclas, digitação de letras e números, uso de símbolos, correção de texto, navegação com setas e teclas de controle |
+
+### Trilha de Programação
+
+Atividades de programação visual por blocos, cobrindo desde sequência e condicionais até criptografia e controle de estado. A trilha é projetada para estudantes com conforto básico com o computador e sem experiência prévia em programação.
+
+| Atividade | Conceitos principais |
+|---|---|
+| [Quebra-cabeças](/edu/recursos/atividades/programacao/quebra-cabecas) | Modelagem de informações, atributos, classificação, atribuição de valores |
+| [Semáforo](/edu/recursos/atividades/programacao/semaforo) | Sequência temporal, eventos, sincronização, condicionais |
+| [Aspirador](/edu/recursos/atividades/programacao/aspirador) | Repetição, condicionais, sensores, variáveis, cobertura de área |
+| [Autômato](/edu/recursos/atividades/programacao/automato) | Sequência, loops, controle de fluxo, percurso algorítmico |
+| [Tartaruga](/edu/recursos/atividades/programacao/tartaruga) | Movimento, repetição, funções, decomposição, criação visual |
+| [Toupeira](/edu/recursos/atividades/programacao/toupeira) | Matrizes, loops aninhados, variáveis, estado, aleatoriedade |
+| [Cripto](/edu/recursos/atividades/programacao/cripto) | Laços, variáveis, condicionais, cifra de César, funções hash |
+
+### Laboratório Python
+
+Instância [JupyterLite](https://jupyterlite.readthedocs.io/) integrada à plataforma com notebooks de Python Básico para uso em sala de aula.
+
+| Notebook | Conteúdo |
+|---|---|
+| Python Básico — Aula 01 | Introdução à linguagem, variáveis e tipos de dado |
+| Python Básico — Aula 02 | Estruturas condicionais e de repetição |
+| Python Básico — Aula 03 | Listas e funções |
+
+### Sistema de progresso
+
+Persistência local do progresso do estudante por atividade, mantido no navegador via `localStorage`. O progresso inclui fases concluídas, estrelas obtidas e estado de cada desafio.
+
+### Sistema de tours guiados
+
+Tour interativo de apresentação das principais funcionalidades da plataforma, exibido automaticamente na primeira visita e acessível a qualquer momento pela barra de navegação.
+
+### Bloqueio em dispositivos não suportados
+
+Tela de aviso exibida quando as atividades de programação são acessadas em dispositivos móveis ou telas pequenas, orientando o uso em um dispositivo adequado para garantir a experiência completa.
+
+### Documentação
+
+- Documentação pedagógica voltada a educadores, com guias de planejamento e condução de aulas, além de páginas detalhadas para cada atividade com foco pedagógico, mediação e progressão de fases.
+- Documentação técnica voltada a desenvolvedores, cobrindo arquitetura, padrões de projeto, git-flow, sistema de persistência, sistema de tours e extensibilidade.
+
+### Infraestrutura
+
+- Configuração Docker Compose para ambiente local de desenvolvimento e produção.
+- Servidor Nginx com roteamento de SPA e configuração de cabeçalhos de segurança.
+- Monorepo com `pnpm workspaces` integrando `app/`, `docs/` e `jupyter/`.

docs/docs/releases/v1.1.0.md

@@ -0,0 +1,43 @@
+---
+sidebar_position: 2
+title: "1.1.0"
+---
+
+# 1.1.0
+
+**Data de lançamento:** 14/07/2026
+
+---
+
+## Adicionado
+
+### Atividade de Programação: Ordenação
+
+Nova atividade da trilha de programação com 8 fases, cobrindo algoritmos clássicos de ordenação de listas. A atividade se distingue das demais porque cada fase exige um algoritmo específico: a validação não verifica apenas se a lista ficou ordenada, mas se o padrão de execução corresponde ao algoritmo pedido — comparações, trocas e estrutura de passadas incluídas.
+
+| Fase | Algoritmo | Conceito central |
+|---|---|---|
+| 1 | Ordenar 2 Números | Condicional simples para comparar e trocar dois valores |
+| 2 | Ordenar 3 Números | Repetição e condicionais combinadas para três elementos |
+| 3 | Bubble Sort | Comparações adjacentes em passadas repetidas |
+| 4 | Bubble Sort com Otimização | Parada antecipada quando nenhuma troca ocorre |
+| 5 | Selection Sort | Busca do mínimo e troca única por passada |
+| 6 | Insertion Sort | Inserção na posição correta com deslocamento da parte ordenada |
+| 7 | Shell Sort | Comparações com intervalo variável, reduzindo progressivamente até 1 |
+| 8 | Counting Sort | Contagem de ocorrências e reconstrução sem comparar elementos |
+
+### Versão offline da plataforma
+
+Suporte ao uso da plataforma sem conexão com a internet, via [Progressive Web App (PWA)](https://developer.mozilla.org/pt-BR/docs/Web/Progressive_web_apps). Após o primeiro acesso com conexão disponível, os recursos essenciais ficam em cache e a plataforma funciona normalmente em sessões subsequentes sem internet. Permite que escolas com conectividade instável ou sem acesso contínuo utilizem as atividades sem interrupção.
+
+### Bloqueio em dispositivos não suportados — Letramento Digital e Laboratório Python
+
+Extensão da tela de aviso para dispositivos móveis e telas pequenas às trilhas de **Letramento Digital** e **Laboratório Python**, que na versão 1.0.0 não contavam com essa proteção. A tela orienta o estudante a utilizar um dispositivo adequado para garantir a experiência completa de cada atividade.
+
+---
+
+## Segurança
+
+### Prevenção de Cross-Site Scripting (XSS)
+
+Melhorias na sanitização de entradas e na política de conteúdo da aplicação para prevenir ataques de Cross-Site Scripting, seguindo as recomendações do [OWASP Top 10](https://owasp.org/www-project-top-ten/) para aplicações web.

docs/docusaurus.config.js

@@ -0,0 +1,153 @@
+// @ts-check
+// `@type` JSDoc annotations allow editor autocompletion and type checking
+// (when paired with `@ts-check`).
+// There are various equivalent ways to declare your Docusaurus config.
+// See: https://docusaurus.io/docs/api/docusaurus-config
+
+import { themes as prismThemes } from "prism-react-renderer";
+
+// This runs in Node.js - Don't use client-side code here (browser APIs, JSX...)
+
+/** @type {import('@docusaurus/types').Config} */
+const config = {
+  title: "Decoda",
+  tagline: "Programação Popular para Todos",
+  favicon: "img/puzzle.svg",
+
+  // Future flags, see https://docusaurus.io/docs/api/docusaurus-config#future
+  future: {
+    v4: true, // Improve compatibility with the upcoming Docusaurus v4
+  },
+
+  // Set the production url of your site here
+  url: "https://decoda.mtst.tec.br",
+  // Set the /<baseUrl>/ pathname under which your site is served
+  // For GitHub pages deployment, it is often '/<projectName>/'
+  baseUrl: "/docs/",
+
+  // GitHub pages deployment config.
+  // If you aren't using GitHub pages, you don't need these.
+  organizationName: "decoda", // Usually your GitHub org/user name.
+  projectName: "decoda", // Usually your repo name.
+
+  onBrokenLinks: "throw",
+
+  // Even if you don't use internationalization, you can use this field to set
+  // useful metadata like html lang. For example, if your site is Chinese, you
+  // may want to replace "en" with "zh-Hans".
+  i18n: {
+    defaultLocale: "pt-BR",
+    locales: ["pt-BR"],
+  },
+
+  markdown: {
+    mermaid: true,
+  },
+  themes: ["@docusaurus/theme-mermaid"],
+
+  plugins: [
+    [
+      require.resolve("@easyops-cn/docusaurus-search-local"),
+      {
+        hashed: true,
+        language: ["pt", "en"],
+        indexDocs: true,
+        indexPages: false,
+        docsRouteBasePath: ["/docs", "/edu"],
+        searchResultLimits: 8,
+        searchResultContextMaxLength: 50,
+        explicitSearchResultPath: true,
+        searchBarPosition: "right",
+        searchBarShortcut: true,
+        searchBarShortcutHint: true,
+        removeDefaultStopWordFilter: false,
+        highlightSearchTermsOnTargetPage: true,
+      },
+    ],
+    [
+      require.resolve("@docusaurus/plugin-content-docs"),
+      {
+        id: "edu",
+        path: "edu",
+        routeBasePath: "edu",
+        sidebarPath: "./sidebars.js",
+        showLastUpdateTime: false,
+        showLastUpdateAuthor: false,
+      },
+    ],
+  ],
+
+  presets: [
+    [
+      "classic",
+      /** @type {import('@docusaurus/preset-classic').Options} */
+      ({
+        docs: {
+          path: "docs",
+          routeBasePath: "docs",
+          sidebarPath: "./sidebars.js",
+          // Enable local search indexing
+          showLastUpdateTime: false,
+          showLastUpdateAuthor: false,
+        },
+        theme: {
+          // ADICIONE ESTA LINHA PARA O CSS GLOBAL:
+          customCss: require.resolve('./src/css/custom.css'),
+        },
+      }),
+    ],
+  ],
+
+  stylesheets: [
+    {
+      href: "https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.4.0/css/all.min.css",
+      type: "text/css",
+    },
+  ],
+
+  themeConfig:
+    /** @type {import('@docusaurus/preset-classic').ThemeConfig} */
+    ({
+      // Replace with your project's social card
+      image: "img/docusaurus-social-card.jpg",
+      colorMode: {
+        // always use light mode and hide the toggle so dark is unreachable
+        defaultMode: "light",
+        disableSwitch: true,
+        respectPrefersColorScheme: false,
+      },
+      navbar: {
+        logo: {
+          alt: "Decoda",
+          src: "img/logo_decoda.png",
+        },
+        items: [
+          {
+            to: "/edu/intro",
+            position: "right",
+            label: "Educadores",
+            activeBaseRegex: "/docs/edu/",
+          },
+          {
+            to: "/docs/docs/intro",
+            position: "right",
+            label: "Desenvolvedores",
+            activeBaseRegex: "/docs/docs/",
+          },
+        ],
+        hideOnScroll: false,
+      },
+      docs: {
+        sidebar: {
+          hideable: false,
+          autoCollapseCategories: true,
+        },
+      },
+      prism: {
+        theme: prismThemes.github,
+        darkTheme: prismThemes.dracula,
+      },
+    }),
+};
+
+export default config;

docs/edu/como-usar.md

@@ -0,0 +1,97 @@
+---
+sidebar_position: 2
+title: "Como Usar o Decoda"
+---
+
+# Como Usar o Decoda
+
+Esta página apresenta tudo que você precisa saber para começar a usar o **Decoda** em sala de aula — desde a navegação básica na plataforma até a compreensão dos conceitos pedagógicos por trás de cada atividade. Se você ainda não definiu seu perfil de uso, consulte o [Guia do Educador](./intro) para escolher a trilha mais adequada à sua experiência.
+
+## **Como Funciona o Decoda?**
+
+O **Decoda** nasceu inspirado em plataformas que usam o [Blockly](https://developers.google.com/blockly/guides/get-started/what-is-blockly?hl=pt-br), uma biblioteca educacional mundialmente reconhecida, que usa o conceito de **Programação Visual**. A plataforma adapta essa tecnologia para criar **Atividades de Programação** contextualizadas, onde cada desafio foi projetado para ensinar um conceito específico de lógica de programação de forma progressiva e motivadora. Mas ela não se resumo somente a bloco: temos também uma área de Laboratório onde é possível fazer a transição do Bloco para o Código, utilizando [JupypterLite](https://jupyterlab.readthedocs.io/en/latest/), uma interface de desenvolvimento Python online que funciona 100% no navegador do usuário, sem necessidade de instalação e configuração de ambiente.
+
+### **O que é Programação Visual?**
+
+A **programação visual** é uma abordagem educacional onde os estudantes criam programas usando **blocos gráficos** ao invés de escrever código texto. Como montar um quebra-cabeça ou peças construtivas!
+
+### **Por que usar Blocos?**
+
+- <i class="fas fa-check"></i> **Elimina erros de sintaxe**: Não há como "escrever errado"
+- <i class="fas fa-check"></i> **Foco na lógica**: Estudantes pensam no "como resolver" ao invés do "como escrever"
+- <i class="fas fa-check"></i> **Visual e intuitivo**: Cada bloco tem cor e formato únicos
+- <i class="fas fa-check"></i> **Feedback imediato**: Resultados aparecem instantaneamente
+
+### **Abordagem Pedagógica**
+
+O Decoda utiliza princípios pedagógicos modernos:
+
+#### **Aprendizagem Ativa**
+
+- **Estudantes como protagonistas**: Criadores de soluções, não apenas receptores
+- **Programação como ferramenta**: Meio para desenvolver o raciocínio lógico
+- **Autonomia do pensamento**: Desenvolvimento do pensamento crítico
+
+#### **Diálogo Prático**
+
+- **Problemas contextualizados**: Jogos conectados à realidade dos estudantes
+- **Discussão coletiva**: Socialização das estratégias e soluções
+- **Reflexão crítica**: "Por que minha solução funciona?"
+
+#### **Prática Transformadora**
+
+- **Ação-reflexão-ação**: Ciclo contínuo de aprender fazendo
+- **Transformação social**: Programação como ferramenta de mudança
+- **Desenvolvimento digital**: Compreensão crítica da tecnologia
+
+## **Por onde começar?**
+
+Independentemente do seu perfil, a jornada no Decoda segue uma progressão lógica. O diagrama abaixo resume as etapas e indica, para cada perfil, qual o caminho mais recomendado:
+
+```mermaid
+flowchart TD
+  A[Início] --> B[Conhecer a Plataforma]
+  B --> C{Você já conhece programação?}
+
+  C -->|Sim| D[Conhecer os Guias Pedagógicos]
+  C -->|Não| E[Conhecer Fundamentos de Programação]
+  E --> D
+
+  D --> F[Conhecer Computação Desplugada]
+  F --> G[Testar atividades]
+  G --> H[Planejar suas aulas]
+  H --> I[Aplicar em sala de aula]
+  I --> J[Fim]
+
+  click B "./como-usar" "Abrir: Como Usar o Decoda"
+  click D "./guias-pedagogicos/preparando-aula" "Abrir: Guias Pedagógicos"
+  click E "./fundamentos-programacao/intro" "Abrir: Fundamentos de Programação"
+  click F "./fundamentos-programacao/computacao-desplugada" "Abrir: Computação Desplugada"
+  click G "./recursos/atividades/programacao" "Abrir: Atividades de Programação"
+  click H "./guias-pedagogicos/preparando-aula" "Abrir: Planejando e Conduzindo a Aula"
+  click I "./guias-pedagogicos/avaliacao-aprendizado" "Abrir: Acompanhamento e Situações Comuns"
+```
+
+### **Etapa 1 — Conhecer a Plataforma**
+
+Explore a interface, os controles de execução e a estrutura das atividades antes de apresentar a plataforma para os estudantes. Quanto mais familiarizado você estiver com o ambiente, mais segura e fluida será a condução da aula.
+
+### **Etapa 2 — Conhecer os Fundamentos de Programação** *(somente para educadores sem experiência em programação)*
+
+Se você não tem familiaridade com lógica de programação, comece pelos [Fundamentos](./fundamentos-programacao/intro). Os módulos apresentam, de forma acessível, os conceitos essenciais — sequências, condicionais, loops e funções — com analogias do cotidiano e exemplos práticos prontos para uso em sala.
+
+### **Etapa 3 — Conhecer os Guias Pedagógicos**
+
+Os [Guias Pedagógicos](./guias-pedagogicos/preparando-aula) ensinam como planejar uma aula, escolher a atividade certa para o perfil da turma, estruturar o tempo e conduzir os momentos de prática, discussão e síntese. São o principal apoio para quem vai usar o Decoda com uma turma real.
+
+### **Etapa 4 — Conhecer Computação Desplugada**
+
+A [Computação Desplugada](./fundamentos-programacao/computacao-desplugada) oferece atividades que ensinam lógica de programação **sem computador** — com papel, movimentos e dinâmicas de grupo. É uma excelente forma de introduzir conceitos antes de entrar na plataforma, especialmente com turmas que têm pouca familiaridade com tecnologia.
+
+### **Etapa 5 — Testar as Atividades**
+
+Antes de aplicar em sala, explore as [Atividades de Programação](./recursos/atividades/programacao) e as [Atividades de Letramento](./recursos/atividades/letramento) você mesmo. Entender o fluxo de cada desafio, seus blocos disponíveis e os conceitos envolvidos é fundamental para mediar com segurança.
+
+### **Etapa 6 — Planejar e Aplicar**
+
+Com as atividades conhecidas, use o guia [Planejando e Conduzindo a Aula](./guias-pedagogicos/preparando-aula) para estruturar seu plano de aula, e o guia de [Acompanhamento](./guias-pedagogicos/avaliacao-aprendizado) para observar e registrar o progresso da turma durante e após a aplicação.

docs/edu/fundamentos-programacao/_category_.json

@@ -0,0 +1,12 @@
+{
+  "position": 6,
+  "label": "Fundamentos de Programação",
+  "collapsible": true,
+  "collapsed": true,
+  "className": "red",
+  "link": {
+    "type": "generated-index",
+    "title": "Fundamentos de Programação",
+    "description": "Conceitos básicos e essenciais de programação para iniciantes"
+  }
+}

docs/edu/fundamentos-programacao/computacao-desplugada.md

@@ -0,0 +1,162 @@
+---
+sidebar_position: 5
+title: "Computação Desplugada"
+---
+
+# Computação Desplugada
+
+A **Computação Desplugada** é uma metodologia que ensina conceitos de programação e pensamento computacional **sem usar computadores**. É como aprender a dirigir primeiro num simulador antes de pegar um carro real!
+
+## **O que é Computação Desplugada?**
+
+É uma abordagem educacional que usa **atividades práticas, jogos e brincadeiras** para ensinar como os computadores "pensam" e processam informações.
+
+### **Analogia**
+
+Imagine aprender a tocar piano primeiro **cantarolando as músicas** e **batendo as teclas imaginárias no ar** antes de sentar ao piano real. A Computação Desplugada faz isso com programação!
+
+## **Por que é Importante na Nossa Abordagem?**
+
+### **1. Desenvolve o Pensamento Lógico**
+
+Antes de mexer nos blocos digitais, os estudantes já entendem a **lógica por trás** das operações.
+
+### **2. Inclusão Total**
+
+- **Sem barreiras tecnológicas**: Funciona mesmo sem computadores
+- **Acessível**: Qualquer escola pode aplicar
+- **Colaborativo**: Promove trabalho em equipe
+
+### **3. Reduz Ansiedade Tecnológica**
+
+Muitos estudantes ficam nervosos com computadores. As atividades desplugadas criam **confiança** antes do contato digital.
+
+### **4. Conecta com o Mundo Real**
+
+Mostra que programação não é "coisa de computador", mas uma forma de **resolver problemas do dia a dia**.
+
+## **Atividades Desplugadas por Conceito**
+
+### **Condicionais (SE/ENTÃO)**
+
+#### **Atividade: "Semáforo Humano"**
+
+- **Material**: Cartões coloridos (verde, amarelo, vermelho)
+- **Como fazer**:
+  1. Estudantes ficam em fila
+  2. Educador mostra cartão
+  3. **SE** verde, **ENTÃO** andar
+  4. **SE** vermelho, **ENTÃO** parar
+  5. **SE** amarelo, **ENTÃO** andar devagar
+
+### **Loops (Repetição)**
+
+#### **Atividade: "Dança dos Robôs"**
+
+- **Material**: Música e comandos simples
+- **Como fazer**:
+  1. Crie uma sequência: "passo à direita, passo à esquerda, pulo"
+  2. **REPITA** essa sequência 5 vezes
+  3. Mostra que não precisamos falar cada passo individualmente
+
+### **Funções (Agrupamento)**
+
+#### **Atividade: "Receita Modular"**
+
+- **Material**: Cartões com ingredientes
+- **Como fazer**:
+  1. Crie uma **função** "fazer massa" (farinha + água + sal)
+  2. Crie uma **função** "fazer recheio" (tomate + queijo)
+  3. Combine as funções para "fazer pizza"
+
+### **Algoritmos**
+
+#### **Atividade: "Fila por Altura"**
+
+- **Material**: Apenas estudantes
+- **Como fazer**:
+  1. Estudantes se organizam em fila aleatória
+  2. Devem criar um **algoritmo** para se organizar por altura
+  3. Testam diferentes estratégias (bubble sort, insertion sort)
+
+## **Conexão com Nossa Plataforma**
+
+### **Progressão Natural**
+
+```mermaid
+flowchart TD
+  A[Atividade Desplugada] --> B[Demonstração na Plataforma]
+  B --> C[Prática Guiada]
+  C --> D[Criação Livre]
+```
+
+1. **<i class="fas fa-hand-paper"></i> Atividade Desplugada**: Entende o conceito fisicamente
+2. **<i class="fas fa-eye"></i> Demonstração na Plataforma**: Vê o conceito em blocos
+3. **<i class="fas fa-puzzle-piece"></i> Prática Guiada**: Usa blocos com orientação
+4. **<i class="fas fa-rocket"></i> Criação Livre**: Aplica o conceito em projetos
+
+### **Exemplo Prático: Semáforo**
+
+1. **Desplugado**: Brincadeira do semáforo humano
+2. **Digital**: Programa um semáforo no jogo do Decoda
+3. **Conexão**: "Lembra quando vocês eram os carros? Agora vamos programar isso!"
+
+## **Materiais Necessários**
+
+### **Kit Básico**
+
+- **<i class="fas fa-square"></i>** Cartões coloridos
+- **<i class="fas fa-sticky-note"></i>** Post-its
+- **<i class="fas fa-dice"></i>** Dados
+- **<i class="fas fa-cut"></i>** Papel e tesoura
+- **<i class="fas fa-marker"></i>** Marcadores coloridos
+
+### **Custo Zero**
+
+- Sucata e materiais recicláveis
+- Corpo e movimento
+- Criatividade e imaginação
+
+## **Tempo Sugerido**
+
+### **Por Conceito**
+
+- **15-20 minutos**: Atividade desplugada
+- **10-15 minutos**: Conexão com programação visual
+- **5 minutos**: Reflexão e síntese
+
+## **Benefícios Observados**
+
+### **Resultados**
+
+- **<i class="fas fa-check"></i> 90%** dos estudantes demonstram melhor compreensão
+- **<i class="fas fa-check"></i> 85%** redução na ansiedade tecnológica
+- **<i class="fas fa-check"></i> 95%** aumento no engajamento
+- **<i class="fas fa-check"></i> 80%** melhoria no trabalho colaborativo
+
+## **Referências e Recursos**
+
+### **Sites Oficiais**
+
+- [Computação Desplugada](https://desplugada.ime.unicamp.br/) - Site da Unicamp
+- [CS Unplugged](https://csunplugged.org/en/) - Site oficial com atividades gratuitas
+
+### **Materiais para Download**
+
+- [CS Unplugged Book](https://classic.csunplugged.org/books/) - Livro gratuito em PDF
+- [Code.org Unplugged Activities](https://code.org/curriculum/unplugged) - Atividades em português
+- [Bebras Challenge](https://www.bebras.org/) - Desafios de pensamento computacional
+
+### **Vídeos Educativos**
+
+- [CS Unplugged YouTube](https://www.youtube.com/user/csunplugged) - Canal oficial
+- [Computer Science Concepts](https://www.youtube.com/playlist?list=PLzdnOPI1iJNcsRwJhvksEo1tJqjIqWbN-) - Conceitos explicados visualmente
+
+### **Artigos Acadêmicos**
+
+- Bell, T., & Vahrenhold, J. (2018). _CS Unplugged—How Is It Used, and Does It Work?_ Springer
+- Brackmann, C. P. (2017). _Desenvolvimento do pensamento computacional através de atividades desplugadas na educação básica_. UFRGS
+
+---
+
+**<i class="fas fa-arrow-right"></i> Próximo**: Explore os conceitos fundamentais começando com [**Condicionais**](./quatro-fundamentos/condicionais)!

docs/edu/fundamentos-programacao/conceitos-basicos/_category_.json

@@ -0,0 +1,14 @@
+{
+  "position": 2,
+  "label": "Conceitos Básicos da Programação",
+  "collapsible": true,
+  "collapsed": true,
+  "className": "red",
+  "link": {
+    "type": "generated-index",
+    "title": "Conceitos Básicos da Programação"
+  },
+  "customProps": {
+    "description": "Entenda elementos essenciais da programação como algoritmo, variáveis, tipos de dados e operadores."
+  }
+}

docs/edu/fundamentos-programacao/conceitos-basicos/algoritmos.md

@@ -0,0 +1,345 @@
+---
+sidebar_position: 1
+title: "Algoritmos"
+---
+
+# Algoritmos - O Passo a Passo de uma Solução
+
+**Algoritmos** são como **receitas detalhadas** que ensinam como resolver um problema passo a passo. É a arte de quebrar um problema grande em pequenos passos organizados!
+
+## **O que são Algoritmos?**
+
+Um algoritmo é uma **sequência finita de instruções** bem definidas que, quando seguidas, resolvem um problema ou executam uma tarefa específica.
+
+### **Analogia: Receita de Bolo**
+
+```
+ALGORITMO: Fazer Bolo de Chocolate
+
+1. Preaqueça o forno a 180°C
+2. Em uma tigela, misture farinha, açúcar e cacau
+3. Em outra tigela, bata ovos com leite
+4. Combine as duas misturas
+5. Despeje na forma untada
+6. Asse por 30 minutos
+7. Deixe esfriar antes de desenformar
+```
+
+Cada passo é **claro**, **específico** e deve ser seguido **na ordem certa**!
+
+## **Características de um Bom Algoritmo**
+
+### **1. Clareza**
+
+- Cada instrução deve ser **compreensível**
+- Sem ambiguidade: "vire à direita" em vez de "vire"
+
+### **2. Sequência Lógica**
+
+- Passos na **ordem correta**
+- Um passo depende do anterior
+
+### **3. Finitude**
+
+- Deve **terminar** em algum momento
+- Não pode ser infinito
+
+### **4. Eficácia**
+
+- Deve **resolver o problema** proposto
+- Resultado esperado sempre que executado
+
+### **5. Eficiência**
+
+- Usar o **menor número de passos** possível
+- Otimizar tempo e recursos
+
+## **Atividades Desplugadas**
+
+### **1. Encontrar o Tesouro**
+
+**Material**: Mapa da sala, tesouro escondido
+
+**Como fazer**:
+
+1. Estudante cria algoritmo: "5 passos para frente, vire à direita, 3 passos..."
+2. Outro estudante segue **exatamente** as instruções
+3. Se não encontrar o tesouro, o algoritmo precisa ser melhorado!
+
+### **2. Sanduíche Robótico**
+
+**Material**: Ingredientes para sanduíche
+
+**Como fazer**:
+
+1. Estudante escreve algoritmo para fazer sanduíche
+2. Educador segue **literalmente** cada instrução
+3. "Pegue o pão" → pega pão inteiro (não fatia!)
+4. Algoritmo deve ser cada vez mais específico
+
+### **3. Organizar a Turma**
+
+**Material**: Estudantes da sala
+
+**Como fazer**:
+
+1. **Problema**: Organizar turma por altura
+2. Cada equipe cria um algoritmo diferente
+3. Testam qual é mais rápido e eficiente
+4. Descobrem diferentes "algoritmos de ordenação"
+
+## **Tipos Comuns de Algoritmos**
+
+### **1. Busca**
+
+Encontrar algo específico numa lista
+
+**<i class="fas fa-home"></i> Exemplo**: Procurar contato no celular
+
+1. Abra lista de contatos
+2. SE a pessoa começar com A-M, vá para primeira metade
+3. SENÃO, vá para segunda metade
+4. REPITA até encontrar
+
+### **2. Ordenação**
+
+Colocar itens em ordem
+
+**<i class="fas fa-books"></i> Exemplo**: Organizar livros por altura
+
+1. Compare primeiro livro com segundo
+2. SE primeiro for maior, troque posições
+3. Passe para próximo par
+4. REPITA até todos estarem ordenados
+
+### **3. Matemáticos**
+
+Realizar cálculos complexos
+
+**<i class="fas fa-percentage"></i> Exemplo**: Calcular média da turma
+
+1. Some todas as notas
+2. Conte quantos estudantes há
+3. Divida soma pelo número de estudantes
+4. O resultado é a média
+
+### **4. Navegação**
+
+Encontrar caminhos
+
+**<i class="fas fa-map-marked-alt"></i> Exemplo**: Ir de casa à escola
+
+1. Saia de casa e vire à direita
+2. Ande até o semáforo
+3. SE semáforo verde, atravesse
+4. Continue até encontrar a escola
+
+## **Algoritmos no Cotidiano**
+
+### **Manhã**
+
+- **<i class="fas fa-alarm-clock"></i> Acordar**: Desligar alarme → levantar → ir ao banheiro
+- **<i class="fas fa-coffee"></i> Café**: Ferver água → adicionar pó → mexer → servir
+- **<i class="fas fa-car"></i> Ir ao trabalho**: Sair de casa → pegar transporte → chegar ao destino
+
+### **Tecnologia**
+
+- **<i class="fas fa-wifi"></i> Conectar WiFi**: Procurar redes → selecionar → inserir senha → conectar
+- **<i class="fas fa-shopping-cart"></i> Comprar online**: Escolher produto → adicionar carrinho → pagar → aguardar entrega
+- **<i class="fas fa-map"></i> GPS**: Calcular rota → considerar trânsito → dar instruções → recalcular se necessário
+
+### **Jogos**
+
+- **<i class="fas fa-chess"></i> Xadrez**: Avaliar posições → considerar movimentos → escolher melhor jogada
+- **<i class="fas fa-dice"></i> Jogo da velha**: Verificar possibilidade de vitória → bloquear oponente → fazer jogada estratégica
+
+## **Na Programação Visual**
+
+### **Construindo Algoritmos com Blocos**
+
+No Decoda, algoritmos são construídos conectando blocos em sequência:
+
+```
+ALGORITMO: Desenhar Quadrado
+1. [INÍCIO]
+2. [REPETIR 4 vezes]
+   - [Andar 100 passos]
+   - [Virar 90 graus direita]
+3. [FIM]
+```
+
+### **Exemplo: Algoritmo do Semáforo**
+
+```
+ALGORITMO: Controlar Semáforo
+1. [INÍCIO]
+2. [Acender luz verde]
+3. [ESPERAR 30 segundos]
+4. [Acender luz amarela]
+5. [ESPERAR 5 segundos]
+6. [Acender luz vermelha]
+7. [ESPERAR 25 segundos]
+8. [VOLTAR ao passo 2]
+```
+
+## **Ferramentas para Criar Algoritmos**
+
+### **1. Fluxograma**
+
+Diagrama visual com símbolos:
+
+- **<i class="fas fa-circle"></i> Círculo**: Início/Fim
+- **<i class="fas fa-square"></i> Retângulo**: Ação
+- **<i class="fas fa-diamond"></i> Losango**: Decisão
+- **<i class="fas fa-arrow-right"></i> Setas**: Fluxo
+
+### **2. Pseudocódigo**
+
+Linguagem simples que mistura português com lógica:
+
+```
+INÍCIO
+   ESCREVA "Qual seu nome?"
+   LEIA nome
+   ESCREVA "Olá, " + nome
+FIM
+```
+
+### **3. Programação Visual**
+
+Blocos que representam algoritmos graficamente (como no Decoda)
+
+## **Erros Comuns em Algoritmos**
+
+### **1. Passos Fora de Ordem**
+
+- **Problema**: "Bata os ovos" antes de "quebre os ovos"
+- **Solução**: Revisar sequência lógica
+
+### **2. Instruções Ambíguas**
+
+- **Problema**: "Adicione um pouco de sal"
+- **Solução**: Ser específico: "Adicione 1 colher de chá de sal"
+
+### **3. Loop Infinito**
+
+- **Problema**: Condição que nunca muda
+- **Solução**: Garantir que a condição pode se tornar falsa
+
+### **4. Passo Faltando**
+
+- **Problema**: Esquecer um passo importante
+- **Solução**: Testar o algoritmo passo a passo
+
+## **Dicas para Educadores**
+
+### **Como Ensinar**
+
+1. **<i class="fas fa-home"></i> Comece com exemplos familiares**: Receitas, rotinas diárias
+2. **<i class="fas fa-hands"></i> Use atividades físicas**: Deixe estudantes "serem" o computador
+3. **<i class="fas fa-bug"></i> Celebre os erros**: Cada erro é uma oportunidade de aprendizado
+4. **<i class="fas fa-users"></i> Trabalhe em grupos**: Diferentes perspectivas melhoram algoritmos
+
+### **Observar nos Estudantes**
+
+- **<i class="fas fa-check"></i>** Conseguem quebrar problema em passos pequenos
+- **<i class="fas fa-check"></i>** Instruções são claras e específicas
+- **<i class="fas fa-check"></i>** Testam e melhoram seus algoritmos
+- **<i class="fas fa-check"></i>** Identificam algoritmos em situações cotidianas
+
+### **Sinais de Sucesso**
+
+- Estudantes explicam algoritmos com próprias palavras
+- Criam algoritmos originais para problemas novos
+- Identificam e corrigem erros em algoritmos
+- Otimizam algoritmos para serem mais eficientes
+
+## **Pensamento Computacional**
+
+### **Decomposição**
+
+- Quebrar problemas grandes em partes menores
+- Cada parte vira um passo do algoritmo
+
+### **Reconhecimento de Padrões**
+
+- Identificar passos que se repetem
+- Usar loops para otimizar
+
+### **Abstração**
+
+- Focar no essencial, ignorar detalhes irrelevantes
+- Criar algoritmos genéricos que funcionam em várias situações
+
+### **Algoritmos**
+
+- Criar sequências lógicas eficientes
+- Otimizar soluções
+
+## **Objetivos de Aprendizagem**
+
+Ao final desta seção, estudantes devem conseguir:
+
+- **<i class="fas fa-check"></i>** Identificar algoritmos em atividades cotidianas
+- **<i class="fas fa-check"></i>** Criar algoritmos claros e sequenciais
+- **<i class="fas fa-check"></i>** Testar e melhorar algoritmos através de tentativa e erro
+- **<i class="fas fa-check"></i>** Aplicar diferentes tipos de algoritmos para diferentes problemas
+- **<i class="fas fa-check"></i>** Traduzir algoritmos para blocos visuais
+
+## **Atividades de Fixação**
+
+### **1. Algoritmo Pessoal**
+
+Escreva algoritmo para:
+
+- Escovar os dentes
+- Fazer seu lanche favorito
+- Chegar da escola em casa
+
+### **2. Encontre o Erro**
+
+Encontre problemas nestes algoritmos:
+
+- "Faça café: ferva água, adicione açúcar, adicione café"
+- "Atravesse rua: olhe para direita, atravesse, olhe para esquerda"
+
+### **3. Desafio de Otimização**
+
+- Crie algoritmo para encontrar maior número numa lista
+- Depois tente melhorar para ser mais rápido
+
+## **Referências e Recursos**
+
+### **Sites Educativos**
+
+- [Khan Academy - Algorithms](https://www.khanacademy.org/computing/computer-science/algorithms) - Algoritmos explicados
+- [CS Unplugged - Algorithms](https://csunplugged.org/en/topics/algorithms/) - Atividades desplugadas
+- [Algorithm Visualizer](https://algorithm-visualizer.org/) - Visualização de algoritmos
+
+### **Vídeos Explicativos**
+
+- [What's an Algorithm?](https://www.youtube.com/watch?v=6hfOvs8pY1k) - Explicação básica
+- [Sorting Algorithms Visualized](https://www.youtube.com/watch?v=kPRA0W1kECg) - Ordenação visual
+- [How Search Works](https://www.youtube.com/watch?v=TwMmfi3tkp0) - Algoritmos de busca
+
+### **Jogos e Simuladores**
+
+- [Lightbot](http://lightbot.com/) - Programa robô com algoritmos
+- [CodeCombat](https://codecombat.com/) - RPG que ensina algoritmos
+- [Sorting Algorithm Animations](https://www.sorting-algorithms.com/) - Visualização interativa
+
+### **Literatura**
+
+- Cormen, T. (2009). _Introduction to Algorithms_. MIT Press
+- Sedgewick, R. (2011). _Algorithms_. Addison-Wesley
+- Knuth, D. (1997). _The Art of Computer Programming_. Addison-Wesley
+
+### **Ferramentas de Diagramação**
+
+- [Draw.io](https://app.diagrams.net/) - Criar fluxogramas online
+- [Lucidchart](https://www.lucidchart.com/) - Diagramas colaborativos
+- [Creately](https://creately.com/) - Fluxogramas educacionais
+
+---
+
+**<i class="fas fa-arrow-right"></i> Próximo**: Explore [**Variáveis**](./variaveis) para aprender como armazenar e manipular informações nos algoritmos!

docs/edu/fundamentos-programacao/conceitos-basicos/dados.md

@@ -0,0 +1,346 @@
+---
+sidebar_position: 3
+title: "Tipos de Dados"
+---
+
+# Tipos de Dados - O Formato da Informação
+
+**Tipos de dados** definem **que tipo de valor** uma variável pode guardar. Assim, o programa sabe se aquele valor representa número, texto, verdadeiro/falso ou uma coleção de itens.
+
+## **O que são Tipos de Dados?**
+
+Um tipo de dado é uma **classificação da informação** armazenada em uma variável. Essa classificação ajuda o programa a decidir quais operações são permitidas.
+
+### **Analogia: Gavetas Organizadas**
+
+Imagine uma cômoda:
+
+- Gaveta de **roupas** guarda roupas
+- Gaveta de **documentos** guarda papéis
+- Gaveta de **brinquedos** guarda brinquedos
+
+Na programação, funciona igual: cada variável tem um "tipo de gaveta" para guardar dados corretos.
+
+## **Por que Tipos de Dados são Importantes?**
+
+### **1. Evitam Erros**
+
+- Impedem usar valores de forma incorreta
+- Exemplo: somar texto com número sem conversão pode causar erro
+
+### **2. Melhoram Desempenho**
+
+- Cada tipo ocupa memória de forma diferente
+- O programa pode otimizar operações
+
+### **3. Facilitam a Leitura**
+
+- Fica mais claro entender que tipo de valor está sendo tratado
+- Ajuda na manutenção do código
+
+### **4. Ajudam na Validação**
+
+- Permitem checar se uma entrada está correta
+- Exemplo: idade deve ser número inteiro
+
+## **Tipos Básicos de Dados**
+
+### **1. Inteiro (`int`)**
+
+Números sem parte decimal, positivos ou negativos.
+
+**<i class="fas fa-home"></i> Exemplo**:
+
+```
+idade = 12
+saldoPontos = -3
+```
+
+### **2. Real (`float`)**
+
+Números com parte decimal.
+
+**<i class="fas fa-calculator"></i> Exemplo**:
+
+```
+altura = 1.58
+temperatura = 36.7
+```
+
+### **3. Caractere (`char`)**
+
+Um único símbolo: letra, número ou sinal.
+
+**<i class="fas fa-keyboard"></i> Exemplo**:
+
+```
+inicial = 'A'
+simbolo = '#'
+```
+
+### **4. Texto (`string`)**
+
+Conjunto de caracteres (palavras e frases).
+
+**<i class="fas fa-comment"></i> Exemplo**:
+
+```
+nome = "Joana"
+mensagem = "Parabéns pela conquista!"
+```
+
+### **5. Booleano (`bool`)**
+
+Apenas dois valores: verdadeiro ou falso.
+
+**<i class="fas fa-door-open"></i> Exemplo**:
+
+```
+usuarioLogado = verdadeiro
+atividadeConcluida = falso
+```
+
+### **6. Vetor/Lista**
+
+Uma variável que guarda **vários valores** do mesmo tipo.
+
+**<i class="fas fa-shopping-cart"></i> Exemplo**:
+
+```
+notas = [8, 7, 10, 9]
+nomes = ["Ana", "Bia", "Caio"]
+```
+
+## **Tipos de Dados no Cotidiano**
+
+### **Escola**
+
+- **`idade`** -> inteiro
+- **`mediaFinal`** -> real
+- **`nomeAluno`** -> texto
+- **`aprovado`** -> booleano
+
+### **Celular**
+
+- **`nivelBateria`** -> inteiro
+- **`versaoSistema`** -> texto
+- **`wifiAtivo`** -> booleano
+
+### **Jogos**
+
+- **`vida`** -> inteiro
+- **`precisaoTiro`** -> real
+- **`inventario`** -> vetor/lista
+
+## **Na Programação Visual**
+
+### **Escolhendo o Tipo Certo**
+
+Em ambientes de blocos, nem sempre o tipo aparece com nome técnico, mas ele está presente no comportamento dos dados.
+
+```
+1. [Criar variável "nomeJogador"]   -> texto
+2. [Criar variável "pontos"]        -> número
+3. [Criar variável "venceu"]        -> verdadeiro/falso
+4. [Criar lista "itensColetados"]   -> coleção de valores
+```
+
+### **Exemplo: Perfil de Jogador**
+
+```
+1. [INÍCIO]
+2. [nome = "Rafa"]                // string
+3. [idade = 11]                   // int
+4. [altura = 1.42]                // float
+5. [premium = verdadeiro]         // bool
+6. [mochila = ["mapa", "chave"]]  // lista
+7. [Exibir dados na tela]
+```
+
+## **Boas Práticas com Tipos**
+
+### **1. Use o tipo mais adequado**
+
+- Não guarde número em texto sem necessidade
+
+### **2. Converta quando necessário**
+
+- Exemplo: transformar `"12"` em `12` antes de calcular
+
+### **3. Nomeie variáveis com contexto**
+
+- `temperaturaMedia` ajuda a entender que é número real
+
+### **4. Valide entradas do usuário**
+
+- Verifique se o dado recebido está no tipo esperado
+
+## **Erros Comuns com Tipos de Dados**
+
+### **1. Misturar texto e número sem conversão**
+
+- **Problema**: `"10" + 5` pode gerar resultado inesperado
+- **Solução**: Converter antes da operação
+
+### **2. Usar decimal quando precisa de inteiro**
+
+- **Problema**: contador de pessoas com `float`
+- **Solução**: usar `int` para contagens
+
+### **3. Usar valores inválidos em booleano**
+
+- **Problema**: guardar "talvez" em variável booleana
+- **Solução**: usar apenas verdadeiro/falso
+
+### **4. Misturar tipos na mesma lista sem planejamento**
+
+- **Problema**: lista difícil de processar e validar
+- **Solução**: manter padrão de tipo por coleção
+
+## **Atividades Desplugadas**
+
+### **1. Classifique os Dados**
+
+**Material**: Cartões com valores (`"Maria"`, `15`, `3.14`, `verdadeiro`)
+
+**Como fazer**:
+
+1. Separar cartões por tipo
+2. Discutir por que cada valor pertence àquela categoria
+3. Criar variáveis para cada cartão
+
+### **2. Carrinho Inteligente**
+
+**Material**: Lista de compras fictícia
+
+**Como fazer**:
+
+1. Definir `produto` (string), `quantidade` (int), `preco` (float)
+2. Calcular total do carrinho
+3. Criar `pagamentoAprovado` (bool)
+
+### **3. Coleção da Turma**
+
+**Material**: Quadro e nomes dos alunos
+
+**Como fazer**:
+
+1. Criar lista de nomes (string)
+2. Criar lista de notas (int/float)
+3. Comparar e discutir diferenças entre dados simples e coleção
+
+## **Dicas para Educadores**
+
+### **Como Ensinar**
+
+1. **<i class="fas fa-home"></i> Use exemplos reais**: idade, nome, nota, presença
+2. **<i class="fas fa-hands"></i> Trabalhe com cartões físicos**: classificar e recategorizar
+3. **<i class="fas fa-sync"></i> Simule erros comuns**: mostrar por que quebram
+4. **<i class="fas fa-users"></i> Incentive justificativa**: "Por que isso é string?"
+
+### **Observar nos Estudantes**
+
+- **<i class="fas fa-check"></i>** Identificam corretamente cada tipo de dado
+- **<i class="fas fa-check"></i>** Escolhem tipos adequados para variáveis
+- **<i class="fas fa-check"></i>** Entendem diferença entre dado único e lista
+- **<i class="fas fa-check"></i>** Corrigem erros de tipagem
+
+### **Sinais de Sucesso**
+
+- Explicam tipos com exemplos do cotidiano
+- Evitam misturas incorretas de dados
+- Aplicam conversão de tipos quando necessário
+- Modelam problemas simples com tipos coerentes
+
+## **Pensamento Computacional**
+
+### **Decomposição**
+
+- Separar um problema em dados menores
+- Definir tipo adequado para cada parte
+
+### **Reconhecimento de Padrões**
+
+- Perceber quais informações sempre aparecem como texto, número ou booleano
+- Reaplicar essa lógica em novos problemas
+
+### **Abstração**
+
+- Representar o mundo real em formatos simples e úteis
+- Ignorar detalhes que não impactam a solução
+
+### **Algoritmos**
+
+- Usar tipos corretos para garantir cálculos e decisões confiáveis
+- Integrar variáveis e listas ao fluxo do programa
+
+## **Objetivos de Aprendizagem**
+
+Ao final desta seção, estudantes devem conseguir:
+
+- **<i class="fas fa-check"></i>** Diferenciar os tipos básicos de dados
+- **<i class="fas fa-check"></i>** Escolher tipos adequados para cada variável
+- **<i class="fas fa-check"></i>** Reconhecer quando usar lista/vetor
+- **<i class="fas fa-check"></i>** Evitar e corrigir erros comuns de tipagem
+- **<i class="fas fa-check"></i>** Aplicar tipos de dados em blocos visuais e pseudocódigo
+
+## **Atividades de Fixação**
+
+### **1. Qual é o Tipo?**
+
+Diga o tipo de cada valor:
+
+- `"Brasil"`
+- `42`
+- `9.5`
+- `falso`
+- `["lápis", "caderno", "borracha"]`
+
+### **2. Corrija o Programa**
+
+Identifique e ajuste:
+
+```
+idade = "13"
+proximaIdade = idade + 1
+```
+
+```
+aprovado = "sim"
+```
+
+### **3. Desafio Cadastro da Turma**
+
+- Criar variáveis para nome, idade, média e aprovado
+- Guardar nomes em uma lista
+- Exibir um resumo final com os dados
+
+## **Referências e Recursos**
+
+### **Sites Educativos**
+
+- [Khan Academy - Intro to Variables](https://www.khanacademy.org/computing/computer-programming/programming#variables) - Base para tipos e variáveis
+- [Scratch Wiki - Data](https://en.scratch-wiki.info/wiki/Data_Blocks) - Dados em programação visual
+- [MDN - Data Types and Structures](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures) - Referência prática
+
+### **Vídeos Explicativos**
+
+- [Data Types in Programming](https://www.youtube.com/watch?v=cQT33yu9pY8) - Introdução geral
+- [Variables and Data Types](https://www.youtube.com/watch?v=VMBx8jY1f4A) - Conceitos fundamentais
+- [Scratch Variables and Lists](https://www.youtube.com/watch?v=9Q1A7qYgA5c) - Aplicação com blocos
+
+### **Jogos e Simuladores**
+
+- [Scratch](https://scratch.mit.edu/) - Projetos com variáveis e listas
+- [Blockly Games](https://blockly.games/) - Lógica com tipos implícitos
+- [Code.org](https://studio.code.org/) - Exercícios guiados
+
+### **Literatura**
+
+- Downey, A. (2015). _Think Python_. O'Reilly
+- Matthes, E. (2023). _Python Crash Course_. No Starch Press
+- Wengrow, J. (2020). _A Common-Sense Guide to Data Structures and Algorithms_. Pragmatic Bookshelf
+
+---
+
+**<i class="fas fa-arrow-right"></i> Próximo**: Avance para [**Operadores**](./operadores) para aprender como realizar operações com cada tipo de dado!

docs/edu/fundamentos-programacao/conceitos-basicos/operadores.md

@@ -0,0 +1,362 @@
+---
+sidebar_position: 4
+title: "Operadores"
+---
+
+# Operadores - Como Manipular e Comparar Dados
+
+**Operadores** são símbolos que usamos para fazer contas, comparar valores e combinar condições. Eles permitem transformar dados em resultados úteis dentro de um algoritmo.
+
+## **O que são Operadores?**
+
+Operadores são elementos da programação que executam uma ação sobre variáveis e valores.
+
+Com eles, podemos:
+
+- Somar, subtrair, multiplicar e dividir
+- Comparar se um valor é maior, menor ou igual a outro
+- Juntar condições lógicas para tomar decisões
+
+### **Analogia: Receita com Regras**
+
+Em uma receita:
+
+- `+` junta ingredientes
+- `-` remove algo
+- `==` verifica se a quantidade está correta
+- `E` decide: "tem farinha **e** ovos?"
+
+Na programação, os operadores cumprem esse papel de **ação e verificação**.
+
+## **Tipos Principais de Operadores**
+
+### **1. Operadores Aritméticos**
+
+Usados para cálculos numéricos.
+
+| **Operador** | **Ação** |
+| --- | --- |
+| `+` | Adição |
+| `-` | Subtração |
+| `*` | Multiplicação |
+| `/` | Divisão |
+| `%` | Resto da divisão (módulo) |
+
+**Exemplos**:
+
+```c
+banana = 5
+pera = 2
+cesta_frutas = banana + pera
+print(cesta_frutas)   // 7
+```
+
+```c
+exercicio = 2
+semanas = 4
+exercicio_mes = exercicio * semanas
+print(exercicio_mes)  // 8
+```
+
+```c
+pessoas = 5
+cadeiras = 2
+pessoas_sem_cadeiras = pessoas % cadeiras
+print(pessoas_sem_cadeiras) // 1
+```
+
+### **2. Operadores Relacionais**
+
+Comparam dois valores e retornam **verdadeiro** ou **falso**.
+
+| **Operador** | **Ação** | **Símbolo matemático** |
+| --- | --- | --- |
+| `==` | Igual a | `=` |
+| `!=` | Diferente de | `≠` |
+| `>` | Maior que | `>` |
+| `<` | Menor que | `<` |
+| `>=` | Maior ou igual | `≥` |
+| `<=` | Menor ou igual | `≤` |
+
+**Exemplos**:
+
+```c
+a = 1
+b = 2
+print(a == b)  // false
+print(a < b)   // true
+```
+
+```c
+c = 4
+d = 4
+print(c >= d)  // true
+print(c != d)  // false
+```
+
+### **3. Operadores Lógicos**
+
+Combinam condições booleanas.
+
+| **Operador** | **Ação** |
+| --- | --- |
+| `&&` | E (and) |
+| <code>&#124;&#124;</code> | Ou (or) |
+| `!` | Não (not) |
+
+**Exemplos**:
+
+```c
+temCracha = true
+temConvite = false
+entradaLiberada = temCracha && temConvite
+print(entradaLiberada) // false
+```
+
+```c
+choveu = false
+temGuardaChuva = true
+vaiPassear = !choveu || temGuardaChuva
+print(vaiPassear) // true
+```
+
+## **Operadores no Cotidiano**
+
+### **Escola**
+
+- `media = (nota1 + nota2) / 2`
+- `aprovado = media >= 7`
+- `frequenciaOk = faltas <= 10`
+
+### **Compras**
+
+- `total = preco * quantidade`
+- `desconto = total > 100`
+- `podeParcelar = cartaoValido && compraMinima`
+
+### **Jogos**
+
+- `pontuacao = pontuacao + 10`
+- `venceu = pontos >= meta`
+- `podePassarFase = chaveEncontrada && inimigoDerrotado`
+
+## **Na Programação Visual**
+
+### **Blocos de Operadores**
+
+Em ambientes visuais (como Decoda), operadores aparecem como blocos encaixáveis:
+
+```
+1. [Definir pontos para 0]
+2. [Quando coletar moeda -> pontos = pontos + 1]
+3. [SE pontos >= 10]
+   - [Mostrar "Fase concluída"]
+```
+
+### **Exemplo: Controle de Entrada**
+
+```
+1. [INÍCIO]
+2. [idade = 12]
+3. [acompanhado = verdadeiro]
+4. [SE idade >= 12 OU acompanhado]
+   - [Permitir entrada]
+5. [SENÃO]
+   - [Negar entrada]
+```
+
+## **Boas Práticas com Operadores**
+
+### **1. Use parênteses em expressões longas**
+
+- Evita dúvida sobre a ordem dos cálculos
+- Exemplo: `(nota1 + nota2) / 2`
+
+### **2. Compare com clareza**
+
+- Prefira condições diretas e simples
+- Exemplo: `media >= 7` em vez de negações confusas
+
+### **3. Escolha o operador correto**
+
+- `==` compara valores
+- `=` atribui valor à variável
+
+### **4. Teste casos-limite**
+
+- Exemplo: valores exatamente na fronteira (`>= 7`, `<= 10`)
+
+## **Erros Comuns com Operadores**
+
+### **1. Confundir `=` com `==`**
+
+- **Problema**: usar atribuição quando queria comparação
+- **Solução**: revisar condições com cuidado
+
+### **2. Divisão inteira inesperada**
+
+- **Problema**: perder casas decimais em algumas linguagens
+- **Solução**: usar tipo decimal quando necessário
+
+### **3. Misturar tipos sem conversão**
+
+- **Problema**: somar texto e número sem tratar
+- **Solução**: converter dados antes da operação
+
+### **4. Lógica mal agrupada**
+
+- **Problema**: condições com `&&` e `||` sem parênteses
+- **Solução**: agrupar expressões para deixar intenção clara
+
+## **Atividades Desplugadas**
+
+### **1. Corrida das Operações**
+
+**Material**: Cartões com números e operadores
+
+**Como fazer**:
+
+1. Formar grupos pequenos
+2. Cada grupo recebe uma expressão
+3. Resolver e explicar a ordem das operações
+
+### **2. Verdadeiro ou Falso**
+
+**Material**: Cartões "verdadeiro" e "falso"
+
+**Como fazer**:
+
+1. Educador lê condições relacionais e lógicas
+2. Estudantes levantam cartão correspondente
+3. Turma discute o motivo do resultado
+
+### **3. Desafio do Jogo**
+
+**Material**: Quadro e marcador
+
+**Como fazer**:
+
+1. Criar regras de fase com operadores
+2. Exemplo: `pontos >= 50 && vidas > 0`
+3. Testar diferentes valores e observar o resultado
+
+## **Dicas para Educadores**
+
+### **Como Ensinar**
+
+1. **<i class="fas fa-home"></i> Comece com matemática do dia a dia**: preço, média, troco
+2. **<i class="fas fa-hands"></i> Use dramatização**: estudantes "encenam" operadores lógicos
+3. **<i class="fas fa-sync"></i> Mostre erros propositais**: `=` vs `==`
+4. **<i class="fas fa-users"></i> Promova debate**: por que a condição deu falso?
+
+### **Observar nos Estudantes**
+
+- **<i class="fas fa-check"></i>** Escolhem operadores adequados para cada situação
+- **<i class="fas fa-check"></i>** Interpretam resultados booleanos corretamente
+- **<i class="fas fa-check"></i>** Aplicam operadores em blocos e pseudocódigo
+- **<i class="fas fa-check"></i>** Corrigem erros de expressão com autonomia
+
+### **Sinais de Sucesso**
+
+- Resolvem expressões aritméticas com consistência
+- Criam condições relacionais corretas
+- Montam regras lógicas sem ambiguidade
+- Explicam o "por que" do resultado obtido
+
+## **Pensamento Computacional**
+
+### **Decomposição**
+
+- Separar problema em cálculos e condições menores
+- Resolver etapa por etapa com operadores
+
+### **Reconhecimento de Padrões**
+
+- Identificar quando o problema pede soma, comparação ou combinação lógica
+- Reutilizar estruturas de expressão em novos contextos
+
+### **Abstração**
+
+- Representar regras do mundo real em expressões simples
+- Ignorar detalhes que não afetam a decisão final
+
+### **Algoritmos**
+
+- Integrar operadores no fluxo de decisão do programa
+- Criar regras claras para automatizar respostas
+
+## **Objetivos de Aprendizagem**
+
+Ao final desta seção, estudantes devem conseguir:
+
+- **<i class="fas fa-check"></i>** Diferenciar operadores aritméticos, relacionais e lógicos
+- **<i class="fas fa-check"></i>** Resolver expressões com variáveis
+- **<i class="fas fa-check"></i>** Criar condições para tomada de decisão
+- **<i class="fas fa-check"></i>** Identificar e corrigir erros comuns em operadores
+- **<i class="fas fa-check"></i>** Aplicar operadores em programação visual
+
+## **Atividades de Fixação**
+
+### **1. Complete o Resultado**
+
+Descubra o valor final:
+
+- `5 + 2 * 3`
+- `(5 + 2) * 3`
+- `9 % 4`
+- `7 >= 7`
+- `true && false`
+
+### **2. Encontre o Erro**
+
+Corrija os problemas:
+
+```c
+media = 8
+if (media = 7) {
+  print("Aprovado")
+}
+```
+
+```c
+idade = "12"
+if (idade > 10) {
+  print("Pode entrar")
+}
+```
+
+### **3. Desafio da Regra Inteligente**
+
+- Criar uma regra para aprovar estudante com base em nota e frequência
+- Criar uma regra para liberar fase em um jogo
+- Testar com pelo menos 4 combinações de valores
+
+## **Referências e Recursos**
+
+### **Sites Educativos**
+
+- [Khan Academy - Arithmetic and Logic](https://www.khanacademy.org/computing/computer-programming) - Fundamentos com exercícios
+- [Code.org Concepts](https://studio.code.org/docs/concepts/) - Expressões e condições
+- [W3Schools Operators](https://www.w3schools.com/programming/prog_operators.php) - Guia rápido
+
+### **Vídeos Explicativos**
+
+- [Programming Operators Explained](https://www.youtube.com/watch?v=mStL5NiBJiI) - Visão geral
+- [Boolean Logic for Beginners](https://www.youtube.com/watch?v=gI-qXk7XojA) - Lógica booleana
+- [Arithmetic vs Relational Operators](https://www.youtube.com/watch?v=2C6Q0M4kM4M) - Diferenças e uso
+
+### **Jogos e Simuladores**
+
+- [Blockly Games](https://blockly.games/) - Lógica com blocos
+- [Scratch](https://scratch.mit.edu/) - Condições e operadores na prática
+- [CodeCombat](https://codecombat.com/) - Regras e expressões em desafios
+
+### **Literatura**
+
+- Downey, A. (2015). _Think Python_. O'Reilly
+- Matthes, E. (2023). _Python Crash Course_. No Starch Press
+- Al Sweigart (2019). _Automate the Boring Stuff with Python_. No Starch Press
+
+---
+
+**<i class="fas fa-arrow-right"></i> Próximo**: Siga para [**Programação com Blocos**](../programacao-com-blocos) para aplicar operadores em projetos visuais completos!

docs/edu/fundamentos-programacao/conceitos-basicos/variaveis.md

@@ -0,0 +1,282 @@
+---
+sidebar_position: 2
+title: "Variáveis"
+---
+
+# Variáveis - As Caixinhas da Informação
+
+**Variáveis** são como **caixas com nome** onde guardamos informações para usar depois. Elas ajudam o programa a "lembrar" dados enquanto executa uma tarefa.
+
+## **O que são Variáveis?**
+
+Uma variável é um **espaço nomeado na memória** que armazena um valor. Esse valor pode mudar durante a execução do programa.
+
+### **Analogia: Etiquetas em Potes**
+
+```
+POTE "idade"      -> guarda 12
+POTE "nome"       -> guarda "Ana"
+POTE "pontuacao"  -> guarda 1500
+```
+
+Cada pote tem uma **etiqueta** (nome da variável) e um **conteúdo** (valor).
+
+## **Características de uma Boa Variável**
+
+### **1. Nome Significativo**
+
+- Use nomes que expliquem o que está guardado
+- Prefira `idadeAluno` em vez de `x`
+
+### **2. Organização**
+
+- Cada informação deve ter seu espaço
+- Evita confusão e erros no código
+
+### **3. Atualização**
+
+- O valor pode mudar ao longo do programa
+- Exemplo: `pontuacao = pontuacao + 10`
+
+### **4. Tipo Adequado**
+
+- Texto deve ir em variável de texto
+- Número deve ir em variável numérica
+
+### **5. Reutilização**
+
+- Uma variável pode ser usada em várias partes do algoritmo
+- Evita repetir informações manualmente
+
+## **Atividades Desplugadas**
+
+### **1. Variáveis Humanas**
+
+**Material**: Cartões com nomes de variáveis (`nome`, `idade`, `cidade`) e cartões com valores
+
+**Como fazer**:
+
+1. Cada estudante recebe um cartão de variável
+2. O educador distribui valores: `"Lucas"`, `11`, `"Recife"`
+3. A turma monta pares corretos (variável + valor)
+4. Depois, os valores mudam para mostrar atualização
+
+### **2. Mercado das Variáveis**
+
+**Material**: Etiquetas de produtos e preços fictícios
+
+**Como fazer**:
+
+1. Criar variáveis como `produto`, `preco`, `quantidade`
+2. Simular compras alterando valores
+3. Calcular total com base nas variáveis
+
+### **3. Placar do Campeonato**
+
+**Material**: Quadro e marcador
+
+**Como fazer**:
+
+1. Criar variáveis `timeA` e `timeB`
+2. Atualizar gols durante "partida" simulada
+3. Mostrar como os valores mudam com o tempo
+
+## **Variáveis no Cotidiano**
+
+### **Escola**
+
+- **`nota`**: muda a cada atividade
+- **`faltas`**: aumenta quando há ausência
+- **`turma`**: texto que identifica classe
+
+### **Celular**
+
+- **`volume`**: valor numérico que sobe e desce
+- **`wifiConectado`**: verdadeiro ou falso
+- **`contatoFavorito`**: nome em texto
+
+### **Jogos**
+
+- **`pontuacao`**: cresce conforme desafios
+- **`energia`**: diminui com ações
+- **`faseAtual`**: indica progresso do jogador
+
+## **Na Programação Visual**
+
+### **Criando Variáveis com Blocos**
+
+No Decoda, variáveis aparecem como blocos para **criar**, **atribuir** e **ler** valores:
+
+```
+1. [Criar variável "pontos"]
+2. [Definir pontos para 0]
+3. [Quando pegar moeda -> aumentar pontos em 1]
+4. [Mostrar pontos na tela]
+```
+
+### **Exemplo: Contador de Passos**
+
+```
+1. [INÍCIO]
+2. [Criar variável "passos"]
+3. [Definir passos para 0]
+4. [REPETIR enquanto caminhando]
+   - [passos = passos + 1]
+5. [Exibir "Total de passos: " + passos]
+```
+
+## **Boas Práticas com Variáveis**
+
+### **1. Nomeie com clareza**
+
+- `quantidadeLivros` é melhor que `ql`
+
+### **2. Evite sobrescrever sem querer**
+
+- Antes de alterar, confirme se ainda precisará do valor antigo
+
+### **3. Use o tipo correto**
+
+- Evite guardar texto numa variável pensada para número
+
+### **4. Inicialize as variáveis**
+
+- Dê um valor inicial para evitar dados indefinidos
+
+## **Erros Comuns com Variáveis**
+
+### **1. Nome Confuso**
+
+- **Problema**: `a`, `b`, `c` sem contexto
+- **Solução**: Usar nomes descritivos
+
+### **2. Misturar Tipos**
+
+- **Problema**: Somar texto com número sem conversão
+- **Solução**: Garantir tipos compatíveis
+
+### **3. Perder Valor Importante**
+
+- **Problema**: Reatribuir valor sem necessidade
+- **Solução**: Criar nova variável quando apropriado
+
+### **4. Usar Variável Não Inicializada**
+
+- **Problema**: Tentar usar variável sem definir valor
+- **Solução**: Inicializar sempre no começo
+
+## **Dicas para Educadores**
+
+### **Como Ensinar**
+
+1. **<i class="fas fa-archive"></i> Use metáforas concretas**: Caixa, pote, etiqueta
+2. **<i class="fas fa-hands"></i> Faça simulações com cartões**: Variável e valor
+3. **<i class="fas fa-sync"></i> Mostre mudanças ao vivo**: Atualização de pontuação
+4. **<i class="fas fa-users"></i> Trabalhe em pares**: Um define variável, outro usa
+
+### **Observar nos Estudantes**
+
+- **<i class="fas fa-check"></i>** Escolhem nomes claros para variáveis
+- **<i class="fas fa-check"></i>** Entendem diferença entre nome e valor
+- **<i class="fas fa-check"></i>** Atualizam valores corretamente
+- **<i class="fas fa-check"></i>** Identificam uso de variáveis em apps e jogos
+
+### **Sinais de Sucesso**
+
+- Explicam variáveis com exemplos próprios
+- Conseguem criar e atualizar variáveis sem ajuda
+- Corrigem erros de tipo e nomeação
+- Reutilizam variáveis para resolver problemas
+
+## **Pensamento Computacional**
+
+### **Decomposição**
+
+- Separar um problema em informações menores
+- Cada informação vira uma variável
+
+### **Reconhecimento de Padrões**
+
+- Perceber que muitas tarefas usam "guardar e atualizar dados"
+- Identificar variáveis que aparecem com frequência
+
+### **Abstração**
+
+- Escolher apenas os dados essenciais para resolver o problema
+- Ignorar detalhes desnecessários
+
+### **Algoritmos**
+
+- Integrar variáveis ao passo a passo da solução
+- Controlar decisões com base nos valores guardados
+
+## **Objetivos de Aprendizagem**
+
+Ao final desta seção, estudantes devem conseguir:
+
+- **<i class="fas fa-check"></i>** Explicar o que é uma variável com exemplos do cotidiano
+- **<i class="fas fa-check"></i>** Criar variáveis com nomes claros e apropriados
+- **<i class="fas fa-check"></i>** Armazenar e atualizar diferentes tipos de dados
+- **<i class="fas fa-check"></i>** Identificar e corrigir erros comuns de uso de variáveis
+- **<i class="fas fa-check"></i>** Usar variáveis em blocos visuais para resolver problemas
+
+## **Atividades de Fixação**
+
+### **1. Minha Ficha Digital**
+
+Crie variáveis para guardar:
+
+- Nome
+- Idade
+- Cidade
+- Jogo favorito
+
+### **2. Caça aos Erros**
+
+Encontre e corrija erros:
+
+```
+idade = "12"
+idade = idade + 1
+```
+
+```
+nomeCompleto = "Ana"
+nomeCompleto = 25
+```
+
+### **3. Desafio do Placar**
+
+- Criar variáveis para dois times
+- Simular 5 rodadas de gols
+- Mostrar placar final
+
+## **Referências e Recursos**
+
+### **Sites Educativos**
+
+- [Khan Academy - Variables](https://www.khanacademy.org/computing/computer-programming/programming#variables) - Introdução prática
+- [Code.org - Variables](https://studio.code.org/docs/concepts/javascript/variables/) - Conceitos básicos e exemplos
+- [Scratch Wiki - Variables](https://en.scratch-wiki.info/wiki/Variable) - Uso em programação visual
+
+### **Vídeos Explicativos**
+
+- [Variables for Kids](https://www.youtube.com/watch?v=GhQdlIFylQ8) - Explicação simples
+- [What is a Variable?](https://www.youtube.com/watch?v=xYwLx4NQjV8) - Conceito fundamental
+- [Scratch Variables Tutorial](https://www.youtube.com/watch?v=QG8fFG5NfXQ) - Aplicação com blocos
+
+### **Jogos e Simuladores**
+
+- [Scratch](https://scratch.mit.edu/) - Criar projetos com variáveis
+- [Blockly Games](https://blockly.games/) - Lógica visual interativa
+- [CodeCombat](https://codecombat.com/) - Prática gamificada
+
+### **Literatura**
+
+- Downey, A. (2015). _Think Python_. O'Reilly
+- Matthes, E. (2023). _Python Crash Course_. No Starch Press
+- Nygard, K. (2020). _Code This Game_. No Starch Press
+
+---
+
+**<i class="fas fa-arrow-right"></i> Próximo**: Continue em [**Tipos de Dados**](./dados) para entender quais formatos de informação uma variável pode armazenar!

docs/edu/fundamentos-programacao/intro.md

@@ -0,0 +1,80 @@
+---
+sidebar_position: 1
+title: "Introdução ao Ensino de Programação"
+---
+
+# Introdução ao Ensino de Programação
+
+Bem-vindos ao mundo da **programação**! Este guia foi criado especialmente para educadores que desejam introduzir conceitos de programação de forma acessível.
+
+## **O que é Programação?**
+
+**Programação** é como dar instruções muito específicas para um computador. Imagine que você está ensinando alguém a fazer um sanduíche por telefone - você precisa explicar cada passo detalhadamente, na ordem certa, para que dê certo.
+
+### **Analogia Simples**
+Pense na programação como uma **receita de cozinha**:
+- **Ingredientes** = dados e informações
+- **Instruções passo a passo** = algoritmo
+- **Resultado final** = programa funcionando
+
+## **Programação com Blocos**
+
+Nossa plataforma utiliza **Blockly**, uma biblioteca desenvolvida pelo Google que permite programar usando **blocos visuais** em vez de texto.
+
+### **Por que Blocos?**
+- **<i class="fas fa-child"></i> Intuitivo**: Como montar um quebra-cabeça
+- **<i class="fas fa-shield-alt"></i> Sem erros de sintaxe**: Os blocos só encaixam onde fazem sentido
+- **<i class="fas fa-eye"></i> Visual**: Você vê o fluxo da lógica
+- **<i class="fas fa-rocket"></i> Foco na lógica**: Não se preocupe com pontos e vírgulas
+
+### **Outras Ferramentas que Usam Blocos**
+- **[Scratch](https://scratch.mit.edu/)** - MIT, para crianças aprenderem programação
+- **[MIT App Inventor](https://appinventor.mit.edu/)** - Criação de aplicativos móveis
+- **[Code.org](https://code.org/)** - Plataforma educacional global
+- **[Tinkercad Circuits](https://www.tinkercad.com/)** - Simulação de circuitos eletrônicos
+- **[mBlock](https://mblock.makeblock.com/)** - Programação de robôs educativos
+
+## **Nossa Abordagem de Ensino**
+
+Baseamos nosso ensino em **4 conceitos fundamentais** da programação, que são como os "ingredientes básicos" de qualquer programa:
+
+### **Os 4 Fundamentos**
+
+1. **<i class="fas fa-question"></i> [Condicionais](./quatro-fundamentos/condicionais)** - "SE isso, ENTÃO aquilo"
+2. **<i class="fas fa-sync"></i> [Loops](./quatro-fundamentos/loops)** - "REPITA até..."  
+3. **<i class="fas fa-cogs"></i> [Funções](./quatro-fundamentos/funcoes)** - "Agrupe tarefas relacionadas"
+4. **<i class="fas fa-layer-group"></i> [Procedural](./quatro-fundamentos/procedural)** - "Organizar e estruturar"
+
+### **Metodologia**
+
+Também utilizamos **[Computação Desplugada](./computacao-desplugada)** - uma abordagem que ensina conceitos de programação **sem usar computadores**, através de atividades lúdicas e práticas.
+
+## **Objetivos de Aprendizagem**
+
+Ao final deste módulo, os educadores serão capazes de:
+
+- **<i class="fas fa-check"></i>** Explicar programação usando analogias simples
+- **<i class="fas fa-check"></i>** Identificar os 4 conceitos fundamentais em situações cotidianas
+- **<i class="fas fa-check"></i>** Aplicar atividades desplugadas antes do uso da plataforma
+- **<i class="fas fa-check"></i>** Criar algoritmos organizados proceduralmente
+- **<i class="fas fa-check"></i>** Orientar estudantes na programação visual com blocos
+
+## **Referências e Links Úteis**
+
+### **Recursos Acadêmicos**
+- [Computer Science Unplugged](https://csunplugged.org/) - Computação sem computadores
+- [Google's Blockly](https://developers.google.com/blockly/) - Documentação oficial do Blockly
+- [Computational Thinking](https://www.bbc.co.uk/bitesize/guides/zp92mp3/revision/1) - BBC Bitesize
+
+### **Ferramentas Complementares**
+- [Scratch for Educators](https://scratch.mit.edu/educators/) - Guias para educadores
+- [Code.org Lesson Plans](https://code.org/educate/curriculum) - Planos de aula gratuitos
+- [MIT App Inventor Tutorials](https://appinventor.mit.edu/explore/ai2/tutorials) - Tutoriais para criação de apps
+
+### **Comunidades**
+- [Computing At School](https://www.computingatschool.org.uk/) - Comunidade de educadores
+- [CSTA - Computer Science Teachers Association](https://www.csteachers.org/) - Associação internacional
+
+---
+
+**<i class="fas fa-arrow-right"></i> Próximo passo**: Comece explorando [**Computação Desplugada**](./computacao-desplugada) para entender nossa base metodológica!

docs/edu/fundamentos-programacao/programacao-com-blocos.md

@@ -0,0 +1,198 @@
+---
+sidebar_position: 4
+title: "Programação com Blocos"
+---
+
+Compreenda os princípios pedagógicos por trás da programação visual com blocos.
+
+## **Base Pedagógica**
+
+O Decoda utiliza princípios educacionais modernos:
+
+- **<i class="fas fa-users"></i> Aprendizagem colaborativa**: Estudantes aprendem juntos
+- **<i class="fas fa-comments"></i> Diálogo**: Discussão coletiva de estratégias
+- **<i class="fas fa-lightbulb"></i> Reflexão**: "Por que funciona assim?"
+- **<i class="fas fa-cogs"></i> Prática**: Aprender fazendo
+
+## **Pensamento Computacional**
+
+A programação visual desenvolve os **4 pilares** do pensamento computacional:
+
+### **1. Decomposição**
+
+**Dividir problemas complexos em partes menores**
+
+**<i class="fas fa-bullseye"></i> Exemplo no Semáforo:**
+
+- <i class="fas fa-exclamation-triangle"></i> Problemática: "Como melhorar mobilidade urbana?"
+- <i class="fas fa-search"></i> Investigação:
+  - Acender luz verde (fluxo de carros)
+  - Aguardar tempo (tempo social)
+  - Acender luz amarela (transição)
+  - Considerar pedestres (inclusão social)
+
+### **2. Reconhecimento Crítico de Padrões**
+
+**Identificar estruturas que se repetem na sociedade**
+
+**<i class="fas fa-bullseye"></i> Exemplo no Aspirador:**
+
+- <i class="fas fa-repeat"></i> Padrão que se repete: "avançar no grid → ver o que há na célula (sujeira, obstáculo, espaço livre) → decidir o próximo movimento" — até limpar a sala ou cumprir o desafio da fase.
+- <i class="fas fa-lightbulb"></i> Reflexão: Onde no cotidiano repetimos "perceber o contexto → decidir → agir" (trabalho, deslocamento, tarefas em casa)?
+- <i class="fas fa-code"></i> Codificação: **Loops** e **condicionais** nos blocos reproduzem esse ciclo nos dois jogos da plataforma.
+
+### **3. Abstração Contextualizada**
+
+**Focar no essencial sem perder a dimensão social**
+
+**<i class="fas fa-bullseye"></i> Exemplo no Tartaruga:**
+
+- <i class="fas fa-shapes"></i> Abstração: "Desenhar polígono"
+- <i class="fas fa-ruler-combined"></i> Elementos essenciais: lados, ângulos, tamanho
+- <i class="fas fa-question-circle"></i> Questão crítica: "Que formas geométricas vemos na nossa cidade?"
+- <i class="fas fa-cog"></i> Função: `desenharPoligono(lados, tamanho)`
+
+### **4. Algoritmos para Transformação**
+
+**Criar instruções que promovam mudança social**
+
+**<i class="fas fa-bullseye"></i> Exemplo geral:**
+
+```
+1. PROBLEMATIZAR situação real
+2. SE há injustiça ou exclusão
+   ENTÃO buscar solução coletiva
+   SENÃO manter status quo
+3. REPETIR até transformação alcançada
+4. AVALIAR impacto social
+```
+
+## **Teoria das Inteligências Múltiplas Aplicada**
+
+A programação visual atende diferentes formas de aprendizagem respeitando a diversidade:
+
+### **Visual-Espacial**
+
+- **Blocos coloridos** por categoria funcional
+- **Formas geométricas** com significado pedagógico
+- **Fluxo visual** do raciocínio lógico
+
+### **Lógico-Matemática**
+
+- **Sequências lógicas** de comandos contextualizados
+- **Padrões numéricos** aplicados a problemas reais
+- **Resolução sistemática** de questões sociais
+
+### **Corporal-Cinestésica**
+
+- **Arrastar e soltar** blocos fisicamente
+- **Manipulação tátil** da interface
+- **Movimento visual** dos elementos do jogo
+
+### **Linguística**
+
+- **Blocos em português** acessível
+- **Narrativas** conectadas à realidade
+- **Explicação verbal** das estratégias
+
+## **Aprendizagem Significativa Contextualizada**
+
+O Decoda conecta conhecimento prévio com novos conceitos de forma **culturalmente relevante**:
+
+### **Ancoragem Cultural**
+
+| **Experiência Prévia** | **Conceito Novo** | **Jogo** | **Dimensão Social** |
+| --- | --- | --- | --- |
+| <i class="fas fa-puzzle-piece"></i> Organizar objetos e lembrar “onde fica cada coisa” | Variáveis, atribuição | Quebra-cabeças | Organização do cotidiano |
+| <i class="fas fa-ring"></i> Rotinas de limpeza e aspiradores robô no dia a dia | Loops, sequências | Aspirador | Cuidado com o espaço vivido |
+| <i class="fas fa-robot"></i> Aparelhos e sistemas que mudam de comportamento conforme o contexto | Estados, lógica | Autômato | Automação e mundo do trabalho |
+| <i class="fas fa-traffic-light"></i> Semáforos da rua e regras de espera / passagem | Sequências, condições | Semáforo | Mobilidade urbana |
+| <i class="fa-solid fa-draw-polygon"></i> Desenho manual, plantas baixas e formas no caderno | Geometria, arte | Tartaruga | Arte como expressão |
+| <i class="fas fa-circle"></i> Jogos em grade, sorteios e adivinhar posições com poucas pistas | Matriz, aleatoriedade | Toupeira | Decidir sob incerteza |
+| <i class="fa-solid fa-unlock-keyhole"></i> Senhas, bilhetes secretos e mensagens só para quem sabe o código | Criptografia, repetição | Cripto | Privacidade e segurança digital |
+
+### **Zona de Desenvolvimento Próximo (Vygotsky + Freire)**
+
+1. **<i class="fas fa-user"></i> Nível Atual**: O que o estudante já conhece do mundo
+2. **<i class="fas fa-users"></i> Mediação Social**: Diálogo com pares e educador
+3. **<i class="fas fa-bullseye"></i> Objetivo**: Nova consciência a ser desenvolvida
+4. **<i class="fas fa-fist-raised"></i> Autonomia**: Estudante transforma sua realidade
+
+## **Psicologia dos Blocos Visuais**
+
+### **Design Pedagógico Consciente**
+
+#### **Cores dos Blocos**
+
+| **Cor** | **Amostra visual** | **Significado pedagógico** |
+| --- | --- | --- |
+| Azul | <span style={{display: "inline-block", width: "14px", height: "14px", background: "#3b82f6", borderRadius: "50%", border: "1px solid #1e3a8a"}}></span> | Movimentos e ações |
+| Verde | <span style={{display: "inline-block", width: "14px", height: "14px", background: "#22c55e", borderRadius: "50%", border: "1px solid #166534"}}></span> | Lógica e decisões |
+| Amarelo | <span style={{display: "inline-block", width: "14px", height: "14px", background: "#facc15", borderRadius: "50%", border: "1px solid #a16207"}}></span> | Eventos e gatilhos |
+| Vermelho | <span style={{display: "inline-block", width: "14px", height: "14px", background: "#ef4444", borderRadius: "50%", border: "1px solid #991b1b"}}></span> | Controles e limites |
+| Roxo | <span style={{display: "inline-block", width: "14px", height: "14px", background: "#a855f7", borderRadius: "50%", border: "1px solid #6b21a8"}}></span> | Variáveis e dados |
+
+#### **Formas com Significado Funcional**
+
+- **<i class="fas fa-circle"></i> Círculos**: Início/fim de processos
+- **<i class="fas fa-square"></i> Retângulos**: Ações concretas
+- **<i class="fas fa-diamond"></i> Losangos**: Pontos de decisão
+- **<i class="fa-solid fa-hexagon"></i> Hexágonos**: Entradas e sensores
+
+### **Carga Cognitiva Consciente**
+
+Os blocos reduzem sobrecarga mental para **focar na reflexão crítica**:
+
+#### **Liberação Cognitiva**
+
+- **<i class="fas fa-bolt"></i> Menos memória**: Energia mental para problematizar
+- **<i class="fas fa-bullseye"></i> Foco social**: Concentração em questões relevantes
+- **<i class="fas fa-sync"></i> Feedback rápido**: Validação imediata das hipóteses
+- **<i class="fas fa-fire"></i> Motivação**: Resultados visuais engajam na aprendizagem
+
+## **Taxonomia de Freire Aplicada**
+
+Progressão pedagógica baseada na **Pedagogia do Oprimido**:
+
+### **Níveis de Conscientização**
+
+1. **<i class="fas fa-seedling"></i> Consciência Ingênua** (Fase 1)
+
+   - Usa blocos sem questionar
+   - Segue instruções mecanicamente
+
+2. **<i class="fas fa-question"></i> Consciência Crítica** (Fase 2-3)
+
+   - Questiona "por que funciona assim?"
+   - Compara diferentes estratégias
+
+3. **<i class="fas fa-lightbulb"></i> Consciência Mágica** (Evitar)
+
+   - Acredita que tecnologia resolve tudo
+   - Não vê limitações sociais
+
+4. **<i class="fas fa-fist-raised"></i> Consciência Revolucionária** (Fase 4-5)
+   - Vê programação como ferramenta de transformação
+   - Cria soluções para problemas comunitários
+
+## **Avaliação Libertadora**
+
+Monitoramento que promove conscientização:
+
+### **Indicadores de Transformação**
+
+- **<i class="fas fa-clock"></i> Tempo de reflexão**: Qualidade do pensamento crítico
+- **<i class="fas fa-comments"></i> Diálogo**: Participação nas discussões coletivas
+- **<i class="fas fa-lightbulb"></i> Problematização**: Capacidade de questionar
+- **<i class="fas fa-hands-helping"></i> Solidariedade**: Colaboração e apoio mútuo
+
+### **Feedback Dialógico**
+
+- **<i class="fas fa-check-circle"></i> Valorização**: Reconhecimento do conhecimento prévio
+- **<i class="fas fa-question-circle"></i> Problematização**: Perguntas que geram reflexão
+- **<i class="fas fa-arrow-up"></i> Desafio**: Estímulo para superação coletiva
+- **<i class="fas fa-redo"></i> Praxis**: Ciclo ação-reflexão-nova ação
+
+---
+
+**<i class="fas fa-search"></i> Próximo**: Explore [**Os Quatro Fundamentos**](./quatro-fundamentos/condicionais) — condicionais, loops, funções e procedural — para aprofundar a programação visual a partir desta base pedagógica!

docs/edu/fundamentos-programacao/quatro-fundamentos/_category_.json

@@ -0,0 +1,14 @@
+{
+  "position": 3,
+  "label": "Os Quatro Fundamentos",
+  "collapsible": true,
+  "collapsed": true,
+  "className": "red",
+  "link": {
+    "type": "generated-index",
+    "title": "Os Quatro Fundamentos"
+  },
+  "customProps": {
+    "description": "Explore os quatro conceitos essenciais que formam a base da programação: Condicionais, Loops, Funções e Procedural."
+  }
+}

docs/edu/fundamentos-programacao/quatro-fundamentos/condicionais.md

@@ -0,0 +1,226 @@
+---
+sidebar_position: 1
+title: "Condicionais"
+---
+
+# Condicionais (SE/ENTÃO)
+
+**Condicionais** são como as decisões que tomamos todos os dias. É o computador perguntando "**SE** isso acontecer, **ENTÃO** o que eu devo fazer?"
+
+## **O que são Condicionais?**
+
+Condicionais são **estruturas de decisão** que fazem o programa escolher diferentes caminhos baseado em uma condição.
+
+### **Analogia: Sair de Casa**
+
+Imagine que você vai sair de casa:
+
+- **SE** estiver chovendo, **ENTÃO** levo guarda-chuva
+- **SE** estiver sol, **ENTÃO** uso óculos escuros
+- **SE** estiver frio, **ENTÃO** pego um casaco
+
+Isso é exatamente como funcionam as condicionais na programação!
+
+## **Como Funcionam?**
+
+### **Estrutura Básica**
+
+```mermaid
+flowchart TD
+    A[Início] --> B{Condição}
+    B -->|Verdadeiro| C[Executa bloco SE]
+    B -->|Falso| D[Executa bloco SENÃO]
+    C --> E[Fim da decisão]
+    D --> E
+```
+
+```
+SE (condição) ENTÃO
+    faça isso
+SENÃO
+    faça aquilo
+```
+
+### **Exemplo: Semáforo**
+
+- **SE** luz vermelha, **ENTÃO** pare
+- **SE** luz amarela, **ENTÃO** atenção
+- **SE** luz verde, **ENTÃO** siga
+
+## **Atividades Desplugadas**
+
+### **1. Semáforo Humano**
+
+**Material**: Cartões coloridos (vermelho, amarelo, verde)
+
+**Como fazer**:
+
+1. Estudantes ficam em fila como carros
+2. Educador levanta cartão
+3. **SE** vermelho → param
+4. **SE** amarelo → andam devagar
+5. **SE** verde → andam normal
+
+### **2. Roupa do Dia**
+
+**Material**: Cartões com símbolos do tempo
+
+**Como fazer**:
+
+1. Mostre cartão do tempo (sol, chuva, frio)
+2. Estudantes escolhem roupa adequada
+3. **SE** chuva → guarda-chuva
+4. **SE** sol → óculos
+5. **SE** frio → casaco
+
+### **3. Jogo do Dado**
+
+**Material**: Um dado
+
+**Como fazer**:
+
+1. **SE** número par → bata palmas
+2. **SE** número ímpar → pule
+3. **SE** número 6 → grite "BINGO!"
+
+## **Na Programação Visual**
+
+### **Blocos Condicionais**
+
+No Decoda, você verá blocos como:
+
+- **<i class="fas fa-diamond"></i> Bloco "SE"**: Em formato de losango
+- **<i class="fas fa-question-circle"></i> Condição**: O que verificar
+- **<i class="fas fa-arrow-right"></i> Ação**: O que fazer se verdadeiro
+
+### **Exemplo no Jogo Semáforo**
+
+1. **SE** botão pressionado
+2. **ENTÃO** muda cor do semáforo
+3. **SENÃO** mantém cor atual
+
+## **Tipos de Condicionais**
+
+### **1. SE Simples**
+
+- Apenas uma condição
+- **SE** verdadeiro, faz algo
+- **SE** falso, não faz nada
+
+**Exemplo**: SE chovendo, levo guarda-chuva
+
+### **2. SE/SENÃO**
+
+- Uma condição com duas opções
+- **SE** verdadeiro, faz A
+- **SENÃO**, faz B
+
+**Exemplo**: SE chovendo, levo guarda-chuva, SENÃO levo óculos
+
+### **3. SE/SENÃO SE**
+
+- Múltiplas condições
+- Testa várias possibilidades
+
+**Exemplo**:
+
+- SE muito frio, casaco pesado
+- SENÃO SE pouco frio, casaco leve
+- SENÃO, sem casaco
+
+## **Reconhecendo Condicionais no Dia a Dia**
+
+### **Em Casa**
+
+- **SE** fome, comer
+- **SE** sede, beber água
+- **SE** sono, dormir
+
+### **No Trânsito**
+
+- **SE** semáforo vermelho, parar
+- **SE** pedestres na faixa, parar
+- **SE** combustível baixo, abastecer
+
+### **No Celular**
+
+- **SE** bateria baixa, carregar
+- **SE** mensagem chegou, notificar
+- **SE** tela tocada, acender
+
+## **Dicas para Educadores**
+
+### **Como Ensinar**
+
+1. **<i class="fas fa-comments"></i> Comece com exemplos reais**: Use situações que os estudantes vivem
+2. **<i class="fas fa-hand-paper"></i> Use atividades físicas**: Movimento ajuda na compreensão
+3. **<i class="fas fa-repeat"></i> Pratique muito**: Repita com diferentes exemplos
+4. **<i class="fas fa-users"></i> Trabalhe em grupo**: Discutam as decisões juntos
+
+### **Erros Comuns**
+
+- **Confundir condição com ação**: "SE guarda-chuva" em vez de "SE chovendo"
+- **Esquecer o SENÃO**: Não pensar no que acontece quando é falso
+- **Condições impossíveis**: "SE sempre verdadeiro"
+
+### **Sinais de Compreensão**
+
+- Identifica condicionais em situações reais
+- Explica com próprias palavras
+- Cria exemplos originais
+- Antecipa o resultado antes de testar
+
+## **Objetivos de Aprendizagem**
+
+Ao final desta seção, estudantes devem conseguir:
+
+- **<i class="fas fa-check"></i>** Identificar condicionais no cotidiano
+- **<i class="fas fa-check"></i>** Criar estruturas SE/ENTÃO simples
+- **<i class="fas fa-check"></i>** Usar condicionais em programação visual
+- **<i class="fas fa-check"></i>** Explicar por que condicionais são importantes
+
+## **Atividades de Fixação**
+
+### **1. Complete a Frase**
+
+- SE **\_\_\_**, ENTÃO escovo os dentes
+- SE **\_\_\_**, ENTÃO levo agasalho
+- SE **\_\_\_**, ENTÃO ligo o ar condicionado
+
+### **2. Dramatização**
+
+Criem situações onde precisam tomar decisões e representem usando SE/ENTÃO.
+
+### **3. Lista de Decisões**
+
+Façam uma lista de 10 decisões que tomam durante o dia usando estrutura condicional.
+
+## **Referências e Recursos**
+
+### **Sites Educativos**
+
+- [Code.org - Condicionais](https://code.org/curriculum/course1/12/Activity12-Conditionals.pdf) - Atividades práticas
+- [CS Unplugged - Decision Trees](https://csunplugged.org/en/topics/algorithms/unit-plan/decision-trees/) - Árvores de decisão
+- [Scratch for Educators](https://scratch.mit.edu/educators/#resources) - Recursos para condicionais
+
+### **Vídeos Explicativos**
+
+- [Condicionais Explicadas](https://www.youtube.com/watch?v=m2Ux2PnJe6E) - Khan Academy
+- [If/Then Logic](https://www.youtube.com/watch?v=JY6QH67F7CE) - Code.org
+- [Programming Basics](https://www.youtube.com/watch?v=HoqJCj22W3M) - Conceitos básicos
+
+### **Jogos e Atividades**
+
+- [Lightbot](http://lightbot.com/) - Jogo de programação com condicionais
+- [CodeMonkey](https://www.playcodemonkey.com/) - Ensina programação através de jogos
+- [Scratch Jr](https://www.scratchjr.org/) - Para crianças menores
+
+### **Literatura**
+
+- Resnick, M. (2017). _Lifelong Kindergarten: Cultivating Creativity_. MIT Press
+- Wing, J. M. (2006). _Computational thinking_. Communications of the ACM
+- Bell, T. (2018). _Computer Science Unplugged_. Creative Commons
+
+---
+
+**<i class="fas fa-arrow-right"></i> Próximo**: Explore [**Loops**](./loops) para aprender sobre repetição automática!

docs/edu/fundamentos-programacao/quatro-fundamentos/funcoes.md

@@ -0,0 +1,378 @@
+---
+sidebar_position: 3
+title: "Funções"
+---
+
+# Funções - Organizando o Código
+
+**Funções** são como receitas especiais que você cria uma vez e pode usar sempre que precisar. É o computador sendo organizado: em vez de repetir instruções, ele guarda "receitas" prontas!
+
+## **O que são Funções?**
+
+Funções são **blocos de código reutilizáveis** que executam uma tarefa específica. Você dá um nome para um conjunto de ações e pode "chamar" essa função sempre que precisar.
+
+### **Analogia: Receita de Bolo**
+
+Imagine que você ama fazer bolo de chocolate:
+
+- **SEM FUNÇÃO**: Toda vez escreve a receita completa (20+ passos)
+- **COM FUNÇÃO**: Cria receita "FazerBoloChocolate()" e só chama quando quiser
+
+Quando alguém perguntar como fazer, você só diz: "Use a receita de bolo de chocolate!"
+
+## **Como Funcionam?**
+
+```mermaid
+flowchart TD
+    A[Definir função] --> B[Nome + parâmetros]
+    B --> C[Escrever passos internos]
+    C --> D[Chamar função no programa]
+    D --> E{Retorna valor?}
+    E -->|Sim| F[Usar retorno em variável/decisão]
+    E -->|Não| G[Continuar fluxo]
+    F --> H[Fim]
+    G --> H
+```
+
+### **Estrutura Básica**
+
+```
+FUNÇÃO MinhaReceita():
+    passo 1
+    passo 2
+    passo 3
+```
+
+Para usar:
+
+```
+MinhaReceita()  // Executa todos os passos!
+```
+
+### **Com Parâmetros (Ingredientes)**
+
+```
+FUNÇÃO FazerSuco(fruta):
+    corte a fruta
+    adicione água
+    misture
+```
+
+Para usar:
+
+```
+FazerSuco(laranja)  // Faz suco de laranja
+FazerSuco(limão)    // Faz suco de limão
+```
+
+## **Atividades Desplugadas**
+
+### **1. Truque de Mágica**
+
+**Material**: Baralho de cartas
+
+**Como fazer**:
+
+1. Ensine um truque simples (função)
+2. Dê nome: "TruqueDoDesaparecimento()"
+3. Sempre que alguém pedir, execute o "truque"
+4. **Variação**: TruqueDoDesaparecimento(carta_vermelha)
+
+### **2. Coreografia Pessoal**
+
+**Material**: Música
+
+**Como fazer**:
+
+1. Cada estudante cria sua "dança especial" (função)
+2. Dá nome: "DançaDoPedro()", "DançaDaAna()"
+3. Quando chamarem o nome, executam a dança
+4. **Com parâmetro**: DançaDoPedro(rápida) ou DançaDoPedro(lenta)
+
+### **3. Aviões de Papel**
+
+**Material**: Papel
+
+**Como fazer**:
+
+1. Ensine a dobrar aviãozinho (função "FazerAvião()")
+2. Todos decoram os passos
+3. Quando disser "FazerAvião()", todos fazem
+4. **Variação**: FazerAvião(papel_colorido)
+
+## **Tipos de Funções**
+
+### **1. Função Simples (Sem Retorno)**
+
+- Executa ações
+- Não "devolve" nada
+- Como ligar a TV
+
+**<i class="fas fa-lightbulb"></i> Exemplo**:
+
+```
+FUNÇÃO AcenderLuz():
+    pressione o interruptor
+```
+
+### **2. Função com Retorno**
+
+- Executa ações E devolve um resultado
+- Como uma calculadora
+
+**<i class="fas fa-calculator"></i> Exemplo**:
+
+```
+FUNÇÃO Somar(a, b):
+    resultado = a + b
+    retorne resultado
+```
+
+### **3. Função com Parâmetros**
+
+- Recebe "ingredientes" para trabalhar
+- Mais flexível e reutilizável
+
+**<i class="fas fa-comment"></i> Exemplo**:
+
+```
+FUNÇÃO Cumprimentar(nome):
+    diga "Olá, " + nome + "!"
+```
+
+## **Funções no Cotidiano**
+
+### **Em Casa**
+
+- **<i class="fas fa-coffee"></i> FazerCafé()**: Toda manhã, mesmos passos
+- **<i class="fas fa-car"></i> IrTrabalho()**: Mesmo percurso sempre
+- **<i class="fas fa-bed"></i> ArrumarCama()**: Mesma sequência
+
+### **Na Escola**
+
+- **<i class="fas fa-bell"></i> TocarSinal()**: Música sempre igual
+- **<i class="fas fa-list-alt"></i> FazerChamada(turma)**: Processo padrão
+- **<i class="fas fa-chalkboard"></i> ExplicarMatéria(assunto)**: Estrutura similar
+
+### **Na Tecnologia**
+
+- **<i class="fas fa-save"></i> Salvar()**: Sempre mesmo processo
+- **<i class="fas fa-print"></i> Imprimir(documento)**: Passos padrão
+- **<i class="fas fa-envelope"></i> EnviarEmail(destinatário, mensagem)**: Protocolo fixo
+
+## **Na Programação Visual**
+
+### **Blocos de Função**
+
+No Decoda, você verá:
+
+- **<i class="fas fa-plus"></i> "Criar função"**: Para definir nova função
+- **<i class="fas fa-tag"></i> Nome da função**: Como identificar
+- **<i class="fas fa-cogs"></i> Parâmetros**: "Ingredientes" que recebe
+- **<i class="fas fa-play"></i> Chamar função**: Bloco para usar
+
+### **Exemplo no Jogo Tartaruga**
+
+```
+FUNÇÃO DesenharQuadrado(tamanho):
+    repita 4 vezes:
+        ande tamanho passos
+        vire 90 graus
+
+// Para usar:
+DesenharQuadrado(50)   // Quadrado pequeno
+DesenharQuadrado(100)  // Quadrado grande
+```
+
+## **Vantagens das Funções**
+
+### **1. Reutilização**
+
+- Escreve uma vez, usa muitas vezes
+- Economiza tempo e esforço
+
+### **2. Organização**
+
+- Código mais limpo e claro
+- Cada função faz uma coisa específica
+
+### **3. Facilita Manutenção**
+
+- Erro? Conserta só na função
+- Melhoria? Atualiza só um lugar
+
+### **4. Trabalho em Equipe**
+
+- Cada pessoa pode criar suas funções
+- Compartilha com o grupo
+
+### **5. Menos Erros**
+
+- Testa função uma vez
+- Confia sempre que usar
+
+## **Criando Boas Funções**
+
+### **Nome Descritivo**
+
+- **Bom**: `CalcularIdade()`
+- **Ruim**: `Fazer()`
+
+### **Uma Responsabilidade**
+
+- **Bom**: `EnviarEmail()` só envia email
+- **Ruim**: `EnviarEmailEFazerCafé()` faz duas coisas
+
+### **Tamanho Adequado**
+
+- **Bom**: 5-15 linhas geralmente
+- **Ruim**: 100 linhas (muito complexa)
+
+## **Atividades Práticas com Decoda**
+
+### **1. Biblioteca de Formas**
+
+Crie funções para:
+
+- `DesenharTriângulo(tamanho)`
+- `DesenharCirculo(raio)`
+- `DesenharEstrela(pontas)`
+
+### **2. Efeitos Sonoros**
+
+Crie funções para:
+
+- `SomDeVitória()`: Música alegre
+- `SomDerrota()`: Som triste
+- `SomAção(tipo)`: Diferentes sons
+
+### **3. Comportamentos do Personagem**
+
+Crie funções para:
+
+- `Pular(altura)`: Pulo customizável
+- `Correr(velocidade)`: Corrida variável
+- `Atacar(direção)`: Ataque direcional
+
+## **Dicas para Educadores**
+
+### **Como Ensinar**
+
+1. **<i class="fas fa-repeat"></i> Comece com repetição**: Mostre código repetitivo
+2. **<i class="fas fa-magic"></i> Apresente como solução**: "Vamos organizar isso!"
+3. **<i class="fas fa-hands"></i> Use analogias físicas**: Receitas, instruções
+4. **<i class="fas fa-step-forward"></i> Construa gradualmente**: Simples → Parâmetros → Retorno
+
+### **Erros Comuns**
+
+- **Função muito genérica**: `FazerTudo()`
+- **Nome confuso**: `Coisa1()`, `Função2()`
+- **Muitos parâmetros**: `Função(a,b,c,d,e,f,g)`
+- **Função muito complexa**: Faz muitas coisas diferentes
+
+### **Sinais de Compreensão**
+
+- Identifica código repetitivo
+- Cria nomes descritivos para funções
+- Usa parâmetros apropriadamente
+- Explica por que funções são úteis
+
+## **Pensamento Computacional**
+
+### **Decomposição**
+
+- Quebrar problemas em funções menores
+- Cada função resolve uma parte
+
+### **Abstração**
+
+- Esconder detalhes complexos
+- Usuário só precisa saber o nome da função
+
+### **Reconhecimento de Padrões**
+
+- Identificar ações que se repetem
+- Criar funções para padrões comuns
+
+### **Algoritmos**
+
+- Organizar soluções em blocos reutilizáveis
+- Construir sistemas complexos com peças simples
+
+## **Objetivos de Aprendizagem**
+
+Ao final desta seção, estudantes devem conseguir:
+
+- **<i class="fas fa-check"></i>** Identificar quando usar funções
+- **<i class="fas fa-check"></i>** Criar funções simples com nomes descritivos
+- **<i class="fas fa-check"></i>** Usar parâmetros para tornar funções flexíveis
+- **<i class="fas fa-check"></i>** Organizar código usando funções
+- **<i class="fas fa-check"></i>** Explicar vantagens das funções
+
+## **Atividades de Fixação**
+
+### **1. Identifique a Função**
+
+Que funções você criaria para:
+
+- Fazer um sanduíche
+- Arrumar o quarto
+- Escovar os dentes
+
+### **2. Nomeação**
+
+Dê nomes melhores para:
+
+- `Função1()` que desenha casa
+- `Coisa()` que toca música
+- `Fazer()` que calcula nota
+
+### **3. Parâmetros**
+
+Que parâmetros essas funções precisariam?
+
+- `DesenharRetângulo(?)`
+- `TocarMúsica(?)`
+- `MandarMensagem(?)`
+
+## **Referências e Recursos**
+
+### **Sites Educativos**
+
+- [Code.org - Functions](https://code.org/curriculum/course3/14/Activity14-Functions.pdf) - Atividades com funções
+- [CS Unplugged - Functions](https://csunplugged.org/en/topics/programming-languages/unit-plan/modular-programming/) - Programação modular
+- [Scratch - Custom Blocks](https://scratch.mit.edu/help/studio/tips/custom-blocks/) - Blocos personalizados
+
+### **Vídeos Explicativos**
+
+- [Functions Explained](https://www.youtube.com/watch?v=N_Ls37qeQ4c) - Conceitos básicos
+- [Why Use Functions?](https://www.youtube.com/watch?v=j9Ll8QWwwTE) - Vantagens das funções
+- [Function Parameters](https://www.youtube.com/watch?v=HnC2JhdsJYw) - Parâmetros explicados
+
+### **Jogos e Atividades**
+
+- [CodeCombat](https://codecombat.com/) - RPG que ensina funções
+- [CheckiO](https://checkio.org/) - Desafios de programação
+- [CodinGame](https://www.codingame.com/) - Jogos com funções
+
+### **Literatura Acadêmica**
+
+- Martin, R. (2008). _Clean Code: A Handbook of Agile Software Craftsmanship_
+- McConnell, S. (2004). _Code Complete: A Practical Handbook_
+- Fowler, M. (2018). _Refactoring: Improving the Design of Existing Code_
+
+### **Ferramentas Práticas**
+
+- [Repl.it](https://replit.com/) - Editor online para praticar funções
+- [Trinket](https://trinket.io/) - Python no navegador
+- [JSFiddle](https://jsfiddle.net/) - JavaScript para experimentar
+
+### **Cursos Complementares**
+
+- [Khan Academy - Intro to Programming](https://www.khanacademy.org/computing/intro-to-programming) - Funções básicas
+- [MIT OpenCourseWare](https://ocw.mit.edu/courses/electrical-engineering-and-computer-science/) - Programação avançada
+- [Coursera - Programming for Everybody](https://www.coursera.org/learn/python) - Python com funções
+
+---
+
+**<i class="fas fa-arrow-right"></i> Próximo**: Explore [**Procedural**](./procedural) para aprender como organizar algoritmos passo a passo!

docs/edu/fundamentos-programacao/quatro-fundamentos/loops.md

@@ -0,0 +1,302 @@
+---
+sidebar_position: 2
+title: "Loops (Repetição)"
+---
+
+# Loops - A Arte da Repetição
+
+**Loops** são como receitas que dizem "faça isso várias vezes". É o computador sendo eficiente: em vez de escrever a mesma coisa 100 vezes, ele repete automaticamente!
+
+## **O que são Loops?**
+
+Loops são **estruturas de repetição** que fazem o programa executar as mesmas ações múltiplas vezes, sem precisar reescrever o código.
+
+### **Analogia: Caminhada**
+
+Imagine que você precisa dar 10 passos:
+
+- **SEM LOOP**: Passo 1, Passo 2, Passo 3... (escrever 10 vezes)
+- **COM LOOP**: "Repita 10 vezes: dê um passo"
+
+Muito mais simples, não é?
+
+## **Como Funcionam?**
+
+### **Estrutura Básica**
+
+```
+REPITA X vezes:
+    faça isso
+```
+
+ou
+
+```
+ENQUANTO (condição verdadeira):
+    faça isso
+```
+
+## **Atividades Desplugadas**
+
+### **1. Robô Repetidor**
+
+**Material**: Cartões com comandos
+
+**Como fazer**:
+
+1. Um estudante é o "robô"
+2. Outro é o "programador"
+3. Programador dá comando: "Repita 5 vezes: levante o braço direito"
+4. Robô executa exatamente 5 vezes
+
+### **2. Música em Loop**
+
+**Material**: Uma música conhecida
+
+**Como fazer**:
+
+1. Escolham um refrão simples
+2. "Repita 3 vezes: Parabéns pra você..."
+3. Todos cantam o refrão 3 vezes seguidas
+4. Experimente com números diferentes
+
+### **3. Receita de Biscoitos**
+
+**Material**: Papel e caneta
+
+**Como fazer**:
+
+1. Escreva receita para 1 biscoito
+2. Agora para 12 biscoitos sem loop:
+   - "Misture farinha, misture farinha, misture farinha..." (12 vezes)
+3. Com loop:
+   - "Repita 12 vezes: misture farinha, adicione açúcar, modele"
+
+## **Tipos de Loops**
+
+```mermaid
+flowchart TD
+   A[Preciso repetir uma ação] --> B{Sei quantas vezes?}
+   B -->|Sim| C[Use FOR]
+   B -->|Não| D{Tenho condição de parada?}
+   D -->|Sim| E[Use WHILE]
+   D -->|Não| F[Reveja a lógica para evitar loop infinito]
+   C --> G{É para cada item de lista?}
+   G -->|Sim| H[Use FOR EACH]
+   G -->|Não| I[FOR tradicional]
+```
+
+### **1. Loop com Contador (FOR)**
+
+- Repete um **número específico** de vezes
+- "Faça isso 10 vezes"
+
+**<i class="fas fa-home"></i> Exemplo**: Escovar dentes
+
+- Repita 20 vezes: mova a escova para cima e para baixo
+
+### **2. Loop com Condição (WHILE)**
+
+- Repete **enquanto** algo for verdadeiro
+- "Faça isso enquanto..."
+
+**<i class="fas fa-car"></i> Exemplo**: Dirigir até o destino
+
+- Enquanto não chegou no destino: continue dirigindo
+
+### **3. Loop para Cada Item (FOR EACH)**
+
+- Repete **para cada** elemento de uma lista
+- "Para cada item, faça isso"
+
+**<i class="fas fa-shopping-bag"></i> Exemplo**: Lista de compras
+
+- Para cada item da lista: pegue o produto
+
+## **Loops no Cotidiano**
+
+### **Em Casa**
+
+- **<i class="fas fa-utensils"></i> Lavar louça**: Para cada prato sujo, lave
+- **<i class="fas fa-broom"></i> Varrer casa**: Para cada cômodo, varra
+- **<i class="fas fa-shower"></i> Tomar banho**: Repita até ficar limpo: ensaboe e enxágue
+
+### **Na Escola**
+
+- **<i class="fas fa-pencil-alt"></i> Tabuada**: Repita 10 vezes: 2 x número
+- **<i class="fas fa-book"></i> Leitura**: Para cada página do livro, leia
+- **<i class="fas fa-running"></i> Educação física**: Repita 20 vezes: flexão
+
+### **Na Tecnologia**
+
+- **<i class="fas fa-envelope"></i> Email**: Para cada mensagem nova, notifique
+- **<i class="fas fa-video"></i> Vídeo**: Repita 30 vezes por segundo: mostre frame
+- **<i class="fas fa-gamepad"></i> Jogos**: Enquanto jogo não acabou: continue rodando
+
+## **Na Programação Visual**
+
+### **Blocos de Loop**
+
+No Decoda, você verá:
+
+- **<i class="fas fa-sync"></i> Bloco "Repetir"**: Formato circular ou oval
+- **<i class="fas fa-hashtag"></i> Número**: Quantas vezes repetir
+- **<i class="fas fa-code"></i> Comandos dentro**: O que será repetido
+
+### **Exemplo no Jogo Tartaruga**
+
+1. **Repetir 4 vezes**:
+   - Ande 100 passos
+   - Vire 90 graus à direita
+2. **Resultado**: Desenha um quadrado!
+
+## **Cuidados com Loops**
+
+### **Loop Infinito**
+
+- **Problema**: Loop que nunca para
+- **Exemplo**: "Enquanto 1 = 1: diga olá" (nunca vai parar!)
+- **Solução**: Sempre ter uma condição de parada
+
+### **Loop Muito Lento**
+
+- **Problema**: Muitas repetições desnecessárias
+- **Exemplo**: "Repita 1 milhão de vezes: pisque"
+- **Solução**: Use apenas o número necessário
+
+## **Atividades Práticas com Decoda**
+
+### **1. Desenhar Formas**
+
+- **Triângulo**: Repita 3 vezes (ande, vire 120°)
+- **Quadrado**: Repita 4 vezes (ande, vire 90°)
+- **Estrela**: Repita 5 vezes (ande, vire 144°)
+
+### **2. Mover Personagem**
+
+- **Andar em linha**: Repita 10 vezes (ande 1 passo)
+- **Dança**: Repita 5 vezes (esquerda, direita, pule)
+- **Patrulha**: Enquanto não encontrar inimigo, ande
+
+### **3. Sons e Efeitos**
+
+- **Sirene**: Repita 10 vezes (som agudo, som grave)
+- **Batida**: Repita enquanto música toca (toque tambor)
+- **Eco**: Para cada nota, repita 3 vezes mais baixo
+
+## **Dicas para Educadores**
+
+### **Como Ensinar**
+
+1. **<i class="fas fa-eye"></i> Mostre a ineficiência primeiro**: Escreva sem loop
+2. **<i class="fas fa-magic"></i> Apresente o loop como mágica**: "E se eu disser que há um jeito mais fácil?"
+3. **<i class="fas fa-hands"></i> Use atividades físicas**: Loops corporais
+4. **<i class="fas fa-step-forward"></i> Vá do simples ao complexo**: Comece com números pequenos
+
+### **Erros Comuns**
+
+- **Esquecer a condição de parada**: Criar loops infinitos
+- **Contar errado**: "Repita 5 vezes" mas contar 6
+- **Loop desnecessário**: Usar loop para uma única ação
+- **Condição sempre falsa**: Loop que nunca executa
+
+### **Sinais de Compreensão**
+
+- Identifica repetições no cotidiano
+- Escolhe o tipo certo de loop
+- Prevê quantas vezes algo vai repetir
+- Explica quando usar ou não usar loops
+
+## **Pensamento Computacional**
+
+### **Reconhecimento de Padrões**
+
+- Identificar quando algo se repete
+- Ver semelhanças em diferentes situações
+
+### **Decomposição**
+
+- Quebrar problema grande em pequenas repetições
+- "Como faço uma vez?" → "Como repito muitas vezes?"
+
+### **Abstração**
+
+- Focar no padrão, não nos detalhes
+- "O que se repete é o importante"
+
+### **Algoritmos**
+
+- Criar sequências eficientes
+- Otimizar através da repetição
+
+## **Objetivos de Aprendizagem**
+
+Ao final desta seção, estudantes devem conseguir:
+
+- **<i class="fas fa-check"></i>** Identificar repetições no cotidiano
+- **<i class="fas fa-check"></i>** Escolher o tipo apropriado de loop
+- **<i class="fas fa-check"></i>** Criar loops simples na programação visual
+- **<i class="fas fa-check"></i>** Evitar loops infinitos
+- **<i class="fas fa-check"></i>** Otimizar código usando repetição
+
+## **Atividades de Fixação**
+
+### **1. Identifique o Loop**
+
+Transforme estas ações em loops:
+
+- Subir 10 degraus
+- Ler todas as páginas de um livro
+- Lavar todos os pratos
+
+### **2. Conte as Repetições**
+
+Quantas vezes o loop executará?
+
+- Repita 5 vezes: pule
+- Enquanto bateria > 0: use celular
+- Para cada dedo da mão: conte
+
+### **3. Construa o Loop**
+
+Crie loops para:
+
+- Desenhar escadinha de 6 degraus
+- Tocar "Parabéns" 3 vezes
+- Verificar chuva até parar
+
+## **Referências e Recursos**
+
+### **Sites Educativos**
+
+- [Code.org - Loops](https://code.org/curriculum/course2/5/Activity5-Loops.pdf) - Atividades com loops
+- [CS Unplugged - Algorithms](https://csunplugged.org/en/topics/algorithms/) - Algoritmos sem computador
+- [Scratch - Repetition](https://scratch.mit.edu/ideas) - Ideias para loops
+
+### **Vídeos Explicativos**
+
+- [Loops Explained](https://www.youtube.com/watch?v=mgooqyWMTxk) - Explicação visual
+- [Repetition in Programming](https://www.youtube.com/watch?v=wxds6MAtUQ0) - Code.org
+- [For Loops vs While Loops](https://www.youtube.com/watch?v=94UHCEmprCY) - Diferenças
+
+### **Jogos e Atividades**
+
+- [Cargo Bot](http://twolivesleft.com/CargoBot/) - Programa robô com loops
+- [Human Resource Machine](https://tomorrowcorporation.com/humanresourcemachine) - Puzzles com loops
+- [While True: Learn()](https://luden.io/wtl/) - Machine learning com loops
+
+### **Literatura Acadêmica**
+
+- Weintrop, D. (2016). _Defining Computational Thinking for Mathematics and Science_
+- Yadav, A. (2014). _Computational Thinking in Elementary and Secondary Education_
+- Grover, S. (2013). _Learning to Code, Coding to Learn_
+
+### **Ferramentas Complementares**
+
+- [Logo Programming](http://www.logointerpreter.com/) - Desenhos com loops
+- [Alice](http://www.alice.org/) - Programação 3D com repetição
+- [Greenfoot](https://www.greenfoot.org/) - Java visual com loops
+
+---
+
+**<i class="fas fa-arrow-right"></i> Próximo**: Descubra [**Funções**](./funcoes) para organizar e reutilizar seu código!

docs/edu/fundamentos-programacao/quatro-fundamentos/procedural.md

@@ -0,0 +1,478 @@
+---
+sidebar_position: 4
+title: "Procedural"
+---
+
+# Procedural - Algoritmos Organizados
+
+**Procedural** é como organizar uma empresa: cada departamento (procedimento) tem sua função específica, mas todos trabalham juntos para atingir um objetivo maior!
+
+**Esta é a essência dos ALGORITMOS** - sequências de passos organizados que resolvem problemas!
+
+## **O que é Procedural?**
+
+É organizar **algoritmos** (sequências de passos) em **procedimentos** que executam tarefas específicas, seguindo uma sequência lógica de **cima para baixo**.
+
+### **Algoritmo = Receita Detalhada**
+
+Um **algoritmo** é como uma receita muito específica:
+
+- **Cada passo é claro** (sem ambiguidade)
+- **Ordem importa** (passo 2 vem depois do passo 1)
+- **Sempre termina** (tem um fim)
+- **Resolve o problema** (chega no resultado esperado)
+
+### **Analogia: Construindo uma Casa**
+
+```
+PROJETO: Construir Casa
+
+PROCEDIMENTO PrepararTerreno():
+    - Limpar área
+    - Nivelar solo
+    - Marcar fundação
+
+PROCEDIMENTO FazerFundação():
+    - Cavar buracos
+    - Colocar ferro
+    - Despejar concreto
+
+PROCEDIMENTO ConstruirParedes():
+    - Assentar tijolos
+    - Fazer argamassa
+    - Levantar estrutura
+
+PROGRAMA PRINCIPAL:
+    1. PrepararTerreno()
+    2. FazerFundação()
+    3. ConstruirParedes()
+    4. ColocarTelhado()
+    5. FazerAcabamento()
+```
+
+Cada **procedimento** faz uma parte, mas todos seguem uma **ordem lógica**!
+
+## **Algoritmos - A Base de Tudo**
+
+### **Exemplo de Algoritmo Simples**
+
+```
+ALGORITMO: Fazer Sanduíche
+1. Pegue 2 fatias de pão
+2. Passe manteiga numa fatia
+3. Adicione presunto
+4. Adicione queijo
+5. Feche com a outra fatia
+6. Corte na diagonal
+RESULTADO: Sanduíche pronto!
+```
+
+### **Características de um Bom Algoritmo**
+
+- **<i class="fas fa-eye"></i> Clareza**: Cada passo é compreensível
+- **<i class="fas fa-list-ol"></i> Ordem lógica**: Sequência faz sentido
+- **<i class="fas fa-flag-checkered"></i> Finitude**: Sempre termina
+- **<i class="fas fa-bullseye"></i> Eficácia**: Resolve o problema
+- **<i class="fas fa-tachometer-alt"></i> Eficiência**: Usa poucos passos
+
+## **Características do Paradigma Procedural**
+
+### **1. Fluxo Top-Down (De Cima para Baixo)**
+
+```mermaid
+flowchart TD
+    A[Problema principal] --> B[Dividir em subproblemas]
+    B --> C[Transformar em procedimentos]
+    C --> D[Organizar ordem de execução]
+    D --> E[Executar programa principal]
+```
+
+- Começamos com o **problema principal**
+- Dividimos em **subproblemas menores**
+- Cada subproblema vira um **procedimento**
+
+### **2. Modularidade**
+
+- Código dividido em **módulos/procedimentos**
+- Cada módulo tem **responsabilidade específica**
+- Fácil de entender e manter
+
+### **3. Reutilização**
+
+- Procedimentos podem ser **chamados várias vezes**
+- Evita repetição de código
+- Economiza trabalho
+
+### **4. Sequencialidade**
+
+- Execução **passo a passo**
+- Uma instrução por vez
+- Ordem importa!
+
+## **Atividades Desplugadas**
+
+### **1. Festa de Aniversário**
+
+**Material**: Lista de tarefas, cartões
+
+**Como fazer**:
+
+1. **Problema**: Organizar festa de aniversário
+2. **Dividir em procedimentos**:
+   - `ComprarIngredientes()`
+   - `DecorarSala()`
+   - `PrepararComida()`
+   - `ChamarConvidados()`
+3. **Executar na ordem**: Cada equipe fica responsável por um procedimento
+
+### **2. Peça de Teatro**
+
+**Material**: Roteiro simples
+
+**Como fazer**:
+
+1. **Problema**: Apresentar peça
+2. **Procedimentos**:
+   - `PrepararCenário()`
+   - `AquecerVoz()`
+   - `AtuarCena1()`
+   - `AtuarCena2()`
+   - `Agradecer()`
+3. **Executar sequencialmente**: Cada procedimento tem seus atores
+
+### **3. Viagem Escolar**
+
+**Material**: Mapa, lista de atividades
+
+**Como fazer**:
+
+1. **Problema**: Organizar viagem
+2. **Procedimentos**:
+   - `PlanejarRota()`
+   - `FazerLanche()`
+   - `SubirOnibus()`
+   - `VisitarLocal()`
+   - `VoltarEscola()`
+
+### **4. Encontrar Objeto Perdido (Algoritmo de Busca)**
+
+**Material**: Objetos escondidos na sala
+
+**Como fazer**:
+
+1. **Algoritmo Linear**: Procure um por um, da esquerda para direita
+2. **Algoritmo Inteligente**: Divida a sala em metades, elimine metade onde não está
+3. **Compare eficiência**: Qual foi mais rápido?
+
+### **5. Organizar Fila por Altura (Algoritmo de Ordenação)**
+
+**Material**: Estudantes
+
+**Como fazer**:
+
+1. **Algoritmo Bolha**: Compare pares vizinhos, troque se necessário
+2. **Algoritmo Seleção**: Encontre o menor, coloque no início
+3. **Teste qual é mais eficiente** com turmas diferentes
+
+## **Diferenças de Outros Paradigmas**
+
+### **Procedural vs Orientado a Objetos**
+
+```mermaid
+flowchart TD
+    A[Paradigmas de Programação] --> B[Procedural]
+    A --> C[Orientado a Objetos]
+    B --> B1[Foco em ações e sequência]
+    B --> B2[Dados e procedimentos separados]
+    C --> C1[Foco em entidades e comportamento]
+    C --> C2[Dados e métodos agrupados]
+```
+
+**<i class="fas fa-cogs"></i> Procedural**:
+
+- Foco nas **ações/procedimentos**
+- "O que o programa **faz**?"
+- Dados e procedimentos **separados**
+
+**<i class="fas fa-cube"></i> Orientado a Objetos**:
+
+- Foco nos **objetos/entidades**
+- "O que o programa **representa**?"
+- Dados e métodos **juntos**
+
+### **Exemplo Comparativo**
+
+**<i class="fas fa-list-ol"></i> Procedural - Controlar Carro**:
+
+```
+PROCEDIMENTO Ligar()
+PROCEDIMENTO Acelerar()
+PROCEDIMENTO Frear()
+PROCEDIMENTO Desligar()
+
+PROGRAMA:
+    Ligar()
+    Acelerar()
+    Frear()
+    Desligar()
+```
+
+**<i class="fas fa-cube"></i> Orientado a Objetos - Carro**:
+
+```
+OBJETO Carro:
+    - propriedades: velocidade, combustível
+    - métodos: ligar(), acelerar(), frear()
+
+PROGRAMA:
+    meuCarro = novo Carro()
+    meuCarro.ligar()
+    meuCarro.acelerar()
+```
+
+## **Na Programação Visual (Decoda)**
+
+### **Estrutura Procedural**
+
+No Decoda, seguimos naturalmente o paradigma procedural:
+
+```
+PROCEDIMENTO IniciarJogo():
+    - Criar personagem
+    - Definir cenário
+    - Tocar música
+
+PROCEDIMENTO ProcessarJogada():
+    - Ler entrada do jogador
+    - Mover personagem
+    - Verificar colisões
+
+PROCEDIMENTO FinalizarJogo():
+    - Mostrar pontuação
+    - Salvar recorde
+    - Perguntar se quer jogar novamente
+
+PROGRAMA PRINCIPAL:
+    IniciarJogo()
+    ENQUANTO jogo não acabou:
+        ProcessarJogada()
+    FinalizarJogo()
+```
+
+### **Exemplo: Jogo do Semáforo**
+
+```
+PROCEDIMENTO ConfigurarSemáforo():
+    - Desenhar semáforo na tela
+    - Definir posição inicial
+    - Preparar sons
+
+PROCEDIMENTO MudarCor(nova_cor):
+    - Apagar cor anterior
+    - Acender nova cor
+    - Tocar som correspondente
+
+PROCEDIMENTO VerificarEntrada():
+    - SE botão pressionado
+    - ENTÃO próxima cor
+
+PROGRAMA PRINCIPAL:
+    ConfigurarSemáforo()
+    REPETIR para sempre:
+        VerificarEntrada()
+        ESPERAR 1 segundo
+```
+
+## **Vantagens da Programação Procedural**
+
+### **1. Fácil de Aprender**
+
+- **Intuitivo**: Pense no problema, divida em partes
+- **Natural**: Como resolvemos problemas no dia a dia
+- **Sequencial**: Uma coisa por vez
+
+### **2. Fácil de Debugar**
+
+- **Isolamento**: Erro em um procedimento não afeta outros
+- **Rastreabilidade**: Fácil encontrar onde está o problema
+- **Testing**: Teste cada procedimento separadamente
+
+### **3. Trabalho em Equipe**
+
+- **Divisão de tarefas**: Cada pessoa pode fazer um procedimento
+- **Integração**: Juntar depois é mais fácil
+- **Paralelismo**: Várias pessoas trabalhando simultaneamente
+
+### **4. Legibilidade**
+
+- **Código limpo**: Cada procedimento tem propósito claro
+- **Manutenção**: Fácil entender e modificar
+- **Documentação**: Nome do procedimento explica o que faz
+
+## **Limitações e Cuidados**
+
+### **1. Dependências Entre Procedimentos**
+
+- **Problema**: Um procedimento depende de outro
+- **Solução**: Planejar bem a ordem de execução
+
+### **2. Compartilhamento de Dados**
+
+- **Problema**: Vários procedimentos precisam dos mesmos dados
+- **Solução**: Usar parâmetros ou variáveis globais com cuidado
+
+### **3. Crescimento do Projeto**
+
+- **Problema**: Projetos muito grandes ficam complexos
+- **Solução**: Dividir em módulos menores e independentes
+
+## **Ensinando Programação Procedural**
+
+### **Estratégias Pedagógicas**
+
+1. **<i class="fas fa-home"></i> Comece com exemplos reais**: Rotina diária, receitas
+2. **<i class="fas fa-puzzle-piece"></i> Divida problemas grandes**: Mostre como quebrar
+3. **<i class="fas fa-hands"></i> Use atividades físicas**: Representem procedimentos
+4. **<i class="fas fa-step-forward"></i> Construa gradualmente**: Simples → Complexo
+
+### **Observações nos Estudantes**
+
+**<i class="fas fa-check"></i> Sinais de Compreensão**:
+
+- Dividem problemas em partes menores naturalmente
+- Criam nomes descritivos para procedimentos
+- Entendem a importância da ordem de execução
+- Reutilizam procedimentos quando apropriado
+
+**<i class="fas fa-exclamation-triangle"></i> Dificuldades Comuns**:
+
+- Criar procedimentos muito grandes
+- Não conseguir dividir o problema
+- Confundir ordem de execução
+- Repetir código em vez de criar procedimentos
+
+## **Procedural no Cotidiano**
+
+### **Cozinha**
+
+```
+PROCEDIMENTO PrepararIngredientes()
+PROCEDIMENTO CozinharPrato()
+PROCEDIMENTO EmpratarComida()
+PROCEDIMENTO LimparCozinha()
+```
+
+### **Aula**
+
+```
+PROCEDIMENTO PrepararMaterial()
+PROCEDIMENTO ExplicarConteúdo()
+PROCEDIMENTO FazerAtividade()
+PROCEDIMENTO CorrigirExercícios()
+```
+
+### **Dirigir**
+
+```
+PROCEDIMENTO VerificarCarroSeguro()
+PROCEDIMENTO LigarCarro()
+PROCEDIMENTO ColocarCinto()
+PROCEDIMENTO DirigirDestino()
+```
+
+## **Pensamento Computacional**
+
+### **Decomposição**
+
+- **Fundamental**: Quebrar problemas em subproblemas
+- **Cada subproblema** → vira um procedimento
+- **Hierarquia**: Procedimentos podem chamar outros procedimentos
+
+### **Abstração**
+
+- **Esconder complexidade**: Usuário não precisa saber como funciona internamente
+- **Interface clara**: Nome e parâmetros explicam o que faz
+- **Reutilização**: Mesmo procedimento, diferentes contextos
+
+### **Algoritmos**
+
+- **Cada procedimento é um algoritmo**: Sequência de passos específica
+- **Algoritmo principal**: Chama outros algoritmos na ordem certa
+- **Otimização**: Melhorar um procedimento melhora todo o programa
+
+## **Objetivos de Aprendizagem**
+
+Ao final desta seção, estudantes devem conseguir:
+
+- **<i class="fas fa-check"></i>** Dividir problemas complexos em procedimentos menores
+- **<i class="fas fa-check"></i>** Criar procedimentos com nomes descritivos e responsabilidades claras
+- **<i class="fas fa-check"></i>** Organizar procedimentos em sequência lógica
+- **<i class="fas fa-check"></i>** Reutilizar procedimentos quando apropriado
+- **<i class="fas fa-check"></i>** Identificar quando usar programação procedural vs outros paradigmas
+
+## **Atividades de Fixação**
+
+### **1. Decomposição**
+
+Divida estes problemas em procedimentos:
+
+- Organizar festa na escola
+- Fazer uma apresentação
+- Limpar a casa
+
+### **2. Pseudocódigo Procedural**
+
+Escreva pseudocódigo para:
+
+- Sistema de biblioteca escolar
+- Jogo de adivinhação
+- Calculadora simples
+
+### **3. Otimização**
+
+- Identifique código repetitivo neste programa
+- Crie procedimentos para eliminar repetição
+- Organize em estrutura procedural
+
+## **Referências e Recursos**
+
+### **Sites Educativos**
+
+- [Structured Programming](https://www.tutorialspoint.com/structured-programming) - Conceitos básicos
+- [Khan Academy - Functions](https://www.khanacademy.org/computing/computer-programming/programming/functions/a/intro-to-functions) - Funções e procedimentos
+- [CS50 - Functions](https://cs50.harvard.edu/x/2024/weeks/1/) - Harvard CS50
+
+### **Vídeos Explicativos**
+
+- [Procedural Programming Explained](https://www.youtube.com/watch?v=xLVCqJdSO60) - Conceitos fundamentais
+- [Top-Down Design](https://www.youtube.com/watch?v=q86G4Gf_CVE) - Design de cima para baixo
+- [Modular Programming](https://www.youtube.com/watch?v=b2pO3ip0S3A) - Programação modular
+
+### **Literatura Clássica**
+
+- Dijkstra, E. (1972). _Structured Programming_. Academic Press
+- Wirth, N. (1976). _Algorithms + Data Structures = Programs_. Prentice Hall
+- Yourdon, E. (1979). _Structured Design_. Prentice Hall
+
+### **Ferramentas de Ensino**
+
+- [Pseudocode Generator](https://www.pseudocode.io/) - Gerar pseudocódigo
+- [Flowchart Maker](https://app.diagrams.net/) - Criar fluxogramas
+- [Alice](http://www.alice.org/) - Programação 3D procedural
+
+### **Exemplos Práticos**
+
+- [Scratch](https://scratch.mit.edu/) - Programação visual procedural
+- [Logo](http://www.calormen.com/jslogo/) - Linguagem procedural clássica
+- [Processing](https://processing.org/) - Arte generativa procedural
+
+---
+
+**<i class="fas fa-graduation-cap"></i> Parabéns!** Você completou os **4 Fundamentos da Programação**:
+
+1. **<i class="fas fa-question"></i> Condicionais** - Decisões inteligentes
+2. **<i class="fas fa-sync"></i> Loops** - Repetição eficiente
+3. **<i class="fas fa-box"></i> Funções** - Organização e reutilização
+4. **<i class="fas fa-list-ol"></i> Procedural** - Algoritmos estruturados
+
+Agora está pronto para aplicar esses conceitos em projetos reais com **Decoda**!

docs/edu/guias-pedagogicos/_category_.json

@@ -0,0 +1,12 @@
+{
+  "position": 3,
+  "label": "Guias Pedagógicos",
+  "collapsible": true,
+  "collapsed": true,
+  "className": "red",
+  "link": {
+    "type": "generated-index",
+    "title": "Guias Pedagógicos",
+    "description": "Guias Pedagógicos para educadores sobre metodologias e práticas de ensino com programação"
+  }
+}

docs/edu/guias-pedagogicos/avaliacao-aprendizado.md

@@ -0,0 +1,65 @@
+---
+sidebar_position: 4
+title: "Acompanhamento e Situações Comuns"
+---
+
+# Acompanhamento e Situações Comuns
+
+Acompanhar o aprendizado em uma aula de programação ou letramento digital não exige testes ou provas. O que mais revela sobre o progresso de cada estudante é o que acontece durante a prática — as perguntas que fazem, as estratégias que tentam, como reagem ao erro e como interagem com os colegas.
+
+## O que observar em cada trilha
+
+Na trilha de **letramento digital**, o progresso mais importante não é completar todas as atividades - **é a transformação da relação da pessoa com o equipamento**. Quem chegou com medo de "quebrar o computador" e começa a clicar com confiança, quem para de olhar para as mãos e passa a olhar para a tela, quem experimenta sem precisar de permissão explícita — esses são sinais concretos de desenvolvimento. Observe também se o estudante consegue retomar de onde parou sem precisar de instrução e se já consegue ajudar um colega em dificuldade.
+
+Na trilha de **programação**, observe se o estudante consegue articular o que está tentando fazer antes de executar — isso indica que o raciocínio lógico está se desenvolvendo. Preste atenção também em como reage ao erro: quem relê o código procurando onde está o problema está em um estágio diferente de quem simplesmente apaga tudo e começa do zero. Com o tempo, a qualidade das perguntas muda — de "o que eu faço?" para "por que isso acontece?" — e essa mudança é um dos indicadores mais relevantes de evolução.
+
+```mermaid
+flowchart TD
+	A[Observação em aula] --> B{Trilha}
+	B -->|Letramento| C[Autonomia e confiança]
+	B -->|Programação| D[Raciocínio lógico e depuração]
+	C --> E[Registro curto por estudante]
+	D --> E
+	E --> F[Próxima intervenção pedagógica]
+```
+
+## Como registrar sem burocratizar
+
+Um registro simples e consistente vale mais do que uma ficha complexa preenchida às pressas. Uma anotação breve ao final de cada aula — o nome do estudante, o que foi feito, uma observação relevante — é suficiente para acompanhar a evolução ao longo do tempo.
+
+Não é necessário registrar todo mundo todo dia. Foque em quem apresentou algo diferente: uma dificuldade que não estava aparecendo antes, um avanço inesperado, um comportamento que merece atenção. Ao longo de algumas semanas, essas anotações pontuais formam um retrato mais honesto do que qualquer nota numérica.
+
+Se a turma é grande, uma alternativa é reservar a pergunta "o que você aprendeu hoje?" para o encerramento da aula. As respostas espontâneas dos estudantes já revelam muito sobre onde cada um está.
+
+## Autoavaliação e troca entre estudantes
+
+Perguntar para o estudante o que ele mesmo acha que aprendeu não é uma formalidade — é uma das formas mais diretas de desenvolver consciência sobre o próprio processo. Perguntas simples como "o que ficou fácil?", "o que você ainda acha difícil?" e "o que você faria diferente?" podem ser feitas oralmente, sem precisar de formulário.
+
+Reservar alguns minutos no final da aula para que grupos compartilhem o que descobriram também tem valor pedagógico: quem explica para o colega consolida o próprio aprendizado, e quem ouve muitas vezes entende algo que não havia ficado claro na prática individual. Não é necessário que todos apresentem toda semana — uma ou duas duplas por aula já é suficiente para criar essa cultura.
+
+## Situações frequentes
+
+Quando surgir um problema recorrente, esta árvore ajuda a decidir o próximo passo com rapidez:
+
+```mermaid
+flowchart TD
+	A[Problema em aula] --> B{Tipo principal}
+	B -->|Técnico| C[Aplicar contingência: grupos maiores e síntese oral]
+	B -->|Ritmo desigual| D[Tutoria entre pares + trilha de desafio]
+	B -->|Resistência| E[Escuta ativa + evidências concretas de aprendizagem]
+	B -->|Conflito de grupo| F[Rodízio do mouse + conversa mediada]
+	C --> G[Registrar e acionar gestão se recorrente]
+	D --> G
+	E --> G
+	F --> G
+```
+
+**Ritmos muito diferentes na mesma turma.** É normal que alguns terminem as atividades em poucos minutos e outros precisem de toda a aula para o mesmo conteúdo. Para quem termina rápido, as atividades de programação oferecem níveis mais avançados — mas também é válido pedir que ajudem quem ainda está tentando. Ensinar consolida o aprendizado de quem já sabe, e aprende-se com mais facilidade de um colega do que de um adulto. Para quem está mais lento, a pressão de "todo mundo já terminou" pode ser mais prejudicial do que qualquer dificuldade técnica — vale criar um ambiente em que terminar não seja o objetivo principal.
+
+**Bloqueio emocional com a tecnologia.** Alguns estudantes — especialmente na trilha de letramento — chegam com a crença de que "não têm jeito para isso". Não adianta contrariar diretamente. O mais eficaz é criar situações em que o sucesso seja inevitável nos primeiros minutos: atividades muito simples, um passo de cada vez, com reconhecimento explícito de cada pequeno avanço. A confiança vem da experiência acumulada, não do encorajamento verbal.
+
+**Resistência à metodologia.** Se um estudante ou responsável questiona o valor das atividades, a resposta mais honesta é concreta: quais habilidades estão sendo trabalhadas, como elas se conectam com o currículo e quais são os resultados observados. Mostrar registros reais de evolução de turmas anteriores costuma ser mais convincente do que qualquer explicação teórica.
+
+**Conflitos dentro dos grupos.** Em trabalhos em dupla, é comum que um dos dois assuma o controle e o outro se desengaje. Quando isso acontece, a solução imediata é o rodízio do mouse — quem estava operando vai observar, e vice-versa. Se o conflito for mais sério, parar a atividade e conversar diretamente com os envolvidos resolve mais rápido do que ignorar e torcer para passar.
+
+**Problemas técnicos recorrentes.** Se um computador trava com frequência, se o navegador não carrega as atividades de letramento ou se a conexão é instável, vale reportar para a gestão do local antes que vire rotina. Uma aula planejada para um equipamento que não funciona é frustrante para todo mundo. Se a limitação for estrutural — poucos computadores, sem internet —, trabalhar em grupos maiores e reservar mais tempo para discussão e síntese coletiva é uma adaptação real, não um improviso, e ai atividades desplugadas podem ser uma ferramenta importante para ser usada nestes momentos.

docs/edu/guias-pedagogicos/preparando-aula.md

@@ -0,0 +1,96 @@
+---
+sidebar_position: 3
+title: "Planejando e Conduzindo a Aula"
+---
+
+# Planejando e Conduzindo a Aula
+
+Ensinar com a plataforma não exige que você seja especialista em programação — exige que você conheça bem quem está na sua frente. Este artigo reúne o que é necessário saber para planejar uma aula, escolher as atividades adequadas e conduzi-la de forma que todos consigam participar.
+
+## Conhecendo sua turma
+
+A plataforma oferece duas trilhas com perfis de público bem distintos. A trilha de **letramento digital** é voltada para pessoas com pouca ou nenhuma familiaridade com computadores — alguém que nunca usou mouse, que hesita em tocar no teclado, que não sabe o que é um duplo clique. A trilha de **programação** é voltada para quem já tem conforto básico com o equipamento e está pronto para aprender lógica, sequências e condições por meio de atividades interativas.
+
+Antes de começar, vale conversar com a turma: quem já usa computador em casa? Quem tem smartphone mas nunca usou mouse? Quem já tentou alguma vez escrever um código? Essas respostas determinam por onde começar — e são mais úteis do que qualquer ficha de cadastro.
+
+Além do nível de familiaridade tecnológica, considere o contexto da turma: faixa etária, se há estudantes com dificuldades de leitura, se o espaço tem equipamentos suficientes para todos ou se será necessário trabalhar em duplas ou trios.
+
+Para facilitar a escolha da trilha inicial, o fluxo abaixo resume uma decisão prática:
+
+```mermaid
+flowchart TD
+	A[Início da turma] --> B{Usa mouse e teclado com autonomia?}
+	B -->|Não| C[Letramento digital]
+	B -->|Sim| D{Consegue seguir sequência lógica simples?}
+	D -->|Não| C
+	D -->|Sim| E[Programação básica]
+	C --> F[Começar por mouse-basico]
+	E --> G[Começar por aspirador ou semaforo]
+```
+
+## Escolhendo as atividades certas
+
+Para turmas de letramento, as atividades seguem uma progressão — do básico do mouse ao desafio completo — e respeitar essa ordem importa. A sequência começa com mover e clicar, passa por precisão, controle do cursor, múltiplos cliques, sequências numéricas, velocidade, botão direito, arrastar e termina em um desafio que combina todas as habilidades adquiridas. Pular etapas cria frustração, especialmente com quem está tendo o primeiro contato com um periférico.
+
+Para turmas de programação, as atividades são independentes entre si, mas têm complexidades diferentes. O **Quebra-cabeças** e o **Semáforo** são bons pontos de entrada — trabalham com sequências e condições simples, acessíveis mesmo para quem não tem experiência prévia. O **Aspirador** e o **Autômato** exigem um raciocínio lógico um pouco mais elaborado. A **Tartaruga** e a **Toupeira** introduzem variáveis e aleatoriedade. A **Cripto** trabalha criptografia e repetição com texto. A **Ordenação** é a mais avançada, com algoritmos clássicos de ordenação e análise de eficiência, adequada para turmas que já dominam laços, variáveis e condicionais.
+
+Um modo simples de visualizar a progressão das escolhas é este:
+
+#### Letramento Digital 
+
+```mermaid
+flowchart LR
+	L1[1. Mouse] --> L2[2. Teclado]
+```
+
+#### Programação 
+```mermaid
+flowchart LR
+	P1[1. Quebra-cabeças/Semáforo] --> P2[2. Aspirador/Autômato]
+	P2 --> P3[3. Tartaruga/Toupeira]
+	P3 --> P4[4. Cripto]
+	P4 --> P5[5. Ordenação]
+```
+
+Uma boa aula raramente cobre mais de uma atividade inteira. O tempo de exploração, as dúvidas que surgem e as conversas em torno do que acontece na tela valem tanto quanto completar os desafios.
+
+## Estruturando o tempo
+
+Uma aula de 50 minutos funciona bem com uma divisão aproximada. Os primeiros minutos são de acolhimento e resgate do que foi feito anteriormente — não precisa ser mais do que uma conversa curta. Em seguida, vem a apresentação do que vai ser feito: contextualize por que aquela atividade faz sentido, o que ela vai ensinar, e levante expectativas ou dúvidas iniciais da turma. A maior parte do tempo vai para a prática, com os estudantes explorando a atividade em duplas ou individualmente. Nos últimos minutos, vale reunir a turma para socializar o que cada um descobriu, quais estratégias funcionaram e o que ficou como dúvida.
+
+```mermaid
+flowchart TD
+	A[**Acolhimento**
+8-10 min] --> B[**Contextualização**
+10-12 min]
+	B --> C[**Prática guiada**
+20-25 min]
+	C --> D[**Síntese coletiva**
+5-8 min]
+```
+
+Essa estrutura é flexível. Se uma atividade gera muita discussão, deixe a discussão acontecer. Se a turma está engajada e o tempo passou, não force uma síntese artificial só para encerrar a aula.
+
+## Conduzindo as atividades
+
+Durante a prática, o papel do educador é circular, observar e fazer perguntas — não resolver. Quando um estudante trava em um passo, a primeira resposta útil é "o que você tentou até agora?" e não mostrar imediatamente a solução. Isso vale especialmente na trilha de letramento: uma pessoa que acabou de aprender a clicar sente um orgulho real em descobrir sozinha que o duplo clique abre uma pasta.
+
+Para a trilha de programação, perguntas como "por que você escolheu essa sequência?" ou "o que aconteceria se você mudasse essa parte?" estimulam mais do que respostas prontas. O erro é parte do processo — e é no erro que os conceitos mais importantes costumam aparecer.
+
+Evite demonstrações longas no início da aula. Mostre o mínimo necessário para que os estudantes possam começar e deixe a exploração revelar o restante.
+
+## Organização do espaço e dos grupos
+
+Quando há menos computadores do que estudantes, trabalhar em duplas é a melhor opção — e não é uma solução de compromisso. Dois estudantes na mesma máquina conversam sobre o que fazer, se explicam mutuamente e aprendem mais do que aprenderiam sozinhos. O desafio é garantir que os dois participem de verdade: combinar rodízio de quem está no mouse a cada etapa evita que um dos dois assuma o controle por toda a aula.
+
+Para trios, vale definir papéis rotativos: quem opera o equipamento, quem observa e sugere, quem anota o que foi descoberto. Esses papéis podem trocar a cada etapa ou a cada aula. O posicionamento no espaço também importa: uma disposição em que todos consigam se ver facilita a síntese coletiva no final.
+
+## Quando algo não sai como planejado
+
+Problemas técnicos acontecem — a internet cai, um computador trava, um navegador não carrega a atividade. **A melhor preparação é ter testado as atividades antes da aula e, se possível, saber quais funcionam com conexão instável**.
+
+Se a internet cair durante a aula, aproveite para uma discussão sobre o que a turma estava fazendo: "qual era a lógica que vocês estavam tentando montar?" ou "o que vocês acharam difícil até agora?" são perguntas que continuam a aula sem depender da tela.
+
+Se o nível da turma for muito heterogêneo, deixe os que terminaram mais rápido ajudarem os colegas — ou explore a atividade em um nível mais avançado enquanto outros completam o básico. As atividades de programação têm níveis diferentes, o que permite que ritmos distintos coexistam na mesma aula.
+
+Se aparecer resistência — "isso não é aula de verdade", "não entendo para que serve" — vale escutar antes de responder. Às vezes a resistência vem de insegurança com a tecnologia, e uma conversa individual resolve mais do que qualquer argumento coletivo.

docs/edu/intro.md

@@ -0,0 +1,107 @@
+---
+sidebar_position: 1
+title: "Guia do Educador"
+---
+
+Bem-vindo ao **Decoda**, uma plataforma educacional de programação visual desenvolvida especialmente para o ensino de lógica de programação!
+
+## **O que é o Decoda?**
+
+O **Decoda** é uma plataforma educacional que integra atividades práticas para o ensino de **programação** e **letramento digital** de forma acessível e progressiva. Combina exercícios com *Blockly* - programação visual baseada em blocos - com cursos em *Python* usando *JupyterLite*, além de módulos de *Letramento Digital* que familiarizam estudantes com o uso seguro e eficiente do computador. O objetivo é reduzir a barreira da sintaxe e priorizar o desenvolvimento do **raciocínio lógico** e do **pensamento computacional**.
+
+Nas atividades com *Blockly*, os alunos constroem algoritmos arrastando e encaixando blocos, explorando conceitos como sequências, condições, loops e variáveis por meio de desafios e jogos interativos que oferecem feedback imediato. Essa abordagem incentiva experimentação, depuração guiada e criatividade, tornando abstratos conceitos de programação em tarefas concretas e motivadoras.
+
+O suporte a *Python* via *JupyterLite* permite uma transição suave do visual para o textual, com exercícios práticos executáveis direto no navegador, sem instalação. Paralelamente, os módulos de Letramento Digital desenvolvem competências básicas de uso do computador, navegação e cidadania digital, preparando os alunos para aplicar habilidades de programação em contextos reais e escolares.
+
+
+## **Para Educadores**
+
+Esta documentação é destinada a **qualquer pessoa que deseje ensinar programação**, não apenas professores formais. Seja você um profissional de tecnologia sem experiência em sala de aula, seja um educador de outras áreas sem familiaridade com programação, o **Decoda** oferece suporte prático para transformar conhecimento em atividade pedagógica.
+
+Se você é um **profissional de tecnologia** que nunca deu aulas, o **Decoda** auxilia com orientações pedagógicas, sequências de atividades, planos de aula e recursos práticos (exercícios em *Blockly*, transição para *Python* via *JupyterLite*, avaliações e dicas de mediação) para que o ensino seja estruturado e eficaz desde o primeiro encontro com os alunos.
+
+Se você é um **educador sem conhecimento em programação**, a documentação apresenta de forma clara os conceitos essenciais da lógica de programação, exemplos passo a passo e módulos de Letramento Digital que cobrem o uso seguro e eficiente do computador, permitindo uma transição gradual do visual para o textual e oferecendo apoio nos primeiros passos da implementação em sala.
+
+## **Recursos de ensino do Decoda**
+
+O **Decoda** organiza o ensino em dois grandes recursos: **Atividades** e **Laboratórios**. Essa divisão permite adaptar o uso da plataforma ao perfil da turma, ao tempo disponível e aos objetivos de aprendizagem de cada aula.
+
+As **Atividades** foram pensadas para estudantes e podem ser aplicadas com mediação do educador ou com maior autonomia, conforme o contexto. Em muitos casos, parte da intencionalidade pedagógica não aparece de forma explícita na interface, justamente para que o educador conduza discussões, proponha perguntas e explore os conceitos de programação de forma contextualizada. A trilha de **Letramento Digital** também faz parte desse recurso e tem como objetivo reduzir o medo da máquina, desenvolver confiança e ensinar interações básicas, como uso de mouse, teclado e navegação.
+
+Os **Laboratórios** são ambientes mais abertos e elaborados. No laboratório de **Blocos**, educadores com mais experiência podem propor desafios além dos exemplos prontos, trabalhando algoritmos de forma criativa e progressiva. No laboratório de **Python**, a proposta é apoiar a transição de blocos para código textual por meio do curso em **JupyterLite**, mantendo a prática em um ambiente acessível no navegador.
+
+## **Benefícios Pedagógicos**
+
+O uso do **Decoda** em sala vai além do aprendizado técnico de programação. A plataforma foi desenvolvida para estimular habilidades cognitivas e sociais que são fundamentais nos dias atuais, independentemente de o estudante seguir ou não uma carreira em tecnologia. Ao resolver problemas com blocos, depurar erros, adaptar estratégias e colaborar com colegas, os estudantes desenvolvem uma forma de pensar mais estruturada, criativa e crítica.
+
+### **Desenvolvimento Cognitivo**
+
+A programação visual com blocos exige que o estudante decomponha problemas complexos em etapas menores, identifique padrões e construa abstrações — habilidades centrais do **pensamento computacional**. O ciclo de tentar, errar e ajustar desenvolve a **resolução de problemas** de forma sistemática. E a liberdade de criar diferentes soluções para o mesmo desafio estimula a **criatividade** como parte natural do processo.
+
+- **Pensamento Computacional**: Decomposição, padrões, abstração
+- **Resolução de Problemas**: Estratégias sistemáticas e iterativas
+- **Criatividade**: Expressão através da programação
+
+### **Habilidades Desenvolvidas**
+
+Nas aulas com o **Decoda**, os estudantes frequentemente trabalham em duplas ou grupos, o que transforma o aprendizado em uma experiência coletiva. Explicar o raciocínio para um colega, comparar soluções diferentes e argumentar sobre escolhas pedagógicas desenvolve **comunicação** e **colaboração** de forma orgânica. A análise de soluções próprias e alheias — "o que funcionou, o que poderia ser melhor?" — exercita o **pensamento crítico** aplicado a situações concretas.
+
+- **Colaboração**: Trabalho em equipe e peer programming
+- **Comunicação**: Explicação de algoritmos e soluções
+- **Pensamento Crítico**: Análise e otimização de soluções
+
+## **Por onde começar?**
+
+Ao começar, escolha o seu perfil para seguir a trilha mais adequada: se você **já tem conhecimento de programação**, a sequência foca em como usar a plataforma e aplicar atividades; se você **é educador sem experiência em programação**, a trilha inclui antes os fundamentos teóricos e práticos para apoiá-lo nas aulas. Cada etapa oferece guias, exemplos e recursos práticos para aplicar em sala ou em oficinas.
+
+```mermaid
+flowchart TD
+	A[Início] --> B[Conhecer a Plataforma]
+	B --> C{Você já conhece programação?}
+
+	C -->|Sim| D[Conhecer os Guias Pedagógicos]
+	C -->|Não| E[Conhecer Fundamentos de Programação]
+	E --> D
+
+	D --> F[Conhecer Computação Desplugada]
+	F --> G[Testar atividades]
+	G --> H[Planejar suas aulas]
+	H --> I[Aplicar em sala de aula]
+	I --> J[Fim]
+
+	click B "./como-usar" "Abrir: Como Usar o Decoda"
+	click D "./guias-pedagogicos/preparando-aula" "Abrir: Guias Pedagógicos"
+	click E "./fundamentos-programacao/intro" "Abrir: Fundamentos de Programação"
+	click F "./fundamentos-programacao/computacao-desplugada" "Abrir: Computação Desplugada"
+	click G "./recursos/atividades/programacao" "Abrir: Atividades de Programação"
+	click H "./guias-pedagogicos/preparando-aula" "Abrir: Planejando e Conduzindo a Aula"
+	click I "./guias-pedagogicos/avaliacao-aprendizado" "Abrir: Acompanhamento e Situações Comuns"
+```
+
+### **1. Primeiros Passos**
+
+- [**Como Usar a Plataforma**](./como-usar) - Interface básica e navegação
+- [**Fundamentos da Programação Visual**](./fundamentos-programacao/intro) - Base teórica
+- [**Computação Desplugada**](./fundamentos-programacao/computacao-desplugada) - Metodologia prática sem computador
+
+### **2. Guias Práticos**
+
+- [**Preparando a Aula**](./guias-pedagogicos/preparando-aula) - Planejamento e checklist
+- [**Avaliação e Acompanhamento**](./guias-pedagogicos/avaliacao-aprendizado) - Como medir progresso
+
+### **3. Conhecendo os Recursos do Decoda**
+
+- [**Atividades de Programação**](./recursos/atividades/programacao) - Organização da trilha de programação
+- [**Atividades de Letramento**](./recursos/atividades/letramento) - Organização da trilha de letramento digital
+- [**Laboratório de Blocos**](./recursos/playground/blocos) - Uso do ambiente visual atual
+- [**Laboratório de Python**](./recursos/playground/python) - Curso disponível em JupyterLite
+
+## **Suporte e Comunidade**
+
+- <i class="fas fa-envelope"></i> **Suporte Técnico**: [contato@tecnologiaparatodos.org.br](mailto:contato@tecnologiaparatodos.org.br)
+- <i class="fas fa-comments"></i> **Comunidade Educativa**: Fórum de troca de experiências
+- <i class="fas fa-download"></i> **Recursos Extras**: Materiais complementares para download
+
+---
+
+**Pronto para transformar suas aulas de programação?** Comece explorando nosso guia [**Como Usar a Plataforma**](./como-usar)! <i class="fas fa-rocket"></i><i class="fas fa-sparkles"></i>

docs/edu/recursos/_category_.json

@@ -0,0 +1,12 @@
+{
+  "position": 4,
+  "label": "Recursos do Decoda",
+  "collapsible": true,
+  "collapsed": true,
+  "className": "green",
+  "link": {
+    "type": "generated-index",
+    "title": "Recursos",
+    "description": "Recursos que o Decoda oferece para ensino."
+  }
+}

docs/edu/recursos/atividades/_category_.json

@@ -0,0 +1,12 @@
+{
+  "position": 4,
+  "label": "Atividades",
+  "collapsible": true,
+  "collapsed": true,
+  "className": "green",
+  "link": {
+    "type": "generated-index",
+    "title": "Atividades",
+    "description": "As Atividades do Decoda organizam o ensino em duas trilhas complementares: Programação e Letramento Digital. A trilha de Programação desenvolve raciocínio lógico com blocos visuais e desafios progressivos; a trilha de Letramento Digital fortalece a autonomia no uso do computador (mouse, teclado e navegação), reduzindo o medo da máquina e preparando o estudante para avançar com confiança."
+  }
+}

docs/edu/recursos/atividades/letramento/_category_.json

@@ -0,0 +1,5 @@
+{
+  "label": "Letramento",
+  "position": 2,
+  "collapsed": true
+}

docs/edu/recursos/atividades/letramento/index.md

@@ -0,0 +1,33 @@
+---
+title: "Letramento"
+slug: /recursos/atividades/letramento
+---
+
+# Atividades de Letramento Digital
+
+As atividades de letramento digital do **Decoda** são voltadas para estudantes com pouca ou nenhuma familiaridade com computador. O objetivo é desenvolver segurança, autonomia e fluência nas interações básicas com a máquina antes, durante ou junto das atividades de programação.
+
+## Objetivo pedagógico
+
+Essa trilha busca reduzir o medo do computador e criar confiança para a aprendizagem digital. Mais do que "acertar" tarefas, a proposta é consolidar habilidades essenciais de interação: movimentar o cursor, clicar com precisão, usar botões do mouse, arrastar elementos e compreender instruções na tela.
+
+## Como conduzir em sala
+
+As atividades de letramento são HTMLs autocontidos e funcionam bem com mediação leve do educador:
+
+```mermaid
+flowchart TD
+  A[Selecionar atividade] --> B[Carregar HTML da atividade]
+  B --> C[Interação do estudante]
+  C --> D[Observar dúvidas e dificuldades]
+  D --> E[Intervenção curta do educador]
+  E --> F[Evento de progresso/resultado]
+  F --> G[Avançar para próxima etapa]
+```
+
+## Boas práticas de mediação
+
+- Demonstre uma vez e deixe o estudante repetir com autonomia.
+- Trabalhe em duplas quando houver poucos computadores.
+- Valorize pequenos avanços para fortalecer a autoconfiança.
+- Evite acelerar etapas: a progressão é parte do aprendizado.

docs/edu/recursos/atividades/letramento/mouse.md

@@ -0,0 +1,50 @@
+---
+sidebar_position: 3
+title: "Mouse"
+---
+
+# Atividade Mouse
+
+A atividade **Mouse** é uma trilha prática de letramento digital focada no uso do cursor, clique, duplo clique, botão direito, arrastar e soltar, controle de movimento e coordenação visomotora.
+
+Diferente das atividades de programação com blocos, aqui cada fase é um HTML autocontido com uma habilidade motora e cognitiva específica. O objetivo não é velocidade pura, mas desenvolver segurança, precisão e autonomia no uso do mouse.
+
+## O que se espera de cada fase
+
+| Fase | Atividade | Habilidade principal | O que se espera do estudante |
+| --- | --- | --- | --- |
+| 1 | **Mouse Básico** | Movimento, clique e duplo clique | Explorar a área com o cursor (cobertura mínima), clicar no alvo e realizar duplo clique com controle. |
+| 2 | **Precisão com Mouse** | Precisão de clique | Acertar alvos menores em posições variadas, ajustando coordenação fina mão-olho. |
+| 3 | **Controle do Mouse** | Trajetória do cursor | Iniciar no ponto indicado e conduzir o cursor ao longo da trilha com estabilidade. |
+| 4 | **Múltiplos Cliques** | Varredura visual | Identificar e clicar múltiplos alvos distribuídos na tela, sem repetir alvos já concluídos. |
+| 5 | **Sequência Numérica** | Ordem e atenção | Clicar os alvos na ordem correta (1 a 5), mantendo foco em sequência. |
+| 6 | **Velocidade e Reflexo** | Agilidade com controle | Clicar alvos que surgem rapidamente dentro do tempo, sem perder precisão. |
+| 7 | **Botão Direito** | Menu de contexto | Abrir o menu com botão direito e selecionar uma ação, entendendo uso contextual do clique direito. |
+| 8 | **Arrastar e Soltar** | Arrastar e soltar | Arrastar arquivos e soltar no destino correto, com noção de intenção e posicionamento. |
+| 9 | **Desenhar Traçados** | Controle contínuo | Manter clique pressionado e desenhar sobre um guia circular com cobertura mínima. |
+| 10 | **Desafio Completo** | Integração de habilidades | Resolver uma sequência de mini-desafios combinando precisão, sequência, contexto, arraste e controle. |
+
+## Como conduzir em sala
+
+- Evite intervir cedo demais: observe primeiro a estratégia do estudante.
+- Trate erro como diagnóstico de habilidade específica (ex.: precisão, ritmo ou atenção).
+- Reptir a atividade se perceber que houve muita dificuldade.
+- Usar ferramentas alternativas para desenvolver a habilidade (ex: Paint, Explorar de Arquivos para clique, duplo-clique, etc.)
+
+## Analogias úteis para explicar as fases
+
+- **Mover o mouse**: como dirigir um carrinho em uma pista sem sair da faixa.
+- **Clique simples**: como apertar a campainha uma vez.
+- **Duplo clique**: como bater duas vezes na porta em ritmo rápido.
+- **Botão direito**: como pedir "opções" de uma ferramenta antes de usar.
+- **Arrastar e soltar**: como pegar um livro e colocar na prateleira correta.
+- **Seguir trilha**: como caminhar sobre uma linha pintada no chão.
+- **Desenhar no guia**: como contornar uma figura sem levantar o lápis.
+
+## Indicadores de avanço
+
+- Consegue localizar e clicar alvos sem tensão excessiva.
+- Reduz cliques involuntários e movimentos bruscos.
+- Compreende diferença entre clique esquerdo, duplo clique e botão direito.
+- Executa arrastar e soltar com menos tentativas.
+- Mantém atenção em sequência e regras de cada fase.

docs/edu/recursos/atividades/letramento/teclado.md

@@ -0,0 +1,49 @@
+---
+sidebar_position: 4
+title: "Teclado"
+---
+
+# Atividade Teclado
+
+A atividade **Teclado** é uma trilha prática de letramento digital focada em localização de teclas, digitação de letras e números, uso de símbolos, correção de texto, navegação com setas e comandos de controle como Home, End, Enter e Esc.
+
+Assim como nas demais trilhas de letramento, cada fase é um HTML autocontido com uma habilidade específica. O objetivo não é apenas velocidade de digitação, mas desenvolver precisão, autonomia e confiança para escrever, revisar e navegar sem depender do mouse.
+
+## O que se espera de cada fase
+
+| Fase | Atividade | Habilidade principal | O que se espera do estudante |
+| --- | --- | --- | --- |
+| 1 | **Regiões do Teclado** | Mapa mental do teclado | Reconhecer grupos de teclas (letras, números, especiais e navegação) e localizar cada região com segurança. |
+| 2 | **Números do Teclado** | Digitação numérica | Digitar sequências progressivas de números, mantendo ritmo e reduzindo erros. |
+| 3 | **Prática de Escrita** | Digitação de palavras e frases | Reproduzir palavras e frases com atenção à ordem dos caracteres e ao conteúdo na tela. |
+| 4 | **Símbolos com Shift** | Combinação de teclas | Usar Shift + número para gerar símbolos, compreendendo o uso de teclas modificadoras. |
+| 5 | **Backspace e Correção** | Revisão e edição | Apagar trechos incorretos e corrigir textos, entendendo que erro faz parte do processo de escrita. |
+| 6 | **Labirinto das Setas** | Navegação direcional | Usar setas com controle para deslocamento preciso e tomada de decisão em percurso. |
+| 7 | **Teclas de Navegação** | Home, End e setas | Mover o cursor estrategicamente dentro do texto sem apagar conteúdo. |
+| 8 | **Setas no Texto** | Inserção no ponto correto | Posicionar o cursor e inserir caracteres no local certo para completar frases. |
+| 9 | **Chuva de Letras** | Agilidade com precisão | Digitar letras, combinações e palavras em tempo progressivo mantendo taxa de acerto. |
+| 10 | **Atividade Final** | Integração de habilidades | Resolver uma sequência que combina letras, números, maiúsculas, símbolos e teclas de comando. |
+
+## Como conduzir em sala
+
+- Comece com demonstração breve e deixe o estudante explorar o teclado com autonomia.
+- Observe onde surgem os erros: localização de tecla, atenção, ritmo ou coordenação bimanual.
+- Reforce postura e tempo de resposta, sem transformar a atividade em disputa de velocidade.
+- Retome fases anteriores quando notar insegurança em habilidades-base (ex.: setas, Shift, Backspace).
+- Incentive verbalização da estratégia: "qual tecla você vai usar agora e por quê?".
+
+## Analogias úteis para explicar as fases
+
+- **Regiões do teclado**: como um mapa da cidade em que cada bairro tem uma função.
+- **Números**: como discar um telefone sem olhar para as mãos o tempo todo.
+- **Shift + símbolo**: como usar uma "chave" para abrir um segundo caractere da mesma tecla.
+- **Backspace**: como usar uma borracha no caderno para ajustar o que foi escrito.
+- **Setas/Home/End**: como mover o cursor de leitura para início, meio ou fim de uma linha.
+
+## Indicadores de avanço
+
+- Localiza letras, números e teclas especiais com menor hesitação.
+- Usa Shift, Backspace e setas com intenção clara, sem tentativas aleatórias.
+- Mantém maior taxa de acerto em frases e sequências.
+- Corrige os próprios erros com mais autonomia.
+- Demonstra confiança para escrever e navegar no texto sem apoio constante.

docs/edu/recursos/atividades/programacao/_category_.json

@@ -0,0 +1,5 @@
+{
+  "label": "Programação",
+  "position": 1,
+  "collapsed": true
+}

docs/edu/recursos/atividades/programacao/aspirador.md

@@ -0,0 +1,54 @@
+---
+title: Aspirador
+sidebar_position: 3
+---
+
+# Aspirador
+
+<div style={{ display: "flex", alignItems: "flex-start", gap: "16px", flexWrap: "wrap" }}>
+	<img
+		src={require("@site/static/images/atividades/programacao/aspirador-thumbnail.png").default}
+		alt="Thumbnail da atividade Aspirador"
+		style={{ width: "280px", height: "280px", objectFit: "contain", flexShrink: 0 }}
+	/>
+	<div style={{ flex: 1, minWidth: "260px" }}>
+		<p>O Aspirador coloca o estudante diante de um problema clássico da computação: como fazer um agente agir no ambiente com base em regras, repetição e informação vinda de sensores. A narrativa do robô aspirador é simples e familiar, mas o que ela encena é profundamente algorítmico: perceber o estado do espaço, decidir a próxima ação e repetir esse ciclo até concluir a tarefa.</p>
+		<p>Ao longo das fases, a atividade sai de trajetos previsíveis e avança para situações em que o comportamento precisa se adaptar. Isso é importante porque ajuda o estudante a entender que um algoritmo não é apenas uma lista fixa de passos. Em muitos casos, ele precisa observar condições do ambiente, testar possibilidades, corrigir o rumo e manter algum critério para cobrir uma área com eficiência.</p>
+	</div>
+</div>
+
+## O que esta atividade ensina sobre programação
+
+Pedagogicamente, o Aspirador é uma atividade forte para trabalhar controle de fluxo. Nas fases iniciais, o estudante aprende a encadear ações e reconhecer padrões. Em seguida, passa a usar laços de repetição para evitar código redundante. Depois disso, entram sensores e condicionais, que introduzem a ideia de programa reativo: o comportamento muda conforme o estado detectado.
+
+As fases mais avançadas acrescentam variáveis e padrões de cobertura, como escadas, espirais e zigue-zague. Nesse ponto, a atividade deixa de ser apenas uma introdução a blocos e se torna um exercício de estratégia algorítmica. O estudante precisa pensar em eficiência, previsibilidade e generalização, que são competências importantes tanto para programação quanto para resolução de problemas mais amplos.
+
+## Mediação pedagógica
+
+Nesta atividade, costuma valer a pena pedir que o estudante descreva seu algoritmo antes de executá-lo. Quando ele explica "o robô anda até bater, depois vira e continua", já começa a externalizar a lógica que está tentando implementar. Isso ajuda o professor a identificar se o problema está na ideia do algoritmo ou apenas na montagem dos blocos.
+
+Também é útil comparar soluções. Em especial nas fases finais, duas respostas podem funcionar, mas uma ser mais legível, menor ou mais adaptável. Essa comparação abre espaço para discutir qualidade de código de forma introdutória, sem tecnicismo excessivo.
+
+## Progressão das fases
+
+| Fase | Nome | O que o estudante pratica |
+| --- | --- | --- |
+| 1 | A Linha Reta | usar um laço simples para repetir movimento até concluir a limpeza |
+| 2 | A Curva no Corredor | combinar repetição com mudança de direção em um trajeto previsível |
+| 3 | A Escadinha | organizar sequência de movimentos e viradas em padrão repetido |
+| 4 | O Sensor de Impacto | reagir a bloqueios com estruturas se/senão baseadas em sensor |
+| 5 | Modo Bordas | seguir uma estratégia estável de contorno de ambiente |
+| 6 | Desvio de Obstáculo | criar uma rotina de contorno e retorno ao caminho principal |
+| 7 | A Escada Crescente | usar variável para controlar crescimento progressivo do deslocamento |
+| 8 | A Espiral de Limpeza | combinar laços, condição e variável em um padrão expansivo |
+| 9 | O Labirinto Cego | testar alternativas de direção com decisões encadeadas |
+| 10 | Zigue-Zague | construir um algoritmo de cobertura de área com alternância e espelhamento |
+
+## Quando usar
+
+O Aspirador é especialmente adequado quando a meta é consolidar sequência, repetição e condicionais em um mesmo contexto. Ele também funciona bem como ponte entre atividades de navegação simples e problemas mais estratégicos, nos quais o estudante já precisa pensar em comportamento geral e não apenas em trajetos específicos.
+
+## Referências
+
+- Google Blockly, o que é o Blockly?: https://developers.google.com/blockly/guides/get-started/what-is-blockly?hl=pt-br
+- Fluxo de controle: https://pt.wikipedia.org/wiki/Fluxo_de_controle

docs/edu/recursos/atividades/programacao/automato.md

@@ -0,0 +1,55 @@
+---
+title: Autômato
+sidebar_position: 4
+---
+
+# Autômato
+
+<div style={{ display: "flex", alignItems: "flex-start", gap: "16px", flexWrap: "wrap" }}>
+	<img
+		src={require("@site/static/images/atividades/programacao/automato-thumbnail.png").default}
+		alt="Thumbnail da atividade Autômato"
+		style={{ width: "280px", height: "280px", objectFit: "contain", flexShrink: 0 }}
+	/>
+	<div style={{ flex: 1, minWidth: "260px" }}>
+		<p>O Autômato é uma atividade de navegação em labirintos que trabalha a construção gradual de algoritmos. Seu valor pedagógico está em tornar visível a passagem de soluções lineares para soluções estruturadas. O estudante começa com movimentos isolados, depois percebe que pode comprimir padrões com repetição e, por fim, precisa usar decisões para lidar com trajetos menos previsíveis.</p>
+		<p>Esse percurso é particularmente importante na introdução à programação porque mostra por que estruturas de controle existem. Em vez de apresentar laços e condicionais como conteúdo abstrato, a atividade os torna necessários. O estudante sente o limite de uma solução puramente sequencial e, a partir daí, encontra sentido em usar repetição e seleção.</p>
+	</div>
+</div>
+
+## O que esta atividade ensina sobre programação
+
+O Autômato desenvolve, de maneira muito direta, a ideia de algoritmo como sequência organizada de ações para atingir um objetivo. Nas primeiras fases, o foco está na precisão do comando. Em seguida, entram laços para reduzir repetição desnecessária. Nas fases posteriores, as condicionais passam a ter função central, porque o estudante precisa decidir se há caminho livre, se deve virar ou continuar, e como adaptar o percurso ao labirinto.
+
+Embora a interface seja simples, o ganho conceitual é relevante: a atividade aproxima o estudante de noções de controle de fluxo, tomada de decisão e decomposição de problemas em regras executáveis. Ela também é uma excelente base para discutir depuração, porque erros de lógica aparecem de forma concreta no caminho percorrido pelo personagem.
+
+## Mediação pedagógica
+
+Nesta atividade, é produtivo pedir que o estudante compare uma solução "bloco por bloco" com uma solução que usa repetição. Esse contraste ajuda a mostrar que programar não é apenas fazer funcionar, mas também identificar padrões e representá-los de modo mais claro.
+
+Quando surgirem labirintos com bifurcações, uma mediação útil é perguntar quais informações o programa precisa observar antes de agir. Essa pergunta desloca o foco da tentativa e erro para a leitura do estado do problema, o que prepara a compreensão de condicionais de forma mais sólida.
+
+## Progressão das fases
+
+| Fase | Nome | O que o estudante pratica |
+| --- | --- | --- |
+| 1 | Primeiro Passo | compreender o efeito do comando básico de avançar |
+| 2 | Primeira Curva | combinar deslocamento e rotação para alterar trajetória |
+| 3 | Linha Reta | usar repetição para substituir sequência redundante |
+| 4 | Escadaria | aplicar laços em trajetos diagonais com mudanças de direção |
+| 5 | Torre | planejar percurso vertical e leitura espacial do mapa |
+| 6 | Caminho em Bloco | introduzir condicional simples baseada em caminho livre |
+| 7 | Labirinto Ramificado | decidir entre alternativas em percursos que se bifurcam |
+| 8 | Caminho Complexo | lidar com trajeto mais longo mantendo legibilidade da solução |
+| 9 | Labirinto Avançado | usar if/else para diferenciar ações conforme o contexto |
+| 10 | Desafio Final | integrar movimentos, repetição e decisão em um labirinto completo |
+
+## Quando usar
+
+O Autômato é indicado para momentos em que a turma precisa consolidar a ideia de que blocos não são apenas comandos isolados, mas estruturas que organizam comportamento. Ele costuma funcionar muito bem depois de uma atividade mais descritiva, como Quebra-cabeças, e antes de atividades reativas mais complexas, como Aspirador ou Semáforo.
+
+## Referências
+
+- Google Blockly, o que é o Blockly?: https://developers.google.com/blockly/guides/get-started/what-is-blockly?hl=pt-br
+- Fluxo de controle: https://pt.wikipedia.org/wiki/Fluxo_de_controle
+- Máquina de estados finitos: https://pt.wikipedia.org/wiki/M%C3%A1quina_de_estados_finitos

docs/edu/recursos/atividades/programacao/cripto.md

@@ -0,0 +1,55 @@
+---
+title: Cripto
+sidebar_position: 8
+---
+
+# Cripto
+
+<div style={{ display: "flex", alignItems: "flex-start", gap: "16px", flexWrap: "wrap" }}>
+	<img
+		src={require("@site/static/images/atividades/programacao/cripto-thumbnail.png").default}
+		alt="Thumbnail da atividade Cripto"
+		style={{ width: "280px", height: "280px", objectFit: "contain", flexShrink: 0 }}
+	/>
+	<div style={{ flex: 1, minWidth: "260px" }}>
+		<p>Cripto é a atividade mais explicitamente voltada para representação simbólica e transformação de dados. Ela usa desafios de cifra, substituição, inversão e somatório de integridade para mostrar que programação também serve para codificar, decodificar, comparar e proteger informação. Isso a torna especialmente interessante para estudantes que já avançaram um pouco além dos comandos básicos e estão prontos para trabalhar com cadeias de texto, posições e regras mais abstratas.</p>
+		<p>Seu percurso é muito pedagógico porque começa com algo simples e concreto, a conversão entre letras e números, e avança até operações de cifra de César, alfabetos secretos e noções introdutórias de hash. Ao fazer isso, a atividade mostra que dados podem ser transformados sistematicamente por regras bem definidas e que pequenas mudanças de fórmula alteram o resultado final de maneira significativa.</p>
+	</div>
+</div>
+
+## O que esta atividade ensina sobre programação
+
+Cripto ensina, de forma bastante clara, que programar envolve percorrer sequências, manipular símbolos, guardar estados intermediários e aplicar operações repetidas com consistência. O estudante trabalha contadores, leitura de caracteres, busca de posição, concatenação de saída, uso de variáveis auxiliares e estruturas condicionais.
+
+Do ponto de vista conceitual, a atividade é valiosa porque aproxima programação de temas reais da computação, como criptografia clássica, codificação, substituição e verificação de integridade. Mesmo em nível introdutório, isso ajuda a desfazer a ideia de que programação se resume a mover objetos na tela. Aqui, o foco passa a ser transformação de informação, que é um eixo central da computação.
+
+## Mediação pedagógica
+
+Uma mediação eficaz é pedir que o estudante explique a regra da transformação em linguagem comum antes de programá-la. Por exemplo: “cada letra anda três casas no alfabeto” ou “se a letra for A, troco por 4”. Essa explicitação ajuda a converter uma regra informal em algoritmo.
+
+Também vale discutir a diferença entre cifra e hash. Mesmo de forma introdutória, a atividade permite mostrar que algumas transformações visam esconder uma mensagem, enquanto outras servem para verificar integridade. Essa conversa costuma enriquecer bastante o sentido da atividade.
+
+## Progressão das fases
+
+| Fase | Nome | O que o estudante pratica |
+| --- | --- | --- |
+| 1 | De Letra para Número | percorrer o alfabeto e associar símbolo a posição numérica |
+| 2 | De Número para Letra | reverter o mapeamento e reconstruir texto a partir de índices |
+| 3 | Cifra de César (+3) | aplicar deslocamento fixo com busca de posição e módulo |
+| 4 | Cifra de César (-3) | realizar deslocamento inverso controlando índices negativos |
+| 5 | Criptografia com Chave Variável | generalizar a cifra usando variável para a chave |
+| 6 | Descriptografia com Chave Variável | reutilizar a lógica anterior invertendo a operação |
+| 7 | Código Leetspeak | usar condicionais para substituições específicas por regra |
+| 8 | Mensagem Invertida | manipular ordem de caracteres e composição incremental de saída |
+| 9 | Alfabeto Secreto | cifrar usando correspondência entre dois alfabetos |
+| 10 | Somador de Integridade (Hash) | acumular valor numérico por fórmula repetida para integridade |
+
+## Quando usar
+
+Cripto é mais adequada quando a turma já domina repetição, variáveis e manipulação básica de texto. Ela funciona bem como atividade de aprofundamento, fechamento de trilha ou ponte para discussões sobre segurança digital, codificação e proteção de dados.
+
+## Referências
+
+- Cifra de César: https://pt.wikipedia.org/wiki/Cifra_de_C%C3%A9sar
+- Função hash: https://pt.wikipedia.org/wiki/Fun%C3%A7%C3%A3o_hash
+- Criptografia: https://pt.wikipedia.org/wiki/Criptografia

docs/edu/recursos/atividades/programacao/index.md

@@ -0,0 +1,83 @@
+---
+title: Programação
+slug: /recursos/atividades/programacao
+---
+
+# Atividades de Programação
+
+As Atividades de Programação do Decoda organizam a aprendizagem em desafios curtos, progressivos e visualmente concretos. Em vez de começar por sintaxe textual, o estudante manipula blocos, observa efeitos imediatos na tela e passa a relacionar comando, regra e resultado. Isso reduz a barreira inicial de entrada e permite concentrar a atenção no raciocínio computacional.
+
+Pedagogicamente, esse conjunto de atividades cobre um percurso bastante amplo: modelagem por propriedades, sequência de comandos, repetição, condicionais, eventos, coordenadas, variáveis, memória de estado, funções e noções iniciais de criptografia. Cada atividade enfatiza um recorte do pensamento computacional e pode ser usada tanto em trilhas sequenciais quanto em intervenções pontuais, de acordo com o objetivo da aula.
+
+## Objetivo pedagógico
+
+O principal objetivo desta trilha é desenvolver pensamento computacional com progressão didática: partir de desafios concretos e visuais, avançar para estruturas de controle e, gradualmente, chegar a problemas que exigem mais abstração, planejamento e revisão de estratégia.
+
+Além de aprender blocos ou comandos isolados, espera-se que o estudante compreenda como construir soluções passo a passo, comparar alternativas, identificar padrões e justificar decisões. Com mediação adequada, as atividades também fortalecem autonomia, linguagem para explicar raciocínio e confiança para lidar com erro como parte do processo de aprendizagem.
+
+## Como conduzir em sala
+
+Uma forma simples e eficaz de condução é trabalhar em ciclos curtos de exploração, execução e reflexão:
+
+```mermaid
+flowchart TD
+	A[Selecionar atividade e objetivo da aula] --> B[Explorar o desafio e prever estratégia]
+	B --> C[Montar solução em blocos]
+	C --> D[Executar e observar resultado]
+	D --> E[Discutir o que funcionou e o que precisa ajuste]
+	E --> F[Refinar a solução]
+	F --> C
+```
+
+Esse formato ajuda a manter o foco pedagógico em raciocínio e tomada de decisão, e não apenas em chegar rapidamente ao fim da fase.
+
+## Boas práticas de mediação
+
+- Comece pelo conceito-alvo da aula e escolha a atividade em função desse foco.
+- Incentive o estudante a explicar a estratégia antes e depois de executar.
+- Evite entregar a resposta pronta; prefira perguntas que levem à revisão do raciocínio.
+- Valorize soluções diferentes quando forem corretas e discuta critérios de clareza e eficiência.
+- Use o erro como evidência de aprendizagem em progresso, destacando o que já foi compreendido.
+
+## Como navegar nesta seção
+
+Nesta subpasta, cada atividade possui uma página própria. Em cada uma delas você encontra:
+
+- o foco pedagógico da atividade;
+- os conceitos de programação mais evidentes;
+- sugestões de mediação em sala;
+- uma tabela com a progressão das fases;
+- referências externas para aprofundamento.
+
+## Mapa das atividades
+
+| Atividade | Foco principal | Conceitos mais evidentes |
+| --- | --- | --- |
+| [Quebra-cabeças](./programacao/quebra-cabecas) | Modelagem de informações e atributos | propriedades, classificação, atribuição de valores |
+| [Aspirador](./programacao/aspirador) | Navegação reativa e estratégia | sequência, repetição, condicionais, sensores, variáveis |
+| [Autômato](./programacao/automato) | Construção de algoritmos de percurso | sequência, loops, condicionais, controle de fluxo |
+| [Semáforo](./programacao/semaforo) | Programação orientada a eventos e segurança lógica | sequência temporal, eventos, sincronização, condicionais |
+| [Tartaruga](./programacao/tartaruga) | Programação como construção visual | movimento, repetição, funções, decomposição |
+| [Toupeira](./programacao/toupeira) | Coordenadas, memória e aleatoriedade | matrizes, loops aninhados, variáveis, estado |
+| [Cripto](./programacao/cripto) | Representação simbólica e transformação de dados | laços, variáveis, condicionais, funções hash, cifra |
+| [Ordenação](./programacao/ordenacao) | Algoritmos de ordenação e análise de eficiência | listas, loops aninhados, variáveis, comparação, algoritmos clássicos |
+
+## Como escolher uma atividade
+
+Se a turma ainda está começando, vale priorizar atividades em que a relação entre comando e efeito seja imediatamente visível, como [Quebra-cabeças](./programacao/quebra-cabecas), [Semáforo](./programacao/semaforo), [Autômato](./programacao/automato) e [Aspirador](./programacao/aspirador). Elas ajudam a consolidar a ideia de que programar é construir instruções precisas para resolver um problema.
+
+Se o objetivo é avançar para estruturas mais complexas, [Toupeira](./programacao/toupeira) e [Cripto](./programacao/cripto) abrem espaço para discutir estados, regras condicionais, memória, representação de dados e transformação algorítmica de informação. Já [Ordenação](./programacao/ordenacao) aprofunda essa progressão com algoritmos clássicos e noções de eficiência comparada, sendo a mais indicada quando o objetivo inclui discutir custo computacional e múltiplas estratégias para o mesmo problema. Já [Tartaruga](./programacao/tartaruga) é especialmente útil quando se deseja trabalhar criatividade, abstração e decomposição ao mesmo tempo.
+
+## Sugestão de progressão
+
+Uma progressão possível é:
+
+1. começar com modelagem e comando simples em [Quebra-cabeças](./programacao/quebra-cabecas);
+2. avançar para navegação com [Autômato](./programacao/automato) e [Aspirador](./programacao/aspirador);
+3. introduzir coordenação de regras e eventos em [Semáforo](./programacao/semaforo);
+4. explorar criação visual e funções em [Tartaruga](./programacao/tartaruga);
+5. trabalhar memória, coordenadas e aleatoriedade em [Toupeira](./programacao/toupeira);
+6. fechar com transformação simbólica e segurança em [Cripto](./programacao/cripto);
+7. avançar para algoritmos de ordenação e análise de eficiência em [Ordenação](./programacao/ordenacao).
+
+Essa ordem não é obrigatória. Em muitos contextos, faz mais sentido escolher a atividade pelo conceito que se deseja observar ou reforçar na aula.

docs/edu/recursos/atividades/programacao/ordenacao.md

@@ -0,0 +1,251 @@
+---
+title: Ordenação
+sidebar_position: 9
+---
+
+# Ordenação
+
+<div style={{ display: "flex", alignItems: "flex-start", gap: "16px", flexWrap: "wrap" }}>
+	<img
+		src={require("@site/static/images/atividades/programacao/ordenacao-thumbnail.png").default}
+		alt="Thumbnail da atividade Ordenação"
+		style={{ width: "280px", height: "280px", objectFit: "contain", flexShrink: 0 }}
+	/>
+	<div style={{ flex: 1, minWidth: "260px" }}>
+		<p>Ordenação apresenta um dos problemas mais estudados da computação — colocar uma lista em ordem crescente — e o explora por múltiplos ângulos. O estudante implementa, fase a fase, cinco estratégias diferentes para o mesmo problema e percebe que cada uma tem uma lógica distinta, um custo diferente e situações em que funciona melhor ou pior.</p>
+		<p>Ao contrário de atividades que permitem soluções abertas, aqui cada fase exige um algoritmo específico. A validação verifica não só se a lista ficou ordenada, mas se o padrão de execução corresponde ao algoritmo pedido. Isso leva o estudante a entender o que torna cada algoritmo diferente — não apenas a chegar no resultado.</p>
+	</div>
+</div>
+
+## O que esta atividade ensina sobre programação
+
+Ordenação é um contexto muito fértil para trabalhar estruturas de repetição aninhadas, variáveis de controle e operações sobre listas. Mas o que a distingue das demais atividades é que ela introduz uma ideia central da computação: diferentes algoritmos podem resolver o mesmo problema, com estratégias e custos radicalmente distintos.
+
+Nas fases iniciais, o estudante pratica comparação e troca de dois ou três elementos com condicionais simples — consolidando o básico. A progressão avança para os algoritmos clássicos: **Bubble Sort**, **Selection Sort**, **Insertion Sort**, **Shell Sort** e **Counting Sort**. Cada um representa uma abordagem diferente, dos mais intuitivos aos que fogem completamente do paradigma de comparação direta.
+
+A atividade também é uma porta de entrada concreta para análise de algoritmos. Sem precisar de formalismo matemático, o estudante pode observar quantas operações cada estratégia realiza, comparar resultados e começar a pensar em eficiência — uma competência que vai além da programação e se aplica a qualquer tipo de problema que exige raciocínio sobre custo e escala.
+
+## Os algoritmos
+
+Cada algoritmo desta atividade representa uma estratégia diferente para o mesmo problema. Os diagramas abaixo mostram o fluxo lógico de cada um.
+
+### Bubble Sort
+
+O Bubble Sort percorre a lista repetidamente, comparando pares de elementos adjacentes e trocando os que estão fora de ordem. A cada passada completa, o maior elemento ainda desordenado chega à sua posição final. O processo se repete até que nenhuma troca seja necessária.
+
+```mermaid
+flowchart TD
+    A[Início] --> B[Nova passada pela lista]
+    B --> C[i = 0]
+    C --> D{elemento atual maior que o próximo?}
+    D -->|Sim| E[Trocar os dois]
+    D -->|Não| F[i = i + 1]
+    E --> F
+    F --> G{Fim da passada?}
+    G -->|Não| D
+    G -->|Sim| H{Alguma troca ocorreu?}
+    H -->|Sim| B
+    H -->|Não| I[Lista ordenada]
+```
+
+A versão com otimização acrescenta uma variável de controle que detecta quando nenhuma troca ocorreu na passada — o que significa que a lista já está ordenada — encerrando o algoritmo antes das passadas restantes.
+
+#### Quando é vantajoso
+
+O Bubble Sort brilha quando a lista já está quase ordenada: com a otimização de parada antecipada, ele pode terminar em uma única passada, com custo proporcional ao tamanho da lista. É também o algoritmo mais fácil de implementar e depurar, o que o torna o ponto de partida natural para quem está aprendendo ordenação.
+
+#### Quando não é a melhor escolha
+
+Em listas grandes e desordenadas, o Bubble Sort realiza um número quadrático de comparações e trocas — o que o torna impraticável para volumes acima de alguns milhares de elementos. Em performance real, costuma ser o mais lento entre os algoritmos O(n²) porque acumula muitas trocas por passada.
+
+#### Onde é usado
+
+Por seu custo quadrático, o Bubble Sort raramente é escolhido em sistemas reais. Sua importância é quase inteiramente pedagógica: a lógica de "empurrar o maior elemento para o final a cada passada" é uma das mais intuitivas para entender o conceito de ordenação. Versões educacionais e ferramentas de visualização de algoritmos o utilizam amplamente por esse motivo.
+
+### Selection Sort
+
+O Selection Sort divide a lista em duas partes: a porção já ordenada, que cresce da esquerda, e a porção desordenada. A cada passada, o algoritmo varre toda a parte desordenada para encontrar o menor elemento e o posiciona no início dela — com uma única troca por passada.
+
+```mermaid
+flowchart TD
+    A[i = 0] --> B[mínimo = i]
+    B --> C[j = i + 1]
+    C --> D{elemento j menor que elemento mínimo?}
+    D -->|Sim| E[mínimo = j]
+    D -->|Não| F[j = j + 1]
+    E --> F
+    F --> G{j chegou ao fim?}
+    G -->|Não| D
+    G -->|Sim| H[Trocar posições i e mínimo]
+    H --> I{i chegou ao penúltimo?}
+    I -->|Não| J[i = i + 1]
+    J --> B
+    I -->|Sim| K[Lista ordenada]
+```
+
+Uma característica do Selection Sort é que ele realiza exatamente `n - 1` trocas, independente do estado inicial da lista — ao contrário do Bubble Sort, que pode realizar muitas mais.
+
+#### Quando é vantajoso
+
+O Selection Sort é vantajoso quando o custo de escrever na memória é significativamente mais alto do que o de ler — por exemplo, em memórias flash, onde cada escrita tem custo real de desgaste. Nesse contexto, fazer no máximo `n - 1` trocas é uma vantagem concreta. Ele também é simples de implementar e tem comportamento previsível: o número de comparações é sempre o mesmo, independente da entrada.
+
+#### Quando não é a melhor escolha
+
+Assim como o Bubble Sort, o Selection Sort tem custo quadrático no número de comparações — mesmo que a lista já esteja ordenada, ele percorre toda a parte não ordenada a cada passada. Não existe versão com parada antecipada eficaz. Para listas grandes, algoritmos O(n log n) são muito mais eficientes.
+
+#### Onde é usado
+
+O Selection Sort aparece em contextos embarcados com memória muito limitada e escrita cara, como microcontroladores simples e dispositivos EEPROM. Em sistemas de uso geral, é substituído por algoritmos mais eficientes. Pedagogicamente, é valioso porque separa claramente a fase de busca do mínimo da fase de troca, tornando a lógica de duas etapas por passada muito explícita.
+
+### Insertion Sort
+
+O Insertion Sort constrói a lista ordenada de forma incremental. Para cada elemento da parte desordenada, ele retrocede na parte já ordenada deslocando os elementos maiores uma posição para a direita, até encontrar o lugar certo para inserir o elemento atual.
+
+```mermaid
+flowchart TD
+    A[i = 1] --> B[guardar elemento da posição i]
+    B --> C[j = i - 1]
+    C --> D{j válido e elemento j maior que o guardado?}
+    D -->|Sim| E[Deslocar elemento j uma posição para a direita]
+    E --> F[j = j - 1]
+    F --> D
+    D -->|Não| G[Inserir o guardado na posição j + 1]
+    G --> H{i chegou ao fim?}
+    H -->|Não| I[i = i + 1]
+    I --> B
+    H -->|Sim| J[Lista ordenada]
+```
+
+O Insertion Sort é muito eficiente para listas quase ordenadas, pois precisa de poucos deslocamentos quando os elementos já estão próximos de sua posição final. É também a base do Shell Sort.
+
+#### Quando é vantajoso
+
+O Insertion Sort é uma das melhores escolhas para listas pequenas (tipicamente abaixo de 20 elementos) ou quase ordenadas. Nesses casos, ele supera algoritmos teoricamente mais eficientes como o Merge Sort, que carregam custo fixo maior de divisão e combinação. Para listas já ordenadas, seu custo é linear — O(n) — pois nenhum deslocamento é necessário.
+
+#### Quando não é a melhor escolha
+
+Em listas grandes e aleatórias, o custo quadrático domina. Cada novo elemento pode precisar ser deslocado até o início da lista, resultando em muitas operações de escrita. Para esses casos, algoritmos O(n log n) são necessários.
+
+#### Onde é usado
+
+O Insertion Sort está presente em implementações híbridas de algoritmos avançados. O Timsort — usado por padrão em Python e na JVM — aplica o Insertion Sort em blocos pequenos antes de combiná-los com Merge Sort. O IntroSort — base do `std::sort` do C++ — também recorre ao Insertion Sort quando a recursão chega a sublistas pequenas. É um algoritmo com papel real e ativo nos sistemas de produção mais difundidos.
+
+### Shell Sort
+
+O Shell Sort é uma generalização do Insertion Sort. Em vez de inserir comparando apenas elementos vizinhos, ele começa comparando elementos separados por um intervalo inicial de metade do tamanho da lista. A cada rodada, esse intervalo é dividido ao meio. Quando o intervalo chega a 1, o comportamento é idêntico ao Insertion Sort — mas a lista já está bem próxima da ordem, então o trabalho restante é mínimo.
+
+```mermaid
+flowchart TD
+    A[intervalo = tamanho dividido por 2] --> B{intervalo maior ou igual a 1?}
+    B -->|Não| Z[Lista ordenada]
+    B -->|Sim| C[i = intervalo]
+    C --> D[guardar elemento da posição i]
+    D --> E[j = i - intervalo]
+    E --> F{j válido e elemento j maior que o guardado?}
+    F -->|Sim| G[Deslocar elemento j para a posição j + intervalo]
+    G --> H[j = j - intervalo]
+    H --> F
+    F -->|Não| I[Inserir o guardado na posição j + intervalo]
+    I --> J{i chegou ao fim?}
+    J -->|Não| K[i = i + 1]
+    K --> D
+    J -->|Sim| L[intervalo = intervalo dividido por 2]
+    L --> B
+```
+
+A intuição por trás do Shell Sort é que comparações de longa distância movem os elementos para perto de sua posição final muito mais rapidamente do que comparações vizinhas, reduzindo o trabalho das rodadas seguintes.
+
+#### Quando é vantajoso
+
+O Shell Sort é especialmente adequado para sistemas embarcados e ambientes sem suporte a recursão, onde algoritmos O(n log n) baseados em divisão (como Merge Sort e Quick Sort) são difíceis de implementar. Ele entrega desempenho subquadrático — na prática próximo de O(n log n) para sequências de intervalos bem escolhidas — com código iterativo simples e memória O(1).
+
+#### Quando não é a melhor escolha
+
+A complexidade do Shell Sort depende da sequência de intervalos escolhida, e a análise teórica ainda é um problema em aberto para algumas sequências. Em sistemas com suporte a recursão e memória suficiente, o Merge Sort ou o Timsort oferecem garantias mais sólidas e melhor desempenho em listas grandes.
+
+#### Onde é usado
+
+O Shell Sort é encontrado em firmwares, sistemas operacionais compactos e ambientes com pilha de chamadas limitada. O kernel do Linux e o uClibc utilizaram implementações de Shell Sort em contextos onde simplicidade e ausência de recursão eram mais importantes do que performance máxima. É também um ponto de passagem didático natural entre o Insertion Sort e os algoritmos baseados em divisão.
+
+### Counting Sort
+
+O Counting Sort é fundamentalmente diferente dos anteriores: ele **não compara elementos entre si**. Em vez disso, conta quantas vezes cada valor aparece na lista e, a partir dessas contagens, reconstrói a lista já ordenada. Por isso, ele escapa do limite teórico inferior O(n log n) que vale para qualquer algoritmo baseado em comparação.
+
+```mermaid
+flowchart TD
+    A[Criar lista de contagem com zeros] --> B[Para cada elemento da lista]
+    B --> C[Incrementar a contagem do valor correspondente]
+    C --> D{Todos os elementos contados?}
+    D -->|Não| B
+    D -->|Sim| E[v = 0]
+    E --> F{v menor que tamanho da contagem?}
+    F -->|Não| G[Lista reconstruída]
+    F -->|Sim| H{contagem de v maior que zero?}
+    H -->|Não| I[v = v + 1]
+    I --> F
+    H -->|Sim| J[Adicionar v à próxima posição da lista]
+    J --> K[Decrementar contagem de v]
+    K --> H
+```
+
+#### Quando é vantajoso
+
+O Counting Sort tem complexidade O(n + k), onde **k** é o valor máximo dos dados. Quando k é pequeno em relação a n, ele supera qualquer algoritmo de comparação: ordenar um milhão de notas escolares no intervalo 0–10 é muito mais rápido com Counting Sort do que com Bubble, Insertion ou até Merge Sort.
+
+Ele também é a base do **Radix Sort**, que o aplica dígito a dígito para ordenar inteiros arbitrários em O(d · n), onde d é o número de dígitos.
+
+#### Quando não é a melhor escolha
+
+Quando k >> n — por exemplo, ordenar 10 números no intervalo [0, 1.000.000] — o algoritmo aloca um array de 1 milhão de posições desnecessariamente, com memória O(k) dominando o custo. Além disso, o Counting Sort não se aplica diretamente a dados com ponto flutuante, strings ou objetos complexos, nem a dados com distribuição desconhecida ou muito esparsa.
+
+#### Comparação de complexidade
+
+| Algoritmo | Tempo médio | Memória |
+|---|---|---|
+| Bubble / Insertion | O(n²) | O(1) |
+| Merge / Heap | O(n log n) | O(n) / O(1) |
+| Quick Sort | O(n log n) | O(log n) |
+| Counting Sort | O(n + k) | O(k) |
+
+Nas fases desta atividade, a lista tem 10 valores com máximo 55. O Counting Sort usa um array de 56 posições — mais memória do que o estritamente necessário para n=10, mas eficiente caso houvesse muitos elementos nessa faixa. Sua importância aqui é pedagógica: ilustrar que existem algoritmos que exploram propriedades dos dados para escapar do limite O(n log n), ao custo de restrições sobre o tipo e a faixa dos valores.
+
+#### Onde é usado
+
+O Counting Sort aparece como subroutine do **Radix Sort**, que o aplica dígito a dígito para ordenar inteiros de qualquer magnitude. Sistemas de contagem de votos, classificação de idades, notas ou qualquer dado inteiro com faixa pequena e conhecida são contextos naturais. Implementações de ordenação estável em sistemas de banco de dados também o utilizam quando os dados satisfazem as restrições de tipo e faixa. No ecossistema de algoritmos, ele representa a categoria dos algoritmos não comparativos — junto com o Radix Sort e o Bucket Sort — que quebram o limite teórico O(n log n) ao explorar a estrutura interna dos dados.
+
+## Mediação pedagógica
+
+Uma abordagem eficaz é pedir que o estudante descreva o algoritmo em palavras antes de implementá-lo em blocos. "O que o Bubble Sort faz a cada passada?" ou "Como o Selection Sort escolhe o próximo elemento?" ajudam a separar a compreensão do algoritmo da habilidade de montá-lo. Se o estudante trava nos blocos, o problema está quase sempre na compreensão do algoritmo — não na ferramenta.
+
+Outro recurso valioso é comparar soluções após a implementação. Dois algoritmos que produzem o mesmo resultado final podem ter realizado quantidades muito diferentes de operações. Perguntar "qual deles você acha que fez mais trabalho?" e em seguida observar o número de comparações e trocas — disponíveis nos dados de execução — torna a noção de eficiência concreta e baseada em evidência.
+
+O Shell Sort e o Counting Sort merecem atenção especial na mediação. O Shell Sort exige que o estudante entenda por que comparar elementos distantes pode ser útil antes de comparar os vizinhos — uma ideia contraintuitiva que vale explorar antes de implementar. O Counting Sort, por sua vez, rompe com o modelo mental de "comparar e decidir" e pode gerar uma boa discussão sobre o que é realmente necessário para ordenar uma lista quando se conhece o intervalo dos dados.
+
+## Progressão das fases
+
+| Fase | Nome | O que o estudante pratica |
+|---|---|---|
+| 1 | Ordenar 2 Números | usar condicional para comparar e trocar dois valores |
+| 2 | Ordenar 3 Números | combinar repetição e condicionais para ordenar três elementos |
+| 3 | Bubble Sort | comparar pares adjacentes em passadas repetidas |
+| 4 | Bubble Sort com Otimização | adicionar controle de parada antecipada quando não há trocas |
+| 5 | Selection Sort | encontrar o mínimo da parte desordenada e posicioná-lo com uma troca |
+| 6 | Insertion Sort | inserir cada elemento na posição correta deslocando os maiores |
+| 7 | Shell Sort | usar comparações com intervalo variável que diminui progressivamente até 1 |
+| 8 | Counting Sort | contar ocorrências e reconstruir a lista sem comparar elementos |
+
+## Quando usar
+
+Ordenação é indicada quando a turma já tem fluência com laços, variáveis e condicionais, e está pronta para um problema com múltiplas soluções corretas e eficiências distintas. É especialmente adequada em aulas que queiram discutir análise de algoritmos de forma introdutória, ou que queiram mostrar que a escolha da estratégia depende das características dos dados — não apenas da correção do resultado.
+
+A atividade funciona bem como continuação natural após Cripto, já que ambas trabalham com transformação sistemática de informação regida por regras precisas. Se o objetivo incluir conceitos como memória auxiliar, troca entre espaço e tempo, ou a categoria de algoritmos não comparativos, o Counting Sort oferece um gancho concreto e didático para essa discussão.
+
+## Referências
+
+- Algoritmos de ordenação: https://pt.wikipedia.org/wiki/Algoritmo_de_ordena%C3%A7%C3%A3o
+- Bubble Sort: https://pt.wikipedia.org/wiki/Bubble_sort
+- Selection Sort: https://pt.wikipedia.org/wiki/Selection_sort
+- Insertion Sort: https://pt.wikipedia.org/wiki/Insertion_sort
+- Shell Sort: https://pt.wikipedia.org/wiki/Shell_sort
+- Counting Sort: https://pt.wikipedia.org/wiki/Counting_sort
+- Complexidade computacional: https://pt.wikipedia.org/wiki/Complexidade_computacional

docs/edu/recursos/atividades/programacao/quebra-cabecas.md

@@ -0,0 +1,55 @@
+---
+title: Quebra-cabeças
+sidebar_position: 2
+---
+
+# Quebra-cabeças
+
+<div style={{ display: "flex", alignItems: "flex-start", gap: "16px", flexWrap: "wrap" }}>
+	<img
+		src={require("@site/static/images/atividades/programacao/puzzle-thumbnail.png").default}
+		alt="Thumbnail da atividade Quebra-cabeças"
+		style={{ width: "280px", height: "280px", objectFit: "contain", flexShrink: 0 }}
+	/>
+	<div style={{ flex: 1, minWidth: "260px" }}>
+		<p>O Quebra-cabeças trabalha uma dimensão de programação que costuma aparecer pouco nas primeiras aulas: a necessidade de representar corretamente um objeto por meio de seus atributos. Em vez de pedir ao estudante que apenas mova personagens ou repita comandos, a atividade pede que ele monte uma ficha técnica coerente para cada animal. Isso desloca o foco para a ideia de que programas também organizam e descrevem dados.</p>
+		<p>Na prática, a atividade introduz uma lógica de modelagem: cada animal é descrito por tipo, número de patas, cobertura corporal, forma de locomoção e som. O estudante precisa escolher e combinar valores adequados, o que aproxima a experiência de noções fundamentais de computação, como propriedades, categorias, seleção de valores válidos e consistência entre campos relacionados. É uma boa porta de entrada para discutir variáveis e estruturas de dados sem recorrer cedo demais à abstração textual.</p>
+	</div>
+</div>
+
+## O que esta atividade ensina sobre programação
+
+Ao montar cada ficha, o estudante aprende que programar também envolve representar o mundo com precisão. Em termos pedagógicos, isso ajuda a construir repertório para compreender que um mesmo objeto pode ser descrito por diferentes propriedades e que essas propriedades precisam ser coerentes entre si. Mais adiante, essa ideia sustenta conceitos como variáveis, registros, objetos e modelagem de dados.
+
+O uso de blocos favorece esse processo porque reduz a sobrecarga de sintaxe e mantém o foco na relação entre categoria e valor. O erro deixa de ser apenas "o programa não rodou" e passa a ser também "a descrição construída não representa corretamente o problema". Esse tipo de erro é pedagogicamente rico, porque exige leitura de contexto, comparação de atributos e revisão de hipóteses.
+
+## Mediação pedagógica
+
+Uma boa estratégia é pedir que a turma verbalize por que determinada combinação faz sentido ou não. Em vez de confirmar apenas se a resposta está correta, vale perguntar quais características são essenciais para distinguir um animal de outro e quais propriedades ajudam mais a classificá-lo.
+
+Também é uma atividade adequada para introduzir a diferença entre escolher um valor qualquer e escolher um valor compatível com uma estrutura. Essa distinção é central em programação: preencher um campo não basta; é preciso preencher com um dado válido para aquele contexto.
+
+## Progressão das fases
+
+| Fase | Animal-alvo | O que o estudante pratica |
+| --- | --- | --- |
+| 1 | Gato | relacionar mamífero, quatro patas, pelos, locomoção e som em uma ficha coerente |
+| 2 | Cachorro | revisar a mesma estrutura mudando apenas atributos específicos, especialmente o som |
+| 3 | Abelha | perceber mudança de categoria e propriedades associadas, como inseto, seis patas e voo |
+| 4 | Caracol | lidar com combinações menos óbvias, como ausência de patas e locomoção rastejante |
+| 5 | Peixe | associar tipo, cobertura e locomoção típicos de ambiente aquático |
+| 6 | Aranha | diferenciar aracnídeos de insetos por número de patas e classificação |
+| 7 | Sapo | trabalhar características de anfíbios e discutir exceções em classificações cotidianas |
+| 8 | Pato | combinar ave, duas patas, penas, voo e som em uma estrutura única |
+| 9 | Cobra | observar que ausência de patas não basta para classificar um animal corretamente |
+| 10 | Leão | consolidar o uso da estrutura completa com um novo conjunto coerente de atributos |
+
+## Quando usar
+
+Esta atividade funciona bem no início de uma trilha, principalmente quando o objetivo é mostrar que programação também é organização de informação. Ela também pode ser usada antes de atividades com variáveis ou objetos, como preparação conceitual para discutir como dados são representados em um programa.
+
+## Referências
+
+- Google Blockly, o que é o Blockly?: https://developers.google.com/blockly/guides/get-started/what-is-blockly?hl=pt-br
+- Variável (ciência da computação): https://pt.wikipedia.org/wiki/Vari%C3%A1vel_(ci%C3%AAncia_da_computa%C3%A7%C3%A3o)
+- Objeto (ciência da computação): https://pt.wikipedia.org/wiki/Objeto_(ci%C3%AAncia_da_computa%C3%A7%C3%A3o)

docs/edu/recursos/atividades/programacao/semaforo.md

@@ -0,0 +1,50 @@
+---
+title: Semáforo
+sidebar_position: 5
+---
+
+# Semáforo
+
+<div style={{ display: "flex", alignItems: "flex-start", gap: "16px", flexWrap: "wrap" }}>
+	<img
+		src={require("@site/static/images/atividades/programacao/semaforo-thumbnail.png").default}
+		alt="Thumbnail da atividade Semáforo"
+		style={{ width: "280px", height: "280px", objectFit: "contain", flexShrink: 0 }}
+	/>
+	<div style={{ flex: 1, minWidth: "260px" }}>
+		<p>O Semáforo é uma atividade especialmente valiosa para introduzir programação orientada a eventos e coordenação entre regras simultâneas. Seu contexto é socialmente reconhecível: carros e pedestres precisam compartilhar o espaço com segurança. Isso faz com que o estudante compreenda rapidamente que programar, nesse caso, não é apenas acionar cores, mas sincronizar comportamentos para evitar conflito.</p>
+		<p>Ao contrário de atividades baseadas apenas em deslocamento, aqui a lógica temporal ganha protagonismo. O estudante precisa respeitar ordem, intervalos de espera, dependência entre dois sistemas e, em fases posteriores, sinais adicionais como luz piscante e som. É um contexto muito fértil para discutir estados, transições e regras de segurança.</p>
+	</div>
+</div>
+
+## O que esta atividade ensina sobre programação
+
+O Semáforo ajuda a entender que muitos programas controlam sistemas que mudam de estado ao longo do tempo. A cada comando, o sistema assume uma nova condição: verde, amarelo, vermelho, pedestre liberado, pedestre em alerta, som ativo ou inativo. Isso aproxima o estudante da lógica de máquinas de estado, mesmo sem usar esse vocabulário logo de início.
+
+Além disso, a atividade reforça a importância da ordem e da sincronização. Se um comando está correto, mas fora da sequência, o resultado ainda pode ser perigoso ou inválido. Essa percepção é pedagogicamente importante porque mostra que, em programação, não basta saber quais ações usar; é preciso também saber quando e em que relação elas devem ocorrer.
+
+## Mediação pedagógica
+
+Uma abordagem produtiva é pedir que a turma descreva o comportamento do sistema antes de montá-lo em blocos: quando o carro passa, quando o pedestre espera, quando o pedestre atravessa e quando recebe aviso de encerramento. Essa verbalização ajuda a transformar uma rotina do cotidiano em algoritmo.
+
+Também é interessante explorar a ideia de segurança lógica. Perguntas como “o que acontece se os dois estiverem verdes ao mesmo tempo?” ou “por que o amarelo existe?” ajudam a mostrar que regras intermediárias fazem parte da confiabilidade de um sistema programado.
+
+## Progressão das fases
+
+| Fase | Nome | O que o estudante pratica |
+| --- | --- | --- |
+| 1 | Controle básico do semáforo de carros | ordenar corretamente as cores do semáforo principal |
+| 2 | Controle básico com tempo | associar mudança de estado a intervalos temporais explícitos |
+| 3 | Controle do semáforo de pedestres | sincronizar dois subsistemas dependentes entre si |
+| 4 | Semáforo de pedestres com luz piscante | acrescentar estado intermediário de alerta antes do fechamento |
+| 5 | Semáforo com sons | integrar sinal visual e sonoro em uma sequência coordenada |
+
+## Quando usar
+
+Esta atividade é muito adequada quando o objetivo é discutir ordem temporal, eventos e coordenação entre múltiplas regras. Ela também funciona bem em aulas que queiram aproximar programação de problemas de cidadania, mobilidade urbana e sistemas automatizados do cotidiano.
+
+## Referências
+
+- Máquina de estados finitos: https://pt.wikipedia.org/wiki/M%C3%A1quina_de_estados_finitos
+- Fluxo de controle: https://pt.wikipedia.org/wiki/Fluxo_de_controle
+- Semáforo (sinalização): https://pt.wikipedia.org/wiki/Sem%C3%A1foro

docs/edu/recursos/atividades/programacao/tartaruga.md

@@ -0,0 +1,55 @@
+---
+title: Tartaruga
+sidebar_position: 6
+---
+
+# Tartaruga
+
+<div style={{ display: "flex", alignItems: "flex-start", gap: "16px", flexWrap: "wrap" }}>
+	<img
+		src={require("@site/static/images/atividades/programacao/turtle-thumbnail.png").default}
+		alt="Thumbnail da atividade Tartaruga"
+		style={{ width: "280px", height: "280px", objectFit: "contain", flexShrink: 0 }}
+	/>
+	<div style={{ flex: 1, minWidth: "260px" }}>
+		<p>A Tartaruga aproxima a programação da criação visual. Em vez de resolver um labirinto ou classificar dados, o estudante escreve instruções que se transformam em formas, padrões, composições e desenhos. Essa relação imediata entre comando e imagem é uma das maneiras mais eficazes de introduzir abstração, decomposição e reaproveitamento de código.</p>
+		<p>Historicamente, a programação com tartaruga está ligada à tradição educacional do Logo e ao uso de desenho geométrico como porta de entrada para pensamento computacional. No Decoda, essa proposta aparece em linguagem de blocos, com progressão que começa em formas simples e avança para funções, padrões compostos e criação autoral.</p>
+	</div>
+</div>
+
+## O que esta atividade ensina sobre programação
+
+O principal ganho pedagógico da Tartaruga é tornar visível a estrutura do algoritmo. Quando o estudante desenha um quadrado, por exemplo, percebe que uma forma pode ser descrita por um padrão que se repete. Quando desenha estrelas, círculos e composições mais complexas, passa a entender que um programa pode encapsular uma rotina em uma função e reutilizá-la em diferentes contextos.
+
+Essa atividade também ajuda a desenvolver noções de orientação, ângulo, deslocamento, repetição e coordenação entre ações. Como o resultado aparece de forma gráfica, erros e acertos ficam mais fáceis de interpretar. Isso favorece a depuração e o refinamento do raciocínio, além de abrir espaço para integrar programação com arte e geometria.
+
+## Mediação pedagógica
+
+Vale pedir que o estudante descreva qual padrão está tentando construir antes de começar a montar os blocos. Em muitos casos, a pergunta central não é “qual bloco usar?”, mas “qual regularidade existe nesse desenho?”. Essa mudança de foco é importante porque aproxima o estudante da ideia de algoritmo como descrição de um padrão.
+
+Também é produtivo comparar duas soluções visuais para o mesmo desenho: uma totalmente linear e outra baseada em função ou repetição. Essa comparação ajuda a discutir generalização, legibilidade e reaproveitamento de código sem perder o caráter criativo da atividade.
+
+## Progressão das fases
+
+| Fase | Nome | O que o estudante pratica |
+| --- | --- | --- |
+| 1 | O Quadrado | associar deslocamento e rotação para formar um polígono simples |
+| 2 | O Pentágono | ajustar repetição e ângulo para uma nova figura regular |
+| 3 | A Estrela | criar padrão geométrico mais complexo e introduzir cor |
+| 4 | Estrela e Linha | controlar caneta, deslocamento sem desenho e composição simples |
+| 5 | Quatro Estrelas | repetir uma função visual em diferentes posições |
+| 6 | Três Estrelas e uma Linha | combinar composição geométrica com mudança de cor e reposicionamento |
+| 7 | Três Estrelas e Raios | construir padrões radiais com repetição adicional |
+| 8 | Três Estrelas e um Círculo | simular curva por repetição incremental de movimentos e giros |
+| 9 | Lua Crescente | sobrepor formas e cores para produzir um efeito visual composto |
+| 10 | Desafio Livre | planejar, criar e revisar um desenho autoral com autonomia |
+
+## Quando usar
+
+A Tartaruga é ideal quando se quer mostrar que programação não serve apenas para controlar regras rígidas, mas também para criar. Ela funciona muito bem em propostas interdisciplinares com matemática, geometria e artes, além de ser uma ótima atividade para consolidar repetição e funções de maneira significativa.
+
+## Referências
+
+- Python, módulo turtle (pt-BR): https://docs.python.org/pt-br/3/library/turtle.html
+- Google Blockly, o que é o Blockly?: https://developers.google.com/blockly/guides/get-started/what-is-blockly?hl=pt-br
+- Logo (linguagem de programação): https://pt.wikipedia.org/wiki/Logo_(linguagem_de_programa%C3%A7%C3%A3o)

docs/edu/recursos/atividades/programacao/toupeira.md

@@ -0,0 +1,54 @@
+---
+title: Toupeira
+sidebar_position: 7
+---
+
+# Toupeira
+
+<div style={{ display: "flex", alignItems: "flex-start", gap: "16px", flexWrap: "wrap" }}>
+	<img
+		src={require("@site/static/images/atividades/programacao/molemash-thumbnail.png").default}
+		alt="Thumbnail da atividade Toupeira"
+		style={{ width: "280px", height: "280px", objectFit: "contain", flexShrink: 0 }}
+	/>
+	<div style={{ flex: 1, minWidth: "260px" }}>
+		<p>A Toupeira trabalha uma combinação muito rica de conceitos: coordenadas, repetição, memória, aleatoriedade e controle de estado. O tabuleiro 3x3 dá à atividade uma aparência simples, mas, pedagogicamente, ela progride para problemas bastante sofisticados, em que o estudante já não precisa apenas mover um personagem, e sim definir regras para um comportamento que se repete sem se tornar previsível ou inválido.</p>
+		<p>Essa atividade é importante porque desloca a programação do controle puramente sequencial para a gestão de informações durante a execução. O estudante precisa lembrar posições anteriores, evitar repetições, decidir o que fazer diante de sorteios aleatórios e organizar a lógica em ciclos. Isso introduz uma noção inicial de sistema dinâmico controlado por variáveis.</p>
+	</div>
+</div>
+
+## O que esta atividade ensina sobre programação
+
+Nas fases iniciais, a Toupeira ajuda a consolidar o sistema de coordenadas em grade e a leitura linha-coluna. Em seguida, amplia esse trabalho com laços de repetição e varredura completa da matriz. Mais adiante, a atividade passa a exigir sorteio de posições, armazenamento temporário em variáveis e comparação com estados anteriores.
+
+Do ponto de vista pedagógico, essa progressão é muito relevante porque mostra que programas podem produzir resultados diferentes a cada execução, desde que respeitem regras definidas. O estudante começa a entender que variáveis não servem apenas para guardar números: elas também sustentam memória, contexto e controle de comportamento.
+
+## Mediação pedagógica
+
+Antes de avançar para as fases com aleatoriedade, vale garantir que a turma esteja confortável com a leitura do tabuleiro. Uma mediação simples é pedir que os estudantes antecipem verbalmente a posição para a qual a toupeira deve saltar antes de executar o código.
+
+Nas fases com memória, é útil perguntar o que o programa precisa “lembrar” para não errar. Essa pergunta ajuda a introduzir variáveis como recurso de modelagem do estado atual e do estado anterior, em vez de tratá-las apenas como conteúdo formal.
+
+## Progressão das fases
+
+| Fase | Nome | O que o estudante pratica |
+| --- | --- | --- |
+| 1 | Movimento Sequencial | usar coordenadas simples para deslocamentos planejados na mesma linha |
+| 2 | Os Quatro Cantos | localizar posições extremas e organizar percurso em grade |
+| 3 | O Pêndulo Vertical | combinar repetição com alternância de posições fixas |
+| 4 | Varredura Completa | usar loops aninhados para percorrer toda a matriz |
+| 5 | A Toupeira Inquieta | introduzir aleatoriedade controlada com linha fixa |
+| 6 | Coordenadas na Memória | sortear linha e coluna, armazenar valores e usá-los no movimento |
+| 7 | O Centro Proibido | aplicar condicionais para restringir comportamento a partir de regras |
+| 8 | Memória de Curto Prazo | comparar posição atual com posição anterior e evitar repetição de linha |
+| 9 | O Algoritmo Perfeito | usar while e memória para impedir repetição imediata do mesmo buraco |
+| 10 | O Desafio da IA Final | integrar repetição, memória, restrições de linha e pausa entre saltos |
+
+## Quando usar
+
+Esta atividade é indicada quando a turma já domina sequência e repetição e está pronta para avançar para variáveis, memória e aleatoriedade. Ela também funciona muito bem em aulas que queiram aproximar programação de noções de grade, posição e comportamento reativo.
+
+## Referências
+
+- Sistema de coordenadas: https://pt.wikipedia.org/wiki/Sistema_de_coordenadas
+- Fluxo de controle: https://pt.wikipedia.org/wiki/Fluxo_de_controle

docs/edu/recursos/playground/_category_.json

@@ -0,0 +1,7 @@
+{
+  "position": 5,
+  "label": "Laboratórios",
+  "collapsible": true,
+  "collapsed": true,
+  "className": "purple"
+}

docs/edu/recursos/playground/blocos.md

@@ -0,0 +1,341 @@
+---
+sidebar_position: 1
+title: "Blocos"
+---
+
+# Laboratório de Blocos
+
+O **Laboratório de Blocos** é um ambiente de experimentação onde estudantes e educadores podem criar programas com blocos visuais sem limitações de fases. Ele foi pensado para apoiar aprendizagem exploratória, permitir testes rápidos de ideias e facilitar a transição progressiva da programação visual para a textual.
+
+## Objetivo do laboratório
+
+No laboratório, o foco está em:
+
+- **Experimentação livre**: criar programas sem restrições de níveis ou desafios pré-definidos.
+- **Aprendizagem exploratória**: testar hipóteses, observar resultados e refinar soluções.
+- **Visualização de código**: entender como blocos se transformam em código textual.
+- **Transição progressiva**: preparar estudantes para linguagens baseadas em texto.
+
+## JavaScript e Python: entenda a diferença
+
+No laboratório, você vê duas versões do mesmo programa:
+
+**JavaScript** <i class="lucide lucide-play-circle"></i> (código real)
+
+- É o código que **realmente executa** no navegador.
+- Ao clicar em "Executar", é este código que roda.
+- Os resultados aparecem no console da página.
+
+**Python** <i class="lucide lucide-eye"></i> (código ilustrativo)
+
+- É uma **tradução visual** dos mesmos blocos.
+- Serve para familiarizar estudantes com sintaxe Python.
+- **Não é executado** nesta interface.
+
+:::info Por que apenas JavaScript executa?
+O navegador web entende JavaScript nativamente. Python requer um ambiente específico de execução que não está disponível diretamente nesta interface de laboratório. Por isso, aqui o Python é usado como recurso pedagógico de visualização.
+:::
+
+## Como funciona
+
+### Interface em 3 painéis
+
+<img
+  src={require("../../../assets/tela-inteira-laboratorio.png").default}
+  alt="Tela completa do laboratório Decoda"
+  style={{ display: "block", margin: "0 auto", width: "80%", maxWidth: "100%", height: "auto" }}
+/>
+
+1. **Editor de blocos** (esquerda)
+
+- Arraste blocos da caixa de ferramentas.
+- Monte seu programa como um quebra-cabeça.
+- Organize e conecte os blocos logicamente.
+
+<img
+  src={require("../../../assets/editor-bloco-laboratorio.png").default}
+  alt="Editor de blocos na tela do laboratório"
+  style={{ display: "block", margin: "0 auto", width: "50%", maxWidth: "100%", height: "auto" }}
+/>
+
+2. **Visualizador de código** (centro/direita superior)
+
+- Veja o código JavaScript e Python gerado.
+- Alterne entre as duas linguagens.
+- Acompanhe como blocos viram texto.
+
+<img
+  src={require("../../../assets/visualizador-codigo-laboratorio.png").default}
+  alt="Visualizador de código no laboratório"
+  style={{ display: "block", margin: "0 auto", width: "50%", maxWidth: "100%", height: "auto" }}
+/>
+
+3. **Console de saída** (centro/direita inferior)
+
+- Execute seu programa.
+- Veja resultados e mensagens.
+- Identifique erros e faça debug.
+
+<img
+  src={require("../../../assets/console-laboratorio.png").default}
+  alt="Visualizador de console no laboratório"
+  style={{ display: "block", margin: "0 auto", width: "50%", maxWidth: "100%", height: "auto" }}
+/>
+
+## Fluxo de uso
+
+```mermaid
+flowchart TD
+  A[Abrir laboratório] --> B[Montar programa com blocos]
+  B --> C[Visualizar código gerado]
+  C --> D[Executar]
+  D --> E[Analisar resultado no console]
+  E --> F[Refinar a solução]
+  F --> B
+```
+
+## Categorias de blocos disponíveis
+
+- <i class="lucide lucide-zap"></i> **Lógica**: condicionais, comparações, operadores booleanos.
+- <i class="lucide lucide-repeat"></i> **Laços**: repetições (`for`, `while`, `forEach`).
+- <i class="lucide lucide-calculator"></i> **Matemática**: operações e funções matemáticas.
+- <i class="lucide lucide-type"></i> **Texto**: manipulação de strings e concatenação.
+- <i class="lucide lucide-list"></i> **Listas**: arrays e manipulação de coleções.
+- <i class="lucide lucide-palette"></i> **Cores**: operações com cores RGB e HSV.
+- <i class="lucide lucide-variable"></i> **Variáveis**: criação e atualização de variáveis.
+- <i class="lucide lucide-function-square"></i> **Funções**: definição de funções customizadas.
+
+## Primeiros passos
+
+1. Acesse o Laboratório no menu da plataforma.
+2. Explore a caixa de ferramentas.
+3. Arraste um bloco de saída para a área de trabalho.
+4. Digite uma mensagem.
+5. Clique em "Executar" e observe o console.
+
+:::tip Dica para iniciantes
+Comece com programas simples: mensagens, cálculos básicos e variáveis. Em seguida, avance para condicionais e laços.
+:::
+
+## Para o educador: como integrar nas aulas
+
+O laboratório pode ser usado em diferentes momentos:
+
+### 1. Demonstrações ao vivo
+
+- Projete a tela e monte programas com a turma.
+- Convide estudantes a sugerirem blocos e lógica.
+- Mostre em tempo real como o código se comporta.
+
+### 2. Atividades guiadas
+
+- Proponha desafios com objetivo claro.
+- Circule pela sala apoiando individualmente.
+- Permita soluções diferentes para o mesmo problema.
+
+### 3. Exercícios livres
+
+- Defina um objetivo geral (por exemplo, "criar uma calculadora").
+- Incentive exploração e experimentação.
+- Valorize criatividade e justificativa das escolhas.
+
+### 4. Compartilhamento de soluções
+
+- Peça apresentações curtas dos programas.
+- Compare abordagens distintas para o mesmo desafio.
+- Estimule aprendizagem entre pares.
+
+## Ideias de atividades
+
+### Nível iniciante
+
+#### Apresentação pessoal
+
+**Objetivo**: usar blocos de texto e variáveis.
+
+- Armazene nome e idade em variáveis.
+- Exiba uma mensagem de apresentação completa.
+
+**Conceitos**: variáveis, concatenação, saída de dados.
+
+#### Calculadora básica
+
+**Objetivo**: operações matemáticas e variáveis.
+
+- Armazene dois números.
+- Calcule soma, subtração, multiplicação e divisão.
+- Mostre todos os resultados.
+
+**Conceitos**: operadores, variáveis numéricas, múltiplas saídas.
+
+#### Conversor de temperatura
+
+**Objetivo**: aplicação de fórmula matemática.
+
+- Leia temperatura em Celsius.
+- Aplique $F = (C \times 9/5) + 32$.
+- Exiba o resultado.
+
+**Conceitos**: variáveis, operações e fórmulas.
+
+### Nível intermediário
+
+#### Tabuada automática
+
+**Objetivo**: laços de repetição.
+
+- Escolha um número.
+- Multiplique de 1 a 10 com um laço.
+- Imprima cada linha da tabuada.
+
+**Conceitos**: `for`, variáveis e sequência de operações.
+
+#### Lista de compras
+
+**Objetivo**: manipulação de listas.
+
+- Crie lista com 5 itens.
+- Adicione um item.
+- Remova um item.
+- Exiba a lista final.
+
+**Conceitos**: arrays e operações em coleção.
+
+#### Verificador de números
+
+**Objetivo**: condicionais.
+
+- Receba um número.
+- Verifique se é par/ímpar.
+- Verifique se é positivo/negativo/zero.
+- Exiba as classificações.
+
+**Conceitos**: `if/else`, comparação e módulo.
+
+### Nível avançado
+
+#### Sistema de pontuação
+
+**Objetivo**: funções e lógica composta.
+
+- Crie função para calcular nota final.
+- Receba notas de prova e trabalho.
+- Aplique pesos.
+- Informe aprovação com média $\geq 7$.
+
+**Conceitos**: funções, parâmetros, retorno, condicionais aninhadas.
+
+#### Ordenador de números
+
+**Objetivo**: listas e algoritmo.
+
+- Crie lista desordenada.
+- Implemente ordenação simples.
+- Exiba lista ordenada.
+
+**Conceitos**: laços aninhados, comparações e algoritmo.
+
+#### Contador de palavras
+
+**Objetivo**: manipulação de strings.
+
+- Receba uma frase.
+- Conte palavras.
+- Identifique a palavra mais longa.
+- Mostre estatísticas.
+
+**Conceitos**: texto, iteração e condicionais.
+
+## Dicas para criar seus próprios desafios
+
+### Estrutura de um bom desafio
+
+1. Objetivo claro: o que o programa deve fazer.
+2. Conceitos-chave: quais habilidades serão praticadas.
+3. Entradas e saídas: o que entra e o que deve sair.
+4. Dica inicial: por onde começar.
+5. Extensão opcional: como aprofundar.
+
+### Progressão pedagógica
+
+- Comece com **um conceito por vez**.
+- Depois **combine conceitos**.
+- Permita **múltiplas soluções válidas**.
+- Incentive **melhorias iterativas**.
+
+## Recursos pedagógicos do laboratório
+
+### Visualização dupla (JavaScript e Python)
+
+Use a comparação entre linguagens para discutir:
+
+- lógica comum e sintaxe diferente;
+- semelhanças estruturais;
+- pensamento computacional independente da linguagem.
+
+**Sugestão de atividade: "Caça às diferenças"**
+
+1. Monte um programa simples em blocos.
+2. Compare JavaScript e Python gerados.
+3. Identifique o que muda e o que permanece.
+
+### Tour guiado inicial
+
+O laboratório inclui tour interativo para apresentar interface, blocos, execução e console. Uma estratégia eficiente é primeiro um tour individual, seguido de revisão coletiva.
+
+### Exemplos prontos
+
+Os exemplos podem ser usados para inspiração, leitura de código, modificação incremental e análise reversa do raciocínio.
+
+### Persistência local
+
+Os programas são salvos localmente, permitindo continuidade entre aulas e comparação de versões.
+
+## Problemas comuns e como mediar
+
+### "Meu código não faz nada"
+
+- Verifique se clicou em executar.
+- Confira se há bloco de saída.
+- Leia o console com o estudante.
+
+### "Os blocos não encaixam"
+
+- Confira compatibilidade de tipos e encaixes.
+- Use cor e formato dos blocos como pistas.
+
+### "Deu erro no console"
+
+- Leia a mensagem de erro em conjunto.
+- Identifique a parte correspondente nos blocos.
+- Faça ajuste incremental.
+
+### "Não sei por onde começar"
+
+- Comece com um exemplo simples.
+- Divida o problema em partes menores.
+- Modifique aos poucos uma base conhecida.
+
+:::tip Celebre erros
+Erros são evidências de tentativa e parte do processo de aprendizagem. Valorize investigação, revisão e melhoria contínua.
+:::
+
+## Avaliação de aprendizagem
+
+**Evite avaliar**:
+
+- complexidade aparente do programa;
+- quantidade de blocos;
+- ausência total de erros.
+
+**Avalie**:
+
+- se a lógica resolve o problema proposto;
+- se o estudante explica o próprio raciocínio;
+- se compreende os conceitos praticados;
+- se identifica e corrige erros com apoio crescente de autonomia;
+- se demonstra evolução ao longo do tempo.
+
+:::info Foco no processo
+No laboratório, o principal indicador é evolução de raciocínio computacional, não perfeição de código.
+:::

docs/edu/recursos/playground/index.md

@@ -0,0 +1,31 @@
+---
+title: "Laboratórios"
+---
+
+# Laboratórios
+
+Os laboratórios do Decoda são ambientes de experimentação voltados para prática, investigação e autoria. Diferentemente das atividades com fases, eles permitem que estudantes e educadores testem ideias em fluxo livre, façam ajustes rápidos e comparem estratégias sem depender de uma trilha fixa.
+
+## Para que servem os laboratórios
+
+De forma geral, os laboratórios ajudam a:
+
+- ampliar repertório técnico por meio de experimentação guiada;
+- conectar conceitos de programação com prática imediata;
+- incentivar autonomia e revisão iterativa de soluções;
+- apoiar transição entre programação visual e textual.
+
+## Laboratórios disponíveis
+
+- [Blocos](./blocos): ambiente de programação visual com geração de código e console de execução.
+- [Python](./python): trilha baseada em notebooks para prática de programação textual em Python.
+
+## Como escolher entre Blocos e Python
+
+Use **Blocos** quando o foco estiver em lógica, estrutura de controle e construção de solução com menor carga de sintaxe. É especialmente útil para introdução e mediação coletiva.
+
+Use **Python** quando a turma já estiver pronta para escrever código textual, explorar sintaxe da linguagem e resolver problemas em um ambiente de notebook.
+
+## Sugestão de uso pedagógico
+
+Uma combinação comum é iniciar no laboratório de blocos para consolidar raciocínio algorítmico e, em seguida, avançar para Python para praticar leitura e escrita de código textual mantendo os mesmos conceitos-base.

docs/edu/recursos/playground/python.md

@@ -0,0 +1,60 @@
+---
+sidebar_position: 2
+title: "Python"
+---
+
+# Laboratório de Python
+
+O **Laboratório de Python** é um ambiente interativo baseado em [JupyterLite](https://jupyterlite.readthedocs.io/) — uma versão do Jupyter que roda inteiramente no navegador, sem necessidade de instalação, servidor externo ou configuração pelo estudante.
+
+A instância do Decoda está integrada à plataforma e pode ser acessada diretamente pelo menu. Ela oferece tudo que é necessário para um ensino livre de Python: execução de código real, visualização de resultados, suporte a bibliotecas e um ambiente de notebooks familiar ao ecossistema científico e educacional de Python.
+
+## O que é o Jupyter
+
+O Jupyter é um ambiente de notebooks interativos amplamente adotado no ensino de programação, ciência de dados e computação científica. Um notebook combina texto explicativo, código executável e resultados em um único documento — o que o torna especialmente adequado para aprendizagem progressiva e iterativa.
+
+No Laboratório de Python do Decoda, usamos o **JupyterLite**: uma versão que executa Python diretamente no navegador via WebAssembly, sem precisar de Python instalado no computador do estudante.
+
+```mermaid
+flowchart TD
+  A[Estudante acessa o Laboratório de Python] --> B[Navegador carrega o JupyterLite]
+  B --> C[Python roda localmente via WebAssembly]
+  C --> D[Estudante escreve e executa código em células]
+  D --> E[Resultado aparece imediatamente abaixo da célula]
+```
+
+## Uso livre
+
+Além do curso incluído, a instância oferece um ambiente de notebook completamente livre. O estudante pode:
+
+- criar novos notebooks do zero;
+- escrever qualquer código Python válido;
+- usar bibliotecas disponíveis no ambiente (como `math`, `random`, `json` e outras compatíveis com Pyodide);
+- salvar e retomar o trabalho localmente no navegador.
+
+Isso permite que o laboratório seja usado tanto como recurso guiado quanto como espaço de experimentação e projetos autorais.
+
+## Curso de Python incluído
+
+A instância já vem com três notebooks prontos para uso em aula:
+
+| Aula | Título | O que cobre |
+| --- | --- | --- |
+| 1 | Noções Básicas de Python | O que é Python, por que aprender, variáveis, tipos de dados e primeiros comandos. |
+| 2 | Estruturas Lógicas | Condicionais `if/elif/else`, operadores de comparação e tomada de decisão. |
+| 3 | Estruturas de Repetição e Boas Práticas | Laços `for` e `while`, boas práticas de código e organização de programas. |
+
+Os notebooks são sequenciais e progressivos, mas podem ser usados de forma independente conforme o ritmo da turma.
+
+## Quando usar o Laboratório de Python
+
+Use este laboratório quando a turma já estiver pronta para escrever código textual e se beneficiar da execução célula a célula. Ele é especialmente adequado para:
+
+- continuidade após o Laboratório de Blocos, aprofundando os mesmos conceitos em Python real;
+- aulas em que o educador quer combinar explicação, código e resultado no mesmo documento;
+- projetos livres em que o estudante escreve, testa e documenta sua própria solução;
+- introdução ao ecossistema de ferramentas amplamente usadas em ciência de dados e computação.
+
+:::tip Dica para o educador
+Os notebooks do curso podem ser abertos, lidos e executados célula por célula junto com a turma. Uma estratégia eficaz é executar o código coletivamente, modificar um valor e observar o que muda — isso torna o ciclo de teste-e-aprendizado visível para todos.
+:::

docs/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "docs",
+  "version": "0.0.0",
+  "private": true,
+  "scripts": {
+    "docusaurus": "docusaurus",
+    "start": "docusaurus start",
+    "build": "docusaurus build",
+    "swizzle": "docusaurus swizzle",
+    "deploy": "docusaurus deploy",
+    "clear": "docusaurus clear",
+    "serve": "docusaurus serve",
+    "write-translations": "docusaurus write-translations",
+    "write-heading-ids": "docusaurus write-heading-ids"
+  },
+  "dependencies": {
+    "@docusaurus/core": "3.10.1",
+    "@docusaurus/faster": "^3.10.1",
+    "@docusaurus/preset-classic": "3.10.1",
+    "@docusaurus/theme-mermaid": "3.10.1",
+    "@easyops-cn/docusaurus-search-local": "^0.52.1",
+    "@mdx-js/react": "^3.0.0",
+    "clsx": "^2.0.0",
+    "prism-react-renderer": "^2.3.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "devDependencies": {
+    "@docusaurus/module-type-aliases": "3.10.1",
+    "@docusaurus/types": "3.10.1"
+  },
+  "browserslist": {
+    "production": [
+      ">0.5%",
+      "not dead",
+      "not op_mini all"
+    ],
+    "development": [
+      "last 3 chrome version",
+      "last 3 firefox version",
+      "last 5 safari version"
+    ]
+  },
+  "engines": {
+    "node": ">=20.0"
+  }
+}

docs/sidebars.js

@@ -0,0 +1,32 @@
+// @ts-check
+
+// This runs in Node.js - Don't use client-side code here (browser APIs, JSX...)
+
+/**
+ * Sidebars auto-generated from filesystem structure and frontmatter
+ * Pages control their own metadata through frontmatter properties:
+ * - sidebar_position: number for ordering
+ * - sidebar_label: custom label (optional)
+ * - sidebar_class_name: custom CSS class (optional)
+ * 
+ * @type {import('@docusaurus/plugin-content-docs').SidebarsConfig}
+ */
+const sidebars = {
+  // Auto-generate sidebar from docs structure for developers
+  tutorialSidebar: [
+    {
+      type: 'autogenerated',
+      dirName: '.', // Generate from docs root directory
+    },
+  ],
+  
+  // Auto-generate sidebar from edu structure for educators
+  educatorSidebar: [
+    {
+      type: 'autogenerated',
+      dirName: '.', // Generate from edu root directory
+    },
+  ],
+};
+
+export default sidebars;

docs/src/components/Home/index.js

@@ -0,0 +1,51 @@
+import React from "react";
+import Link from "@docusaurus/Link";
+import useDocusaurusContext from "@docusaurus/useDocusaurusContext";
+import Layout from "@theme/Layout";
+import styles from "./styles.module.css";
+
+function HomePage() {
+  return (
+    <section className={styles.homeBanner}>
+      <div className={styles.mainCard}>
+        {/* Lado Esquerdo: Textos e Botões */}
+        <div>
+          <h1 className={styles.title}>
+            Documentação do{" "}
+            <span className={styles.titleHighlight}>Decoda</span>
+          </h1>
+          <p className={styles.description}>
+            Encontre tudo que você precisa para usar, desenvolver e ensinar
+            com o Decoda. Guias completos para desenvolvedores e educadores.
+          </p>
+          <div className={styles.actionButtons}>
+            <Link to="/edu/intro" className={styles.button}>
+              <i className="fas fa-graduation-cap"></i>
+              <span>Guia do Educador</span>
+            </Link>
+            <Link to="/docs/docs/intro" className={styles.button}>
+              <i className="fas fa-code"></i>
+              <span>Guia do Desenvolvedor</span>
+            </Link>
+          </div>
+        </div>
+        
+        {/* Lado Direito: Imagem */}
+        <div>
+          <img
+            src="/docs/img/home.png"
+            alt="Decoda"
+            className={styles.homeImage}
+          />
+        </div>
+      </div>
+    </section>
+  );
+}
+
+export default function Home() {
+  const { siteConfig } = useDocusaurusContext();
+  return (
+    <HomePage />
+  );
+}

docs/src/components/Home/styles.module.css

@@ -0,0 +1,105 @@
+.homeBanner {
+  background: linear-gradient(135deg, #f8f9fa, #ffffff);
+  padding: 4rem 1rem;
+  min-height: calc(100vh - 60px);
+  display: flex;
+  align-items: center;
+}
+
+.mainCard {
+  background: white;
+  border-radius: 2rem;
+  box-shadow: 0 20px 40px rgba(0, 0, 0, 0.05);
+  border: 1px solid rgba(0, 0, 0, 0.05);
+  padding: 3rem;
+  max-width: 1200px;
+  margin: 0 auto;
+  width: 100%;
+  display: grid;
+  grid-template-columns: 1fr 1fr;
+  gap: 4rem;
+  align-items: center;
+}
+
+.title {
+  font-size: clamp(2.5rem, 5vw, 4rem); 
+  font-weight: 900;
+  /* Cor gerenciada pelo custom.css global */
+  color: var(--ifm-color-emphasis-1000); 
+  line-height: 1.1;
+  margin-bottom: 1rem;
+}
+
+.titleHighlight {
+  background: linear-gradient(135deg, var(--primary-gradient-start), var(--primary-gradient-end));
+  -webkit-background-clip: text;
+  background-clip: text;
+  color: transparent;
+}
+
+.description {
+  font-size: clamp(1rem, 2vw, 1.25rem);
+  /* Cor de alto contraste gerenciada pelo custom.css global */
+  color: var(--ifm-color-emphasis-700); 
+  margin-bottom: 3rem;
+  line-height: 1.5;
+}
+
+.actionButtons {
+  display: grid;
+  grid-template-columns: 1fr 1fr;
+  gap: 1.5rem;
+  width: 100%;
+  max-width: 650px; 
+}
+
+.button {
+  background-color: var(--action-green);
+  color: #000000;
+  padding: 1rem 1.5rem; 
+  border-radius: 32px;
+  box-shadow: 0 4px 6px -1px rgba(0, 0, 0, 0.1);
+  font-size: 1rem; 
+  font-weight: 700;
+  text-decoration: none;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  gap: 0.75rem;
+  transition: transform 0.3s ease, box-shadow 0.3s ease;
+  width: 100%;
+  text-align: center;
+}
+
+.button:hover {
+  transform: scale(1.05);
+  text-decoration: none;
+  color: #000000;
+  box-shadow: 0 10px 15px -3px rgba(0, 0, 0, 0.1);
+}
+
+.homeImage {
+  width: 100%;
+  max-width: 500px;
+  margin: 0 auto;
+  display: block;
+  filter: drop-shadow(0 10px 25px rgba(0, 0, 0, 0.1));
+}
+
+/* Responsividade */
+@media (max-width: 996px) {
+  .mainCard {
+    grid-template-columns: 1fr;
+    text-align: center;
+    padding: 2rem;
+  }
+  .actionButtons {
+    margin: 0 auto;
+  }
+}
+
+@media (max-width: 600px) {
+  .actionButtons {
+    grid-template-columns: 1fr;
+  }
+}

docs/src/css/custom.css

@@ -0,0 +1,130 @@
+/* Importação das fontes do Google Fonts */
+@import url('https://fonts.googleapis.com/css2?family=Barlow+Semi+Condensed:wght@400;600;700&family=JetBrains+Mono:wght@400;700&family=Lato:wght@400;700;900&display=swap');
+
+:root {
+  /* ==========================================
+     CORES ORIGINAIS DA MARCA DECODA
+     ========================================== */
+  --brand-primary: #ed1b2f;
+  --brand-secondary: #ed0973;
+  --brand-accent: #b624c0;
+  --action-green: rgb(213, 223, 80);
+  --action-orange: rgb(255, 181, 80);
+  
+  --primary-gradient-start: #F90527;
+  --primary-gradient-end: #F50C52;
+
+  /* ==========================================
+     MAPEAMENTO DE TIPOGRAFIA (INFIMA)
+     ========================================== */
+  --ifm-font-family-base: "Lato", system-ui, sans-serif;
+  --ifm-heading-font-family: "Barlow Semi Condensed", system-ui, sans-serif;
+  --ifm-font-family-monospace: "JetBrains Mono", monospace;
+
+  /* ==========================================
+     MAPEAMENTO DE CORES PRIMÁRIAS (INFIMA)
+     ========================================== */
+  --ifm-color-primary: var(--brand-primary);
+  --ifm-color-primary-dark: #d5182a;
+  --ifm-color-primary-darker: #c91728;
+  --ifm-color-primary-darkest: #a61321;
+  --ifm-color-primary-light: #f03244;
+  --ifm-color-primary-lighter: #f13d4e;
+  --ifm-color-primary-lightest: #f45e6d;
+  --ifm-font-color-base: #000000;   
+  --ifm-color-emphasis-700: #1a1a1a; 
+  --ifm-color-emphasis-800: #000000;
+  --ifm-color-emphasis-900: #000000;
+  --ifm-color-emphasis-1000: #000000;
+  --ifm-menu-color: #1a1a1a;
+  --ifm-menu-color-active: var(--brand-primary);
+}
+/* rgb(252 165 165 / var(--tw-border-opacity, 1)) */
+
+/* ==========================================
+   SIDEBAR
+   ========================================== */
+
+.theme-doc-sidebar-menu {
+  --ifm-menu-color-background-hover: rgba(213, 223, 80, 0.2);
+}
+
+.theme-doc-sidebar-menu .menu__link,
+.theme-doc-sidebar-menu .menu__list-item-collapsible {
+  border-radius: 1rem;
+  transition: background-color 0.2s ease; /* Deixa a troca de cor mais suave */
+}
+
+.theme-doc-sidebar-menu .menu__link--active,
+.theme-doc-sidebar-menu .menu__list-item-collapsible--active {
+  background-color: var(--action-green) !important;
+  color: #000000 !important;
+  font-weight: 700 !important;
+}
+
+.theme-doc-sidebar-menu .menu__list-item-collapsible--active .menu__link--sublist-caret {
+  color: #000000 !important;
+}
+
+/* ==========================================
+   BREADCRUMBS (Trilha de Navegação)
+   ========================================== */
+
+.theme-doc-breadcrumbs .breadcrumbs__item--active .breadcrumbs__link {
+  background-color: var(--action-orange) !important;
+  color: #000000 !important;
+  font-weight: 700;
+}
+
+.theme-doc-breadcrumbs .breadcrumbs__link:hover {
+  background-color: rgba(255, 181, 80, 0.2) !important;
+  color: #000000 !important;
+}
+
+/* ==========================================
+   SIDEBAR DIREITA (Table of Contents)
+   ========================================== */
+
+.table-of-contents__link {
+  border-radius: 1rem;
+  padding: 0.3rem 0.6rem !important;
+  transition: background-color 0.2s ease, color 0.2s ease;
+  display: block; /* Garante que o fundo preencha o espaço como um botão */
+  margin-bottom: 0.15rem; /* Dá um leve respiro entre os itens */
+}
+
+.table-of-contents__link:hover {
+  background-color: rgba(255, 181, 80, 0.2) !important;
+  border-radius: 1rem;
+  color: #000000 !important;
+  text-decoration: none;
+}
+
+.table-of-contents__link--active {
+  background-color: var(--action-orange) !important;
+  color: #000000 !important;
+  font-weight: 700 !important;
+}
+
+/* ==========================================
+   SCROLLBAR
+   ========================================== */
+
+::-webkit-scrollbar {
+  width: 8px;
+  height: 8px;
+}
+
+::-webkit-scrollbar-track {
+  background: #f8f9fa; 
+  border-radius: 4px;
+}
+
+::-webkit-scrollbar-thumb {
+  background: linear-gradient(45deg, #fe0002 0%, #f50c52 100%);
+  border-radius: 4px;
+}
+
+::-webkit-scrollbar-thumb:hover {
+  background: linear-gradient(45deg, #fe0002 0%, #f50c52 100%);
+}

docs/src/js/navbar-scroll.js

@@ -0,0 +1,87 @@
+// Navbar scroll effect for Decoda Documentation
+(function () {
+  "use strict";
+
+  let navbar;
+  let scrollTimer = null;
+  let isScrolling = false;
+
+  function initNavbarScrollEffect() {
+    navbar = document.querySelector(".navbar");
+    if (!navbar) return;
+
+    // Add scroll event listener with throttling
+    window.addEventListener("scroll", handleScroll, { passive: true });
+
+    // Initial check
+    handleScroll();
+  }
+
+  function handleScroll() {
+    if (!navbar) return;
+
+    const scrollTop = window.pageYOffset || document.documentElement.scrollTop;
+    const threshold = 50; // Pixels to scroll before effect kicks in
+
+    // Clear existing timer
+    if (scrollTimer) {
+      clearTimeout(scrollTimer);
+    }
+
+    // Add scrolling class immediately
+    if (scrollTop > threshold && !isScrolling) {
+      navbar.classList.add("navbar--scrolled");
+      isScrolling = true;
+    } else if (scrollTop <= threshold && isScrolling) {
+      navbar.classList.remove("navbar--scrolled");
+      isScrolling = false;
+    }
+
+    // Debounce for performance
+    scrollTimer = setTimeout(() => {
+      const currentScrollTop =
+        window.pageYOffset || document.documentElement.scrollTop;
+      if (
+        currentScrollTop > threshold &&
+        !navbar.classList.contains("navbar--scrolled")
+      ) {
+        navbar.classList.add("navbar--scrolled");
+        isScrolling = true;
+      } else if (
+        currentScrollTop <= threshold &&
+        navbar.classList.contains("navbar--scrolled")
+      ) {
+        navbar.classList.remove("navbar--scrolled");
+        isScrolling = false;
+      }
+    }, 10);
+  }
+
+  // Initialize when DOM is ready
+  if (document.readyState === "loading") {
+    document.addEventListener("DOMContentLoaded", initNavbarScrollEffect);
+  } else {
+    initNavbarScrollEffect();
+  }
+
+  // Re-initialize on route changes (for SPA navigation)
+  window.addEventListener("popstate", () => {
+    setTimeout(initNavbarScrollEffect, 100);
+  });
+
+  // Observer for dynamic content loading
+  if (typeof MutationObserver !== "undefined") {
+    const observer = new MutationObserver((mutations) => {
+      mutations.forEach((mutation) => {
+        if (mutation.type === "childList" && !navbar) {
+          initNavbarScrollEffect();
+        }
+      });
+    });
+
+    observer.observe(document.body, {
+      childList: true,
+      subtree: true,
+    });
+  }
+})();

docs/src/pages/index.js

@@ -0,0 +1,20 @@
+import React from "react";
+import Head from "@docusaurus/Head";
+import HomePage from "@site/src/components/Home";
+
+export default function Home() {
+  return (
+    <>
+      <Head>
+        <title>Decoda - Plataforma Educacional React</title>
+        <meta
+          name="description"
+          content="Plataforma educacional React para ensino de programação visual - Portal completo para desenvolvedores e educadores"
+        />
+      </Head>
+      <div className="homepage-container homepage-hero-only">
+        <HomePage />
+      </div>
+    </>
+  );
+}

docs/src/pages/index.module.css

@@ -0,0 +1,23 @@
+/**
+ * CSS files with the .module.css suffix will be treated as CSS modules
+ * and scoped locally.
+ */
+
+.heroBanner {
+  padding: 4rem 0;
+  text-align: center;
+  position: relative;
+  overflow: hidden;
+}
+
+@media screen and (max-width: 996px) {
+  .heroBanner {
+    padding: 2rem;
+  }
+}
+
+.buttons {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}

docs/src/theme/Root.js

@@ -0,0 +1,9 @@
+import React from 'react';
+
+export default function Root({children}) {
+  return (
+    <>
+      {children}
+    </>
+  );
+}