PROMETEU is a fantasy handheld / fantasy console. The VM is only one subsystem of that machine. Because of that, this documentation surface covers more than bytecode and runtime: it covers timing, virtual hardware, firmware, cartridge packaging, assets, and the host ABI.

The organization here is intentionally flat. The taxonomy is conceptual, not structural.

Scope Boundary

Belongs in docs/runtime/specs/:

the technical contract of the PROMETEU machine;
virtual hardware and its peripherals;
the firmware and boot envelope;
cartridge, asset, and load surfaces;
the VM-to-host ABI.

Does not belong in docs/runtime/specs/ as the primary canonical source:

internal architectural invariants of the VM/runtime: ../virtual-machine/ARCHITECTURE.md;
bytecode-level ISA: ../virtual-machine/ISA_CORE.md;
pedagogical guides and learning material: ../learn/README.md;
agendas, proposals, and plans: docs/runtime/agendas/ and docs/runtime/pull-requests/.

Organization Rules

flat structure;
no topics/ folder;
no embedded Back / Next / Summary navigation;
semantic filenames;
each chapter must stand on its own;
each chapter must declare its domain and documentary function at the top of the file;
taxonomy should live in the README, not in an artificial directory tree.

Taxonomy

Range	Domain
`01`	machine timing and cycle budget
`02` to `03`, `09a`, `16` to `16a`	VM subsystem and host ABI
`04` to `08`	virtual hardware peripherals
`09` to `11`	machine execution envelope, diagnostics, and portability
`12` and `14`	firmware and boot orchestration
`13` and `15`	cartridge package and asset surface

Here, hardware is not a generic bucket for everything. In the current package, "hardware" means the machine's virtual peripherals: GFX, AUDIO, INPUT, TOUCH, and MEMCARD/save memory. VM, firmware, cartridge, and ABI sit in sibling categories rather than inside hardware.

Document Functions

normative: defines the technical contract, expected behavior, or implementation-facing surface.
mixed (normative + explanatory): contains technical contract material but preserves explanatory framing to clarify the machine model.
historical: archived material; not the authority for new implementation work.
pedagogical: teaching material; does not define the technical contract on its own.

In the current state, no chapter under the active docs/runtime/specs/ root is purely historical. If historical material appears, it must not compete with the primary normative surface.

Current Chapter Map

File	Domain	Function
`01-time-model-and-cycles.md`	machine timing and cycles	normative
`02-vm-instruction-set.md`	VM subsystem overview	normative
`02a-vm-values-and-calling-convention.md`	VM values and calling convention	normative
`02b-vm-function-values-and-closures.md`	VM closures and function values	normative
`03-memory-stack-heap-and-allocation.md`	VM memory model	normative
`04-gfx-peripheral.md`	virtual hardware: graphics	normative
`05-audio-peripheral.md`	virtual hardware: audio	normative
`06-input-peripheral.md`	virtual hardware: input	normative
`07-touch-peripheral.md`	virtual hardware: touch	normative
`08-save-memory-and-memcard.md`	virtual hardware: save memory	normative
`09-events-and-concurrency.md`	machine events and frame scheduling	normative
`09a-coroutines-and-cooperative-scheduling.md`	VM coroutine model	normative
`10-debug-inspection-and-profiling.md`	machine diagnostics	normative
`11-portability-and-cross-platform-execution.md`	portability contract	normative
`12-firmware-pos-and-prometeuhub.md`	firmware and system orchestration	normative
`13-cartridge.md`	cartridge package	normative
`14-boot-profiles.md`	firmware boot flow	normative
`15-asset-management.md`	asset runtime surface	normative
`16-host-abi-and-syscalls.md`	host ABI structure	normative
`16a-syscall-policies.md`	host ABI operational policy	normative

Authority Model

docs/runtime/specs/ defines the PROMETEU machine and its external execution surfaces.
../virtual-machine/ARCHITECTURE.md remains the canonical authority for internal VM/runtime invariants.
../virtual-machine/ISA_CORE.md remains the authority for the bytecode ISA.
When a chapter here touches the VM, it may complement but must not contradict the canonical VM/runtime architecture.

Rules for Future Chapters

the filename should communicate the domain;
the chapter should declare Domain and Function at the top;
hardware chapters should cover peripherals or observable machine surfaces, not arbitrary technical topics;
historical or purely pedagogical chapters must not compete with normative chapters for authority;
internal links should add real context rather than act as mandatory navigation.

Pairing Rule

A topic should be created as a spec + learn pair when:

the normative contract matters, but the mental model matters too;
the text needs historical context, comparison with classic hardware, or extensive design rationale;
the pedagogical material risks bloating or confusing the normative chapter;
the subject serves both as a technical surface and as a teaching tool.

In those cases:

docs/runtime/specs/ defines the contract;
docs/runtime/learn/ explains the why, the intuition, and the examples;
the spec should point to the pedagogical companion near the top;
the pedagogical guide should point back to the canonical spec.