Add od-scan-duplex runbook: duplex ADF one-side capture over TWAIN

Diagnostic tree for single-pass duplex ADF scanners feeding Open Dental
over TWAIN, keyed on the Show TWAIN UI toggle (OD Duplex checkbox vs.
scanner TWAIN dialog authoritative). Placeholders only; no client data.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

README.md

@@ -67,6 +67,7 @@ run time — never commit filled-in values.
 |---|---|
 | [`od-smb-cred.md`](od-smb-cred.md) | Open Dental SMB share — stored-credential fix |
 | [`od-cfg-persist.md`](od-cfg-persist.md) | Open Dental — persist "Do not show this window on startup" (writable FreeDentalConfig.xml) |
+| [`od-scan-duplex.md`](od-scan-duplex.md) | Open Dental — duplex ADF scanner captures only one side (TWAIN, Show TWAIN UI branches) |
 | [`scripts/cg-disable.ps1`](scripts/cg-disable.ps1) | Disable Credential Guard, then reboot (prompts to confirm) |
 | [`scripts/od-cfg-acl.ps1`](scripts/od-cfg-acl.ps1) | Grant Users Modify on FreeDentalConfig.xml (Option B of od-cfg-persist) |
 

od-scan-duplex.md

@@ -0,0 +1,116 @@
+# Runbook: Open Dental — Duplex ADF scanner captures only one side
+
+**Applies to:** Any single-pass duplex ADF scanner feeding Open Dental over **TWAIN** on a Windows 11 workstation (standalone / self-enrolled is common). Written against a Canon imageFORMULA DR-series with the combined ISIS/TWAIN/WIA driver package, but the diagnostic tree is model-agnostic.
+**Symptom:** A double-sided document run through the ADF into the Open Dental **Imaging** module lands as front-only — the back side is missing, blank, or pages come out in the wrong order.
+**Most likely cause:** Duplex is not enabled on whichever setting is *authoritative*, and which one is authoritative depends on the **Show TWAIN UI** toggle. The classic miss is a checked-but-inert control on the branch that isn't in charge.
+
+**Placeholders:**
+
+| Placeholder | Meaning |
+|---|---|
+| `<WORKSTATION>` | The Windows 11 workstation with the scanner attached |
+| `<SCANNER_MODEL>` | The duplex ADF scanner model (e.g. a Canon DR-series) |
+| `<TWAIN_SOURCE>` | The native TWAIN data source name as it appears in Open Dental's **Twain Name** dropdown |
+| `<TEST_PATIENT>` | A dummy patient/chart used for test scans only — never a live chart |
+| `<OD_USER>` | The Open Dental user the front desk actually scans as |
+
+---
+
+## Key concept — where duplex is governed
+
+> [!IMPORTANT]
+> In Open Dental, duplex is controlled in **one of two places**, and only one is live at a time. The **Show TWAIN UI** toggle (Setup → Imaging → **Edit Imaging Device**) decides which:
+>
+> - **Show TWAIN UI = OFF** → **Open Dental's own Duplex checkbox** (Imaging Quality → **Multipage Scans**) is authoritative. The scanner's own dialog never appears.
+> - **Show TWAIN UI = ON** → the **scanner's TWAIN dialog at scan time** is authoritative. Open Dental's Duplex checkbox is **inert** — it is not read.
+>
+> **The trap:** an OD Duplex checkbox that is checked *while Show TWAIN UI is ON* (or a scanner dialog set to duplex *while Show TWAIN UI is OFF*) changes nothing. A control set correctly on the **wrong branch** is the single most common misdiagnosis here. Always establish the toggle state **first**, then set duplex on the branch that matches it.
+
+---
+
+## Diagnostic steps
+
+Work these in order. Steps a–c establish ground truth before you change anything.
+
+### a. Confirm the Twain Name binds to the NATIVE source, not a WIA bridge
+
+In **Edit Imaging Device**, check the **Twain Name** value.
+
+- It should be the vendor's **native TWAIN** source (e.g. the `<SCANNER_MODEL>` TWAIN entry).
+- If it reads **`WIA-<SCANNER_MODEL>`** or any `WIA-…` entry, that is the Windows WIA→TWAIN bridge. **The WIA bridge frequently drops the second side** and cannot be relied on for duplex. Re-select the native TWAIN source.
+
+If the native source isn't in the list, the 32-bit TWAIN driver isn't registered — see [Gotchas](#gotchas).
+
+### b. Record the Show TWAIN UI state
+
+Note whether **Show TWAIN UI** is **ON** or **OFF**. This determines which fix branch applies below. Write it down — you'll restore or deliberately set it.
+
+### c. Screenshot the current settings (baseline / rollback)
+
+Capture the current **Edit Imaging Device** and **Imaging Quality → Multipage Scans** settings before touching anything, so you have a known-good rollback point and a record of what changed.
+
+> [!WARNING]
+> Screenshots for your own rollback are fine, but they may contain client-identifying detail (hostname, user, chart data). Keep them in the **private tier** — never attach them to this public repo.
+
+### d. Confirm the scan action is multi-page (ADF), not single-page
+
+The front-desk action must be **Scan Multi-Page Document** (ADF → multi-page PDF). The plain **Scan Document** action pulls a single page and **can never be duplex** regardless of every other setting. If the button in use is single-page, that alone explains front-only output.
+
+### e. Reproduce with a real double-sided document
+
+Feed a genuine two-sided document through the ADF and record the **exact** failure mode — they point at different causes:
+
+| Observed | Points toward |
+|---|---|
+| Front pages only, backs never appear | Duplex off on the authoritative branch (step f) |
+| Backs captured then dropped if blank/light | **Skip Blank Page** is on (see Gotchas) |
+| Both sides present but interleaved/out of order | Scan-order / driver page-order setting |
+
+### f. Apply the fix for the matching branch
+
+Use the [decision table](#fix-decision-table) below, keyed to the Show TWAIN UI state from step b.
+
+### g. If still failing, isolate with Twacker over TWAIN
+
+Twacker is the reference TWAIN test application. Scan the same document through Twacker against the **same `<TWAIN_SOURCE>`**:
+
+- **Works in Twacker, fails in Open Dental** → the driver and hardware are fine; the problem is Open Dental configuration or how it drives the source. Return to steps a–f.
+- **Fails in Twacker too** → the problem is below Open Dental: driver settings or hardware. Fix it in the scanner's TWAIN dialog / driver, then retest.
+
+### h. Verify end-to-end and set as default
+
+1. Trigger the scan from the **actual front-desk button** as `<OD_USER>` — not a settings-screen test.
+2. **Open the resulting PDF** and confirm **both sides are present and in reading order**.
+3. Set the working configuration as the **default** so it survives an app restart or profile reset. A fix that only holds for the current session isn't done.
+
+---
+
+## Fix decision table
+
+| Show TWAIN UI | Authoritative setting | Action |
+|---|---|---|
+| **OFF** | Open Dental **Duplex** checkbox (Imaging Quality → Multipage Scans) | **Check it.** |
+| **ON** | Scanner's **TWAIN dialog** at scan time | Set **Scanning Side = Duplex**; set **Skip Blank Page = OFF**. |
+
+> **Resolved example (OFF branch):** In the case that prompted this runbook, **Show TWAIN UI was OFF** and Open Dental's **Duplex** checkbox was **unchecked**. Checking it resolved the issue immediately — no driver or hardware change needed. This is the common OFF-branch outcome; still walk the tree above rather than assuming, since the ON branch fails differently.
+
+---
+
+## Gotchas
+
+- **"Skip Blank Page" masquerades as simplex.** With this enabled in the TWAIN driver, a blank or light back side is **silently deleted on save** — the output looks exactly like a simplex scan even though both sides were captured. Turn it **OFF** while diagnosing duplex.
+- **Open Dental is 32-bit and binds a 32-bit TWAIN source.** Open Dental only supports **32-bit TWAIN** drivers. The ISIS/TWAIN/WIA package installs a 32-bit source, and Open Dental (a 32-bit app) binds to it. A 64-bit-only driver, or picking the wrong source, means no working duplex — confirm the **native 32-bit TWAIN** source is what's selected in step a.
+- **Windows Fax and Scan is NOT a valid isolation test.** It drives the scanner over **WIA, not TWAIN**. It can succeed while the TWAIN path fails (or vice versa) and tells you nothing about an Open Dental/TWAIN problem. Use **Twacker over TWAIN** (step g) for isolation.
+- **Mechanical checks.** Before chasing software: the feed/separation **lever is in the separation (multi-sheet) position**, **double-feed detection** isn't misfiring and halting the second side, and the back side of the test document **genuinely has content**.
+
+---
+
+## Compliance note
+
+> [!WARNING]
+> Run all test scans into a **`<TEST_PATIENT>`** dummy account — **never a live chart**. When finished, **purge the test images** from `<TEST_PATIENT>` so no stray PHI or test scans are left behind. Confirm the dummy account holds nothing before leaving the workstation.
+
+## References
+
+- Open Dental manual — Imaging module / device setup: <https://www.opendental.com/manual/imaging.html>
+- Open Dental manual — Edit Imaging Device (Twain Name, Show TWAIN UI): <https://www.opendental.com/manual/imagingdevices.html>