diff --git a/CLAUDE.md b/CLAUDE.md
index 214a39ed..85758fdf 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -278,10 +278,13 @@ dos_port/run                           # build + launch in DOSBox-X
 nasm -f coff -o /dev/null dos_port/src/util/fill_memory.asm
 ```
 
-DOSBox-X config (`~/.config/dosbox-x/dosbox-x-2026.06.02.conf`) is set to:
+DOSBox-X is driven by the tracked repo config **`dos_port/dosbox-x.conf`**, loaded
+automatically by `dos_port/run`. It overrides the user's system config for:
 - `machine = vgaonly` (Mode 13h plain VGA — required)
 - `cputype = 386_prefetch`
+- `cycles = fixed 23880` (386SX ~20 MHz baseline)
 - `memory io optimization 1 = false` (VGA writes broken if true)
+- `[autoexec]`: `mount c .` + launch `PKMN.EXE`
 
 **Note:** All testing and debugging must occur on **DOSBox-X**, not standard DOSBox. Standard DOSBox lacks the accuracy and debugger features required for this port.
 
diff --git a/docs/assembly.md b/docs/assembly.md
index 0afa74d9..1e7671b7 100644
--- a/docs/assembly.md
+++ b/docs/assembly.md
@@ -146,13 +146,33 @@ nasm -f coff -o /dev/null dos_port/src/util/fill_memory.asm
 
 ## DOSBox-X Configuration
 
-Config file: `~/.config/dosbox-x/dosbox-x-2026.06.02.conf`
+The repo ships a tracked config at **`dos_port/dosbox-x.conf`**. The `dos_port/run`
+script loads it automatically via `dosbox-x -defaultdir <dos_port/> -conf dosbox-x.conf`.
+It overrides the user's system config only for the settings below; everything else
+(audio, window size, etc.) falls through to the system config.
 
-Required settings:
 ```ini
-machine = vgaonly          # Mode 13h plain VGA — other machines break rendering
-cputype = 386_prefetch
-memory io optimization 1 = false   # VGA writes broken if true
+[dosbox]
+machine                   = vgaonly        ; Mode 13h plain VGA — required
+
+[video]
+memory io optimization 1  = false          ; VGA writes broken if true
+
+[cpu]
+cputype                   = 386_prefetch
+cycles                    = fixed 23880    ; 386SX ~20 MHz baseline
+cycleup                   = 500
+cycledown                 = 500
+
+[autoexec]
+mount c .                                  ; . = -defaultdir (dos_port/)
+c:
+PKMN.EXE
+```
+
+To run manually without the script:
+```sh
+dosbox-x -defaultdir "$PWD/dos_port" -conf "$PWD/dos_port/dosbox-x.conf"
 ```
 
 Must use **DOSBox-X**, not standard DOSBox. Standard DOSBox lacks the debugger
diff --git a/dos_port/dosbox-x.conf b/dos_port/dosbox-x.conf
new file mode 100644
index 00000000..706d444e
--- /dev/null
+++ b/dos_port/dosbox-x.conf
@@ -0,0 +1,23 @@
+; dos_port/dosbox-x.conf — tracked repo config for PKMN.EXE testing
+; Loaded by dos_port/run via: dosbox-x -defaultdir <dos_port/> -conf dosbox-x.conf
+; Overrides the user's system dosbox-x.conf for machine type, CPU, and cycles.
+; All other settings (audio, window, etc.) fall through to the system config.
+;
+; Target hardware baseline: 386SX @ ~20 MHz ≈ 23880 cycles in DOSBox-X.
+
+[dosbox]
+machine                   = vgaonly
+
+[video]
+memory io optimization 1  = false
+
+[cpu]
+cputype                   = 386_prefetch
+cycles                    = fixed 23880
+cycleup                   = 500
+cycledown                 = 500
+
+[autoexec]
+mount c .
+c:
+PKMN.EXE
diff --git a/dos_port/run b/dos_port/run
index f2669329..83cfadd7 100755
--- a/dos_port/run
+++ b/dos_port/run
@@ -1,6 +1,6 @@
 #!/usr/bin/env bash
-# Launch PKMN.EXE in DOSBox-X.
-# dos_port/ is mounted as C: drive.
+# Launch PKMN.EXE in DOSBox-X using the repo config (dosbox-x.conf).
+# dos_port/ is mounted as C: via 'mount c .' in the config autoexec.
 set -e
 DOSPORT="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-exec dosbox-x -defaultdir "$DOSPORT" -c "mount c \"$DOSPORT\"" -c "c:" -c "PKMN.EXE"
+exec dosbox-x -defaultdir "$DOSPORT" -conf "$DOSPORT/dosbox-x.conf"