From ba18853432d524b4796a0280b1eb259087086fd7 Mon Sep 17 00:00:00 2001
From: retrogcom <retrogcom@users.noreply.github.com>
Date: Thu, 28 May 2026 12:45:13 +0200
Subject: [PATCH 1/3] Add practical MAC + HDLC docs, cross-dev workflow, case
 study, and RE tooling
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Empirically-verified docs from building/running real MAC programs (an HTTP
server over HDLC) on SINTRAN III VSX/500 L under nd100x. Additive; follows
the repo's evidence-tag and See-Also conventions; cross-linked throughout.

New docs:
- Developer/Languages/System/MAC-COOKBOOK.md - @MAC source encoding,
  )9ASSM->NRL build, addressing deref ladder, P-relative/literal-pool rules,
  monitor-call skip-on-success ABI + verified MON table, a "File system
  access from MAC" section, gotcha catalogue, debugging methodology.
- SINTRAN/Devices/HDLC/implementation/Buffer-Pool-and-Emulator-Usage.md -
  buffer-pool setup (CHANGE-BUFFER-SIZE via SINTRAN-SERVICE + RESTART-SYSTEM,
  per COSMOS guide Example 61), D-I-W/D-O-W sizing and status=4, the
  receive-arm-size trap, running HDLC under the nd100x --hdlc tap, and the
  transmitter-restart-after-idle requirement (reload DCB + retrigger).
- Developer/Workflow/CROSS-DEVELOPMENT-WITH-ND100X.md - host-driven build
  loop (encode -> stage into SMD image -> drive @MAC/@NRL over telnet).
- Developer/Case-Studies/HTTP-Server-over-HDLC.md (+ README) - end-to-end
  worked example tying the above together.
- Developer/Reverse-Engineering/ (README + Disassembling-a-PROG.md +
  ND-100-Instruction-Decoding.md) - disassembly workflow + the
  word->mnemonic decode reference, confidence-tagged [V]/[B].
- scripts/nd100_disasm.py + scripts/nd100_brf.py - the disassembler the RE
  docs describe.

Fix to existing doc:
- MAC-DEVELOPER-GUIDE.md Hello World used MONITOR 43 / MONITOR 3; per the
  repo's own MON reference those are CloseFile and the No-Wait switch.
  Corrected to OutString (MON 162B) and ExitFromProgram (MON 0).

All technical claims cross-checked against the repo's own MON reference,
ND-60.096 §2.3 (instruction repertoire incl. JAF=non-zero), and the COSMOS
Operator Guide (CHANGE-BUFFER-SIZE Example 61).

Index/cross-link updates: System README, MAC-DEVELOPER-GUIDE See Also, HDLC
README + raw-guide See Also, Workflow README, Developer README doc map.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .../Case-Studies/HTTP-Server-over-HDLC.md     | 127 +++
 Developer/Case-Studies/README.md              |  30 +
 Developer/Languages/System/MAC-COOKBOOK.md    | 483 ++++++++++++
 .../Languages/System/MAC-DEVELOPER-GUIDE.md   |  17 +-
 Developer/Languages/System/README.md          |  20 +
 Developer/README.md                           |   8 +
 .../Disassembling-a-PROG.md                   | 136 ++++
 .../ND-100-Instruction-Decoding.md            | 190 +++++
 Developer/Reverse-Engineering/README.md       |  39 +
 .../Workflow/CROSS-DEVELOPMENT-WITH-ND100X.md | 158 ++++
 Developer/Workflow/README.md                  |  17 +
 .../HDLC/HDLC-Raw-Programming-Guide.md        |   5 +
 SINTRAN/Devices/HDLC/README.md                |   9 +
 .../Buffer-Pool-and-Emulator-Usage.md         | 227 ++++++
 scripts/nd100_brf.py                          | 458 +++++++++++
 scripts/nd100_disasm.py                       | 729 ++++++++++++++++++
 16 files changed, 2648 insertions(+), 5 deletions(-)
 create mode 100644 Developer/Case-Studies/HTTP-Server-over-HDLC.md
 create mode 100644 Developer/Case-Studies/README.md
 create mode 100644 Developer/Languages/System/MAC-COOKBOOK.md
 create mode 100644 Developer/Reverse-Engineering/Disassembling-a-PROG.md
 create mode 100644 Developer/Reverse-Engineering/ND-100-Instruction-Decoding.md
 create mode 100644 Developer/Reverse-Engineering/README.md
 create mode 100644 Developer/Workflow/CROSS-DEVELOPMENT-WITH-ND100X.md
 create mode 100644 SINTRAN/Devices/HDLC/implementation/Buffer-Pool-and-Emulator-Usage.md
 create mode 100644 scripts/nd100_brf.py
 create mode 100644 scripts/nd100_disasm.py

diff --git a/Developer/Case-Studies/HTTP-Server-over-HDLC.md b/Developer/Case-Studies/HTTP-Server-over-HDLC.md
new file mode 100644
index 00000000..c8b22785
--- /dev/null
+++ b/Developer/Case-Studies/HTTP-Server-over-HDLC.md
@@ -0,0 +1,127 @@
+# Case Study: An HTTP Server on SINTRAN III, over HDLC
+
+**A worked example tying together MAC programming, SINTRAN file I/O, and the
+HDLC device — serving a web page and an image from an ND-100 to a browser.**
+
+This case study is a map, not a code dump: it shows how the pieces
+documented elsewhere in this repo combine into a real, running application,
+and records the design decisions and lessons. Follow the links for the
+how-to detail.
+
+> **Verified** on SINTRAN III VSX/500 L under `nd100x`. Pages and a binary
+> GIF were served to a normal browser, byte-for-byte intact.
+
+---
+
+## Goal
+
+From a browser on a modern laptop, open `http://nd-server/` and get an
+HTML 3.2 page **plus an image**, where the content lives on the ND-100's
+SINTRAN file system and is served by a program running on the ND-100.
+
+## Architecture
+
+```
+ browser ──HTTP──► host bridge ──HDLC frames (TCP tap)──► nd100x ──► MAC server (HSERVI)
+                                                                         │
+                                                          reads files from NDFS (MON 50/117/43)
+```
+
+Three layers:
+
+1. **MAC server on the ND-100** — at startup it opens each file on the
+   SINTRAN disk, reads it into memory, and then drives the HDLC controller to
+   put the bytes on the wire.
+2. **HDLC transport** — the ND's HDLC controller, exposed by the emulator as a
+   TCP "tap."
+3. **Host bridge** — a small program that speaks HTTP to the browser and
+   HDLC frames to the tap, routing each URL to the right bytes.
+
+## How each layer was built
+
+### 1. The MAC server (read files, push frames)
+
+- **Read files from NDFS.** Open with `MON 50` (access = 3, random), pull the
+  whole file in one shot with `MON 117` (block read), close with `MON 43`.
+  `MON 117` is essential here: the simpler sequential `MON 1` is capped at
+  ~456 bytes, too small for a real page. Word counts, access codes, and the
+  high-byte-first packing that lets a **binary GIF round-trip intact** are in
+  the [MAC Cookbook — File system access from MAC](../Languages/System/MAC-COOKBOOK.md#7-file-system-access-from-mac-reading-files-to-serve-them).
+- **Drive HDLC.** Reserve the device, DEVCL + DEVINI, then transmit the cached
+  bytes as frames via `MON 201B`. The API is in the
+  [HDLC Raw Programming Guide](../../SINTRAN/Devices/HDLC/HDLC-Raw-Programming-Guide.md);
+  buffer-pool setup and the receive-arm trap are in
+  [HDLC Buffer-Pool and Emulator Usage](../../SINTRAN/Devices/HDLC/implementation/Buffer-Pool-and-Emulator-Usage.md).
+- The whole program is written and built with the
+  [MAC Cookbook](../Languages/System/MAC-COOKBOOK.md) conventions and the
+  [host cross-development loop](../Workflow/CROSS-DEVELOPMENT-WITH-ND100X.md).
+
+### 2 & 3. Transport and host bridge
+
+- The emulator's `--hdlc=1:<port>` exposes the controller's wire as TCP. The
+  bridge connects there, de-stuffs/decodes HDLC frames the ND sends, and
+  frames/encodes anything it sends back.
+- The bridge serves HTTP to the browser and maps each request path to a slice
+  of the bytes the ND produced (one HTML page, another page, the GIF), setting
+  the right content type.
+
+## Key design decision: broadcast vs request/response
+
+The natural design is request/response: the ND receives the HTTP request,
+reads the requested file, and replies. In our first attempt the reply didn't
+reach the wire — after the receive, a plain send transmitted nothing. The
+cause is a **missing transmitter restart**: a transmitter that has gone idle
+must be explicitly restarted (reload DCB + retrigger) before it sends again;
+TX and RX are independent modules. This restart path is **verified to work
+in the emulator** — SINTRAN's own `XMSG-HDLC-TEST` echo mode does
+receive-then-transmit between two relay-connected nd100x instances (5/5
+frames echoed, 0 errors). So request/response is achievable; our broadcast
+server simply never stops the transmitter, while a request/response server
+must do the restart after each receive. See
+[HDLC Buffer-Pool and Emulator Usage](../../SINTRAN/Devices/HDLC/implementation/Buffer-Pool-and-Emulator-Usage.md#restarting-transmit-after-the-tx-list-drains-incl-after-a-receive).
+
+So the shipping design is **broadcast**: the ND continuously transmits all of
+its cached files (the transmitter never goes idle, so no restart is needed);
+the host bridge captures one full cycle and serves URLs from that capture.
+Trade-offs:
+
+| Model | Status | RAM footprint | Notes |
+|-------|--------|---------------|-------|
+| Broadcast (cache all, stream) | ✅ shipping | all files resident | simplest; transmitter never stops, wire always busy |
+| Request/response (read on demand) | achievable — needs per-receive TX restart (verified via XMSG-HDLC-TEST) | one file at a time | the goal; scales past RAM |
+
+On a 2 MB ND-110 the request/response model also matters for *scale* (you
+can't cache an unbounded site), so it remains the target design — implemented
+with a proper transmitter restart after each receive.
+
+## Lessons worth carrying forward
+
+- **`MON 117`, not `MON 1`, for whole files** — the ~456-byte sequential cap
+  is a wall you will hit immediately on real content.
+- **Binary survives if you don't byte-swap** — `MON 117` packs high-byte-first;
+  emit words high-then-low and a GIF arrives intact. No special binary path.
+- **Size the HDLC receive arm above `FRSIZE`+header** — too small and the
+  driver insta-completes the arm, turning a blocking receive into a busy
+  flood. (Buffer doc §3.)
+- **Enlarge the HDLC buffer pool once, into a base image** — `CHANGE-BUFFER-SIZE`
+  + `@RESTART-SYSTEM` (warm start), then reuse the snapshot. (Buffer doc §1;
+  cross-dev workflow.)
+- **A host bridge is a legitimate architecture** — pushing the HTTP/routing
+  complexity to the host keeps the ND-side MAC program small and within the
+  device's real constraints.
+
+---
+
+## See Also
+
+- **[MAC Cookbook](../Languages/System/MAC-COOKBOOK.md)** — writing/building the MAC server; file I/O.
+- **[HDLC Raw Programming Guide](../../SINTRAN/Devices/HDLC/HDLC-Raw-Programming-Guide.md)** — the MON 201B transmit/receive API.
+- **[HDLC Buffer-Pool and Emulator Usage](../../SINTRAN/Devices/HDLC/implementation/Buffer-Pool-and-Emulator-Usage.md)** — pool setup, receive tuning, the RX→TX caveat.
+- **[Cross-Development with nd100x](../Workflow/CROSS-DEVELOPMENT-WITH-ND100X.md)** — the host build/run loop.
+
+---
+
+*Built and verified on SINTRAN III VSX/500 L under nd100x. Transmit-after-
+receive is a transmitter-restart requirement (reload + retrigger an idled
+TX), verified working in the emulator via XMSG-HDLC-TEST echo mode between
+two relay-connected instances — not an emulator limitation.*
diff --git a/Developer/Case-Studies/README.md b/Developer/Case-Studies/README.md
new file mode 100644
index 00000000..91ca7d12
--- /dev/null
+++ b/Developer/Case-Studies/README.md
@@ -0,0 +1,30 @@
+# Case Studies
+
+End-to-end, worked examples that combine the language, device, and workflow
+guides into a complete, **verified** application on real SINTRAN III under
+`nd100x`. Each case study is a map: it shows how the pieces fit and records
+the design decisions and lessons, linking to the how-to docs for detail.
+
+---
+
+## Case Studies
+
+### [HTTP-Server-over-HDLC.md](HTTP-Server-over-HDLC.md)
+**An HTTP server on SINTRAN III, serving files over HDLC to a browser**
+
+Reads HTML and a binary GIF from the SINTRAN file system in a MAC program,
+puts them on the wire via the HDLC controller, and serves them to a browser
+through a small host bridge.
+
+**Ties together:**
+- [MAC Cookbook](../Languages/System/MAC-COOKBOOK.md) — writing/building the MAC server, SINTRAN file I/O
+- [HDLC Raw Programming Guide](../../SINTRAN/Devices/HDLC/HDLC-Raw-Programming-Guide.md) + [Buffer-Pool and Emulator Usage](../../SINTRAN/Devices/HDLC/implementation/Buffer-Pool-and-Emulator-Usage.md) — the transport
+- [Cross-Development with nd100x](../Workflow/CROSS-DEVELOPMENT-WITH-ND100X.md) — the host build/run loop
+
+**Highlights:** `MON 117` to beat the 456-byte read cap, binary round-trip
+via high-byte-first packing, the broadcast-vs-request/response design
+decision (and the transmitter-restart-after-receive requirement behind it).
+
+---
+
+*Case studies are verified end-to-end on SINTRAN III VSX/500 L under nd100x.*
diff --git a/Developer/Languages/System/MAC-COOKBOOK.md b/Developer/Languages/System/MAC-COOKBOOK.md
new file mode 100644
index 00000000..57b6ab3c
--- /dev/null
+++ b/Developer/Languages/System/MAC-COOKBOOK.md
@@ -0,0 +1,483 @@
+# MAC Cookbook — what actually assembles and runs
+
+**A practitioner's companion to the [MAC Assembler Developer Guide](MAC-DEVELOPER-GUIDE.md).**
+
+Where the developer guide describes the NORD-10/100 MAC *language*, this
+cookbook records what we **empirically verified** while writing and
+running real MAC programs through the **`@MAC` interactive/reentrant
+subsystem** ([ND-60.096](<../../../Reference-Manuals/ND-60.096.01 MAC Interactive Assembly and Debugging System User's Guide.md>))
+on **SINTRAN III VSX/500 L**, assembled with `)9ASSM` and linked with NRL,
+running under the `nd100x` emulator. It is the "what bit us / what works"
+layer: the exact source encoding, the addressing-mode deref ladder, the
+monitor-call calling convention, and a catalogue of the specific errors we
+hit and how we fixed them.
+
+> **Scope note.** Everything here is verified against the *reentrant* `@MAC`
+> subsystem driven from a running SINTRAN III. Some forms shown in the
+> sibling developer guide (e.g. `=N` immediates, `)ENTR`, `MONITOR n`) did
+> **not** assemble in this path; see [§9 Differences we observed](#9-differences-we-observed-from-the-general-reference).
+> Treat the two docs as complementary: language reference vs. verified
+> SINTRAN workflow.
+
+---
+
+## 0. TL;DR — the five things that must be right
+
+A MAC source file fed to `@MAC` will only assemble if **all five** of these
+hold. Get one wrong and you get a misleading cascade of `ILL. CHARACTER` →
+`I/O-ERROR` → `NO SUCH PAGE`, all reported at the location counter, not the
+offending source line.
+
+| # | Property | Value | Why |
+|---|----------|-------|-----|
+| 1 | File type | `:SYMB` | MAC's documented source extension; matches its defaults. |
+| 2 | Line ending | **CR only** (`\r`), no LF | A bare LF (`0x0A`) trips `ILL. CHARACTER`. |
+| 3 | Parity | **even parity on every byte** | `)9PARI` defaults ON; 7-bit-clean fails. |
+| 4 | EOF | **no `\x17`/ETB byte** | ETB (`027`) is rejected as `ILL. CHARACTER` despite the manual. |
+| 5 | Terminator | `)LINE` on its own last line | Switches MAC back to terminal input — the proper end. |
+
+Plus three language facts that cause the most lost time:
+
+- **Numbers are OCTAL by default.** `1361` means `1361₈` (= 753 decimal).
+- **Labels are significant to 5 characters.** Longer labels collide silently.
+- **Monitor calls skip-on-success** (return to PC+2 on success, PC+1 on
+  error) — your control flow must be built around that. See [§6](#6-monitor-calls-mon-n).
+
+---
+
+## 1. The build pipeline (host → SINTRAN → run)
+
+```
+your .SYMB source
+   │  (even parity, CR-only, no ETB)
+   ▼
+@MAC  )9ASSM name:SYMB,0,"name:BRF"   →  name:BRF   (relocatable object)
+   │
+   ▼
+@NRL  PROG-FILE "name" / LOAD name / EXIT   →  name:PROG  (executable)
+   │
+   ▼
+@name      ← run it
+```
+
+Interactive transcript that works:
+
+```
+@MAC
+)9ASSM HELLO:SYMB,0,"HELLO:BRF"     % list=0 → no listing; "..:BRF" creates the file
+)9EXIT
+@NRL
+PROG-FILE "HELLO"
+LOAD HELLO
+EXIT
+@HELLO                               % run
+```
+
+Notes:
+- `list` arg: `0` = null device (silent). Use `TERM` while debugging — MAC
+  then echoes each source line *before* its error, which is the only
+  reliable way to localise a source-level mistake.
+- A **double-quoted** `"name:BRF"` opens-with-create; an unquoted name only
+  opens an existing file.
+- After `)9EXIT`, link with NRL ([ND Relocating Loader](<../../../Reference-Manuals/ND-60.066.04 ND Relocating Loader.md>)).
+- This whole sequence automates cleanly over a telnet connection to
+  SINTRAN; we drive it from Python (boot `nd100x`, log in, stage the
+  even-parity source into the disk image, then send the lines above).
+
+---
+
+## 2. Your first program
+
+```mac
+        )9BEG START      % declare START as the entry point
+START,  MON 0            % MON 0 = ExitFromProgram
+        )9END            % close the BRF program unit
+        )LINE            % terminate source / back to terminal
+```
+
+That assembles to a one-word `:BRF` that NRL turns into a `:PROG` which
+exits cleanly. Four facts already in play:
+
+- `)9BEG <label>` declares the entry point. **Not** `)ENTR` (which errors
+  `WHAT? ENTR` in this subsystem).
+- `)9END` closes the program unit; required before `)LINE`.
+- `MON 0` is the clean exit.
+- Labels end with a comma: `START,`.
+
+## 3. Printing a value (and the marker trick)
+
+`MON 35` (OutNumber) prints the **A** register as a number; **T** selects
+the base: `SAT 10` → octal output, `SAT 12` → decimal output (10₈ and 12₈
+= 8 and 10 decimal — even the *format codes* are octal).
+
+```mac
+        )9BEG START
+START,  SAT  10          % T = 8 → octal output format
+        SAA  5           % A = 5
+        MON  35          % prints "5" — MON 35 does NOT skip-on-success
+        SAT  10
+        SAA  6
+        MON  35          % prints "6"
+        MON  0
+        )9END
+        )LINE
+```
+
+`MON 35` is the workhorse for **debugging by marker**: drop
+`SAT 1; SAA <char>; MON 2` (or `MON 35`) at known points so the terminal
+tells you exactly which code paths executed and in what order. This single
+technique found most of the bugs in [§8](#8-gotcha-catalogue). (`MON 2`
+prints one character — the low byte of A — and *is* privileged; in a
+non-RT user program output still appears but a deferred
+`PRIVILEGED INSTRUCTION` error is logged. For pure diagnostics either is
+fine; for real text output `MON 35`/`MON 162` are safer.)
+
+---
+
+## 4. Numbers, labels, and reserved words
+
+### Numbers are octal
+`SAA 62` loads `62₈` = 50 decimal (ASCII `'2'`). To emit an ASCII marker
+you must convert: ASCII `'2'`..`'9'` = `62₈`..`71₈`, then `':'` = `72₈`,
+`';'` = `73₈`. Decimal `68` is **not** a valid octal literal — digits `8`
+and `9` in an "octal" context silently misassemble. When generating MAC
+from a script, always `format(n, 'o')`.
+
+### Labels: 5 significant characters
+`RDEVNO`, `HDEVNO`, `LDEVNO` all collapse to `DEVNO` and trigger
+`ALREADY DEFINED`. Keep labels unique within their first 5 characters.
+
+### Reserved mnemonics collide with labels
+Instruction and monitor names are reserved; using one as a label fails:
+
+| Wanted label | Collides with | Symptom | Use instead |
+|--------------|---------------|---------|-------------|
+| `COPY` | the `COPY` register-transfer instruction | label silently shadows / `ILL` | `CPYIT` |
+| `WRITE` | reserved mnemonic | `ILL.MNEMONIC` | `WRT` |
+| `CLOSE` | `CLOSE` monitor name | `ALREADY DEFINED CLOSE` | `CLOSEF` |
+
+This bites hardest with **dead code**: an unreferenced label like `ECLOSE`
+still gets defined and still collides. Delete dead labels, don't just stop
+jumping to them.
+
+### Immediates are small and signed
+`SAA n` / `SAT n` take an **8-bit signed** immediate (±127). For anything
+larger, put it in a data word and load it:
+
+```mac
+        LDA  LDNUM        % load a constant > 127 from memory
+        ...
+LDNUM,  1361              % 1361 octal lives here
+```
+
+`=N` and `(N` prefixes on `LDA` (as the general guide shows) **error** in
+this subsystem (`ILL. USE OF COMMAND` / `ILL. CHARACTER`); use a labelled
+data word or the literal-pool form in [§5](#5-addressing--the-deref-ladder).
+
+---
+
+## 5. Addressing & the deref ladder
+
+This is the single biggest source of subtle bugs. The `(LABEL` literal-pool
+form and the `I` indirect flag compose into a "ladder" of dereferences:
+
+| Form | Meaning | A ends up holding |
+|------|---------|-------------------|
+| `LDA (LABEL` | load the **address** of LABEL (from the literal pool) | `&LABEL` |
+| `LDA I (LABEL` | load the **contents** of LABEL | `*(&LABEL)` = `LABEL`'s value |
+| `LDA LABEL` | P-relative direct load | `LABEL`'s value (if in ±range) |
+| `STA I (LABEL` | store A **into** LABEL (via the pool address) | `LABEL := A` |
+| `LDA ,X` | load via the **X register** as an absolute pointer | `*X` |
+| `STA ,B` | store via the **B register** as an absolute pointer | `*B := A` |
+
+**The classic mistake:** `LDA (PARR` where you meant `LDA I (PARR`. The
+first loads the *address* of the parameter list; the second loads the
+*value*. One missing `I` and every dereference is off by one level.
+Likewise, **by-reference parameter-list slots hold ADDRESSES, not values** —
+a slot you "set" must be the address of the cell, and the monitor reads
+through it.
+
+### P-relative range is ±128 words — and the literal pool must be flushed
+P-relative operands (including `JMP LABEL` and `(LABEL` literal refs) reach
+only ±128 words. Two consequences:
+
+1. **Jumps that escape range** silently wrap or mis-target. If a `JMP` to a
+   far label misbehaves at runtime (but assembled fine), suspect range.
+   Restructure so the target is near, or bounce through a nearby trampoline.
+2. **The literal pool needs periodic flushing.** Every `(LABEL` you use is
+   stored in a literal pool that must be emitted within reach. After the
+   last instruction you must add `)FILL`, or you get `)FILL MISSING`. For
+   long routines with many forward `(LABEL` references (more than ~8), you
+   must flush **mid-program** too, or MAC emits range errors
+   (`ERROR 5/14/17/26/31`) — and crucially the `:BRF` may still *build* but
+   then **fault at runtime**. The pattern:
+
+```mac
+        ... code using many (LABEL refs ...
+        JMP  MID          % skip over the pool we are about to dump
+        )FILL             % flush the literal pool here
+MID,    ... more code ...
+```
+
+### Walking memory with X/B
+The register-pointer forms (`LDA ,X` / `STA ,B`) are **absolute** — no
+±128 limit — which is how you copy buffers larger than P-relative reach.
+Increment a pointer register with `COPY`:
+
+```mac
+        LDA  (SRC         % X = &SRC
+        COPY SA DX        %   (A → X)
+        LDA  (DST
+        COPY SA DB        % B = &DST
+        LDA  (71          % counter = 57 decimal (71 octal)
+        STA  I (CNT
+LOOP,   LDA  ,X           % A = *X
+        STA  ,B           % *B = A
+        COPY AD1 SX DX    % X++  (add-1, source X, dest X)
+        COPY AD1 SB DB    % B++
+        LDA  I (CNT
+        SUB  (1
+        STA  I (CNT
+        JAZ  DONE         % JAZ = jump if A zero
+        JMP  LOOP
+DONE,   ...
+```
+
+`COPY AD1 S<reg> D<reg>` is the idiomatic register increment; `COPY SA DX`
+moves A→X, `COPY SX DA` moves X→A, etc.
+
+---
+
+## 6. Monitor calls (`MON n`)
+
+The SINTRAN monitor-call ABI, as we exercised it (see also
+[ND MON Calls](<../../MON/ND MON Calls.md>) and
+[ND-860228 SINTRAN III Monitor Calls](<../../../Reference-Manuals/ND-860228-2-EN SINTRAN III Monitor Calls.md>)):
+
+- **Most calls take a parameter list by reference.** Load the *address* of
+  the param list into A (`LDA (PARM`), then `MON n`. Each slot in the list
+  is itself usually an **address** of the actual argument cell.
+- **Skip-on-success.** On success the monitor returns to **PC+2** (it skips
+  the next word); on error it returns to **PC+1**. So the instruction
+  immediately after `MON n` is the **error path**, and the one after that
+  is the **success path**. The idiom is a single jump as the "skip slot":
+
+```mac
+        LDA  (PARM
+        MON  50           % OpenFile
+        JMP  EOPEN        % ← executed ONLY on error (PC+1)
+        STA  FILNO        % ← success continues here (PC+2)
+```
+
+  For an unconditional continue after success, use the **convergent jump**:
+  put `JMP TARGET` twice, so both the success-skip and the explicit jump
+  land on `TARGET`.
+
+  **Exception:** some simple-return monitors do **not** skip — notably
+  `MON 35`, which just falls through. Don't leave a skip slot after those.
+
+- **Error codes print in octal.** A returned `-10B` is `-8` decimal
+  ("Illegal function"). Read monitor errors as octal.
+- **`MON 35` is special:** it uses the **T and A registers directly** (T =
+  format, A = number), *not* a parameter list.
+- Test A with `JAZ` (jump if A = 0), `JAF` (jump if A **non-zero**), `JAP`
+  (A ≥ 0), `JAN` (A < 0). *(JAF = "jump if A Filled" = non-zero — per
+  ND-60.096 §2.3; a common error-check idiom since a 0/negative return makes
+  JAF branch exactly on the non-zero error.)*
+
+### Monitors we used (verified)
+
+| MON | Name | Args | Notes |
+|-----|------|------|-------|
+| `0` | ExitFromProgram | — | clean exit; last instruction |
+| `1` | InByte (sequential read) | param list | capped ~456 bytes by an internal buffer — see below |
+| `2` | OutByte | A = byte | privileged; works for diagnostics, logs deferred error in user mode |
+| `35` | OutNumber | T=format, A=number | no skip; T=`10`→octal, `12`→decimal |
+| `43` | CloseFile | T = file number | |
+| `50` | OpenFile | X=&name, A=&type, T=access | access 1=seq read, 2=random R/W, 3=random read-only |
+| `74` | SetStartByte | param list | position within an open file |
+| `117` | ReadFromFile (random/block) | param list | **bypasses the MON 1 ~456-byte cap**; reads whole blocks; count is in **words** |
+| `122` | Reserve device | param list | reserve a logical device (e.g. an HDLC LDN) before use |
+| `201` | HDLCfunction | param list | full HDLC send/receive/init; heavily used — see the HDLC docs |
+
+The **MON 1 vs MON 117** distinction matters: sequential `MON 1` is limited
+by an internal ~456-byte buffer (tied to `CHANGE-BUFFER-SIZE`), so to read a
+larger file in one shot, open with access=3 and use `MON 117` with a word
+count. (`RFCNT` is a *word* count: `1000₈` = 512 words = 1024 bytes.)
+
+---
+
+## 7. File system access from MAC (reading files to serve them)
+
+This is the file-I/O surface we used to read HTML/GIF files off the SINTRAN
+disk and serve them — the recipe for any MAC program that reads stored
+files. All of it is plain SINTRAN monitor calls; nothing HDLC-specific.
+
+### The calls and their registers
+
+| MON | Name | Inputs | Returns |
+|-----|------|--------|---------|
+| `50` | OpenFile | `X = &name`, `A = &type`, `T = access code` | `A = file number` (save it) |
+| `1` | InByte (sequential) | param list / open file | next byte; **capped ~456 bytes per buffer** |
+| `117` | ReadFromFile (random/block) | param list (see below) | reads N **words** into a buffer; **no 456-byte cap** |
+| `74` | SetStartByte | param list | repositions the file pointer for sequential I/O |
+| `43` | CloseFile | `T = file number` | — |
+
+### Access codes (the `T` value passed to MON 50)
+
+| Access | Meaning | Notes |
+|--------|---------|-------|
+| `1` | sequential read | works with `MON 1`; subject to the ~456-byte buffer |
+| `2` | random read/write | |
+| `3` | random read-only | **required for `MON 117`** block reads |
+
+A filename/type is a packed character literal: `FILNA, 'INDEX'` and
+`FILTY, 'HTML'`. Names are significant to the usual SINTRAN limits — keep
+them short (we hit failures with 6-char names where 5 worked).
+
+### Why MON 117, not MON 1 — the 456-byte wall
+
+**[VERIFIED]** Sequential `MON 1` reads through an internal buffer that caps
+a single read at roughly **456 bytes** (tied to `CHANGE-BUFFER-SIZE`). For
+anything larger — a full HTML page, a GIF — that wall forces awkward
+chunking. **`MON 117` reads whole blocks directly and has no such cap**, so
+it is the right call for "load a file into memory in one shot." Two details:
+
+- Open with **access = 3** (random read-only); `MON 117` requires it.
+- `RFCNT` is a **word** count, not bytes: `1000₈` = 512 words = 1024 bytes.
+
+### The recipe: open → block-read → close
+
+```mac
+LOAD,   SAT  3                  % access = 3 (random, read-only) — required for MON 117
+        LDX  (FILNA             % X = &filename
+        LDA  (FILTY             % A = &filetype
+        MON  50                 % OpenFile
+        JMP  EOPEN              % error path (PC+1)
+        STA  FILNO              % success: save returned file number
+        LDA  (RFPAR             % A = &MON-117 parameter list
+        MON  117                % ReadFromFile (block)
+        JAF  EREAD              % JAF = jump if A non-zero (MON 117 left a non-zero error) → read error
+        LDT  FILNO
+        MON  43                 % CloseFile (T = file number)
+        JMP  ECLOSE             % error path
+        ...                     % success: file now in FILEBUF
+
+% MON 117 parameter list — each slot is an ADDRESS (by reference),
+% except the buffer slot which IS the buffer's address.
+RFPAR,  FILNO; RFWAIT; FILEBUF; RFBLK; RFCNT
+RFWAIT, 0                       % 0 = wait until complete
+RFBLK,  0                       % start block (0 = beginning)
+RFCNT,  1000                    % 1000 octal = 512 words = 1024 bytes
+FILNA,  'INDEX'
+FILTY,  'HTML'
+FILNO,  0
+FILEBUF, 0; 0; 0 ...            % buffer, sized to the read (in words)
+```
+
+### Bytes inside words (matters for binary files)
+
+`MON 117` packs file bytes into 16-bit words **high byte first**: file byte
+0 is the high byte of word 0, byte 1 the low byte, and so on. When you later
+emit those words (e.g. over HDLC) high-byte-then-low-byte, the on-wire byte
+stream matches the original file order — so **binary files (GIF, etc.)
+round-trip intact** with no special handling. Just don't byte-swap.
+
+### Serving several files
+
+To serve more than one file, repeat **open → MON 117 → close** per file into
+**separate buffer regions** (one slot per file), then keep the buffers
+resident. Each `MON 117` reuses the same parameter-list shape with a
+different name/type and a different buffer address. Memory is the limit:
+on a 2 MB ND-110 you cannot cache an unbounded set, so a large site wants a
+rotation that reads one file at a time from disk rather than caching all of
+them at once.
+
+> Complete, runnable versions live in the project's `mac-programs/` set
+> (`hfile-mon117.mac` for the block read; the HDLC server programs combine
+> this with transmit). For the file-serving-over-HDLC application — buffer
+> pool setup, the receive-arm trap, running under nd100x — see
+> **[HDLC Buffer-Pool and Emulator Usage](../../../SINTRAN/Devices/HDLC/implementation/Buffer-Pool-and-Emulator-Usage.md)**.
+
+---
+
+## 8. Gotcha catalogue
+
+Every entry here cost real debugging time. Symptom → cause → fix.
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| `ILL. CHARACTER` cascade, points at location counter not source | LF in line endings, or an ETB (`\x17`) EOF byte, or odd parity | CR-only, even parity, no ETB; end with `)LINE` |
+| `)FILL MISSING` | used `(LABEL` literals but never flushed the pool | add `)FILL` after the last instruction |
+| `ERROR 5/14/17/26/31`, or builds but **faults at runtime** | literal pool / P-relative reference out of ±128 range | flush the pool mid-program (`JMP MID; )FILL; MID,`); keep jumps near |
+| `ALREADY DEFINED <X>` | two labels share their first 5 chars, **or** a label equals a reserved mnemonic/monitor name (incl. dead code) | rename to a unique ≤5-char non-reserved label; delete dead labels |
+| `WHAT? ENTR` | used `)ENTR` for the entry point | use `)9BEG <label>` |
+| `ILL. USE OF COMMAND` / `ILL. CHARACTER` on a load | used `=N` or `(N` immediate forms | use `SAA`/`SAT` (±127) or a labelled data word |
+| value wrong by a factor / nonsense address | forgot the `I` — `LDA (X)` (address) vs `LDA I (X)` (value) | add the `I` for the value; one deref level per `I` |
+| marker bytes print as wrong glyphs (`8`, `9`, `!`) | decimal literal where MAC expects octal | emit octal (`format(n,'o')`); remember default base is octal |
+| program runs the error path even though the call worked | mis-applied skip-on-success (or left a skip slot after `MON 35`) | error path is PC+1, success PC+2; `MON 35` does not skip |
+| reading a file truncates near ~456 bytes | `MON 1` sequential read hits the internal buffer cap | open access=3 and use `MON 117` (word count) |
+| `STA I (CELL)` seems to corrupt a nearby variable | wrote past a buffer because the counter/loop ran one extra iteration | re-check the `JAZ`/decrement order; the test is *before* the next write |
+
+---
+
+## 9. Differences we observed from the general reference
+
+The sibling [MAC-DEVELOPER-GUIDE.md](MAC-DEVELOPER-GUIDE.md) documents the
+broad NORD-10/100 MAC language. In the **reentrant `@MAC` subsystem on
+SINTRAN III VSX/500 L** we drive, these specific forms behaved differently —
+recorded here so the two docs don't quietly contradict each other:
+
+| General guide shows | In `@MAC` (verified) | Use |
+|---------------------|----------------------|-----|
+| `=100` immediate (`LDA =100`) | errors `ILL. USE OF COMMAND` | `SAA`/`SAT` (±127), or a labelled data word |
+| `)ENTR START` | errors `WHAT? ENTR` | `)9BEG START` |
+| `MONITOR 43` / `MONITOR 3` | not the form used | `MON n`; exit is `MON 0` |
+| `JSR` / `JMP I 0` subroutine return | not exercised here | we used straight-line + `JMP` flow; verify before relying on `JSR` |
+
+These may reflect a different MAC variant/version than the one resident at
+segment 134B on our SINTRAN. The point isn't that either doc is "wrong" —
+it's that **if you're building through `@MAC` + `)9ASSM` on SINTRAN III,
+the right-hand column is what assembles.**
+
+---
+
+## 10. Debugging methodology
+
+When a MAC program assembles but misbehaves at runtime, in order of payoff:
+
+1. **Marker prints.** Insert `SAT 1; SAA <ascii>; MON 2` (or `MON 35`) at
+   each milestone. The terminal output becomes an execution trace —
+   e.g. `ABCDEFG` tells you which phases ran and where it stopped. This is
+   the fastest, most reliable tool; reach for it first.
+2. **Assemble with `list = TERM`.** MAC echoes each source line before its
+   diagnostics, which is the only dependable way to map an error back to a
+   source line (error addresses are location-counter-relative, not line
+   numbers).
+3. **Disassemble the `:PROG`/`:BRF`.** Cross-check the generated code and
+   addressing against intent (the project ships disassembly tooling; the
+   PROG/BRF format is documented under Reference-Manuals).
+4. **Read the device/emulator logs.** For I/O (HDLC, disk), the `nd100x`
+   logs show every IOX register access and DMA command, which pins down
+   whether the chip saw what you intended.
+
+---
+
+## See Also
+
+- **[MAC-DEVELOPER-GUIDE.md](MAC-DEVELOPER-GUIDE.md)** — the MAC language reference (syntax, addressing, directives, macros).
+- **[ND-60.096 MAC Interactive Assembly and Debugging System User's Guide](<../../../Reference-Manuals/ND-60.096.01 MAC Interactive Assembly and Debugging System User's Guide.md>)** — the authoritative `@MAC` subsystem manual.
+- **[ND-60.113 Assembler Reference Manual](<../../../Reference-Manuals/ND-60.113.02 EN Assembler Reference Manual.md>)** — instruction set reference.
+- **[ND-860228 SINTRAN III Monitor Calls](<../../../Reference-Manuals/ND-860228-2-EN SINTRAN III Monitor Calls.md>)** and **[ND MON Calls](<../../MON/ND MON Calls.md>)** — the monitor-call catalogue.
+- **[ND-60.066 ND Relocating Loader](<../../../Reference-Manuals/ND-60.066.04 ND Relocating Loader.md>)** — NRL linking.
+- **[LINKING-GUIDE.md](../../Workflow/LINKING-GUIDE.md)** — build/link workflow.
+- **[HDLC Raw Programming Guide](../../../SINTRAN/Devices/HDLC/HDLC-Raw-Programming-Guide.md)** — programming the HDLC device (MON 201B, DCBs) — the natural next step once you can write MAC.
+- **[HDLC Buffer-Pool and Emulator Usage](../../../SINTRAN/Devices/HDLC/implementation/Buffer-Pool-and-Emulator-Usage.md)** — buffer setup, receive tuning, and running HDLC under nd100x.
+
+---
+
+*This cookbook is empirical: every claim was observed while building and
+running MAC programs through `@MAC` on SINTRAN III VSX/500 L under nd100x.
+Where it disagrees with a manual, it is reporting what the live system did —
+please verify on your own configuration before treating any single item as
+universal.*
diff --git a/Developer/Languages/System/MAC-DEVELOPER-GUIDE.md b/Developer/Languages/System/MAC-DEVELOPER-GUIDE.md
index c8dad5ad..7ed4498d 100644
--- a/Developer/Languages/System/MAC-DEVELOPER-GUIDE.md
+++ b/Developer/Languages/System/MAC-DEVELOPER-GUIDE.md
@@ -530,11 +530,9 @@ SIZE, END-START          % Relocatable - relocatable = absolute
 ```mac
 % Hello World in pure MAC
 
-START,  LDA =43               % WRTSW monitor call
-        LDT I (MSG)           % Message address
-        MONITOR 43            % Write string
-        LDA =3                % EXIT monitor call
-        MONITOR 3             % Exit program
+START,  LDT I (MSG)           % Message address
+        MONITOR 162           % OutString - write the message (MON 162B)
+        MONITOR 0             % ExitFromProgram
 
 MSG,    'HELLO FROM MAC!'
         15, 12                % CR, LF
@@ -542,6 +540,14 @@ MSG,    'HELLO FROM MAC!'
         )ENTR START
 ```
 
+> **Monitor numbers corrected.** Earlier drafts of this example used
+> `MONITOR 43` for "write string" and `MONITOR 3` for "exit"; per the
+> repo's own monitor-call reference those are **CloseFile** (43) and the
+> **No-Wait switch** (3). String output is **OutString = MON 162B** and
+> program exit is **ExitFromProgram = MON 0**. (For the `@MAC` *reentrant*
+> subsystem the mnemonic is `MON n`, not `MONITOR n` — see the
+> [MAC Cookbook](MAC-COOKBOOK.md).)
+
 ### 9.2 Subroutine
 
 ```mac
@@ -794,6 +800,7 @@ ROUTINE, LDA LOCAL
 
 ## See Also
 
+- **[MAC-COOKBOOK.md](MAC-COOKBOOK.md)** - Practitioner's companion: what actually assembles and runs through `@MAC` on SINTRAN III (verified source encoding, addressing deref ladder, monitor-call ABI, gotcha catalogue)
 - **[NPL-DEVELOPER-GUIDE.md](NPL-DEVELOPER-GUIDE.md)** - NPL language guide
 - **[LINKING-GUIDE.md](../../Workflow/LINKING-GUIDE.md)** - NRL linker guide
 - **[QUICK-START-EXAMPLES.md](../../QUICK-START-EXAMPLES.md)** - Hello World examples
diff --git a/Developer/Languages/System/README.md b/Developer/Languages/System/README.md
index c1d5ce81..3b44b431 100644
--- a/Developer/Languages/System/README.md
+++ b/Developer/Languages/System/README.md
@@ -55,6 +55,26 @@ Low-level assembly language for NORD-100 computers.
 
 ---
 
+### [MAC-COOKBOOK.md](MAC-COOKBOOK.md)
+**MAC Practitioner's Cookbook**
+
+The empirically-verified companion to the MAC guide: what actually assembles and runs through the `@MAC` reentrant subsystem on SINTRAN III VSX/500 L (built with `)9ASSM` + NRL, run under nd100x).
+
+**Covers:**
+- The exact source encoding that `@MAC` accepts (`:SYMB`, CR-only, even parity, `)LINE`)
+- Build pipeline: `)9ASSM` → NRL → run
+- The addressing deref ladder (`LDA (` vs `LDA I (`), P-relative ±128 limit, literal-pool flushing
+- The monitor-call ABI (skip-on-success convention, by-reference param lists)
+- A gotcha catalogue (symptom → cause → fix) and a debugging methodology
+- Differences observed vs. the general language reference
+
+**Use Cases:**
+- Getting a first MAC program to assemble and run on SINTRAN III
+- Debugging "assembled fine but faults at runtime" issues
+- Onboarding (AI or human) to practical ND MAC coding
+
+---
+
 ### [NORD-500-ASSEMBLER-DEVELOPER-GUIDE.md](NORD-500-ASSEMBLER-DEVELOPER-GUIDE.md)
 **NORD-500 Assembler**
 
diff --git a/Developer/README.md b/Developer/README.md
index 7f73fba9..d6f1b9d4 100644
--- a/Developer/README.md
+++ b/Developer/README.md
@@ -71,8 +71,16 @@ Developer/
 │   ├── COMPILER-COMMANDS-REFERENCE.md
 │   ├── LINKING-GUIDE.md
 │   ├── SCRIPT-GUIDE.md
+│   ├── CROSS-DEVELOPMENT-WITH-ND100X.md
 │   └── TOOLS-REFERENCE.md
 │
+├── Case-Studies/ (End-to-end worked examples)
+│   └── HTTP-Server-over-HDLC.md
+│
+├── Reverse-Engineering/ (Disassembly + binary RE)
+│   ├── Disassembling-a-PROG.md
+│   └── ND-100-Instruction-Decoding.md
+│
 ├── Editors/ (Text editor guides)
 │   ├── EDITORS-GUIDE.md
 │   ├── QED-QUICK-REFERENCE.md
diff --git a/Developer/Reverse-Engineering/Disassembling-a-PROG.md b/Developer/Reverse-Engineering/Disassembling-a-PROG.md
new file mode 100644
index 00000000..17d80c97
--- /dev/null
+++ b/Developer/Reverse-Engineering/Disassembling-a-PROG.md
@@ -0,0 +1,136 @@
+# Disassembling and Reverse-Engineering a SINTRAN `:PROG`
+
+**A practical workflow for taking a built `:PROG` (or `:BRF`) apart and
+understanding it — when you have the binary but not the source.**
+
+This is the approach we used to verify our own programs and to understand
+others. It pairs with two references: the
+**[ND-100 Instruction Decoding](ND-100-Instruction-Decoding.md)** table
+(word → mnemonic) and the
+**[:PROG File Format Reference](../../SINTRAN/File-Formats/PROG-FILE-FORMAT.md)**
+(the container). Where the decode table is the *what*, this is the *how*.
+
+> Verified against real SINTRAN `:PROG` files (HTTP server, ping, XMSG
+> test) under nd100x / SINTRAN III VSX/500 L.
+
+---
+
+## 1. Get the bytes and find the memory image
+
+A `:PROG` is a 256-byte header followed by the program's memory image as
+big-endian 16-bit words: **memory address 0 lives at file offset `0x100`**.
+So the first thing to read is the header (end address, entry/marker fields —
+see the format reference), then treat everything from `0x100` on as words at
+ascending addresses.
+
+For a `:BRF` (relocatable object, pre-link) the layout differs — it carries
+relocation/definition records. The most useful thing a `:BRF` gives you for
+RE is the **set of relocated slots**: those are pointer cells whose values
+are addresses, which seed control-flow discovery (below).
+
+## 2. Find the entry point(s)
+
+- The header's entry/start field is the primary entry.
+- In MAC source the entry is declared with `)9BEG <label>`; in the binary
+  it's just the address execution begins at.
+- Additional entry points show up as the **targets of relocated pointer
+  slots** (from the `:BRF`) and as jump/call targets you discover while
+  tracing.
+
+## 3. Separate code from data (don't disassemble strings)
+
+Blindly disassembling every word produces garbage over data regions. Two
+reliable separators:
+
+- **Reachability trace.** Start from the entry point(s), follow straight-line
+  flow, jumps, and conditional branches, and mark every reachable word as
+  code. Everything unreached is data (or unreachable code). This alone
+  cleans up most output.
+- **Printable-ASCII heuristic.** A window where >~85% of bytes are printable
+  (or CR/LF/TAB/NUL) is almost certainly a string/message region — skip it.
+
+Our disassembler does both: a forward trace from the entries (seeded with
+`:BRF` relocation targets when available) plus the ASCII heuristic, then only
+disassembles the reachable, non-text words.
+
+## 4. Decode the words
+
+Apply the [instruction decoding table](ND-100-Instruction-Decoding.md) in its
+disambiguation order. Things that make the output readable:
+
+- **Resolve P-relative targets** to labels: a memory-ref/jump in P-rel or
+  indirect-P-rel mode points to `PC + signed8(disp)`; name those addresses
+  `Lnnnnnn` and back-substitute so jumps read as `JMP LOOP` not `JMP 0o…`.
+- **Annotate `MON n`** with the monitor name (see
+  [ND MON Calls](../MON/ND MON Calls.md)) — `MON 0o50 (OpenFile)` tells you
+  far more than the number.
+- **Recognise the patterns** from the cookbook: a `MON` followed by a `JMP`
+  is the skip-on-success error path, not a bug; a block of `.WORD` after a
+  `)FILL`-terminated routine is the **literal pool** (addresses for `(LABEL`
+  operands), not code.
+
+## 5. Reconstruct intent
+
+With code separated and decoded, the structure usually falls out:
+
+- **MON-call sites** tell you what the program *does* (file I/O via
+  50/117/43, device I/O via 122/201, output via 2/35/162, exit via 0).
+- **The literal pool + addressing modes** reveal the data the routine touches
+  (each `(LABEL` is a pool entry pointing at a variable/buffer/param-list).
+- **Param lists** for monitor calls are contiguous data words holding
+  addresses — find the `LDA (PARM; MON n` and read `PARM`'s words as the
+  call's arguments (each a by-reference address). This is how you recover,
+  e.g., an `OpenFile` filename/type or a `ReadFromFile` block/count.
+
+## 6. Improve the disassembler as you go
+
+Reverse-engineering and tooling co-evolve: every time a real program reveals
+a mnemonic, addressing form, or MON number the decoder got wrong, fold the
+correction back into the decode table. The well-verified families
+(memory-reference, jumps, arguments, MON, IOX, addressing modes) got that way
+by being checked against real `:PROG` output; the **[B]**-tagged families in
+the decode reference are the ones still worth hardening against ND-60.096
+§2.3 the next time you meet them in the wild.
+
+---
+
+## Tooling
+
+This workflow is implemented as a Python disassembler shipped in this repo:
+**[`scripts/nd100_disasm.py`](../../scripts/nd100_disasm.py)** (with
+**[`scripts/nd100_brf.py`](../../scripts/nd100_brf.py)** for the optional
+`--brf` relocation seeding). It parses the `:PROG` header, runs the
+reachability trace, applies the decode table, resolves P-relative labels, and
+annotates MON calls. The decode logic in
+[ND-100 Instruction Decoding](ND-100-Instruction-Decoding.md) is exactly that
+tool's table — keep them in sync.
+
+```bash
+# Inspect the header
+python scripts/nd100_disasm.py MYPROG.PROG --header
+
+# Disassemble, following control flow from the entry point (cleaner output)
+python scripts/nd100_disasm.py MYPROG.PROG --trace 0
+
+# Seed the trace from a matching :BRF's relocations (finds more code)
+python scripts/nd100_disasm.py MYPROG.PROG --brf MYPROG.BRF
+
+# Annotate addresses with your own symbol file (addr name per line)
+python scripts/nd100_disasm.py MYPROG.PROG --sym MYPROG.sym
+```
+
+Stdlib-only (Python 3.10+); `--brf` is the sole inter-module dependency.
+
+---
+
+## See Also
+
+- **[ND-100 Instruction Decoding](ND-100-Instruction-Decoding.md)** — the word → mnemonic table.
+- **[:PROG File Format Reference](../../SINTRAN/File-Formats/PROG-FILE-FORMAT.md)** — header + memory image container.
+- **[MAC Cookbook](../Languages/System/MAC-COOKBOOK.md)** — the assembly side; addressing deref ladder, MON ABI, literal pool.
+- **[ND-60.096 §2.3](<../../Reference-Manuals/ND-60.096.01 MAC Interactive Assembly and Debugging System User's Guide.md>)** — authoritative instruction repertoire.
+
+---
+
+*Workflow verified reverse-engineering real SINTRAN `:PROG` files; the decode
+table it relies on was hardened against that same set of programs.*
diff --git a/Developer/Reverse-Engineering/ND-100-Instruction-Decoding.md b/Developer/Reverse-Engineering/ND-100-Instruction-Decoding.md
new file mode 100644
index 00000000..3290e3f1
--- /dev/null
+++ b/Developer/Reverse-Engineering/ND-100-Instruction-Decoding.md
@@ -0,0 +1,190 @@
+# ND-100 Instruction Decoding (Disassembly Reference)
+
+**How to decode a 16-bit ND-100 / ND-110 instruction word back to a
+mnemonic — the inverse of MAC assembly.**
+
+This is the decode table behind a working disassembler we built and ran
+against real SINTRAN `:PROG` files (an HTTP server, ping, XMSG test). The
+authoritative instruction repertoire is
+**[ND-60.096 §2.3](<../../Reference-Manuals/ND-60.096.01 MAC Interactive Assembly and Debugging System User's Guide.md>)
+(NORD-10 Instruction Repertoire)** — the ND-100 is binary-compatible with
+NORD-10/S at the user-mode ISA level SINTRAN programs use; see also
+**[ND-60.113 Assembler Reference Manual](<../../Reference-Manuals/ND-60.113.02 EN Assembler Reference Manual.md>)**.
+For the *file container* (header, memory image), see the repo's
+**[:PROG File Format Reference](../../SINTRAN/File-Formats/PROG-FILE-FORMAT.md)**.
+
+> **Confidence tags:** **[V]** verified by disassembling real `:PROG` files
+> and matching the source; **[B]** best-effort (the manual's tables for this
+> family are inconsistent — cross-check against ND-60.096 before relying on
+> it). Numbers are **octal** (MAC convention) unless prefixed `0x`.
+
+---
+
+## Words and addresses
+
+- An instruction is **one 16-bit word**, stored **big-endian** in the file.
+- In a `:PROG`, the 256-byte header is followed by the memory image; **memory
+  address 0 = file offset `0x100`**. Word at address *a* is at byte
+  `0x100 + a*2`. (Header fields: see the file-format reference.)
+- Memory-reference and jump displacements are **signed 8-bit** (−128..+127),
+  added to the current address (P-relative). Argument immediates are signed
+  8-bit. Shift counts are signed 7-bit.
+
+---
+
+## Decode order (disambiguation)
+
+Families overlap in the opcode space, so decode in this order (this is the
+order the disassembler uses, and it resolves the overlaps):
+
+1. `0` → data word `ZERO`.
+2. **MON**: `(w & 0xFF00) == 0xD600` → `MON n`, `n = w & 0xFF`. **[V]**
+3. **IOX**: `(w & 0o174000) == 0o164000` → `IOX <w & 0o3777>`. **[V]**
+4. **Byte ops**: `SBYT = 0o142600`, `LBYT = 0o142200`. **[V]**
+5. **Conditional jumps**: `(w & 0o174000) == 0o130000` (see table). **[V]**
+6. **Memory-reference** (incl. `JMP`/`JPL`): top 5 bits in the MEM table. **[V]**
+7. **Argument instructions**: `(w & 0o177400)` in the ARG table. **[V]**
+8. **Shift**: `(w & 0o174000) == 0o154000`. **[B]**
+9. **Privileged / system** (IOF/ION/WAIT/TRA/…). **[B]**
+10. **Bit instructions**: `(w & 0o174000) == 0o174000`. **[B]**
+11. **Skip** (`SKP`) then **register-ops**: `(w & 0o170000) == 0o140000`. **[B]**
+12. Else `.WORD <w>` (data).
+
+---
+
+## Memory-reference instructions  **[V]**
+
+Format: `op(bits 15-11) | mode(bits 10-8) | disp(bits 7-0, signed)`.
+
+| Opcode (octal) | Mnem | | Opcode | Mnem | | Opcode | Mnem |
+|---|---|---|---|---|---|---|---|
+| `004000` | STA | | `044000` | LDA | | `064000` | SUB |
+| `000000` | STZ | | `050000` | LDT | | `070000` | AND |
+| `010000` | STT | | `054000` | LDX | | `074000` | ORA |
+| `014000` | STX | | `060000` | ADD | | `120000` | MPY |
+| `020000` | STD | | `024000` | LDD | | `124000` | JMP |
+| `030000` | STF | | `034000` | LDF | | `134000` | JPL |
+| `040000` | MIN | | | | | | |
+| `100000` | FAD | | `104000` | FSB | | `110000` | FMU |
+| `114000` | FDV | | | | | | |
+
+### Addressing modes (bits 10-8 = `w & 0o3400`)  **[V]**
+
+| `w & 0o3400` | Syntax | Effective address |
+|---|---|---|
+| `0o0000` | `<disp>` (P-rel) | `PC + disp` |
+| `0o0400` | `<disp>,B` | `B + disp` |
+| `0o1000` | `I <disp>` | `*(PC + disp)` (indirect P-rel) |
+| `0o1400` | `I <disp>,B` | `*(B + disp)` |
+| `0o2000` | `<disp>,X` | `X + disp` |
+| `0o2400` | `<disp>,B,X` | `B + X + disp` |
+| `0o3000` | `I <disp>,X` | `*(PC + disp) + X` |
+| `0o3400` | `I <disp>,B,X` | `*(B + disp) + X` |
+
+Only P-rel and indirect-P-rel resolve to a static target when disassembling;
+B/X modes depend on runtime register values. (This is exactly the
+"deref ladder" from the [MAC Cookbook](../Languages/System/MAC-COOKBOOK.md#5-addressing--the-deref-ladder),
+seen from the decode side.)
+
+## Conditional jumps  **[V]**
+
+Base `0o130000`, condition in bits 10-8, signed-8 displacement (P-rel).
+
+| Code | Mnem | meaning |
+|---|---|---|
+| `130000` | JAP | jump if A ≥ 0 |
+| `130400` | JAN | jump if A < 0 |
+| `131000` | JAZ | jump if A = 0 |
+| `131400` | JAF | jump if A ≠ 0 |
+| `132000` | JPC | jump if X-count positive (and increment) |
+| `132400` | JNC | jump if X-count negative (and increment) |
+| `133000` | JXZ | jump if X = 0 |
+| `133400` | JXN | jump if X < 0 |
+
+## Argument instructions  **[V]**
+
+Base in bits 15-8, signed-8 immediate in bits 7-0.
+
+| Code | Mnem | | Code | Mnem |
+|---|---|---|---|---|
+| `170000` | SAB | | `172000` | AAB |
+| `170400` | SAA | | `172400` | AAA |
+| `171000` | SAT | | `173000` | AAT |
+| `171400` | SAX | | `173400` | AAX |
+
+`SAx` = set register to immediate; `AAx` = add immediate to register
+(B/A/T/X). Immediate range ±127 — the cookbook's "immediates are small and
+signed" rule, confirmed from the encoding.
+
+## MON and IOX  **[V]**
+
+- **`MON n`**: `0xD600 | n` (i.e. `0o153000 + n`); `n` is the octal monitor
+  number. Full name table in the disassembler and in
+  [ND MON Calls](../MON/ND MON Calls.md) — e.g. `0o0` ExitFromProgram,
+  `0o2` OutByte, `0o35` OutNumber, `0o43` CloseFile, `0o50` OpenFile,
+  `0o117` ReadFromFile, `0o122` ReserveResource, `0o201` HDLCfunction.
+- **`IOX <dev>`**: `(w & 0o174000) == 0o164000`, device/function in
+  `w & 0o3777`. (Raw I/O — e.g. direct HDLC register pokes.)
+
+## Register operations  **[B]**
+
+`(w & 0o170000) == 0o140000`. Format `1100 | QC | IC | R | source(5-3) | dest(2-0)`
+with AD1/ADC/CLD/CM1/CM2 modifier bits. Source/destination register maps:
+
+| `src (bits 5-3)` | name | | `dst (bits 2-0)` | name |
+|---|---|---|---|---|
+| `0o00` | 0 | | `0o0` | STS |
+| `0o10` | SD | | `0o1` | DD |
+| `0o20` | SP | | `0o2` | DP |
+| `0o30` | SB | | `0o3` | DB |
+| `0o40` | SL | | `0o4` | DL |
+| `0o50` | SA | | `0o5` | DA |
+| `0o60` | ST | | `0o6` | DT |
+| `0o70` | SX | | `0o7` | DX |
+
+Base ops by `w & 0o7700`: `RADD 0o6000`, `COPY 0o6100`, `RSUB 0o6600`,
+`SWAP 0o4000`, `RAND 0o4400`, `REXO 0o5000`, `RORA 0o5400`. Common combined
+forms: `EXIT = 0o146142` (COPY SL DP), `RCLR = 0o146100`, `RINC = 0o146400`,
+`RDCR = 0o146200`. Modifier-bit decoding is the inconsistent part — verify
+against ND-60.096 §2.3.5 before trusting a modified form.
+
+## Other families (summarised)  **[B]**
+
+- **Skip** `SKP <cond> <sr> <dr>`: `0o140000` with cond in bits 10-8
+  (`EQL/GRE/MGRE/UEQ/LST/MLST`) and the RAD/QC/IC fields zero.
+- **Shift** `0o154000` family: target `SHT/SHD/SHA/SAD` (bits 8-7), mode
+  `ARITH/ROT/ZIN/LIN` (bits 10-9), signed-7 count (negative = right).
+- **Bit** `0o174000` family: `BSET/BSKP/BSTC/BSTA/BLDA/BANC/BAND/BORC/BORA`
+  with condition `ZRO/ONE/BCM/BAC`. *(Manual tables inconsistent — [B].)*
+- **Privileged/system**: `IOF 0o150401`, `ION 0o150402`, `POF 0o150404`,
+  `PON 0o150410`, `WAIT 0o151000+n`, `IDENT 0o143600`, and register-coded
+  `TRA/TRR/MCL/MST 0o1501xx/0o1502xx/0o1503xx`, `IRR 0o153400+`, `IRW
+  0o153600+`. Many are RT/privileged and won't appear in user-mode programs.
+
+---
+
+## Worth knowing when reading disassembly
+
+- **Literal pool**: blocks of `.WORD` after a routine are usually the literal
+  pool (addresses for `(LABEL` operands) — not code. A run of high-entropy
+  words right after a `)FILL`-terminated routine is the giveaway.
+- **MON-call skip slots**: after a `MON n` the next word is the error path and
+  the one after is the success path (skip-on-success) — so a `JMP`
+  immediately after a `MON` is normal control flow, not dead code.
+- **Text/data vs code**: a window where most bytes are printable ASCII is a
+  string/data region; don't disassemble it. (The disassembler's reachability
+  trace and an ">85% printable" heuristic separate the two.)
+
+---
+
+## See Also
+
+- **[Disassembling a :PROG](Disassembling-a-PROG.md)** — the practical RE workflow that uses this table.
+- **[:PROG File Format Reference](../../SINTRAN/File-Formats/PROG-FILE-FORMAT.md)** — the container around the memory image.
+- **[ND-60.096 §2.3](<../../Reference-Manuals/ND-60.096.01 MAC Interactive Assembly and Debugging System User's Guide.md>)** — authoritative NORD-10 instruction repertoire.
+- **[MAC Cookbook](../Languages/System/MAC-COOKBOOK.md)** — the assembly side (addressing deref ladder, MON ABI).
+
+---
+
+*Decode tables come from a disassembler verified against real SINTRAN
+`:PROG` files; [B]-tagged families need a cross-check against ND-60.096 §2.3.*
diff --git a/Developer/Reverse-Engineering/README.md b/Developer/Reverse-Engineering/README.md
new file mode 100644
index 00000000..e61d0a45
--- /dev/null
+++ b/Developer/Reverse-Engineering/README.md
@@ -0,0 +1,39 @@
+# Reverse Engineering ND-100 Programs
+
+Taking a built SINTRAN program apart — decoding `:PROG`/`:BRF` binaries back
+to instructions and reconstructing intent — when you have the binary but not
+the source. The inverse of the [MAC](../Languages/System/MAC-DEVELOPER-GUIDE.md)
+assembly workflow.
+
+---
+
+## Documents
+
+### [Disassembling-a-PROG.md](Disassembling-a-PROG.md)
+**The practical RE workflow**
+
+Get the memory image, find entry points, separate code from data (reachability
+trace + ASCII heuristic), decode, resolve P-relative labels, annotate MON
+calls, and reconstruct intent from MON-call sites + literal pool + param lists.
+
+### [ND-100-Instruction-Decoding.md](ND-100-Instruction-Decoding.md)
+**The decode reference: 16-bit word → mnemonic**
+
+Opcode families (memory-reference, conditional jumps, argument, register-ops,
+shift, bit, privileged), the 8 addressing modes, source/destination register
+maps, and MON/IOX detection. Derived from a disassembler verified against real
+`:PROG` files; confidence-tagged **[V]**/**[B]**. Complements
+[ND-60.096 §2.3](<../../Reference-Manuals/ND-60.096.01 MAC Interactive Assembly and Debugging System User's Guide.md>)
+(authoritative repertoire).
+
+---
+
+## Related
+
+- **[:PROG File Format Reference](../../SINTRAN/File-Formats/PROG-FILE-FORMAT.md)** — the binary container (header + memory image).
+- **[MAC Cookbook](../Languages/System/MAC-COOKBOOK.md)** — the assembly side (addressing, MON ABI, literal pool).
+- **[ND MON Calls](../MON/ND MON Calls.md)** — monitor-call numbers to annotate `MON n` sites.
+
+---
+
+*Verified against real SINTRAN `:PROG` files under nd100x.*
diff --git a/Developer/Workflow/CROSS-DEVELOPMENT-WITH-ND100X.md b/Developer/Workflow/CROSS-DEVELOPMENT-WITH-ND100X.md
new file mode 100644
index 00000000..8601ac6a
--- /dev/null
+++ b/Developer/Workflow/CROSS-DEVELOPMENT-WITH-ND100X.md
@@ -0,0 +1,158 @@
+# Cross-Development: Building SINTRAN Programs from a Modern Host with nd100x
+
+**How to edit, assemble, link, and run ND-100 / SINTRAN III programs from a
+modern PC, driving the `nd100x` emulator — no hand-typing source on the
+target.**
+
+This is the loop we used to build and iterate on real MAC programs (an HTTP
+server) hundreds of times. The existing [Scripting Guide](SCRIPT-GUIDE.md)
+covers automation *inside* SINTRAN (MODE files); this document covers the
+*host* side: getting your source into the emulated machine, building it, and
+capturing output, all from outside.
+
+> **Verified** against `nd100x` + SINTRAN III VSX/500 L on an SMD disk image.
+> The mechanics are emulator-/host-agnostic; we automated them in Python, but
+> nothing here depends on a particular language.
+
+---
+
+## The loop at a glance
+
+```
+edit source on host
+   │  (encode correctly + stage into the disk image)
+   ▼
+boot nd100x with the image
+   │
+   ▼
+drive @MAC / @NRL over the telnet console
+   │
+   ▼
+run the program, capture console + device output
+   │
+   └─► repeat (re-stage source, re-boot or re-run)
+```
+
+Two host-side capabilities make this work: **(1)** writing files into the
+SINTRAN disk image with the correct on-disk encoding, and **(2)** driving the
+SINTRAN console over TCP (telnet). Everything else is orchestration.
+
+---
+
+## 1. Encode the source the way SINTRAN expects
+
+A source file you stage into the image must match what the target subsystem
+reads. For **MAC** (`:SYMB`) the rules are strict — get them wrong and you
+get a misleading `ILL. CHARACTER` cascade:
+
+- **CR-only** line endings (`\r`), never LF.
+- **Even parity** on every byte.
+- **No ETB/`\x17`** end-of-file byte; terminate with `)LINE`.
+- File type **`:SYMB`**.
+
+Full detail and the per-language variations are in the
+[MAC Cookbook §0–1](../Languages/System/MAC-COOKBOOK.md). Other subsystems
+(PLANC, NPL, BASIC) have their own line-ending / EOF conventions — encode to
+match the one you are feeding.
+
+## 2. Stage the file into the SMD disk image
+
+You cannot just drop bytes into the image at an arbitrary offset — SINTRAN's
+file system needs a real directory entry with correct invariants. The
+reliable pattern is **let SINTRAN allocate, then fill from the host**:
+
+1. Boot the image and, on the SINTRAN console, **`@CREATE-FILE name:type,pages`**
+   so SINTRAN creates the directory entry and pre-allocates pages.
+2. Shut the emulator down.
+3. From the host, **write your (correctly-encoded) bytes into the file's
+   allocated pages** using a tool that understands the on-disk file system,
+   and patch the bytes-used / last-write-date / modified flag so SINTRAN sees
+   a valid file.
+
+This "create on target, fill from host" split avoids re-deriving every
+directory-entry invariant. (We implemented step 3 in Python against the disk
+image; any tool that reads/writes the SINTRAN FS format works.)
+
+## 3. Boot nd100x
+
+```
+nd100x --boot=smd --smd0=<image.IMG> --telnet=<port> [--hdlc=1:<tcp-port>] [--max-instr=<N>]
+```
+
+- `--boot=smd --smd0=<image>` — boot from the SMD disk image.
+- `--telnet=<port>` — expose the SINTRAN console on `127.0.0.1:<port>`; connect
+  a TCP/telnet client to drive it.
+- `--hdlc=1:<tcp-port>` — (optional) attach HDLC controller 1 and serve its
+  wire on a TCP socket; see
+  [HDLC Buffer-Pool and Emulator Usage](../../SINTRAN/Devices/HDLC/implementation/Buffer-Pool-and-Emulator-Usage.md).
+- `--max-instr=<N>` — instruction budget; set high for long-running servers.
+
+## 4. Drive the build over the console
+
+Connect to the telnet port, log in, then send the build sequence as if typing
+it. For MAC:
+
+```
+@MAC
+)9ASSM <name>:SYMB,0,"<name>:BRF"     % list=0 silent; "..:BRF" creates the object
+)9EXIT
+@NRL
+PROG-FILE "<name>"
+LOAD <name>
+EXIT
+@<name>                                % run it
+```
+
+Practical tips:
+- Drive it as a **send-line / read-until-quiet** exchange: send a command,
+  read console output until it goes idle, then send the next. SINTRAN echoes
+  and prompts (`@`, `*`) tell you where you are.
+- For debugging an assembly error, use `)9ASSM ...,TERM,...` so MAC echoes each
+  source line before its diagnostics (error addresses are location-counter
+  relative, not line numbers — see the cookbook's debugging section).
+- Build the linker step (`@NRL`) only after `)9EXIT` returns to `@`.
+
+## 5. Run and capture output
+
+- **Console output** comes back on the telnet stream. Marker prints
+  (`SAT 1; SAA <char>; MON 2`) are the fastest execution trace — see the
+  cookbook's debugging methodology.
+- **Device output** (HDLC, etc.) comes back on that device's tap (e.g. the
+  `--hdlc` TCP socket). Drive and verify it with a host-side client.
+- The emulator's own logs (when enabled) show IOX register accesses and DMA
+  commands — invaluable for I/O debugging.
+
+---
+
+## A reusable base image saves time
+
+Some target state is expensive to set up every run (e.g. enlarging the HDLC
+driver buffers needs `CHANGE-BUFFER-SIZE` + an `@RESTART-SYSTEM` warm start —
+see the HDLC buffer doc). Do that **once**, snapshot the resulting image as a
+**permanent base**,
+and start each build by copying the base. Your per-build script then only
+stages source and builds, never re-does the one-time setup.
+
+---
+
+## Why bother (vs editing on the target)
+
+- **Real editor + version control** for your source on the host.
+- **Reproducible, scriptable** build/run — essential for iterating quickly or
+  for CI-style regression runs.
+- **Programmatic verification** — assert on console/device output instead of
+  eyeballing a terminal.
+
+---
+
+## See Also
+
+- **[MAC Cookbook](../Languages/System/MAC-COOKBOOK.md)** — source encoding, the `)9ASSM`→NRL build, monitor-call ABI, file I/O.
+- **[Scripting and Automation Guide](SCRIPT-GUIDE.md)** — automation *inside* SINTRAN (MODE files).
+- **[Linking Guide](LINKING-GUIDE.md)** — NRL details.
+- **[HDLC Buffer-Pool and Emulator Usage](../../SINTRAN/Devices/HDLC/implementation/Buffer-Pool-and-Emulator-Usage.md)** — the `--hdlc` tap, buffer setup, running HDLC apps under nd100x.
+
+---
+
+*Workflow verified while cross-developing MAC programs for SINTRAN III
+VSX/500 L on nd100x from a Windows host.*
diff --git a/Developer/Workflow/README.md b/Developer/Workflow/README.md
index 132e80bf..d38722b5 100644
--- a/Developer/Workflow/README.md
+++ b/Developer/Workflow/README.md
@@ -115,6 +115,23 @@ Automate your development workflow with MODE scripts.
 
 ---
 
+### [CROSS-DEVELOPMENT-WITH-ND100X.md](CROSS-DEVELOPMENT-WITH-ND100X.md)
+**Host-Driven Cross-Development with the nd100x Emulator**
+
+Build, link, and run SINTRAN programs from a modern PC instead of typing source on the target. (SCRIPT-GUIDE automates *inside* SINTRAN; this is the *host* side.)
+
+**Contents:**
+- The edit → stage → boot → drive → run loop
+- Source encoding for the target (CR-only, even parity, `:SYMB`)
+- Staging files into the SMD disk image (create on target, fill from host)
+- `nd100x` invocation flags (`--boot=smd`, `--smd0`, `--telnet`, `--hdlc`, `--max-instr`)
+- Driving `@MAC`/`@NRL` over the telnet console; capturing console + device output
+- Reusable base images for expensive one-time setup
+
+**Verified** building MAC programs for SINTRAN III VSX/500 L under nd100x.
+
+---
+
 ### [TOOLS-REFERENCE.md](TOOLS-REFERENCE.md)
 **Complete Development Tools Reference**
 
diff --git a/SINTRAN/Devices/HDLC/HDLC-Raw-Programming-Guide.md b/SINTRAN/Devices/HDLC/HDLC-Raw-Programming-Guide.md
index 74ba03a0..f0e08270 100644
--- a/SINTRAN/Devices/HDLC/HDLC-Raw-Programming-Guide.md
+++ b/SINTRAN/Devices/HDLC/HDLC-Raw-Programming-Guide.md
@@ -2379,3 +2379,8 @@ entire system.
 | PLANC Reference Manual | ND-60.117.5 EN | -- | PLANC language specification |
 | HDLC Driver Source | MP-P2-HDLC-DRIV.NPL | -- | SINTRAN HDLC driver (626 lines) |
 | COM5025 Datasheet | SMC/AMD | -- | Multi-Protocol Communications Controller |
+
+## See Also
+
+- **[Buffer-Pool and Emulator Usage](implementation/Buffer-Pool-and-Emulator-Usage.md)** — operational layer around this API: `CHANGE-BUFFER-SIZE` buffer setup, pool sizing (D-I-W/D-O-W), the receive-arm trap (undersized arm → flood), and running/testing HDLC under nd100x.
+- **[MAC Cookbook](../../../Developer/Languages/System/MAC-COOKBOOK.md)** — writing the MAC program that issues these monitor calls (source encoding, the monitor-call skip-on-success ABI, file I/O).
diff --git a/SINTRAN/Devices/HDLC/README.md b/SINTRAN/Devices/HDLC/README.md
index 94b12fc2..04b90c9e 100644
--- a/SINTRAN/Devices/HDLC/README.md
+++ b/SINTRAN/Devices/HDLC/README.md
@@ -26,6 +26,14 @@
 5. [Testing Scenarios](implementation/Testing-Scenarios.md) - Test your implementation
 6. [Debugging Guide](implementation/Debugging-Guide.md) - Troubleshoot issues
 
+### 🛠️ I'm Writing a Program That Uses HDLC
+**Start here if**: You want to send/receive HDLC frames from your own SINTRAN program (and run it under nd100x).
+
+⚙️ **Your Path**:
+1. [HDLC Raw Programming Guide](HDLC-Raw-Programming-Guide.md) - MON 201B API, DCB layout, send/receive flow
+2. [Buffer-Pool and Emulator Usage](implementation/Buffer-Pool-and-Emulator-Usage.md) - `CHANGE-BUFFER-SIZE` setup, pool sizing, the receive-arm trap, running under nd100x
+3. [MAC Cookbook](../../../Developer/Languages/System/MAC-COOKBOOK.md) - writing the MAC program itself (source encoding, monitor-call ABI, file I/O)
+
 ### 🔍 I'm Debugging an Existing System
 **Start here if**: Something isn't working and you need to figure out why.
 
@@ -76,6 +84,7 @@
 | Document | Description | Lines |
 |----------|-------------|-------|
 | [Emulator-Implementation-Guide.md](implementation/Emulator-Implementation-Guide.md) | Complete emulator development guide | ~800 |
+| [Buffer-Pool-and-Emulator-Usage.md](implementation/Buffer-Pool-and-Emulator-Usage.md) | Buffer setup (`CHANGE-BUFFER-SIZE`), pool sizing, receive-arm tuning, running HDLC apps under nd100x | ~230 |
 | [Testing-Scenarios.md](implementation/Testing-Scenarios.md) | Comprehensive test cases | ~400 |
 | [Debugging-Guide.md](implementation/Debugging-Guide.md) | Troubleshooting and debugging strategies | ~450 |
 
diff --git a/SINTRAN/Devices/HDLC/implementation/Buffer-Pool-and-Emulator-Usage.md b/SINTRAN/Devices/HDLC/implementation/Buffer-Pool-and-Emulator-Usage.md
new file mode 100644
index 00000000..4e45f2f8
--- /dev/null
+++ b/SINTRAN/Devices/HDLC/implementation/Buffer-Pool-and-Emulator-Usage.md
@@ -0,0 +1,227 @@
+# HDLC Buffer-Pool Setup, Receive Tuning, and Running Under nd100x
+
+**Operational companion to the [HDLC Raw Programming Guide](../HDLC-Raw-Programming-Guide.md).**
+
+The raw programming guide covers the MON 201B API, DCB layout, and
+send/receive flow. This document covers the **operational layer around it**
+that we had to get right to run a real, sustained HDLC application
+(an HTTP server) on SINTRAN III VSX/500 L under the `nd100x` emulator:
+
+1. Enlarging the driver buffer pool with `CHANGE-BUFFER-SIZE` (a one-time
+   SINTRAN setup that is otherwise easy to miss).
+2. Sizing the pool: how D-I-W, D-O-W, and the per-buffer max size relate,
+   and what `status = 4` ("no buffer") really means.
+3. The receive arm-size trap: an undersized receive buffer makes the
+   driver *complete the arm immediately*, which turns a blocking receive
+   into a busy flood.
+4. Running and testing HDLC under `nd100x` (the `--hdlc` TCP tap), plus one
+   emulator-specific caveat to be aware of.
+
+> **Evidence tags** follow the repo convention: **[VERIFIED]** = observed
+> directly in our runs; **[OBSERVED-nd100x]** = observed under the emulator
+> and may differ on real hardware; **[FROM-MANUAL]** = stated in an ND
+> manual in this repo.
+
+**LDN convention used throughout:** `1360` = HDLC1 **input**, `1361` =
+HDLC1 **output** (the first HDLC controller). Adjust for other units.
+
+---
+
+## 1. Enlarge the buffer pool first: `CHANGE-BUFFER-SIZE`
+
+**[VERIFIED]** Out of the box, the HDLC logical devices have a small driver
+buffer allocation, and a stock image will silently fail to sustain real
+traffic (transfers abort before your program does useful work). The pool
+must be enlarged **once** and the system restarted so SINTRAN reallocates.
+
+**[FROM-MANUAL]** Per the
+[COSMOS Operator Guide ND-30.025.02](<../../../../Operations/Cosmos/ND-30.025.02 COSMOS Operator Guide.md>)
+§8.4.2 ("Example 61. Changing the HDLC Buffer Size"), use
+`@SINTRAN-SERVICE` — **one LDN per line**, comma-separated — then a
+**`@RESTART-SYSTEM` warm start** (not a cold boot). The guide's example
+tests HDLC2 (LDNs 1362/1363) and notes: *"replace 1362 and 1363 with
+n, n+1"* for another link, so for HDLC1 use 1360/1361:
+
+```
+@SINTRAN-SERVICE
+*CHANGE-BUFFER-SIZE,1360,L,400,Y,N
+*CHANGE-BUFFER-SIZE,1361,0,400,Y,N
+*EXIT
+@RESTART-SYSTEM
+```
+
+- one line per LDN (the link's `n` and `n+1`); the third field follows the
+  manual's pattern (`L` on the first LDN, `0` on the second).
+- `400` is the buffer size; this is the cap the pool math in §2 must respect.
+- `@RESTART-SYSTEM` is a **warm start** — the manual states it is needed
+  "to allow SINTRAN to reallocate the buffers." The allocation is
+  established at restart, not live.
+
+> If you skip this step, the most common symptom is that the first transfer
+> after reservation returns a buffer-related error (`status = 4`, see §2)
+> even though your DCBs look correct.
+
+> **Note on exact syntax.** The form above is transcribed from the COSMOS
+> guide (Example 61). An older note of ours used a different spelling
+> (`*CHANGE-BUFFER-SIZE 1360/1361,INPUT/OUTPUT,400,Y,Y` + cold boot); treat
+> the manual's comma form + `RESTART-SYSTEM` as authoritative and verify
+> against your SINTRAN version's `SINTRAN-SERVICE` help if it differs.
+
+---
+
+## 2. Pool sizing: D-I-W, D-O-W, and `status = 4`
+
+The driver keeps a **finite pool of fixed-size buffers** shared by the
+in-flight transfers. Two configuration counts govern how many buffers are
+reserved:
+
+| Term | Meaning |
+|------|---------|
+| **D-I-W** (Driver Input Wait) | number of concurrent **input** (receive) buffers the driver pre-allocates |
+| **D-O-W** (Driver Output Wait) | number of concurrent **output** (transmit) buffers |
+
+**[OBSERVED-nd100x]** A usable rule of thumb for the per-LDN pool:
+
+```
+pool_words  >=  (D-I-W + D-O-W) x (per_buffer_max + overhead)
+```
+
+with the per-buffer max bounded by the `CHANGE-BUFFER-SIZE` value (§1, `400`
+octal). Concretely, with **D-I-W = 4** a per-buffer max of about **50**
+(`MRX = 50`) keeps the total within the `400` cap; pushing the per-buffer
+max up to the full `400` while also holding several buffers exhausts the
+pool. **D-I-W = 4** is the default that works on `nd100x`.
+
+**`status = 4` ("No buffer available")** — documented in the raw guide's
+status table — is **pool exhaustion**, *not* a queue-depth limit. It means
+the driver could not get a free buffer for your DCB. Causes, in order of
+likelihood:
+
+1. The pool was never enlarged (§1).
+2. The per-buffer max times (D-I-W + D-O-W) exceeds the pool (this section).
+3. Frames are arriving faster than your program retrieves them, so the
+   receive pool drains (see the raw guide's buffer-exhaustion flow).
+
+See also: [Register-Reference](../reference/Register-Reference.md),
+[HDLC Raw Programming Guide §6](../HDLC-Raw-Programming-Guide.md) (queuing
+and buffer exhaustion).
+
+---
+
+## 3. The receive arm-size trap (blocking receive turns into a flood)
+
+This one cost real time, so it is worth stating plainly.
+
+When you use the **arm-then-collect** receive model (post an empty receive
+DCB to arm the line, then collect the filled DCB — the multi-buffer DMA
+queue model in the raw guide), the **maximum-size field on the arm must be
+large enough to hold a frame**, specifically larger than the input
+`FRSIZE` plus the channel header. If it is too small:
+
+**[OBSERVED-nd100x]** the driver **completes the armed buffer immediately**
+instead of waiting for data. A program that then loops "collect → process →
+re-arm" never blocks — it spins, and on the wire this manifests as the
+transmitter **flooding** (the serve loop runs continuously because the
+receive never actually waits).
+
+What we found works for small request frames (e.g. an 8-byte `GET /`):
+
+| Field | Bad (insta-completes) | Good (blocks correctly) |
+|-------|----------------------|--------------------------|
+| input `FRSIZE` | `200` oct (128 dec) | `40` oct (32 dec) — fine for tiny requests |
+| arm max-size (`MRX`/MSize) | `10` oct (too small) | `100` oct (64 dec), > FRSIZE+header |
+| recv collect size (`USize`) | `10` oct | `100` oct |
+
+Keep the arm max-size **above `FRSIZE` + header but small enough that
+`(D-I-W + D-O-W) x max-size` still fits the pool** (§2). Those two
+constraints together are the whole trick.
+
+> Note the raw guide also documents a **simpler single-call receive** where
+> the MSize parameter is the *wait flag* (`1` = block, `0` = poll). That is
+> a different model from the arm-then-collect queue above; this section is
+> about the queue model's arm step. See
+> [HDLC Raw Programming Guide §6.11](../HDLC-Raw-Programming-Guide.md).
+
+---
+
+## 4. Running and testing HDLC under nd100x
+
+**[OBSERVED-nd100x]** The emulator exposes an HDLC controller's wire as a
+**TCP socket** (a "tap"). Launch with:
+
+```
+nd100x --boot=smd --smd0=<image> --telnet=<port> --hdlc=1:<tcp-port>
+```
+
+- `--hdlc=1:<tcp-port>` attaches HDLC controller **1** and serves its wire
+  on `127.0.0.1:<tcp-port>`.
+- Connect a TCP client to that port to act as the **far end**: bytes the ND
+  transmits arrive as bytes on the socket; bytes you write to the socket are
+  delivered to the ND as a received frame.
+- Frames on the tap are real HDLC: `7E` flag, address, control, payload,
+  FCS, `7E` flag, with byte-stuffing. A host-side decoder/encoder
+  (de-stuff on read, frame on write) is all you need to drive it.
+
+Minimal test pattern we used:
+
+1. Boot the image, log in over `--telnet`, start your MAC HDLC program.
+2. Connect to the `--hdlc` TCP port.
+3. To test **transmit**: read the socket and decode frames the ND sends.
+4. To test **receive**: write one framed payload (e.g.
+   `7E 03 03 <bytes> <FCS> 7E`) to the socket and confirm your program's
+   `FRCV` returns.
+
+### Restarting transmit after the TX list drains (incl. after a receive)
+
+**TX and RX are independent modules** and run independently. When a module
+stops because its DCB list has been consumed, **it must be restarted by
+loading fresh DCBs and triggering start again**. A continuously-running
+stream (e.g. a broadcast loop) never stops, so it never needs the restart;
+a stop/idle period — including the gap after a receive — does.
+
+**[VERIFIED-nd100x] The emulator fully supports receive-then-transmit.** We
+confirmed it with SINTRAN's own `XMSG-HDLC-TEST` (COSMOS guide §8.4.3) run
+across **two nd100x instances** whose `--hdlc` taps were bridged by a TCP
+relay: the **echo end** (`Loop on interface? N`, then `ECHO-MODE`) received
+each frame and transmitted it back, and the **send end** (`SEND 5`) reported
+`5 sent / 5 received / 0 errors`, with bidirectional traffic on the relay
+(≈670 bytes each way). So RX→TX is **not** an emulator limitation.
+
+A naive request/response server of ours *did* stall on the RX→TX turn — but
+the cause was on our side: after the receive we issued a bare send **without
+the explicit transmitter restart** (reload DCB + retrigger) that `ECHO-MODE`
+performs. A broadcast design never stops the transmitter and so avoids the
+issue; **a request/response design must restart the transmitter after each
+receive**, exactly as XMSG-HDLC-TEST's echo mode does (and which the
+emulator handles correctly).
+
+---
+
+## 5. Putting it together — checklist for a sustained HDLC app
+
+1. **[ ]** `CHANGE-BUFFER-SIZE` both LDNs via `@SINTRAN-SERVICE` + `@RESTART-SYSTEM` warm start (§1).
+2. **[ ]** Choose D-I-W / D-O-W and a per-buffer max that fit the pool (§2).
+3. **[ ]** Reserve the LDNs (`MON 122B`), then DEVCL + DEVINI before any
+   TRANS DCB (see raw guide); the input LDN arms only when the first empty
+   receive DCB is posted.
+4. **[ ]** Size the receive arm above `FRSIZE` + header so receive actually
+   blocks (§3).
+5. **[ ]** Under nd100x, drive/verify over the `--hdlc` TCP tap (§4); watch
+   for the RX→TX caveat.
+
+---
+
+## See Also
+
+- **[HDLC Raw Programming Guide](../HDLC-Raw-Programming-Guide.md)** — the MON 201B API, DCB layout, send/receive flow, queuing.
+- **[Register Reference](../reference/Register-Reference.md)** — FRSIZE, RRTS/RTTS, WRTC/WTTC bit definitions.
+- **[Debugging Guide](Debugging-Guide.md)** — general HDLC troubleshooting.
+- **[COSMOS Operator Guide ND-30.025.02](<../../../../Operations/Cosmos/ND-30.025.02 COSMOS Operator Guide.md>)** — `CHANGE-BUFFER-SIZE` and operator commands.
+- **[MAC Cookbook](../../../../Developer/Languages/System/MAC-COOKBOOK.md)** — writing the MAC program that drives all of the above (source encoding, monitor-call ABI, file I/O).
+
+---
+
+*Operational notes verified while building an HTTP server over HDLC on
+SINTRAN III VSX/500 L under nd100x. Items tagged **[OBSERVED-nd100x]** were
+seen under the emulator; confirm on your hardware/build before treating as
+universal.*
diff --git a/scripts/nd100_brf.py b/scripts/nd100_brf.py
new file mode 100644
index 00000000..76f54c54
--- /dev/null
+++ b/scripts/nd100_brf.py
@@ -0,0 +1,458 @@
+"""ND BRF (Binary Relocatable Format) parser.
+
+Reads :BRF files emitted by MAC / FORTRAN / PLANC / etc., and produces:
+  - A relocation map: {memory_addr: "LF" | "LR" | "AFF" | "ARF" | "AFR" | "ARR"}
+  - The symbol table (MAIN, ENTR, LIBR, REF — start address, named entries, refs)
+  - The list of program units (each BEG...END pair, with its program base)
+  - Real-time priority and other metadata
+
+This unlocks BRF-aware disassembly: words tagged as `LR` are POINTERS that
+the loader patches with the program base at load time. They look like data
+in the PROG but are actually function/jump-table entries.
+
+Reference: ND-60.066.04 ND Relocating Loader §2.1–2.9.
+
+BRF byte stream syntax (sequence of "groups"):
+
+  <control_byte>                       — 0 args (FEED, BEG, INHB, EOF)
+  <control_byte><P-group>              — 1 P-group (LF, LR, LC, SFL, AFL, SRL, END, LNF, RT)
+  <control_byte><P-group><P-group>     — 2 P-groups (AFF, ARF, AFR, ARR)
+  <control_byte><S-group>              — 1 S-group (4 or 6 bytes)
+  <control_byte><S-group><P-group>     — S+P (MAIN, LIBR, ENTR, REF, ASF, ADS)
+
+A P-group is one 16-bit word, big-endian, 2 bytes.
+An S-group is a packed symbol — 4 bytes default, 6 bytes if LONGF flag set.
+
+Usage:
+  python nd100_brf.py PROG.bin --brf PROG.brf       # cross-reference
+  python nd100_brf.py PROG.brf                       # parse only
+
+Output: prints the relocation map and symbol table to stdout.
+"""
+from __future__ import annotations
+import argparse
+import sys
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+# --- Control-byte constants (octal, per ND-60.066.04 §2.9) ---
+CB_FEED = 0o0    # skip / padding
+CB_LF   = 0o1    # load value (1 word, no reloc)
+CB_LR   = 0o2    # load relocated (W + PB) — addresses
+CB_LC   = 0o3    # load common-relative (W + CDB)
+CB_AFF  = 0o4    # fix-up: W1 + (W2) -> (W2)
+CB_ARF  = 0o5    # fix-up: W1 + PB + (W2) -> (W2)
+CB_AFR  = 0o6    # fix-up: W1 + (W2+PB) -> (W2+PB)
+CB_ARR  = 0o7    # fix-up: W1 + PB + (W2+PB) -> (W2+PB)
+CB_SFL  = 0o10   # set CLC := W1
+CB_AFL  = 0o11   # CLC += W1, fill zeros
+CB_SRL  = 0o12   # CLC := W1 + PB
+# 0o13 not used
+CB_MAIN = 0o14   # S-group + P: main entry
+CB_LIBR = 0o15   # S-group + P: library subprogram
+CB_ENTR = 0o16   # S-group + P: entry point
+CB_BEG  = 0o17   # start of program unit, CLC -> PB
+CB_REF  = 0o20   # S-group + P: external reference
+CB_END  = 0o21   # end of unit + checksum
+CB_INHB = 0o22   # compilation errors flag (no args)
+CB_EOF  = 0o23   # end of loading (no args)
+CB_LNF  = 0o24   # 1+W1: load W1 words
+CB_RT   = 0o25   # RT priority (1 word)
+CB_ASF  = 0o26   # COMMON block (S+P)
+CB_ADS  = 0o27   # add common (S only)
+CB_LONGF = 0o32  # set 6-byte S-group mode for the rest of the unit
+
+# --- CC-100 (ND-100 C compiler) BRF extensions ---
+# Reverse-engineered 2026-05-25 from CAT.C → CAT.BRF correlation, then extended
+# by inspecting the C runtime libraries (CC-{1,2}BANK/HEADER/TRAILER-A.BRF).
+# Standard BRF only defines control bytes 0o0-0o27 + 0o32. CC-100 adds:
+CB_CC_STRSEG_BEG = 0o51   # marker: begin string-data segment (no args)
+CB_CC_STRSEG_END = 0o50   # marker: end string-data segment (no args)
+CB_CC_REFFIX_A   = 0o52   # REF fix-up sub-marker, 1 P-group arg
+CB_CC_REFFIX_B   = 0o53   # REF fix-up sub-marker (different flavor), 1 P-group arg
+# C runtime BRFs (CC-{1,2}{HEADER,TRAILER,BANK}-A.BRF) use additional bytes:
+CB_CC_RT54       = 0o54   # observed in CC-{1,2}HEADER preamble; 1 P-group?
+CB_CC_RT60       = 0o60   # also HEADER preamble
+# Plus various high-byte ones (0o113-0o324 range) that appear preceding REF
+# symbols within the runtime. Likely fix-up records with multi-byte arg
+# encoding we haven't fully decoded; the parser falls through to "skip
+# unknown" for these and the parse still produces useful output.
+
+CONTROL_NAMES = {
+    CB_FEED: "FEED", CB_LF: "LF", CB_LR: "LR", CB_LC: "LC",
+    CB_AFF: "AFF", CB_ARF: "ARF", CB_AFR: "AFR", CB_ARR: "ARR",
+    CB_SFL: "SFL", CB_AFL: "AFL", CB_SRL: "SRL",
+    CB_MAIN: "MAIN", CB_LIBR: "LIBR", CB_ENTR: "ENTR",
+    CB_BEG: "BEG", CB_REF: "REF", CB_END: "END",
+    CB_INHB: "INHB", CB_EOF: "EOF", CB_LNF: "LNF",
+    CB_RT: "RT", CB_ASF: "ASF", CB_ADS: "ADS",
+    CB_LONGF: "LONGF",
+    CB_CC_STRSEG_BEG: "CC.STRBEG", CB_CC_STRSEG_END: "CC.STREND",
+    CB_CC_REFFIX_A:   "CC.REFA",   CB_CC_REFFIX_B:   "CC.REFB",
+}
+
+
+# --- Symbol decoding (Radix-50 family, MAC manual §3.2.2 / §D.3) ---
+# 6-bit characters packed: 'A'-'Z'=1-26, '0'-'9'=27-36, etc.
+# 4-byte S-group = 4 chars; 6-byte = 6 chars (with LONGF).
+def decode_symbol_packed(buf: bytes) -> str:
+    """Decode an S-group as packed ASCII (often 4 right-padded bytes)."""
+    # Many ND BRFs use 4 chars of plain ASCII rather than radix-50.
+    # We attempt ASCII decoding; if non-printable, fall back to hex.
+    if all(32 <= b < 127 or b == 0 for b in buf):
+        return buf.decode("ascii", errors="replace").rstrip("\x00 ")
+    return "0x" + buf.hex()
+
+
+# --- Data classes ---
+
+@dataclass
+class Reloc:
+    """One memory-location reloc/load entry."""
+    addr: int           # memory address (in words) where loaded
+    kind: str           # "LF", "LR", "LC", "ARF", etc.
+    value: int          # raw P-group word value (pre-relocation)
+    unit: int = 0       # which program unit it's in
+
+
+@dataclass
+class Symbol:
+    name: str
+    kind: str           # MAIN | ENTR | LIBR | REF
+    addr: int           # address of the entry (or referencing location for REF)
+
+
+@dataclass
+class ProgramUnit:
+    base: int                       # PB at BEG time
+    end: int                        # CLC at END time
+    checksum: int = 0
+    symbols: list[Symbol] = field(default_factory=list)
+    rt_priority: int | None = None
+    longf: bool = False
+
+
+# --- Strip parity helper (some BRF streams have even-parity bit 7 set) ---
+
+def maybe_strip_parity(data: bytes) -> bytes:
+    """If majority of bytes have bit 7 set, strip it."""
+    high = sum(1 for b in data if b & 0x80)
+    if high > len(data) * 0.4:   # >40% high-bit set → likely parity
+        return bytes(b & 0x7F for b in data)
+    return data
+
+
+# --- Parser ---
+
+class BRFParser:
+    def __init__(self, data: bytes, base_address: int = 0):
+        self.data = data
+        self.pos = 0
+        self.clc = base_address      # current location counter (= load address)
+        self.pb = 0                  # program base
+        self.unit_idx = 0
+        self.units: list[ProgramUnit] = []
+        self.relocs: list[Reloc] = []
+        self.longf: bool = False     # 6-byte S-groups when set
+
+    def _read_byte(self) -> int | None:
+        if self.pos >= len(self.data):
+            return None
+        b = self.data[self.pos]
+        self.pos += 1
+        return b
+
+    def _read_word(self) -> int:
+        hi = self._read_byte() or 0
+        lo = self._read_byte() or 0
+        return (hi << 8) | lo
+
+    def _read_sgroup(self) -> bytes:
+        n = 6 if self.longf else 4
+        out = self.data[self.pos:self.pos + n]
+        self.pos += n
+        return out
+
+    def parse(self) -> list[ProgramUnit]:
+        cur_unit: ProgramUnit | None = None
+        while self.pos < len(self.data):
+            cb = self._read_byte()
+            if cb is None:
+                break
+
+            if cb == CB_FEED:
+                continue
+
+            if cb == CB_BEG:
+                # Start a new unit
+                cur_unit = ProgramUnit(base=self.clc, end=self.clc)
+                self.pb = self.clc
+                self.units.append(cur_unit)
+                self.unit_idx += 1
+                continue
+
+            if cb == CB_END:
+                cur_unit.end = self.clc - 1
+                cur_unit.checksum = self._read_word()
+                continue
+
+            if cb == CB_LONGF:
+                self.longf = True
+                if cur_unit:
+                    cur_unit.longf = True
+                continue
+
+            if cb == CB_INHB or cb == CB_EOF:
+                # No args
+                continue
+
+            if cb in (CB_LF, CB_LR, CB_LC):
+                w = self._read_word()
+                self.relocs.append(Reloc(self.clc, CONTROL_NAMES[cb], w,
+                                          self.unit_idx))
+                self.clc += 1
+                continue
+
+            if cb in (CB_AFF, CB_ARF, CB_AFR, CB_ARR):
+                w1 = self._read_word()
+                w2 = self._read_word()
+                # w2 is the address being fixed up; w1 is the value to add
+                # Record at the FIXUP TARGET ADDRESS, not at CLC
+                self.relocs.append(Reloc(w2, CONTROL_NAMES[cb] + ".val", w1,
+                                          self.unit_idx))
+                # NOTE: fix-up doesn't advance CLC
+                continue
+
+            if cb == CB_SFL:
+                w = self._read_word()
+                self.clc = w
+                continue
+
+            if cb == CB_AFL:
+                w = self._read_word()
+                # Fill (W1) zeros, advance CLC by W1
+                self.clc += w
+                continue
+
+            if cb == CB_SRL:
+                w = self._read_word()
+                self.clc = w + self.pb
+                continue
+
+            if cb == CB_LNF:
+                w = self._read_word()
+                for _ in range(w):
+                    word = self._read_word()
+                    self.relocs.append(Reloc(self.clc, "LF", word, self.unit_idx))
+                    self.clc += 1
+                continue
+
+            if cb == CB_RT:
+                prio = self._read_word()
+                if cur_unit:
+                    cur_unit.rt_priority = prio
+                continue
+
+            if cb in (CB_MAIN, CB_ENTR, CB_LIBR, CB_REF):
+                # Per ND-60.066.04 §2.9 "MAIN 2(3)" means the S-group is 2 words
+                # (3 if LONGF). There is NO trailing P-group; the symbol's value
+                # is set by the loader (= current CLC for MAIN/ENTR, or a
+                # back-link for REF, or conditional for LIBR).
+                sym = decode_symbol_packed(self._read_sgroup())
+                if cur_unit:
+                    cur_unit.symbols.append(
+                        Symbol(name=sym, kind=CONTROL_NAMES[cb], addr=self.clc)
+                    )
+                continue
+
+            if cb == CB_ASF:
+                sym = decode_symbol_packed(self._read_sgroup())
+                length = self._read_word()
+                if cur_unit:
+                    cur_unit.symbols.append(
+                        Symbol(name=f"COMMON:{sym}({length})", kind="ASF",
+                               addr=length)
+                    )
+                continue
+
+            if cb == CB_ADS:
+                sym = decode_symbol_packed(self._read_sgroup())
+                if cur_unit:
+                    cur_unit.symbols.append(
+                        Symbol(name=sym, kind="ADS", addr=0)
+                    )
+                continue
+
+            # CC-100 dialect: string-segment markers (no args)
+            if cb in (CB_CC_STRSEG_BEG, CB_CC_STRSEG_END):
+                continue
+
+            # CC-100 dialect: REF fix-up sub-markers (1 P-group arg)
+            if cb in (CB_CC_REFFIX_A, CB_CC_REFFIX_B):
+                w = self._read_word()
+                if cur_unit:
+                    cur_unit.symbols.append(
+                        Symbol(name=f"CC{cb:o}.subref", kind=CONTROL_NAMES[cb], addr=w)
+                    )
+                continue
+
+            # Unknown control byte — print and continue (defensive)
+            print(f"; warning: unknown BRF control byte 0o{cb:o} at offset {self.pos-1}",
+                  file=sys.stderr)
+
+        return self.units
+
+
+# --- High-level helpers ---
+
+def parse_brf(data: bytes, base_address: int = 0) -> BRFParser:
+    """Parse a BRF byte stream and return the populated parser."""
+    p = BRFParser(maybe_strip_parity(data), base_address)
+    p.parse()
+    return p
+
+
+def reloc_kinds(parser: BRFParser) -> dict[int, str]:
+    """Return {addr: kind} for every relocation entry."""
+    return {r.addr: r.kind for r in parser.relocs}
+
+
+def relocated_addresses(parser: BRFParser) -> set[int]:
+    """Set of memory addresses that hold RELOCATED ADDRESSES (LR or ARF/ARR)."""
+    return {r.addr for r in parser.relocs
+            if r.kind in ("LR", "LC", "ARF.val", "ARR.val")}
+
+
+def materialize_memory(parser: BRFParser) -> dict[int, int]:
+    """Apply all BRF records to produce a {addr: word} memory image.
+
+    Per ND-60.066.04 §2.9 + empirical refinements from HSERV1 validation:
+
+      LF  loads W1 unmodified at CLC                          [VERIFIED]
+      LR  W1 is a 1-indexed word ordinal; loaded value at CLC is (W1-1) + PB
+          when W1 != 0; LR with W1=0 is a placeholder waiting for an AFR/ARR
+          fix-up to supply the symbol value.                   [empirical]
+      LC  loads W1 + CDB at CLC (CDB=0 assumed; we don't model COMMON)
+      AFR fix-up: W2 is a 1-indexed word ordinal selecting the target word
+                  within the unit (target = PB + W2 - 1).
+                  For LF-targeted (= jump/displacement fix-up): add = W1 raw.
+                  For LR-targeted (= pointer fix-up): add = W1 - 1.
+                  Same applies to ARR (raises the conditional add by PB).
+      AFF/ARF: W2 is interpreted as the absolute target address (no -1).
+               W1 for AFF is raw; for ARF, add = W1 + PB.
+
+    The LF-vs-LR-target distinction is determined from the FIRST-PASS state:
+    if memory[target] was set by an LR record, the fix-up applies the
+    ordinal-to-offset shift; otherwise it adds the raw W1.
+
+    This rule has been empirically validated against HSERV1:BRF vs
+    HSERV1:PROG (201 / 281 LF-only match → 281 / 281 with the rule above).
+    """
+    mem: dict[int, int] = {}
+    target_was_lr: dict[int, bool] = {}  # tracks LR-target identity
+
+    # Pre-pass: establish initial values from LF/LR/LC.
+    for r in parser.relocs:
+        if r.kind in ("LF", "LR", "LC"):
+            unit = parser.units[r.unit - 1] if r.unit > 0 else None
+            pb = unit.base if unit else 0
+            if r.kind == "LF":
+                mem[r.addr] = r.value & 0xFFFF
+                target_was_lr[r.addr] = False
+            elif r.kind == "LR":
+                # When W1=0 the slot is a placeholder for an upcoming AFR
+                # fix-up that supplies the full address. Leaving the initial
+                # value at 0 makes the fix-up math work out (AFR's W1 will
+                # be the 1-indexed ordinal whose -1 is the actual target).
+                if r.value == 0:
+                    mem[r.addr] = 0
+                else:
+                    mem[r.addr] = ((r.value - 1) + pb) & 0xFFFF
+                target_was_lr[r.addr] = True
+            elif r.kind == "LC":
+                mem[r.addr] = r.value & 0xFFFF
+                target_was_lr[r.addr] = False
+
+    # Second pass: apply fix-ups.
+    for r in parser.relocs:
+        if not r.kind.endswith(".val"):
+            continue
+        unit = parser.units[r.unit - 1] if r.unit > 0 else None
+        pb = unit.base if unit else 0
+        kind = r.kind[:-4]
+        if kind == "AFF":
+            target = r.addr
+            add = r.value
+        elif kind == "ARF":
+            target = r.addr
+            add = (r.value + pb) & 0xFFFF
+        elif kind == "AFR":
+            target = (pb + r.addr - 1) & 0xFFFF
+            is_lr = target_was_lr.get(target, False)
+            add = (r.value - 1) if is_lr else r.value
+        elif kind == "ARR":
+            target = (pb + r.addr - 1) & 0xFFFF
+            is_lr = target_was_lr.get(target, False)
+            add = ((r.value - 1) if is_lr else r.value) + pb
+            add &= 0xFFFF
+        else:
+            continue
+        old = mem.get(target, 0)
+        mem[target] = (old + add) & 0xFFFF
+
+    return mem
+
+
+def main():
+    p = argparse.ArgumentParser(description=__doc__,
+                                formatter_class=argparse.RawDescriptionHelpFormatter)
+    p.add_argument("brf", type=Path, help=":BRF file to parse")
+    p.add_argument("--base", type=lambda s: int(s, 0), default=0,
+                   help="initial CLC (load address)")
+    p.add_argument("--show-reloc", action="store_true",
+                   help="print every relocation entry")
+    p.add_argument("--out", type=Path, default=None,
+                   help="write reloc map to file (one line per address)")
+    args = p.parse_args()
+
+    data = args.brf.read_bytes()
+    parser = parse_brf(data, args.base)
+    units = parser.units
+
+    print(f"# BRF parse of {args.brf.name} ({len(data)} bytes)")
+    print(f"# {len(units)} program unit(s), {len(parser.relocs)} reloc entries")
+    print(f"# LONGF: {parser.longf}")
+    print()
+
+    for i, u in enumerate(units):
+        print(f"## Unit {i}: base=0o{u.base:o}, end=0o{u.end:o}, "
+              f"checksum=0o{u.checksum:o}")
+        if u.rt_priority is not None:
+            print(f"   RT priority: {u.rt_priority}")
+        for s in u.symbols:
+            print(f"   {s.kind:5s} {s.name:8s} = 0o{s.addr:o}")
+
+    if args.show_reloc:
+        print()
+        print("# Relocation entries:")
+        for r in parser.relocs:
+            print(f"  0o{r.addr:06o}  {r.kind:5s}  0o{r.value:06o}  (unit {r.unit})")
+
+    if args.out:
+        # Write {addr -> kind} map
+        lines = [f"0o{r.addr:o}\t{r.kind}\t0o{r.value:o}" for r in parser.relocs]
+        args.out.write_text("\n".join(lines))
+        print(f"\nWrote reloc map to {args.out}")
+
+    # Summary stats
+    kinds: dict[str, int] = {}
+    for r in parser.relocs:
+        kinds[r.kind] = kinds.get(r.kind, 0) + 1
+    print("\n# Relocation kind histogram:")
+    for k, c in sorted(kinds.items(), key=lambda x: -x[1]):
+        print(f"  {k:8s} {c:6d}")
+
+
+if __name__ == "__main__":
+    main()
diff --git a/scripts/nd100_disasm.py b/scripts/nd100_disasm.py
new file mode 100644
index 00000000..e0a1739a
--- /dev/null
+++ b/scripts/nd100_disasm.py
@@ -0,0 +1,729 @@
+"""ND-100 / ND-110 disassembler — covers the SINTRAN III user-mode ISA
+plus most privileged instructions.
+
+Reference: ND-60.096.01 MAC Interactive Assembly and Debugging System §2.3
+(NORD-10 Instruction Repertoire). The ND-100 is binary-compatible with
+NORD-10/S at the user-mode ISA level used by SINTRAN III programs.
+
+PROG file layout (verified against HSERV1 / HPING / XMSG-HDLC-TEST):
+  bytes 0..0xFF       SINTRAN PROG header (256 bytes)
+  bytes 0x100..end    program memory image (BE 16-bit words; addr 0 = file offset 0x100)
+
+See `SINTRAN/File-Formats/PROG-FILE-FORMAT.md` for the file layout details,
+and `Developer/Reverse-Engineering/` for the decode reference and workflow.
+"""
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+PROG_HEADER_BYTES = 0x100
+
+
+# =========================================================================
+# PROG file conventions
+# =========================================================================
+
+def parse_prog_header(data: bytes) -> dict:
+    if len(data) < PROG_HEADER_BYTES:
+        return {}
+    def w(idx: int) -> int:
+        return (data[idx * 2] << 8) | data[idx * 2 + 1]
+    name_bytes = data[24 * 2:28 * 2]
+    lib_name = "".join(chr(b) for b in name_bytes if 32 <= b < 127)
+    return {
+        "end_addr": w(3), "marker": w(4), "build_id": w(14),
+        "const21": w(21), "library": lib_name,
+    }
+
+
+# =========================================================================
+# Decoding primitives
+# =========================================================================
+
+def signed8(v: int) -> int:
+    return v - 256 if v & 0x80 else v
+
+
+def signed7(v: int) -> int:
+    return v - 128 if v & 0x40 else v
+
+
+# Source/destination register name maps
+SRC_REG = {0o00: "0", 0o10: "SD", 0o20: "SP", 0o30: "SB",
+           0o40: "SL", 0o50: "SA", 0o60: "ST", 0o70: "SX"}
+DST_REG = {0o0: "STS", 0o1: "DD", 0o2: "DP", 0o3: "DB", 0o4: "DL",
+           0o5: "DA", 0o6: "DT", 0o7: "DX"}
+
+
+# Memory-reference opcodes (top 4 bits)
+MEM_OPS = {
+    0o000000: "STZ", 0o004000: "STA", 0o010000: "STT", 0o014000: "STX",
+    0o020000: "STD", 0o024000: "LDD", 0o030000: "STF", 0o034000: "LDF",
+    0o040000: "MIN", 0o044000: "LDA", 0o050000: "LDT", 0o054000: "LDX",
+    0o060000: "ADD", 0o064000: "SUB", 0o070000: "AND", 0o074000: "ORA",
+    0o100000: "FAD", 0o104000: "FSB", 0o110000: "FMU", 0o114000: "FDV",
+    0o120000: "MPY",
+    0o124000: "JMP", 0o134000: "JPL",
+}
+
+JCC_OPS = {
+    0o130000: "JAP", 0o130400: "JAN", 0o131000: "JAZ", 0o131400: "JAF",
+    0o132000: "JPC", 0o132400: "JNC", 0o133000: "JXZ", 0o133400: "JXN",
+}
+
+ARG_OPS = {
+    0o170000: "SAB", 0o170400: "SAA",
+    0o171000: "SAT", 0o171400: "SAX",
+    0o172000: "AAB", 0o172400: "AAA",
+    0o173000: "AAT", 0o173400: "AAX",
+}
+
+# Known MON-call numbers (extracted from ND-860228-2-EN SINTRAN III Monitor Calls).
+# Numbers are OCTAL (matching MAC convention). 125 names verified — includes
+# 0o0=ExitFromProgram, 0o1=InByte, 0o2=OutByte, 0o122=ReserveResource,
+# 0o123=ReleaseResource, 0o201=HDLCfunction. Update via the extraction script
+# at scripts/extract_mon_names.py if you want to refresh.
+MON_NAMES = {
+    0o0: 'ExitFromProgram',
+    0o1: 'InByte',
+    0o2: 'OutByte',
+    0o3: 'SetEcho',
+    0o4: 'SetBreak',
+    0o6: 'WriteScratchFile',
+    0o7: 'ReadBlock',
+    0o10: 'WriteBlock',
+    0o13: 'ClearInBuffer',
+    0o14: 'ClearOutBuffer',
+    0o16: 'GetTerminalType',
+    0o17: 'SetTerminalType',
+    0o23: 'In8Bytes',
+    0o24: 'Out8Bytes',
+    0o26: 'GetLastByte',
+    0o27: 'GetRTDescr',
+    0o30: 'GetOwnRTAddress',
+    0o31: 'IOInstruction',
+    0o32: 'OutMessage',
+    0o36: 'NoWaitSwitch',
+    0o37: 'ReadADChannel',
+    0o40: 'CloseSpoolingFile',
+    0o41: 'ReadObjectEntry',
+    0o43: 'Closefile',
+    0o44: 'GetUserEntry',
+    0o50: 'OpenFile',
+    0o53: 'GetSegmentEntry',
+    0o54: 'DeleteFile',
+    0o55: 'GetSpoolingEntry',
+    0o57: 'GetUserParam',
+    0o62: 'GetBytesInFile',
+    0o65: 'ErrorMessage',
+    0o66: 'InBufferSpace',
+    0o70: 'CallCommand',
+    0o71: 'DisableEscape',
+    0o73: 'SetMaxBytes',
+    0o74: 'SetStartByte',
+    0o75: 'GetStartByte',
+    0o76: 'SetBlockSize',
+    0o77: 'SetStartBlock',
+    0o101: 'DelayStart',
+    0o103: 'StartupInterval',
+    0o105: 'StopRTProgram',
+    0o106: 'StartOnInterrupt',
+    0o107: 'NoInterruptStart',
+    0o110: 'SetRTPriority',
+    0o111: 'SetClock',
+    0o112: 'AdjustClock',
+    0o114: 'GetTimeUsed',
+    0o115: 'FixScattered',
+    0o117: 'ReadFromFile',
+    0o120: 'WriteToFile',
+    0o121: 'AwaitFileTransfer',
+    0o122: 'ReserveResource',
+    0o123: 'ReleaseResource',
+    0o124: 'ForceReserve',
+    0o126: 'ExactDelayStart',
+    0o130: 'ExactInterval',
+    0o137: 'DisableRTStart',
+    0o140: 'ReservationInfo',
+    0o141: 'DeviceControl',
+    0o142: 'ToErrorDevice',
+    0o144: 'DeviceFunction',
+    0o147: 'CAMACfunction',
+    0o150: 'CAMACGLRegister',
+    0o151: 'GetRTAddress',
+    0o152: 'GetRTName',
+    0o153: 'CAMACIOInstruction',
+    0o154: 'AssignCAMACLAM',
+    0o155: 'Graphic',
+    0o157: 'SegmentToPageTable',
+    0o160: 'FixContiguous',
+    0o161: 'InString',
+    0o200: 'XMSGFunction',          # Program-to-program comm; from manual cross-ref table (not in MON N %Monitor call form)
+    0o201: 'HDLCfunction',
+    0o213: 'GetDirUserIndexes',
+    0o214: 'GetUserName',
+    0o215: 'GetObjectEntry',
+    0o216: 'SetObjectEntry',
+    0o217: 'GetAllFileIndexes',
+    0o220: 'DirectOpen',
+    0o221: 'CreateFile',
+    0o230: 'GetEscLocalChar',
+    0o231: 'ExpandFile',
+    0o233: 'SetTemporaryFile',
+    0o234: 'SetPeripheralFile',
+    0o236: 'SetPermanentOpen',
+    0o240: 'AppendSpooling',
+    0o241: 'NewUser',
+    0o242: 'OldUser',
+    0o243: 'GetDirNameIndex',
+    0o244: 'GetDirEntry',
+    0o245: 'GetNameEntry',
+    0o246: 'ReserveDir',
+    0o247: 'ReleaseDir',
+    0o250: 'GetDefaultDir',
+    0o251: 'CopyPage',
+    0o252: 'BackupClose',
+    0o253: 'NewFileVersion',
+    0o254: 'GetErrorDevice',
+    0o256: 'FullFileName',
+    0o257: 'OpenFileInfo',
+    0o262: 'GetSystemInfo',
+    0o263: 'GetDeviceType',
+    0o267: 'TimeOut',
+    0o271: 'WriteDiskPage',
+    0o272: 'DeletePage',
+    0o273: 'GetFileName',
+    0o274: 'GetFileIndexes',
+    0o275: 'SetTerminalName',
+    0o306: 'GetTerminalMode',
+    0o307: 'TerminalNoWait',
+    0o310: 'In8AndFlag',
+    0o311: 'WriteDirEntry',
+    0o312: 'CheckMonCall',
+    0o313: 'InBufferState',
+    0o322: 'GetSegmentNo',
+    0o323: 'SegmentOverlay',
+    0o324: 'OctobusFunction',
+    0o326: 'LogInStart',
+    0o327: 'FileSystemFunction',
+    0o330: 'TerminalStatus',
+    0o332: 'TerminalStatus',
+    0o333: 'DMAFunction',
+    0o334: 'GetErrorMessage',
+    0o335: 'DataTransfer',
+}
+
+
+# =========================================================================
+# Addressing-mode decode (memory-reference family)
+# =========================================================================
+
+def decode_ea(w: int, pc: int):
+    """For a memory-reference instruction, return (ea_text, target_addr_or_None).
+    target_addr is only resolved for P-rel and P-indirect modes (B-rel /
+    X-rel depend on runtime register state).
+    """
+    disp = signed8(w & 0xFF)
+    mode = w & 0o3400
+    if mode == 0o0000:
+        return f"L{(pc + disp) & 0xFFFF:o}", (pc + disp) & 0xFFFF
+    if mode == 0o0400:
+        return f"{disp},B", None
+    if mode == 0o1000:
+        return f"I L{(pc + disp) & 0xFFFF:o}", (pc + disp) & 0xFFFF
+    if mode == 0o1400:
+        return f"I {disp},B", None
+    if mode == 0o2000:
+        return f"{disp},X", None
+    if mode == 0o2400:
+        return f"{disp},B,X", None
+    if mode == 0o3000:
+        return f"I L{(pc + disp) & 0xFFFF:o},X", (pc + disp) & 0xFFFF
+    if mode == 0o3400:
+        return f"I {disp},B,X", None
+    return "?", None
+
+
+# =========================================================================
+# Register-op decode (0o140000..0o147777 family)
+# =========================================================================
+
+# Combined register-op codes (§2.3.5 + §2.3 Combined Instructions)
+REG_OPS = {
+    # The high octet's bits 11-9 select function (RAD=1 family vs RAD=0 family)
+    # Plus QC, IC modifiers, plus AD1/CLD/CM1/CM2 modifiers in bits 4-9.
+    # We do a coarse classification by the function field bits 9-6.
+    # Codes encode: opcode + AD1(bit 8) + ADC(bit 9) + CLD(bit 7) + CM1(bit 8) +CM2(bit 7+8)
+    # See full table in ND-60.096.01 §2.3.5.
+}
+
+
+def decode_reg_op(w: int) -> str:
+    """Decode a register-operations instruction (top 4 = 1100).
+    Format: 1100 | QC | IC | R | source[3] | destin[3]
+    Combined ops have bit-7/bit-8 modifiers (AD1, ADC, CLD, CM1, CM2).
+    """
+    # Common shortcuts (combined instructions per §2.3 Combined)
+    if w == 0o146142: return "EXIT"          # COPY SL DP
+    if w == 0o146100: return "RCLR"          # COPY 0 0   (clear)
+    if w == 0o146400: return "RINC"          # RADD AD1
+    if w == 0o146200: return "RCDR"          # RADD CM1
+
+    sr = w & 0o70
+    dr = w & 0o7
+    sr_n = SRC_REG.get(sr, f"S?{sr:o}")
+    dr_n = DST_REG.get(dr, f"D?{dr:o}")
+
+    # Determine base opcode by bits 11-6 (excluding the modifier bits 7-8)
+    op_field = w & 0o7700
+    BASE_OP = {
+        0o6000: "RADD", 0o6100: "COPY", 0o6600: "RSUB",
+        0o4000: "SWAP", 0o4400: "RAND", 0o5000: "REXO", 0o5400: "RORA",
+        # Extended arithmetic (no separate src/dst encoding in the same way)
+        0o1200: "RMPY", 0o1600: "RDIV",
+    }
+    op = BASE_OP.get(op_field)
+    if op:
+        # Modifier bits per ND-60.096.01 §2.3.5
+        # CLD (bit 7), CM1 (bit 8), AD1 (bit 8 too? — actually different table per RAD)
+        # We just print core form.
+        return f"{op} {sr_n} {dr_n}".rstrip()
+    return f"REG 0o{w:06o}  ; sr={sr_n} dr={dr_n}"
+
+
+# =========================================================================
+# Skip-instructions decode (0o140000..0o140777 — RAD=0, IC=QC=0, sub-class)
+# =========================================================================
+
+# SKP format: 1100 0 | condition[2:0] | source[3] | destin[3]
+SKP_CONDS = {
+    0o0000: "EQL", 0o0400: "GRE", 0o1000: "MGRE",   # signed greater-or-equal / magnitude
+    0o2000: "UEQ", 0o2400: "LST", 0o3000: "MLST",
+}
+
+
+def maybe_skp(w: int) -> str | None:
+    """Detect and decode SKP instructions.
+    Per §2.3.7: SKP base = 0o140000, with condition bits 11-9 distinguishing.
+    But this overlaps the reg-op range, so detect by checking common SKP forms.
+    """
+    if (w & 0o170000) != 0o140000:
+        return None
+    # The reg-op family also lives here; SKP is distinguished by bit pattern.
+    # Easiest heuristic: SKP instruction has form 0o14X000 + cond + sr + dr,
+    # where bits 11-10 are 00 (vs reg-op which has 01-10 set).
+    # Per the manual table, SKP = 0o140000 exactly with cond/src/dst encoded in low bits.
+    if (w & 0o7000) == 0o000:        # the RAD/QC/IC fields are zero
+        sr = w & 0o70
+        dr = w & 0o7
+        cond_bits = w & 0o3400
+        cond = SKP_CONDS.get(cond_bits, f"?{cond_bits:o}")
+        sr_n = SRC_REG.get(sr, f"S{sr:o}")
+        dr_n = DST_REG.get(dr, f"D{dr:o}")
+        return f"SKP {cond} {sr_n} {dr_n}"
+    return None
+
+
+# =========================================================================
+# Shift-instructions decode (0o154000..0o155777)
+# =========================================================================
+
+SHIFT_TARGET = {0o000: "SHT", 0o200: "SHD", 0o400: "SHA", 0o600: "SAD"}
+SHIFT_MODE   = {0o000: "ARITH", 0o1000: "ROT", 0o2000: "ZIN", 0o3000: "LIN"}
+
+
+def decode_shift(w: int) -> str:
+    """Per ND-60.096.01 §2.3.8."""
+    if (w & 0o174000) != 0o154000:
+        return None
+    target = w & 0o600
+    mode = w & 0o3000
+    count = signed7(w & 0o177)         # signed 7-bit shift count; negative = right-shift
+    op = SHIFT_TARGET.get(target, "SH?")
+    mod = SHIFT_MODE.get(mode, "")
+    if count == 0:
+        return f"{op}"
+    direction = "SHR" if count < 0 else ""
+    return f"{op} {direction} {abs(count)}  {mod}".strip()
+
+
+# =========================================================================
+# Bit-instructions decode (0o174000..0o177777)
+# =========================================================================
+
+BIT_OPS = {
+    0o174000: "BSET", 0o175000: "BSKP",
+    0o176000: "BSTC", 0o176200: "BSTA",
+    0o176400: "BLDA", 0o176440: "BLDC",   # 176600/176640 in some tables — check
+    0o177000: "BANC", 0o177200: "BAND",
+    0o177400: "BORC", 0o177600: "BORA",
+}
+BIT_CONDS = {0o000: "ZRO", 0o200: "ONE", 0o400: "BCM", 0o600: "BAC"}
+
+
+def decode_bit(w: int) -> str:
+    """Bit instructions: 1111 | function(11-9) | cond(8-6 or 7-5) | bit(5-3) | dst(2-0).
+    Tables in manual aren't fully consistent; output a best-effort name."""
+    if (w & 0o174000) != 0o174000:
+        return None
+    op_field = w & 0o177400
+    op = BIT_OPS.get(op_field)
+    if op is None:
+        # Fall back to top 9 bits
+        op_field = w & 0o177000
+        op = BIT_OPS.get(op_field, f"BIT?")
+    cond_field = w & 0o600
+    cond = BIT_CONDS.get(cond_field, "?")
+    bit_no = (w >> 3) & 0o17
+    dst = w & 0o7
+    dst_n = DST_REG.get(dst, "?")
+    return f"{op} {cond} bit{bit_no} {dst_n}"
+
+
+# =========================================================================
+# Privileged / system / interlevel decode
+# =========================================================================
+
+PRIV_NAMED = {
+    0o150401: "IOF", 0o150402: "ION",
+    0o150404: "POF", 0o150410: "PON",
+    0o151000: "WAIT 0",
+    0o151400: "NLZ",                # integer-to-floating
+    0o152000: "DNZ",                # floating-to-integer
+    0o152402: "SRB",                # store register block (priv)
+    0o152600: "LRB",                # load register block (priv)
+    0o143600: "IDENT",              # interrupt identification (priv)
+}
+SYS_PREFIX = {
+    0o150000: "TRA", 0o150100: "TRR",
+    0o150200: "MCL", 0o150300: "MST",
+    0o150400: "OPCOM",              # (octal range)
+    0o153400: "IRR",                # inter-register read (priv)
+    0o153600: "IRW",                # inter-register write (priv)
+}
+
+
+def decode_priv(w: int) -> str | None:
+    if w in PRIV_NAMED:
+        return PRIV_NAMED[w]
+    # OPR / panel-info: 150400-150477 (OPCOM family)
+    if (w & 0o177400) == 0o150400:
+        return f"OPCOM 0o{w & 0o377:o}"
+    # IRR/IRW have level encoded in low bits
+    op_hi = w & 0o177700
+    if op_hi == 0o153400:
+        return f"IRR 0o{w & 0o77:o}"
+    if op_hi == 0o153600:
+        return f"IRW 0o{w & 0o77:o}"
+    # TRA/TRR/MCL/MST take a register code in low 6 bits
+    op_hi2 = w & 0o177700
+    if op_hi2 in SYS_PREFIX:
+        return f"{SYS_PREFIX[op_hi2]} 0o{w & 0o77:o}"
+    return None
+
+
+# =========================================================================
+# Byte instructions decode (SBYT/LBYT)
+# =========================================================================
+
+def decode_byte(w: int) -> str | None:
+    if w == 0o142600:
+        return "SBYT"
+    if w == 0o142200:
+        return "LBYT"
+    return None
+
+
+# =========================================================================
+# Top-level decoder
+# =========================================================================
+
+def decode(w: int, pc: int) -> tuple[str, int | None]:
+    """Decode word `w` at memory address `pc`. Returns (mnemonic, jump_target or None)."""
+    if w == 0:
+        return "ZERO", None
+
+    # MON N — top 8 bits = 0xD6
+    if (w & 0xFF00) == 0xD600:
+        n = w & 0xFF
+        ann = MON_NAMES.get(n)
+        if ann:
+            return f"MON 0o{n:o}  ({ann})", None
+        return f"MON 0o{n:o}", None
+
+    # IOX — 0o164000..0o167777 (top 5 bits = 11101)
+    # NB: mask is 0o174000 not 0o170000 — IOX bit-11 is set.
+    if (w & 0o174000) == 0o164000:
+        return f"IOX 0o{w & 0o3777:o}", None
+
+    # Byte instructions (specific opcodes)
+    bm = decode_byte(w)
+    if bm:
+        return bm, None
+
+    top5 = w & 0o174000
+
+    # Conditional jumps (10110X family)
+    if top5 == 0o130000:
+        cc = w & 0o3400
+        disp = signed8(w & 0xFF)
+        op = JCC_OPS.get(top5 | cc, f"JCC?0o{cc:o}")
+        target = (pc + disp) & 0xFFFF
+        return f"{op} L{target:o}", target
+
+    # Memory-reference (and JMP/JPL)
+    if top5 in MEM_OPS:
+        op = MEM_OPS[top5]
+        eatxt, target = decode_ea(w, pc)
+        return f"{op} {eatxt}", target
+
+    # Argument instructions
+    top8 = w & 0o177400
+    if top8 in ARG_OPS:
+        arg = signed8(w & 0o377)
+        return f"{ARG_OPS[top8]} 0o{arg & 0o377:o}", None
+
+    # Shift instructions
+    sh = decode_shift(w)
+    if sh:
+        return sh, None
+
+    # Privileged / system control / WAIT
+    # WAIT N — 0o151000..0o151377
+    if (w & 0o177400) == 0o151000:
+        return f"WAIT 0o{w & 0o377:o}", None
+    priv = decode_priv(w)
+    if priv:
+        return priv, None
+
+    # Bit instructions
+    bi = decode_bit(w)
+    if bi:
+        return bi, None
+
+    # Skip family (before reg-op fallback)
+    skp = maybe_skp(w)
+    if skp:
+        return skp, None
+
+    # Register-ops fall-back
+    if (w & 0o170000) == 0o140000:
+        return decode_reg_op(w), None
+
+    return f".WORD 0o{w:06o}", None
+
+
+# =========================================================================
+# Disassembly infrastructure
+# =========================================================================
+
+class Program:
+    def __init__(self, data: bytes, base_offset: int = PROG_HEADER_BYTES):
+        self.data = data
+        self.base = base_offset
+        hdr = parse_prog_header(data) if base_offset == PROG_HEADER_BYTES else {}
+        self.end_addr = hdr.get("end_addr", (len(data) - base_offset) // 2)
+        self.header = hdr
+
+    def word(self, addr: int) -> int | None:
+        off = self.base + addr * 2
+        if off + 1 >= len(self.data):
+            return None
+        return (self.data[off] << 8) | self.data[off + 1]
+
+    def words(self):
+        for a in range(self.end_addr):
+            yield a, self.word(a)
+
+
+def disassemble(prog: Program, start: int = 0, end: int | None = None,
+                symbols: dict[int, str] | None = None,
+                code_only: set[int] | None = None) -> list[str]:
+    if end is None:
+        end = prog.end_addr
+    symbols = dict(symbols or {})
+    lines: list[str] = []
+    target_set: set[int] = set()
+
+    for a in range(start, end):
+        w = prog.word(a)
+        if w is None:
+            continue
+        if code_only is not None and a not in code_only:
+            continue
+        _, tgt = decode(w, a)
+        if tgt is not None:
+            target_set.add(tgt)
+
+    for a in range(start, end):
+        w = prog.word(a)
+        if w is None:
+            continue
+        if code_only is not None and a not in code_only:
+            continue
+        sym = symbols.get(a, "")
+        if a in target_set and not sym:
+            sym = f"L{a:o}"
+        mnem, tgt = decode(w, a)
+        if tgt is not None and tgt in target_set:
+            named = symbols.get(tgt, f"L{tgt:o}")
+            mnem = mnem.replace(f"L{tgt:o}", named)
+        chars = "".join(chr(b) if 32 <= b < 127 else "." for b in (w >> 8, w & 0xFF))
+        label = f"{sym + ',':<12s}" if sym else " " * 12
+        lines.append(f"0o{a:06o}  0x{w:04x}  {label}{mnem:<36s}  ; {chars}")
+    return lines
+
+
+def trace_reachable(prog: Program, entries: list[int],
+                    reloc_targets: set[int] | None = None) -> set[int]:
+    """Forward control-flow trace. If `reloc_targets` provided (from BRF parse),
+    also seed the worklist with addresses these pointers point to."""
+    code: set[int] = set()
+    worklist = list(entries)
+    if reloc_targets:
+        worklist.extend(reloc_targets)
+    while worklist:
+        pc = worklist.pop()
+        if pc < 0 or pc >= prog.end_addr or pc in code:
+            continue
+        w = prog.word(pc)
+        if w is None:
+            continue
+        if _looks_like_text(prog, pc):
+            continue
+        code.add(pc)
+        _follow(prog, pc, w, worklist)
+    return code
+
+
+def _looks_like_text(prog: Program, pc: int) -> bool:
+    text = 0
+    total = 0
+    for k in range(pc, min(pc + 8, prog.end_addr)):
+        w = prog.word(k)
+        if w is None:
+            break
+        for b in (w >> 8, w & 0xFF):
+            total += 1
+            if 32 <= b < 127 or b in (0, 10, 13, 9):
+                text += 1
+    return total > 0 and text / total > 0.85
+
+
+def _follow(prog: Program, pc: int, w: int, worklist: list[int]) -> None:
+    if w == 0:
+        return
+    if (w & 0xFF00) == 0xD600:
+        n = w & 0xFF
+        if n != 0:
+            worklist.append(pc + 1)
+            worklist.append(pc + 2)
+        return
+    if w == 0o146142:  # EXIT
+        return
+    top5 = w & 0o174000
+    mode = w & 0o3400
+    disp = signed8(w & 0xFF)
+    if top5 == 0o124000:
+        if mode == 0o0000:
+            worklist.append((pc + disp) & 0xFFFF)
+        elif mode == 0o1000:
+            ptr = (pc + disp) & 0xFFFF
+            v = prog.word(ptr)
+            if v is not None:
+                worklist.append(v)
+        return
+    if top5 == 0o134000:
+        if mode == 0o0000:
+            worklist.append((pc + disp) & 0xFFFF)
+        elif mode == 0o1000:
+            ptr = (pc + disp) & 0xFFFF
+            v = prog.word(ptr)
+            if v is not None:
+                worklist.append(v)
+        worklist.append(pc + 1)
+        return
+    if top5 == 0o130000:
+        worklist.append((pc + disp) & 0xFFFF)
+        worklist.append(pc + 1)
+        return
+    worklist.append(pc + 1)
+
+
+# =========================================================================
+# CLI
+# =========================================================================
+
+def main():
+    p = argparse.ArgumentParser(description=__doc__,
+                                formatter_class=argparse.RawDescriptionHelpFormatter)
+    p.add_argument("file", type=Path)
+    p.add_argument("--base", type=lambda s: int(s, 0), default=PROG_HEADER_BYTES)
+    p.add_argument("--start", type=lambda s: int(s, 0), default=0)
+    p.add_argument("--end", type=lambda s: int(s, 0), default=None)
+    p.add_argument("--trace", type=lambda s: int(s, 0), action="append", default=None)
+    p.add_argument("--header", action="store_true")
+    p.add_argument("--sym", type=Path, default=None)
+    p.add_argument("--brf", type=Path, default=None,
+                   help="matching :BRF file — seeds trace with LR addresses (relocations)")
+    args = p.parse_args()
+
+    data = args.file.read_bytes()
+    prog = Program(data, args.base)
+
+    if args.header:
+        print(f"File: {args.file}")
+        print(f"Size: {len(data)} bytes")
+        for k, v in prog.header.items():
+            print(f"  {k}: {v!r}")
+        print(f"  base_offset: 0x{args.base:x}")
+        print(f"  memory_size: {prog.end_addr} words")
+        return
+
+    symbols: dict[int, str] = {}
+    if args.sym:
+        for line in args.sym.read_text().splitlines():
+            line = line.strip()
+            if not line or line.startswith("#"):
+                continue
+            parts = line.split(None, 1)
+            if len(parts) == 2:
+                try:
+                    symbols[int(parts[0], 0)] = parts[1]
+                except ValueError:
+                    pass
+
+    reloc_targets = None
+    if args.brf:
+        try:
+            sys.path.insert(0, str(Path(__file__).parent))
+            import nd100_brf
+            brf = nd100_brf.parse_brf(args.brf.read_bytes())
+            reloc_addrs = nd100_brf.relocated_addresses(brf)
+            # Seed trace with the VALUES at those addresses (they're function pointers)
+            reloc_targets = set()
+            for a in reloc_addrs:
+                v = prog.word(a)
+                if v is not None and 0 <= v < prog.end_addr:
+                    reloc_targets.add(v)
+                # Also include the slot's address as a candidate code start
+                symbols.setdefault(a, f"PTR_{a:o}")
+            print(f"; BRF: {len(reloc_addrs)} relocated slots, "
+                  f"{len(reloc_targets)} unique pointer values", file=sys.stderr)
+        except Exception as e:
+            print(f"; BRF load failed: {e}", file=sys.stderr)
+
+    code_only = None
+    if args.trace or reloc_targets:
+        entries = (args.trace or []) + list(reloc_targets or [])
+        code_only = trace_reachable(prog, entries, reloc_targets)
+        print(f"; trace-reachable: {len(code_only)} of {prog.end_addr} words "
+              f"({len(code_only) * 100 // max(1, prog.end_addr)}%)", file=sys.stderr)
+
+    for line in disassemble(prog, args.start, args.end, symbols, code_only):
+        print(line)
+
+
+if __name__ == "__main__":
+    main()

From 527aee1f7660b83e6ffa2da9ca1f70d31a12d971 Mon Sep 17 00:00:00 2001
From: retrogcom <retrogcom@users.noreply.github.com>
Date: Thu, 28 May 2026 12:45:13 +0200
Subject: [PATCH 2/3] Document the working request/response + on-demand HDLC
 server
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The request/response server (not just broadcast) now works end-to-end on
nd100x: a browser fetches the page byte-exact, with the ND reading one disk
block on demand instead of caching every file. Update the case study and the
buffer-pool RX->TX section with the verified recipe — transmit the
just-received DCB keeping its RX-set size, drain each send with an output-side
FRCV, pace requests ~120 ms, MON 117 block reads per request — and link the
XSSDATA transmit deep-dive for the underlying DMA descriptor (LKEY/LBYTC).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .../Case-Studies/HTTP-Server-over-HDLC.md     | 83 +++++++++++++------
 .../Buffer-Pool-and-Emulator-Usage.md         | 45 ++++++++--
 2 files changed, 96 insertions(+), 32 deletions(-)

diff --git a/Developer/Case-Studies/HTTP-Server-over-HDLC.md b/Developer/Case-Studies/HTTP-Server-over-HDLC.md
index c8b22785..fddff377 100644
--- a/Developer/Case-Studies/HTTP-Server-over-HDLC.md
+++ b/Developer/Case-Studies/HTTP-Server-over-HDLC.md
@@ -65,34 +65,52 @@ Three layers:
   of the bytes the ND produced (one HTML page, another page, the GIF), setting
   the right content type.
 
-## Key design decision: broadcast vs request/response
-
-The natural design is request/response: the ND receives the HTTP request,
-reads the requested file, and replies. In our first attempt the reply didn't
-reach the wire — after the receive, a plain send transmitted nothing. The
-cause is a **missing transmitter restart**: a transmitter that has gone idle
-must be explicitly restarted (reload DCB + retrigger) before it sends again;
-TX and RX are independent modules. This restart path is **verified to work
-in the emulator** — SINTRAN's own `XMSG-HDLC-TEST` echo mode does
-receive-then-transmit between two relay-connected nd100x instances (5/5
-frames echoed, 0 errors). So request/response is achievable; our broadcast
-server simply never stops the transmitter, while a request/response server
-must do the restart after each receive. See
+## Two working designs: broadcast and request/response
+
+Both designs are implemented and verified on `nd100x`.
+
+**Broadcast** (the first to ship): the ND continuously transmits all of its
+cached files; the host bridge captures one full cycle and serves URLs from
+that capture. The transmitter never goes idle, so it sidesteps the
+restart-after-receive problem entirely — at the cost of caching every file in
+RAM and keeping the wire always busy.
+
+**Request/response** (now working, and the design that scales past RAM): the
+ND receives an HTTP request, reads the requested data **from disk on demand**,
+and replies. Our first attempt stalled — after the receive, a plain send
+transmitted nothing — because the transmitter had gone idle and a bare `FSND`
+did not restart it. The working recipe, verified end-to-end (a browser fetches
+the full page, byte-exact), is:
+
+1. **Transmit the buffer that just received.** After a real DMA receive the
+   only DCB the driver will transmit is the one whose receive just completed.
+   Overwrite its payload with your response bytes but **keep the RX-set
+   `USize`** (the receive wrote the byte count into the shared size cell) — the
+   driver validates the transmit length against that count, so the response
+   frame can be at most as large as the request frame.
+2. **Drain the transmit with an `FRCV` on the *output* LDN** before re-arming
+   the buffer for receive. The DMA writes completion status back into the DCB;
+   without the drain the transmitter dies after ~3 frames (a TX/RX write-back
+   clash on a shared DCB — keep TX and RX DCB memory separate where you can).
+3. **Pace the requests.** A request frame sent *immediately* after a response
+   is dropped (the ND is mid drain-and-re-arm, RX not yet armed). The host
+   waits ~120 ms between chunk-requests.
+4. **Read on demand.** Open the file once (`MON 50`), and per request
+   `MON 117`-read one disk block into a single block buffer — no full-file
+   cache. The host sizes each request to the response chunk and reassembles.
+
+The full recipe, the transmit DCB format it relies on, and the gotchas are in
 [HDLC Buffer-Pool and Emulator Usage](../../SINTRAN/Devices/HDLC/implementation/Buffer-Pool-and-Emulator-Usage.md#restarting-transmit-after-the-tx-list-drains-incl-after-a-receive).
 
-So the shipping design is **broadcast**: the ND continuously transmits all of
-its cached files (the transmitter never goes idle, so no restart is needed);
-the host bridge captures one full cycle and serves URLs from that capture.
-Trade-offs:
-
 | Model | Status | RAM footprint | Notes |
 |-------|--------|---------------|-------|
-| Broadcast (cache all, stream) | ✅ shipping | all files resident | simplest; transmitter never stops, wire always busy |
-| Request/response (read on demand) | achievable — needs per-receive TX restart (verified via XMSG-HDLC-TEST) | one file at a time | the goal; scales past RAM |
+| Broadcast (cache all, stream) | ✅ verified | all files resident | simplest; transmitter never stops, wire always busy |
+| Request/response (read on demand) | ✅ verified | **one disk block (~512 B) at a time** | scales past RAM; ND program ~4× smaller (no cache); needs the TX-drain + request pacing above |
 
-On a 2 MB ND-110 the request/response model also matters for *scale* (you
-can't cache an unbounded site), so it remains the target design — implemented
-with a proper transmitter restart after each receive.
+On a 2 MB ND-110 the request/response model matters for *scale* — you can't
+cache an unbounded site. The on-demand server holds only one 512-byte disk
+block regardless of total site size, and its ND-side program is roughly a
+quarter the size of the cache-everything build.
 
 ## Lessons worth carrying forward
 
@@ -109,6 +127,14 @@ with a proper transmitter restart after each receive.
 - **A host bridge is a legitimate architecture** — pushing the HTTP/routing
   complexity to the host keeps the ND-side MAC program small and within the
   device's real constraints.
+- **After a receive, transmit the buffer that received** — a fresh standalone
+  TX DCB won't start the transmitter post-receive; the just-completed RX DCB
+  will. Refill its payload, keep the RX-set size. (Buffer doc, RX→TX section.)
+- **Drain each send with an `FRCV` on the output LDN** — lets the DMA finish
+  writing status back into the DCB before you reuse it; without it the
+  transmitter stalls after a few frames.
+- **Pace request/response** — the ND needs a beat (~120 ms) between requests to
+  drain TX and re-arm RX; a too-fast follow-up request frame is dropped.
 
 ---
 
@@ -121,7 +147,10 @@ with a proper transmitter restart after each receive.
 
 ---
 
-*Built and verified on SINTRAN III VSX/500 L under nd100x. Transmit-after-
-receive is a transmitter-restart requirement (reload + retrigger an idled
-TX), verified working in the emulator via XMSG-HDLC-TEST echo mode between
-two relay-connected instances — not an emulator limitation.*
+*Built and verified on SINTRAN III VSX/500 L under nd100x. Both the broadcast
+and the on-demand request/response servers were run end-to-end: a browser
+fetched the page byte-exact. Transmit-after-receive is a transmitter-restart
+requirement, not an emulator limitation — first confirmed via SINTRAN's own
+XMSG-HDLC-TEST echo mode between two relay-connected instances, then
+implemented in our server by transmitting the just-received DCB and draining
+each send with an output-side `FRCV`.*
diff --git a/SINTRAN/Devices/HDLC/implementation/Buffer-Pool-and-Emulator-Usage.md b/SINTRAN/Devices/HDLC/implementation/Buffer-Pool-and-Emulator-Usage.md
index 4e45f2f8..8fc7d08d 100644
--- a/SINTRAN/Devices/HDLC/implementation/Buffer-Pool-and-Emulator-Usage.md
+++ b/SINTRAN/Devices/HDLC/implementation/Buffer-Pool-and-Emulator-Usage.md
@@ -189,11 +189,46 @@ each frame and transmitted it back, and the **send end** (`SEND 5`) reported
 
 A naive request/response server of ours *did* stall on the RX→TX turn — but
 the cause was on our side: after the receive we issued a bare send **without
-the explicit transmitter restart** (reload DCB + retrigger) that `ECHO-MODE`
-performs. A broadcast design never stops the transmitter and so avoids the
-issue; **a request/response design must restart the transmitter after each
-receive**, exactly as XMSG-HDLC-TEST's echo mode does (and which the
-emulator handles correctly).
+the explicit transmitter restart** that `ECHO-MODE` performs. A broadcast
+design never stops the transmitter and so avoids the issue.
+
+#### The verified request/response recipe
+
+**[VERIFIED-nd100x]** A request/response server *does* work; a browser fetched
+a full page byte-exact over it. The recipe that restarts the transmitter after
+each receive:
+
+1. **Transmit the DCB whose receive just completed.** After a real DMA receive
+   the driver will *only* start the transmitter for the just-received DCB — a
+   fresh standalone TX DCB produces no transmit at all. Overwrite that DCB's
+   payload (from word 4, preserving the address/control word) with your
+   response bytes.
+2. **Keep the RX-set transmit size.** `FRCV` writes the received byte count
+   into the shared `USize` cell; reuse it unchanged on the `FSND`. The driver
+   validates the transmit length against that count — forcing a larger `USize`
+   produces *no* `TX_START`. **Consequence:** one response frame can be at most
+   the size of the request frame, so the host sizes each request to the chunk
+   it wants and reassembles a larger page from several request/response turns.
+3. **Drain the transmit with an `FRCV` on the *output* LDN** before re-arming
+   the DCB for receive. The DMA writes send/receive status back *into the DCB
+   memory*; reusing one DCB for both directions without draining makes the
+   transmitter die after ~3 frames. **Keep TX and RX DCBs in separate memory
+   where you can** (the DMA engine writes back to both).
+4. **Pace the requests.** A request frame that arrives while the ND is mid
+   drain-and-re-arm (RX not yet armed) is dropped. ~120 ms between
+   request/response turns is enough on `nd100x`.
+
+The 4-word transmit DMA descriptor this builds on — `LKEY` = `FSERM`
+(`002003₈`, "block to be transmitted"), `LBYTC` = byte count, then the data
+address — is disassembled in the
+[XSSDATA transmit deep-dive](../deep-dives/Deep-Dive-XSSDATA.md).
+
+> **`MON 117` notes for on-demand reads.** Reads start at a block boundary;
+> block size defaults to 512 bytes; `BlockNo = -1` reads the next block. The
+> byte count is in **bytes** (octal `166` = 118, `1000` = 512) and is read
+> low-word-first. `MON 76 SetBlockSize` (param-list form) returned error
+> `133₈` for every size we tried, so to read sub-512-byte chunks we read the
+> 512-byte block and sub-chunk it in memory rather than shrinking the block.
 
 ---
 

From 7cdea00513a6fb214b8265fb7a5809003d69f896 Mon Sep 17 00:00:00 2001
From: retrogcom <retrogcom@users.noreply.github.com>
Date: Thu, 28 May 2026 12:45:13 +0200
Subject: [PATCH 3/3] Correct MON 76 ABI and request pacing in the HDLC docs

Resolved two open items from the on-demand server work:
- MON 76 SetBlockSize is register-based on ND-100 (T=file number, A=block size
  in WORDS, skip-on-success) -- not a parameter list. The earlier param-list
  form returned error 133. With it fixed, MON 117 reads one chunk per call so
  the server needs only a single ~60-word chunk buffer (no page cache).
- The request pacing floor is ~2 ms, not ~120 ms; ~10 ms is a safe margin
  (~0.1 s/page). Keeping 2+ RX DCBs armed (double-buffering, as XMSG does)
  removes pacing entirely -- a fast follow-up frame is dropped only because no
  empty RX DCB is loaded during the drain/re-arm window.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .../Case-Studies/HTTP-Server-over-HDLC.md     | 31 ++++++++++++-------
 .../Buffer-Pool-and-Emulator-Usage.md         | 28 +++++++++++------
 2 files changed, 38 insertions(+), 21 deletions(-)

diff --git a/Developer/Case-Studies/HTTP-Server-over-HDLC.md b/Developer/Case-Studies/HTTP-Server-over-HDLC.md
index fddff377..512d46e0 100644
--- a/Developer/Case-Studies/HTTP-Server-over-HDLC.md
+++ b/Developer/Case-Studies/HTTP-Server-over-HDLC.md
@@ -92,12 +92,15 @@ the full page, byte-exact), is:
    the buffer for receive. The DMA writes completion status back into the DCB;
    without the drain the transmitter dies after ~3 frames (a TX/RX write-back
    clash on a shared DCB — keep TX and RX DCB memory separate where you can).
-3. **Pace the requests.** A request frame sent *immediately* after a response
-   is dropped (the ND is mid drain-and-re-arm, RX not yet armed). The host
-   waits ~120 ms between chunk-requests.
-4. **Read on demand.** Open the file once (`MON 50`), and per request
-   `MON 117`-read one disk block into a single block buffer — no full-file
-   cache. The host sizes each request to the response chunk and reassembles.
+3. **Pace the requests (or double-buffer RX).** A request frame sent
+   *immediately* after a response is dropped (the ND is mid drain-and-re-arm,
+   RX not yet armed). The pacing floor is only ~2 ms; ~10 ms is a safe margin.
+   To drop pacing entirely, keep two or more RX DCBs armed so a fresh buffer
+   always catches the next frame.
+4. **Read on demand.** Open the file once (`MON 50`), set the block size to one
+   chunk (`MON 76`, register form: `T`=file, `A`=size in words), and per
+   request `MON 117`-read the next chunk into a single ~60-word buffer — no
+   full-file cache. The host sizes each request to the chunk and reassembles.
 
 The full recipe, the transmit DCB format it relies on, and the gotchas are in
 [HDLC Buffer-Pool and Emulator Usage](../../SINTRAN/Devices/HDLC/implementation/Buffer-Pool-and-Emulator-Usage.md#restarting-transmit-after-the-tx-list-drains-incl-after-a-receive).
@@ -105,12 +108,12 @@ The full recipe, the transmit DCB format it relies on, and the gotchas are in
 | Model | Status | RAM footprint | Notes |
 |-------|--------|---------------|-------|
 | Broadcast (cache all, stream) | ✅ verified | all files resident | simplest; transmitter never stops, wire always busy |
-| Request/response (read on demand) | ✅ verified | **one disk block (~512 B) at a time** | scales past RAM; ND program ~4× smaller (no cache); needs the TX-drain + request pacing above |
+| Request/response (read on demand) | ✅ verified | **one ~118 B chunk at a time** | scales past RAM; ND program ~6× smaller (no cache); needs the TX-drain + light request pacing above |
 
 On a 2 MB ND-110 the request/response model matters for *scale* — you can't
-cache an unbounded site. The on-demand server holds only one 512-byte disk
-block regardless of total site size, and its ND-side program is roughly a
-quarter the size of the cache-everything build.
+cache an unbounded site. The on-demand server holds only one disk chunk
+regardless of total site size, and its ND-side program is roughly a
+sixth the size of the cache-everything build.
 
 ## Lessons worth carrying forward
 
@@ -133,8 +136,12 @@ quarter the size of the cache-everything build.
 - **Drain each send with an `FRCV` on the output LDN** — lets the DMA finish
   writing status back into the DCB before you reuse it; without it the
   transmitter stalls after a few frames.
-- **Pace request/response** — the ND needs a beat (~120 ms) between requests to
-  drain TX and re-arm RX; a too-fast follow-up request frame is dropped.
+- **Pace request/response lightly, or double-buffer RX** — the ND needs a beat
+  (~2 ms floor, ~10 ms safe) between requests to drain TX and re-arm RX; a
+  too-fast follow-up is dropped. Keeping 2+ RX DCBs armed removes the need.
+- **`MON 76 SetBlockSize` is register-based** (`T`=file, `A`=size in *words*),
+  not a parameter list — passing a list address returns error `133₈`. Set the
+  block size to one chunk and each `MON 117` reads exactly one chunk.
 
 ---
 
diff --git a/SINTRAN/Devices/HDLC/implementation/Buffer-Pool-and-Emulator-Usage.md b/SINTRAN/Devices/HDLC/implementation/Buffer-Pool-and-Emulator-Usage.md
index 8fc7d08d..0dd52c8e 100644
--- a/SINTRAN/Devices/HDLC/implementation/Buffer-Pool-and-Emulator-Usage.md
+++ b/SINTRAN/Devices/HDLC/implementation/Buffer-Pool-and-Emulator-Usage.md
@@ -214,21 +214,31 @@ each receive:
    memory*; reusing one DCB for both directions without draining makes the
    transmitter die after ~3 frames. **Keep TX and RX DCBs in separate memory
    where you can** (the DMA engine writes back to both).
-4. **Pace the requests.** A request frame that arrives while the ND is mid
-   drain-and-re-arm (RX not yet armed) is dropped. ~120 ms between
-   request/response turns is enough on `nd100x`.
+4. **Pace the requests** (or double-buffer RX). A request frame that arrives
+   while the ND is mid drain-and-re-arm — RX not yet armed — is dropped: it is
+   buffered in the emulator's TCP ring but discarded at the DMA receiver
+   because no empty RX DCB is loaded (`rxDCB == NULL`). The pacing floor is
+   only **~2 ms** (0 ms drops the follow-up); ~10 ms is a safe margin and
+   fetches the page in ~0.1 s. To remove pacing entirely, **keep two or more
+   empty RX DCBs armed** so a fresh buffer always catches the next frame while
+   the previous one is being processed — the DMA DCB list supports this and
+   SINTRAN's `XMSG-HDLC-TEST` arms four.
 
 The 4-word transmit DMA descriptor this builds on — `LKEY` = `FSERM`
 (`002003₈`, "block to be transmitted"), `LBYTC` = byte count, then the data
 address — is disassembled in the
 [XSSDATA transmit deep-dive](../deep-dives/Deep-Dive-XSSDATA.md).
 
-> **`MON 117` notes for on-demand reads.** Reads start at a block boundary;
-> block size defaults to 512 bytes; `BlockNo = -1` reads the next block. The
-> byte count is in **bytes** (octal `166` = 118, `1000` = 512) and is read
-> low-word-first. `MON 76 SetBlockSize` (param-list form) returned error
-> `133₈` for every size we tried, so to read sub-512-byte chunks we read the
-> 512-byte block and sub-chunk it in memory rather than shrinking the block.
+> **`MON 117` / `MON 76` notes for on-demand reads.** `MON 117` reads start at
+> a block boundary; the block size defaults to 512 bytes; `BlockNo = -1` reads
+> the next block; the byte count is in **bytes**, low-word-first (octal `166` =
+> 118, `1000` = 512). To read sub-512-byte chunks, set the block size with
+> **`MON 76 SetBlockSize`** — its ND-100 MAC form is **register-based, not a
+> parameter list**: `LDT` file number, `LDA` block size **in words**, `MON 76`,
+> skip-on-success (a `JMP` after it is the error path). Passing a parameter-list
+> address instead returns error `133₈`. With the block size set to one chunk
+> (e.g. 59 words = 118 bytes) each `MON 117` reads exactly one contiguous chunk,
+> so the server needs only a single ~60-word chunk buffer — no page cache.
 
 ---