discussion framework migration

README.md

@@ -31,8 +31,8 @@ PROMETEU is the machine. The VM/runtime is one subsystem inside that machine.
 
 Authoritative documents:
 
-- [`docs/runtime/virtual-machine/ARCHITECTURE.md`](docs/runtime/virtual-machine/ARCHITECTURE.md) is normative for VM/runtime invariants.
+- [`docs/runtime/virtual-machine/ARCHITECTURE.md`](docs/vm-arch/ARCHITECTURE.md) is normative for VM/runtime invariants.
-- [`docs/runtime/specs/README.md`](docs/runtime/specs/README.md) describes the broader PROMETEU machine, hardware model, and fantasy console context.
+- [`docs/runtime/specs/README.md`](docs/specs/README.md) describes the broader PROMETEU machine, hardware model, and fantasy console context.
 - Supporting material under `docs/` may expand, explain, or propose changes, but it must not silently collapse the whole machine into the VM layer.
 
 ---

docs/runtime/learn/README.md

@@ -7,8 +7,8 @@ It exists to explain the fantasy handheld's mental model, influences, tradeoffs,
 ## Authority
 
 - `docs/runtime/learn/` is not a canonical source of technical contract.
-- The machine's normative surfaces live in [`../specs/`](../specs/README.md).
+- The machine's normative surfaces live in [`../specs/`](../../specs/README.md).
-- The VM/runtime's internal invariants live in [`../virtual-machine/ARCHITECTURE.md`](../virtual-machine/ARCHITECTURE.md).
+- The VM/runtime's internal invariants live in [`../virtual-machine/ARCHITECTURE.md`](../../vm-arch/ARCHITECTURE.md).
 
 ## Reading Order
 

docs/runtime/learn/historical-asset-status-first-fault-and-return-contract.md

@@ -3,8 +3,8 @@
 Status: historical snapshot in `learn`, not normative.
 Current normative anchors:
 
-- [`../specs/15-asset-management.md`](../specs/15-asset-management.md)
+- [`../specs/15-asset-management.md`](../../specs/15-asset-management.md)
-- [`../specs/16a-syscall-policies.md`](../specs/16a-syscall-policies.md)
+- [`../specs/16a-syscall-policies.md`](../../specs/16a-syscall-policies.md)
 - [`mental-model-status-first-and-fault-thinking.md`](mental-model-status-first-and-fault-thinking.md)
 
 ## Status

docs/runtime/learn/historical-audio-status-first-fault-and-return-contract.md

@@ -3,8 +3,8 @@
 Status: historical snapshot in `learn`, not normative.
 Current normative anchors:
 
-- [`../specs/05-audio-peripheral.md`](../specs/05-audio-peripheral.md)
+- [`../specs/05-audio-peripheral.md`](../../specs/05-audio-peripheral.md)
-- [`../specs/16a-syscall-policies.md`](../specs/16a-syscall-policies.md)
+- [`../specs/16a-syscall-policies.md`](../../specs/16a-syscall-policies.md)
 - [`mental-model-status-first-and-fault-thinking.md`](mental-model-status-first-and-fault-thinking.md)
 
 ## Status

docs/runtime/learn/historical-cartridge-boot-protocol-and-manifest-authority.md

@@ -2,9 +2,9 @@
 
 Status: pedagogical / historical
 Normative anchors:
-- [`../specs/13-cartridge.md`](../specs/13-cartridge.md)
+- [`../specs/13-cartridge.md`](../../specs/13-cartridge.md)
-- [`../specs/12-firmware-pos-and-prometeuhub.md`](../specs/12-firmware-pos-and-prometeuhub.md)
+- [`../specs/12-firmware-pos-and-prometeuhub.md`](../../specs/12-firmware-pos-and-prometeuhub.md)
-- [`../specs/14-boot-profiles.md`](../specs/14-boot-profiles.md)
+- [`../specs/14-boot-profiles.md`](../../specs/14-boot-profiles.md)
 
 This document records the historical rationale behind removing `entrypoint` from the cartridge manifest and moving cartridge boot authority into the executable artifact itself.
 

docs/runtime/learn/historical-game-memcard-slots-surface-and-semantics.md

@@ -3,9 +3,9 @@
 Status: historical snapshot in `learn`, not normative.
 Current normative anchors:
 
-- [`../specs/08-save-memory-and-memcard.md`](../specs/08-save-memory-and-memcard.md)
+- [`../specs/08-save-memory-and-memcard.md`](../../specs/08-save-memory-and-memcard.md)
-- [`../specs/16-host-abi-and-syscalls.md`](../specs/16-host-abi-and-syscalls.md)
+- [`../specs/16-host-abi-and-syscalls.md`](../../specs/16-host-abi-and-syscalls.md)
-- [`../specs/16a-syscall-policies.md`](../specs/16a-syscall-policies.md)
+- [`../specs/16a-syscall-policies.md`](../../specs/16a-syscall-policies.md)
 - [`mental-model-save-memory-and-memcard.md`](mental-model-save-memory-and-memcard.md)
 - [`mental-model-status-first-and-fault-thinking.md`](mental-model-status-first-and-fault-thinking.md)
 

docs/runtime/learn/historical-gfx-status-first-fault-and-return-contract.md

@@ -3,8 +3,8 @@
 Status: historical snapshot in `learn`, not normative.
 Current normative anchors:
 
-- [`../specs/04-gfx-peripheral.md`](../specs/04-gfx-peripheral.md)
+- [`../specs/04-gfx-peripheral.md`](../../specs/04-gfx-peripheral.md)
-- [`../specs/16a-syscall-policies.md`](../specs/16a-syscall-policies.md)
+- [`../specs/16a-syscall-policies.md`](../../specs/16a-syscall-policies.md)
 - [`mental-model-status-first-and-fault-thinking.md`](mental-model-status-first-and-fault-thinking.md)
 
 ## Status

docs/runtime/learn/mental-model-asset-management.md

@@ -3,9 +3,9 @@
 Status: pedagogical
 Companion specs:
 
-- [`../specs/13-cartridge.md`](../specs/13-cartridge.md)
+- [`../specs/13-cartridge.md`](../../specs/13-cartridge.md)
-- [`../specs/15-asset-management.md`](../specs/15-asset-management.md)
+- [`../specs/15-asset-management.md`](../../specs/15-asset-management.md)
-- [`../specs/04-gfx-peripheral.md`](../specs/04-gfx-peripheral.md)
+- [`../specs/04-gfx-peripheral.md`](../../specs/04-gfx-peripheral.md)
 
 Origin decisions:
 

docs/runtime/learn/mental-model-audio.md

@@ -1,7 +1,7 @@
 # Audio Mental Model
 
 Status: pedagogical
-Companion spec: [`../specs/05-audio-peripheral.md`](../specs/05-audio-peripheral.md)
+Companion spec: [`../specs/05-audio-peripheral.md`](../../specs/05-audio-peripheral.md)
 
 The right mental model for audio in PROMETEU is an active peripheral with a budget, not "automatic sound".
 

docs/runtime/learn/mental-model-gfx.md

@@ -1,9 +1,9 @@
 # GFX Mental Model
 
 Status: pedagogical
-Companion spec: [`../specs/04-gfx-peripheral.md`](../specs/04-gfx-peripheral.md)
+Companion spec: [`../specs/04-gfx-peripheral.md`](../../specs/04-gfx-peripheral.md)
 
-Related asset spec: [`../specs/15-asset-management.md`](../specs/15-asset-management.md)
+Related asset spec: [`../specs/15-asset-management.md`](../../specs/15-asset-management.md)
 
 PROMETEU treats graphics as an explicit peripheral, not as a modern GPU.
 

docs/runtime/learn/mental-model-input.md

@@ -1,7 +1,7 @@
 # Input Mental Model
 
 Status: pedagogical
-Companion spec: [`../specs/06-input-peripheral.md`](../specs/06-input-peripheral.md)
+Companion spec: [`../specs/06-input-peripheral.md`](../../specs/06-input-peripheral.md)
 
 PROMETEU treats input as sampled state, not as an asynchronous event.
 

docs/runtime/learn/mental-model-observability-and-debugging.md

@@ -1,7 +1,7 @@
 # Observability and Debugging
 
 Status: pedagogical
-Companion spec: [`../specs/10-debug-inspection-and-profiling.md`](../specs/10-debug-inspection-and-profiling.md)
+Companion spec: [`../specs/10-debug-inspection-and-profiling.md`](../../specs/10-debug-inspection-and-profiling.md)
 
 PROMETEU was designed to be observable.
 

docs/runtime/learn/mental-model-portability-and-cross-platform.md

@@ -1,7 +1,7 @@
 # Portability and Cross-Platform Execution
 
 Status: pedagogical
-Companion spec: [`../specs/11-portability-and-cross-platform-execution.md`](../specs/11-portability-and-cross-platform-execution.md)
+Companion spec: [`../specs/11-portability-and-cross-platform-execution.md`](../../specs/11-portability-and-cross-platform-execution.md)
 
 PROMETEU treats portability as an architectural property of the machine, not as an after-the-fact adaptation.
 

docs/runtime/learn/mental-model-save-memory-and-memcard.md

@@ -1,7 +1,7 @@
 # Save Memory and MEMCARD
 
 Status: pedagogical
-Companion spec: [`../specs/08-save-memory-and-memcard.md`](../specs/08-save-memory-and-memcard.md)
+Companion spec: [`../specs/08-save-memory-and-memcard.md`](../../specs/08-save-memory-and-memcard.md)
 Historical snapshot: [`historical-game-memcard-slots-surface-and-semantics.md`](historical-game-memcard-slots-surface-and-semantics.md)
 
 PROMETEU treats persistence as explicit hardware, not as invisible save behavior.

docs/runtime/learn/mental-model-status-first-and-fault-thinking.md

@@ -3,11 +3,11 @@
 Status: pedagogical
 Companion specs:
 
-- [`../specs/16a-syscall-policies.md`](../specs/16a-syscall-policies.md)
+- [`../specs/16a-syscall-policies.md`](../../specs/16a-syscall-policies.md)
-- [`../specs/04-gfx-peripheral.md`](../specs/04-gfx-peripheral.md)
+- [`../specs/04-gfx-peripheral.md`](../../specs/04-gfx-peripheral.md)
-- [`../specs/05-audio-peripheral.md`](../specs/05-audio-peripheral.md)
+- [`../specs/05-audio-peripheral.md`](../../specs/05-audio-peripheral.md)
-- [`../specs/08-save-memory-and-memcard.md`](../specs/08-save-memory-and-memcard.md)
+- [`../specs/08-save-memory-and-memcard.md`](../../specs/08-save-memory-and-memcard.md)
-- [`../specs/15-asset-management.md`](../specs/15-asset-management.md)
+- [`../specs/15-asset-management.md`](../../specs/15-asset-management.md)
 
 PROMETEU uses a status-first model so the host/runtime boundary does not hide operational errors as silence, improper `Trap`, or accidental `Panic`.
 

docs/runtime/learn/mental-model-time-and-cycles.md

@@ -1,7 +1,7 @@
 # Time Model and Cycles
 
 Status: pedagogical
-Companion spec: [`../specs/01-time-model-and-cycles.md`](../specs/01-time-model-and-cycles.md)
+Companion spec: [`../specs/01-time-model-and-cycles.md`](../../specs/01-time-model-and-cycles.md)
 
 PROMETEU treats time as an explicit part of the machine.
 

docs/runtime/learn/mental-model-touch.md

@@ -1,7 +1,7 @@
 # Touch Mental Model
 
 Status: pedagogical
-Companion spec: [`../specs/07-touch-peripheral.md`](../specs/07-touch-peripheral.md)
+Companion spec: [`../specs/07-touch-peripheral.md`](../../specs/07-touch-peripheral.md)
 
 PROMETEU uses TOUCH as an absolute, deterministic pointer, not as a gesture-rich surface.
 

docs/specs/01-time-model-and-cycles.md

@@ -3,7 +3,7 @@
 Domain: machine timing and cycles
 Function: normative
 
-Didactic companion: [`../learn/mental-model-time-and-cycles.md`](../learn/mental-model-time-and-cycles.md)
+Didactic companion: [`../learn/mental-model-time-and-cycles.md`](../runtime/learn/mental-model-time-and-cycles.md)
 
 ## 1 Scope
 

docs/specs/02-vm-instruction-set.md

@@ -12,7 +12,7 @@ It is intentionally narrower than the broader machine specs:
 - verifier boundary;
 - relationship between the VM and adjacent specs.
 
-For the bytecode-level instruction contract, see [`../virtual-machine/ISA_CORE.md`](../virtual-machine/ISA_CORE.md).
+For the bytecode-level instruction contract, see [`../virtual-machine/ISA_CORE.md`](../vm-arch/ISA_CORE.md).
 
 ## 1 Scope
 
@@ -67,7 +67,7 @@ Each frame:
 
 ## 4 Instruction Families
 
-The public VM instruction surface is documented at the bytecode level in [`../virtual-machine/ISA_CORE.md`](../virtual-machine/ISA_CORE.md). At the machine/spec level, the instruction families are:
+The public VM instruction surface is documented at the bytecode level in [`../virtual-machine/ISA_CORE.md`](../vm-arch/ISA_CORE.md). At the machine/spec level, the instruction families are:
 
 - execution control:
   - `NOP`, `HALT`, `JMP`, `JMP_IF_FALSE`, `JMP_IF_TRUE`, `TRAP`, `FRAME_SYNC`

docs/specs/04-gfx-peripheral.md

@@ -3,7 +3,7 @@
 Domain: virtual hardware: graphics
 Function: normative
 
-Didactic companion: [`../learn/mental-model-gfx.md`](../learn/mental-model-gfx.md)
+Didactic companion: [`../learn/mental-model-gfx.md`](../runtime/learn/mental-model-gfx.md)
 
 ## 1. Overview
 

docs/specs/05-audio-peripheral.md

@@ -3,7 +3,7 @@
 Domain: virtual hardware: audio
 Function: normative
 
-Didactic companion: [`../learn/mental-model-audio.md`](../learn/mental-model-audio.md)
+Didactic companion: [`../learn/mental-model-audio.md`](../runtime/learn/mental-model-audio.md)
 
 ## 1 Scope
 

docs/specs/06-input-peripheral.md

@@ -3,7 +3,7 @@
 Domain: virtual hardware: input  
 Function: normative
 
-Didactic companion: [`../learn/mental-model-input.md`](../learn/mental-model-input.md)
+Didactic companion: [`../learn/mental-model-input.md`](../runtime/learn/mental-model-input.md)
 
 ## 1 Scope
 

docs/specs/07-touch-peripheral.md

@@ -3,7 +3,7 @@
 Domain: virtual hardware: touch
 Function: normative
 
-Didactic companion: [`../learn/mental-model-touch.md`](../learn/mental-model-touch.md)
+Didactic companion: [`../learn/mental-model-touch.md`](../runtime/learn/mental-model-touch.md)
 
 ## 1 Scope
 

docs/specs/08-save-memory-and-memcard.md

@@ -3,7 +3,7 @@
 Domain: virtual hardware: save memory  
 Function: normative
 
-Didactic companion: [`../learn/mental-model-save-memory-and-memcard.md`](../learn/mental-model-save-memory-and-memcard.md)
+Didactic companion: [`../learn/mental-model-save-memory-and-memcard.md`](../runtime/learn/mental-model-save-memory-and-memcard.md)
 
 ## 1 Scope
 

docs/specs/10-debug-inspection-and-profiling.md

@@ -3,7 +3,7 @@
 Domain: machine diagnostics
 Function: normative
 
-Didactic companion: [`../learn/mental-model-observability-and-debugging.md`](../learn/mental-model-observability-and-debugging.md)
+Didactic companion: [`../learn/mental-model-observability-and-debugging.md`](../runtime/learn/mental-model-observability-and-debugging.md)
 
 ## 1 Scope
 

docs/specs/11-portability-and-cross-platform-execution.md

@@ -3,7 +3,7 @@
 Domain: portability contract
 Function: normative
 
-Didactic companion: [`../learn/mental-model-portability-and-cross-platform.md`](../learn/mental-model-portability-and-cross-platform.md)
+Didactic companion: [`../learn/mental-model-portability-and-cross-platform.md`](../runtime/learn/mental-model-portability-and-cross-platform.md)
 
 ## 1 Scope
 

docs/specs/README.md

@@ -19,11 +19,11 @@ Belongs in `docs/runtime/specs/`:
 Does not belong in `docs/runtime/specs/` as the primary canonical source:
 
 - internal architectural invariants of the VM/runtime:
-  [`../virtual-machine/ARCHITECTURE.md`](../virtual-machine/ARCHITECTURE.md);
+  [`../virtual-machine/ARCHITECTURE.md`](../vm-arch/ARCHITECTURE.md);
 - bytecode-level ISA:
-  [`../virtual-machine/ISA_CORE.md`](../virtual-machine/ISA_CORE.md);
+  [`../virtual-machine/ISA_CORE.md`](../vm-arch/ISA_CORE.md);
 - pedagogical guides and learning material:
-  [`../learn/README.md`](../learn/README.md);
+  [`../learn/README.md`](../runtime/learn/README.md);
 - agendas, proposals, and plans:
   `docs/runtime/agendas/` and `docs/runtime/pull-requests/`.
 
@@ -87,8 +87,8 @@ In the current state, no chapter under the active `docs/runtime/specs/` root is
 ## Authority Model
 
 - `docs/runtime/specs/` defines the PROMETEU machine and its external execution surfaces.
-- [`../virtual-machine/ARCHITECTURE.md`](../virtual-machine/ARCHITECTURE.md) remains the canonical authority for internal VM/runtime invariants.
+- [`../virtual-machine/ARCHITECTURE.md`](../vm-arch/ARCHITECTURE.md) remains the canonical authority for internal VM/runtime invariants.
-- [`../virtual-machine/ISA_CORE.md`](../virtual-machine/ISA_CORE.md) remains the authority for the bytecode ISA.
+- [`../virtual-machine/ISA_CORE.md`](../vm-arch/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