# 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/`](../specs/README.md).
- As invariantes internas da VM/runtime vivem em [`../virtual-machine/ARCHITECTURE.md`](../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`](mental-model-time-and-cycles.md)
2. [`mental-model-portability-and-cross-platform.md`](mental-model-portability-and-cross-platform.md)
3. [`mental-model-observability-and-debugging.md`](mental-model-observability-and-debugging.md)
4. [`mental-model-status-first-and-fault-thinking.md`](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-time-and-cycles.md)
- [`mental-model-portability-and-cross-platform.md`](mental-model-portability-and-cross-platform.md)
- [`mental-model-observability-and-debugging.md`](mental-model-observability-and-debugging.md)
- [`mental-model-status-first-and-fault-thinking.md`](mental-model-status-first-and-fault-thinking.md)

## Peripheral Mental Models

- [`mental-model-gfx.md`](mental-model-gfx.md)
- [`mental-model-audio.md`](mental-model-audio.md)
- [`mental-model-input.md`](mental-model-input.md)
- [`mental-model-touch.md`](mental-model-touch.md)
- [`mental-model-save-memory-and-memcard.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-gfx-status-first-fault-and-return-contract.md)
- [`historical-audio-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-asset-status-first-fault-and-return-contract.md)
- [`historical-game-memcard-slots-surface-and-semantics.md`](historical-game-memcard-slots-surface-and-semantics.md)
- [`historical-retired-fault-and-input-decisions.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.