Imported from just-chillin/dos-containers (AGENTS.md). Install upstream with npx skills add just-chillin/dos-containers. Copyright stays with the author.

AGENTS.md

Guidance for AI agents working in this repo.

What this is

A wrapper repo around PC-MOS/386 v5.01 (a multiuser DOS clone), vendored as the git submodule pcmos386v501/ (from git@github.com:roelandjansen/pcmos386v501.git). All interaction with it — booting, disk setup, driving the guest — goes through the root Makefile and QEMU.

After a fresh clone:

git submodule update --init

Wiki

Deeper operational knowledge lives in wiki/: PC-MOS's own command set and INT D4h API, CONFIG.SYS/SMPSIZE internals, the multitasking model (ADDTASK/SWITCH/MOS MAP), disk-image internals and the mtools write-lock/writeback-cache traps, building DOS programs on this host (nasm today, Open Watcom for anything needing real C), the from-scratch install flow, and the eval-copy timeout. The Gotchas section below is the quick reference; the wiki has the full "why" and the exact commands.

Makefile targets

Agent workflow: driving the guest

Because PC-MOS/386 is text-mode, and QEMU's curses display renders that text mode as literal terminal characters, and tmux buffers whatever's drawn to its pane independent of any attached client — an agent can close the loop entirely through shell commands:

1. make run-curses — boot it.
2. make tmux-read — read the current screen state as text.
3. Decide what to do based on that text.
4. make tmux-send CMD="..." — act (type a command/response, or a function key — see Gotchas below).
5. Repeat from step 2.

This is the intended pattern for automating things like the HDSETUP / MSYS install flow: read the prompt text, send the appropriate response, read the next screen, and so on, without any human in the loop.

Working from a mobile session

When the user is driving this from a phone, make tmux-read text dumps are hard to read and easy to misjudge — column alignment collapses, and CP437 box-drawing characters may not survive the trip. Take screenshots and attach them. After any step that changes what's on the guest screen, run make screenshot and send the resulting screenshots/screen.png to the user rather than pasting a text dump. It's a real framebuffer grab, so it shows exactly what the guest is displaying, free of any encoding issues.

Prefer this over tmux-read for reporting to a mobile user. tmux-read is still the right tool for the agent's own read-decide-act loop.

Gotchas

• Stale QEMU processes hold file locks. Before running any target that touches images/pcmos-hdd.img or either floppy image, run ps aux | grep qemu. A leftover process from a previous run will make a new launch fail instantly with Failed to get write lock. If this happens inside run-curses, tmux's sole pane exits immediately, which kills the whole session — so the symptom you'll actually see is make tmux-read failing with no server running. Fix: kill the stale QEMU process, then retry make run-curses.
• Don't rely on Ctrl+Alt+2/Ctrl+Alt+1 to switch to/from the QEMU monitor console inside a real terminal — it's unreliable (terminals don't reliably pass those modifier combos through). Use the monitor unix socket instead: make monitor CMD="...".
• CP437 control-range glyphs (0x00–0x1F) render as garbage, and this is not fixable from the terminal side. Most of CP437 comes through fine — box drawing (╔ ═ ║ ╚), shading (░ ▒ ▓) — because qemu's curses UI converts guest bytes with iconv -f CP437. But CP437's graphical meanings for the 0x00–0x1F range (↑ ↓ ♥ ♦ ¶ § …) are not in the standard CP437 mapping; iconv correctly treats those bytes as C0 control characters. qemu hands the control char to ncurses, which emits garbage — typically a double-width CJK codepoint, which also eats a cell and truncates the rest of the row. Observed: the scrollbar arrows in HDSETUP-style menus come out as 鄡 (U+9121) and 錡 (U+9321) instead of ↑/↓, and those rows capture as 53 chars instead of 80. No LANG/LC_ALL/tmux -u setting changes this — the corruption happens inside qemu before tmux ever sees it. Use make screenshot whenever glyph fidelity matters, and don't trust tmux-read for the exact contents of a cell that looks wrong — cross-check it against the framebuffer.
• Function keys work directly in tmux send-keys, e.g. tmux send-keys -t pcmos F3 — needed for function-key-driven DOS TUIs like HDSETUP.