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.

Current Guides

• gfx-mental-model.md
• audio-mental-model.md
• input-mental-model.md
• touch-mental-model.md
• save-memory-and-memcard.md
• observability-and-debugging.md
• portability-and-cross-platform.md
• time-model-and-cycles.md
• retired-decisions-004-005-history.md
• 008-gfx-status-first-fault-and-return-contract.md
• 009-audio-status-first-fault-and-return-contract.md
• 010-asset-status-first-fault-and-return-contract.md

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.

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.