docs: add FreeDOS/QEMU CALC launch notes

Record how to build CALC.COM, put it on a FAT floppy image, and boot it under
FreeDOS 1.4 in qemu.  The note keeps the observed LiveCD CRT/ClrScr caveat and
points at tests/calc_cli.py as the tested launcher.

FREEDOS-CALC.md

@@ -0,0 +1,119 @@
+# Running CALC.COM under FreeDOS in QEMU
+
+This is the manual FreeDOS route.  The supported, tested path remains
+`shell/tests/calc_cli.py`, which boots the compiler's own `bootcom.s` loader.
+
+## 1. Build CALC.COM
+
+From the repository root:
+
+```sh
+cd shell
+
+# Build comtest (also runs the normal COM tests).
+tests/run_com_tests.sh
+
+# Stage CALC.PAS with CALC.INC beside it.
+tests/calc_ladder.sh
+
+# Compile the staged source.  comtest writes CALC.PAS.COM in the cwd.
+printf '%s\n' ../tmp/calc_ladder/CALC.PAS | ./comtest
+mv -f CALC.PAS.COM CALC.COM
+```
+
+If a fresh `CALC.PAS.COM` is already present, `cp CALC.PAS.COM CALC.COM` is
+enough.
+
+## 2. Make a FAT floppy image containing CALC.COM
+
+```sh
+sudo apt install qemu-system-x86 mtools unzip
+
+cd /tmp
+dd if=/dev/zero of=calc.img bs=1024 count=1440
+mformat -i calc.img -f 1440 ::
+mcopy -i calc.img /path/to/TP3-comp/shell/CALC.COM ::CALC.COM
+mdir -i calc.img ::
+```
+
+`mdir` must show `CALC.COM`.
+
+## 3. Boot the FreeDOS 1.4 LiveCD
+
+Download and unpack:
+
+```sh
+mkdir -p ~/freedos
+cd ~/freedos
+wget https://download.freedos.org/1.4/FD14-LiveCD.zip
+unzip FD14-LiveCD.zip
+```
+
+Boot qemu:
+
+```sh
+qemu-system-i386 \
+  -m 128 \
+  -boot d \
+  -cdrom ~/freedos/FD14LIVE.iso \
+  -drive file=/tmp/calc.img,format=raw,if=floppy \
+  -vga std
+```
+
+At the FreeDOS menu choose **Use FreeDOS 1.4 in Live Environment mode**.
+
+At the DOS prompt, the LiveCD may take `A:`, so check both drives:
+
+```dos
+DIR A:
+DIR B:
+```
+
+In the tested layout `A:` is the FreeDOS boot floppy and the CALC floppy is
+`B:`:
+
+```dos
+B:
+CALC
+```
+
+## 4. Persistent installation
+
+Create a hard-disk image and boot the installer:
+
+```sh
+qemu-img create -f raw ~/freedos.img 128M
+qemu-system-i386 -m 128 -hda ~/freedos.img \
+  -cdrom ~/freedos/FD14LIVE.iso -boot d
+```
+
+Install to `C:`, then reboot with both disks attached:
+
+```sh
+qemu-system-i386 -m 128 -hda ~/freedos.img \
+  -drive file=/tmp/calc.img,format=raw,if=floppy -boot c
+```
+
+Inside FreeDOS:
+
+```dos
+COPY A:\CALC.COM C:\CALC.COM
+C:
+CALC
+```
+
+## Current limitation
+
+`CALC.COM` was validated under the project's SeaBIOS `bootcom.s` harness.  In
+testing the same binary under the FreeDOS 1.4 LiveCD, CALC started but its
+`ClrScr`/CRT path blanked or garbled the display.  The cell-entry and
+nested-procedure fixes are not the cause; this is a separate FreeDOS BIOS/CRT
+issue.
+
+Until that is fixed, use the tested launcher:
+
+```sh
+cd shell
+python3 tests/calc_cli.py --com CALC.PAS.COM \
+  --no-keypress --keys '\r1+2\r/Q'
+```

README.md

@@ -67,6 +67,8 @@ Options: `--keys` (Python escapes such as `\r`, `\n`, `\x1b`), `--keys-file`,
 (make AH=0Bh report no queued key; useful for scripted CALC input).
 Input is a static boot-time key stream, not a live terminal. The automated
 smoke check is `python3 tests/calc_smoke.py`, run by `tests/run_all.sh`.
+For a manual FreeDOS/qemu setup, see `FREEDOS-CALC.md`; note its current
+LiveCD display caveat.
 
 ## Layout