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

PROMETEU Learn

This area contains pedagogical material about the PROMETEU machine.

It exists to explain the fantasy handheld's mental model, influences, tradeoffs, and design implications without contaminating the normative specs with pedagogical framing.

Authority

• docs/runtime/learn/ is not a canonical source of technical contract.
• The machine's normative surfaces live in ../specs/.
• The VM/runtime's internal invariants live in ../virtual-machine/ARCHITECTURE.md.

Reading Order

If someone is entering the machine model now, the most useful order is:

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. then the peripherals and specific domains

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-asset-management.md
• mental-model-input.md
• mental-model-touch.md
• mental-model-save-memory-and-memcard.md

Historical Snapshots

These files preserve the rationale of decisions already absorbed by specs and/or implementation. They are useful for context, but they should not be read as the primary current contract.

• 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-cartridge-boot-protocol-and-manifest-authority.md
• historical-game-memcard-slots-surface-and-semantics.md
• historical-retired-fault-and-input-decisions.md

Naming Convention

• mental-model-*.md: consolidated pedagogical entry point.
• historical-*.md: historical snapshot, retired rationale, or material consolidated elsewhere.
• README.md: area map and navigation.

Rules

• material in learn may explain, compare, teach, and provide context;
• material in learn must not redefine the normative contract of the specs;
• when a topic has both a spec and a pedagogical guide, the guide should point to the corresponding spec;
• when there is both a historical snapshot and a consolidated guide for the same topic, the consolidated guide should be the entry point;
• snapshots must make clear that they are historical and point to the current normative anchors.

When To Create A Pair

Create a spec + learn pair when the topic:

• needs a stable technical contract and a mental model;
• has strong historical, pedagogical, or design-rationale weight;
• risks turning into manifesto text inside the normative spec;
• requires examples, comparisons, or intuition that do not belong in the contract.

If the topic is small and strictly contractual, the chapter may live only in specs.

Learn Refactoring Rule

When learn accumulates too many snapshots:

• consolidate repeated ideas into larger pedagogical guides;
• reduce chronological redundancy;
• keep snapshots only as historical trace and backlink;
• reorganize by mental model, not by decision order.