prometeu-runtime/docs/runtime/learn/README.md

PROMETEU Learn

Esta área reúne material didático sobre a máquina PROMETEU.

Ela existe para explicar o modelo mental da fantasy handheld, suas influências, tradeoffs e implicações de design sem contaminar as specs normativas com framing pedagógico.

Authority

• docs/runtime/learn/ não é fonte canônica de contrato técnico.
• As superfícies normativas da máquina vivem em ../specs/.
• As invariantes internas da VM/runtime vivem em ../virtual-machine/ARCHITECTURE.md.

Reading Order

Se a pessoa esta entrando agora no modelo da maquina, a ordem mais util e:

1. mental-model-time-and-cycles.md
2. mental-model-portability-and-cross-platform.md
3. mental-model-observability-and-debugging.md
4. mental-model-status-first-and-fault-thinking.md
5. depois os perifericos e dominios especificos

Core Mental Models

• mental-model-time-and-cycles.md
• mental-model-portability-and-cross-platform.md
• mental-model-observability-and-debugging.md
• mental-model-status-first-and-fault-thinking.md

Peripheral Mental Models

• mental-model-gfx.md
• mental-model-audio.md
• mental-model-input.md
• mental-model-touch.md
• mental-model-save-memory-and-memcard.md

Historical Snapshots

Estes arquivos preservam o racional de decisions ja absorvidas por specs e/ou implementacao. Eles sao uteis para contexto, mas nao devem ser lidos como contrato atual primario.

• historical-gfx-status-first-fault-and-return-contract.md
• historical-audio-status-first-fault-and-return-contract.md
• historical-asset-status-first-fault-and-return-contract.md
• historical-game-memcard-slots-surface-and-semantics.md
• historical-retired-fault-and-input-decisions.md

Naming Convention

• mental-model-*.md: ponto de entrada didatico e consolidado.
• historical-*.md: snapshot historico, racional aposentado ou consolidado em outro lugar.
• README.md: mapa e navegacao da area.

Rules

• material em learn pode explicar, comparar, ensinar e contextualizar;
• material em learn não deve redefinir o contrato normativo dos specs;
• quando um tema tiver spec e guia didático, o guia deve apontar para o spec correspondente.
• quando houver snapshot historico e guia consolidado sobre o mesmo tema, o guia consolidado deve ser o ponto de entrada.
• snapshots devem deixar claro que sao historicos e apontar para as anchors normativas atuais.

When To Create A Pair

Criar um par spec + learn quando o tema:

• precisa de contrato técnico estável e também de modelo mental;
• tem forte carga histórica, pedagógica ou de design rationale;
• corre risco de virar manifesto dentro do spec normativo;
• exige exemplos, comparações ou intuição que não pertencem ao contrato.

Se o tema for pequeno e estritamente contratual, o capítulo pode nascer só em specs.

Learn Refactoring Rule

Quando learn acumular snapshots demais:

• consolidar ideias repetidas em guias didaticos maiores;
• reduzir redundancia cronologica;
• manter snapshots apenas como rastro historico e backlink;
• reorganizar por modelo mental, nao por ordem de decisao.